dsh-tower 2.4.2 → 2.6.0

package/domain/config/schema.js

@@ -16,6 +16,7 @@
 import Schema from '@deepseek-ai/schemastery'
 import { TowerToolError } from '../errors.js'
 import { DEFAULT_MAX_REPORT_BYTES } from '../missions/completion.js'
+import { materializeVolatile, resolveReviewPolicy } from '../integration/review.js'
 
 export const DEFAULT_DENY_TOOLS = [
   'create_goal',
@@ -57,7 +58,7 @@ const SECTION_KEYS = {
     'maxEntries',
     'lockTimeoutMs',
   ],
-  review: ['requireReview', 'maxRoundsPerReviewer'],
+  review: ['mode', 'requireReview', 'maxRoundsPerReviewer'],
   merge: ['timeoutMs', 'maxBufferBytes'],
   git: ['timeoutMs'],
   worktrees: ['root'],
@@ -74,14 +75,36 @@ const SECTION_KEYS = {
     'requireLease',
   ],
   send: ['maxPerMinute', 'interruptDefault'],
-  tests: ['enabled', 'admission', 'timeoutMs', 'maxBytes', 'autoChecks', 'allowPackageDiscovery'],
+  tests: ['admission', 'timeoutMs', 'maxBytes', 'autoChecks', 'allowPackageDiscovery'],
   gates: ['requireChecks', 'requireTests', 'allowReviewExemption', 'maxReportBytes'],
-  docs: ['board', 'boardLocation'],
-  archive: ['enabled', 'afterDays', 'maxMissions'],
+  docs: ['boardLocation'],
+  archive: ['afterDays', 'maxMissions'],
   leases: ['ttlMs'],
   dev: ['reloadDelayMs', 'reloadRequiredIds'],
 }
 
+// #133/#135: `docs.board` and `archive.enabled` were component-shaped switches
+// hiding in the config form. They are component rows now, so a legacy config
+// keeps failing as an unknown key — with an upgrade note naming the row that
+// replaced it.
+/** @type {Record<string, string>} */
+const REMOVED_KEYS = {
+  'docs.board': 'tower-board',
+  'archive.enabled': 'tower-archive',
+}
+
+/**
+ * Upgrade note for a removed component switch, appended to the unknown-key error.
+ * @param {string} group
+ * @param {string} key
+ * @returns {string}
+ */
+function removedKeyNote(group, key) {
+  const component = REMOVED_KEYS[`${group}.${key}`]
+  if (!component) return ''
+  return ` — ${group}.${key} was removed: the ${component} component row in cordis.patch.yml is the switch (see docs/adr/0005-component-surface.md)`
+}
+
 const MODEL_KEYS = ['provider', 'model', 'reasoningEffort', 'maxTokens']
 
 const ModelSchema = () =>
@@ -147,13 +170,35 @@ export const Config = Schema.object({
     .default({})
     .description('Tower-mode behavior and persistence.'),
   review: Schema.object({
+    // #M39: deliberately *no* schema default here. Cordis resolves the schema
+    // before `apply()` on some paths, and a materialized `mode:'optional'` would
+    // sit next to a legacy `review.requireReview:true` and look like a user
+    // contradiction. The resolver (`resolveTowerConfig`) is the single place
+    // that applies the `optional` default, after alias resolution.
+    // #M40: `.volatile()` is what makes a field editable from the DSH
+    // Plugins-page settings form. The form projection keeps only fields under a
+    // volatile ancestor, and Cordis then hands the runtime a live reference
+    // that is updated in place on a settings write (see host/config.js).
+    //
+    // Both review keys are volatile on purpose: the page must show the
+    // *resolved* policy, and `resolveReviewPolicy` lets the deprecated alias
+    // decide when `mode` is absent. A non-volatile alias would be dropped by the
+    // projection, so a profile that sets only `review.requireReview:true` would
+    // render as Optional (and a save could persist a contradiction). The group
+    // itself stays non-volatile so the tuning keys remain ordinary config.
+    mode: Schema.union(['off', 'optional', 'required'])
+      .volatile()
+      .description(
+      '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.',
+    ),
     requireReview: Schema.boolean()
       .default(false)
-      .description('Require an independent clean review before merge. Default false: review is optional; set true to enforce the review gate globally.'),
+      .volatile()
+      .description('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.'),
     maxRoundsPerReviewer: Schema.natural().min(1).default(5).description('Review-round cap per reviewer per mission branch.'),
   })
     .default({})
-    .description('Review policy.'),
+    .description('Review policy: off, optional (default) or required.'),
   merge: Schema.object({
     timeoutMs: Schema.natural().min(1000).default(900000).description('Default tower_merge timeout, including pre-merge hooks.'),
     maxBufferBytes: Schema.natural().min(65536).default(67108864).description('Captured merge output buffer.'),
@@ -207,7 +252,9 @@ export const Config = Schema.object({
     .default({})
     .description('Message delivery policy.'),
   tests: Schema.object({
-    enabled: Schema.boolean().default(true).description('Run declared test discovery when a mission configures it.'),
+    // #136: no `enabled` switch. The `tower-tests` component row *is* the
+    // switch; a second boolean could only disagree with it, and a row-off
+    // profile has no tower_test tool and no receipt to gate on.
     admission: Schema.union(['spawn', 'complete', 'off'])
       .default('off')
       .description('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).'),
@@ -239,30 +286,24 @@ export const Config = Schema.object({
     .default({})
     .description('Merge-gate strictness.'),
   docs: Schema.object({
-    board: Schema.boolean()
-      .default(true)
-      .description('Write a human-readable MISSIONS.md after mission changes.'),
     boardLocation: Schema.union(['common', 'repo'])
       .default('common')
-      .description('common = <git-common-dir>/dsh-tower/MISSIONS.md; repo = <repoRoot>/MISSIONS.md.'),
+      .description('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).'),
   })
     .default({})
-    .description('Human-readable artifacts.'),
+    .description('Human-readable artifact location. Turning the board off is a component row, not a tuning key.'),
   archive: Schema.object({
-    enabled: Schema.boolean()
-      .default(true)
-      .description('Move terminal (merged/abandoned) missions whose worktree is gone into <git-common-dir>/dsh-tower/archive/ at the next mutation, so state.json stops carrying their full history.'),
     afterDays: Schema.natural()
       .min(0)
       .default(30)
-      .description('Terminal missions untouched for at least this many days are archived on the next mutation (0 archives them immediately).'),
+      .description('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).'),
     maxMissions: Schema.natural()
       .min(0)
       .default(100)
       .description('Maximum terminal missions kept hot; once exceeded, the oldest eligible terminal missions are archived until the cap holds (0 archives every eligible terminal mission).'),
   })
     .default({})
-    .description('Terminal-mission archival policy. Archived missions are moved, never deleted.'),
+    .description('Terminal-mission archival tuning. Whether archival runs at all is the tower-archive component row; archived missions are moved, never deleted.'),
   leases: Schema.object({
     ttlMs: Schema.natural().min(1000).max(86400000).default(900000).description('Default advisory lease lifetime; expiry never auto-releases.'),
   })
@@ -376,9 +417,10 @@ export function assertKnownKeys(raw, label) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) continue
     const bad = Object.keys(value).filter((key) => !allowed.includes(key))
     if (bad.length > 0) {
+      const notes = bad.map((key) => removedKeyNote(group, key)).join('')
       throw new TowerToolError(
         'config-unknown-key',
-        `${label} has unknown key(s) ${bad.map((key) => `${group}.${key}`).join(', ')}`,
+        `${label} has unknown key(s) ${bad.map((key) => `${group}.${key}`).join(', ')}${notes}`,
       )
     }
     if ((group === 'spawn') && value.workerModel && typeof value.workerModel === 'object') {
@@ -413,7 +455,10 @@ export function assertSafeKeys(value, label) {
 
 /** @param {any} [rawConfig] */
 export function resolveTowerConfig(rawConfig) {
-  const raw = rawConfig ?? {}
+  // #M40: the profile config Cordis hands `apply()` carries `review.mode` as a
+  // live volatile reference. Materialize before validation so the value checked
+  // here is the current one; the reference itself stays live in host/config.js.
+  const raw = materializeVolatile(rawConfig ?? {})
   if (raw !== null && typeof raw !== 'object') throw new TowerToolError('config-invalid', 'Tower config must be an object')
   assertKnownKeys(raw, 'Tower config')
   let parsed
@@ -423,13 +468,10 @@ export function resolveTowerConfig(rawConfig) {
     throw new TowerToolError('config-invalid', `Tower config is invalid: ${String(error?.message ?? error)}`)
   }
   const mode = clone(parsed.mode ?? {})
-  if (parsed.gates?.requireTests === true && parsed.tests?.enabled === false) {
-    // #121: the tower-tests *component row* is the capability switch now; a
-    // repository that turns the row off cannot satisfy gates.requireTests. The
-    // component-level half of this invariant is enforced at plan/mode entry,
-    // where the mounted rows are known (host/presets.js).
-    throw new TowerToolError('config-invalid', 'Tower config is invalid: gates.requireTests is true but test discovery is disabled (tests.enabled:false)')
-  }
+  // #136: `tests.enabled` is gone, so this resolver can no longer disagree with
+  // the mounted rows. The component-level invariant (`gates.requireTests:true`
+  // with the `tower-tests` row off) is enforced where the rows are known:
+  // host/presets.js at plan/mode entry, and the merge gate reports its cause.
   // Canonical keys win; the legacy top-level aliases only fill gaps.
   const rawMode = raw.mode ?? {}
   if (rawMode.promptSection === undefined && raw.section !== undefined) mode.promptSection = raw.section
@@ -440,12 +482,28 @@ export function resolveTowerConfig(rawConfig) {
   // Cordis config may omit this key, and an explicit legacy top-level
   // `allowAgentControl:true` must not be shadowed by a schema default.
   if (mode.allowAgentControl === undefined) mode.allowAgentControl = true
+  // F17/#130: materialize the resolved prompt section as well. `section` always
+  // mirrors `mode.promptSection`, so leaving the canonical field absent for a
+  // config with neither key would make a *second* pass copy the just-added
+  // `section:''` back into `mode` (`promptSection:''`): one pass would not be a
+  // fixed point. Filling it here makes `resolve(resolve(raw))` equal
+  // `resolve(raw)` for every valid config without changing any resolved value.
+  if (mode.promptSection === undefined) mode.promptSection = ''
   if (!Array.isArray(mode.denyTools) || mode.denyTools.length === 0) mode.denyTools = [...DEFAULT_DENY_TOOLS]
+  // #M39: resolve the review policy here so every consumer reads one shape.
+  // `review.mode` is canonical; the deprecated `review.requireReview` boolean is
+  // materialized from it (true only for `required`), which keeps older readers
+  // working and makes `resolve(resolve(raw))` a fixed point — the mirrored alias
+  // is compatible with the mode it came from (domain/integration/review.js).
+  const reviewPolicy = resolveReviewPolicy(raw.review)
+  const review = clone(parsed.review ?? {})
+  review.mode = reviewPolicy.mode
+  review.requireReview = reviewPolicy.mode === 'required'
   return {
-    section: mode.promptSection ?? '',
+    section: mode.promptSection,
     init: clone(parsed.init ?? {}),
     mode,
-    review: clone(parsed.review ?? {}),
+    review,
     merge: clone(parsed.merge ?? {}),
     git: clone(parsed.git ?? {}),
     worktrees: clone(parsed.worktrees ?? {}),

package/domain/contracts/outputs.js

@@ -87,6 +87,7 @@ const SCHEMAS = {
       gitLock: S.obj({ held: S.bool, pid: S.any, phase: S.any, heldMs: S.any }),
       mode: S.any,
       spawn: S.any,
+      review: S.any,
       towerAgentId: S.any,
       ownerMissing: S.bool,
     },
@@ -259,6 +260,7 @@ const SCHEMAS = {
       }),
       reports: S.any,
       surface: S.any,
+      review: S.any,
       archive: S.obj({
         missions: S.any,
         archivedMissions: S.int,

package/domain/contracts/tool-inputs/missions.js

@@ -21,7 +21,7 @@ export const PlanInput = Type.Object({
       kind: Type.Optional(enumOf(MISSION_KINDS, { description: 'survey = read-only investigation that reserves no scope.' })),
       context: Type.Optional(Type.String({ description: "The user's own key sentences, verbatim (max 4096 chars)." })),
       references: Type.Optional(Type.Array(Type.String(), { maxItems: 20, description: 'Read-only pointers/files the worker should read (max 20); copied into the briefing.' })),
-      reviewPolicy: Type.Optional(enumOf(REVIEW_POLICIES, { description: 'required-clean (mission default) means a clean review is required when review.requireReview is on; none needs reviewExemptionReason, and with the review gate on it also needs gates.allowReviewExemption.' })),
+      reviewPolicy: Type.Optional(enumOf(REVIEW_POLICIES, { description: 'required-clean (mission default) means a clean review is required when review.mode is required; none needs reviewExemptionReason, and with the review gate on it also needs gates.allowReviewExemption.' })),
       reviewExemptionReason: Type.Optional(Type.String({ description: 'Non-empty justification when reviewPolicy is "none".' })),
     }, { additionalProperties: false }),
     { description: 'Missions to create, in intended order.' },

package/domain/errors.js

@@ -181,6 +181,12 @@ export const ERROR_CODES = {
     retryable: false,
     nextAction: 'complete the mission first, then spawn the reviewer',
   },
+  'review-disabled': {
+    description: 'Review is disabled by `review.mode:off`; no reviewer, verdict, or review blocker exists in this configuration.',
+    trigger: '`tower_spawn` with `role:"reviewer"`, or a review submission, while `review.mode` is `off`',
+    retryable: false,
+    nextAction: 'set review.mode to optional or required in the Tower config, then retry',
+  },
   'not-authorized': {
     description: 'The calling agent role may not perform this action.',
     trigger: 'a worker calling a tower-only tool or changing mission status/scope; a reviewer mutating findings',

package/domain/gate.js

@@ -1,7 +1,7 @@
 // Pure completion gate checks (#49). No repository I/O.
 // @ts-check
 import { isTerminal } from './mission.js'
-import { isReviewExempt, reviewExemptionInvalid } from './integration/review.js'
+import { isReviewExempt, reviewExemptionInvalid, reviewRequired } from './integration/review.js'
 
 /** @typedef {import('../types/index.js').Blocker} Blocker */
 /** @typedef {import('../types/index.js').MergeGateOptions} MergeGateOptions */
@@ -47,7 +47,11 @@ export function completionBlockers(mission, config = {}) {
 
 /**
  * Review, roster, and test-evidence blockers; all inputs are snapshots.
- * @param {MergeGateOptions} options
+ * `testsComponent` is the optional `tower-tests` row state (#140). It is passed
+ * through the options bag rather than declared on `MergeGateOptions` because the
+ * domain may not read the component registry itself: the composition root
+ * publishes the probe on the port bag and `app/gate.js` forwards the snapshot.
+ * @param {MergeGateOptions & { testsComponent?: ({ enabled?: boolean, reason?: string } | null) }} options
  * @returns {Blocker[]}
  */
 export function mergeGateBlockers({
@@ -61,6 +65,7 @@ export function mergeGateBlockers({
   parentStatus = null,
   inactiveStates = [],
   rebaseWaived = false,
+  testsComponent = null,
 }) {
   /** @type {Blocker[]} */
   const blockers = []
@@ -69,13 +74,16 @@ export function mergeGateBlockers({
     blockers.push({ code, detail })
   }
   const inactive = new Set(inactiveStates)
-  const requireReview = config.review?.requireReview !== false
+  // #M39: only `review.mode:required` produces review blockers. `optional`
+  // records reviews without gating, and `off` disables review entirely (no
+  // tower_review, no reviewer spawn), so both skip this whole block.
+  const requireReview = reviewRequired(config)
   const exempt = isReviewExempt(mission, config)
   if (reviewExemptionInvalid(mission, config)) {
     push('review-exemption-invalid', `mission ${mission.id} requests no review but gates.allowReviewExemption is disabled`)
   }
   if (requireReview && !exempt && !review) {
-    push('no-review', `branch ${branch ?? '(none)'} has no review; assign a reviewer first (or set review.requireReview:false)`)
+    push('no-review', `branch ${branch ?? '(none)'} has no review; assign a reviewer first (or set review.mode:optional)`)
   } else if (requireReview && !exempt) {
     const latest = /** @type {Review} */ (review)
     if (latest.missionId !== mission.id) push('review-mission-mismatch', `latest review belongs to mission ${latest.missionId}`)
@@ -106,7 +114,17 @@ export function mergeGateBlockers({
   if (config.gates?.requireTests === true) {
     const runs = (mission.testRuns ?? []).filter((run) => run.ok === true && run.treeTip && branchTip && run.treeTip === branchTip)
     if (runs.length === 0) {
-      push('tests-missing', `mission ${mission.id} has no passing test discovery for tip ${branchTip ? branchTip.slice(0, 7) : '(none)'}`)
+      // #140: name the component cause when the row is off. Without this the
+      // blocker reads as a repository mistake ("no passing discovery") when the
+      // real cause is a disabled row and no tower_test tool exists to produce a
+      // receipt. The component state is a snapshot on the options bag.
+      const tip = branchTip ? branchTip.slice(0, 7) : '(none)'
+      const cause =
+        testsComponent && testsComponent.enabled !== true
+          ? `; ${testsComponent.reason ?? 'disabled by component tower-tests'} so no receipt can exist: ` +
+            're-enable the tower-tests component (or set gates.requireTests:false) and re-record discovery'
+          : ''
+      push('tests-missing', `mission ${mission.id} has no passing test discovery for tip ${tip}${cause}`)
     }
   }
   return blockers

package/domain/integration/review.js

@@ -1,11 +1,197 @@
-// Pure review-selection and exemption decisions shared by the merge/gate/read
-// projections. No repository I/O.
+// Pure review-selection, review-policy resolution and exemption decisions
+// shared by the merge/gate/read projections and the config layer. No repository
+// I/O and no process state.
+//
+// REVIEW POLICY (#M39)
+// --------------------
+// `review.mode` is the single policy with exactly three independent values:
+//
+//   off       review is intentionally unavailable: recording a review is
+//             refused, `tower_spawn` refuses the reviewer role, and the merge
+//             gate ignores review blockers. Registration is profile-time: a
+//             profile-level off does not mount `tower_review`, while a
+//             repository-level off over a profile that mounted it refuses the
+//             submission with `review-disabled`;
+//   optional  review is available but never blocks a merge (the default, and the
+//             2.0.3+ behavior of `review.requireReview:false`);
+//   required  a clean review bound to the branch tip is a merge blocker (the
+//             old `review.requireReview:true` behavior).
+//
+// `review.requireReview` stays accepted for one release as a normalized alias:
+// true -> required, false -> optional. Precedence for one raw config object is
+// deterministic:
+//
+//   * only the alias set: the alias decides;
+//   * only the mode set: the mode decides;
+//   * both set: an alias of `true` next to any mode other than `required` is a
+//     contradiction and is rejected naming both keys. An alias of `false` stays
+//     compatible with `off` because both mean "not required by merge" and the
+//     mode is the more specific policy. That asymmetry is also what keeps the
+//     resolver idempotent: it materializes the alias from the mode it resolved,
+//     and `required` is the only mode that mirrors back to `true`.
 // @ts-check
+import { TowerToolError } from '../errors.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').Review} Review */
 /** @typedef {import('../../types/index.js').TowerConfig} TowerConfig */
 
+export const REVIEW_MODES = Object.freeze(['off', 'optional', 'required'])
+export const DEFAULT_REVIEW_MODE = 'optional'
+
+// Cordis materializes a `.volatile()` schema field as a live reference object
+// (`{ get() }` plus a non-enumerable `Symbol.for('cosmokit.volatile.write')`).
+// Settings forms hand the runtime these references, not plain values, so every
+// consumer below unwraps them before validating or comparing. Keeping the
+// helpers here (instead of a new config module) lets the schema import them
+// without a cycle: review.js has no dependency on schema.js.
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
+
+/**
+ * True for the live reference Cordis/Schemastery creates for a volatile field.
+ * @param {unknown} value
+ * @returns {value is { get: () => unknown }}
+ */
+export function isVolatileRef(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof /** @type {{ get?: unknown }} */ (value).get === 'function' &&
+    Object.getOwnPropertySymbols(value).includes(VOLATILE_WRITE)
+  )
+}
+
+/**
+ * Read a volatile reference once; other values pass through unchanged.
+ * @template T
+ * @param {T | { get: () => T }} value
+ * @returns {T}
+ */
+export function unwrapVolatile(value) {
+  return /** @type {any} */ (isVolatileRef(value) ? value.get() : value)
+}
+
+/**
+ * Deep-copy a raw config object, replacing every volatile reference with its
+ * current value. Non-plain objects (for example a class instance) are returned
+ * as-is; Tower config is JSON-shaped plain data.
+ * @param {unknown} value
+ * @returns {any}
+ */
+export function materializeVolatile(value) {
+  const plain = unwrapVolatile(value)
+  if (Array.isArray(plain)) return plain.map((entry) => materializeVolatile(entry))
+  if (plain === null || typeof plain !== 'object') return plain
+  const proto = Object.getPrototypeOf(plain)
+  if (proto !== Object.prototype && proto !== null) return plain
+  /** @type {Record<string, unknown>} */
+  const copy = {}
+  for (const [key, entry] of Object.entries(plain)) copy[key] = materializeVolatile(entry)
+  return copy
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is 'off' | 'optional' | 'required'}
+ */
+export function isReviewMode(value) {
+  return typeof value === 'string' && REVIEW_MODES.includes(value)
+}
+
+/**
+ * The mode the deprecated boolean alias means.
+ * @param {boolean} requireReview
+ */
+export function legacyReviewMode(requireReview) {
+  return requireReview === true ? 'required' : DEFAULT_REVIEW_MODE
+}
+
+/**
+ * The resolved mode for any config object the runtime may hold: a resolved
+ * config, a raw profile/repo layer, or a hand-built test fixture. An explicit
+ * `mode` always wins; otherwise the deprecated alias decides; otherwise the
+ * documented default applies.
+ * @param {{ review?: any } | null | undefined} [config]
+ * @returns {'off' | 'optional' | 'required'}
+ */
+export function reviewModeOf(config) {
+  const review = config?.review ?? {}
+  const mode = unwrapVolatile(review.mode)
+  if (isReviewMode(mode)) return mode
+  const alias = unwrapVolatile(review.requireReview)
+  if (typeof alias === 'boolean') return legacyReviewMode(alias)
+  return DEFAULT_REVIEW_MODE
+}
+
+/**
+ * The review gate is enforced only in `required`. `off` and `optional` both
+ * ignore review at the merge gate; they differ in availability, not strictness.
+ * @param {{ review?: any } | null | undefined} [config]
+ */
+export function reviewRequired(config) {
+  return reviewModeOf(config) === 'required'
+}
+
+/**
+ * True when review is intentionally switched off (`tower_review` absent,
+ * reviewer spawn refused, merge gate ignores review).
+ * @param {{ review?: any } | null | undefined} [config]
+ */
+export function reviewUnavailable(config) {
+  return reviewModeOf(config) === 'off'
+}
+
+/**
+ * Resolve one raw `review` object (a profile, a repository layer, or a single
+ * written config) into its mode. Rejects contradictory explicit values and an
+ * unknown mode with an actionable `config-invalid` error.
+ *
+ * @param {any} rawReview
+ * @returns {{ mode: 'off' | 'optional' | 'required', explicit: boolean, legacy: boolean }}
+ */
+export function resolveReviewPolicy(rawReview) {
+  const review = rawReview && typeof rawReview === 'object' && !Array.isArray(rawReview) ? rawReview : {}
+  const mode = unwrapVolatile(review.mode)
+  const alias = unwrapVolatile(review.requireReview)
+  if (mode !== undefined && !isReviewMode(mode)) {
+    throw new TowerToolError(
+      'config-invalid',
+      `review.mode must be one of ${REVIEW_MODES.join('|')}, got ${JSON.stringify(mode)}`,
+    )
+  }
+  if (alias !== undefined && typeof alias !== 'boolean') {
+    throw new TowerToolError(
+      'config-invalid',
+      'review.requireReview must be a boolean (deprecated alias: true -> required, false -> optional)',
+    )
+  }
+  if (mode !== undefined && alias === true && mode !== 'required') {
+    throw new TowerToolError(
+      'config-invalid',
+      `review.mode is ${JSON.stringify(mode)} but review.requireReview is true; set only review.mode (off|optional|required) — review.requireReview is a deprecated alias (true -> required, false -> optional) and may not contradict it`,
+    )
+  }
+  if (mode !== undefined) return { mode, explicit: true, legacy: alias !== undefined }
+  if (alias !== undefined) return { mode: legacyReviewMode(alias), explicit: true, legacy: true }
+  return { mode: DEFAULT_REVIEW_MODE, explicit: false, legacy: false }
+}
+
+/**
+ * The small read-only projection reported by `tower_status` and the doctor's
+ * `review` check. `detail` is the one sentence both surfaces share.
+ * @param {{ review?: any } | null | undefined} [config]
+ */
+export function reviewPolicyView(config) {
+  const mode = reviewModeOf(config)
+  const detail =
+    mode === 'off'
+      ? 'review.mode:off — review is intentionally unavailable: recording a review is refused, reviewer spawn is refused, and the merge gate ignores review; a profile-level off does not register tower_review'
+      : mode === 'required'
+        ? 'review.mode:required — a clean review bound to the branch tip is a merge blocker'
+        : 'review.mode:optional — review is available but never blocks a merge'
+  return { mode, available: mode !== 'off', required: mode === 'required', detail }
+}
+
 /**
  * Reviews are branch-scoped; a missing branch has no reviews.
  * @param {Review[] | null | undefined} reviews
@@ -26,27 +212,35 @@ export function latestReview(reviews) {
 }
 
 /**
- * A mission may skip review only with both the exemption gate and a reason.
+ * A mission skips the review gate unless `review.mode` is `required`. In
+ * `required`, it may still skip with both the exemption gate and a reason.
+ * `off` and `optional` both bypass the gate; they differ only in whether the
+ * review tools/spawn role exist.
  * @param {Mission} mission
  * @param {TowerConfig} [config]
  * @returns {boolean}
  */
 export function isReviewExempt(mission, config = {}) {
+  if (!reviewRequired(config)) return true
   return (
-    config.review?.requireReview === false ||
-    (mission.reviewPolicy === 'none' &&
-      config.gates?.allowReviewExemption === true &&
-      String(mission.reviewExemptionReason ?? '').trim().length > 0)
+    mission.reviewPolicy === 'none' &&
+    config.gates?.allowReviewExemption === true &&
+    String(mission.reviewExemptionReason ?? '').trim().length > 0
   )
 }
 
 /**
  * `reviewPolicy: none` is invalid when the reviewer gate does not allow it.
+ * Only `review.mode:required` can make the request invalid; with review off or
+ * optional no review blocker is produced at all.
  * @param {Mission} mission
  * @param {TowerConfig} [config]
  * @returns {boolean}
  */
 export function reviewExemptionInvalid(mission, config = {}) {
-  const requireReview = config.review?.requireReview !== false
-  return requireReview && mission.reviewPolicy === 'none' && config.gates?.allowReviewExemption !== true
+  return (
+    reviewRequired(config) &&
+    mission.reviewPolicy === 'none' &&
+    config.gates?.allowReviewExemption !== true
+  )
 }