dsh-tower 2.0.3 → 2.1.0-beta.1

package/docs/reference/config.md

@@ -22,7 +22,7 @@ win, profile keys survive when the repo does not set them. `tower_status` report
 
 ```json
 {
-  "review": { "maxRoundsPerReviewer": 3 },
+  "review": { "requireReview": true, "maxRoundsPerReviewer": 3 },
   "merge": { "timeoutMs": 1800000 },
   "worktrees": { "root": "D:/tower-worktrees" },
   "spawn": { "reviewerPreset": "tower-reviewer", "maxDepth": 2 }
@@ -38,14 +38,16 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | 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`. |
+| `allowAgentControl` | `true` (alias of `mode.allowAgentControl`) | Legacy alias: register `tower_control` so the model may toggle the mode. |
 | `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/*`). |
+| `init.autoExclude` | `true` | Append in-repo artifacts (`MISSIONS.md`, in-repo worktree roots) to `.git/info/exclude`; never touches `.gitignore`. |
 | `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.allowAgentControl` | `true` | Register `tower_control`; the model may enter/leave with a reason. Set `false` for human-only mode control. |
 | `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.requireHumanAckOnFirstEntry` | `false` | Require a human `/tower ack` before the model may make the first Tower-mode entry in a session. |
 | `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. |
@@ -58,6 +60,7 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `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. |
+| `git.timeoutMs` | `15000` | Default timeout for Git commands other than merge; merge uses `merge.timeoutMs`. |
 | `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`. |
@@ -72,20 +75,21 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `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.admission` | `off` | `spawn` runs discovery before starting a worker, `complete` at `tower_complete`, `off` only on explicit `tower_test` (default; repository code is not executed automatically). |
 | `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. |
+| `gates.requireTests` | `false` | Require a passing discovery receipt for the current mission branch tip (`tests-missing`); independent of the review gate. |
+| `gates.allowReviewExemption` | `false` | With `review.requireReview:true`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant while the global review gate is off. |
 | `docs.board` | `true` | Write `MISSIONS.md` after mutations. |
 | `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`; `repo` = `<repoRoot>/MISSIONS.md`. |
+| `tools.exposeOperational` | `true` | Register batch/resource/import/legacy/recover/test/doctor tools; `false` shrinks the fixed tool-schema context. |
 | `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. |
+| `dev.reloadRequiredIds` | five Tower loader ids | Entry ids passed to `reconcileProfile` as required. |
 
 ## Example
 

package/docs/reference/errors.generated.md

@@ -0,0 +1,39 @@
+# Error code catalog (generated)
+
+> Generated by `npm run docs:generate:errors` from `domain/errors.js`. Do not edit by hand.
+
+| Code | Description |
+|---|---|
+| `invalid-argument` | A tool argument is missing, malformed, or not allowed. |
+| `repo-invalid` | repoRoot is missing, relative, or not inside a Git repository. |
+| `not-initialized` | Tower is not initialized for this repository; run tower_init. |
+| `mission-not-found` | No mission with that id exists. |
+| `finding-not-found` | No finding with that id exists. |
+| `invalid-transition` | The requested state transition is not allowed. |
+| `stale-base` | The repository state changed while the operation was being prepared; retry. |
+| `state-locked` | Another Tower writer holds the state lock. |
+| `state-corrupt` | The Tower state file is unreadable or invalid. |
+| `config-invalid` | Tower configuration is invalid. |
+| `config-unknown-key` | Tower configuration has an unknown top-level key. |
+| `git-failed` | A git command failed. |
+| `git-timeout` | A git command timed out or exceeded its output buffer. |
+| `worktree-dirty` | The mission worktree has uncommitted changes and cannot complete. |
+| `spawn-unavailable` | The subagents service is unavailable. |
+| `provider-missing` | No subagent provider is registered. |
+| `provider-cooldown` | The provider is throttled; spawn is in a short cooldown. |
+| `preset-missing` | The configured agent preset is not registered. |
+| `reviewer-prerequisite` | The reviewer spawn prerequisite is not met. |
+| `not-authorized` | The calling agent role may not perform this action. |
+| `workspace-busy` | Another Tower session owns this repository workspace lock. |
+| `worker-limit` | The repository reached spawn.maxLiveWorkers live workers. |
+| `rate-limited` | The tower_send per-minute rate limit was reached. |
+| `takeover-refused` | The mission already has a live worker that was not stopped first. |
+| `reload-unavailable` | The DSH HMR service is not available in this profile. |
+| `reload-failed` | The HMR reload failed; check the DSH log and restart if needed. |
+| `tests-failed` | Declared test discovery failed or did not meet its admission requirements. |
+| `tests-timeout` | Test discovery exceeded its time or output budget. |
+| `lease-busy` | Another holder owns the requested advisory lease. |
+| `lease-token` | The lease release token does not match the current holder. |
+| `batch-invalid` | The batch request or its close evidence is invalid. |
+| `legacy-invalid` | The legacy snapshot or mapping is invalid. |
+| `tool-internal` | An unexpected failure; read the message and the activity log. |

package/docs/reference/errors.md

@@ -1,14 +1,19 @@
 # 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:
+[blockers.md](blockers.md)). Every thrown error carries a stable code as a message prefix. This
+release defines 33 tool error codes.
+
+Every `TowerToolError` also carries `retryable` (boolean), `nextAction` (string or `null`) and `details`
+(structured context or `null`) for programmatic callers; the message prefix remains the stable contract
+for text-only clients.
 
 ```
 [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`.
+plain `Error` without a structured code is reported as `tool-internal`.
 
 | Code | Meaning | Typical trigger |
 |---|---|---|
@@ -18,6 +23,8 @@ message without a more specific match is reported as `tool-internal`.
 | `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. |
+| `stale-base` | The repository state changed while the operation was being prepared; retry. | two-phase mutation revalidation |
+| `worktree-dirty` | The mission worktree has uncommitted changes and cannot complete. | staged, modified, or untracked files left behind before `tower_complete` |
 | `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 |
@@ -26,6 +33,7 @@ message without a more specific match is reported as `tool-internal`.
 | `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 |
+| `provider-cooldown` | spawn is in a short cooldown after repeated retryable provider failures. | wait for `blockedUntil`, then retry |
 | `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 |

package/docs/reference/events.md

@@ -1,8 +1,8 @@
 # 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.
+other plugins can observe a repository without polling. This release emits 29 process-local events.
+Events are **not** sent over the network and carry no telemetry.
 
 ```js
 ctx.on('tower/merge', (payload) => {
@@ -32,14 +32,17 @@ ctx.on('tower/merge', (payload) => {
 | `tower/status` | `tower_status` read the dashboard |
 | `tower/preflight` | `tower_preflight` evaluated the gate |
 | `tower/doctor` | `tower_doctor` completed its read-only checks |
+| `tower/recover` | `tower_recover` inspected or cleared a stale state lock |
 | `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_mode` read/changed the session stance (`value.mode`, `allowAgentControl`, `deniedWhileActive`) |
+| `tower/control` | `tower_control` entered/left the mode (`value.mode`, actor/reason in `value`) |
+| `tower/reload` | `tower_reload` returned a reload schedule/result |
 
-`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.
+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/testing.md

@@ -50,7 +50,8 @@ 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`).
+  for the current mission branch tip (`tests-missing`). Review is independent of this gate: with
+  `review.requireReview:false` the tests gate still checks the branch tip.
 
 ## Trust boundary
 

package/docs/reference/tools.generated.md

@@ -0,0 +1,33 @@
+# Tools overview (generated)
+
+> Generated by `npm run docs:generate:tools` from the registered tool definitions. Do not edit by hand.
+
+| Tool | Description |
+|---|---|
+| `tower_adopt` | Reconcile the roster with the durable subagent catalog after a restart or new session. Agents that are provably gone are marked retired (records are kept) or missing (retireMissing:false, so the tower can inspect/take over); agents whose parent catalog cannot be read stay unknown and are never changed. Only the tower may adopt. |
+| `tower_batch` | Manage finite evidence batches: create freezes missionIds/requiredChecks/receiptPaths, status summarizes members, close verifies every required check and receipt hash, abandon retires a stale open batch. Membership and exclusions are immutable after create; close/abandon never remove missions. |
+| `tower_complete` | Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base, and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. Stores the full report; completion means ready for preflight and optional review, not merged. |
+| `tower_diff` | Read-only view of a mission branch for review: merge base, changed files, commits, and a capped patch against the recorded base. Safe for reviewers; it never modifies the repository. |
+| `tower_doctor` | Read-only environment and repository health check: git, state schema, config, presets/subagents/HMR, workspace lock, roster staleness, worktree ownership, test discovery, leases. Returns checks with pass/warn/fail and an environment contract. Never writes state. |
+| `tower_finding` | File a structured finding (bug / improve / vuln / idea) for the tower to route. Use this for anything notable OUTSIDE your mission scope instead of editing out-of-scope files. Severity is one of low|medium|high|critical. Use tower_findings to list, read, or close findings later. |
+| `tower_findings` | List, read, or update findings for a repository. Without id it lists findings newest-first with counts by status (filters: status, type, severity, missionId, open, limit). With id it returns that finding; with id plus status and/or note it records a lifecycle transition. Statuses are open -> triaged -> fixed|wontfix, and fixed/wontfix can be reopened to open. Only the tower or a worker may change a finding; reviewers may only list and read. Read-only when no id is given. |
+| `tower_import_legacy` | Read-only import of a Tower Codex (schemaVersion 1) or DSH legacy state file. Stores the full payload under <common>/dsh-tower/legacy/<sha256>.json and records only a summary in state.legacySnapshots; never activates, adopts, or resumes paused missions. |
+| `tower_inbox` | Read your tower inbox: messages addressed to you plus broadcasts, newest first. Only returned messages are acknowledged; the result reports unreadRemaining, so keep reading until it reaches 0. Set include_read for history. Unread messages block tower_complete. |
+| `tower_init` | Initialize Tower mission state for a repository (absolute repoRoot). Creates <git-common-dir>/dsh-tower/state.json and an activity log; idempotent on an existing workspace. Options: autoGitInit (git init + empty initial commit when the directory is not a repository), snapshotDirty (snapshot uncommitted work into a dangling commit used as the mission baseline), reanchor (change base when every mission is merged/abandoned). Only the tower may initialize. |
+| `tower_interrupt` | Interrupt one running tower roster agent (worker or reviewer) and record it as interrupted in the roster. Only the tower may interrupt. Idempotent: an agent that is not running returns interrupted:false. Use it before takeover after a runaway worker, or to stop work that is no longer wanted. |
+| `tower_legacy_map` | Audit-only mapping between a legacy snapshot id and a current mission. map records sourceHash/oldId/newMissionId; status lists mappings. Mapping never adopts or resumes a legacy mission. |
+| `tower_merge` | Merge a mission branch into the recorded base branch with --no-ff, after the hard gate passes. Verifies the two merge parents and records the mission as merged. If the merge commit already landed (manual merge, crashed or slow pre-merge hook), it detects the merge commit and records it as reconciled instead of merging again. A failed gate returns stable blocker codes without merging; a hook failure aborts cleanly and returns "merge-hook-failed" while a real content conflict returns "merge-conflict". |
+| `tower_mission` | Update one mission: lifecycle status, decision note, blocker, clear blockers, mark a task done, drop a task with a reason, or widen the scope (tower only). "merged" is never set here; only a future tower_merge records it. Merged and abandoned are terminal. |
+| `tower_plan` | Plan one or more missions in an initialized repository. Each mission has a printable-ASCII title, relative scope globs, optional task checklist, optional mission-id dependencies, and kind build|survey. Assigns M1.. ids and auto-adds a dependency when build scopes overlap (serializes merges); rejects dependency cycles. |
+| `tower_preflight` | Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, read-only-survey, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.requireReview is on. Never changes anything. |
+| `tower_rebase` | Rebase a mission branch onto the current base tip inside its own worktree. Refuses while its worker is running or the worktree is dirty. A clean conflict-free rebase waives re-review for the old review; a conflict is aborted and the mission is marked blocked. If the branch is already contained in the base, it returns alreadyMerged and leaves the branch untouched so tower_merge can record the landed merge. |
+| `tower_recover` | Read-only recovery diagnostics and an explicit stale-state-lock repair. status reports the state lock owner; clear-stale-lock requires confirm:"CLEAR_STALE_LOCK" and only moves a lock whose PID is provably dead to a backup file. It never resets Tower state or worktrees. |
+| `tower_reload` | Dev-only: ask DSH HMR to reconcile this profile and reload the Tower Host plugin from disk. The reload is scheduled a few milliseconds after this call returns (so the result reaches the model first). Use after editing the plugin source in a linked profile; plugin_manager install/update already triggers reconciliation by itself. Registered while dev.hotReload is on; fails with reload-unavailable when the HMR service is absent. |
+| `tower_resource` | Advisory resource leases per repository (coordination only; no OS CPU/memory hard cap). acquire/release require a token and are tower-only; status is read-only. Expired leases are never taken over silently. |
+| `tower_review` | Submit an independent review verdict for a completed mission, bound to the current branch tip. status is "clean", "p1-Nitems", or "p2-Nitems"; merge is "merge", "fix-then-merge", or "hold" (only clean + merge is later approval). Non-clean returns the mission to active. Reviewers are capped at 5 rounds per branch; a tower-submitted review is break-glass and requires breakGlassReason. |
+| `tower_roster` | List tower roster agents with authoritative live activity from the subagent catalog (running/inactive/missing/unknown). Read-only; never resumes children. Use before completion or merge decisions. |
+| `tower_send` | Send a durable inbox message to a tower participant: a roster agent name, "tower", or "all" (broadcast). The message is persisted first; when the recipient is a currently running roster agent the tower also steers it into that child's current turn. Returns delivery results. |
+| `tower_spawn` | Spawn a worker or reviewer for a mission. Workers use the tower-worker preset; reviewers require a completed mission and use the read-only tower-reviewer preset. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing, and starts a background subagent in that worktree. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns record the branch tip so a reviewer that modifies the branch cannot submit a review. Returns immediately unless wait=true. |
+| `tower_status` | Read the Tower dashboard for a repository: state path, base branch, revision, mission status counts, paged mission summaries (scope/deps/tasks/worktree/owner), roster size, findings, config path and the activity tail. Pass missionId for one full mission (tasks, notes, reviews, findings, completion report); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; format:"markdown" returns the human-readable mission board. Read-only. |
+| `tower_teardown` | Tear down eligible mission worktrees after their missions are merged or abandoned. A worktree whose roster agent is running is always kept (force cannot override); dirty worktrees need force; exclude keeps named missions. dry_run previews the remove/keep decisions without changing anything. |
+| `tower_test` | Run the mission worktree's declared tower.testDiscovery (package.json) and record the receipt. Returns ok:false with diagnostics when discovery fails; does not change mission status. Use tower_complete for automatic admission checks. |

package/docs/reference/tools.md

@@ -1,10 +1,10 @@
 # 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),
+The build exposes up to 29 tools: 19 core repository tools below (including `tower_interrupt`),
+`tower_mode`, `tower_control` (registered by default; set `mode.allowAgentControl:false` to disable),
 `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_recover`, `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`,
@@ -31,16 +31,16 @@ findings but not mutate them. Violations throw `[tower:not-authorized]` or
 | 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_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 non-empty reason; when the review gate is on, preflight also requires `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_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. Includes `mode` with `lastChange` and recent `history` when the host mode hook is available. |
 | `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_complete` | `missionId` (alias `id`), `report`, `checks?` | Worker reports completion (mission becomes `completed`, ready for preflight and optional 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. |
@@ -50,9 +50,10 @@ findings but not mutate them. Violations throw `[tower:not-authorized]` or
 | `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_control` | `action` (`enter`/`exit`), `reason` | Model-initiated mode change; registered by default; disable with `mode.allowAgentControl:false`; 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_recover` | `action` (`status`/`clear-stale-lock`), `confirm?` | Recovery diagnostics plus an explicit stale state-lock repair. `clear-stale-lock` requires `confirm:"CLEAR_STALE_LOCK"` and only moves a lock whose PID is provably dead to a backup; it never resets state/worktrees. |
 | `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`/`abandon`), `missionIds?`, `exclusions?`, `requiredChecks?`, `receiptPaths?`, `batchId?`, `checks?`, `treeTip?`, `receiptHashes?`, `reason?` | Finite evidence batch. Create freezes members/checks/receipts; close verifies every required check and receipt hash; merged members are eligible; abandon retires a stale open batch without deleting missions. Membership is immutable. |
 | `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. |

package/docs/zh/README.md

@@ -11,7 +11,7 @@
   workspace 锁、roster、worktree 归属、测试策略与租约，不写任何状态。
 - **测试发现与完成证据**：[测试、发现与证据](reference/testing.md)。仓库可在
   `package.json.tower.testDiscovery` 声明发现命令；回执可自动附加到 `tower_complete`，
-  `gates.requireTests` 可要求针对被审查 tip 的通过回执。
+  `gates.requireTests` 可要求针对当前 mission 分支 tip 的通过回执（与审查门禁独立）。
 - **证据批次、咨询式租约、旧版导入**：[批次、租约与旧版导入](reference/operations.md)
   （`tower_batch`、`tower_resource`、`tower_import_legacy`、`tower_legacy_map`）。
 - **workspace 锁与计划模式**：`mode.workspaceLock` 限制每个仓库同时只有一个 Tower 会话，
@@ -29,7 +29,7 @@
 | 新用户 | [什么时候用 Tower](guide/scenarios-and-philosophy.md) → [快速开始](guide/quickstart.md) → [工具参考](reference/tools.md) → [第一个 mission 示例（英文）](../examples/first-mission.md) |
 | 正在选择工作流 | [Tower 与 Agent Teams、Ralph、Workflow、普通并行子代理的区别](guide/scenarios-and-philosophy.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) |
+| 维护者 | [架构与状态机（英文）](../architecture/overview.md) → [配置参考](reference/config.md) → [热重载](guide/hot-reload.md) → [发布检查清单（英文）](../guide/release.md) → [看板查询（英文）](../board.md) → [贡献指南](../../CONTRIBUTING.md) |
 
 参考页是当前发行版的权威说明；CI 中的 `npm run docs:check` 会校验文档与实现一致（包括中文页）。
 
@@ -51,7 +51,8 @@
 - [安全模型](operations/security.md)
 
 以下页面目前只有英文版：[架构与状态机](../architecture/overview.md)、
-[运维 runbook](../operations/runbook.md)、[示例：第一个 mission](../examples/first-mission.md)。
+[运维 runbook](../operations/runbook.md)、[示例：第一个 mission](../examples/first-mission.md)、
+[发布检查清单](../guide/release.md)、[看板查询](../board.md)。
 
 ## 语言 / Language
 

package/docs/zh/faq.md

@@ -3,22 +3,25 @@
 [English](../faq.md) | **简体中文**
 
 **什么时候该用 Tower，而不是 Agent Teams、Ralph、Workflow 或普通子代理？**
-当输出是单个 Git 仓库中需要审查并合入的变更时，用 Tower。只读探索或快速独立子任务用普通子代理；
+当输出是单个 Git 仓库中需要集成的变更时，用 Tower（需要独立结论时再开启审查）。只读探索或快速独立子任务用普通子代理；
 横切的人类协作/设计决策用 Agent Teams；对同一目标反复新鲜尝试用 Ralph；程序化高扇出分析用 Workflow。
 完整选择路径、场景与对比表见[什么时候用 Tower](guide/scenarios-and-philosophy.md)。
 
 **可以同时把 Tower 和 Team/Workflow/Ralph 组合使用吗？**
 同一会话中不能并发：Tower 模式会拒绝这些工具并清除 plan mode。请按阶段组合——先用 Workflow/Team
-分析与决策，再启动 Tower 执行并审查仓库变更。详见[完整指南](guide/scenarios-and-philosophy.md#4-tower-与其他-dsh-工作流模式的区别)。
+分析与决策，再启动 Tower 执行（可选审查）仓库变更。详见[完整指南](guide/scenarios-and-philosophy.md#4-tower-与其他-dsh-工作流模式的区别)。
 
 **为什么 worker 刚完成，`tower_preflight` 就因 `no-review` 失败？**
-这是预期行为：`completed` 的 mission 正在等待审查。spawn 一个 reviewer；干净审查后门禁就会变绿。
+只有在 `review.requireReview:true` 开启时才会如此：已完成的 mission 在等待独立审查。spawn 一个
+reviewer；干净审查后门禁就会变绿。默认 `review.requireReview:false` 时审查可选，不会产生
+`no-review` blocker。
 
 **需要轮询 worker 吗？**
 不需要。worker 的最终报告会送回本会话；`tower_roster` 显示实时活动。轮询只会浪费回合。
 
 **`/tower` 显示模式已开启，但没有 `tower_control`。**
-`mode.allowAgentControl` 关闭了。在 profile patch 中把它设为 `true` 并重启 DSH。
+`mode.allowAgentControl` 被关闭了。它默认为 `true`；如果被显式设为 `false`，在 profile patch 中改回
+`true` 并重启 DSH。
 
 **合并钩子要跑几分钟，`tower_merge` 失败了。**
 用更大的 `timeoutMs` 重试：`tower_merge({ missionId, timeoutMs: 1800000 })`。默认超时是 15 分钟，
@@ -33,8 +36,8 @@
 
 **可以要求强制独立审查吗？**
 可以。在 profile 或仓库配置中设 `review.requireReview:true` 可开启全局审查门禁（默认 `false`，
-即审查可选）。开启后可用 mission 级 `reviewPolicy:"none"` + 理由做更窄的豁免。`tower_review`
-始终可用并记录结论。
+即审查可选）。开启后可用 mission 级 `reviewPolicy:"none"` + 理由 + `gates.allowReviewExemption:true`
+做更窄的豁免。`tower_review` 始终可用并记录结论。
 
 **reviewer 能修改文件吗？**
 不能。reviewer 使用只读的 `tower-reviewer` preset（没有 write/edit/pwsh）；reviewer spawn 之后分支

package/docs/zh/guide/hot-reload.md

@@ -97,7 +97,7 @@ Windows 上通常是 `C:\Users\<you>\.dsh`）：
 |---|---|
 | `dev.hotReload` | 注册 `tower_reload`；关闭时 `/tower reload` 也被禁用（默认 `true`）。无 HMR 服务时工具仍注册，以便返回 `reload-unavailable`。 |
 | `dev.reloadDelayMs` | 计划中的对账运行前的延迟，单位毫秒（默认 `50`），让工具/命令结果先送达模型，再替换插件。 |
-| `dev.reloadRequiredIds` | profile 必须保持活跃的 Loader 条目 id（默认 `tower`、`tower-skills`、`preset-tower-worker`、`preset-tower-reviewer`）。即使某个 required 条目早已处于非活跃状态，也会被报告为重载失败。 |
+| `dev.reloadRequiredIds` | profile 必须保持活跃的 Loader 条目 id（默认 `tower-bundle`、`tower`、`tower-skills`、`preset-tower-worker`、`preset-tower-reviewer`）。即使某个 required 条目早已处于非活跃状态，也会被报告为重载失败。 |
 
 重载是**调度而非等待**：`/tower reload` 与 `tower_reload` 立即返回 `scheduled`、`delayMs`、
 `requiredIds`（以及存在待处理错误时的 `lastError`），随后 HMR 在延迟后对账 profile。这是有意为之——

package/docs/zh/guide/install-upgrade-migration.md

@@ -4,7 +4,7 @@
 
 ## 环境要求
 
-- DSH `0.2.1-rc.2` 或更新版本
+- DSH `0.2.1-rc.2`；每个版本实际验证过的 host 构建见 [COMPATIBILITY.md](../../../COMPATIBILITY.md)
 - Node.js 22+
 - Git（本地 worktree；不需要网络访问）
 
@@ -31,12 +31,24 @@ Host 插件在 DSH 启动时加载：**安装或更新后需要重启 DSH**。
 
 ## 迁移说明
 
-- **1.x → 2.0（未发布）**：不需要迁移状态（`schemaVersion` 保持 1；新字段都是可选的）。需要留意的
+- **2.0.4 → 2.1.0-beta.1**：不需要迁移 state/config。这是发布到 `next` dist-tag 的**预发布**，
+  `latest` 仍指向 2.0.4——请用 `dsh plugin --profile web add dsh-tower@next`（或精确版本号）安装。
+  运行时行为未变；本版本承载的是交付闸门（CI 中的 mount smoke、`npm run release:check`、证据约定
+  与追踪策略），而不是工具变化。本文档先于人工发布步骤合入：只有在[发布清单](release.md)执行
+  `npm publish --tag next` 之后，`next` 才会解析到 2.1.0-beta.1；`latest` 在稳定版发布前保持 2.0.4。
+- **2.0.3 → 2.0.4**：不需要迁移 state/config。本版本是安全加固与完整性修复（授权、merge SHA 绑定、
+  dirty worktree 完成拒绝、stale lock 恢复、限制 test/git 进程环境、`tower_recover`、UI 0.2.2）。
+  升级后请按威胁模型重新检查 `review.requireReview`、`tests.admission` 与 worker 工具权限。
+- **2.0.1 → 2.0.3**：不需要迁移状态。2.0.3 起独立审查**默认可选**（`review.requireReview:false`）；
+  若要保留旧的审查门禁行为，请显式设为 `true`。2.0.1 为 `tower_batch` 增加 `abandon`、允许 merged
+  成员 close、让 doctor 跳过已 teardown 的 worktree，并修复终态 mission spawn/preflight 边界。
+  可选 `ui-bundle` 0.2.1 增加常驻 Tower 模式 chip 与模式感知的 disabled 工具行。
+- **1.x → 2.0（已发布）**：不需要迁移状态（`schemaVersion` 保持 1；新字段都是可选的）。需要留意的
   行为变化：Tower 模式激活期间，`mode.denyTools` 现在还会拒绝 `workflow`、`ralph`、`subagent`、
   `subagent_fork`、`wait_agent` 与 `team_task_list`（可用显式列表覆盖）；`spawn.maxLiveWorkers`
-  默认为 4；`mode.workspaceLock` 默认关闭。worker 不能再直接完成/放弃/扩大 mission 的 scope——
-  请使用 `tower_complete`。新工具：`tower_interrupt`，以及 HMR 可用时的 `tower_reload`。升级后重启
-  一次 DSH；见[热重载](hot-reload.md)。
+  默认为 4；`mode.workspaceLock` 代码默认关闭、随包 patch 开启。worker 不能再直接完成/放弃/扩大
+  mission 的 scope——请使用 `tower_complete`。新工具：`tower_interrupt`，以及 HMR 可用时的
+  `tower_reload`。升级后重启一次 DSH；见[热重载](hot-reload.md)。
 - **1.3 → 1.4**：不需要迁移状态。新增：仓库级配置（`<git-common-dir>/dsh-tower/config.json`）、
   稳定的 `[tower:<code>]` 工具错误、`tower_findings`，以及 `id`/`missionId` 与 snake/camel 输入
   别名。既有调用保持可用；重启 DSH 以加载新工具面（`tower_findings` 与更新的 output schema）。

package/docs/zh/guide/quickstart.md

@@ -32,14 +32,17 @@ tower_spawn repoRoot=D:\work\repo missionId=M1 role=worker
 调用立即返回子代理 id。worker 在 mission worktree 内工作、提交、把任务标记完成，并调用
 `tower_complete`；它的最终报告会送回本会话。用 `tower_roster` 观察活动，不要循环轮询。
 
-## 4. 审查
+## 4. 可选：审查
+
+独立审查默认可选。若要采用严格流程，先在 profile 或仓库配置中开启
+`review.requireReview:true`，然后：
 
 ```
 tower_spawn repoRoot=D:\work\repo missionId=M1 role=reviewer
 ```
 
-reviewer 使用只读的 `tower-reviewer` preset。它查看 `tower_diff` 并提交 `tower_review`。只有
-`clean` + `merge` 的结论才允许合并。
+reviewer 使用只读的 `tower-reviewer` preset，查看 `tower_diff` 并提交 `tower_review`。开启
+`review.requireReview:true` 后，只有 `clean` + `merge` 的结论才允许合并。
 
 ## 5. 门禁、合并与清理
 
@@ -49,8 +52,9 @@ tower_merge     repoRoot=D:\work\repo missionId=M1
 tower_teardown  repoRoot=D:\work\repo
 ```
 
-审查前运行 `tower_preflight` 预期报告 `no-review`；干净审查之后应为 `ok:true`。存在 blocker 时
-`tower_merge` 拒绝合并。`tower_teardown` 移除已 merged/abandoned 的 worktree 与分支。
+开启审查门禁时，审查前运行 `tower_preflight` 会报告 `no-review`；干净审查之后应为 `ok:true`。
+默认 `review.requireReview:false` 时没有审查 blocker。存在其他 blocker 时 `tower_merge` 拒绝合并。
+`tower_teardown` 移除已 merged/abandoned 的 worktree 与分支。
 
 ```
 /tower off
@@ -59,8 +63,9 @@ tower_teardown  repoRoot=D:\work\repo
 ## 如果失败
 
 阅读 blocker code 并查阅 [blocker 参考](../reference/blockers.md)。最常见的情况：`stale-base`
-（执行 `tower_rebase`）、`no-review`（spawn reviewer）、`merge-hook-failed`（重试，或调大
-`timeoutMs`）、`tip-moved`（审查后分支已变化，需要重新审查）。
+（执行 `tower_rebase`）、`no-review`（仅在 `review.requireReview:true` 时；spawn reviewer）、
+`merge-hook-failed`（重试，或调大 `timeoutMs`）、`tip-moved`（仅在审查门禁开启时；审查后分支
+已变化，需要重新审查）。
 
 工具抛出的错误带 `[tower:<code>]` 前缀；见[错误码](../reference/errors.md)（例如
 `preset-missing` 表示安装 bundle 后需要重启 DSH，`not-initialized` 表示先运行 `tower_init`）。
@@ -72,7 +77,7 @@ tower_teardown  repoRoot=D:\work\repo
 
 ```json
 {
-  "review": { "maxRoundsPerReviewer": 3 },
+  "review": { "requireReview": true, "maxRoundsPerReviewer": 3 },
   "merge": { "timeoutMs": 1800000 },
   "worktrees": { "root": "D:/tower-worktrees" }
 }