dsh-tower 2.1.0 → 2.4.0

package/docs/operations/incident.md

@@ -0,0 +1,82 @@
+# Incidents and regressions
+
+A **regression** is something that *worked in a released version, then stopped*.
+It is not a feature request and not an ordinary bug: a user could rely on the old
+behavior, so the record must say which release broke it, who was affected, and
+which test now prevents it from happening again.
+
+Only shipped regressions get this record. Ordinary bugs, missing features and
+questions use the normal issue flow.
+
+## The six-field record
+
+Copy this into the issue body (or the closing comment) when a regression is
+confirmed. All six lines are part of the closure; the `Regression test:` line is
+the one a machine can check.
+
+```text
+Symptom:            what the user sees, with the exact error text
+Introduced in:      version / commit range
+Blast radius:       who is affected (all sessions? restored ones? one platform?)
+Root cause:         one paragraph, mechanism not blame; include the fix
+Regression test:    path to the test that fails without the fix
+Released in:        version that carries the fix, and how it was verified
+```
+
+The fields answer, in order: what broke, which release introduced it, the user
+impact, the cause and the fix, the proof, and the release that carries the fix.
+`Introduced in` and `Released in` are different answers; do not fill both with the
+current version.
+
+## Label
+
+The `regression` label means exactly **"worked in a released version, then
+stopped"**. It is mutually exclusive with `bug` for a shipped break: the regression
+label is the narrower claim. The issue title still describes the symptom.
+
+## Closing rule
+
+A `regression` issue may not be closed while any of these is true:
+
+- no `Regression test:` line names a path;
+- the path does not exist in the repository;
+- the path is not a test file (a script or a doc is not evidence).
+
+The offline audit reads a local tracker export, so it needs no network and no
+token:
+
+```powershell
+# 1) Export (network, once) — same export as the P0/P1 audit
+New-Item -ItemType Directory -Force tracker | Out-Null
+$all = foreach ($n in (gh issue list --repo louifinn/dsh-tower --state all --limit 500 --json number --jq '.[].number')) {
+  gh issue view $n --repo louifinn/dsh-tower --json number,title,state,labels,closedAt,body,comments | ConvertFrom-Json
+}
+@{ issues = @($all) } | ConvertTo-Json -Depth 8 | Set-Content tracker/issues.json -Encoding utf8
+
+# 2) Audit (offline)
+npm run audit:regressions
+npm run audit:regressions -- --tracker path/to/export.json --json
+```
+
+Exit codes: `0` — every closed regression names an existing test; `1` — at least
+one is missing or points at a nonexistent/non-test path; `2` — the export is
+missing or malformed.
+
+The audit is a script because a checklist is only as reliable as the reader.
+`tests/regression-audit.test.mjs` proves the check fails for a seeded missing path
+and passes for a real one, so the rule cannot silently become prose.
+
+## Where the practice starts
+
+The first real entry is #68 (all tower write tools failed with `unknown` after a
+session restore). The tower retro-fills that issue with these six fields; this
+document is the template it used.
+
+## Non-goals
+
+No blameless-postmortem ceremony for ordinary bugs, no SLA commitments, no
+five-whys, and no incident commander. Only shipped regressions get the six fields.
+
+Unowned. This is a writing habit and a closing convention; no runtime code
+enforces it. The one checkable part — the `Regression test:` path — is enforced by
+`scripts/regression-audit.mjs`.

package/docs/operations/runbook.md

@@ -48,9 +48,18 @@ fails, the previous plugin code no longer runs: restart DSH and check the HMR lo
 
 ## State lock
 
-`tower state is locked by another writer` means an operation holds `state.lock`. Wait and retry. Only if
-the owning process is gone, remove `<git-common-dir>/dsh-tower/state.lock` deliberately; never delete it
-while an agent may still be running.
+`tower state is locked by another writer` means an operation holds `state.lock`. Wait and retry: a
+live holder rewrites the record's `at` heartbeat every second, so it is never stolen while it runs.
+A crashed holder stops heartbeating; once its last heartbeat is older than three intervals (3 s), the
+next mutation reclaims the record after byte verification. A reclaimed live-PID record is kept as
+`state.lock.reclaimed-<ts>-<id>` for audit; a provably dead PID (ESRCH) is reclaimed immediately.
+
+If a lock never clears, `tower_recover({action:"status"})` reports the owner's `pid`, `startedAt`,
+`ageMs` and `heartbeatAgeMs`, and `tower_doctor` reports the same. `tower_recover
+clear-stale-lock` with `confirm:"CLEAR_STALE_LOCK"` moves a provably dead lock to
+`state.lock.recovered-<ts>`; add `force: true` to clear a live-but-silent PID (the recycled-PID case)
+after confirming no writer is active. The repair always renames, never deletes, so the bytes stay
+auditable. Never delete `state.lock` by hand while an agent may still be running.
 
 ## Worktrees and teardown
 

package/docs/operations/security.md

@@ -104,7 +104,7 @@ Tower work, and run the host under OS-level isolation.
   cannot make those safe; review hooks before running Tower on an untrusted repository.
 - **Package test commands.** Declared discovery commands have the same trust as repository hooks; a
   malicious `package.json` can run code. Disable `tests.allowPackageDiscovery` and review the file.
-- **HMR reload.** With `dev.hotReload`, `/tower reload`/`tower_reload` asks DSH to re-import the plugin
+- **HMR reload.** With the `tower-hmr` component row on, `/tower reload`/`tower_reload` asks DSH to re-import the plugin
   from disk. Only enable HMR watch roots for checkouts you trust; a reload executes the current files.
 - **Prompt injection.** The reviewer reads untrusted branch content (diff/comments). The read-only preset
   limits impact, but no model-side protection is absolute.

package/docs/reference/blockers.md

@@ -18,10 +18,10 @@ tables below define 32 stable blocker/failure codes.
 | `read-only-survey` | Survey mission changed files; survey missions must be read-only. |
 | `out-of-scope` | Changed files outside the mission scope; widen scope deliberately or revert. On a case-sensitive checkout a case-only mismatch is still rejected and the detail names the scope entry it would match if case were folded. |
 | `base-dirty` | The main checkout has uncommitted changes the merge would overwrite. |
-| `deps-unmerged` | A dependency mission is not merged/abandoned. |
+| `deps-unmerged` | A dependency mission is not satisfied: a build dependency must be `merged`/`abandoned`, while a survey dependency is satisfied at `completed` (archived entries included). |
 | `no-review` | `review.requireReview:true` and no review exists on the branch: spawn a reviewer (or disable the review gate). |
 | `review-mission-mismatch` | `review.requireReview:true` and the latest review belongs to another mission. |
-| `not-clean` | `review.requireReview:true` and latest review is `p1-Nitems`/`p2-Nitems`; another round is required. |
+| `not-clean` | `review.requireReview:true` and latest review is `p1-Nitems`/`p2-Nitems`; another round is required. Verdicts from later routes of the same round are appended to it instead of flipping the mission again. |
 | `review-hold` | `review.requireReview:true` and latest review recommends hold; a later clean review must supersede it. |
 | `review-not-approved` | `review.requireReview:true` and latest clean review says `fix-then-merge` or `hold`; only `merge` approves. |
 | `tip-moved` | `review.requireReview:true` and the branch changed after review; review again (or use a clean rebase waiver). |

package/docs/reference/component-surface.md

@@ -0,0 +1,135 @@
+# Component surface (generated)
+
+> Generated by `npm run docs:generate:components` from `scripts/component-surface.json` and
+> `scripts/surface-baseline.json`. Do not edit by hand.
+
+Decision: [ADR 0005](../adr/0005-component-surface.md) · decision date: 2026-10-23 · baseline 2026-10-23 · visible components: 8 (`tower`, `tower-skills`, `tower-batch`, `tower-import`, `tower-leases`, `tower-tests`, `tower-hmr`, `preset-tower-reviewer`)
+
+The component axis answers one question for every config key: may a user turn it
+off, and if so, must that switch be a component? Four classes cover every key, so
+"should this be a component?" is a table lookup rather than a judgement call.
+
+| Class | Meaning |
+|---|---|
+| `core` | Removing it breaks the Tower contract. It is never a switch. |
+| `optional-component` | A capability whose off state leaves the rest of Tower intact. It must be a user-visible switch with a documented fallback. |
+| `optional-config` | A tuning knob, not a capability. It stays in the config form and never hides a component. |
+| `forbidden-to-disable` | The host, the health contract, the recovery escape, the review contract and the merge gates. No group, row or boolean key may turn it off. |
+
+## Components
+
+The shipped `cordis.patch.yml` rows, with the fallback contract each off state
+must satisfy. A visible row is a component the plugin page may switch; an internal
+row is a section of its parent and is not independently switchable.
+
+| Component | Scope | Kind | Off state and fallback |
+|---|---|---|---|
+| `tower` | visible | group | Off equals uninstalling Tower: no tools, presets or skills remain. That is the accepted all-off boundary of the mandatory host anchor, not an optional capability. |
+| `tower-host` | internal | row | The Host plugin itself, nested under the mandatory tower anchor. A mandatory dependency, never its own switch. |
+| `tower-skills` | visible | row | The 3 skills leave the catalog; the worker/reviewer PROTOCOL sections still ship through systemPrompt.section, so only the tower-recovery guidance is lost. |
+| `tower-batch` | visible | row | tower_batch is not registered; missions, gates and merges are unaffected because no state depends on a batch. |
+| `tower-import` | visible | row | tower_import_legacy and tower_legacy_map are not registered; new repository state is unaffected. |
+| `tower-leases` | visible | row | tower_resource is not registered; advisory leases are coordination only, so nothing else depends on them. |
+| `tower-tests` | visible | row | tower_test is not registered and no test receipt can be recorded. With gates.requireTests:true planning/mode entry is rejected with an explanation, and the merge gate still reports tests-missing. |
+| `tower-hmr` | visible | row | tower_reload and /tower reload are unavailable; a profile without HMR behaves exactly as before. Shipped disabled: enable the row for a linked dev profile. |
+| `preset-tower-worker` | internal | row | tower_spawn fails without the worker preset. A mandatory dependency, never a switch. |
+| `preset-tower-reviewer` | visible | row | The reviewer cannot be dispatched. Supported while review.requireReview is false (merge is unaffected); with the gate on planning/mode entry is locked with an explanatory error. |
+
+## Forbidden to disable
+
+The host, the health contract, the recovery escape, the review contract and the
+merge gates are configuration or code, never switches. `npm run
+docs:check:components` derives the live disablers from `host/tool-registry.js`
+and `cordis.patch.yml`; a disabler that is not recorded here fails the gate.
+
+| Capability | Why it may not be disabled | Recorded disablers | Decision |
+|---|---|---|---|
+| the Tower host | Without the host the plugin registers nothing; there is no off state that leaves the rest working, and no config boolean may remove it. The visible `tower` anchor is the all-off boundary, and the host section nested under it may never become its own switch. | none | none may exist |
+| tower_doctor (read-only health contract) | Diagnosis must always exist so a failure message can point at it. #122 removed exposeDoctor and the exposeOperational master switch; the tool is registered for every configuration. | none | none may exist |
+| tower_recover (stale state-lock escape) | The escape hatch must exist whenever the lock it repairs can be left behind. #122 removed exposeRecovery and the exposeOperational master switch; the tool is registered for every configuration. | none | none may exist |
+| the review contract | review.requireReview is a merge blocker, not a component; a row may not switch it off. The reviewer row is conditional, not a way to weaken the gate. | none | none may exist |
+| the merge gates | gates.* decides delivery; a component may not bypass it. | none | none may exist |
+
+## Gateable tools
+
+The allowlist of boolean routes in `host/tool-registry.js`. Every shipped
+`tools.expose*` route must match this table. A route to a tool that is not listed
+here is refused, so no boolean key can quietly remove a review, merge or host
+tool. Since #122 the shipped table is empty: `tower_doctor` and `tower_recover`
+are registered for every configuration and no other capability may become a
+boolean switch.
+
+| Tool | Switch key |
+|---|---|
+| _(none)_ | — |
+
+## Config keys
+
+All keys from `domain/config/schema.js`, classified on the component axis.
+
+| Key | Component class | Decision note |
+|---|---|---|
+| `section` | `core` | Legacy alias for mode.promptSection: the Tower-mode prompt contract, not a capability. |
+| `allowAgentControl` | `core` | Legacy alias for mode.allowAgentControl: the human-owned mode rule (ADR 0003), not a component. |
+| `init.autoGitInit` | `optional-config` | Bootstrap convenience; off only means tower_init will not run git init. |
+| `init.snapshotDirty` | `optional-config` | Dirty-work baseline convenience; no capability is removed. |
+| `init.autoExclude` | `optional-config` | Keeps Tower artifacts out of .git/info/exclude; safe either way. |
+| `mode.promptSection` | `core` | Replaces the whole Tower-mode prompt text; contract text, not a capability. |
+| `mode.sectionAppend` | `optional-config` | Appends team conventions to the prompt. |
+| `mode.allowAgentControl` | `core` | Decides whether the model may toggle the mode (ADR 0003). A governance rule, never a component. |
+| `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; a row may not turn it off. |
+| `mode.workspaceLockScope` | `optional-config` | Chooses whether read-only tools take the workspace lock. |
+| `mode.planModePolicy` | `core` | Plan mode and Tower mode stay mutually exclusive. |
+| `mode.workspaceStaleMs` | `optional-config` | Stale window for the advisory workspace lock. |
+| `mode.heartbeatMs` | `optional-config` | Heartbeat interval while the mode is on. |
+| `mode.denyTools` | `core` | The denied-tool list is part of the mode guard. |
+| `mode.storePath` | `optional-config` | Custom mode-store location; no capability is removed. |
+| `mode.maxEntries` | `optional-config` | Bounds the persisted mode store. |
+| `mode.lockTimeoutMs` | `optional-config` | Bounded wait for the cross-process mode lock. |
+| `review.requireReview` | `forbidden-to-disable` | Turns independent review into a merge blocker; no component may switch it off. With it on, the preset-tower-reviewer row may not be off (planning/mode entry refuse the combination). |
+| `review.maxRoundsPerReviewer` | `forbidden-to-disable` | Caps review rounds; part of the review contract. |
+| `merge.timeoutMs` | `optional-config` | Default merge timeout; a per-call value wins. |
+| `merge.maxBufferBytes` | `optional-config` | Captured merge output buffer. |
+| `git.timeoutMs` | `optional-config` | Default Git command timeout outside merge. |
+| `worktrees.root` | `optional-config` | Default worktree placement. |
+| `spawn.workerPreset` | `core` | Chooses the worker tool surface; a dependency, never a switch. |
+| `spawn.reviewerPreset` | `core` | Chooses the read-only reviewer surface; a dependency, never a switch. |
+| `spawn.maxDepth` | `optional-config` | Subagent depth requested at spawn. |
+| `spawn.provider` | `optional-config` | Provider route for spawned agents. |
+| `spawn.workerModel` | `optional-config` | Optional model route for workers. |
+| `spawn.reviewerModel` | `optional-config` | Optional independent model route for reviewers. |
+| `spawn.maxLiveWorkers` | `core` | Resource-safety cap on live workers. |
+| `spawn.staleMs` | `optional-config` | Roster staleness window before merge is blocked. |
+| `spawn.maxWaitMs` | `optional-config` | Upper bound for a blocking spawn wait. |
+| `spawn.requireLease` | `optional-config` | Advisory-lease gate before a worker starts. |
+| `send.maxPerMinute` | `optional-config` | Message rate limit; zero disables it. |
+| `send.interruptDefault` | `optional-config` | Default for the interrupt-before-deliver flag. |
+| `tests.enabled` | `optional-component` | Tuning inside the optional tower-tests component: it decides whether discovery runs when the row is on. Off with gates.requireTests:true is rejected at config resolution. |
+| `tests.admission` | `optional-config` | Chooses when discovery runs inside the optional tests capability. |
+| `tests.timeoutMs` | `optional-config` | Per-command discovery timeout. |
+| `tests.maxBytes` | `optional-config` | Captured discovery output cap. |
+| `tests.autoChecks` | `optional-config` | Attaches a tests check to completion when discovery runs. |
+| `tests.allowPackageDiscovery` | `core` | Allows repository code to execute; a security contract, not a component. |
+| `gates.requireChecks` | `forbidden-to-disable` | Requires completion evidence before merge; a merge gate. |
+| `gates.requireTests` | `forbidden-to-disable` | Requires a test receipt before merge; a merge gate. With the tower-tests row off, planning/mode entry refuse the combination. |
+| `gates.allowReviewExemption` | `forbidden-to-disable` | The review-exemption path is part of the review and merge contract. |
+| `gates.maxReportBytes` | `forbidden-to-disable` | The report cap is part of the completion contract; the refusal itself is never configurable away. |
+| `docs.board` | `optional-config` | Writes the human-readable board; no capability is removed. |
+| `docs.boardLocation` | `optional-config` | Chooses the board location. |
+| `archive.enabled` | `optional-config` | Archival is maintenance, not a tool capability; off only leaves terminal missions hot. |
+| `archive.afterDays` | `optional-config` | Archive age threshold. |
+| `archive.maxMissions` | `optional-config` | Hot terminal-mission cap. |
+| `leases.ttlMs` | `optional-config` | Tuning inside the optional tower-leases component. |
+| `dev.reloadDelayMs` | `optional-config` | Delay so a tool result is delivered before a scheduled reload inside the optional tower-hmr component. |
+| `dev.reloadRequiredIds` | `optional-config` | Loader ids passed to reconcileProfile as required by the tower-hmr component. |
+
+## Non-goals
+
+This page does not decide whether a key is useful, and it is not an approval
+process. It records the class so the gate can refuse an unclassified or
+forbidden surface.
+
+Enforced by: `scripts/check-components.mjs`; tests in `tests/components.test.mjs`; gate: `npm run docs:check:components`.

package/docs/reference/config.generated.md

@@ -1,6 +1,7 @@
 # Config reference (generated)
 
 > Generated by `npm run docs:generate:config` from `domain/config/schema.js`. Values are defaults before repo config.
+> Surface: config keys: 56 · sections: 14 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
 
 | Key | Default | Description |
 |---|---|---|
@@ -57,14 +58,6 @@
 | `archive.enabled` | `true` | Move terminal (merged/abandoned) missions whose worktree is gone into <git-common-dir>/dsh-tower/archive/ at the next mutation, so state.json stops carrying their full history. |
 | `archive.afterDays` | `30` | Terminal missions untouched for at least this many days are archived on the next mutation (0 archives them immediately). |
 | `archive.maxMissions` | `100` | Maximum terminal missions kept hot; once exceeded, the oldest eligible terminal missions are archived until the cap holds (0 archives every eligible terminal mission). |
-| `tools.exposeOperational` | `true` | Master switch for batch/resource/import/legacy/recover/test/doctor tools. |
-| `tools.exposeBatch` | `true` | Register tower_batch. |
-| `tools.exposeImport` | `true` | Register tower_import_legacy/tower_legacy_map. |
-| `tools.exposeLeases` | `true` | Register tower_resource advisory leases. |
-| `tools.exposeTests` | `true` | Register tower_test; gates.requireTests requires it. |
-| `tools.exposeRecovery` | `true` | Register tower_recover (stale state-lock escape). |
-| `tools.exposeDoctor` | `true` | Register tower_doctor (read-only health contract). |
 | `leases.ttlMs` | `900000` | Default advisory lease lifetime; expiry never auto-releases. |
-| `dev.hotReload` | `true` | Register tower_reload and /tower reload when the DSH HMR service is available. |
 | `dev.reloadDelayMs` | `50` | Delay before a scheduled reload, so the tool result is delivered first. |
-| `dev.reloadRequiredIds` | `["tower-bundle","tower","tower-skills","preset-tower-worker","preset-tower-reviewer"]` | Loader entry ids passed to reconcileProfile as required. |
+| `dev.reloadRequiredIds` | `["tower","tower-host","preset-tower-worker"]` | Loader entry ids passed to reconcileProfile as required. Optional component rows are deliberately not required, so a row switched off is not a reload failure. |

package/docs/reference/config.md

@@ -74,14 +74,14 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `spawn.requireLease` | `''` | Optional lease name that must be held before a worker can spawn. |
 | `send.maxPerMinute` | `120` | Per-repository `tower_send` rate limit (0 disables); exceeding it returns `rate-limited`. |
 | `send.interruptDefault` | `false` (bundled patch: `true`) | Default for `tower_send.interrupt` (interrupt the running turn before delivering). |
-| `tests.enabled` | `true` | Run declared test discovery when the worktree `package.json` configures it. |
+| `tests.enabled` | `true` | Run declared test discovery when the worktree `package.json` configures it. It only tunes the optional `tower-tests` component: with that row off there is no `tower_test` tool and no receipt, and `gates.requireTests:true` is refused rather than silently unmet. |
 | `tests.admission` | `off` | `spawn` runs discovery before starting a worker, `complete` at `tower_complete`, `off` only on explicit `tower_test` (default; repository code is not executed automatically). |
 | `tests.timeoutMs` | `60000` | Per discovery command timeout. |
 | `tests.maxBytes` | `16777216` (16 MiB) | Captured stdout cap per command. |
 | `tests.autoChecks` | `true` | Attach an automatic `tests` check to the completion report. |
 | `tests.allowPackageDiscovery` | `true` | Allow repo-controlled `tower.testDiscovery` commands (executes worktree code; see security). |
 | `gates.requireChecks` | `false` | Require at least one `tower_complete.checks` entry before merge (`no-check-evidence`). |
-| `gates.requireTests` | `false` | Require a passing discovery receipt for the current mission branch tip (`tests-missing`); independent of the review gate. |
+| `gates.requireTests` | `false` | Require a passing discovery receipt for the current mission branch tip (`tests-missing`); independent of the review gate. With the `tower-tests` component row off, planning/mode entry refuse this combination with an explanation. |
 | `gates.allowReviewExemption` | `false` | With `review.requireReview:true`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant while the global review gate is off. |
 | `gates.maxReportBytes` | `32768` (32 KiB) | Hard cap in UTF-8 bytes for `tower_complete.report`. A larger report is rejected with `invalid-argument` and an actionable `nextAction` (file the full text in the mission worktree and reference its path); it is never truncated. Existing larger reports still load. |
 | `docs.board` | `true` | Write `MISSIONS.md` after mutations. |
@@ -89,16 +89,14 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `archive.enabled` | `true` | Move terminal (`merged`/`abandoned`) missions whose worktree is gone into `<git-common-dir>/dsh-tower/archive/` at a mutation boundary. Archived missions keep tasks, reviews, findings and the completion report; they are moved, never deleted. |
 | `archive.afterDays` | `30` | Age trigger: a terminal mission untouched for at least this many days is archived on the next mutation (`0` archives immediately). |
 | `archive.maxMissions` | `100` | Cap trigger: once more than this many terminal missions are hot, the oldest eligible ones are archived until the cap holds (`0` archives every eligible terminal mission). A mission with a live worktree is never archived. |
-| `tools.exposeOperational` | `true` | Register batch/resource/import/legacy/recover/test/doctor tools; `false` shrinks the fixed tool-schema context. |
 | `leases.ttlMs` | `900000` | Default advisory lease lifetime; expiry never auto-releases. |
-| `dev.hotReload` | `true` | Register `tower_reload`; `/tower reload` is disabled when off. It returns `reload-unavailable` when the profile has no HMR service. |
-| `dev.reloadDelayMs` | `50` | Delay before a scheduled reload so the tool result is delivered first. |
-| `dev.reloadRequiredIds` | five Tower loader ids | Entry ids passed to `reconcileProfile` as required. |
+| `dev.reloadDelayMs` | `50` | Delay before a scheduled reload so the tool result is delivered first. Tuning inside the optional `tower-hmr` component. |
+| `dev.reloadRequiredIds` | three Tower loader ids | Entry ids passed to `reconcileProfile` as required by the `tower-hmr` component. Optional component rows are deliberately not required. |
 
 ## Example
 
 ```yaml
-- id: tower
+- id: tower-host
   name: 'dsh-tower'
   config:
     mode:
@@ -113,10 +111,14 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
       reviewerModel:
         provider: deepseek-account
         model: deepseek-flash
-    dev:
-      hotReload: true
 ```
 
+The optional capabilities (`tower-skills`, `tower-batch`, `tower-import`,
+`tower-leases`, `tower-tests`, `tower-hmr`, `preset-tower-reviewer`) are switched
+from the plugin page, not from a config key. The keys that used to switch them
+(`tools.expose*`, `dev.hotReload`) were removed in 2.4.0 and are rejected as
+unknown keys.
+
 ## Looking up the effective schema
 
 `cordis_inspect_query` with `Config.listConfigs({ name: "dsh-tower" })` returns the projected JSON

package/docs/reference/doctor.md

@@ -8,10 +8,35 @@ It returns:
   "ok": true,
   "checks": [
     { "id": "git", "status": "pass", "detail": "git version 2.55.0" },
+    { "id": "surface", "status": "pass", "detail": "config keys: 56 · sections: 14 · tools: 29 (baseline 2026-10-23)" },
     { "id": "state", "status": "pass", "detail": ".../state.json revision 7" },
     { "id": "state-schema", "status": "pass", "detail": "schemaVersion 3 is current" },
     { "id": "case-mode", "status": "pass", "detail": "caseInsensitive: true; scope matching uses case-insensitive comparison" }
   ],
+  "surface": {
+    "configKeys": 56,
+    "sections": 14,
+    "tools": 29,
+    "baselineDate": "2026-10-23",
+    "line": "config keys: 56 · sections: 14 · tools: 29"
+  },
+  "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
+  },
   "stateSchema": {
     "currentVersion": 3,
     "supportedVersion": 3,
@@ -40,6 +65,19 @@ It returns:
 }
 ```
 
+`surface` (and the `surface` check) reports the concept budget in the same format
+as the generated references: `config keys: N · sections: N · tools: N`, plus the
+committed baseline date from `scripts/surface-baseline.json`. The counts are live:
+the config schema and every tool the build ships — `define()`-registered tools,
+the `tower_mode`/`tower_control` pair the Host entry registers directly (#118),
+and the capability tools whose optional component row may be off (#121) —
+independent of the operational switches. The `tools` count is therefore the full
+build surface (29 in 2.4.0), even though the shipped profile mounts 28 because
+`tower-hmr` ships off; the `components` check names the mounted subset and every
+disabled row. `npm run surface:check` is what fails when a count grew without an
+ADR, a matching deletion or a recorded measurement correction. See
+[surface-budget.md](surface-budget.md) for the classification table.
+
 `stateSchema` describes the file **on disk**, not the in-memory document: `currentVersion` is the
 `schemaVersion` doctor read, `supportedVersion` is the build's `SCHEMA_VERSION`, and `migrations` is
 the ordered v→v path a write would apply (`[]` when current). `status` is one of `current`,
@@ -49,6 +87,19 @@ and keeps a `state.json.v<N>.bak` backup). A file written by a newer plugin repo
 `fail`: this build refuses to downgrade it. A state-load failure is reported as a failed check rather
 than thrown so doctor remains useful on a broken repository.
 
+`stateLock` (and the `state-lock` check) reports the held lock's age (`ageMs`, from the record's
+`since`) and heartbeat freshness (`heartbeatAgeMs`, from its last `at`) against the stale window
+(`staleAfterMs = 3 × 1000 ms`). A live PID is not proof of a live writer: a holder that stopped
+heartbeating is reported as `stale: true` and is reclaimable by the next mutation (or by
+`tower_recover clear-stale-lock force:true`), while a fresh heartbeat is reported as held and is never
+stolen. This is what makes a recycled PID diagnosable without reading `state.lock` by hand.
+
+`gitLock` (and the `git-lock` check) reports the repo-scoped git mutex: `{held, pid, phase, heldMs}`
+while a merge/rebase/init/teardown/provision holds it, and `{held: false}` when free. A merge may hold
+it for the configured merge timeout (15 minutes by default), so a held lock is a `warn` rather than a
+failure; the holder's phase and age make a stalled tower diagnosable. `tower_status` returns the same
+`gitLock` object.
+
 `archive` reports the terminal-mission archive: active `missions`, `archivedMissions` and `stateBytes`,
 the archive directory's `archiveBytes`/`years`/`files`, every `unreadable` diagnostic, and the configured
 `policy` (`enabled`, `afterDays`, `maxMissions`). A missing archive directory is a healthy empty archive
@@ -68,8 +119,8 @@ never probes — a probe creates a temporary file, and a read-only call must not
 applies.
 
 Checks cover: git availability, repository identity, state schema/load, the detected case mode, repo
-config presence, worker/reviewer preset names, subagents and HMR services, workspace lock
-holder/staleness, live roster, worktree existence/ownership/dirtiness, test-discovery policy, legacy
+config presence, worker/reviewer preset names, subagents and HMR services, state lock age/heartbeat,
+workspace lock holder/staleness, live roster, worktree existence/ownership/dirtiness, test-discovery policy, legacy
 snapshots, batches and leases. Missions intentionally cleaned up by `tower_teardown` are skipped (the
 check notes the removed count) instead of being reported as missing.
 `warn` is advisory; `fail` means the repository needs attention before spawning/merging.

package/docs/reference/errors.generated.md

@@ -2,40 +2,44 @@
 
 > Generated by `npm run docs:generate:errors` from `domain/errors.js`. Do not edit by hand.
 
-| Code | Description |
-|---|---|
-| `invalid-argument` | A tool argument is missing, malformed, or not allowed. |
-| `repo-invalid` | repoRoot is missing, relative, or not inside a Git repository. |
-| `not-initialized` | Tower is not initialized for this repository; run tower_init. |
-| `mission-not-found` | No mission with that id exists. |
-| `finding-not-found` | No finding with that id exists. |
-| `invalid-transition` | The requested state transition is not allowed. |
-| `stale-base` | The repository state changed while the operation was being prepared; retry. |
-| `state-locked` | Another Tower writer holds the state lock. |
-| `state-corrupt` | The Tower state file is unreadable or invalid. |
-| `state-version-unsupported` | The Tower state file uses a schema version this build cannot read or downgrade. |
-| `state-migration-failed` | A Tower state migration failed; the original state file was not modified. |
-| `config-invalid` | Tower configuration is invalid. |
-| `config-unknown-key` | Tower configuration has an unknown top-level key. |
-| `git-failed` | A git command failed. |
-| `git-timeout` | A git command timed out or exceeded its output buffer. |
-| `worktree-dirty` | The mission worktree has uncommitted changes and cannot complete. |
-| `spawn-unavailable` | The subagents service is unavailable. |
-| `provider-missing` | No subagent provider is registered. |
-| `provider-cooldown` | The provider is throttled; spawn is in a short cooldown. |
-| `preset-missing` | The configured agent preset is not registered. |
-| `reviewer-prerequisite` | The reviewer spawn prerequisite is not met. |
-| `not-authorized` | The calling agent role may not perform this action. |
-| `workspace-busy` | Another Tower session owns this repository workspace lock. |
-| `worker-limit` | The repository reached spawn.maxLiveWorkers live workers. |
-| `rate-limited` | The tower_send per-minute rate limit was reached. |
-| `takeover-refused` | The mission already has a live worker that was not stopped first. |
-| `reload-unavailable` | The DSH HMR service is not available in this profile. |
-| `reload-failed` | The HMR reload failed; check the DSH log and restart if needed. |
-| `tests-failed` | Declared test discovery failed or did not meet its admission requirements. |
-| `tests-timeout` | Test discovery exceeded its time or output budget. |
-| `lease-busy` | Another holder owns the requested advisory lease. |
-| `lease-token` | The lease release token does not match the current holder. |
-| `batch-invalid` | The batch request or its close evidence is invalid. |
-| `legacy-invalid` | The legacy snapshot or mapping is invalid. |
-| `tool-internal` | An unexpected failure; read the message and the activity log. |
+The catalog is the source of truth for the stable codes and the recovery metadata the tool boundary
+renders: `retryable` marks a failure that can succeed later unchanged, and `nextAction` is the
+single recovery step appended to the message as ` — next: …` (with ` (retryable)` when retryable).
+
+| Code | Meaning | Retryable | Next action |
+|---|---|---|---|
+| `invalid-argument` | A tool argument is missing, malformed, or not allowed. | no | — |
+| `repo-invalid` | repoRoot is missing, relative, or not inside a Git repository. | no | pass an absolute path to a directory inside a Git repository |
+| `not-initialized` | Tower is not initialized for this repository; run tower_init. | no | run tower_init for this repository |
+| `mission-not-found` | No mission with that id exists. | no | list missions with tower_status |
+| `finding-not-found` | No finding with that id exists. | no | list findings with tower_findings |
+| `invalid-transition` | The requested state transition is not allowed. | no | — |
+| `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 |
+| `state-locked` | Another Tower writer holds the state lock. | yes | wait for the other Tower writer to finish, then retry |
+| `state-corrupt` | The Tower state file is unreadable or invalid. | no | restore state.json from a backup, or re-initialize after filing the corruption |
+| `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 |
+| `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 |
+| `config-invalid` | Tower configuration is invalid. | no | fix the repository config file, then retry |
+| `config-unknown-key` | Tower configuration has an unknown top-level key. | no | remove the unknown key from the repository config file, then retry |
+| `git-failed` | A git command failed. | no | — |
+| `git-timeout` | A git command timed out or exceeded its output buffer. | yes | retry; if it persists, raise git.timeoutMs or merge.timeoutMs |
+| `worktree-dirty` | The mission worktree has uncommitted changes and cannot complete. | no | commit or remove the worktree changes, then retry tower_complete |
+| `spawn-unavailable` | The subagents service is unavailable. | no | enable the DSH subagents service, then retry |
+| `provider-missing` | No subagent provider is registered. | no | register a subagent provider in the DSH profile, then retry |
+| `provider-cooldown` | The provider is throttled; spawn is in a short cooldown. | yes | wait for the cooldown to expire, then retry |
+| `preset-missing` | The configured agent preset is not registered. | no | install the tower-worker and tower-reviewer agent presets and restart DSH |
+| `reviewer-prerequisite` | The reviewer spawn prerequisite is not met. | no | complete the mission first, then spawn the reviewer |
+| `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 |
+| `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 |
+| `worker-limit` | The repository reached spawn.maxLiveWorkers live workers. | no | wait for a live worker to finish or raise spawn.maxLiveWorkers |
+| `rate-limited` | The tower_send per-minute rate limit was reached. | yes | wait for the next per-minute window or raise send.maxPerMinute |
+| `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 |
+| `reload-unavailable` | The DSH HMR service is not available in this profile. | no | restart DSH instead of reloading |
+| `reload-failed` | The HMR reload failed; check the DSH log and restart if needed. | no | check the DSH log and restart DSH |
+| `tests-failed` | Declared test discovery failed or did not meet its admission requirements. | no | fix the failing tests, then retry tower_complete |
+| `tests-timeout` | Test discovery exceeded its time or output budget. | no | raise tests.timeoutMs or tests.maxBytes (or speed up the suite), then retry |
+| `lease-busy` | Another holder owns the requested advisory lease. | no | release the lease or wait for it to expire, then retry |
+| `lease-token` | The lease release token does not match the current holder. | no | use the token returned when the lease was acquired |
+| `batch-invalid` | The batch request or its close evidence is invalid. | no | fix the batch request or the receipt hashes, then retry |
+| `legacy-invalid` | The legacy snapshot or mapping is invalid. | no | check the legacy snapshot path, schema and mapping, then retry |
+| `tool-internal` | An unexpected failure; read the message and the activity log. | no | — |