dsh-tower 2.6.0 → 2.7.0

package/docs/adr/0006-mission-shapes.md

@@ -0,0 +1,306 @@
+# ADR 0006: Mission shapes
+
+- Status: accepted
+- Date: 2026-11-10
+- Ref: #148, #149
+
+## Context
+
+`kind` was a column on one mission record, but it carried three contracts: a build
+owns a branch and a worktree, is reviewed at its tip, and merges; a survey only
+reads one commit. The state document could describe both shapes at once, so the
+generic layers kept asking `kind === 'survey'` and the answer leaked into
+completion (`commit >= 1`), the merge gate (`read-only-survey`), archive and
+reanchor terminality, planning's open-work count, and provisioning. A survey
+that completed could not be archived, blocked reanchor forever, counted as open
+work, and paid for a full checkout while consuming the live-worker budget.
+
+## Decision
+
+`domain/shapes/` is the one registry. Each shape module owns its statuses,
+transitions, terminality, merge/rebase permission, provisioning, plan fields,
+completion invariants, dependency satisfaction, briefing and summary projection.
+`domain/shapes/index.js` is the only way a generic layer resolves a shape:
+`shapeFor(mission.kind)`, `isTerminal(kind, status)`, `canTransition(kind, from,
+to)`, and `assertActionSupported(mission, action)` for merge/rebase/preflight/diff.
+The global `TERMINAL_STATUSES`/`TRANSITIONS` vocabulary and the one-argument
+`isTerminal`/`canTransition` entry points are deleted.
+
+Schema version 4 is a TypeBox union: a build mission keeps its worktree/branch and
+merge fields; a survey carries `readCommit` and `readDirty` and may not carry
+`worktree`, `branch`, `baseCommit`, `mergedCommit` or `mergedAt`. `merged` is not
+a survey status. Migration v3→v4 is pure, one-way and idempotent: it stamps every
+mission with a shape, reads a legacy survey's commit from
+`worktree.baseCommit ?? baseCommit`, drops its branch fields, and maps a legacy
+`merged` survey to `completed`.
+
+Read-only is structural, not a gate: `tower_plan({kind:'survey'})` refuses while
+the `tower-survey` component row is off; a survey spawn uses the shared checkout
+and the `tower-survey` preset allow-list; `tower_complete` checks that HEAD still
+equals `readCommit`, that the tracked-status set matches the set captured at plan
+time, and that zero commits were made.
+
+`scripts/shape-audit.mjs` enforces the decision: no kind or role literal
+comparison outside `domain/shapes/` and `domain/roles.js`, no global status
+vocabulary, no one-argument entry points. Waivers are justified data in
+`scripts/architecture-waivers.json` under `shapeWaivers`; an unjustified or stale
+waiver fails. `docs/reference/shapes.md` is generated from the registry.
+
+## Surface budget
+
+The shape redesign grows the config surface by exactly one key, recorded in
+`scripts/surface-baseline.json`:
+
+- `spawn.surveyModel` (tuning): an optional independent model route, mirroring
+  `spawn.workerModel`/`spawn.reviewerModel`.
+
+An earlier cut of this work also added `spawn.surveyPreset` (core) and
+`survey.sandbox` (tuning) in a new `survey` section. Review contracted the
+surface back before release (config 57 → 55, sections 15 → 14): a shape owns its
+preset (`SHAPES.survey.spawn.defaultPreset`), so a `spawn.surveyPreset` key could
+only disagree with the registry; and `survey.sandbox` advertised a detached
+read-only checkout that W1 does not implement. Neither is a tuning knob a user
+should see; the completion invariants (HEAD, tracked-status fingerprint, zero
+commits) are the read-only guarantee, not a placement option.
+
+The `tower-survey` row is a visible optional component (components 11 → 12): off
+means surveys cannot be planned (an actionable code) and no survey agent can be
+dispatched; build missions are unaffected. It is a declarative preset row: the
+host resolves its availability through the async `agentPresets` probe, not the
+process-local code registry.
+
+## Rejected alternatives
+
+- Keep `kind` on one record and guard each leak with another `kind === 'survey'`
+  check. Rejected: that is exactly the census in #149; the state document would
+  still be able to describe both shapes and every new layer would re-learn the
+  rule.
+- Add a `shape: 'build'|'survey'` flag selecting an old and a new code path during
+  a transition period. Rejected: a dual-shape path lets a document carry an
+  impossible combination (a survey with a worktree, a merged survey) and makes the
+  migration untestable.
+- Keep `commit >= 1` and make a survey commit an empty commit. Rejected: a survey
+  is a read, so the empty commit records nothing and hides that HEAD moved.
+- Enforce read-only at merge time (`read-only-survey` in the gate). Rejected: the
+  write already happened by then; read-only must be structural (preset allow-list)
+  and checked as a completion invariant.
+- Give a survey its own branch so the existing lifecycle "just works". Rejected:
+  it reintroduces provisioning cost, branch ownership, stale-base and merge
+  vocabulary for a kind that never merges.
+
+## Consequences
+
+- `kind` is now a closed vocabulary with one registry; adding a kind means adding
+  a shape module and regenerating `docs/reference/shapes.md`, not editing generic
+  layers.
+- Older v3 documents migrate on load; a legacy survey's `worktree` is removed by
+  a bounded-retry teardown and its completion with commits is accepted as history.
+- A completed survey is terminal, archivable, no longer open work, and no longer
+  blocks reanchor or the live-worker budget.
+- Surveys can be planned only while the `tower-survey` row is on, and they cannot
+  be merged, rebased, preflighted or diffed: each refuses with `invalid-transition`
+  and an actionable next step.
+- The shape audit is part of `npm run check`; a new kind or role comparison in a
+  generic layer fails CI unless a justified waiver is recorded.
+
+## Addendum: W2 detached sandbox and dependency semantics (#148)
+
+W1 implemented the shared-checkout survey only. W2 adds the placement it left
+out, without changing the default or the shared path:
+
+- `survey.sandbox` (`none`|`detached`, default `none`) is tuning, recorded in
+  `scripts/surface-baseline.json` (config keys 55 → 56, sections 14 → 15). The
+  shape resolves the placement (`resolveProvisioning`) and the preset
+  (`resolvePreset`); no generic layer reads the key or compares a kind.
+  `spawn.surveyPreset` stays removed because the preset follows the registry and
+  the resolved placement.
+- `detached` provisions `git worktree add --detach <worktreeRoot>/<id>-sandbox
+  <readCommit>` with no branch and records `mission.sandbox`. It never records
+  `baseCommit`, never participates in stale-base, review or merge, and the
+  completion invariant is sandbox HEAD === `readCommit` plus zero commits.
+  Expected write/shell side effects in the disposable checkout are ignored;
+  the shared placement keeps the tracked-status fingerprint invariant.
+- The sandbox preset (`tower-survey-sandbox`) allows read/write/edit/pwsh plus
+  the mission tools and still denies spawn/merge/rebase/review/diff. Both survey
+  presets are internal children of the one visible `tower-survey` group row, so
+  the component count does not move (12) and turning the capability off removes
+  both.
+- Cleanup is advisory: completion, abandon and `tower_teardown` remove the
+  sandbox with a bounded retry. A failure keeps `mission.sandbox`, records
+  `sandboxCleanupError` and names the `git worktree remove --force <path>`
+  remedy in the activity log; the transition itself is not rolled back. Archival
+  defers a mission whose sandbox is still present instead of moving the only
+  record of the path out of hot state.
+- `gates.requireFreshSurvey` (default `false`) controls dependency freshness. A
+  build depending on a survey whose `readCommit` is not ancestor-or-equal of the
+  build base gets a `survey-stale` warning in plan/preflight with
+  `{code,missionId,depId,readCommit,baseCommit,message}`; only when the gate is
+  `true` does the same code block the merge. The ancestor check is the existing
+  `isAncestor` (`git merge-base --is-ancestor`, which is true for equal commits).
+- A build briefing carries each survey dependency's recorded `result`
+  (`paths`/`symbols`/`plan`/`notes`) with bounded formatting, so the dependent
+  worker sees the evidence rather than only the terminal status. `result`
+  remains survey-only at completion.
+- Placement is decided at provisioning time, not at completion time: a recorded
+  `mission.sandbox` wins over current `survey.sandbox` config for provisioning,
+  preset and completion invariants. Flipping the key after a sandbox was created
+  therefore cannot skip the sandbox HEAD/zero-commit checks or strand the
+  disposable checkout, and a survey that never got a sandbox keeps the shared
+  invariants.
+- The archive index keeps a survey's `readCommit` and bounded `result`, so an
+  archived survey dependency still carries its evidence into a build briefing
+  and `gates.requireFreshSurvey` cannot fail open after archiving (#73).
+
+## Addendum: W3 review, batch, leases and paused-vs-blocked (#149)
+
+W3 audited four state dimensions that are not mission kinds. None became a
+shape: each has one owning module, and each verdict names a fitness rule that
+`npm run shape:audit` enforces (generated into `docs/reference/shapes.md`).
+
+- **Review — commit-stamped evidence (`app/review.js`, `app/reviewCheckout.js`,
+  `domain/missions/review.js`).** A verdict is evidence about a commit, not about
+  a mutable worktree. `tower_spawn` provisions a disposable detached checkout of
+  the mission branch tip for the reviewer and records `reviewCommit` /
+  `reviewCheckout` on the roster row. `tower_review` stamps `reviewedCommit` with
+  that recorded commit, refuses if the checkout HEAD moved, and the merge gate
+  compares the stamp to the current branch tip with the existing `tip-moved`
+  blocker. `tower_diff` shows a reviewer the same recorded commit. The old
+  after-the-fact "reviewer modified the branch" check (`assertReviewerSpawnTip`)
+  is deleted: a stale worker write can no longer affect what a review decided.
+  The checkout is removed when the verdict is recorded and retried by
+  `tower_teardown`. A tower break-glass verdict stamps the current branch tip
+  because there is no checkout. Fitness rule: `review-tip-read`.
+- **Batch — correctly generic second lifecycle (`domain/batch.js`,
+  `domain/collab/batch.js`, `app/batch.js`).** A batch is finite evidence over
+  missions, not a mission kind, so it stays generic — but its second state
+  machine is now owned by one module: `BATCH_STATUS`, `BATCH_TRANSITIONS`
+  (`open → closed | abandoned`), `canTransitionBatch`, `isBatchTerminal` and
+  `normalizeBatchStatus` (legacy `created`/`active`/`pending` read as `open`).
+  `createBatch`/`closeBatch`/`abandonBatch` share one guarded transition and
+  state semantics validates the stored status, so an unknown or invented batch
+  status fails as state corruption. Receipt verification is unchanged. Fitness
+  rule: `batch-status-literal`.
+- **Leases — advisory coordination, never authority (`adapters/leases.js`,
+  `app/spawn-prechecks.js`).** Lease acquisition is not OS-enforced exclusivity,
+  and the docs say so. There is exactly one enforcement point: the fail-closed
+  spawn admission when `spawn.requireLease` names a lease, which refuses a
+  missing lease and a lease held by another actor with an actionable remedy. The
+  prior contract deadlocked: an expired lease held by a crashed process could
+  never be released because a token mismatch was refused even with `force`. Now
+  `force: true` releases an **expired** lease (explicit crash recovery) while a
+  live lease still refuses a foreign token, and `acquire` never takes over
+  automatically. Fitness rule: `lease-ledger`.
+- **Paused vs blocked — two distinct stopped semantics
+  (`domain/missions/lifecycle.js`, `domain/state/semantics.js`).** `blocked` is
+  derived machine state: it means "open blockers exist". `paused` is a deliberate
+  stop with a `pauseCause` (`user`|`failure`|`resource`|`dependency`). They never
+  coexist: a recorded blocker clears a pause and moves the mission to `blocked`;
+  `clear_blockers` clears them and resumes the mission (to `active`, or to
+  `completed` in the same patch); pausing or completing is refused while blockers
+  are open; `status: "blocked"` is refused and machine writers go through
+  `markBlocked(mission, text)` (merge/rebase conflicts use it). The state
+  invariant `status === "blocked" ⇔ open blockers exist` (for non-terminal
+  missions) is checked on every load/validation, and migration v4→v5 normalizes
+  recorded states: a blocked mission without a blocker gets an explicit legacy
+  blocker, blockers under another non-terminal status become `blocked`, and a
+  superseded `pauseCause` is removed. It is not a per-kind rule: both shapes
+  declare `blocked`/`paused` in their own transition tables. Fitness rule:
+  `blocked-status-write`.
+- Because the stopped-status invariant is new, the persisted schema version is
+  now **5** (`SCHEMA_VERSION = 5` in `domain/mission.js`); the v4→v5 migration is
+  pure and idempotent like its predecessors.
+- The audit grew four rules (`review-tip-read`, `batch-status-literal`,
+  `lease-ledger`, `blocked-status-write`) with mutation tests proving each rule
+  fails on a seeded violation. `scripts/shape-audit.mjs` exports `RULES`, and
+  `scripts/generate-shapes-reference.mjs` refuses to generate if a verdict names
+  a rule the audit does not run.
+
+## Addendum: W4 evidence, legacy, scope and role-vs-kind (#149)
+
+W4 audited the four remaining dimensions. Each had no single owner; each got a
+written verdict, one owning module, and a fitness rule that `npm run shape:audit`
+enforces (generated into `docs/reference/shapes.md`). No dimension became a
+per-kind conditional and no second shape table was added.
+
+- **Test receipts / evidence — redesigned to one reader (`domain/evidence.js`).**
+  The same question ("did tests run?") previously had four answers:
+  `mission.completionReport.checks`, a synthetic `tests` check that
+  `tower_complete` copied from discovery via `tests.autoChecks`,
+  `mission.testRuns`, and a separate `gates.requireTests` filter that re-read
+  receipts. `domain/evidence.js` now owns the normalized record
+  `{names, name, source, ok, command, exitCode, evidence, treeTip, entry}` with
+  sources `completionReport` | `testRuns` | `input`, aliases `tests`/`tower_test`
+  carried in `names`, and one ordering (completion checks first, then newest
+  receipts, then caller checks scoped to the mission) applied by `findEvidence` —
+  precedence and ordering are reader decisions, not fields on the record.
+  `evidenceEntries`, `findEvidence`, `passingDiscovery`,
+  `hasCheckEvidence` and `hasTestReceipts` are the only readers; the shapes
+  declare the contract (`build.evidence = {completionChecks: true, testReceipts:
+  "tip-bound"}`, `survey.evidence = {completionChecks: true, testReceipts:
+  false}`) because only a shape with a branch has a tip to bind a receipt to.
+  `gates.requireTests` uses `passingDiscovery`; completion blockers use
+  `hasCheckEvidence`; `tower_batch` validation/summary use `findEvidence`.
+  `tower_complete` no longer copies a `tests` check into the report and
+  `tower_test` returns the receipt only, so the config key `tests.autoChecks`
+  disappears (config surface 57 → 56, recorded in `scripts/surface-baseline.json`
+  and `docs/reference/surface-budget.md`). Fitness rule:
+  `evidence-single-read`, owned by `domain/evidence.js`; mutation tests seed a
+  completion-check read, a `mission.testRuns` read and prove the owner module is
+  exempt.
+- **Legacy import — redesigned to a strict adapter contract
+  (`adapters/legacy.js`).** Import was approximate in four ways: the format was
+  inferred from the first mission id (mixed namespaces were only caught
+  incidentally), an absent `kind` was silently stamped `build`, a Tower Codex
+  `retired` status leaked into the mission summary as if it were a DSH status,
+  and batch exclusion read several hand-written snapshot shapes
+  (`missions`/`snapshot.missions`/`payload.missions`/`pausedIds`). The adapter now
+  exports `LEGACY_FORMATS`: one declared entry per accepted format (id pattern,
+  id hint, input statuses, `statusRemap`, `baseBranchField`,
+  `requiresBaseBranch`). Detection requires exactly one id namespace (a declared
+  `payload.format` is authoritative and validated against the ids); a Codex
+  `retired` status is remapped to `abandoned` and reported in `remapped`; an
+  absent kind is reported in `unresolved` instead of silently invented; mission
+  fields the summary does not carry are reported in `dropped` with the reason
+  that the exact bytes remain in the stored snapshot. The persisted snapshot
+  record gains `unresolved`, `droppedFields` and `remapped`, so the honesty
+  survives a restart. `domain/batch.js` reads only the canonical
+  `pausedMissionIds`. The import remains read-only, byte-exact,
+  hash-addressed and idempotent: it never writes `state.json`, never activates,
+  adopts or resumes a mission, and a paused mission stays paused. Fitness rule:
+  `legacy-vocabulary`, owned by `adapters/legacy.js`; mutation tests prove a
+  second `tower-codex`/`pausedIds` reader fails outside the adapter.
+- **Scope ownership — redesigned to `shape.reach` (`domain/scope.js` +
+  shapes).** The shape flag `ownsScope` lived beside three enforcers (the
+  integration gate, the planner's auto-dependencies, and lifecycle scope
+  widening), each of which read `mission.scope` itself. The shape now declares
+  `reach = { ownsPaths, fence: "scope" | "read-only" }`: a build owns paths and
+  fences changed files against its scope; a survey reaches nothing and is fenced
+  read-only. `domain/scope.js` exports one `scopeFenceBlocker({ mission, reach,
+  changedFiles, caseInsensitive })`; `domain/integration/gate.js` derives the
+  reach from `shapeFor(mission.kind)` and re-exports the existing
+  `outOfScopeBlocker` shape; `domain/missions/plan.js`,
+  `domain/planning.js` and `domain/missions/lifecycle.js` derive
+  `reach.ownsPaths`. `ownsScope` is deleted. Fitness rule: `scope-reach`, owned
+  by `domain/scope.js`; mutation tests seed an `ownsScope` reader and a direct
+  `fileInScope` call.
+- **Role vs kind — redesigned to an orthogonal role contract
+  (`domain/roles.js`).** Spawn resolved a reviewer by combining
+  `isReviewerRole(role)` with `shape.fields.readCommit`/`shape.canMerge`, and
+  presets, prechecks, placement, briefings and the roster each re-derived role
+  facts independently. `domain/roles.js` now owns `ROLE_CONTRACT`, one entry per
+  actor role with `preset`, `model`, `placement`, `briefing`, `tracksMission`,
+  `countsTowardBudget`, `spawnDiscovery` and `requires` (review, canMerge,
+  worktree, status set). `resolveRoleSpawn` returns the preset/model route,
+  `roleMissionBlockers` returns ordered prerequisites, and
+  `roleCountsTowardBudget`, `roleTracksMission`, `rolePlacement`,
+  `roleBriefingKind` and `rolePresetConfig` replace the scattered checks. The
+  shape supplies only facts (`canMerge`, `fields.worktree`, `spawn.model`);
+  `tools/spawn.js`, `app/spawn-prechecks.js`, `app/spawn-support.js`,
+  `domain/roster.js` and `host/presets.js` call the role API and never combine a
+  role predicate with a shape decision. Fitness rule: `role-shape-conflation`,
+  owned by `domain/roles.js`; mutation tests seed a role∧shape conditional and
+  prove the owner module is exempt.
+- The audit now runs 12 rules. The generated reference's `Dimension inventory
+  (#149)` lists every audited dimension with its verdict, owner module and
+  fitness rule; `scripts/generate-shapes-reference.mjs` still refuses to emit a
+  rule id the audit does not run.

package/docs/architecture/overview.md

@@ -226,12 +226,14 @@ planned ──spawn worker──▶ active ──tower_complete──▶ complet
    │                        │  ▲                         │
    │                        │  └──── review round not clean ────┐
    └── abandon ──▶ abandoned│                                   │
-                            ├── blocker ──▶ blocked ──active/completed──▶ ...
+                            ├── blocker ──▶ blocked ──clear_blockers──▶ active
                             └── pause ─────▶ paused ──active──▶ ...
 ```
 
-`merged` and `abandoned` are terminal. `tower_mission` may set `blocked → completed`; `merged` is only
-set by `tower_merge`/reconciliation.
+`merged` and `abandoned` are terminal. `blocked` is derived: it holds exactly while the mission has an open
+blocker, `clear_blockers` resumes it to `active`, and `tower_mission` refuses to set `status: "blocked"` directly.
+`paused` is a deliberate stop (`pause_cause`); a blocker supersedes a pause. `merged` is only set by
+`tower_merge`/reconciliation.
 
 ## Gate pipeline (`tower_preflight`)
 
@@ -261,7 +263,7 @@ After the command, regardless of exit status, it inspects `HEAD`:
 | Path | Contents |
 |---|---|
 | `<git-common-dir>/dsh-tower/state.json` | active missions, roster, reviews, findings, messages, reviews sequence |
-| `<git-common-dir>/dsh-tower/archive/index.json` | compact terminal-mission index (ids, status, branch, timestamps) |
+| `<git-common-dir>/dsh-tower/archive/index.json` | compact terminal-mission index (ids, status, branch, timestamps, survey `readCommit` and bounded `result`) |
 | `<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 (heartbeat reclaim; a recycled PID cannot pin it) |

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

@@ -29,6 +29,32 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
 
 ## Migration notes
 
+- **2.6.0 → 2.7.0 (#148/#149) — mission shapes, survey tasks, and state schema v5**: a completed
+  survey is a read of a commit, not a write of a branch. `tower_plan({kind:"survey"})` records
+  `readCommit` and `readDirty`, creates no branch or worktree, and completes only while HEAD and the
+  tracked-file status still match that read. The optional `survey.sandbox: "detached"` mode gives a
+  writable inspection a disposable worktree pinned to the same commit. `tower-survey` is an optional
+  component row; survey presets are read-only by default, and surveys do not count against
+  `spawn.maxLiveWorkers`.
+  - **State migration is automatic and one-way.** The first write after upgrading migrates
+    `state.json` from v3 to v5 in one step, writes `state.json.v3.bak` first, advances `revision`
+    once, and logs `state.migrated` with steps v3→v4 and v4→v5. Legacy survey rows gain
+    `readCommit`/`readDirty` (anchored at `state.base` when the old row never started), and build
+    rows are stamped `kind:"build"`. Read-only loads migrate in memory without rewriting the file.
+    A newer document is still refused with `state-version-unsupported` and never downgraded.
+  - **Config key count 57 → 56.** `tests.autoChecks` is gone; test evidence is now the
+    `mission.testRuns` receipt read by `domain/evidence.js`. A config that still writes the key is
+    rejected as `config-unknown-key` with this note; there is no replacement switch.
+  - **`blocked` is derived.** Write `status:"blocked"` through `tower_mission` is refused; use
+    `blocker` to report and `clear_blockers` to resolve. Batch statuses are canonical
+    `open → closed|abandoned`; an expired foreign lease requires explicit `force` to recover.
+  - **Survey actions are explicit.** `tower_merge`, `tower_rebase`, `tower_preflight`, and
+    `tower_diff` refuse surveys with `invalid-transition`; a completed survey is terminal for
+    planning, archive, dependency satisfaction, and reanchor. `tower_complete` accepts an optional
+    structured `result` (`paths`, `symbols`, `notes`, `plan`) for surveys only.
+  - Reviewers are now spawned into a detached checkout bound to the recorded commit; a verdict is
+    tied to that commit, and teardown cleans the checkout. Existing build workflows are unchanged.
+  - No npm dist-tag or review-policy change is required. Restart DSH after upgrading.
 - **2.5.0 → 2.6.0 (#M39/#M40) — review modes replace the boolean**: the review policy is one
   tri-state control on the Plugins page in the `dsh-tower` configuration section, and the config key
   is `review.mode`: `off`, `optional` (the default) or `required`.

package/docs/operations/runbook.md

@@ -21,7 +21,7 @@
 
 `tower_rebase` first. If the branch is already contained in the base it returns `alreadyMerged` and
 leaves the branch untouched — then call `tower_merge` to record it. A conflict marks the mission
-`blocked`; resolve in the worktree, set the mission back to `active` (or `completed`), retry.
+`blocked`; resolve in the worktree, then `tower_mission({clear_blockers:true})` resumes it to `active`, retry.
 
 ## Interrupt, stale roster and takeover
 

package/docs/reference/blockers.md

@@ -1,9 +1,13 @@
 # Blockers and failure codes
 
-`tower_preflight` returns `{ok:false, blockers:[{code, detail}]}`. `tower_merge` and `tower_rebase`
+`tower_preflight` returns `{ok:false, blockers:[{code, detail}], warnings:[...]}`. `tower_merge` and `tower_rebase`
 return the same shape for operation failures. Codes are stable; the detail is human-facing. The
 tables below define 32 stable blocker/failure codes.
 
+`survey-stale` is special: it is reported as a stable warning in `plan`/`preflight` by default and
+becomes a merge blocker only when `gates.requireFreshSurvey` is `true`. Its warning object carries
+`{code, missionId, depId, readCommit, baseCommit, message}` so a caller can act without parsing prose.
+
 The review blockers below (`no-review`, `review-mission-mismatch`, `not-clean`, `review-hold`,
 `review-not-approved`, `tip-moved`, `review-exemption-invalid`) exist only when `review.mode` is
 `required`. With `off` or `optional` no review blocker is produced; `off` additionally removes
@@ -20,10 +24,10 @@ The review blockers below (`no-review`, `review-mission-mismatch`, `not-clean`,
 | `no-check-evidence` | `gates.requireChecks` is enabled and the completion report has no `checks`. Return the completed mission to `active`, re-run `tower_complete` with checks, then review again. |
 | `branch-missing` | No worktree/branch yet: spawn a worker first. |
 | `stale-base` | The branch does not contain the base tip: run `tower_rebase`. |
-| `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 satisfied: a build dependency must be `merged`/`abandoned`, while a survey dependency is satisfied at `completed` (archived entries included). |
+| `survey-stale` | A build dependency on a survey whose `readCommit` is not ancestor-or-equal of the build base. Default: a `warnings[]` entry, plan and preflight only. With `gates.requireFreshSurvey:true` the same code blocks the merge; re-plan the survey against the current base, or record why the read is still valid. |
 | `no-review` | `review.mode:required` and no review exists on the branch: spawn a reviewer (or disable the review gate). |
 | `review-mission-mismatch` | `review.mode:required` and the latest review belongs to another mission. |
 | `not-clean` | `review.mode:required` 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. |
@@ -44,7 +48,7 @@ The review blockers below (`no-review`, `review-mission-mismatch`, `not-clean`,
 
 | Code | Meaning / next action |
 |---|---|
-| `merge-conflict` | Real index conflict; the mission is `blocked`. Resolve, restore the mission to `active`/`completed`, retry. |
+| `merge-conflict` | Real index conflict; the mission is `blocked`. Resolve the conflict, then `tower_mission({clear_blockers:true})` resumes the mission to `active`; retry. |
 | `merge-hook-failed` | A hook/process failed before a commit existed; repository restored, mission stays `completed`. Retry; `timeout: true` means the git process timed out. Raise `timeoutMs` for slow hooks. |
 | `merge-shape` | Git produced unexpected merge parents; inspect the repository, do not force. |
 | `batch-invalid` | A batch id/member/receipt/check reference is invalid or close evidence is incomplete. |
@@ -57,7 +61,7 @@ A merge that already landed is **not** a blocker: `tower_merge` records it (`rec
 | Code | Meaning / next action |
 |---|---|
 | `worktree-dirty` | Commit or discard worktree changes, then retry. |
-| `rebase-conflict` | A real conflict; the mission is `blocked`. Resolve manually, return it to `active`, retry. |
+| `rebase-conflict` | A real conflict; the mission is `blocked`. Resolve manually, then `clear_blockers` resumes it to `active`; retry. |
 | `worker-busy` | An agent is running for this mission; wait or retire it first. |
 
 `tower_rebase` returns `alreadyMerged: true` when the branch is already contained in the base; call

package/docs/reference/component-surface.md

@@ -3,7 +3,7 @@
 > 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-11-01 · baseline 2026-10-23 · visible components: 11 (`tower`, `tower-skills`, `tower-batch`, `tower-import`, `tower-leases`, `tower-tests`, `tower-board`, `tower-archive`, `tower-hmr`, `preset-tower-reviewer`, `tower-ui`)
+Decision: [ADR 0005](../adr/0005-component-surface.md) · decision date: 2026-11-01 · baseline 2026-10-23 · visible components: 12 (`tower`, `tower-skills`, `tower-batch`, `tower-import`, `tower-leases`, `tower-tests`, `tower-board`, `tower-archive`, `tower-hmr`, `preset-tower-reviewer`, `tower-survey`, `tower-ui`)
 
 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
@@ -36,6 +36,9 @@ row is a section of its parent and is not independently switchable.
 | `tower-hmr` | visible | row | Development-only tooling: tower_reload and /tower reload are unavailable, so a linked-profile reload has to be triggered outside Tower. A normal profile behaves exactly as before; the row ships disabled on purpose. |
 | `preset-tower-worker` | internal | row | Declared by dsh-tower/preset-worker: tower_spawn fails without the worker preset. A mandatory dependency, never a switch. |
 | `preset-tower-reviewer` | visible | row | Declared by dsh-tower/preset-reviewer: the reviewer cannot be dispatched. Supported while review.mode is off or optional (merge is unaffected; off does not use the preset at all); with review.mode required, planning/mode entry is locked with an explanatory error. |
+| `tower-survey` | visible | group | Declared by the tower-survey group: surveys cannot be planned (planning one is refused with an actionable code) and no survey agent is dispatched, because both the read-only and the sandbox preset are nested dependencies of this row. Build missions and every existing capability are unaffected. survey.sandbox stays tuning: it chooses shared vs detached placement, never whether surveys exist. |
+| `preset-tower-survey` | internal | row | Declared by dsh-tower/preset-survey: the shared-checkout survey preset is a dependency of the tower-survey group, never its own switch. With the group off, a shared survey cannot be dispatched. |
+| `preset-tower-survey-sandbox` | internal | row | Declared by dsh-tower/preset-survey-sandbox: the detached-sandbox survey preset is a dependency of the tower-survey group, never its own switch. It is selected only when survey.sandbox is detached; with the group off, a detached survey cannot be dispatched. |
 | `tower-ui` | visible | row | The Tower web UI plugin does not load in this profile: no Tower tool cards, composer-dock summary or status strip. Host tools, missions, state and the MISSIONS.md board are unaffected. |
 
 ## Forbidden to disable
@@ -110,6 +113,8 @@ All keys from `domain/config/schema.js`, classified on the component axis.
 | `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.surveyModel` | `optional-config` | Optional model route for survey workers. |
+| `survey.sandbox` | `optional-config` | Tuning, not a capability: shared (read-only in the shared checkout) or detached (a disposable detached sandbox that may write and run commands). The tower-survey row is still the switch. |
 | `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. |
@@ -119,11 +124,11 @@ All keys from `domain/config/schema.js`, classified on the component axis.
 | `tests.admission` | `optional-config` | Chooses when discovery runs inside the optional tests capability. Tuning exemption: Tuning when the admission check runs inside the optional tower-tests row, which still owns whether test tooling exists. (2026-11-03 · #138 · [0005-component-surface.md](../adr/0005-component-surface.md)) |
 | `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. Tuning exemption: Tuning the default receipt policy inside the optional tower-tests row, which still owns whether any test tooling exists. (2026-11-03 · #138 · [0005-component-surface.md](../adr/0005-component-surface.md)) |
 | `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.requireFreshSurvey` | `forbidden-to-disable` | Promotes the survey-stale dependency warning to a merge blocker; the gate itself is part of the merge contract and defaults to advisory. |
 | `gates.maxReportBytes` | `forbidden-to-disable` | The report cap is part of the completion contract; the refusal itself is never configurable away. |
 | `docs.boardLocation` | `optional-config` | Chooses where the board is written; whether it is written is the tower-board component row (#133). |
 | `archive.afterDays` | `optional-config` | Archive age threshold inside the optional tower-archive component (#135). |

package/docs/reference/config.generated.md

@@ -1,7 +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: 54 · sections: 14 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
+> Surface: config keys: 56 · sections: 15 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
 
 | Key | Default | Description |
 |---|---|---|
@@ -32,26 +32,28 @@
 | `merge.maxBufferBytes` | `67108864` | Captured merge output buffer. |
 | `git.timeoutMs` | `15000` | Default timeout for Git commands other than merge; merge uses merge.timeoutMs. |
 | `worktrees.root` | `` | Default parent directory for mission worktrees; empty derives <main-checkout-parent>/.dsh-tower-worktrees/<hash>. |
-| `spawn.workerPreset` | `"tower-worker"` | Agent preset for worker missions. |
+| `spawn.workerPreset` | `"tower-worker"` | Agent preset for build workers. |
 | `spawn.reviewerPreset` | `"tower-reviewer"` | Agent preset for reviewers. |
 | `spawn.maxDepth` | `1` | Subagent depth requested when spawning tower agents. |
 | `spawn.provider` | `` | Subagent provider id; empty picks spawn, then the first registered provider. |
 | `spawn.workerModel` | `{}` | Model route for workers; omitted inherits the parent session. |
 | `spawn.reviewerModel` | `{}` | Model route for reviewers; omitted inherits the parent session (recommended). |
+| `spawn.surveyModel` | `{}` | Model route for survey workers; omitted inherits the parent session. |
 | `spawn.maxLiveWorkers` | `4` | Maximum live worker entries allowed per repository at once. |
 | `spawn.staleMs` | `15000` | Roster entries with no catalog activity after this age are marked stale and block merge (0 disables). |
 | `spawn.maxWaitMs` | `90000` | Upper bound for tower_spawn waitMs (default 90s, Kimi-compatible). |
 | `spawn.requireLease` | `` | Optional lease name tower_spawn must hold before starting a worker. |
 | `send.maxPerMinute` | `120` | Per-repository tower_send rate limit per minute (0 disables). |
 | `send.interruptDefault` | `false` | Default value of tower_send.interrupt when the caller omits it. |
+| `survey.sandbox` | `"none"` | Where a survey reads. none = the shared checkout with a read-only preset (writes and shell commands are impossible); detached = a disposable detached git worktree created at the recorded commit, with a sandbox preset that may write and run commands inside it. A detached sandbox is removed when the survey completes or is abandoned; it has no branch, never participates in merge/stale-base, and cannot commit its evidence. |
 | `tests.admission` | `"off"` | Run discovery before spawning a worker, when completing, or only on explicit tower_test (default off: repository code runs only on an explicit tower_test). |
 | `tests.timeoutMs` | `60000` | Per discovery command timeout. |
 | `tests.maxBytes` | `16777216` | Maximum captured stdout bytes per command. |
-| `tests.autoChecks` | `true` | Attach a tests check to the completion report when discovery runs. |
 | `tests.allowPackageDiscovery` | `true` | Allow package.json tower.testDiscovery commands from the mission worktree (executes repository code; see security docs). |
-| `gates.requireChecks` | `false` | Require at least one completion check (tower_complete.checks) before a mission can merge. |
+| `gates.requireChecks` | `false` | Require at least one recorded check (tower_complete.checks) or test-discovery receipt before a mission can merge. |
 | `gates.requireTests` | `false` | Require a passing test-discovery receipt for the reviewed worktree tip before merge. |
 | `gates.allowReviewExemption` | `false` | Allow reviewPolicy:none missions with a non-empty reviewExemptionReason to skip review blockers. |
+| `gates.requireFreshSurvey` | `false` | Promote the advisory survey-stale dependency warning to a merge blocker: a build may only merge when every survey dependency read a commit that is an ancestor-or-equal of the build base. Default false (warning only). |
 | `gates.maxReportBytes` | `32768` | Hard cap, in UTF-8 bytes, for tower_complete.report; a larger report is rejected with an actionable nextAction, never truncated. |
 | `docs.boardLocation` | `"common"` | common = <git-common-dir>/dsh-tower/MISSIONS.md; repo = <repoRoot>/MISSIONS.md. Whether the board is written at all is the tower-board component row (#133). |
 | `archive.afterDays` | `30` | Terminal missions untouched for at least this many days are archived on the next mutation (0 archives them immediately). Archival itself is the tower-archive component row (#135). |

package/docs/reference/config.md

@@ -108,9 +108,8 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `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.requireChecks` | `false` | Require at least one recorded check (`tower_complete.checks`) or a test-discovery receipt 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. With the `tower-tests` component row off, planning/mode entry refuse this combination with an explanation. |
 | `gates.allowReviewExemption` | `false` | With `review.mode:required`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant when `review.mode` is `off` or `optional` (no review blocker is produced). |
 | `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. |

package/docs/reference/doctor.md

@@ -8,17 +8,17 @@ It returns:
   "ok": true,
   "checks": [
     { "id": "git", "status": "pass", "detail": "git version 2.55.0" },
-    { "id": "surface", "status": "pass", "detail": "config keys: 53 · sections: 14 · tools: 29 (baseline 2026-10-23)" },
+    { "id": "surface", "status": "pass", "detail": "config keys: 57 · sections: 15 · 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": "state-schema", "status": "pass", "detail": "schemaVersion 5 is current" },
     { "id": "case-mode", "status": "pass", "detail": "caseInsensitive: true; scope matching uses case-insensitive comparison" }
   ],
   "surface": {
-    "configKeys": 53,
-    "sections": 14,
+    "configKeys": 57,
+    "sections": 15,
     "tools": 29,
     "baselineDate": "2026-10-23",
-    "line": "config keys: 53 · sections: 14 · tools: 29"
+    "line": "config keys: 57 · sections: 15 · tools: 29"
   },
   "stateLock": {
     "held": true,
@@ -38,8 +38,8 @@ It returns:
     "heldMs": 92000
   },
   "stateSchema": {
-    "currentVersion": 3,
-    "supportedVersion": 3,
+    "currentVersion": 5,
+    "supportedVersion": 5,
     "migrations": [],
     "status": "current"
   },

package/docs/reference/operations.md

@@ -31,7 +31,7 @@ tower_resource({action:"release", name:"heavy-ci", token:"<token from acquire>"}
 
 - acquire is tower-only; the caller gets a token, pid, holder, created/expiry timestamps;
 - the same token renews; another holder gets `[tower:lease-busy]`;
-- release requires the token; an **expired** lease still requires the token and explicit `force:true`
+- release requires the holder token; an **expired** lease is recovered by an explicit `force:true` release (a live lease still refuses a foreign token)
   (no silent takeover);
 - `spawn.requireLease` makes a worker spawn fail unless that lease is held.