DSH-taskboard
Native local Taskboard plugin for DeepSeek Harness. SQLite-backed projects, Agent claim/review, and a native Web UI — no iframe, no second chat runtime.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/shengsheng90--dsh-taskboard)HTML
<a href="/listings/shengsheng90--dsh-taskboard"><img src="/api/listings/shengsheng90--dsh-taskboard/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Use these constants. Read live values from disk; do not invent a different package name.
| Name | Value | |---|---| | Package name | `@shengsheng/dsh-taskboard` | | Default profile | `web` | | Default Web port | `3080` (detect; do not assume) | | Profile directory | `$DSH_HOME/profiles/<profile>` , usually `~/.dsh/profiles/web` | | Packed tarball name | `shengsheng-dsh-taskboard-<version>.tgz` |
`<version>` is whatever this repo's `package.json` currently declares — read it there rather than copying a number out of this document. After `pnpm pack`, use the tarball that was actually written.
A longer copy-paste prompt for a Harness-side agent is in [docs/install-plugin-prompt.zh.md](docs/install-plugin-prompt.zh.md). The steps below are the normative English procedure.
1. Detect the running Harness
Find the Web listener and its working directory:
PORT=3080 lsof -iTCP:"$PORT" -sTCP:LISTEN # then, with the listener PID: lsof -p <PID> -a -d cwd
If nothing is listening on `3080`, search other common ports or ask the operator for the URL they use (`http://127.0.0.1:<port>`).
Decide how to invoke the `dsh` CLI:
- If the Harness cwd is a source checkout (repo root has `pnpm-workspace.yaml` and `package.json` contains a `"dsh"` script), run every later command from that checkout root as `pnpm dsh ...`. - Else if `command -v dsh` succeeds, use `dsh ...` directly.
In the commands below, `dsh` means whichever of those two forms you just chose. First use of a profile may initialize it and install `@deepseek-ai/dsh-base`.
2. Choose a prebuilt installation source
Use npm, Git (which includes `lib/`), or a GitHub release `.tgz`:
dsh plugin --profile web add -w @shengsheng/dsh-taskboard # Alternatively: dsh plugin --profile web add -w git+https://github.com/shengsheng90/DSH-taskboard.git
For the local tarball path in step 3, download a release `.tgz` and record its absolute path. Developers changing source run `pnpm install --frozen-lockfile && pnpm build && pnpm pack:release`. Consumer installation does not run a build. Release checks and CI validate completeness, source freshness, and compatibility. See [distribution and compatibility strategy](docs/plugin-compatibility.zh.md) for the verification boundaries.
3. Add the plugin to the profile
The profile directory is a pnpm workspace root (`packages: [.]`). The `-w` / workspace-root flag is **mandatory**. Without it, pnpm fails with `ERR_PNPM_ADDING_TO_ROOT`.
dsh plugin --profile web add -w /absolute/path/to/shengsheng-dsh-taskboard-<version>.tgz
If you already installed through npm or Git in step 2, skip this step and continue to composition verification. Rebuild and run `pnpm verify:package` before installing a source checkout with local changes.
This command may rewrite the profile `package.json`, lockfile, and `node_modules`. That is expected.
Install succeeded only when **all** of the following are true:
1. `$DSH_HOME/profiles/web/package.json` `dependencies` contains `@shengsheng/dsh-taskboard`. 2. The same file's `dsh.profile.bundles` lists `@shengsheng/dsh-taskboard` **after** `@deepseek-ai/dsh-base`. 3. `$DSH_HOME/profiles/web/node_modules/@shengsheng/dsh-taskboard/` exists and contains `lib/` plus `cordis.patch.yml`.
If the CLI warns `declares no dsh.bundle`, the package is missing `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` in `package.json`. This repository already declares that; rebuild and reinstall rather than editing the installed copy by hand.
4. Verify composition (does not start the server)
dsh --profile web --dump-config
Pass when the dump ends with a `# == @shengsheng/dsh-taskboard` layer and the `taskboard` plugin config (`databasePath`, `attachmentRoot`, worker limits, and the other keys listed in [Configuration](#configuration)).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 418 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # DSH Taskboard
- English | [简体中文](README.zh.md)
- Native, local project task management for DeepSeek Harness. SQLite is the sole task authority. Harness Agent Sessions, Goals, Workspaces, tools, permissions, and the Web Client remain the execution and conversation owners.
- This README is written so a human **or another coding agent** can install the plugin into a live Harness profile, verify it, and start using it without guessing.
- **Package:** `@shengsheng/dsh-taskboard`
- **Repository:** https://github.com/shengsheng90/DSH-taskboard
- **License:** Apache-2.0
- **Host version policy:** DSH runtime peers use `*` (no version gate). Installation/loading is tested against `0.1.6-alpha.1`, `0.1.7-rc.1/rc.2`, `0.2.0-rc.1/rc.2`, and `0.2.1-rc.2`. This verifies installation and module loading; GUI operations and model execution still need checking after a Host upgrade.
- 
- If you are an installing agent, jump to [Install into DeepSeek Harness](#install-into-deepseek-harness) and follow every step in order. Git, npm, and release tarballs carry prebuilt Host/Client artifacts. Installation requires neither a TypeScript build nor a Harness source checkout.
- ## What you get
- After a successful install, Harness gains:
- - A **Taskboard** sidebar button and a native overlay page (not an iframe, not a second chat runtime)
- - Local SQLite projects, tasks, comments, relations, attachments, workflows, and automation
- - Stable readable keys such as `DSH-42` plus opaque ids and optimistic versions
- - Seven statuses: `backlog` → `todo` → `in_progress` → `in_review` → `done`, plus `blocked` and `canceled`
- - In-process Agent tools `taskboard_*` (no accept / no generic status mutation)
- - Headless JSON CLI `dsh-taskboard`
- - Packaged Skill `manage-taskboard`
- Agents can submit verified work to `in_review`. Only an authenticated human UI or CLI operation can accept it as `done`.
- Further design docs: [Architecture](docs/architecture.md), [Security and recovery](docs/security.md), [CLI reference](docs/cli.md), [Acceptance audit](docs/acceptance-audit.md). Attribution shipped to package consumers is in `THIRD_PARTY_NOTICES.md`.
- ## Requirements
- | Requirement | Value |
- |---|---|
- | Node.js | `^22.19.0` or `>=24.0.0` (24 recommended; built-in `node:sqlite`) |
- | pnpm | Use `11.15.1` for repository development (`packageManager`); profile installation uses Harness's pnpm |
- | DeepSeek Harness | checkout or installation, **web** profile; no DSH version constraint |
- | Network | only needed to clone this repo and install Node dependencies |
- | Permissions | write access to `$DSH_HOME` (default `~/.dsh`) and the ability to restart the Harness process |
- Confirm the toolchain before installing:
- ```sh
- node -v # v22.19+ or v24+
- pnpm -v # 11.x
- ```
- ## Install into DeepSeek Harness
- Use these constants. Read live values from disk; do not invent a different package name.
- | Name | Value |
- |---|---|
- | Package name | `@shengsheng/dsh-taskboard` |
- | Default profile | `web` |
- | Default Web port | `3080` (detect; do not assume) |
- | Profile directory | `$DSH_HOME/profiles/<profile>` , usually `~/.dsh/profiles/web` |
- | Packed tarball name | `shengsheng-dsh-taskboard-<version>.tgz` |
- `<version>` is whatever this repo's `package.json` currently declares — read it there rather than copying a number out of this document. After `pnpm pack`, use the tarball that was actually written.
- A longer copy-paste prompt for a Harness-side agent is in [docs/install-plugin-prompt.zh.md](docs/install-plugin-prompt.zh.md). The steps below are the normative English procedure.
- ### 1. Detect the running Harness
- Find the Web listener and its working directory:
- ```sh
- PORT=3080
- lsof -iTCP:"$PORT" -sTCP:LISTEN
- # then, with the listener PID:
- lsof -p <PID> -a -d cwd
- ```
- If nothing is listening on `3080`, search other common ports or ask the operator for the URL they use (`http://127.0.0.1:<port>`).
- Set `PORT` to the actual listener port and keep using that value below. Use the running Host's `DSH_HOME` and profile; the examples use profile `web`.
- Decide how to invoke the `dsh` CLI:
- - If the Harness cwd is a source checkout (repo root has `pnpm-workspace.yaml` and `package.json` contains a `"dsh"` script), run every later command from that checkout root as `pnpm dsh ...`.
- - Else if `command -v dsh` succeeds, use `dsh ...` directly.
- In the commands below, `dsh` means whichever of those two forms you just chose. First use of a profile may initialize it and install `@deepseek-ai/dsh-base`.
- ### 2. Choose a prebuilt installation source
- Use npm, Git (which includes `lib/`), or a GitHub release `.tgz`:
- ```sh
- dsh plugin --profile web add -w @shengsheng/dsh-taskboard
- # Alternatively:
- dsh plugin --profile web add -w git+https://github.com/shengsheng90/DSH-taskboard.git
- ```
- For the local tarball path in step 3, download a release `.tgz` and record its absolute path. Developers changing source run `pnpm install --frozen-lockfile && pnpm build && pnpm pack:release`. Consumer installation does not run a build. Release checks and CI validate completeness, source freshness, and compatibility. See [distribution and compatibility strategy](docs/plugin-compatibility.zh.md) for the verification boundaries.
- ### 3. Add the plugin to the profile
- The profile directory is a pnpm workspace root (`packages: [.]`). The `-w` / workspace-root flag is **mandatory**. Without it, pnpm fails with `ERR_PNPM_ADDING_TO_ROOT`.
- ```sh
- dsh plugin --profile web add -w /absolute/path/to/shengsheng-dsh-taskboard-<version>.tgz
- ```
- If you already installed through npm or Git in step 2, skip this step and continue to composition verification. Rebuild and run `pnpm verify:package` before installing a source checkout with local changes.
- This command may rewrite the profile `package.json`, lockfile, and `node_modules`. That is expected.
- Install succeeded only when **all** of the following are true:
- 1. `$DSH_HOME/profiles/web/package.json` `dependencies` contains `@shengsheng/dsh-taskboard`.
- 2. The same file's `dsh.profile.bundles` lists `@shengsheng/dsh-taskboard` **after** `@deepseek-ai/dsh-base`.
- 3. `$DSH_HOME/profiles/web/node_modules/@shengsheng/dsh-taskboard/` exists and contains `lib/` plus `cordis.patch.yml`.
- If the CLI warns `declares no dsh.bundle`, the package is missing `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` in `package.json`. This repository already declares that; rebuild and reinstall rather than editing the installed copy by hand.
- ### 4. Verify composition (does not start the server)
- ```sh
- dsh --profile web --dump-config
- ```
- Pass when the dump ends with a `# == @shengsheng/dsh-taskboard` layer and the `taskboard` plugin config (`databasePath`, `attachmentRoot`, worker limits, and the other keys listed in [Configuration](#configuration)).
- `--dump-config` idempotently rewrites the profile-root `cordis.yml`. If a sandbox returns `EPERM` while writing `~/.dsh`, ask the operator for full filesystem permission and retry. That rewrite is expected, not a failure.
- ### 5. Smoke-test module resolution
- ```sh
- (cd "${DSH_HOME:-$HOME/.dsh}/profiles/web" && node --input-type=module -e \
- "import('@shengsheng/dsh-taskboard').then(m=>console.log('OK', m.name, typeof m.apply)).catch(e=>{console.error(e.message);process.exit(1)})")
- ```
- Pass: `OK taskboard function`.
- Fail is usually a missing peer (`@deepseek-ai/*` or `react`). Those resolve through the install-fallback links under `$DSH_HOME/profiles/node_modules` (usually `~/.dsh/profiles/node_modules`), which Harness heals on boot. Re-run step 4, then retry this import.
- ### 6. See whether the running process already loaded the plugin
- Plugin composition and client-module scanning happen **only at boot**. Installing into the profile does not hot-load the UI.
- **After upgrading or reinstalling the package, restart Harness in step 7 even if both checks below pass.** The manifest contains the package name, not proof that the running Host loaded the new build.
- ```sh
- curl -s "http://127.0.0.1:$PORT/" | grep -c '@shengsheng/dsh-taskboard'
- curl -s -o /dev/null -w '%{http_code}\n' "http://127.0.0.1:$PORT/plugins/@shengsheng/dsh-taskboard/client.js"
- ```
- - Manifest count `> 0` **and** bundle HTTP `200`, with no package changes since boot → client artifacts are served; skip the restart and go to [Confirm activation](#8-confirm-activation).
- - Otherwise restart Harness.
- ### 7. Restart Harness
- Restart stops the process that hosts the current session. Session data lives in `$DSH_HOME/sessions` and is not deleted; in-flight Agent turns are interrupted. Tell the operator before restarting.
- From a Harness source checkout, a typical restart is:
- ```sh
- # stop the current listener
- OLD_PID=$(lsof -tiTCP:"$PORT" -sTCP:LISTEN | head -1)
- if [ -n "$OLD_PID" ]; then kill -TERM "$OLD_PID"; fi
- # wait until the port is free, then start again from the checkout root
- cd /absolute/path/to/deepseek-harness
- nohup pnpm dsh --profile web >> /tmp/dsh-harness-restart.log 2>&1 &
- ```
- Do not treat the first successful `GET /` as “plugin ready”. The Web server can accept connections before the boot manifest injects the plugin. Poll until the package name appears:
- ```sh
- for _ in $(seq 1 30); do
- if curl -s "http://127.0.0.1:$PORT/" | grep -q '@shengsheng/dsh-taskboard'; then echo ready; break; fi
- sleep 2
- done
- curl -s -o /dev/null -w '%{http_code}\n' "http://127.0.0.1:$PORT/plugins/@shengsheng/dsh-taskboard/client.js"
- ```
- A detached restart script used in a real install is documented in [docs/install-plugin-prompt.zh.md](docs/install-plugin-prompt.zh.md) (step 6). Prefer that script when the installing agent would be killed with the old Harness process group.
- ### 8. Confirm activation
- All of these must pass:
- | Check | Expected |
- |---|---|
- | `GET /` contains `@shengsheng/dsh-taskboard` | count ≥ 1 |
- | `GET /plugins/@shengsheng/dsh-taskboard/client.js` | HTTP 200 |
- | Harness boot log | no plugin import / apply error |
- | Browser | refresh `http://127.0.0.1:<port>`; a Taskboard control appears in the sidebar footer |
- | UI write | create a test project and task; refresh and confirm both persist |
- Loading the page alone does not verify the write channel. In browser developer tools, UI actions should POST to `/taskboard/<endpoint>` and return a `server-response` with `result.ok: true`. The channel uses Harness authentication and Origin checks. A `401` / `403` requires checking the browser login and Host access configuration; `404` indicates a missing route or an incorrect proxy path. HTTP `200` with `result.ok: false` is an application error, not a successful write. Custom RPC callers must send a `client-request` envelope with a string `rpcId`, a `method` matching the endpoint, and a `payload`.
- Default data files (created on first use; the Host resolves these paths):
- ```text
- .dsh/taskboard.sqlite
- .dsh/taskboard-attachments
- ```
- Those defaults are **relative**, and a Host inherits its working directory from whatever started it, so they are never resolved against a raw process cwd. They bind to the nearest git project above the startup directory; configuration directories are not projects, so a versioned `~/.claude` or `~/.config/...` is skipped rather than written into. With no project behind the startup directory the store goes to `$DSH_HOME` (default `~/.dsh`) instead of dropping a `.dsh/` folder where nobody asked for one. An existing cwd-relative database is kept, so stores created before this rule are not abandoned, and a project-local store gets a `.dsh/.gitignore` so it stays out of `git status`. The Host logs the resolved absolute paths on startup, plus `taskboard database created at <abs path>` when it initializes a new one. Absolute values, including absolute `DSH_TASKBOARD_DATABASE` / `DSH_TASKBOARD_ATTACHMENTS`, are used as given. See [Configuration](#configuration), and [Upgrading from a cwd-relative store](#upgrading-from-a-cwd-relative-store) if you ran an earlier version.
- ### Install troubleshooting
- | Symptom | Cause | Fix |
- |---|---|---|
- | `dsh: command not found` | CLI not on `PATH` | From a Harness checkout root, use `pnpm dsh ...` |
- | `ERR_PNPM_ADDING_TO_ROOT` | profile is a pnpm workspace root | Add `-w` |
- | Old Git ref / package lacks `lib/` | Old distribution omitted artifacts | Use a new prebuilt version; maintainers run `pnpm build && pnpm pack:release` |
- | `incompatible with dsh` | Old package still declares a bounded DSH range | Upgrade to the package with DSH peers set to `*`; actual API failures still need adaptation |
- | `EPERM` writing `~/.dsh` | sandbox | Ask the operator for full permissions; the write is idempotent |
- | Manifest / `client.js` still 404 | no restart, or checked too early | Restart, then poll (step 7) |
- | Page loads, but create/edit fails | RPC route, authentication, proxy, or request error | Check `/taskboard/<endpoint>` requests and `result.ok` as in step 8; upgrade an older plugin and restart |
- | Import / apply error | missing peers or missing bundle entry | Heal fallbacks with `--dump-config`; confirm `dsh.profile.bundles` |
- | `declares no dsh.bundle` | package missing bundle patch | Rebuild this repo; do not hand-edit the installed tree |
- | GUI down after restart | Harness failed to boot | Read `/tmp/dsh-harness-restart.log` or the process log; confirm checkout path and `pnpm dsh` |
- Install only packages you trust. `pnpm` runs package lifecycle scripts, and Harness then loads the plugin.
- ## Use the Taskboard
- ### Human UI
- 1. Open the Harness Web Client and click the **Taskboard** control in the sidebar footer.
- 2. Create a project: name, short key (used for readable ids such as `DSH-1`), optional Harness Workspace id. Leave Workspace blank for a global project.
- 3. Create a task. New work starts in `backlog` unless you create it already as `todo`.
- 4. Write the description in Markdown. Attach files by paste, drop, or file picker.
- 5. **Approve for work** moves `backlog` → `todo`. Agents and automation may claim only eligible `todo` items.
- 6. Use **Board**, **List**, **Gantt**, **Workflows**, and the Dashboard as needed. The page follows the Harness locale (Chinese or English).
- 7. When an Agent submits review, open the task, read the result comment and verification, then **Accept** (`done`) or **Return for rework**.
- 8. Map a Workspace before using **Open in new session**. It is available for `todo` / `in_progress` tasks and opens a native Session with an unsent task draft. It also binds a fresh claim to that Session, moving `todo` to `in_progress`; an existing claim must be released before a new Session can be bound. Binding increments the task version, so reread the task before writing. Send the draft when ready to start the Agent.
- For both manually bound and automation Sessions, a bound Goal reaching `complete` submits the task to `in_review`; `blocked` moves it to `blocked`. Human acceptance is still required for `done`.
- Human-only actions (UI or CLI, never model tools): approve, accept, return, archive, restore, cancel, reopen, force takeover, permanent delete.
- ### Task lifecycle
- ```text
- human creates backlog
- -> human approves to todo
- -> Agent or automation claims (dependency recheck + exclusive claim + Session)
- -> Agent works in the bound Workspace / branch / worktree
- -> Agent verifies and submits in_review
- -> human accepts done, or returns to todo / in_progress
- ```
- Rules every caller must keep:
- - Every mutation except create carries the **exact current `version`**.
- - `TASK_STALE_VERSION` means reread and reconcile; do not retry the stale version.
- - Never derive an opaque task id from a display key such as `DSH-42`. Use the id the API returned.
- - Goal completion never accepts a task. Agent success ends at `in_review`.
- - Returning or resuming to `todo` releases the claim. Direct `in_progress` rework must create a fresh explicit claim.
- - Orphaned claims stay visible. They are not silently stolen.
- ### Agent tools
- Models must use the in-process tools. Do not shell out to `dsh-taskboard` from a model turn when a tool exists.
- | Tool | Purpose |
- |---|---|
- | `taskboard_list` | Bounded list for one exact `project_id` |
- | `taskboard_get` | Full detail, version, comments, relations, claim |
- | `taskboard_claim` | Claim one eligible `todo` with `expected_version` |
- | `taskboard_comment` | Append a Markdown comment |
- | `taskboard_submit_review` | Move owned `in_progress` work to `in_review` |
- | `taskboard_block` | Block the owned `in_progress` task with a concrete reason |
- | `taskboard_release_claim` | Release only the current Agent's claim |
- | `taskboard_relate` | Add `parent`, `blocks`, or `related` in the same project |
- There is no accept tool and no generic status tool. Follow the packaged Skill at [`skills/manage-taskboard/SKILL.md`](skills/manage-taskboard/SKILL.md):
- 1. `taskboard_list` → pick an eligible `todo`.
- 2. `taskboard_get` immediately before the write.
- 3. `taskboard_claim` with the exact version.
- 4. Do the work in the task's declared development context.
- 5. Verify, then `taskboard_submit_review` with evidence. Never edit the task description to record the result.
- ### JSON CLI
- The CLI emits schema-versioned JSON. Use it for human scripts and interoperability, not as the model's primary API.
- Use the absolute database and attachment paths from the Host startup log when operating its store from another directory. Relative defaults can select a different project store. Pass both `--database` and `--attachment-root`, or set `DSH_TASKBOARD_DATABASE` and `DSH_TASKBOARD_ATTACHMENTS` to those absolute paths.
- ```sh
- dsh-taskboard --database .dsh/taskboard.sqlite project list
- dsh-taskboard --database .dsh/taskboard.sqlite project create --key DSH --name "My project"
- dsh-taskboard --database .dsh/taskboard.sqlite task create --project <project-id> --title "Ship the plugin"
- dsh-taskboard --database .dsh/taskboard.sqlite task get --task DSH-1
- dsh-taskboard --database .dsh/taskboard.sqlite task approve --task <opaque-id> --version 1
- dsh-taskboard --database .dsh/taskboard.sqlite task accept --task <opaque-id> --version 7
- ```
- Structured writes accept JSON:
- ```sh
- dsh-taskboard task create --request-json '{"projectId":"project-...","title":"Ship","creator":"human:cli","priority":"high"}'
- dsh-taskboard task update --task task-... --version 3 --request-json '{"labels":["release"]}'
- dsh-taskboard task return --task task-... --version 4 --comment "Fix the failing test"
- ```
- Groups: `project`, `task`, `relation`, `attachment`, `workflow`, `automation`, `storage`. Full command list: [docs/cli.md](docs/cli.md).
- Exit codes: `0` success, `2` usage, `3` storage/service unavailable, `4` domain/API error, `5` optimistic conflict (`TASK_STALE_VERSION`).
- If the binary is not on `PATH`, run the installed file:
- ```sh
- node "${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@shengsheng/dsh-taskboard/lib/cli.js" --database .dsh/taskboard.sqlite storage status
- ```
- ### Automation
- On the Taskboard page, create an automation for a project: interval, Agent preset, model route, worker count, and quota policy. When enabled, the Host scheduler claims eligible `todo` work, drives a root Agent Session and Goal, and stops at `in_review`. Harness currently exposes no proactive quota signal, so the plugin reports quota as uncertain: new rules default to **ignore**, while choosing **pause-on-uncertain** deliberately prevents new claims without cancelling running work.
- The form prefills the Host's current model and reasoning settings; `defaultModelRoute` can override the form's model default. An explicit rule model route takes precedence over the Host default. Without either a rule route or a Host default model, the worker cannot start.
- Assigning a saved workflow adds its ordered tabs, branches, node kinds, and configuration to the Agent's task instruction as **guidance**. The scheduler does not automatically invoke workflow nodes; `executable` means a Host provider is registered for that node kind, not that assignment turns the workflow into an implicit runner.
- ## Configuration
- `cordis.patch.yml` mounts one Host plugin id `taskboard`. Override values in the profile composition or with environment variables. Paths are resolved by the Host. The browser cannot choose the database or attachment root.
- Relative `databasePath` / `attachmentRoot` values share one base selected by the rules below. The startup cwd helps select that base; absolute paths stay fixed:
- 1. `:memory:` and absolute paths are used as given.
- 2. If the cwd-relative database already exists, that location is kept. A store created before this rule is never abandoned. When only `attachmentRoot` is relative, it anchors this step instead, so bytes an absolute database points at are not orphaned.
- 3. Otherwise the base is the nearest git project above the process cwd: walk up until a directory contains `.git`, skipping roots that hold configuration rather than work — the home directory itself, anything above it, and dot-directories inside it such as `~/.claude` or `~/.config/nvim`. A project-local store also receives a `.dsh/.gitignore` (an existing one is left alone), so it never appears in the project's `git status`.
- 4. If no project is found, files go under `$DSH_HOME` (default `~/.dsh`), using the configured basename — for the defaults, `~/.dsh/taskboard.sqlite` and `~/.dsh/taskboard-attachments`.
- Rule 3 is deliberate: a Host started inside any git project gets a store in that project, because the board is project-local by design. A Host that must always serve one board should pin it with an absolute path rather than rely on where it was started.
- Set `DSH_TASKBOARD_DATABASE` / `DSH_TASKBOARD_ATTACHMENTS` to an absolute path (or pass `--database` / `--attachment-root` to the CLI) to force a location; a relative value follows the same four rules. The Host logs the resolved absolute paths on startup, and `taskboard database created at <abs path>` when it initializes a new database. The CLI writes the same lines to stderr, but only when it had to create a database or fell back to `$DSH_HOME` — its stdout stays a pure JSON contract. `dsh-taskboard storage status` reports both resolved paths.
- | Key | Default | Notes |
- |---|---|---|
- | `databasePath` | `.dsh/taskboard.sqlite` | `DSH_TASKBOARD_DATABASE`. Relative values follow the git-root / `$DSH_HOME` rules above; they are not resolved against a raw process cwd. |
- | `attachmentRoot` | `.dsh/taskboard-attachments` | `DSH_TASKBOARD_ATTACHMENTS`. Same resolution rules as `databasePath`, against the same base. The CLI also accepts the older `DSH_TASKBOARD_ATTACHMENT_ROOT`. |
- | `pageSize` | `100` | Bounded `taskboard_list` page; the result reports the matching total |
- | `snapshotTaskLimit` | `1000` | Tasks per web snapshot; the page reports when it was truncated |
- | `maxAttachmentBytes` | `26214400` | Per file (25 MiB) |
- | `maxTaskAttachmentBytes` | `104857600` | Per task (100 MiB) |
- | `allowedAttachmentTypes` | See list below | MIME types permitted for attachments |
- | `minAutomationIntervalMs` | `30000` | Floor for automation interval |
- | `maxProjectWorkers` | `2` | Concurrent claims per project |
- | `maxGlobalWorkers` | `4` | Concurrent claims globally |
- | `allowSharedWorktrees` | `false` | Exclusive development context |
- | `clientRefreshIntervalMs` | `15000` | Snapshot recovery interval |
- | `maxChangeWaiters` | `128` | Long-poll waiter cap |
- | `maxChangeWatchMs` | `30000` | Long-poll timeout |
- | `defaultAgentPreset` | `standard` | Worker preset |
- | `defaultModelRoute` | unset | Automation form default, in `provider:model` or `provider/model` format; otherwise uses the Host selection |
- Default `allowedAttachmentTypes`: `application/json`, `application/octet-stream`, `application/pdf`, `application/zip`, `image/gif`, `image/jpeg`, `image/png`, `image/webp`, `text/markdown`, `text/plain`. Set `allowedAttachmentTypes` and `defaultModelRoute` in the profile composition; `cordis.patch.yml` only maps the two storage path environment variables.
- Attachment content types and sizes are validated before publication. Downloads stream from disk. Dashboard and `storage status` share SQLite integrity results and bounded revision, count, attachment-cleanup, and orphaned-claim diagnostics.
- The SQLite integrity scan reads every database page, so it never runs on the snapshot path: it runs once when the database opens and on the dashboard's explicit re-check. `storageHealth.integrityCheckedAt` reports when the reported result was measured.
- While the page is open, the plugin waits on the next committed global revision over the existing Typert connection. Timeout polling and periodic snapshots are recovery paths. This does not require changing the Harness Host-event allowlist.
- Backup both the SQLite file (and WAL, if live) and the attachment directory. For a consistent offline backup, stop Harness first.
- ### Upgrading from a cwd-relative store
- Earlier versions resolved the defaults against `process.cwd()`. Nothing has to be migrated: the schema is unchanged, and rule 2 above keeps any store that already sits in the startup directory, including one under a configuration directory. A store only moves when the database it anchors on does not exist, which is when there is nothing to lose. A kept store that git can see also picks up the `.dsh/.gitignore` marker on the next start.
- What the upgrade does not do is clean up after the old behaviour. Empty `.dsh/` directories that earlier versions dropped in unrelated startup directories stay where they are. Find them:
- ```sh
- find ~ -type f -path '*/.dsh/taskboard.sqlite' 2>/dev/null
- ```
- Read each one. `projectCount`, `taskCount` and `attachmentCount` all zero means an empty shell:
- ```sh
- dsh-taskboard --database <absolute path> storage status
- ```
- Delete the empty ones. Keep the store you use where it is, since it is reused, or move it and pin it with `DSH_TASKBOARD_DATABASE` / `DSH_TASKBOARD_ATTACHMENTS`. Move the attachment directory together with the database: attachment rows hold keys relative to the attachment root and the database records no absolute path, so the pair travels anywhere but the halves do not. There is no import or merge, so two stores cannot be combined into one.
- ## Develop this repository
- ```sh
- pnpm install --frozen-lockfile
- pnpm typecheck
- pnpm test
- pnpm build
- pnpm example
- ```
- `pnpm build` cleans and rebuilds `lib/`, compiles Host declarations and runtime, copies the checked Typert artifacts, and produces the browser bundle and build fingerprint. Commit `lib/` with source changes (except JS sourcemaps), then run `pnpm verify:package`, `pnpm test:package`, and `pnpm pack:release`. Generated Remote files stay in `generated/` so an out-of-tree build does not need an adjacent Harness checkout.
- Maintainers regenerate those files with `pnpm generate:typert` against a local DeepSeek Harness checkout — `../deepseek-harness` by default, or wherever `DSH_HARNESS_ROOT` points. That checkout must be recent enough to require `create()` codec factories; an older one still emits the pre-factory shape and would overwrite `generated/` with artifacts `pnpm test` then rejects. Set `KEEP_TYPERT_WORKSPACE=1` to leave the synthetic `.typert-workspace/` in place for inspection. Every generated codec carries a `create()` factory *and* a `schema` accessor that materializes the same memoized schema, so one artifact loads both on Harness `0.1.6-alpha.1` (which reads `codec.schema`) and on newer builds (which read `codec.create()`).
- `pnpm check` runs typecheck, tests, and build.
- ## Further documentation
- | Document | Contents |
- |---|---|
- | [docs/architecture.md](docs/architecture.md) | Module owners and refresh model |
- | [docs/security.md](docs/security.md) | Authority split, attachments, recovery |
- | [docs/cli.md](docs/cli.md) | JSON CLI groups and exits |
- | [docs/acceptance-audit.md](docs/acceptance-audit.md) | Row-by-row acceptance evidence |
- | [docs/browser-e2e.md](docs/browser-e2e.md) | Deterministic browser lifecycle |
- | [docs/install-plugin-prompt.zh.md](docs/install-plugin-prompt.zh.md) | Chinese copy-paste install prompt for a Harness agent |
- | [docs/plugin-compatibility.zh.md](docs/plugin-compatibility.zh.md) | Distribution strategy, compatibility matrix, and verification boundaries |
- | [skills/manage-taskboard/SKILL.md](skills/manage-taskboard/SKILL.md) | Agent operating procedure |
- ## License
- Apache-2.0. See `LICENSE` and `THIRD_PARTY_NOTICES.md`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.