dsh-tower 2.1.0 → 2.3.0

package/docs/architecture/overview.md

@@ -10,7 +10,7 @@ or skill can remain mounted while the `tower_*` tools are gone.
 ```
 Host plugin (index.js)
  ├─ /tower command + Tower mode (guard, prompt section, tower_mode/tower_control, /tower reload)
- ├─ lib/tool-registry.js -> registration aggregator, actor guards, shared helpers
+ ├─ host/tool-registry.js -> registration aggregator, actor guards, shared helpers
  │                    (+ 27 registered repository tools)
  │                    (+ tower_reload while dev.hotReload is on; fails reload-unavailable without HMR)
  ├─ tools/index.js  -> thin public wiring (re-exports the registry + briefings)
@@ -18,20 +18,37 @@ Host plugin (index.js)
        ├─ app/init.js, provision.js, merge.js, rebase.js, teardown.js
        ├─ app/review.js, findings.js, batch.js, messages.js, roster.js
        ├─ app/plan.js, mission.js, checkCompletion.js, spawn.js, recording.js
-       └─ app/gate.js, read.js, board.js, missionContext.js, enrichedMissions.js
- ports (explicit contracts):
-       ports/store.js vcs.js clock.js ids.js
- adapters (the only I/O):
-       adapters/store-fs.js   the only module importing node:fs
-       adapters/vcs-git.js    the only module importing node:child_process
-       adapters/default.js    composition root: store, vcs, clock, ids
- infrastructure (lib/):
-       lib/store.js           repo-scoped lock + atomic JSON + activity.jsonl
-       lib/git.js             bounded git commands + timeout classification
-       lib/config.js          profile/repo config layers over the pure schema
-       lib/workspaceLock.js   optional one-Tower-session-per-repository advisory lock
-       lib/hmr.js             optional DSH HMR bridge (tower_reload / /tower reload)
-       lib/modeStore.js       per-agent Tower mode persistence
+       ├─ app/spawn-prechecks.js, spawn-support.js, briefing.js
+       └─ app/archive.js, gate.js, read.js, board.js, missionContext.js, enrichedMissions.js
+ host (composition root + process/session glue; the only layer that may hold ambient state):
+       host/tool-registry.js   registration aggregator + shared guards/helpers
+       host/config.js          profile/repo config layers over the pure schema
+       host/doctor.js          read-only environment contract and health checks
+       host/hmr.js             optional DSH HMR bridge (tower_reload / /tower reload)
+       host/modeStore.js       per-agent Tower mode persistence
+       host/modeState.js       owned in-memory mode state
+       host/presets.js         cross-field preset validation before work starts
+       host/compatibility.js   COMPATIBILITY.md provenance
+       host/tower.js           default-deps Tower binding for tests/embedders
+ ports (explicit runtime contracts, no implementation):
+       ports/contract.js      definePort/assertPort runtime contract primitives
+       ports/{store,vcs,clock,ids,config,state,ownership,caseSensitivity,archive}.js
+       ports/index.js         PORTS table + assertPorts(deps) injection check
+ adapters (the only I/O; they implement the ports):
+       adapters/store-fs.js   the only module importing node:fs; createStorePort()
+       adapters/vcs-git.js    the only module importing node:child_process; createVcsPort()
+       adapters/git.js        bounded git commands + timeout classification
+       adapters/store.js      repo-scoped lock + atomic JSON + activity.jsonl
+       adapters/persistence.js  shared atomic write / lock / heartbeat primitives
+       adapters/archive.js    terminal-mission archive files
+       adapters/leases.js     repo-scoped advisory lease ledger
+       adapters/workspaceLock.js  optional one-Tower-session-per-repository lock
+       adapters/worktreeOwnership.js  worktree identity verification
+       adapters/stateFile.js  state-file load/migrate/persist
+       adapters/caseSensitivity.js  filesystem case-folding probe
+       adapters/legacy.js     read-only legacy snapshot validation + storage
+       adapters/tests.js      test discovery execution + TAP/JSON parsing
+       adapters/default.js    createDefaultDeps(): the one default port implementation set
  pure domain modules (no fs/git):
        domain/errors.js     stable, structural tool error catalog
        domain/batch.js      batch admission create/close/summary validation
@@ -48,7 +65,6 @@ Host plugin (index.js)
        domain/report.js     board rendering
        domain/roster.js     roster predicates
  tools layer:
-       lib/tool-registry.js     registration aggregator + shared guards/helpers
        tools/index.js           thin public wiring (re-exports only)
        tools/*.js               one module per tool, handler + imported input schema
  Subagents
@@ -61,6 +77,54 @@ The main checkout is the control-tower repo; each mission has a branch `tower/<i
 worktree in `.dsh-tower-worktrees/<hash>/<missionId>`. The plugin never operates on the main checkout's
 working tree except merge and the read-only diff.
 
+## Ports and the composition root (#69)
+
+The seam is real, not documented-only. `ports/` exports **runtime contracts**: each module defines a
+frozen `{ name, methods }` descriptor plus an `assert*Port` helper, and `ports/index.js` exposes the
+`PORTS` table and `assertPorts(deps)`.
+
+`app/**` imports only app siblings, `domain/**`, `ports/**` and `node:path`. Every effectful call goes
+through the `deps` object:
+
+| deps member | contract | default implementation |
+|---|---|---|
+| `store` | StorePort: `pathsFor/exists/ensureDir/readJson/writeJsonAtomic/appendJsonl/withLock/withGitLock/readActivityTail` plus the raw-file and lock primitives `readText/writeText/appendText/rename/renameWithRetry/stat/unlink/readGitLock/gitLockView` | `adapters/store-fs.js` `createStorePort()` |
+| `vcs` | VcsPort: `git/tryGit/revParse/isClean/isAncestor/resolveRepo/currentBranch/countCommits/listWorktrees` | `adapters/vcs-git.js` `createVcsPort()` |
+| `clock`, `ids` | ClockPort / IdsPort | `adapters/default.js` |
+| `config` | ConfigPort: `runtimeConfig/resolveRepoConfig` | `host/config.js` |
+| `state` | StatePort: `loadStateFile` | `adapters/stateFile.js` |
+| `archive` | ArchivePort: `readIndex/readEntry/writeEntries` | `adapters/archive.js` |
+| `ownership` | OwnershipPort: `assertOwnership/canonicalPath` | `adapters/worktreeOwnership.js` |
+| `caseSensitivity` | CaseSensitivityPort: `detect` | `adapters/caseSensitivity.js` |
+
+`index.js` is the composition root: it calls `createDefaultDeps()` once and passes the object to
+`registerTowerTools`. The registry adopts and validates that object (`assertPorts`) instead of building
+its own adapter set, hands every tool an `openTower(repoRoot)` factory bound to those ports, and
+`Tower.open(repoRoot, deps)` / `new Tower(repo, config, deps)` validates the object again before use.
+`app/tower.js` itself imports no adapter and no `host/` module. The one piece of lock policy the app and
+the store share (the git-mutex budget, #93) is pure and lives in `domain/lockBudget.js`;
+`adapters/store.js` re-exports it for the infrastructure callers.
+
+`store.rename` and `store.renameWithRetry` are both declared because they are not interchangeable: the
+retrying helper has temp-file semantics and removes its source when the rename finally fails, which is
+right for a disposable temp file but would destroy the lock bytes `tower_recover` must keep auditable.
+The audit rename therefore uses the plain `rename`. The contract test scans `app/**` **and** `tools/**`
+for every `deps.<port>.<method>` call and fails if the named port does not declare it, so a tool that
+reaches a new port method cannot slip past `assertPorts`.
+
+`lib/` no longer exists (#70): every module was `git mv`-ed into the layer that owns it. The I/O
+implementations now sit in `adapters/` (`store`, `persistence`, `git`, `archive`, `stateFile`,
+`leases`, `workspaceLock`, `worktreeOwnership`, `caseSensitivity`, `legacy`, `tests`), the
+composition root and process/session glue in `host/`, and spawn policy in `app/`. `host/**` is the
+only source root, besides `adapters/**` itself, allowed to import an adapter; `app/**` and `domain/**`
+may not import `lib/**` (rule `no-lib-from-core`) and may not hold ambient module state
+(`host-scope`). Tools receive effectful helpers from the registry instead of importing an adapter.
+
+A full mission lifecycle (init → plan → provision → spawn → complete → review → gate → merge →
+teardown) runs through the real app use cases on an in-memory store and a scripted vcs:
+`tests/ports-lifecycle.test.mjs`. The default adapter set and the in-memory doubles are both asserted
+against the same port contracts in `tests/memory-adapters.contract.test.mjs`.
+
 ## Mission state machine
 
 ```
@@ -82,7 +146,7 @@ set by `tower_merge`/reconciliation.
    against the merge base.
 3. Survey missions must not change files; build missions must stay inside `scope`.
 4. The main checkout must be clean for the files this merge would overwrite and on the base branch.
-5. Dependency missions must be merged/abandoned.
+5. Dependency missions must be merged/abandoned, except a completed survey dependency which is its terminal success state (#107).
 6. If `review.requireReview:true` (default false), a review must exist, belong to this mission, be
    clean, approve merge, and be bound to the tip (unless a clean rebase waived it). No worker may be
    running.
@@ -105,7 +169,7 @@ After the command, regardless of exit status, it inspects `HEAD`:
 | `<git-common-dir>/dsh-tower/archive/index.json` | compact terminal-mission index (ids, status, branch, timestamps) |
 | `<git-common-dir>/dsh-tower/archive/<year>.json` | full archived missions plus their linked reviews/findings |
 | `<git-common-dir>/dsh-tower/activity.jsonl` | append-only activity |
-| `<git-common-dir>/dsh-tower/state.lock` | single-writer state lock (dead-PID reclaimed, live lock reported) |
+| `<git-common-dir>/dsh-tower/state.lock` | single-writer state lock (heartbeat reclaim; a recycled PID cannot pin it) |
 | `<git-common-dir>/dsh-tower/git.lock` | repo-scoped serialization for git mutations outside the state lock |
 | `<git-common-dir>/dsh-tower/lock-holds.jsonl` | state/git lock-hold telemetry |
 | `<checkout parent>/.dsh-tower-worktrees/<hash>/<missionId>` | mission worktree |
@@ -113,8 +177,10 @@ After the command, regardless of exit status, it inspects `HEAD`:
 | `$DSH_HOME/tower-mode/modes.lock` | mode-store single-writer lock |
 
 `state.json` and `modes.json` both use an atomic write (temp + rename), token-checked lock release,
-dead-PID reclamation, and bounded lock waits. `state.json` is the mission persistence contract;
-`modes.json` is the per-agent mode contract; neither is written without its own lock.
+heartbeat-based reclamation (a live PID with a silent heartbeat is reclaimed after byte verification;
+a live holder that keeps heartbeating is never stolen), and bounded lock waits. `state.json` is the
+mission persistence contract; `modes.json` is the per-agent mode contract; neither is written without
+its own lock.
 
 ## Layering rules
 
@@ -123,17 +189,66 @@ dead-PID reclamation, and bounded lock waits. `state.json` is the mission persis
 - `domain/**` must not import I/O or adapters (`domain-pure`).
 - Only `adapters/vcs-git.js` may import `node:child_process`, and only
   `adapters/store-fs.js` may import `node:fs` (`child-process-surface`, `fs-surface`).
-  The rule is enforced over the source roots — `lib/`, `app/`, `domain/`, `tools/`,
+  The rule is enforced over the source roots — `host/`, `app/`, `domain/`, `tools/`,
   `adapters/`, `ports/` — and does not cover `scripts/**`, which holds maintenance
   entry points (release check, mount smoke, docs generators) that may spawn git or npm.
+  The optional Web client (`ui-bundle/`) is its own tier with its own rules.
 - `tools/**` must stay thin and free of status/type literals (`tools-thin`, `tools-vocabulary`);
-  `tools/index.js` is the thin public wiring module and stays exempt from the thinness rule,
-  while registration/shared machinery lives in `lib/tool-registry.js`.
-- Aggregate files have size ceilings; top-level mutable state is limited to explicit composition
-  roots (`aggregate-size`, `ambient-state`). The per-tool ceiling is 200 lines; only the
-  `tools/index.js` wiring module is exempt, and it is now far below the ceiling.
+  `tools/index.js` is the thin public wiring module (it imports `host/tool-registry.js`, not a
+  `node:` module), while registration/shared machinery lives in `host/tool-registry.js`.
+  Tools receive effectful helpers (repository resolution, leases, recovery, legacy import) from
+  the registry instead of importing an adapter.
+- Aggregate files have size ceilings; top-level mutable state is limited to `host/**`
+  (`aggregate-size`, `host-scope`). The per-tool ceiling is 200 lines; `tools/index.js`
+  currently sits inside the 40-200 range, so the tools allow-list is empty rather than silently
+  exempting the wiring module.
+- `app/**` may import only app siblings, `domain/**`, `ports/**` and `node:path` (`app-ports-only`);
+  an app module that reaches an adapter, a `host/` module or `lib/` fails the gate.
+- `app/**` and `domain/**` may not import the retired `lib/` layer (`no-lib-from-core`); with the
+  layer gone this keeps it from creeping back.
+- `host/**` is the only source root that may hold ambient module state (`host-scope`);
+  `app/**` and `domain/**` must stay stateless at module scope. Only `host/**` and `adapters/**`
+  may import an adapter (`composition-root`); `app/`, `tools/`, `domain/` and `ports/` never may.
+- Every `ports/**` module must export a runtime contract (`const`/`function`/`class`) and must not
+  import an implementation (`port-shape`); a typedef plus `export {}` is no longer accepted.
+- `ui-bundle/**` is a browser tier, not host code (#71): no `node:*` import
+  (`client-no-node` — DOM globals are fine; host capabilities must come through the
+  plugin's registration surface), every client file stays at or below 800 lines
+  (`client-size`), and module-level mutable state is banned exactly as it is for
+  `app/**` (`client-ambient`); the split surfaces keep their state inside the
+  `create*` closure the entry composes. `ui-bundle/` is also excluded from
+  `aggregate-size`, which it would otherwise duplicate.
 
-A fixture test seeds one violation per rule, so a rule that cannot fail is itself a test failure.
+### Exemptions are justified data
+
+The gate's only exemptions live in `scripts/architecture-waivers.json`; `scripts/architecture.mjs`
+keeps no allow-lists of its own. Since #70 the file has exactly two entries, both I/O adapter
+boundaries (`adapters/vcs-git.js` for `node:child_process` and `adapters/store-fs.js` for
+`node:fs`). Each entry names the `rule` and `path` and must carry a non-empty `reason` plus an
+`owner` or `ref`. An entry missing any of those is itself a blocking `waiver-contract` violation
+that names the rule and the path, so a bare path cannot turn the gate green. The waiver file is a
+two-key path in `CONTRIBUTING.md`; there is no `reviewBy`/expiry field in this release, so the
+reason and the owner are the reviewed decision.
+
+`host-scope` replaces the old `ambient-state` waivers (#70). It scans `app/**` and `domain/**` and
+records every module-level `let`; `host/**` owns the process/session state and needs no waiver. The
+scan is statement-aware rather than line-based: it walks the module's token stream and records every
+binding of every top-level `let` declaration. A second declarator (`let a = 1, b = 2`), a second
+statement on one line (`let a = 1; let b = 2`), and any new top-level `let` in `app/` or `domain/`
+are each their own violation. Strings, comments, template literals and regex literals are skipped,
+and `let` inside a function, block, class or `for (…)` header is not module-level state.
+
+`domain-pure`, `host-scope`, `no-lib-from-core`, and anything under `domain/**` are load-bearing: no
+waiver may target them, even a justified one. A `waiver-contract` violation rejects that entry and
+the underlying rule still fails.
+
+A green run prints `architecture: ok (waivers: N)`; N is the number of entries that actually
+suppressed a violation, so a stale waiver is visible in the output and in the tests. The fixture
+suite seeds an unjustified waiver (it fails), a justified one (it passes), a `host-scope` fixture
+that puts ambient state in `host/` (allowed) and in `app/`/`domain/` (rejected), a `no-lib-from-core`
+import from `app/` (rejected), a same-line second binding (rejected), and a new violation inside
+each rule. A separate fixture seeds one violation per rule, so a rule that cannot fail is itself a
+test failure.
 
 ## Mount smoke and host internals
 
@@ -149,24 +264,40 @@ probe adjustments in the same change.
 
 All epic DoD items now have an executable gate:
 
-- Pure domain share: **37.9%** (5,993 / 15,820 source lines), enforced by
-  `npm run domain:check` (threshold 35%).
-- `domain/**` imports no fs, child_process, adapters, app, tools, or lib infrastructure;
+- Pure domain share: **39.5%** (7,475 / 18,936 host source lines), enforced by
+  `npm run domain:check` (threshold 35%). `npm run domain:metrics` also prints a
+  separate `ui-bundle` line, so Web-client growth is visible in CI output while the
+  share itself still measures the Host architecture.
+- `domain/**` imports no fs, child_process, adapters, app, tools, or host infrastructure;
   `domain-pure` is a blocking architecture rule.
 - Inside the source roots, only `adapters/vcs-git.js` imports `node:child_process`; only
-  `adapters/store-fs.js` imports `node:fs`; both are blocking rules with fixtures.
-- `lib`, `app`, and `domain` files stay <= 800 lines; every `tools/**` file stays
+  `adapters/store-fs.js` imports `node:fs`; both are blocking rules whose files are the only
+  `child-process-surface`/`fs-surface` entries in `scripts/architecture-waivers.json`.
+- `host`, `app`, and `domain` files stay <= 800 lines; the same ceiling applies to
+  `ui-bundle/**` (`client-size`); every `tools/**` file stays
   40-200 lines (one handler module per tool; `tools/index.js` is 40-line wiring).
 - No `withLock` scope starts a process; the two-phase tests instrument every git call.
 - `tools/**` has no status/type/enum literal; vocabulary is owned by
   `domain/vocabulary.js`; the `tools-vocabulary` rule is blocking.
 - `validateState` has a four-line body over `domain/state/schema.js` and
   `domain/state/semantics.js`.
-- `state.json` and `modes.json` share `lib/persistence.js` atomic write, token-owned
+- `state.json` and `modes.json` share `adapters/persistence.js` atomic write, token-owned
   lock, dead-PID quarantine, and bounded-wait primitives.
-- The in-memory lifecycle and adapter contracts run a full mission lifecycle with no
-  disk and no git.
-- The seven fitness rules are errors, each with a seeded failing fixture.
+- The in-memory lifecycle runs the real app use cases (init → plan → provision → spawn → complete →
+  review → gate → merge → teardown) on an in-memory store and scripted vcs supplied through the
+  composition root, with no disk, no git and no `defaultDeps` (#69).
+- The eleven host fitness rules are errors, each with a seeded failing fixture; the
+  three `client-*` rules form the Web-client tier with one fixture each, and the
+  `waiver-contract` rule makes an unjustified exemption blocking as well.
+
+## Non-goals
+
+This layer map is not a dependency-injection container, a service locator, or a
+place to register classes by reflection. Ports stay runtime contracts and the
+composition root stays the only place that assembles implementations.
+
+Enforced by: `scripts/architecture.mjs` and `ports/index.js`; tests in
+`tests/architecture.test.mjs`; gate: `npm run architecture:check`.
 
 
 

package/docs/guide/hot-reload.md

@@ -86,7 +86,7 @@ To stop watching, run `npm run dev:hmr -- --remove` and restart DSH once.
 
 ## The edit loop
 
-1. Edit `lib/*.js`, `index.js`, `worker.js`, `reviewer.js` or `skills.js`.
+1. Edit `host/*.js`, `adapters/*.js`, `app/*.js`, `domain/**/*.js`, `index.js`, `worker.js`, `reviewer.js` or `skills.js`.
 2. Save the file. The watcher debounces (DSH default 100 ms) and reconciles the profile; changed
    modules are replaced and the affected Loader entries restart.
 3. Watch the DSH log for `reload plugin at <path>` / `restart required: …` messages.

package/docs/guide/release.md

@@ -58,7 +58,7 @@ Put the **host build in cell 0** and the **tag in cell 1**:
 | 0.2.1-rc.2 | v2.1.0-beta.1 | 2026-10-22 | `npm test`, `npm run docs:check`, mount smoke |
 ```
 
-`lib/compatibility.js#parseCompatibility` reads cells 0–3 only: never insert a column before
+`host/compatibility.js#parseCompatibility` reads cells 0–3 only: never insert a column before
 the tag and never add one before "what was run", or `tower_doctor` stops seeing the row. The
 host pin in `scripts/mount-smoke/host.json` must equal cell 0 of the newest row (a unit test
 enforces it).

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/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/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: 64 · sections: 15 · tools: 27 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
 
 | Key | Default | Description |
 |---|---|---|

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: 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,
@@ -40,6 +65,14 @@ 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 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`,
@@ -49,6 +82,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 +114,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 | — |