DSH Taskboard: SQLite Task State as the Authority for DeepSeek Harness Agents

The gap DSH Taskboard fills in a Harness session

A DeepSeek Harness session is good at holding a conversation and running tools. It is a poor place to keep a task list. Sessions end, contexts get compacted, and a plan that lived only in the transcript is gone or expensive to reconstruct. DSH Taskboard puts the task record in SQLite and leaves execution and conversation where they already are. The README states this split directly: SQLite is the sole task authority, while Harness Agent Sessions, Goals, Workspaces, tools, permissions, and the Web Client remain the execution and conversation owners.

The intended user is narrow. You need a working DeepSeek Harness installation on the web profile, Node.js 22.19 or newer, pnpm 11, and write access to $DSH_HOME (default ~/.dsh). If you are evaluating a task tracker for a team of humans who never touch an agent, this is the wrong shape: the whole design assumes an agent is doing work and a person is checking it. The README also points at a packaged Skill called manage-taskboard and a set of in-process Agent tools named taskboard_*, which tells you the primary consumer is an agent, not a person clicking around a board.

What you get after install is a Taskboard sidebar button and a native overlay page. The README is explicit that this is not an iframe and not a second chat runtime, which matters if you have tried plugins that embed a separate web app inside the Harness shell. Tasks carry stable readable keys such as DSH-42 alongside opaque ids and optimistic versions, so a human can refer to a task in conversation without pasting a UUID.

Seven statuses and the human-only accept boundary

The status model is the most opinionated part of the project. There are seven: backlog, todo, in_progress, in_review, done, plus blocked and canceled. The forward path runs backlog to todo to in_progress to in_review to done. The README gives one hard rule about it: agents can submit verified work to in_review, but only an authenticated human UI or CLI operation can accept it as done.

That is a deliberate constraint, and it is worth reading as a design statement rather than a feature. An agent cannot close its own work. The tool surface reflects the same choice: the README describes the taskboard_* tools as having no accept and no generic status mutation. So an agent cannot call a tool that sets status to done, and it cannot reach for a catch-all status setter to route around the missing accept. The transition has to come from a person through the UI or the CLI.

This will annoy anyone who wants fully autonomous task closure. It also means the queue only drains as fast as a human reviews it, which is a real throughput ceiling in a busy setup. Whether that trade is worth it depends on whether you have been burned by an agent marking its own work complete. If you have, the boundary is the reason to use this project rather than a generic board with an API key.

The status set also carries blocked and canceled as first-class states rather than as tags or labels. That is a small thing, but it means an agent reporting a blocker has somewhere to put it that is not a comment thread.

Install is a build-then-pack procedure, not a git add

The README opens with a warning that is easy to skim past: do not add the Git repository as a raw plugin source, because lib/ is gitignored, so a git install has no compiled Host/Client bundle. This is the single most likely way to waste an afternoon. The install is four steps, and step two is mandatory.

First, detect the running Harness. The README suggests lsof -iTCP:"$PORT" -sTCP:LISTEN with PORT defaulting to 3080, then lsof -p <PID> -a -d cwd to find the working directory. If nothing listens on 3080, you are told to search other ports or ask the operator for the URL. You then decide how to invoke the CLI: from a source checkout with pnpm-workspace.yaml, run pnpm dsh ...; otherwise, if command -v dsh succeeds, use dsh ... directly.

Second, build and pack. Clone the repository, run pnpm install, pnpm build, pnpm pack. The expected artifacts are lib/index.js, lib/cli.js, lib/client.js with sibling declarations, plus a tarball named shengsheng-dsh-taskboard-<version>.tgz in the repo root. Read <version> from package.json rather than copying a number from the README.

Third, add the plugin to the profile. The profile directory is a pnpm workspace root, and the README says the -w flag is mandatory, because without it pnpm fails with ERR_PNPM_ADDING_TO_ROOT:

dsh plugin --profile web add -w /absolute/path/to/shengsheng-dsh-taskboard-<version>.tgz

The README warns that a source-directory add can miss lib/ if the tree was not built, so prefer the packed tarball. The command may rewrite the profile package.json, lockfile, and node_modules, which the README calls expected.

Fourth, verify without starting the server. Run dsh --profile web --dump-config and check that the dump ends with a # == @shengsheng/dsh-taskboard layer containing the taskboard plugin config keys (databasePath, attachmentRoot, worker limits, and others). Note the README's caveat that --dump-config idempotently rewrites the profile-root cordis.yml, and that an EPERM while writing ~/.dsh is expected in a sandbox and means you need to ask for full filesystem permission. There is also a module-resolution smoke test using node --input-type=module with a dynamic import, which should print OK taskboard function.

Three install checks that catch most failures

The README defines success as three conditions being true at once, and it is worth treating them as a checklist rather than prose. One: $DSH_HOME/profiles/web/package.json dependencies contains @shengsheng/dsh-taskboard. Two: the same file's dsh.profile.bundles lists @shengsheng/dsh-taskboard after @deepseek-ai/dsh-base. Three: $DSH_HOME/profiles/web/node_modules/@shengsheng/dsh-taskboard/ exists and contains lib/ plus cordis.patch.yml.

The ordering in condition two is the part people miss. The bundle has to come after the base package, and if it does not, you will not get the layer in the config dump. The README also names a specific failure message: if the CLI warns declares no dsh.bundle, the package is missing a dsh.bundle.patch entry pointing at ./cordis.patch.yml in package.json. The repository already declares that, so the README's instruction is to rebuild and reinstall rather than editing the installed copy by hand. Hand-editing node_modules is the kind of fix that survives exactly until the next install.

The smoke test failure mode is also documented. If the dynamic import fails, it is usually a missing peer such as @deepseek-ai/* or react, and the README says those resolve through install-fallback links under the profile directory. That tells you the plugin depends on the host's own dependency tree rather than vendoring everything, which is normal for a host plugin but means a broken profile install breaks the plugin too.

Where the documented surface runs out

The README is unusually careful about what it does not promise, and the honest gaps are worth listing. The compatible host is pinned to DeepSeek Harness 0.1.2-alpha.2. That is an alpha pin, and the README does not describe a compatibility policy for later Harness releases. If your Harness is on a different alpha, nothing in the supplied material tells you whether the plugin loads, whether the cordis.patch.yml layer still applies, or whether the taskboard_* tools keep their shape. Treat the pin as the boundary of what is documented.

The configuration section is referenced but not reproduced in the material available here. The README names databasePath, attachmentRoot, and worker limits as keys that appear in the config dump, but the defaults, types, and valid ranges are not given. If you need to relocate the SQLite file or the attachment directory, you are reading docs/architecture.md and the CLI reference before you touch anything.

The README also points to docs/security.md and docs/acceptance-audit.md for security, recovery, and acceptance details. Those documents are not reproduced here, so claims about backup, migration, or recovery behaviour cannot be confirmed from this material. The same goes for the headless JSON CLI: the README says dsh-taskboard exists and that the CLI reference documents it, but the command syntax is not in the supplied text.

One more limit worth stating plainly. The README says network access is needed only to clone the repository and install Node dependencies. That means the running taskboard is local, and there is no described sync, remote, or multi-machine story. If two engineers on two laptops need to share a board, this design does not address it.

How this differs from a hosted tracker with an agent API

The obvious alternative is a hosted issue tracker such as a self-managed Jira or a GitHub Issues board, driven by an agent that authenticates with an API token and moves cards through a REST API. The difference is not the feature list. It is who holds the write authority and where the state lives.

In the hosted model, the board is a remote service. The agent is one more API client with the same mutation powers as any other client, which typically includes the ability to set a task to done. Review is a policy you enforce with permissions and process, not something the API prevents. State lives on someone else's machine, and every read and write is a network call with its own auth, rate limits, and failure modes.

In DSH Taskboard, the board is a SQLite database on the same machine as the Harness process, and the agent's tool surface is deliberately reduced. The README's phrasing is the key difference: the taskboard_* tools have no accept and no generic status mutation. The in_review to done transition is not available to the agent at all. You get that guarantee without configuring a permission scheme, because the tool was never exposed. You also give up everything a hosted tracker gives you: remote access, cross-machine sync, webhooks into other systems, and a multi-user permission model. The README describes an authenticated human UI or CLI operation as the accept path, which is a local trust boundary, not an organisational one.

The trade is coherent. If your agents run on the same box as your Harness and your review step is one person, the local SQLite model removes a whole category of integration work. If your review step is a team, or your agents run somewhere else, the hosted tracker is the better fit and the accept boundary has to be rebuilt in policy.

Licence, upgrade cost, and what a version bump touches

The project is Apache-2.0, and the README points to THIRD_PARTY_NOTICES.md for the attribution shipped to package consumers. Apache-2.0 is a permissive licence with an explicit patent grant and a notice-retention requirement, which matters if you redistribute the packed tarball inside an organisation. It also means you can modify the plugin, though the practical cost of doing so is higher than it looks: the install procedure builds from source with pnpm build and packs a tarball, so a fork has to be rebuilt and repacked for every change. This is not legal advice; read the licence text and your own obligations.

The upgrade path has a specific shape that the README implies without spelling out. The plugin is installed into a profile as a packed tarball, and the profile's package.json, lockfile, and node_modules are rewritten by the add command. Upgrading therefore means building a new tarball from the target version and running the add command again with the new absolute path. There is no described in-place upgrade command, and no described migration for the SQLite schema between versions. The release history in the material shows v0.1.2, v0.1.3, and v0.1.4 between 2026-08-19 and 2026-08-31, three releases in under two weeks. That cadence is worth weighing: at this stage the plugin is moving quickly, and the supplied material does not document a compatibility guarantee across those versions.

The maintenance burden that follows is concrete. Every Harness upgrade is a potential break, because the compatible host is pinned to one alpha and the plugin composes into the profile through cordis.patch.yml. Every plugin upgrade is a rebuild and a re-add. Before you commit, back up the SQLite database file at whatever path databasePath resolves to, since the supplied material does not describe a recovery procedure.

Editorial conclusion

Adopt DSH Taskboard if you already run a DeepSeek Harness web profile at version 0.1.2-alpha.2, need task state that outlives a chat session, and accept that only a human UI or CLI operation can move a task from in_review to done. Do not adopt it if you are on Harness alpha builds outside that pin, if you have no write access to $DSH_HOME, or if you wanted a hosted multi-user tracker. Verify first that node -v reports v22.19+ or v24+, that pnpm -v reports 11.x, and that dsh --profile web --dump-config ends with a # == @shengsheng/dsh-taskboard layer before you restart the Harness process.

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. shengsheng90/DSH-taskboard on GitHub