dsh-tower 2.1.0 → 2.3.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,128 @@
+# Surface budget
+
+The plugin measures its user-facing surface in three numbers: **config leaf keys**,
+**config sections**, and **registered tools**. The committed baseline is
+[`scripts/surface-baseline.json`](../../scripts/surface-baseline.json); the brake
+is `npm run surface:check`; the decision record is
+[ADR 0004](../adr/0004-surface-budget.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`.
+
+## 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. |
+| `tools.exposeOperational` | core | Master switch for the operational tool surface. |
+| `tools.exposeBatch` | core | Registers the evidence-batch tool. |
+| `tools.exposeImport` | core | Registers the legacy import tools. |
+| `tools.exposeLeases` | core | Registers advisory leases. |
+| `tools.exposeTests` | core | Registers test discovery; required when the test gate is on. |
+| `tools.exposeRecovery` | core | Registers the stale-lock escape hatch. |
+| `tools.exposeDoctor` | core | Registers the read-only health contract. |
+| `leases.ttlMs` | tuning | Default advisory lease lifetime. |
+| `dev.hotReload` | tuning | Registers the dev reload tool when HMR exists. |
+| `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
+an operational switch (`tools.expose*`) or the dev mode can legitimately remove
+them from the surface.
+
+| Tool | Class | Note |
+|---|---|---|
+| `tower_adopt` | core | Reconciles a restored roster with the durable catalog. |
+| `tower_batch` | optional | Evidence-batch workflow; `tools.exposeBatch`. |
+| `tower_complete` | core | The only completion path for a worker. |
+| `tower_diff` | core | The read-only review view. |
+| `tower_doctor` | optional | Read-only health contract; `tools.exposeDoctor`. |
+| `tower_finding` | core | Out-of-scope issue recording. |
+| `tower_findings` | core | Finding lifecycle. |
+| `tower_import_legacy` | optional | Legacy migration; `tools.exposeImport`. |
+| `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; `tools.exposeImport`. |
+| `tower_merge` | core | The only merge path. |
+| `tower_mission` | core | Mission progress and blockers. |
+| `tower_plan` | core | Mission planning. |
+| `tower_preflight` | core | The read-only merge gate. |
+| `tower_rebase` | core | Keeps a mission branch current. |
+| `tower_recover` | optional | Stale-lock recovery; `tools.exposeRecovery`. |
+| `tower_reload` | optional | Dev-only reload; registered while the HMR/dev mode is on. |
+| `tower_resource` | optional | Advisory leases; `tools.exposeLeases`. |
+| `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; `tools.exposeTests`. |
+
+## 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,6 +1,7 @@
 # Tools overview (generated)
 
 > Generated by `npm run docs:generate:tools` from the registered tool definitions. Do not edit by hand.
+> Surface: config keys: 64 · sections: 15 · tools: 27 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
 
 | Tool | Description |
 |---|---|
@@ -8,7 +9,7 @@
 | `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_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. |
@@ -21,13 +22,13 @@
 | `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_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. 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_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

@@ -34,7 +34,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,7 +45,7 @@ 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. |
@@ -53,8 +53,8 @@ findings but not mutate them. Violations throw `[tower:not-authorized]` or
 | `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_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/guide/hot-reload.md

@@ -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: …` 消息。

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 的免审豁免）。 |

package/docs/zh/reference/doctor.md

@@ -11,6 +11,23 @@
     { "id": "git", "status": "pass", "detail": "git version 2.55.0" },
     { "id": "state", "status": "pass", "detail": ".../state.json revision 7" }
   ],
+  "stateLock": {
+    "held": true,
+    "pid": 4242,
+    "startedAt": 1761280000000,
+    "at": 1761280120000,
+    "alive": true,
+    "ageMs": 121000,
+    "heartbeatAgeMs": 1000,
+    "staleAfterMs": 3000,
+    "stale": false
+  },
+  "gitLock": {
+    "held": true,
+    "pid": 4242,
+    "phase": "merge",
+    "heldMs": 92000
+  },
   "archive": {
     "missions": 3,
     "archivedMissions": 12,
@@ -33,6 +50,17 @@
 }
 ```
 
+`stateLock`（以及 `state-lock` 检查）报告锁的年龄（`ageMs`，从记录的 `since` 起算）与心跳新鲜度
+（`heartbeatAgeMs`，从最后一次 `at` 起算），并对照过期窗口（`staleAfterMs = 3 × 1000 ms`）。
+PID 存活并不等于写者存活：停止心跳的持有者会报告 `stale: true`，下一次 mutation 会回收它（或用
+`tower_recover clear-stale-lock force:true` 移到备份）；心跳新鲜则报告为持有中，绝不会被抢走。
+这样无需手工读取 `state.lock` 就能诊断 PID 被复用的情况。
+
+`gitLock`（以及 `git-lock` 检查）报告仓库级 git 互斥锁：被 merge/rebase/init/teardown/provision 持有时为
+`{held, pid, phase, heldMs}`，空闲时为 `{held: false}`。merge 可以合法持有到配置的 merge 超时（默认 15 分钟），
+因此“被持有”是 `warn` 而不是失败；持有者的阶段与时长让卡住的控制塔可被诊断。`tower_status` 返回同一个
+`gitLock` 对象。
+
 `archive` 报告终态任务归档：活跃 `missions`、`archivedMissions` 与 `stateBytes`，归档目录的
 `archiveBytes`/`years`/`files`，每条 `unreadable` 诊断，以及配置的 `policy`（`enabled`、`afterDays`、
 `maxMissions`）。归档目录不存在是健康的空归档（`archive` 检查为 `pass`）；截断的 index/year 文件是
@@ -51,7 +79,7 @@ test-discovery 策略、完成报告大小、归档健康度、旧版快照、ba
 使用安全的 `case-sensitive` 默认值。
 
 检查覆盖：git 可用性、仓库身份、state schema/加载、已探测的大小写模式、仓库配置是否存在、
-worker/reviewer preset 名称、subagents 与 HMR 服务、workspace 锁持有者/是否过期、实时 roster、
+worker/reviewer preset 名称、subagents 与 HMR 服务、state 锁年龄/心跳、workspace 锁持有者/是否过期、实时 roster、
 worktree 是否存在/归属/是否脏、test-discovery 策略、旧版快照、batch 与租约。被 `tower_teardown`
 正常清理的 mission worktree 会被跳过（检查中会注明已移除数量），不会被误报为 missing。`warn` 是提示；`fail` 表示仓库在 spawn/merge 前需要
 处理。state 加载失败会作为失败的检查报告而不是抛出，因此 doctor 在损坏的仓库上仍然有用。

package/docs/zh/reference/tools.md

@@ -34,7 +34,7 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 | `tower_init` | `base?`、`autoGitInit?`、`snapshotDirty?`、`reanchor?` | 创建 `<git-common-dir>/dsh-tower/state.json`。`autoGitInit` 执行 `git init` 并创建空的初始提交；`snapshotDirty` 记录一个游离快照提交作为 mission 基线；`reanchor` 仅在没有非终态 mission 时修改基线。返回 `dirty`、`snapshotCommit`、`reanchored`。 |
 | `tower_plan` | `missions[]`（`title`——可打印 Unicode，NFC 规范化，≤120 字符、`scope[]`、`tasks[]?`、`deps[]?`、`kind?`、`context?`、`references[]?` ≤20、`reviewPolicy?`、`reviewExemptionReason?`） | 创建 mission `M1..`；重叠的 build scope 会自动加依赖；拒绝未知依赖与依赖循环。mission id 保持 ASCII（`M1`、`M2`）；不可见字符与超长标题会以 `invalid-argument` 拒绝。`reviewPolicy:"none"` 需要非空理由；审查门禁开启时，preflight 还要求 `gates.allowReviewExemption`。 |
 | `tower_mission` | `id`（别名 `missionId`）、`status?`、`task_done?`、`task_drop?`+`task_drop_reason?`、`blocker?`、`clear_blockers?`、`note?`、`scope?`、`pause_cause?`、`authorization?` | 更新单个 mission。worker 可安全使用的字段是 task/blocker/note；不能在这里设置 `merged`。暂停的 mission 记录 `pause_cause`（user/failure/resource/dependency）；恢复用户暂停的 mission 会遵循 `mode.requireResumeAuthorization`。 |
-| `tower_status` | `missionId?`、`offset?`、`limit?`、`includeGate?`、`format?` | 默认返回面板。分页 mission 只带 `reportBytes`；`missionId` 返回完整详情（任务/备注/审查/finding/完成报告正文）。`offset`/`limit` 对 mission 分页（默认 20，最大 100），`includeGate` 附带门禁摘要，`format:"markdown"` 返回看板。host 提供 mode hook 时还会包含 `mode.lastChange` 与最近 `history`。 |
+| `tower_status` | `missionId?`、`offset?`、`limit?`、`includeGate?`、`format?` | 默认返回面板。分页 mission 只带 `reportBytes`；`missionId` 返回完整详情（任务/备注/审查/finding/完成报告正文）。`offset`/`limit` 对 mission 分页（默认 20，最大 100），`includeGate` 附带门禁摘要，`format:"markdown"` 返回看板。host 提供 mode hook 时还会包含 `mode.lastChange` 与最近 `history`。还返回仓库级 git 互斥锁 `gitLock`（`{held, pid, phase, heldMs}`，空闲时 `{held:false}`）。 |
 | `tower_spawn` | `missionId`（别名 `id`）、`role`（`worker`/`reviewer`）、`name?`、`instructions?`、`worktreeRoot?`、`wait?`、`waitMs?`、`takeover?`、`includeDirtyBase?` | 准备或复用 worktree 并启动子代理。worker 使用 `tower-worker`；reviewer 要求 mission 为 `completed`，并使用只读的 `tower-reviewer`。`takeover:true` 替换已不再运行的 worker 条目（ownerGeneration 递增）。每个 mission 只能有一个活跃 worker；`spawn.maxLiveWorkers` 限制整个仓库。 |
 | `tower_roster` | — | roster 及来自子代理目录的实时活动（`running`/`inactive`/`missing`/`unknown`）与 `stale` 标记。只读。 |
 | `tower_adopt` | `retireMissing?` | 把 roster 条目与持久子代理目录对账。可证明已消失的 agent 会被标记为 retired（默认），或标记为 `missing`（`retireMissing:false`）以便检查/接管。 |
@@ -45,7 +45,7 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 | `tower_interrupt` | `to?`（roster 名称）、`agentId?`、`reason?` | 通过 `subagents.interrupt` 中断一个运行中的 roster agent，并记录 `state:"interrupted"`。幂等（未运行 → `interrupted:false`）。 |
 | `tower_finding` | `type`、`title`、`summary`、`details`、`suggested_fix`、`severity?`、`missionId?`、`location?` | 记录 scope 之外的问题；reviewer 用它代替直接改文件。新 finding 初始为 `open`。 |
 | `tower_findings` | `id?`、`status?`、`note?`、过滤（`type?`、`severity?`、`missionId?`、`open?`、`limit?`） | 生命周期工具：列出/读取/流转。状态为 `open → triaged → fixed`/`wontfix`，允许重新打开。只有控制塔或 worker 能修改；reviewer 只能列出/读取。 |
-| `tower_review` | `missionId`（别名 `id`）、`status`（`clean`/`p1-Nitems`/`p2-Nitems`）、`merge`（`merge`/`fix-then-merge`/`hold`）、`findings`、`decision`、`checks?`、`breakGlassReason?` | 绑定当前 tip 的 reviewer 结论。reviewer 必须是获派的 reviewer（或由控制塔使用 break-glass）。 |
+| `tower_review` | `missionId`（别名 `id`）、`status`（`clean`/`p1-Nitems`/`p2-Nitems`）、`merge`（`merge`/`fix-then-merge`/`hold`）、`findings`、`decision`、`checks?`、`breakGlassReason?` | 绑定当前 tip 的 reviewer 结论。reviewer 必须是获派的 reviewer（或由控制塔使用 break-glass）。非 clean 结论使 mission 回到 active 后，其他 route 仍可为同一 reviewed tip 提交结论：追加到同一轮（`appended:true`），不再改变状态；tip 已移动时会被明确拒绝。 |
 | `tower_preflight` | `missionId`（别名 `id`） | 只读门禁：返回 `{ok, blockers[], branchTip, baseTip, changedFiles, review}`。 |
 | `tower_merge` | `missionId`（别名 `id`）、`timeoutMs?`（别名 `timeout_ms`） | 门禁全绿后合并。若合并提交已落地则记录（`reconciled`）；若命令失败但提交已存在则恢复（`recoveredFromFailure`）；区分 `merge-hook-failed` 与 `merge-conflict`。 |
 | `tower_rebase` | `missionId`（别名 `id`） | 在 worktree 内把分支 rebase 到基线。worker 运行中或 worktree 脏时拒绝。分支已包含在基线中时返回 `alreadyMerged` 且保持分支不动。 |
@@ -53,8 +53,8 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 | `tower_mode` | — | 报告模式、最近修改、被暂停的 goal、被拒绝的工具、store 路径、插件版本、HMR 可用性、workspace 锁持有者。 |
 | `tower_control` | `action`（`enter`/`exit`）、`reason` | 模型主动切换模式；默认注册，设 `mode.allowAgentControl:false` 可禁用；`reason` 必填。 |
 | `tower_reload` | `repoRoot?` | 仅开发用：请求 DSH HMR 对账 profile 并从磁盘重载 Host 插件。`dev.hotReload` 开启时注册；在工具结果返回后调度（默认 50 ms）；没有 HMR 时以 `reload-unavailable` 失败。传入 `repoRoot` 时调用者必须是控制塔。 |
-| `tower_doctor` | —（需要 `repoRoot`） | 只读健康契约：git、state schema、config、preset/subagents/HMR、workspace 锁、roster、worktree realpath/归属、测试配置、leases。返回 `{ok, checks[{id,status,detail}], environmentContract}`。从不写状态。 |
-| `tower_recover` | `action`（`status`/`clear-stale-lock`）、`confirm?` | 恢复诊断与显式 stale state-lock 修复。`clear-stale-lock` 需要 `confirm:"CLEAR_STALE_LOCK"`，只把 PID 已死的锁移到备份文件；不会重置状态或 worktree。 |
+| `tower_doctor` | —（需要 `repoRoot`） | 只读健康契约：git、state schema、config、preset/subagents/HMR、state 锁的年龄与心跳新鲜度、仓库级 git 锁持有者、workspace 锁、roster、worktree realpath/归属、测试配置、leases。返回 `{ok, checks[{id,status,detail}], stateLock, gitLock, environmentContract}`；`stateLock` 报告 `{held, pid, startedAt, at, alive, ageMs, heartbeatAgeMs, staleAfterMs, stale}`，`gitLock` 报告 `{held, pid, phase, heldMs}`（空闲时 `{held:false}`）并附带 `git-lock` 检查，无需读取文件即可诊断卡住的控制塔。从不写状态。 |
+| `tower_recover` | `action`（`status`/`clear-stale-lock`）、`confirm?`、`force?` | 恢复诊断与显式 stale state-lock 修复。`clear-stale-lock` 需要 `confirm:"CLEAR_STALE_LOCK"`，只把 PID 已死的锁改名为 `.recovered-<ts>` 备份。`force:true` 还能清理 PID 仍存活但心跳静默（PID 被复用）的锁：输出 `{pid, startedAt, ageMs, heartbeatAgeMs}`，记录仍只改名、绝不 unlink。不会重置状态或 worktree。 |
 | `tower_test` | `missionId`（别名 `id`） | 运行 worktree 的 `package.json` 中 `tower.testDiscovery` 配置的发现命令并记录回执；失败时 `ok:false`。自动准入检查请用 `tower_complete`。 |
 | `tower_batch` | `action`（`create`/`status`/`close`/`abandon`）、`missionIds?`、`exclusions?`、`requiredChecks?`、`receiptPaths?`、`batchId?`、`checks?`、`treeTip?`、`receiptHashes?`、`reason?` | 有限证据批次。create 冻结成员/检查/回执；close 校验每条必需检查与回执哈希；`merged` 成员也可参与 close；abandon 可退掉过期的 open batch 且不删除 mission。成员关系不可变。 |
 | `tower_resource` | `action`（`acquire`/`release`/`status`）、`name?`、`holder?`、`token?`、`ttlMs?`、`force?` | 每个仓库的咨询式租约，位于 `<common>/dsh-tower/leases.json`。没有 OS CPU/内存硬上限；过期的租约需要显式 `force` 与正确 token。 |

package/domain/batch.js

@@ -120,7 +120,7 @@ function normalizeReceiptPathOrNull(value, where) {
   }
 }
 
-/** Legacy snapshots imported by lib/legacy.js; only paused missions may be excluded. */
+/** Legacy snapshots imported by adapters/legacy.js; only paused missions may be excluded. */
 function pausedLegacyIds(state) {
   const ids = new Set()
   const collectMission = (mission) => {
@@ -138,7 +138,7 @@ function pausedLegacyIds(state) {
     collectList(snapshot.missions)
     if (isPlainObject(snapshot.snapshot)) collectList(snapshot.snapshot.missions)
     if (isPlainObject(snapshot.payload)) collectList(snapshot.payload.missions)
-    // lib/legacy.js stores imported snapshots with `pausedMissionIds`; older,
+    // adapters/legacy.js stores imported snapshots with `pausedMissionIds`; older,
     // hand-written fixtures may use `pausedIds`.
     for (const key of ['pausedIds', 'pausedMissionIds']) {
       if (Array.isArray(snapshot[key])) {

package/domain/config/schema.js

@@ -2,7 +2,7 @@
 //
 // This module is pure: it declares the Schemastery schema, validates raw config
 // objects, and materializes defaults. Profile and repository loading (fs and the
-// process-local profile snapshot) live in lib/config.js, which re-exports
+// process-local profile snapshot) live in host/config.js, which re-exports
 // `Config` and `resolveTowerConfig` for compatibility.
 //
 // Layers, lowest precedence first:
@@ -290,6 +290,30 @@ export const Config = Schema.object({
     .description('Development and hot-reload behavior.'),
 }).description('DSH Tower configuration')
 
+/**
+ * The user-facing config surface (#84): every leaf key one level deep plus the
+ * names of the object sections. The generated config reference, `tower_doctor`
+ * and the surface baseline all count this same shape, so "how many concepts"
+ * is one number rather than three near-identical ones.
+ *
+ * @param {any} [config] the Schemastery root (defaults to the live `Config`)
+ * @returns {{ keys: string[], sections: string[], count: number }}
+ */
+export function configSurface(config = Config) {
+  const keys = []
+  const sections = []
+  for (const [key, schema] of Object.entries(config?.dict ?? {})) {
+    const dict = schema?.dict
+    if (dict && typeof dict === 'object') {
+      sections.push(key)
+      for (const child of Object.keys(dict)) keys.push(`${key}.${child}`)
+    } else {
+      keys.push(key)
+    }
+  }
+  return { keys, sections, count: keys.length }
+}
+
 export function clone(value) {
   return value === undefined ? undefined : JSON.parse(JSON.stringify(value))
 }