dsh-tower 2.5.0 → 2.7.0

package/docs/guide/scenarios-and-philosophy.md

@@ -10,8 +10,8 @@ a better fit.
 
 If you only remember one sentence: **use Tower when the output is an integrated repository change that
 must land through a controlled merge; use the other patterns when the output is exploration, repeated
-attempts, or programmatic fan-out.** Enable `review.requireReview` when the change also needs an
-independent reviewer.
+attempts, or programmatic fan-out.** Set the review policy to `required` when the change also needs
+an independent reviewer; the default policy is `optional`.
 
 ## 1. The design philosophy
 
@@ -45,11 +45,13 @@ When review is enabled, a reviewer also inspects a specific branch tip and the g
 binding. Separation of duties is the point when review is on: the agent that wrote the code is not the
 agent that approves it, and neither is the agent that merges.
 
-Independent review is optional by default: `review.requireReview:true` enforces it (and then a complete
-mission must carry a clean, merge-approved review from a reviewer bound to the branch tip). Set the flag
-to `true` for sensitive repositories; `reviewPolicy:"none"` + a reason + `gates.allowReviewExemption:true`
-remains available as a per-mission exemption when the global gate is on. Reviews can be submitted and
-recorded either way.
+The review policy is one tri-state control: `off`, `optional` (the default) or `required`. `required`
+enforces independent review (a complete mission must carry a clean, merge-approved review from a
+reviewer bound to the branch tip). Choose it for sensitive repositories; `reviewPolicy:"none"` + a
+reason + `gates.allowReviewExemption:true` remains available as a per-mission exemption when the
+policy is required. `optional` records reviews but never blocks a merge, and `off` is a supported
+mode that removes the review tool. The policy is configuration, not a component row: there is one
+control on the plugin page, not three mutually exclusive rows.
 
 ### 1.5 Evidence over assertion
 
@@ -184,7 +186,7 @@ integration, and what "done" means.**
 | Isolation | Git worktree + branch per mission; one writer per mission | Shared workspace; coordination by task ownership | Fresh child per round; no built-in branch/merge contract | Per-step child; no Git isolation | Child sessions; may share workspace |
 | Durable state | Git metadata + JSON state + activity + board | Team task board + sessions | Minimal; each round starts fresh | Run record/results; not a merge ledger | Session/subagent records |
 | Integration authority | Tower only, after preflight/gate (plus review when enabled) | Humans/teammates merge or edit manually | Usually the parent/worker applies results | Script applies results | Parent applies results |
-| Review / gate | Optional independent review (enable `review.requireReview`) + preflight/merge gate | Review is a collaboration convention, not a hard gate | No built-in review gate | No built-in review gate | No built-in review gate |
+| Review / gate | Optional independent review (one `review.mode` control: off/optional/required) + preflight/merge gate | Review is a collaboration convention, not a hard gate | No built-in review gate | No built-in review gate | No built-in review gate |
 | Parallelism | Multiple missions, disjoint scopes, serialized merges | Many teammates, shared board | Sequential rounds (or external fan-out) | High fan-out, script-controlled | High fan-out |
 | Human role | Owns the mode; can inspect evidence and release | Collaborator/coordinator | Author of the repeated objective | Author of the orchestration script | Delegator |
 | Best for | Feature delivery, migrations, release-bound changes | Design, research, cross-cutting collaboration | Iterative search/repair with fresh context | Large audits, batch analysis, deterministic pipelines | Quick exploration or independent subtasks |
@@ -195,8 +197,8 @@ integration, and what "done" means.**
 Ordinary `subagent`/`subagent_fork` calls are cheap and flexible. They are the right tool for "read
 these five files in parallel" or "try three approaches". They do not provide a write scope, a
 dedicated worktree, a durable mission, independent review, or a merge gate. Tower wraps the same
-subagent primitive in those contracts; it also costs more per child. (Review is optional: enable
-`review.requireReview` when you need the reviewer role.)
+subagent primitive in those contracts; it also costs more per child. (Review is optional: set the
+policy to `required` when you need the reviewer role to gate a merge.)
 
 Choose subagents when the work is read-mostly, short-lived, or you will integrate the result
 yourself. Choose Tower when the result must land on a branch under a controlled merge; enable review
@@ -245,14 +247,19 @@ Tower entry clears an active plan (or refuses entry under `mode.planModePolicy:"
 Tower session cannot use the goal/todo/team/workflow tools. Plan first, then execute; do not expect
 Tower to discover the plan for you.
 
-### 4.6 Review is optional by default
+### 4.6 The review policy is one tri-state control
 
-`review.requireReview:false` is the default, so a completed mission can merge without a reviewer for
-low-risk repositories, scratch work, or human-supervised sessions. Set it to `true` to enforce the
+The review policy is one control — `off`, `optional` (the default) or `required` — in the plugin-page
+`dsh-tower` configuration section, mirrored by `review.mode` in config. It is not a component row and
+not three mutually exclusive rows. `optional` means a completed mission can merge without a reviewer
+for low-risk repositories, scratch work, or human-supervised sessions. `required` enforces the
 independent review gate; the gate then re-checks `no-review`, `not-clean`, `review-hold`,
-`review-not-approved`, `tip-moved`, and `review-mission-mismatch`. `tower_review` is always available
-and records verdicts even when the gate is off. For one mission only, with the global gate on, set
-`reviewPolicy:"none"` + a reason and `gates.allowReviewExemption:true`.
+`review-not-approved`, `tip-moved`, and `review-mission-mismatch`. `off` is a supported mode that
+does not register `tower_review`; `optional` records verdicts but never blocks a merge. For one
+mission only, with the policy `required`, set `reviewPolicy:"none"` + a reason and
+`gates.allowReviewExemption:true`. The deprecated one-release boolean alias maps `true` → `required`
+and `false` → `optional`; see
+[install, upgrade and migration](install-upgrade-migration.md).
 
 ### 4.7 Concrete examples by workflow
 
@@ -309,8 +316,8 @@ A team wants "organization invitations": token model, email delivery, accept/dec
    `src/ui/invites/**`; make the API depend on tokens and email.
 2. Spawn workers for the independent missions; the API waits for its deps.
 3. Each worker commits on its branch, completes with checks.
-4. With `review.requireReview:true`, spawn reviewers and require a clean+merge verdict; otherwise
-   review is optional.
+4. With `review.mode:required`, spawn reviewers and require a clean+merge verdict; otherwise review
+   is optional or off.
 5. `tower_preflight` and `tower_merge` each mission; resolve scope/base/review blockers.
 6. `tower_teardown`; `MISSIONS.md` is the human-readable record.
 
@@ -344,9 +351,9 @@ Tower missions from those findings.
 ### Scenario E: sensitive release
 
 A library release with external consumers. Plan missions for the change, migration guide, and
-release notes; enable `review.requireReview:true` if the release requires independent review, require
-tests, and use `tower_batch` to close the release evidence only when all required checks are present;
-merge and tag outside Tower as your release process requires.
+release notes; set `review.mode:required` if the release requires independent review, require tests,
+and use `tower_batch` to close the release evidence only when all required checks are present; merge
+and tag outside Tower as your release process requires.
 
 ## 6. Choosing in practice: a short decision path
 
@@ -354,9 +361,9 @@ merge and tag outside Tower as your release process requires.
 2. **Would you open a PR for it?** No → Tower is too heavy; use a normal agent.
 3. **Do the slices have stable scopes and a known definition of done?** No → plan/explore first; then
    return to Tower.
-4. **Do you need a merge gate?** Repository changes with integration risk → Tower. Enable
-   `review.requireReview:true` if you also need independent review. If neither isolation nor evidence
-   is needed, plain subagents may be enough.
+4. **Do you need a merge gate?** Repository changes with integration risk → Tower. Set the review
+   policy to `required` if you also need independent review. If neither isolation nor evidence is
+   needed, plain subagents may be enough.
 5. **Do you need many parallel analyses or repeated fresh attempts?** Use Workflow/Ralph for that
    phase; encode the resulting changes as Tower missions.
 6. **Do you need cross-cutting human collaboration?** Use Agent Teams to decide; execute the decided
@@ -368,9 +375,9 @@ merge and tag outside Tower as your release process requires.
   round, gate, merge. Keep missions meaningful (roughly a PR-sized slice), not one task per function.
 - **Merges serialize**: overlapping scopes auto-add dependencies; independent missions still merge
   one at a time onto the base. Do not expect linear speedup for merge-heavy work.
-- **Review is not free when enabled**: each mission then needs a reviewer and a clean verdict.
-  `review.requireReview:false` (the default) makes review optional; when the gate is on, exemptions
-  are opt-in and require a reason.
+- **Review is not free when required**: each mission then needs a reviewer and a clean verdict.
+  `review.mode:optional` (the default) makes review non-blocking, and `off` removes the review tool;
+  when the policy is `required`, exemptions are opt-in and require a reason.
 - **Too-fine missions** increase coordination and merge cost. **Too-coarse missions** lose the benefit
   of parallel review and make scope conflicts likely.
 - **Tower is not a sandbox**: it is a coordination protocol. Host permissions, repository hooks, and
@@ -385,7 +392,7 @@ merge and tag outside Tower as your release process requires.
 - [ ] The work produces a repository change that deserves a PR-style review.
 - [ ] I can name 2–8 missions with non-overlapping scopes and a rough dependency order.
 - [ ] Each mission has a testable definition of done (tasks, checks/tests, optional review).
-- [ ] If this change needs independent review, `review.requireReview` is on (default is off).
+- [ ] If this change needs independent review, the review policy is `required` (default is `optional`).
 - [ ] I know which missions can run in parallel and which must wait.
 - [ ] I accept the merge-gate overhead (and review overhead if enabled) and will inspect
       `MISSIONS.md`/the branch.

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/operations/security.md

@@ -4,15 +4,16 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
 
 ## Enforced by the plugin
 
-- **Review binding (when review is enabled).** `tower_review` records the branch tip it inspected;
-  with `review.requireReview:true`, the gate rejects a moved tip (`tip-moved`) unless a clean
-  conflict-free rebase waived it. A reviewer that modifies the branch after spawning is rejected
+- **Review binding (when required).** `tower_review` records the branch tip it inspected; with
+  `review.mode:required`, the gate rejects a moved tip (`tip-moved`) unless a clean conflict-free
+  rebase waived it. A reviewer that modifies the branch after spawning is rejected
   (`reviewer must not modify the mission branch`).
-- **Review is optional by default, enforceable by config.** `review.requireReview:false` is the
-  default; set it to `true` to enforce the independent-review gate. Mission-level
-  `reviewPolicy:"none"` + reason is the narrower exemption when the global gate is on. With the gate
-  off, separation of duties is not enforced by the plugin; use it only for trusted or human-supervised
-  repositories.
+- **Review is optional by default, enforceable by the tri-state policy.** `review.mode` is `off`,
+  `optional` (the default) or `required`. Set it to `required` to enforce the independent-review gate.
+  Mission-level `reviewPolicy:"none"` + reason is the narrower exemption when the policy is required.
+  With `off`, review is intentionally unavailable; with `optional`, separation of duties is not
+  enforced by the plugin, so use it only for trusted or human-supervised repositories. The policy is
+  one control on the plugin page, not a component row.
 - **Role enforcement.** The caller is resolved against the roster. Worker mission updates are limited to
   task/blocker/note; `completed`, `abandoned`, scope widening and blocker clearing are tower-only, and
   completion (with its unread-inbox/commit gates) must go through `tower_complete`. Tower-only tools reject
@@ -84,8 +85,8 @@ intent behind that entry. What it does provide:
 It does **not** defend against: a model that legitimately passes every gate while acting on malicious
 instructions; repository hooks or test commands the repository itself declares; or filesystem/shell
 access outside the worktree by a worker that ignores its instructions. For a higher-assurance team,
-set `mode.allowAgentControl:false`, keep `review.requireReview:true`, review the repository before
-Tower work, and run the host under OS-level isolation.
+set `mode.allowAgentControl:false`, keep the review policy at `review.mode:required`, review the
+repository before Tower work, and run the host under OS-level isolation.
 
 ## Not enforced by the plugin (deployment concerns)
 

package/docs/reference/blockers.md

@@ -1,9 +1,18 @@
 # 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
+`tower_review` and refuses reviewer spawn.
+
 ## Gate blockers (26)
 
 | Code | Meaning / next action |
@@ -15,16 +24,16 @@ tables below define 32 stable blocker/failure codes.
 | `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). |
-| `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. 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). |
+| `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. |
+| `review-hold` | `review.mode:required` and latest review recommends hold; a later clean review must supersede it. |
+| `review-not-approved` | `review.mode:required` and latest clean review says `fix-then-merge` or `hold`; only `merge` approves. |
+| `tip-moved` | `review.mode:required` and the branch changed after review; review again (or use a clean rebase waiver). |
 | `worker-busy` | A roster agent for this mission is running; wait or retire it. |
 | `worker-status-unknown` | The parent catalog is unavailable, so a live roster agent cannot be proven stopped; retry after the catalog recovers or adopt it. |
 | `base-wrong-branch` | The main checkout is not on the recorded base branch. |
@@ -32,14 +41,14 @@ tables below define 32 stable blocker/failure codes.
 | `worker-stale` | A roster worker for this mission has no catalog activity beyond `spawn.staleMs`; adopt it (or interrupt it only if it is actually running) before merge. |
 | `tests-missing` | `gates.requireTests` is enabled and there is no passing discovery receipt for the current branch tip; run `tower_test` or `tower_complete`. |
 | `tests-failed` | The latest discovery receipt failed or did not meet minCount/required checks. Fix the tests and re-run. |
-| `review-exemption-invalid` | `review.requireReview:true` and the mission requests `reviewPolicy:"none"` while `gates.allowReviewExemption` is off (or the reason is missing). |
+| `review-exemption-invalid` | `review.mode:required` and the mission requests `reviewPolicy:"none"` while `gates.allowReviewExemption` is off (or the reason is missing). |
 | `merge-intent-pending` | A merge intent was recorded before a crash/failure; run `tower_merge` to reconcile before another gate. |
 
 ## Merge failures (4)
 
 | 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. |
@@ -52,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-10-23 · 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
@@ -14,7 +14,7 @@ off, and if so, must that switch be a component? Four classes cover every key, s
 | `core` | Removing it breaks the Tower contract. It is never a switch. |
 | `optional-component` | A capability whose off state leaves the rest of Tower intact. It must be a user-visible switch with a documented fallback. |
 | `optional-config` | A tuning knob, not a capability. It stays in the config form and never hides a component. |
-| `forbidden-to-disable` | The host, the health contract, the recovery escape, the review contract and the merge gates. No group, row or boolean key may turn it off. |
+| `forbidden-to-disable` | The host, the health contract, the recovery escape and the merge gates. No group, row or boolean key may turn it off. |
 
 ## Components
 
@@ -35,13 +35,21 @@ row is a section of its parent and is not independently switchable.
 | `tower-archive` | visible | row | Terminal missions are not moved out of state.json, so the hot state keeps growing and status/doctor keep loading their full history. Merges, gates and every other capability keep working; nothing is deleted. afterDays/maxMissions keep their tuning meaning. |
 | `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.requireReview is false (merge is unaffected); with the gate on planning/mode entry is locked with an explanatory error. |
+| `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
 
-The host, the health contract, the recovery escape, the review contract and the
-merge gates are configuration or code, never switches. `npm run
+The host, the health contract, the recovery escape and the merge gates are
+configuration or code, never switches. The review gate in `required` mode is
+also non-disableable: a completed mission still needs the review evidence bound
+to the branch tip, and the exemption path stays explicit. The policy itself is
+not a never-switch — `review.mode` is the one tri-state control on the
+plugin-page config form (`off`, `optional` or `required`) — and only the gate it
+turns on in `required` mode is non-disableable. `npm run
 docs:check:components` derives the live disablers from `host/tool-registry.js`
 and `cordis.patch.yml`; a disabler that is not recorded here fails the gate.
 
@@ -50,7 +58,7 @@ and `cordis.patch.yml`; a disabler that is not recorded here fails the gate.
 | the Tower host | Without the host the plugin registers nothing; there is no off state that leaves the rest working, and no config boolean may remove it. The visible `tower` anchor is the all-off boundary, and the host section nested under it may never become its own switch. | none | none may exist |
 | tower_doctor (read-only health contract) | Diagnosis must always exist so a failure message can point at it. #122 removed exposeDoctor and the exposeOperational master switch; the tool is registered for every configuration. | none | none may exist |
 | tower_recover (stale state-lock escape) | The escape hatch must exist whenever the lock it repairs can be left behind. #122 removed exposeRecovery and the exposeOperational master switch; the tool is registered for every configuration. | none | none may exist |
-| the review contract | review.requireReview is a merge blocker, not a component; a row may not switch it off. The reviewer row is conditional, not a way to weaken the gate. | none | none may exist |
+| the review gate in required mode | The policy is one tri-state configuration control on the plugin-page form, not a component row: review.mode is off, optional (default) or required, and off is a documented mode that removes tower_review and makes the merge gate ignore review. What no group, row or boolean key may switch off is the gate once the mode is required: a completed mission still needs a clean review bound to the branch tip, and the exemption path stays explicit. review.requireReview is a deprecated one-release alias, not a switch. The reviewer preset row remains a capability the policy may leave unused, never a way to weaken required mode. | none | none may exist |
 | the merge gates | gates.* decides delivery; a component may not bypass it. | none | none may exist |
 
 ## Gateable tools
@@ -92,7 +100,8 @@ All keys from `domain/config/schema.js`, classified on the component axis.
 | `mode.storePath` | `optional-config` | Custom mode-store location; no capability is removed. |
 | `mode.maxEntries` | `optional-config` | Bounds the persisted mode store. |
 | `mode.lockTimeoutMs` | `optional-config` | Bounded wait for the cross-process mode lock. |
-| `review.requireReview` | `forbidden-to-disable` | Turns independent review into a merge blocker; no component may switch it off. With it on, the preset-tower-reviewer row may not be off (planning/mode entry refuse the combination). |
+| `review.mode` | `core` | The review policy: off, optional (default) or required, selected by one tri-state control on the plugin-page configuration form. It is configuration, not a component row and not three mutually exclusive rows. off intentionally removes tower_review, refuses reviewer spawn and makes the merge gate ignore review; optional never blocks a merge; required makes a clean tip-bound review a merge blocker. The reviewer preset row stays a capability the mode may leave unused. |
+| `review.requireReview` | `core` | Deprecated one-release boolean alias for review.mode (true -> required, false -> optional; default optional). It is policy configuration and a deprecated alias, not a switch a row may own; false never overrides an explicit mode. Kept so 2.5 configurations keep working; remove after the 2.6 alias window. |
 | `review.maxRoundsPerReviewer` | `forbidden-to-disable` | Caps review rounds; part of the review contract. |
 | `merge.timeoutMs` | `optional-config` | Default merge timeout; a per-call value wins. |
 | `merge.maxBufferBytes` | `optional-config` | Captured merge output buffer. |
@@ -104,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. |
@@ -113,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). |
@@ -135,6 +146,7 @@ hides a capability cannot use the tuning class without that record.
 
 | Key |
 |---|
+| `review.mode` |
 | `spawn.requireLease` |
 | `tests.admission` |
 

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: 53 · 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 |
 |---|---|---|
@@ -25,32 +25,35 @@
 | `mode.storePath` | `` | Directory for modes.json; defaults to $DSH_HOME/tower-mode. |
 | `mode.maxEntries` | `200` | Maximum persisted mode entries. |
 | `mode.lockTimeoutMs` | `5000` | How long saveModes waits for the cross-process modes.lock before giving up. |
-| `review.requireReview` | `false` | Require an independent clean review before merge. Default false: review is optional; set true to enforce the review gate globally. |
+| `review.mode` | `"optional"` | Review policy. off = review is intentionally unavailable (recording a review is refused, reviewer spawn is refused, and the merge gate ignores review; a profile-level off also does not register tower_review); optional = review is available but never blocks a merge (default); required = a clean review bound to the branch tip is a merge blocker. |
+| `review.requireReview` | `false` | Deprecated alias for review.mode (true -> required, false -> optional); prefer review.mode. true next to a non-required mode is rejected; false never overrides an explicit mode (off, optional or required). The Plugins-page control shows the alias when it is the only key and always writes review.mode with review.requireReview:false. |
 | `review.maxRoundsPerReviewer` | `5` | Review-round cap per reviewer per mission branch. |
 | `merge.timeoutMs` | `900000` | Default tower_merge timeout, including pre-merge hooks. |
 | `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

@@ -27,13 +27,38 @@ win, profile keys survive when the repo does not set them. `tower_status` report
 
 ```json
 {
-  "review": { "requireReview": true, "maxRoundsPerReviewer": 3 },
+  "review": { "mode": "required", "maxRoundsPerReviewer": 3 },
   "merge": { "timeoutMs": 1800000 },
   "worktrees": { "root": "D:/tower-worktrees" },
   "spawn": { "reviewerPreset": "tower-reviewer", "maxDepth": 2 }
 }
 ```
 
+`review.mode` is the review policy: `off`, `optional` or `required`. `review.requireReview` is a
+deprecated alias kept for one release (`true` → `required`, `false` → `optional`); prefer
+`review.mode`. When both are set in the same layer, `requireReview:true` next to any mode other than
+`required` is a contradiction and is rejected with `config-invalid` naming both keys.
+`requireReview:false` never contradicts an explicit mode: `off`, `optional` and `required` all stay
+accepted and the mode wins (`required` still enforces the gate; the resolved alias is mirrored back as
+`true` only for that mode). A repository layer is resolved on its own: it may relax review, but a
+profile with `review.mode:off` never registered `tower_review`, so a repository cannot raise its own
+mode.
+
+The Plugins-page control shows the policy exactly as the runtime resolves it: `review.mode` decides
+when present, and a profile that still sets only `review.requireReview` displays Required (`true`) or
+Optional (`false`). Saving a choice always writes `review.mode` and sets `review.requireReview` to
+`false` in the same profile patch, so the alias can never contradict the selected mode.
+
+The same three choices are available on the Plugins page, in the `dsh-tower` configuration
+section: **Off**, **Optional** (the default) and **Required**, each with a one-line description of
+its effect. That control writes the profile config through the Host settings form, so the accepted
+value is reflected on the page without a manual file edit.
+
+One live change cannot rebuild the mounted tool surface: a profile that started with review off did
+not register `tower_review`. Switching to Optional or Required through the page immediately changes
+the merge gate, but the review tool itself appears only after a restart (or a profile reload); the
+control states that after such a save.
+
 The `mode.*` group is session-scoped, not repository-scoped: it is accepted in the repository file
 for schema compatibility but only the profile config controls the Tower-mode prompt and the
 model-controlled toggle. A malformed file, a non-object value, unknown top-level keys, or a value that
@@ -61,7 +86,8 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `mode.denyTools` | goal/todo/team/workflow/subagent tools | Tools refused while the mode is active (12 defaults). |
 | `mode.storePath` | `$DSH_HOME/tower-mode` | Directory for `modes.json`. |
 | `mode.maxEntries` | `200` | Maximum persisted mode entries (1–2000). |
-| `review.requireReview` | `false` | Enforce an independent clean review before merge. Default `false` (review optional); set `true` to require `no-review`/`not-clean`/`review-hold`/`review-not-approved`/`tip-moved`/`review-mission-mismatch` checks. `tower_review` remains available either way. |
+| `review.mode` | `optional` | Review policy. `off` = review is intentionally unavailable: recording a review is refused, `tower_spawn` refuses the reviewer role, the merge gate ignores review, and a profile-level `off` does not register `tower_review` (a repository-level `off` refuses the submission instead); `optional` = review is available but never blocks a merge (default); `required` = a clean review bound to the branch tip is a merge blocker (`no-review`/`not-clean`/`review-hold`/`review-not-approved`/`tip-moved`/`review-mission-mismatch`). |
+| `review.requireReview` | `false` | Deprecated alias for `review.mode`: `true` → `required`, `false` → `optional`. Prefer `review.mode`. `true` next to a non-`required` `review.mode` is rejected with `config-invalid` naming both keys; `false` is accepted next to any explicit `review.mode` (`off`/`optional`/`required`) and never overrides it. The Plugins-page control shows the alias when it is the only key and always writes `review.mode` with `review.requireReview:false`. |
 | `review.maxRoundsPerReviewer` | `5` | Review-round cap per reviewer per branch. |
 | `merge.timeoutMs` | `900000` (15 min) | Default `tower_merge` timeout, including hooks. A per-call `timeoutMs` wins. |
 | `merge.maxBufferBytes` | `67108864` (64 MB) | Merge output buffer. |
@@ -82,11 +108,10 @@ 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.requireReview:true`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant while the global review gate is off. |
+| `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. |
 | `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); `docs.board` was removed and is rejected as an unknown key. |
 | `archive.afterDays` | `30` | Age trigger: a terminal mission untouched for at least this many days is archived on the next mutation (`0` archives immediately). Archival itself is the `tower-archive` component row (#135); `archive.enabled` was removed and is rejected as an unknown key. |

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/errors.generated.md

@@ -29,6 +29,7 @@ single recovery step appended to the message as ` — next: …` (with ` (retrya
 | `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 |
+| `review-disabled` | Review is disabled by `review.mode:off`; no reviewer, verdict, or review blocker exists in this configuration. | no | set review.mode to optional or required in the Tower config, then retry |
 | `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 |

package/docs/reference/errors.md

@@ -2,7 +2,7 @@
 
 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 35 tool error codes.
+release defines 36 tool error codes.
 
 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:
@@ -43,6 +43,7 @@ plain `Error` without a structured code is reported as `tool-internal`.
 | `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 |
+| `review-disabled` | Review is disabled by `review.mode:off`; no reviewer, verdict, or review blocker exists in this configuration. | no | set review.mode to optional or required in the Tower config, then retry | `tower_spawn` with `role:"reviewer"`, or a review submission, while `review.mode` is `off` |
 | `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 |

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.