dsh-tower 2.1.0 → 2.4.0

package/docs/reference/errors.md

@@ -4,54 +4,66 @@ Tool failures are thrown errors, not `{ok:false}` results (gate outcomes are the
 [blockers.md](blockers.md)). Every thrown error carries a stable code as a message prefix. This
 release defines 35 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.
+Every `TowerToolError` carries `retryable` (boolean), `nextAction` (string or `null`) and `details`
+(structured context or `null`) for programmatic callers. The model-visible surface is the message:
+when the catalog supplies a recovery step, exactly one trailing ` — next: …` segment is rendered;
+when the code is also retryable, that same segment ends with ` (retryable)`. Codes without a
+`nextAction` keep the historical `[tower:<code>] <message>` form byte-for-byte, and a message that
+already contains its action is not suffixed twice. The table below is generated from
+`domain/errors.js`, the same catalog the runtime uses.
 
 ```
-[tower:mission-not-found] unknown mission "M9"
+[tower:mission-not-found] unknown mission "M9" — next: list missions with tower_status
 ```
 
 Callers can match the prefix instead of the prose. Codes are reserved for the conditions below; a
 plain `Error` without a structured code 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. |
-| `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`; invalid JSON; no usable `schemaVersion` |
-| `state-version-unsupported` | The state file's schema version is newer than this build supports, or cannot be migrated. | opening a repository written by a newer plugin; an unknown older version; this build refuses to downgrade |
-| `state-migration-failed` | A state migration threw; the original file was not modified. | a bug in a migration step; see the pre-migration `state.json.v<N>.bak` |
-| `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 |
-| `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 |
-| `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 |
+<!-- generated:error-table:start -->
+| Code | Meaning | Retryable | Next action | Typical trigger |
+|---|---|---|---|---|
+| `invalid-argument` | A tool argument is missing, malformed, or not allowed. | no | — | `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. | no | pass an absolute path to a directory inside a Git repository | passing a path in a directory that is not a repo |
+| `not-initialized` | Tower is not initialized for this repository; run tower_init. | no | run tower_init for this repository | a read tool before `tower_init` |
+| `mission-not-found` | No mission with that id exists. | no | list missions with tower_status | a stale or mistyped `M9` |
+| `finding-not-found` | No finding with that id exists. | no | list findings with tower_findings | `tower_findings({id:"F99"})` |
+| `invalid-transition` | The requested state transition is not allowed. | no | — | 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. | yes | retry the tool; if it keeps failing, run tower_preflight and inspect tower_status | two-phase mutation revalidation |
+| `state-locked` | Another Tower writer holds the state lock. | yes | wait for the other Tower writer to finish, then retry | concurrent mutation after the lock timeout |
+| `state-corrupt` | The Tower state file is unreadable or invalid. | no | restore state.json from a backup, or re-initialize after filing the corruption | hand-edited `state.json`; invalid JSON; no usable `schemaVersion` |
+| `state-version-unsupported` | The Tower state file uses a schema version this build cannot read or downgrade. | no | upgrade dsh-tower to a release that supports this state schemaVersion | opening a repository written by a newer plugin; an unknown older version; this build refuses to downgrade |
+| `state-migration-failed` | A Tower state migration failed; the original state file was not modified. | no | restore the pre-migration backup state.json.v<N>.bak and report the migration bug | a bug in a migration step; see the pre-migration `state.json.v<N>.bak` |
+| `config-invalid` | Tower configuration is invalid. | no | fix the repository config file, then retry | malformed repo `config.json`, a value that violates the schema |
+| `config-unknown-key` | Tower configuration has an unknown top-level key. | no | remove the unknown key from the repository config file, then retry | a typo such as `allowAgentToggle` |
+| `git-failed` | A git command failed. | no | — | a rejected merge command, invalid ref |
+| `git-timeout` | A git command timed out or exceeded its output buffer. | yes | retry; if it persists, raise git.timeoutMs or merge.timeoutMs | slow pre-merge hook, huge diff |
+| `worktree-dirty` | The mission worktree has uncommitted changes and cannot complete. | no | commit or remove the worktree changes, then retry tower_complete | staged, modified, or untracked files left behind before `tower_complete` |
+| `spawn-unavailable` | The subagents service is unavailable. | no | enable the DSH subagents service, then retry | a Host without `subagents` |
+| `provider-missing` | No subagent provider is registered. | no | register a subagent provider in the DSH profile, then retry | an empty provider list |
+| `provider-cooldown` | The provider is throttled; spawn is in a short cooldown. | yes | wait for the cooldown to expire, then retry | repeated retryable provider failures; wait for `blockedUntil` |
+| `preset-missing` | The configured agent preset is not registered. | no | install the tower-worker and tower-reviewer agent presets and restart DSH | missing `tower-worker`/`tower-reviewer` preset rows, DSH not restarted |
+| `reviewer-prerequisite` | The reviewer spawn prerequisite is not met. | no | complete the mission first, then spawn the reviewer | reviewer spawned before the mission is `completed`, or before a worktree exists |
+| `not-authorized` | The calling agent role may not perform this action. | no | call the tool as the tower, or as the worker/reviewer it is assigned to | a worker calling a tower-only tool or changing mission status/scope; a reviewer mutating findings |
+| `workspace-busy` | Another Tower session owns this repository workspace lock. | yes | run /tower off in the other session or wait for its lock to become stale | `mode.workspaceLock:true` and a second session calls a repo-scoped tool |
+| `worker-limit` | The repository reached spawn.maxLiveWorkers live workers. | no | wait for a live worker to finish or raise spawn.maxLiveWorkers | spawning a fifth worker with the default limit |
+| `rate-limited` | The tower_send per-minute rate limit was reached. | yes | wait for the next per-minute window or raise send.maxPerMinute | `send.maxPerMinute` exceeded |
+| `takeover-refused` | The mission already has a live worker that was not stopped first. | no | run tower_interrupt for the live worker, then retry the takeover | `tower_spawn({takeover:true})` before `tower_interrupt` |
+| `reload-unavailable` | The DSH HMR service is not available in this profile. | no | restart DSH instead of reloading | `tower_reload` / `/tower reload` on a profile without HMR |
+| `reload-failed` | The HMR reload failed; check the DSH log and restart if needed. | no | check the DSH log and restart DSH | `reconcileProfile` threw |
+| `tests-failed` | Declared test discovery failed or did not meet its admission requirements. | no | fix the failing tests, then retry tower_complete | nonzero command, malformed output, minCount/required shortfall |
+| `tests-timeout` | Test discovery exceeded its time or output budget. | no | raise tests.timeoutMs or tests.maxBytes (or speed up the suite), then retry | `tests.timeoutMs`, or stdout over `tests.maxBytes` |
+| `lease-busy` | Another holder owns the requested advisory lease. | no | release the lease or wait for it to expire, then retry | `tower_resource acquire` while `heavy-ci` is held |
+| `lease-token` | The lease release token does not match the current holder. | no | use the token returned when the lease was acquired | releasing with another session's token |
+| `batch-invalid` | The batch request or its close evidence is invalid. | no | fix the batch request or the receipt hashes, then retry | unknown member, duplicate id, unsafe receipt path, missing receipt hash |
+| `legacy-invalid` | The legacy snapshot or mapping is invalid. | no | check the legacy snapshot path, schema and mapping, then retry | unknown schema, source inside the Tower state dir, mapping rewrite |
+| `tool-internal` | An unexpected failure; read the message and the activity log. | no | — | a bug; read the message and the activity log |
+<!-- generated:error-table:end -->
+
+A git-mutex timeout is a `state-locked` error that names the holder. Its `details` is
+`{ holderPid, holderPhase, heldMs, waitedMs }`, and the message renders the same facts as
+`held by pid 1234 (merge) for 92 s; waited 60 s`. `holderPhase` is the operation that holds the lock
+(`merge`, `rebase`, `init`, `teardown`, `provision`); `tower_status` and `tower_doctor` expose the same
+holder as `gitLock: { held, pid, phase, heldMs }` while it is held.
 
 ## Why thrown?
 

package/docs/reference/events.md

@@ -1,15 +1,42 @@
 # Tower events
 
+> Generated by `npm run docs:generate:events` from `domain/events.js`. Do not edit by hand.
+
 Tower emits process-local Cordis events after successful tool calls (mutations and read-only tools), so
-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.
+other plugins can observe a repository without polling. This release defines 34 process-local events:
+5 stable domain events and 29 deprecated tool-shaped
+aliases. Events are **not** sent over the network and carry no telemetry.
+
+## Domain events (stable)
+
+Domain events describe what changed, not which tool ran. They are emitted only after the state write
+succeeds, so `revision` is the revision a reader can load back from `state.json`; a failed tool emits
+no domain event. `at` is the transition timestamp in epoch milliseconds. `state.json` stays
+authoritative: these events are an observation channel, not an event-sourced log, and are never
+replayed.
+
+| Event | Payload | Emitted after |
+|---|---|---|
+| `tower.mission.planned` | `{ missionId, revision, at }` | tower_plan persisted one or more new missions |
+| `tower.mission.completed` | `{ missionId, revision, at }` | tower_complete recorded a completion report (or tower_mission set status "completed") |
+| `tower.mission.reviewed` | `{ missionId, revision, at }` | tower_review recorded a verdict for the mission branch |
+| `tower.mission.merged` | `{ missionId, revision, at, commit }` | tower_merge recorded the merge commit that landed the mission branch |
+| `tower.mission.abandoned` | `{ missionId, revision, at }` | a mission transitioned to "abandoned" |
 
 ```js
-ctx.on('tower/merge', (payload) => {
-  // payload.tool, payload.repoRoot, payload.value (the tool's JSON result)
+ctx.on('tower.mission.merged', ({ missionId, revision, at, commit }) => {
+  // the merge is already durable; commit is the merge commit that landed
 })
 ```
 
+## Tool-shaped aliases (deprecated)
+
+The older `tower/<tool>` events are kept for one minor release as a **deprecated** alias for the
+tool-shaped observation channel; prefer the domain events above and expect the alias to be removed in
+the next minor. They carry `{ tool, repoRoot, value }`, fire after a successful tool call, and never
+fail a tool when a listener throws. For `tower_merge` the alias also fires for a gate failure whose
+`value.ok` is false.
+
 | Event | Emitted after |
 |---|---|
 | `tower/init` | `tower_init` created or re-anchored state |
@@ -38,11 +65,16 @@ ctx.on('tower/merge', (payload) => {
 | `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/mode` | `tower_mode` read 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 |
 
-Payloads are JSON: `{tool, repoRoot, value}`. Listener exceptions never affect the tool result.
+```js
+ctx.on('tower/merge', (payload) => {
+  // deprecated: prefer tower.mission.merged
+  // payload.tool, payload.repoRoot, payload.value (the tool's JSON 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/surface-budget.md

@@ -0,0 +1,157 @@
+# Surface budget
+
+The plugin measures its user-facing surface in four numbers: **config leaf keys**,
+**config sections**, **registered tools**, and **visible component rows**. The
+committed baseline is [`scripts/surface-baseline.json`](../../scripts/surface-baseline.json);
+the brakes are `npm run surface:check` for the first three and
+`npm run docs:check:components` for the component count; the decision records are
+[ADR 0004](../adr/0004-surface-budget.md) and
+[ADR 0005](../adr/0005-component-surface.md).
+
+Decision date: 2026-10-23
+
+Every key and tool is classified here so "why is this here" has an answer that a
+check can read. `core` is a behavioural or safety contract, `tuning` is a safe
+default a user may want to change, and `niche` was added for one workflow and
+must carry a removal note for the next minor. A live key or tool missing from
+these tables fails `npm run surface:check`.
+
+A second axis asks who may turn a key off. It is generated from
+[`scripts/component-surface.json`](../../scripts/component-surface.json) into
+[component-surface.md](component-surface.md): every key is `core`,
+`optional-component`, `optional-config` or `forbidden-to-disable`, and the
+component count is the fourth baselined surface, two-way: a contraction needs a
+dated decision just like growth does (`npm run docs:check:components`,
+[ADR 0005](../adr/0005-component-surface.md)). The same source of truth records
+the `gateableTools` allowlist; it is empty since #122, so a future
+`tools.expose*` route to any tool is refused before it can remove a review,
+merge or host tool.
+
+The 2.3.0 baseline counted 27 tools because it recorded only the `define()` path.
+`tower_mode` and `tower_control` are registered directly by `index.js`, so the
+shipped surface was always 29. The 27 → 29 step is an explicit
+*measurement correction* with a reason and date in
+[`scripts/surface-baseline.json`](../../scripts/surface-baseline.json) (see
+[ADR 0004](../adr/0004-surface-budget.md)), not surface growth; a later count
+change still needs an ADR or a provably matching deletion.
+
+The tool count is the **build** surface, not one profile's mounted subset (#121):
+the recorder includes every tool this build can register, so a component row that
+ships off (`tower-hmr`, whose `tower_reload` keeps the count at 29) does not
+shrink the budget. `tower_doctor` reports the same 29 and names the mounted
+subset through its `components` check; the mount smoke asserts the shipped
+profile's 28 loaded tools and pins 29 for the all-rows-on surface.
+
+#121 also shrank the config surface: the seven capability `tools.expose*` keys
+and `dev.hotReload` became component rows, so config keys went 64 → 56 and
+sections 15 → 14. Those are recorded shrank values in the committed baseline,
+not free growth: a later increase still needs its own decision.
+
+## Config keys
+
+| Key | Class | Note |
+|---|---|---|
+| `section` | core | Legacy alias for `mode.promptSection`; changes the Tower-mode prompt contract. |
+| `allowAgentControl` | core | Legacy alias for `mode.allowAgentControl`; decides whether the model may toggle the mode. |
+| `init.autoGitInit` | tuning | Repository bootstrap convenience; safe default is off. |
+| `init.snapshotDirty` | tuning | Baseline snapshot convenience; tracks dirty state explicitly. |
+| `init.autoExclude` | tuning | Keeps generated artifacts out of user dirt without touching `.gitignore`. |
+| `mode.promptSection` | core | Replaces the whole Tower-mode prompt text. |
+| `mode.sectionAppend` | tuning | Appends team conventions to the prompt. |
+| `mode.allowAgentControl` | core | The human-owned-mode toggle described by ADR 0003. |
+| `mode.autoPauseGoal` | core | Entering the mode pauses an active goal; exit never resumes it. |
+| `mode.requireResumeAuthorization` | core | Guards resuming a user-paused mission. |
+| `mode.requireHumanAckOnFirstEntry` | core | First entry can require an explicit human ack. |
+| `mode.workspaceLock` | core | One Tower session per repository is a safety contract. |
+| `mode.workspaceLockScope` | tuning | Chooses whether read-only tools skip the workspace lock. |
+| `mode.planModePolicy` | core | Entering Tower mode either clears plan mode or refuses. |
+| `mode.workspaceStaleMs` | tuning | Stale window for the advisory workspace lock. |
+| `mode.heartbeatMs` | tuning | Heartbeat interval while the mode is on. |
+| `mode.denyTools` | core | The denied-tool list is part of the mode guard. |
+| `mode.storePath` | niche | Custom mode-store location added for one deployment workflow. Removal note: derive the path from `$DSH_HOME` in the next minor; no in-tree caller sets this key. |
+| `mode.maxEntries` | tuning | Bounds the persisted mode store. |
+| `mode.lockTimeoutMs` | tuning | Bounded wait for the cross-process mode lock. |
+| `review.requireReview` | core | Turns the review gate into a merge blocker. |
+| `review.maxRoundsPerReviewer` | core | Caps review rounds; changes the review lifecycle. |
+| `merge.timeoutMs` | tuning | Default merge timeout; a per-call value wins. |
+| `merge.maxBufferBytes` | tuning | Captured merge output buffer. |
+| `git.timeoutMs` | tuning | Default Git command timeout outside merge. |
+| `worktrees.root` | tuning | Default worktree placement. |
+| `spawn.workerPreset` | core | Chooses the tool surface a worker receives. |
+| `spawn.reviewerPreset` | core | Chooses the read-only reviewer surface. |
+| `spawn.maxDepth` | tuning | Subagent depth requested at spawn. |
+| `spawn.provider` | tuning | Provider route for spawned agents. |
+| `spawn.workerModel` | tuning | Optional model route for workers. |
+| `spawn.reviewerModel` | tuning | Optional independent model route for reviewers. |
+| `spawn.maxLiveWorkers` | core | Resource-safety cap on live workers. |
+| `spawn.staleMs` | tuning | Roster staleness window before merge is blocked. |
+| `spawn.maxWaitMs` | tuning | Upper bound for a blocking spawn wait. |
+| `spawn.requireLease` | niche | Advisory-lease gate added for one multi-agent workflow. Removal note: fold into `tower_resource` policy in the next minor unless a second workflow uses it. |
+| `send.maxPerMinute` | tuning | Message rate limit; zero disables it. |
+| `send.interruptDefault` | tuning | Default for the interrupt-before-deliver flag. |
+| `tests.enabled` | core | Whether declared discovery may run at all. |
+| `tests.admission` | core | Chooses when repository code is executed. |
+| `tests.timeoutMs` | tuning | Per-command discovery timeout. |
+| `tests.maxBytes` | tuning | Captured discovery output cap. |
+| `tests.autoChecks` | tuning | Attaches a tests check to completion. |
+| `tests.allowPackageDiscovery` | core | Allows repository code to execute; a security contract. |
+| `gates.requireChecks` | core | Requires completion evidence before merge. |
+| `gates.requireTests` | core | Requires a test receipt before merge. |
+| `gates.allowReviewExemption` | core | Allows a review exemption and its reason. |
+| `gates.maxReportBytes` | tuning | Report size cap; the refusal itself is not configurable. |
+| `docs.board` | tuning | Writes the human-readable board. |
+| `docs.boardLocation` | tuning | Chooses the board location. |
+| `archive.enabled` | core | Controls whether terminal missions leave the hot state. |
+| `archive.afterDays` | tuning | Archive age threshold. |
+| `archive.maxMissions` | tuning | Hot terminal-mission cap. |
+| `leases.ttlMs` | tuning | Default advisory lease lifetime. |
+| `dev.reloadDelayMs` | tuning | Delay so a tool result is delivered before reload. |
+| `dev.reloadRequiredIds` | niche | Loader ids added for one linked-profile development setup. Removal note: derive the required ids from the bundle manifest in the next minor. |
+
+## Tools
+
+Tools are `core` when the product does not work without them and `optional` when
+a component row (`tower-batch`, `tower-import`, `tower-leases`, `tower-tests`,
+`tower-hmr`), `mode.allowAgentControl`, or the dev mode can legitimately remove
+them from the surface. `tower_doctor` and `tower_recover` are core: #122 made
+them mandatory for every configuration.
+
+| Tool | Class | Note |
+|---|---|---|
+| `tower_adopt` | core | Reconciles a restored roster with the durable catalog. |
+| `tower_batch` | optional | Evidence-batch workflow; component `tower-batch`. |
+| `tower_complete` | core | The only completion path for a worker. |
+| `tower_control` | optional | Model-initiated mode change; `mode.allowAgentControl:false` removes it (ADR 0003). |
+| `tower_diff` | core | The read-only review view. |
+| `tower_doctor` | core | Read-only health contract; registered for every configuration (#122). |
+| `tower_finding` | core | Out-of-scope issue recording. |
+| `tower_findings` | core | Finding lifecycle. |
+| `tower_import_legacy` | optional | Legacy migration; component `tower-import`. |
+| `tower_inbox` | core | Message delivery and acknowledgement. |
+| `tower_init` | core | Creates the repository state. |
+| `tower_interrupt` | core | Stops a runaway worker. |
+| `tower_legacy_map` | optional | Legacy audit mapping; component `tower-import`. |
+| `tower_merge` | core | The only merge path. |
+| `tower_mission` | core | Mission progress and blockers. |
+| `tower_mode` | core | Reports the session stance, workspace lock, HMR and plugin version; always registered. |
+| `tower_plan` | core | Mission planning. |
+| `tower_preflight` | core | The read-only merge gate. |
+| `tower_rebase` | core | Keeps a mission branch current. |
+| `tower_recover` | core | Stale-lock recovery; registered for every configuration (#122). |
+| `tower_reload` | optional | Dev-only reload; component `tower-hmr` (shipped off). |
+| `tower_resource` | optional | Advisory leases; component `tower-leases`. |
+| `tower_review` | core | Independent review verdicts. |
+| `tower_roster` | core | Roster and live activity. |
+| `tower_send` | core | Durable messages to agents. |
+| `tower_spawn` | core | Starts workers and reviewers. |
+| `tower_status` | core | The dashboard. |
+| `tower_teardown` | core | Worktree cleanup and archiving. |
+| `tower_test` | optional | Explicit discovery; component `tower-tests`. |
+
+## Non-goals
+
+This is a measurement and a brake, not a cleanup epic. The numbers report the
+surface; they do not decide which key is bad.
+
+Enforced by: `scripts/surface-baseline.mjs` and `domain/surface.js`; tests in
+`tests/surface.test.mjs`; gate: `npm run surface:check`.

package/docs/reference/tools.generated.md

@@ -1,14 +1,16 @@
 # Tools overview (generated)
 
 > Generated by `npm run docs:generate:tools` from the registered tool definitions. Do not edit by hand.
+> Surface: config keys: 56 · sections: 14 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; 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, capped at gates.maxReportBytes (default 32768 UTF-8 bytes); a larger report is rejected with invalid-argument and an actionable nextAction, never truncated. Persists reportBytes on the stored report. completion means ready for preflight and optional review, not merged. |
+| `tower_control` | Enter or leave Tower mode for the calling agent. Allowed only when the deployment enables allowAgentControl; use it when the user intent or task state clearly calls for Tower orchestration or a return to normal collaboration, and always state a concrete reason. |
 | `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, case-sensitivity detection (caseInsensitive and the active scope comparison mode), config, presets/subagents/HMR, workspace lock, roster staleness, worktree ownership, test discovery, leases, and the terminal-mission archive (count, bytes, years, unreadable diagnostics and the configured afterDays/maxMissions policy). Returns checks with pass/warn/fail and an environment contract. Never writes state and never probes the filesystem. |
+| `tower_doctor` | Read-only environment and repository health check: the concept-budget surface (config keys/sections/tools), git, state schema, case-sensitivity detection (caseInsensitive and the active scope comparison mode), config, presets/subagents/HMR, the state lock age/heartbeat freshness, the repo-scoped git lock holder (gitLock: {held,pid,phase,heldMs}), workspace lock, roster staleness, worktree ownership, test discovery, leases, and the terminal-mission archive (count, bytes, years, unreadable diagnostics and the configured afterDays/maxMissions policy). Returns checks with pass/warn/fail, state-lock and git-lock reports and an environment contract. Never writes state and never probes the filesystem. |
 | `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. |
@@ -18,16 +20,17 @@
 | `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_mode` | Report whether Tower mode is active for the calling agent, who changed it last, whether the model may toggle it, any goal paused on entry, the workspace lock, HMR availability and the plugin version. |
 | `tower_plan` | Plan one or more missions in an initialized repository. Each mission has a printable-Unicode title (NFC-normalized, at most 120 characters), 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_recover` | Read-only recovery diagnostics and an explicit stale-state-lock repair. status reports the state lock owner with its age, heartbeat age and staleness; clear-stale-lock requires confirm:"CLEAR_STALE_LOCK" and only moves a lock whose PID is provably dead to a backup file. force:true additionally clears a live-but-silent PID (a recycled PID) and still renames the record to a .recovered-<ts> backup. 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. Registered only while the tower-hmr component is on (the row is shipped off). 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. 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_review` | Submit an independent review verdict bound to the current branch tip: a completed mission starts a review round, and while the mission is active a later route may still record a verdict for that same reviewed tip, appending to the same round without changing the status (a moved tip is rejected with an explanation). 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, archive count, config path and the activity tail. Pass missionId for one full mission (tasks, notes, reviews, findings, completion report; archived missions are loaded from their year file); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; includeArchived appends compact archived summaries after the active page; format:"markdown" returns the human-readable mission board (active missions plus an archived count). Read-only. |
+| `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, archive count, config path and the activity tail. Also reports the repo-scoped git lock holder (`gitLock: {held,pid,phase,heldMs}`) so a merge holding the mutex is visible. Pass missionId for one full mission (tasks, notes, reviews, findings, completion report; archived missions are loaded from their year file); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; includeArchived appends compact archived summaries after the active page; format:"markdown" returns the human-readable mission board (active missions plus an archived count). 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. Terminal missions whose worktree is gone and whose configured archive policy is due (archive.afterDays / archive.maxMissions) are moved to <git-common-dir>/dsh-tower/archive/ so state.json stops rewriting them; nothing is deleted. |
 | `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

@@ -3,8 +3,11 @@
 All tools take `repoRoot` (an absolute path inside the target Git repository) and return JSON.
 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_recover`, `tower_test`, `tower_batch`, `tower_resource`, `tower_import_legacy`, `tower_legacy_map`.
+the always-registered `tower_doctor` and `tower_recover` (#122), and the component-owned tools
+`tower_reload` (`tower-hmr`), `tower_test` (`tower-tests`), `tower_batch` (`tower-batch`),
+`tower_resource` (`tower-leases`), `tower_import_legacy` / `tower_legacy_map` (`tower-import`).
+A component row that is off removes exactly its tools; `tower_status` and `tower_doctor` report it
+as "disabled by component <id>".
 
 `tower_mission` uses `id` (alias `missionId`); every other mission-scoped tool uses `missionId`
 (alias `id`). Other input aliases: `task_done`/`taskDone`, `task_drop`/`taskDrop`,
@@ -34,7 +37,7 @@ findings but not mutate them. Violations throw `[tower:not-authorized]` or
 | `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` — printable Unicode, NFC-normalized, ≤120 characters, `scope[]`, `tasks[]?`, `deps[]?`, `kind?`, `context?`, `references[]?` ≤20, `reviewPolicy?`, `reviewExemptionReason?`) | Create missions `M1..`; overlapping build scopes auto-add a dependency; rejects unknown deps and cycles. Mission ids stay ASCII (`M1`, `M2`); invisible characters and over-long titles are rejected with `invalid-argument`. `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\?`,\ `includeArchived\?`,\ `format\?`\ \|\ Dashboard\ by\ default\.\ Paged\ missions\ carry\ `reportBytes`\ only;\ `missionId`\ returns\ full\ detail\ \(tasks/notes/reviews/findings/completionReport\ body\),\ and\ an\ archived\ mission\ is\ loaded\ from\ its\ year\ file\.\ `offset`/`limit`\ page\ active\ missions\ \(default\ 20,\ max\ 100\),\ `includeGate`\ adds\ gate\ digests,\ `includeArchived`\ appends\ compact\ archived\ summaries\ \(flagged\ `archived:true`,\ no\ report\ body\)\ after\ the\ active\ page,\ and\ `format:"markdown"`\ returns\ the\ board\ \(active\ rows\ plus\ an\ archived\ count\)\.\ Includes\ `mode`\ with\ `lastChange`\ and\ recent\ `history`\ when\ the\ host\ mode\ hook\ is\ available\.\ `archive`\ reports\ `\{count,\ years,\ unreadable,\ message}`;\ a\ corrupt\ archive\ degrades\ to\ `unreadable:true`\ instead\ of\ failing\ the\ dashboard\.\ \|
+\|\ `tower_status`\ \|\ `missionId\?`,\ `offset\?`,\ `limit\?`,\ `includeGate\?`,\ `includeArchived\?`,\ `format\?`\ \|\ Dashboard\ by\ default\.\ Paged\ missions\ carry\ `reportBytes`\ only;\ `missionId`\ returns\ full\ detail\ \(tasks/notes/reviews/findings/completionReport\ body\),\ and\ an\ archived\ mission\ is\ loaded\ from\ its\ year\ file\.\ `offset`/`limit`\ page\ active\ missions\ \(default\ 20,\ max\ 100\),\ `includeGate`\ adds\ gate\ digests,\ `includeArchived`\ appends\ compact\ archived\ summaries\ \(flagged\ `archived:true`,\ no\ report\ body\)\ after\ the\ active\ page,\ and\ `format:"markdown"`\ returns\ the\ board\ \(active\ rows\ plus\ an\ archived\ count\)\.\ Includes\ `mode`\ with\ `lastChange`\ and\ recent\ `history`\ when\ the\ host\ mode\ hook\ is\ available\.\ `archive`\ reports\ `\{count,\ years,\ unreadable,\ message}`;\ a\ corrupt\ archive\ degrades\ to\ `unreadable:true`\ instead\ of\ failing\ the\ dashboard\.\ Also\ returns\ `gitLock`\ \(`\{held,\ pid,\ phase,\ heldMs}`\)\ for\ the\ repo-scoped\ git\ mutex,\ and\ `\{held:\ false}`\ when\ it\ is\ free\.\ \|
 | `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. |
@@ -45,16 +48,16 @@ findings but not mutate them. Violations throw `[tower:not-authorized]` or
 | `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_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). A later route may record a verdict for the same reviewed tip while the mission is active: it appends to that round (`appended:true`) without changing the status; a verdict for a moved tip is rejected with an explanation. |
 | `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. The final pass applies the `archive` policy: terminal missions whose worktree is gone are moved to `<git-common-dir>/dsh-tower/archive/` once `archive.afterDays`/`archive.maxMissions` says so, and `archived` lists their ids. Nothing is deleted; `archive.afterDays:0` archives a just-torn-down mission immediately. |
 | `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; 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 and the terminal-mission archive. Returns `{ok, checks[{id,status,detail}], stateSchema, archive, environmentContract}`; `archive` reports `{missions, archivedMissions, stateBytes, archiveBytes, years, files, unreadable, policy{enabled,afterDays,maxMissions}}`. A missing archive directory is healthy; a corrupt file is a `warn` with its diagnostic. 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_reload` | `repoRoot?` | Dev-only: ask DSH HMR to reconcile the profile and reload the Host plugin from disk. Registered while the `tower-hmr` component row is on (the row ships off); 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: the concept-budget surface (`config keys: N · sections: N · tools: N`), git, state schema, config, presets/subagents/HMR, the state lock's age and heartbeat freshness, the repo-scoped git lock holder, workspace lock, roster, worktree realpath/ownership, test config, leases and the terminal-mission archive. Returns `{ok, checks[{id,status,detail}], surface, stateLock, gitLock, stateSchema, archive, environmentContract}`; `surface` reports `{configKeys, sections, tools, baselineDate, line}` so growth against `scripts/surface-baseline.json` is visible in the output, `stateLock` reports `{held, pid, startedAt, at, alive, ageMs, heartbeatAgeMs, staleAfterMs, stale}` so a stuck tower is diagnosable without reading the file, and `gitLock` reports `{held, pid, phase, heldMs}` (`{held:false}` when free) with a `git-lock` check. `archive` reports `{missions, archivedMissions, stateBytes, archiveBytes, years, files, unreadable, policy{enabled,afterDays,maxMissions}}`. A missing archive directory is healthy; a corrupt file is a `warn` with its diagnostic. Never writes. |
+| `tower_recover` | `action` (`status`/`clear-stale-lock`), `confirm?`, `force?` | 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 `.recovered-<ts>` backup. `force:true` additionally clears a live-but-silent PID (a recycled PID): the output names `{pid, startedAt, ageMs, heartbeatAgeMs}` and the record is still renamed, never unlinked. 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

@@ -19,7 +19,7 @@
   时如何处理活跃的 plan mode。
 - **可观察性**：成功的工具调用发出进程内 [Tower 事件](reference/events.md)；稳定
   [工具错误码](reference/errors.md) 与 [blocker code](reference/blockers.md) 可被程序匹配。
-- **工具面**：本构建最多 28 个工具（含可选的 `tower_control` 与 `tower_reload`）；详见
+- **工具面**：本构建最多 29 个工具（含可选的 `tower_control` 与 `tower_reload`）；详见
   [工具参考](reference/tools.md)。
 
 ## 选择阅读路径

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

@@ -26,7 +26,7 @@ Tower 是 Host 插件：它的工具与提示段落在 DSH 启动时加载。DSH
 - 仍然可以显式请求对账（`/tower reload`、`tower_reload` 或 `plugin_manager`）；即使 `root: []`，
   它也会比较已加载模块与磁盘，并替换发生变化的模块。监视只是让保存后自动触发这次对账。
 - HMR 只为 profile 启动挂载（没有 `profileContext` 时 `disabled`）。没有 profile 启动的进程会报告
-  reload 不可用（`dev.hotReload` 开启时 `tower_reload` 仍注册，因此返回 `reload-unavailable`，
+  reload 不可用（`tower-hmr` 组件行开启时 `tower_reload` 仍注册，因此返回 `reload-unavailable`，
   而不是消失）。
 - profile patch 层在 DSH 启动时加载。编辑它——实际就是 hmr 的 `root` 列表——需要**重启一次 DSH**
   才生效。运行中的进程不会重新读取 HMR 行自身的配置。
@@ -82,7 +82,7 @@ Windows 上通常是 `C:\Users\<you>\.dsh`）：
 
 ## 编辑循环
 
-1. 编辑 `lib/*.js`、`index.js`、`worker.js`、`reviewer.js` 或 `skills.js`。
+1. 编辑 `host/*.js`、`adapters/*.js`、`app/*.js`、`domain/**/*.js`、`index.js`、`worker.js`、`reviewer.js` 或 `skills.js`。
 2. 保存文件。监视器会去抖（DSH 默认 100 ms）并对账 profile；变更的模块被替换，受影响的 Loader
    条目重启。
 3. 观察 DSH 日志中的 `reload plugin at <path>` / `restart required: …` 消息。
@@ -95,9 +95,9 @@ Windows 上通常是 `C:\Users\<you>\.dsh`）：
 
 | 配置键 | 含义 |
 |---|---|
-| `dev.hotReload` | 注册 `tower_reload`；关闭时 `/tower reload` 也被禁用（默认 `true`）。无 HMR 服务时工具仍注册，以便返回 `reload-unavailable`。 |
+| `tower-hmr`（组件行） | 开关本体：开启时注册 `tower_reload` 与 `/tower reload`，关闭时报告“disabled by component tower-hmr”。该行随包关闭；联动开发 profile 在插件页启用它。`dev.hotReload` 已在 2.4.0 移除，现在会作为未知键被拒绝。 |
 | `dev.reloadDelayMs` | 计划中的对账运行前的延迟，单位毫秒（默认 `50`），让工具/命令结果先送达模型，再替换插件。 |
-| `dev.reloadRequiredIds` | profile 必须保持活跃的 Loader 条目 id（默认 `tower-bundle`、`tower`、`tower-skills`、`preset-tower-worker`、`preset-tower-reviewer`）。即使某个 required 条目早已处于非活跃状态，也会被报告为重载失败。 |
+| `dev.reloadRequiredIds` | profile 必须保持活跃的 Loader 条目 id（默认 `tower`、`tower-host`、`preset-tower-worker`）。即使某个 required 条目早已处于非活跃状态，也会被报告为重载失败。可选能力行刻意不在 required 中，因此关闭某一行不会被误报为 reload 失败。 |
 
 重载是**调度而非等待**：`/tower reload` 与 `tower_reload` 立即返回 `scheduled`、`delayMs`、
 `requiredIds`（以及存在待处理错误时的 `lastError`），随后 HMR 在延迟后对账 profile。这是有意为之——

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

@@ -42,6 +42,16 @@ Host 插件在 DSH 启动时加载：**安装或更新后需要重启 DSH**。
   `tower_doctor` 会把未知模式报告为 `warn`（`case-mode`）。在大小写不敏感的检出上，
   `src/Api/**` 与 `src/api/**` 从此视为重叠，仅大小写不同的改动不再被 out-of-scope 门禁拒绝。
   存储的 scope 文本永远不会被改写：看板仍显示操作者输入的原样。
+- **2.3.0 → 2.4.0（未发布）**：所有能力合一的 `tower-bundle` 组行已移除。`cordis.patch.yml`
+  现在随包提供强制的 `tower` host 锚点（Host 插件与 worker preset 是它的内部 section），以及可单独
+  开关的顶层行：`tower-skills`、`tower-batch`、`tower-import`、`tower-leases`、`tower-tests`、
+  `tower-hmr`（随包关闭）与 `preset-tower-reviewer`（受 `review.requireReview` 条件约束）。
+  `tools` 配置组与 `dev.hotReload` 已删除：仍带这些键的 profile 现在会作为未知键被拒绝
+  （`config-unknown-key`），在删除它们之前 host 不会挂载，因此不再存在静默无效的开关。请改为在插件页
+  使用对应的组件行；`tower-hmr` 随包关闭，因此在为联动开发 profile 开启它之前，`tower_reload` 与
+  `/tower reload` 会报告为 “disabled by component tower-hmr”。`tower_doctor` 与 `tower_recover`
+  在任何配置下都会注册，无需配置键。仅当 `review.requireReview` 为 false 时 reviewer 行才可关闭；
+  该门禁开启时，规划与模式进入会以带解释的错误拒绝该组合。不需要迁移 state。
 - **2.0.4 → 2.1.0-beta.1**：不需要迁移 config；state 会按上述说明自动迁移（v1/v2 → v3）。
   这是发布到 `next` dist-tag 的**预发布**，
   `latest` 仍指向 2.0.4——请用 `dsh plugin --profile web add dsh-tower@next`（或精确版本号）安装。

package/docs/zh/operations/security.md

@@ -70,7 +70,7 @@ OS 级隔离运行 host。
 - **测试发现是仓库代码。** `tests.admission` 默认 `off`，只有显式 `tower_test` 才会执行仓库
   `package.json` 的 `tower.testDiscovery` 命令；该命令以 DSH 的 OS 权限运行，不是沙箱。不可信仓库应
   设 `tests.allowPackageDiscovery:false`。
-- **HMR 重载。** 开启 `dev.hotReload` 时，`/tower reload`/`tower_reload` 会让 DSH 从磁盘重新导入
+- **HMR 重载。** 开启 `tower-hmr` 组件行时，`/tower reload`/`tower_reload` 会让 DSH 从磁盘重新导入
   插件。只为你信任的检出配置 HMR 监视 root；重载会执行这些文件当前的代码。
 - **提示注入。** reviewer 会读取不受信任的分支内容（diff/评论）。只读 preset 限制了影响面，但模型侧
   没有绝对防护。

package/docs/zh/reference/blockers.md

@@ -19,10 +19,10 @@
 | `read-only-survey` | survey mission 修改了文件；survey mission 必须只读。 |
 | `out-of-scope` | 改动文件超出 mission scope；有意为之就扩大 scope，否则回退。在大小写敏感的检出上，仅大小写不同的路径仍会被拒绝，detail 会指出折叠大小写后本可匹配的 scope 条目。 |
 | `base-dirty` | 主检出存在未提交改动，合并会覆盖它们。 |
-| `deps-unmerged` | 依赖 mission 尚未 merged/abandoned。 |
+| `deps-unmerged` | 依赖 mission 尚未满足：build 依赖须 `merged`/`abandoned`；survey 依赖在 `completed` 即视为满足（含归档记录）。 |
 | `no-review` | `review.requireReview:true` 且分支上没有审查：spawn reviewer（或关闭审查门禁）。 |
 | `review-mission-mismatch` | `review.requireReview:true` 且最新审查属于另一个 mission。 |
-| `not-clean` | `review.requireReview:true` 且最新审查是 `p1-Nitems`/`p2-Nitems`；需要再来一轮。 |
+| `not-clean` | `review.requireReview:true` 且最新审查是 `p1-Nitems`/`p2-Nitems`；需要再来一轮（同一轮的各 route 结论会追加记录，不会让状态反复翻转）。 |
 | `review-hold` | `review.requireReview:true` 且最新审查建议 hold；必须由后续的干净审查取代。 |
 | `review-not-approved` | `review.requireReview:true` 且最新干净审查给出的是 `fix-then-merge` 或 `hold`；只有 `merge` 才算批准。 |
 | `tip-moved` | `review.requireReview:true` 且审查之后分支发生变化；重新审查（或使用干净 rebase 的免审豁免）。 |