dsh-tower 2.1.0-beta.1 → 2.3.0

package/docs/reference/doctor.md

@@ -8,26 +8,122 @@ It returns:
   "ok": true,
   "checks": [
     { "id": "git", "status": "pass", "detail": "git version 2.55.0" },
-    { "id": "state", "status": "pass", "detail": ".../state.json revision 7" }
+    { "id": "surface", "status": "pass", "detail": "config keys: 64 · sections: 15 · tools: 27 (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": 64,
+    "sections": 15,
+    "tools": 27,
+    "baselineDate": "2026-10-23",
+    "line": "config keys: 64 · sections: 15 · tools: 27"
+  },
+  "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,
+    "migrations": [],
+    "status": "current"
+  },
+  "archive": {
+    "missions": 3,
+    "archivedMissions": 12,
+    "stateBytes": 48211,
+    "archiveBytes": 190244,
+    "years": [2026],
+    "files": 2,
+    "unreadable": [],
+    "policy": { "enabled": true, "afterDays": 30, "maxMissions": 100 }
+  },
   "environmentContract": {
     "platform": "win32",
     "gitVersion": "git version 2.55.0",
     "repoRoot": "D:/repo",
     "commonDir": "D:/repo/.git",
-    "stateDir": "D:/repo/.git/dsh-tower"
+    "stateDir": "D:/repo/.git/dsh-tower",
+    "caseInsensitive": true,
+    "comparisonMode": "case-insensitive"
   }
 }
 ```
 
+`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 the defined tool surface, independent of the operational
+switches); `npm run surface:check` is what fails when a count grew without an ADR
+or a matching deletion. 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`,
+`migratable`, `newer`, `unmigratable`, `invalid`. Doctor never migrates, so a `migratable` file stays
+byte-identical and the `state-schema` check is a `warn` (the next locked write applies the migration
+and keeps a `state.json.v<N>.bak` backup). A file written by a newer plugin reports `newer` and a
+`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
+(`archive` check `pass`); a truncated index or year file is a `warn` with the diagnostic, and archiving is
+paused until it is repaired rather than overwriting it. Nothing is lost while the archive is unreadable:
+the eligible missions stay in `state.json`.
+
 Checks cover: git availability, repository identity, state schema/load, repo config presence,
 worker/reviewer preset names, subagents and HMR services, workspace lock holder/staleness, live roster,
-worktree existence/ownership/dirtiness, test-discovery policy, legacy snapshots, batches and leases.
-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. A state-load
-failure is reported as a failed check rather than thrown so doctor remains useful on a broken
-repository.
+worktree existence/ownership/dirtiness, test-discovery policy, completion-report sizes, archive health, legacy`nsnapshots, batches and leases. Missions intentionally cleaned up by `tower_teardown` are skipped (the check`nnotes the removed count) instead of being reported as missing.
+
+`caseInsensitive` is the mode `tower_init` detected once on the checkout's filesystem; `null` means
+"not detected yet" and the `case-mode` check is a `warn`. `comparisonMode` is the comparison scope
+matching actually uses: `case-insensitive` folds both sides, `case-sensitive` stays byte-exact. Doctor
+never probes — a probe creates a temporary file, and a read-only call must not write. Run
+`tower_init` on a writable checkout to record the mode; until then the safe `case-sensitive` default
+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, 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.
+
+The `reports` check names the largest completion report in the repository (`<bytes> B on <mission>`,
+against the `gates.maxReportBytes` cap); the same numbers are returned as
+`reports: { count, largest: { missionId, bytes } | null, capBytes }`. Reports written before the cap
+only produce a `warn`; doctor never rewrites them.
 
 The environment contract is informational; it is not an identity or authorization proof. `tower_init`
 still requires the tower role, and `tower_spawn` still checks the live subagent catalog.

package/docs/reference/errors.generated.md

@@ -2,38 +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. |
-| `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 | — |

package/docs/reference/errors.md

@@ -2,54 +2,68 @@
 
 Tool failures are thrown errors, not `{ok:false}` results (gate outcomes are the exception: see
 [blockers.md](blockers.md)). Every thrown error carries a stable code as a message prefix. This
-release defines 33 tool error codes.
+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` |
-| `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`.