dsh-tower 1.2.0 → 2.0.0

package/docs/reference/blockers.md

@@ -0,0 +1,58 @@
+# Blockers and failure codes
+
+`tower_preflight` returns `{ok:false, blockers:[{code, detail}]}`. `tower_merge` and `tower_rebase`
+return the same shape for operation failures. Codes are stable; the detail is human-facing.
+
+## Gate blockers (26)
+
+| Code | Meaning / next action |
+|---|---|
+| `mission-missing` | Unknown mission id. Check `tower_status`. |
+| `mission-not-completed` | Mission is not `completed`; only a completed mission (awaiting review) merges. |
+| `tasks-open` | Open tasks remain; the worker must finish or `task_drop` with a reason. |
+| `blockers-present` | The mission has blockers; clear them after resolving. |
+| `no-check-evidence` | `gates.requireChecks` is enabled and the completion report has no `checks`. Return the completed mission to `active`, re-run `tower_complete` with checks, then review again. |
+| `branch-missing` | No worktree/branch yet: spawn a worker first. |
+| `stale-base` | The branch does not contain the base tip: run `tower_rebase`. |
+| `read-only-survey` | Survey mission changed files; survey missions must be read-only. |
+| `out-of-scope` | Changed files outside the mission scope; widen scope deliberately or revert. |
+| `base-dirty` | The main checkout has uncommitted changes the merge would overwrite. |
+| `deps-unmerged` | A dependency mission is not merged/abandoned. |
+| `no-review` | No review on the branch: spawn a reviewer. |
+| `review-mission-mismatch` | The latest review belongs to another mission. |
+| `not-clean` | Latest review is `p1-Nitems`/`p2-Nitems`; another round is required. |
+| `review-hold` | Latest review recommends hold; a later clean review must supersede it. |
+| `review-not-approved` | Latest clean review says `fix-then-merge` or `hold`; only `merge` approves. |
+| `tip-moved` | The branch changed after review; review again (or use a clean rebase waiver). |
+| `worker-busy` | A roster agent for this mission is running; wait or retire it. |
+| `worker-status-unknown` | The parent catalog is unavailable, so a live roster agent cannot be proven stopped; retry after the catalog recovers or adopt it. |
+| `base-wrong-branch` | The main checkout is not on the recorded base branch. |
+| `branch-owned-by-closed-missions` | The mission is already merged/abandoned; re-plan under a new title. |
+| `worker-stale` | A roster worker for this mission has no catalog activity beyond `spawn.staleMs`; adopt it (or interrupt it only if it is actually running) before merge. |
+| `tests-missing` | `gates.requireTests` is enabled and there is no passing discovery receipt for the reviewed tip; run `tower_test` or `tower_complete`. |
+| `tests-failed` | The latest discovery receipt failed or did not meet minCount/required checks. Fix the tests and re-run. |
+| `review-exemption-invalid` | The mission requests `reviewPolicy:"none"` but `gates.allowReviewExemption` is off (or the reason is missing). |
+| `merge-intent-pending` | A merge intent was recorded before a crash/failure; run `tower_merge` to reconcile before another gate. |
+
+## Merge failures (4)
+
+| Code | Meaning / next action |
+|---|---|
+| `merge-conflict` | Real index conflict; the mission is `blocked`. Resolve, restore the mission to `active`/`completed`, retry. |
+| `merge-hook-failed` | A hook/process failed before a commit existed; repository restored, mission stays `completed`. Retry; `timeout: true` means the git process timed out. Raise `timeoutMs` for slow hooks. |
+| `merge-shape` | Git produced unexpected merge parents; inspect the repository, do not force. |
+| `batch-invalid` | A batch id/member/receipt/check reference is invalid or close evidence is incomplete. |
+
+A merge that already landed is **not** a blocker: `tower_merge` records it (`reconciled`,
+`alreadyLanded`) or recovers it (`recoveredFromFailure`, `warnings`).
+
+## Rebase failures (3; `worker-busy` shared)
+
+| Code | Meaning / next action |
+|---|---|
+| `worktree-dirty` | Commit or discard worktree changes, then retry. |
+| `rebase-conflict` | A real conflict; the mission is `blocked`. Resolve manually, return it to `active`, retry. |
+| `worker-busy` | An agent is running for this mission; wait or retire it first. |
+
+`tower_rebase` returns `alreadyMerged: true` when the branch is already contained in the base; call
+`tower_merge` to record the landed merge.

package/docs/reference/config.md

@@ -0,0 +1,114 @@
+# Config reference
+
+Every key is optional; defaults reproduce the shipped behavior. Unknown top-level keys are rejected.
+`section` and `allowAgentControl` are legacy aliases for `mode.promptSection` and
+`mode.allowAgentControl`. A legacy alias only fills a gap: when both forms are set, the canonical
+`mode.*` key wins.
+
+## Layers and precedence
+
+Lowest precedence first:
+
+1. code defaults (the table below),
+2. profile config (the Cordis patch that mounts `dsh-tower` passes it to `apply()`),
+3. repository config at `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/config.json`),
+4. per-call tool arguments such as `worktreeRoot` and `timeoutMs`.
+
+The repository layer is read every time a Tower tool opens a repository, so a repository can tune
+review, merge, worktree and spawn policy without editing the profile. It uses the same JSON shape as
+the profile config (the same groups and the legacy aliases) and is merged group by group: repo keys
+win, profile keys survive when the repo does not set them. `tower_status` reports
+`config.path` and `config.repoConfigPresent`.
+
+```json
+{
+  "review": { "maxRoundsPerReviewer": 3 },
+  "merge": { "timeoutMs": 1800000 },
+  "worktrees": { "root": "D:/tower-worktrees" },
+  "spawn": { "reviewerPreset": "tower-reviewer", "maxDepth": 2 }
+}
+```
+
+The `mode.*` group is session-scoped, not repository-scoped: it is accepted in the repository file
+for schema compatibility but only the profile config controls the Tower-mode prompt and the
+model-controlled toggle. A malformed file, a non-object value, unknown top-level keys, or a value that
+violates the declared schema (for example `merge.timeoutMs` below 1000) fail with the stable
+`config-invalid` / `config-unknown-key` tool error codes.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `section` | `''` | Legacy alias: replace the whole Tower-mode prompt text. Empty keeps the built-in reminder. |
+| `allowAgentControl` | `false` (bundled patch: `true`) | Legacy alias: register `tower_control`. |
+| `init.autoGitInit` | `false` (bundled patch: `true`) | `tower_init` may run `git init` + an empty initial commit when `repoRoot` is an absolute, existing directory that is not a repository. |
+| `init.snapshotDirty` | `false` | `tower_init` may snapshot uncommitted **tracked** changes into a dangling commit used as the mission baseline (untracked files are not included; the commit is kept alive under `refs/tower/snapshot/*`). |
+| `mode.promptSection` | `''` | Replacement prompt text (takes precedence over `section` when both set). |
+| `mode.sectionAppend` | `''` | Extra text appended after the reminder (team conventions). |
+| `mode.allowAgentControl` | `false` | Register `tower_control`; the model may enter/leave with a reason. |
+| `mode.autoPauseGoal` | `true` | Pause an active goal on entry; the goal is never auto-resumed on exit. |
+| `mode.requireResumeAuthorization` | `false` | Resuming a mission paused with `pauseCause:user` requires an `authorization` reference. |
+| `mode.workspaceLock` | `false` (bundled patch: `true`) | Allow only one Tower session per repository (`tower.lock`); others get `workspace-busy`. |
+| `mode.workspaceLockScope` | `all` | `all` locks every repo tool; `mutations` skips the workspace lock for read-only tools. |
+| `mode.planModePolicy` | `clear` | Tower entry clears an active plan mode (or `refuse` until the plan is exited); a pre-step also clears a plan activated later. |
+| `mode.workspaceStaleMs` | `300000` | A workspace lock older than this can be taken over. |
+| `mode.heartbeatMs` | `10000` | Workspace-lock heartbeat interval. |
+| `mode.denyTools` | goal/todo/team/workflow/subagent tools | Tools refused while the mode is active (12 defaults). |
+| `mode.storePath` | `$DSH_HOME/tower-mode` | Directory for `modes.json`. |
+| `mode.maxEntries` | `200` | Maximum persisted mode entries (1–2000). |
+| `review.maxRoundsPerReviewer` | `5` | Review-round cap per reviewer per branch. |
+| `merge.timeoutMs` | `900000` (15 min) | Default `tower_merge` timeout, including hooks. A per-call `timeoutMs` wins. |
+| `merge.maxBufferBytes` | `67108864` (64 MB) | Merge output buffer. |
+| `worktrees.root` | `''` | Default worktree parent; empty derives `<checkout parent>/.dsh-tower-worktrees/<hash>`. |
+| `spawn.workerPreset` | `tower-worker` | Preset used for `role=worker`. |
+| `spawn.reviewerPreset` | `tower-reviewer` | Preset used for `role=reviewer`. |
+| `spawn.maxDepth` | `1` | Subagent depth requested at spawn. |
+| `spawn.provider` | `''` | Subagent provider id; empty prefers `spawn`, then the first provider. |
+| `spawn.workerModel` | `{}` | Optional `{provider, model, reasoningEffort, maxTokens}` for workers. |
+| `spawn.reviewerModel` | `{}` | Optional model route for reviewers; independent review is stronger with a different model. |
+| `spawn.maxLiveWorkers` | `4` | Maximum live worker entries per repository (idle `inactive`, failed, interrupted, missing, stale and retired entries do not count); exceeding it returns `worker-limit`. |
+| `spawn.staleMs` | `15000` | Roster entries without catalog activity after this age are marked `stale` and block merge (`worker-stale`); 0 disables. |
+| `spawn.maxWaitMs` | `90000` | Upper bound for `tower_spawn.waitMs` (Kimi-compatible 90s default). |
+| `spawn.requireLease` | `''` | Optional lease name that must be held before a worker can spawn. |
+| `send.maxPerMinute` | `120` | Per-repository `tower_send` rate limit (0 disables); exceeding it returns `rate-limited`. |
+| `send.interruptDefault` | `false` (bundled patch: `true`) | Default for `tower_send.interrupt` (interrupt the running turn before delivering). |
+| `tests.enabled` | `true` | Run declared test discovery when the worktree `package.json` configures it. |
+| `tests.admission` | `complete` | `spawn` runs discovery before starting a worker, `complete` at `tower_complete`, `off` only on explicit `tower_test`. |
+| `tests.timeoutMs` | `60000` | Per discovery command timeout. |
+| `tests.maxBytes` | `16777216` (16 MiB) | Captured stdout cap per command. |
+| `tests.autoChecks` | `true` | Attach an automatic `tests` check to the completion report. |
+| `tests.allowPackageDiscovery` | `true` | Allow repo-controlled `tower.testDiscovery` commands (executes worktree code; see security). |
+| `gates.requireChecks` | `false` | Require at least one `tower_complete.checks` entry before merge (`no-check-evidence`). |
+| `gates.requireTests` | `false` | Require a passing discovery receipt for the reviewed tip (`tests-missing`). |
+| `gates.allowReviewExemption` | `false` | Allow `reviewPolicy:"none"` + reason to skip review blockers; default off deliberately. |
+| `docs.board` | `true` | Write `MISSIONS.md` after mutations. |
+| `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`; `repo` = `<repoRoot>/MISSIONS.md`. |
+| `leases.ttlMs` | `900000` | Default advisory lease lifetime; expiry never auto-releases. |
+| `dev.hotReload` | `true` | Register `tower_reload`; `/tower reload` is disabled when off. It returns `reload-unavailable` when the profile has no HMR service. |
+| `dev.reloadDelayMs` | `50` | Delay before a scheduled reload so the tool result is delivered first. |
+| `dev.reloadRequiredIds` | four Tower loader ids | Entry ids passed to `reconcileProfile` as required. |
+
+## Example
+
+```yaml
+- id: tower
+  name: 'dsh-tower'
+  config:
+    mode:
+      allowAgentControl: true
+      sectionAppend: 'Team conventions: tests are mandatory.'
+      workspaceLock: true
+    review:
+      maxRoundsPerReviewer: 3
+    merge:
+      timeoutMs: 1800000
+    spawn:
+      reviewerModel:
+        provider: deepseek-account
+        model: deepseek-flash
+    dev:
+      hotReload: true
+```
+
+## Looking up the effective schema
+
+`cordis_inspect_query` with `Config.listConfigs({ name: "dsh-tower" })` returns the projected JSON
+Schema once the plugin declares `Config` (this release does).

package/docs/reference/doctor.md

@@ -0,0 +1,31 @@
+# Doctor
+
+`tower_doctor({repoRoot})` is read-only. It never takes the state lock, writes state, or changes Git.
+It returns:
+
+```json
+{
+  "ok": true,
+  "checks": [
+    { "id": "git", "status": "pass", "detail": "git version 2.55.0" },
+    { "id": "state", "status": "pass", "detail": ".../state.json revision 7" }
+  ],
+  "environmentContract": {
+    "platform": "win32",
+    "gitVersion": "git version 2.55.0",
+    "repoRoot": "D:/repo",
+    "commonDir": "D:/repo/.git",
+    "stateDir": "D:/repo/.git/dsh-tower"
+  }
+}
+```
+
+Checks cover: git availability, repository identity, state schema/load, repo config presence,
+worker/reviewer preset names, subagents and HMR services, workspace lock holder/staleness, live roster,
+worktree existence/ownership/dirtiness, test-discovery policy, legacy snapshots, batches and leases.
+`warn` is advisory; `fail` means the repository needs attention before spawning/merging. A state-load
+failure is reported as a failed check rather than thrown so doctor remains useful on a broken
+repository.
+
+The environment contract is informational; it is not an identity or authorization proof. `tower_init`
+still requires the tower role, and `tower_spawn` still checks the live subagent catalog.

package/docs/reference/errors.md

@@ -0,0 +1,50 @@
+# Tool error codes
+
+Tool failures are thrown errors, not `{ok:false}` results (gate outcomes are the exception: see
+[blockers.md](blockers.md)). Every thrown error carries a stable code as a message prefix:
+
+```
+[tower:mission-not-found] unknown mission "M9"
+```
+
+Callers can match the prefix instead of the prose. Codes are reserved for the conditions below; a
+message without a more specific match is reported as `tool-internal`.
+
+| Code | Meaning | Typical trigger |
+|---|---|---|
+| `invalid-argument` | A tool argument is missing, malformed, or not allowed. | `missionId`/`id` omitted; unknown status; empty report; bad scope glob; `timeoutMs < 1000`; `status: "all"` on an update. |
+| `repo-invalid` | `repoRoot` is missing, relative, or not inside a Git repository. | passing a path in a directory that is not a repo |
+| `not-initialized` | Tower is not initialized for this repository. | a read tool before `tower_init` |
+| `mission-not-found` | No mission with that id exists. | a stale or mistyped `M9` |
+| `finding-not-found` | No finding with that id exists. | `tower_findings({id:"F99"})` |
+| `invalid-transition` | The requested state transition is not allowed. | a blocked→merged attempt; a finding transition not in the graph; a reviewer mutating findings; completing a mission with open tasks, blockers, no commits, or unread inbox messages. |
+| `state-locked` | Another Tower writer holds the state lock. | concurrent mutation after the lock timeout |
+| `state-corrupt` | The Tower state file is unreadable or invalid. | hand-edited `state.json` |
+| `config-invalid` | Tower configuration is invalid. | malformed repo `config.json`, a value that violates the schema |
+| `config-unknown-key` | Tower configuration has an unknown top-level key. | a typo such as `allowAgentToggle` |
+| `git-failed` | A git command failed for a reason other than the delegated cases. | a rejected merge command, invalid ref |
+| `git-timeout` | A git command timed out or exceeded its output buffer. | slow pre-merge hook, huge diff |
+| `spawn-unavailable` | The subagents service is unavailable. | a Host without `subagents` |
+| `provider-missing` | No subagent provider is registered. | an empty provider list |
+| `preset-missing` | The configured agent preset is not registered. | missing `tower-worker`/`tower-reviewer` preset rows, DSH not restarted |
+| `reviewer-prerequisite` | The reviewer spawn prerequisite is not met. | reviewer spawned before the mission is `completed`, or before a worktree exists |
+| `not-authorized` | The calling agent role may not perform this action. | a worker calling a tower-only tool or changing mission status/scope; a reviewer mutating findings |
+| `workspace-busy` | Another Tower session owns this repository's workspace lock. | `mode.workspaceLock:true` and a second session calls a repo-scoped tool |
+| `worker-limit` | The repository reached `spawn.maxLiveWorkers` live workers. | spawning a fifth worker with the default limit |
+| `rate-limited` | The `tower_send` per-minute rate limit was reached. | `send.maxPerMinute` exceeded; retry later |
+| `takeover-refused` | The mission still has a running worker. | `tower_spawn({takeover:true})` before `tower_interrupt` |
+| `reload-unavailable` | The DSH HMR service is not available in this profile. | `tower_reload` / `/tower reload` on a profile without HMR |
+| `reload-failed` | The HMR reload failed. | `reconcileProfile` threw; check the DSH log and restart |
+| `tests-failed` | Declared test discovery failed or did not meet admission requirements. | nonzero command, malformed output, minCount/required shortfall |
+| `tests-timeout` | Test discovery exceeded its time or output budget. | `tests.timeoutMs`, or stdout over `tests.maxBytes` |
+| `lease-busy` | Another holder owns the requested advisory lease. | `tower_resource acquire` while `heavy-ci` is held |
+| `lease-token` | The lease release token does not match the holder. | releasing with another session's token |
+| `batch-invalid` | A batch request or its close evidence is invalid. | unknown member, duplicate id, unsafe receipt path, missing receipt hash |
+| `legacy-invalid` | The legacy snapshot or mapping is invalid. | unknown schema, source inside the Tower state dir, mapping rewrite |
+| `tool-internal` | An unexpected failure. | a bug; read the message and the activity log |
+
+## Why thrown?
+
+Returned `{ok:false}` shapes are reserved for expected policy outcomes that the tower decides on
+(`tower_merge`/`tower_rebase` gate blockers and `tower_preflight`). Anything that prevents the tool
+from producing a decision is thrown so the model does not mistake it for a normal negative result.

package/docs/reference/events.md

@@ -0,0 +1,45 @@
+# Tower events
+
+Tower emits process-local Cordis events after successful tool calls (mutations and read-only tools), so
+other plugins can observe a repository without polling. Events are **not** sent over the network and carry
+no telemetry.
+
+```js
+ctx.on('tower/merge', (payload) => {
+  // payload.tool, payload.repoRoot, payload.value (the tool's JSON result)
+})
+```
+
+| Event | Emitted after |
+|---|---|
+| `tower/init` | `tower_init` created or re-anchored state |
+| `tower/plan` | `tower_plan` created missions |
+| `tower/mission` | `tower_mission` changed one mission |
+| `tower/spawn` | `tower_spawn` recorded a worker/reviewer |
+| `tower/complete` | `tower_complete` recorded a completion report |
+| `tower/review` | `tower_review` recorded a verdict |
+| `tower/merge` | `tower_merge` returned (including gate failures; inspect `value.ok`) |
+| `tower/rebase` | `tower_rebase` returned |
+| `tower/teardown` | `tower_teardown` removed worktrees |
+| `tower/finding` | `tower_finding` created one finding |
+| `tower/findings` | `tower_findings` read/listed/updated findings |
+| `tower/send` | `tower_send` persisted a message |
+| `tower/inbox` | `tower_inbox` acknowledged messages |
+| `tower/interrupt` | `tower_interrupt` stopped a live agent |
+| `tower/diff` | `tower_diff` read a mission diff |
+| `tower/adopt` | `tower_adopt` reconciled the roster |
+| `tower/roster` | `tower_roster` read the roster |
+| `tower/status` | `tower_status` read the dashboard |
+| `tower/preflight` | `tower_preflight` evaluated the gate |
+| `tower/doctor` | `tower_doctor` completed its read-only checks |
+| `tower/test` | `tower_test` ran discovery |
+| `tower/batch` | `tower_batch` created, inspected or closed a batch |
+| `tower/resource` | `tower_resource` acquired/released/inspected leases |
+| `tower/import_legacy` | `tower_import_legacy` stored a legacy snapshot |
+| `tower/legacy_map` | `tower_legacy_map` mapped or listed legacy ids |
+
+`tower_mode`, `tower_control` and `tower_reload` do not emit Tower events. Payloads are JSON:
+`{tool, repoRoot, value}`. Listener exceptions never affect the tool result.
+
+For a durable audit trail use `<git-common-dir>/dsh-tower/activity.jsonl` and `MISSIONS.md` instead;
+events are process-local and are not replayed.

package/docs/reference/operations.md

@@ -0,0 +1,52 @@
+# Batches, leases and legacy import
+
+## Evidence batches
+
+`tower_batch` groups finite mission completion evidence.
+
+- `create` freezes `missionIds`, `exclusions`, `requiredChecks` (default `["check"]`) and exact
+  relative `receiptPaths`. Members must be known missions and only paused legacy missions may be
+  excluded; membership is immutable after create.
+- `status` summarizes members and pending/failed checks.
+- `close` verifies every required check for completed members (from `completionReport.checks`,
+  `testRuns`, or close-time `checks`), checks `treeTip` when provided, and requires every frozen
+  receipt path to be supplied in `receiptHashes`/`receipts` (or bound to a passing check with
+  `receiptHash`). Missing evidence returns `{ok:false, blockers}`; nothing is deleted.
+
+A failed close is not a partial close: the batch stays `open` and can be retried after evidence is
+fixed.
+
+## Advisory leases
+
+`tower_resource` manages per-repository leases in `<git-common-dir>/dsh-tower/leases.json`:
+
+```text
+tower_resource({action:"acquire", name:"heavy-ci", ttlMs:900000})
+tower_resource({action:"status"})
+tower_resource({action:"release", name:"heavy-ci", token:"<token from acquire>"})
+```
+
+- acquire is tower-only; the caller gets a token, pid, holder, created/expiry timestamps;
+- the same token renews; another holder gets `[tower:lease-busy]`;
+- release requires the token; an **expired** lease still requires the token and explicit `force:true`
+  (no silent takeover);
+- `spawn.requireLease` makes a worker spawn fail unless that lease is held.
+
+Leases coordinate local jobs and CI windows. They are **not** an OS CPU/memory hard cap: DSH has no
+public Job Object quota API, so Tower cannot enforce per-process resource limits; use the live-worker
+cap and your OS/CI scheduler for those.
+
+## Legacy import and mapping
+
+`tower_import_legacy({repoRoot,sourcePath})` accepts a Tower Codex `schemaVersion:1` state file or a
+DSH legacy state. It:
+
+- requires an absolute source path outside `<git-common-dir>/dsh-tower`;
+- validates the schema (16 MiB cap), stores the raw payload byte-for-byte under
+  `<git-common-dir>/dsh-tower/legacy/<sha256>.json`, and records only a summary in
+  `state.legacySnapshots`;
+- never activates, adopts, or resumes paused missions.
+
+`tower_legacy_map` records an audit-only `sourceHash + oldId → newMissionId?` mapping. Mappings are
+append-only; rewriting an existing mapping to another mission is rejected. Mapping does not change
+mission state.

package/docs/reference/testing.md

@@ -0,0 +1,61 @@
+# Testing, discovery and evidence
+
+Tower 2.1 can execute a repository's declared test discovery and turn its result into durable
+completion evidence. Discovery is **opt-in by configuration**: a worktree with no
+`package.json.tower.testDiscovery` block behaves exactly as before.
+
+## Configuration
+
+`package.json` (Tower Codex-compatible):
+
+```json
+{
+  "tower": {
+    "testDiscovery": {
+      "version": 1,
+      "commands": [
+        {
+          "id": "unit",
+          "command": "node --test dist/tests/*.test.js",
+          "format": "node-tap",
+          "minCount": 1,
+          "required": ["smoke"]
+        }
+      ]
+    }
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | Unique, `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`; also used in diagnostic file names. |
+| `command` | Shell command executed with the worktree as cwd (Windows `pwsh`, POSIX `bash`). |
+| `format` | `node-tap` (TAP `ok N - name` / `not ok`) or `json-array` (JSON array of `{name, ok?}`). |
+| `minCount` | Minimum discovered tests for this command (default 1). |
+| `required` | Test names that must appear and pass. |
+
+`tests.*` in the Tower config controls admission, timeout, output cap and whether package discovery
+is allowed. `tests.admission` is `spawn` (before a worker starts; fail-closed, no child), `complete`
+(at `tower_complete`; default), or `off` (explicit `tower_test` only).
+
+## Receipts and gates
+
+Each run stores a receipt under `<git-common-dir>/dsh-tower/test-runs/<mission>-<stamp>/` with
+stdout/stderr files, SHA-256 hashes, exit codes, counts, required names, the worktree tip, and an
+overall `ok`. `state.missions[].testRuns` keeps the most recent 50 receipts. The tool returns
+`ok:false` with diagnostics on failure; `tower_complete` throws `[tower:tests-failed]` when automatic
+discovery fails.
+
+- `tower_test({repoRoot,missionId})` runs discovery on demand and records a receipt.
+- `tower_complete` adds a `tests` check when `tests.autoChecks` is on.
+- `gates.requireChecks` requires any completion check; `gates.requireTests` requires a passing receipt
+  for the reviewed tip (`tests-missing`).
+
+## Trust boundary
+
+Discovery commands are repository-controlled code. `tests.allowPackageDiscovery:false` disables the
+package block; a CI or policy profile should set it when cloning untrusted repositories. The command
+runs with the same OS permissions as DSH, in the mission worktree, with no network access added by
+Tower. Output is capped at `tests.maxBytes` (16 MiB default) and each command at `tests.timeoutMs`
+(60 s default); over-budget runs fail closed.

package/docs/reference/tools.md

@@ -0,0 +1,75 @@
+# Tools reference
+
+All tools take `repoRoot` (an absolute path inside the target Git repository) and return JSON.
+The build exposes up to 28 tools: 19 core repository tools below (including `tower_interrupt`),
+`tower_mode`, `tower_control` when `mode.allowAgentControl` is enabled (the bundled patch enables it),
+`tower_reload` while `dev.hotReload` is on, and the 2.1 verification/ops tools `tower_doctor`,
+`tower_test`, `tower_batch`, `tower_resource`, `tower_import_legacy`, `tower_legacy_map`.
+
+`tower_mission` uses `id` (alias `missionId`); every other mission-scoped tool uses `missionId`
+(alias `id`). Other input aliases: `task_done`/`taskDone`, `task_drop`/`taskDrop`,
+`task_drop_reason`/`taskDropReason`, `clear_blockers`/`clearBlockers`,
+`include_read`/`includeRead`, `dry_run`/`dryRun`, `timeoutMs`/`timeout_ms`,
+`waitMs`/`wait_ms`, `mission_id`/`missionId` on findings, `agent_id`/`agentId` on interrupt,
+`include_gate`/`includeGate` on status, `retire_missing`/`retireMissing` on adopt. Outputs use
+canonical camelCase names.
+
+## Roles
+
+Roster roles are resolved from `exec.agent` + the roster. Mission-scoped tools (`tower_interrupt`,
+`tower_init`, `tower_plan`, `tower_spawn`, `tower_merge`, `tower_rebase`, `tower_teardown`,
+`tower_adopt`, `tower_reload`) are **tower only**. `tower_batch` create/close, `tower_resource`
+acquire/release, `tower_import_legacy`, `tower_legacy_map` map and review-exemption planning are
+tower-only; their read-only status actions are open to roster roles. A worker may call `tower_mission`
+only for `task_done`/`task_drop`/`blocker`/`note`; status changes, scope widening, `clear_blockers` and
+`completed` are tower-only (completion must go through `tower_complete`). A roster reviewer may read
+findings but not mutate them. Violations throw `[tower:not-authorized]` or
+`[tower:invalid-transition]`.
+
+## Tools
+
+| Tool | Parameters | Purpose / notes |
+|---|---|---|
+| `tower_init` | `base?`, `autoGitInit?`, `snapshotDirty?`, `reanchor?` | Create `<git-common-dir>/dsh-tower/state.json`. `autoGitInit` runs `git init` + empty initial commit; `snapshotDirty` records a dangling snapshot commit of uncommitted tracked changes used as the mission baseline; `reanchor` changes base only when no non-terminal mission exists. Returns `dirty`, `snapshotCommit`, `reanchored`. |
+| `tower_plan` | `missions[]` (`title`, `scope[]`, `tasks[]?`, `deps[]?`, `kind?`, `context?`, `references[]?` ≤20, `reviewPolicy?`, `reviewExemptionReason?`) | Create missions `M1..`; overlapping build scopes auto-add a dependency; rejects unknown deps and cycles. `reviewPolicy:"none"` requires a reason and `gates.allowReviewExemption`. |
+| `tower_mission` | `id` (alias `missionId`), `status?`, `task_done?`, `task_drop?`+`task_drop_reason?`, `blocker?`, `clear_blockers?`, `note?`, `scope?`, `pause_cause?`, `authorization?` | Update one mission. Worker-safe fields are task/blocker/note; `merged` cannot be set here. Paused missions record `pause_cause` (user/failure/resource/dependency); resuming a user-paused mission honors `mode.requireResumeAuthorization`. |
+| `tower_status` | `missionId?`, `offset?`, `limit?`, `includeGate?`, `format?` | Dashboard by default. `missionId` returns full detail (tasks/notes/reviews/findings/completionReport). `offset`/`limit` page missions (default 20, max 100), `includeGate` adds gate digests, `format:"markdown"` returns the board. |
+| `tower_spawn` | `missionId` (alias `id`), `role` (`worker`/`reviewer`), `name?`, `instructions?`, `worktreeRoot?`, `wait?`, `waitMs?`, `takeover?`, `includeDirtyBase?` | Provision/reuse the worktree and start a subagent. Worker uses `tower-worker`; reviewer requires a `completed` mission and uses the read-only `tower-reviewer`. `takeover:true` replaces a live worker entry that is no longer running (increments ownerGeneration). Only one live worker per mission; `spawn.maxLiveWorkers` caps the repository. |
+| `tower_roster` | — | Roster with live activity (`running`/`inactive`/`missing`/`unknown`) and `stale` flags from the subagent catalog. Read-only. |
+| `tower_adopt` | `retireMissing?` | Reconcile roster entries with the durable subagent catalog. Provably gone agents are retired (default) or marked `missing` (`retireMissing:false`) so they can be inspected/taken over. |
+| `tower_diff` | `missionId` (alias `id`), `maxBytes?` | Read-only merge-base diff: files, commits, capped patch. Safe for reviewers. |
+| `tower_send` | `to`, `subject`, `body`, `scope?`, `interrupt?`, `consentRef?` | Durable message to a roster name, `tower`, or `all`; delivers live to a running agent. `interrupt:true` interrupts the running turn first (Kimi-style), then delivers; `consentRef` is recorded for audit. Rate-limited by `send.maxPerMinute`. |
+| `tower_inbox` | `limit?`, `include_read?` | Read/ack messages addressed to the caller; unread messages block `tower_complete`. |
+| `tower_complete` | `missionId` (alias `id`), `report`, `checks?` | Worker reports completion (mission becomes `completed`, awaiting review). Requires current owner, no open tasks/blockers, ≥1 commit, no unread inbox. `checks` records `{name, command?, exitCode?, evidence?}` evidence; `gates.requireChecks` can demand it. When configured, test discovery runs automatically and adds a `tests` check; failure throws `[tower:tests-failed]`. |
+| `tower_interrupt` | `to?` (roster name), `agentId?`, `reason?` | Interrupt one running roster agent via `subagents.interrupt`, record `state:"interrupted"`. Idempotent (not running → `interrupted:false`). |
+| `tower_finding` | `type`, `title`, `summary`, `details`, `suggested_fix`, `severity?`, `missionId?`, `location?` | Record an out-of-scope issue; reviewers use this instead of editing. Finds start as `open`. |
+| `tower_findings` | `id?`, `status?`, `note?`, filters (`type?`, `severity?`, `missionId?`, `open?`, `limit?`) | Lifecycle tool: list/read/transition. Statuses `open → triaged → fixed`/`wontfix`, reopen allowed. Only the tower or a worker may mutate; a reviewer can list/read. |
+| `tower_review` | `missionId` (alias `id`), `status` (`clean`/`p1-Nitems`/`p2-Nitems`), `merge` (`merge`/`fix-then-merge`/`hold`), `findings`, `decision`, `checks?`, `breakGlassReason?` | Reviewer verdict bound to the current tip. Reviewer must be the assigned reviewer (or tower break-glass). |
+| `tower_preflight` | `missionId` (alias `id`) | Read-only gate: returns `{ok, blockers[], branchTip, baseTip, changedFiles, review}`. |
+| `tower_merge` | `missionId` (alias `id`), `timeoutMs?` (alias `timeout_ms`) | Merge after a green gate. Records already-landed merges (`reconciled`), recovers a failed call whose commit exists (`recoveredFromFailure`), and separates `merge-hook-failed` from `merge-conflict`. |
+| `tower_rebase` | `missionId` (alias `id`) | Rebase the branch onto the base in its worktree. Refuses while the worker runs or the worktree is dirty. Already-contained branches return `alreadyMerged` untouched. |
+| `tower_teardown` | `force?`, `exclude?`, `dry_run?` (alias `dryRun`) | Remove eligible merged/abandoned worktrees and branches; running agents are always kept. |
+| `tower_mode` | — | Report mode, last change, paused goal, denied tools, store path, plugin version, HMR availability, workspace-lock holder. |
+| `tower_control` | `action` (`enter`/`exit`), `reason` | Model-initiated mode change; only when `mode.allowAgentControl` is true; reason is mandatory. |
+| `tower_reload` | `repoRoot?` | Dev-only: ask DSH HMR to reconcile the profile and reload the Host plugin from disk. Registered while `dev.hotReload` is on; scheduled after the result (default 50 ms); fails with `reload-unavailable` without HMR. When `repoRoot` is supplied the caller must be the tower. |
+| `tower_doctor` | — (takes `repoRoot`) | Read-only health contract: git, state schema, config, presets/subagents/HMR, workspace lock, roster, worktree realpath/ownership, test config, leases. Returns `{ok, checks[{id,status,detail}], environmentContract}`. Never writes. |
+| `tower_test` | `missionId` (alias `id`) | Run the worktree's `package.json` `tower.testDiscovery` and record a receipt; `ok:false` on failure. Use `tower_complete` for automatic admission checks. |
+| `tower_batch` | `action` (`create`/`status`/`close`), `missionIds?`, `exclusions?`, `requiredChecks?`, `receiptPaths?`, `batchId?`, `checks?`, `treeTip?`, `receiptHashes?` | Finite evidence batch. Create freezes members/checks/receipts; close verifies every required check and receipt hash. Membership is immutable; close never deletes missions. |
+| `tower_resource` | `action` (`acquire`/`release`/`status`), `name?`, `holder?`, `token?`, `ttlMs?`, `force?` | Advisory per-repository lease in `<common>/dsh-tower/leases.json`. No OS CPU/memory hard cap; expired leases require explicit `force` and the correct token. |
+| `tower_import_legacy` | `sourcePath` | Read-only import of a Tower Codex `schemaVersion:1` or DSH legacy state. Full payload goes under `<common>/dsh-tower/legacy/<sha256>.json`; state stores a summary only. Never activates/adopts/resumes paused missions. |
+| `tower_legacy_map` | `action` (`map`/`status`), `sourceHash?`, `oldId?`, `newMissionId?` | Audit-only legacy-id mapping; mappings are append-only and never adopt a mission. |
+
+## Workspace lock
+
+With `mode.workspaceLock:true` (the bundled patch enables it), the first repo-scoped Tower tool call
+from a Tower-mode session acquires `<git-common-dir>/dsh-tower/tower.lock`; another session gets
+`[tower:workspace-busy]` until the holder runs `/tower off` or the lock exceeds
+`mode.workspaceStaleMs`. `mode.workspaceLockScope:"mutations"` skips the lock for read-only tools.
+Code default is off; the shipped patch is on for Kimi-compatible single-active-tower behavior.
+
+## Failure results
+
+Gate tools return `{ok:false, blockers:[{code, detail}]}`; the code list is in
+[blockers.md](blockers.md). Thrown tool errors carry a stable `[tower:<code>]` prefix
+([errors.md](errors.md)). Successful mutations emit process-local events ([events.md](events.md)),
+and, with `docs.board:true`, refresh `<git-common-dir>/dsh-tower/MISSIONS.md`.

package/docs/zh/README.md

@@ -0,0 +1,58 @@
+# dsh-tower 中文文档
+
+[English docs](../README.md) | **简体中文**
+
+英文文档是权威来源；本页是中文翻译入口。英文文档位于 [docs/](../README.md)，仓库主页见
+[README.md](../../README.md)。
+
+## 2.1 能力概览
+
+- **只读健康检查**：[Doctor](reference/doctor.md)（`tower_doctor`）检查 git、state、配置、preset、
+  workspace 锁、roster、worktree 归属、测试策略与租约，不写任何状态。
+- **测试发现与完成证据**：[测试、发现与证据](reference/testing.md)。仓库可在
+  `package.json.tower.testDiscovery` 声明发现命令；回执可自动附加到 `tower_complete`，
+  `gates.requireTests` 可要求针对被审查 tip 的通过回执。
+- **证据批次、咨询式租约、旧版导入**：[批次、租约与旧版导入](reference/operations.md)
+  （`tower_batch`、`tower_resource`、`tower_import_legacy`、`tower_legacy_map`）。
+- **workspace 锁与计划模式**：`mode.workspaceLock` 限制每个仓库同时只有一个 Tower 会话，
+  `mode.workspaceLockScope:"mutations"` 对只读工具跳过锁；`mode.planModePolicy` 控制进入 Tower
+  时如何处理活跃的 plan mode。
+- **可观察性**：成功的工具调用发出进程内 [Tower 事件](reference/events.md)；稳定
+  [工具错误码](reference/errors.md) 与 [blocker code](reference/blockers.md) 可被程序匹配。
+- **工具面**：本构建最多 28 个工具（含可选的 `tower_control` 与 `tower_reload`）；详见
+  [工具参考](reference/tools.md)。
+
+## 选择阅读路径
+
+| 你是 | 从这里开始 |
+|---|---|
+| 新用户 | [快速开始](guide/quickstart.md) → [工具参考](reference/tools.md) → [第一个 mission 示例（英文）](../examples/first-mission.md) |
+| 运维 | [运维 runbook（英文）](../operations/runbook.md) → [blocker 与失败码](reference/blockers.md) → [错误码](reference/errors.md) → [事件](reference/events.md) → [Doctor](reference/doctor.md) → [测试](reference/testing.md) → [批次/租约/旧版](reference/operations.md) → [安全模型](operations/security.md) |
+| 维护者 | [架构与状态机（英文）](../architecture/overview.md) → [配置参考](reference/config.md) → [热重载](guide/hot-reload.md) → [贡献指南](../../CONTRIBUTING.md) |
+
+参考页是当前发行版的权威说明；CI 中的 `npm run docs:check` 会校验文档与实现一致（包括中文页）。
+
+## 全部中文页面
+
+- [快速开始](guide/quickstart.md)
+- [安装、升级与迁移](guide/install-upgrade-migration.md)
+- [热重载（开发）](guide/hot-reload.md)
+- [工具参考](reference/tools.md)
+- [配置参考](reference/config.md)
+- [blocker 与失败码](reference/blockers.md)
+- [工具错误码](reference/errors.md)
+- [Tower 事件](reference/events.md)
+- [测试、发现与证据](reference/testing.md)
+- [批次、租约与旧版导入](reference/operations.md)
+- [Doctor](reference/doctor.md)
+- [FAQ](faq.md)
+- [安全模型](operations/security.md)
+
+以下页面目前只有英文版：[架构与状态机](../architecture/overview.md)、
+[运维 runbook](../operations/runbook.md)、[示例：第一个 mission](../examples/first-mission.md)。
+
+## 语言 / Language
+
+- [English docs](../README.md)
+- **中文文档**（本页）
+- [仓库主页 README（中文）](../../README.md) · [English README](../../README.en.md)

package/docs/zh/faq.md

@@ -0,0 +1,72 @@
+# FAQ
+
+[English](../faq.md) | **简体中文**
+
+**为什么 worker 刚完成，`tower_preflight` 就因 `no-review` 失败？**
+这是预期行为：`completed` 的 mission 正在等待审查。spawn 一个 reviewer；干净审查后门禁就会变绿。
+
+**需要轮询 worker 吗？**
+不需要。worker 的最终报告会送回本会话；`tower_roster` 显示实时活动。轮询只会浪费回合。
+
+**`/tower` 显示模式已开启，但没有 `tower_control`。**
+`mode.allowAgentControl` 关闭了。在 profile patch 中把它设为 `true` 并重启 DSH。
+
+**合并钩子要跑几分钟，`tower_merge` 失败了。**
+用更大的 `timeoutMs` 重试：`tower_merge({ missionId, timeoutMs: 1800000 })`。默认超时是 15 分钟，
+合并输出最多缓冲 64 MB。钩子失败返回 `merge-hook-failed`，并保持仓库干净以便重试。
+
+**合并提交已存在，但 Tower 说 mission 未合并。**
+再次调用 `tower_merge`。它会检测已落地的合并提交（`reconciled`），或恢复“命令失败但提交已存在”的
+情况（`recoveredFromFailure`）并记录。
+
+**`tower_rebase` 返回 `alreadyMerged` 且什么都没改。**
+正确：分支已经包含在基线中。此时调用 `tower_merge` 记录已落地的合并，而不是 rebase。
+
+**reviewer 能修改文件吗？**
+不能。reviewer 使用只读的 `tower-reviewer` preset（没有 write/edit/pwsh）；reviewer spawn 之后分支
+被改动，审查会被拒绝。mission 之外的问题用 `tower_finding` 记录，不要直接改文件。
+
+**`tower_finding` 与 `tower_findings` 有什么区别？**
+`tower_finding` 创建单条 finding（`open`）。`tower_findings` 是生命周期工具：列出/读取，并在
+`open → triaged → fixed`/`wontfix` 之间流转（允许重新打开）。只有控制塔或 worker 可以修改状态；
+roster 中的 reviewer 只能列出和读取。
+
+**如何只给一个仓库设置配置？**
+创建 `<git-common-dir>/dsh-tower/config.json`（普通检出通常是 `.git/dsh-tower/config.json`），
+使用与 profile 配置相同的 JSON 分组（`review`、`merge`、`worktrees`、`spawn`，以及兼容别名）。
+仓库配置层优先于 profile；单次工具参数又优先于两者。不需要重启，因为每次 Tower 工具打开仓库时都会
+读取该文件。
+
+**worker 能用 Tower 工具 merge 或 spawn 吗？**
+不能。worker preset 只包含 mission/进度工具；merge 与 spawn 属于上级控制塔。
+
+**worker 卡住或失控了，怎么停下它？**
+用 `tower_interrupt({to:"worker-m1",reason:"..."})`；它会调用宿主子代理中断，并把 roster 条目记录为
+`interrupted`。如果你已经中断过它并想要一个全新的 owner，用 `takeover:true` spawn。仍在运行的 worker
+不能被接管（`takeover-refused`）。
+
+**两个会话想驱动同一个仓库。**
+开启 `mode.workspaceLock:true`：第一个调用仓库级工具的 Tower 会话拥有
+`<git-common-dir>/dsh-tower/tower.lock`；其他会话会得到 `[tower:workspace-busy]`，直到 owner 执行
+`/tower off` 或锁过期（`mode.workspaceStaleMs`）。
+
+**能否不重启 DSH 就重载插件？**
+可以，在装有 DSH HMR 服务的 profile 中：`/tower reload` 或 `tower_reload` 工具会对账 profile 并替换
+变更的 linked 包。先运行一次 `npm run dev:hmr` 把仓库加入 profile 的 HMR 监视 root（然后重启 DSH
+一次）；见[热重载](guide/hot-reload.md)。`plugin_manager` 的安装/更新本身就会即时生效。
+
+**如何让完成证据成为强制要求？**
+worker 可以给 `tower_complete` 传 `checks`；设置 `gates.requireChecks:true` 后，没有 checks 的
+completed mission 会被阻止合并（`no-check-evidence`）。
+
+**Tower 把状态存在哪里？**
+目标仓库的 `<git-common-dir>/dsh-tower/state.json`、`activity.jsonl`，以及可供人阅读的
+`MISSIONS.md`；模式状态在 `$DSH_HOME/tower-mode/modes.json`。worktree 位于检出旁边的
+`.dsh-tower-worktrees/`。
+
+**如何修改审查轮数上限或 preset？**
+使用 `review.maxRoundsPerReviewer` 与 `spawn.workerPreset`/`spawn.reviewerPreset`；见
+[配置](reference/config.md)。修改 profile 配置后重启 DSH。
+
+**Tower 会把数据发到别处吗？**
+不会。它没有遥测，也没有网络服务；所有状态都在本地。