dsh-tower 2.5.0 → 2.7.0

package/domain/state/schema.js

@@ -1,15 +1,21 @@
-// Declarative state-file schema (#56 P4).
+// Declarative state-file schema (#56 P4, #149).
 //
 // `StateSchema` describes the structural contract of
-// `<git-common-dir>/dsh-tower/state.json`. Object schemas allow additional
-// properties on purpose: state files are forward/backward compatible and legacy
-// rows carry extra fields. Semantic policy (uniqueness, status/verdict
-// vocabularies, review exemption, worktree records and the revision counter)
-// lives in `./semantics.js`, so this module remains a pure declaration.
+// `<git-common-dir>/dsh-tower/state.json`. Schema v4 splits a mission into a
+// per-shape union: a build mission owns a branch/worktree/merge projection, a
+// survey owns `readCommit`/`readDirty` and may *not* carry the branch-shaped
+// fields. Object schemas allow additional properties on purpose: state files
+// are forward/backward compatible and legacy rows carry extra fields, while the
+// union's forbidden keys are declared `Type.Never()` so a survey carrying a
+// worktree record fails the shape check. Semantic policy (uniqueness,
+// status/verdict vocabularies, review exemption, worktree records and the
+// revision counter) lives in `./semantics.js`, so this module remains a pure
+// declaration.
 // @ts-check
 import { Type } from '@sinclair/typebox'
 import { Value } from '@sinclair/typebox/value'
 import { SCHEMA_VERSION } from '../mission.js'
+import { isShapeKind, shapeFor } from '../shapes/index.js'
 
 const optional = { additionalProperties: true }
 
@@ -17,9 +23,10 @@ const NonNegativeInteger = Type.Integer({ minimum: 0 })
 
 const WorktreeSchema = Type.Object({}, optional)
 
-const MissionSchema = Type.Object(
+const BuildMissionSchema = Type.Object(
   {
     id: Type.String(),
+    kind: Type.Literal('build'),
     status: Type.Optional(Type.String()),
     tasks: Type.Array(Type.Unknown()),
     deps: Type.Array(Type.Unknown()),
@@ -27,10 +34,41 @@ const MissionSchema = Type.Object(
     reviewPolicy: Type.Optional(Type.String()),
     testRuns: Type.Optional(Type.Array(Type.Unknown())),
     worktree: Type.Optional(Type.Union([WorktreeSchema, Type.Null()])),
+    // A build mission reads a base and writes a branch; it never carries the
+    // survey fingerprint or a detached survey sandbox.
+    readCommit: Type.Optional(Type.Never()),
+    readDirty: Type.Optional(Type.Never()),
+    sandbox: Type.Optional(Type.Never()),
   },
   optional,
 )
 
+const SurveyMissionSchema = Type.Object(
+  {
+    id: Type.String(),
+    kind: Type.Literal('survey'),
+    status: Type.Optional(Type.String()),
+    tasks: Type.Array(Type.Unknown()),
+    deps: Type.Array(Type.Unknown()),
+    references: Type.Optional(Type.Array(Type.Unknown())),
+    reviewPolicy: Type.Optional(Type.String()),
+    readCommit: Type.String(),
+    readDirty: Type.Optional(Type.Array(Type.String())),
+    // #148 W2: an optional path to the disposable detached sandbox. Absent for
+    // a shared-checkout survey and for every build.
+    sandbox: Type.Optional(Type.String()),
+    // A survey reads one commit in the shared checkout: no branch shape.
+    worktree: Type.Optional(Type.Never()),
+    branch: Type.Optional(Type.Never()),
+    baseCommit: Type.Optional(Type.Never()),
+    mergedCommit: Type.Optional(Type.Never()),
+    mergedAt: Type.Optional(Type.Never()),
+  },
+  optional,
+)
+
+const MissionSchema = Type.Union([BuildMissionSchema, SurveyMissionSchema])
+
 const RosterEntrySchema = Type.Object(
   {
     name: Type.String(),
@@ -131,6 +169,9 @@ function firstShapeMessage(state, where) {
   for (const mission of state.missions) {
     if (!isPlainObject(mission) || typeof mission.id !== 'string') return `mission entry without id${where}`
     const id = mission.id
+    if (!isShapeKind(mission.kind)) {
+      return `mission ${id} has unknown kind ${String(mission.kind)}${where}`
+    }
     if (!Array.isArray(mission.tasks)) return `mission ${id} has no tasks array${where}`
     if (!Array.isArray(mission.deps)) return `mission ${id} has no deps array${where}`
     if (mission.references !== undefined && !Array.isArray(mission.references)) {
@@ -142,6 +183,27 @@ function firstShapeMessage(state, where) {
     if (mission.testRuns !== undefined && !Array.isArray(mission.testRuns)) {
       return `mission ${id} has no testRuns array${where}`
     }
+    if (isShapeKind(mission.kind)) {
+      const shape = shapeFor(mission.kind)
+      if (shape.fields.readCommit) {
+        if (typeof mission.readCommit !== 'string' || mission.readCommit.length === 0) {
+          return `mission ${id} is a survey and needs a readCommit${where}`
+        }
+        if (mission.readDirty !== undefined && !Array.isArray(mission.readDirty)) {
+          return `mission ${id} has an invalid readDirty fingerprint${where}`
+        }
+        if (mission.sandbox !== undefined && (typeof mission.sandbox !== 'string' || mission.sandbox.length === 0)) {
+          return `mission ${id} has an invalid sandbox path${where}`
+        }
+        if (mission.worktree !== undefined && mission.worktree !== null) {
+          return `mission ${id} is a survey and may not have a worktree record${where}`
+        }
+      } else if (mission.readCommit !== undefined || mission.readDirty !== undefined) {
+        return `mission ${id} is a build and may not have readCommit/readDirty${where}`
+      } else if (mission.sandbox !== undefined) {
+        return `mission ${id} is a build and may not have a sandbox${where}`
+      }
+    }
     if (mission.worktree !== undefined && mission.worktree !== null && !isPlainObject(mission.worktree)) {
       return `mission ${id} has an invalid worktree record${where}`
     }

package/domain/state/semantics.js

@@ -1,12 +1,10 @@
-// Semantic state-file checks (#56 P4).
-//
-// `stateShapeError` proves the structural contract; this module owns the policy
-// the shape cannot express: unique ids, status/verdict vocabularies, the review
-// exemption, roster/agent uniqueness, worktree records and the revision
-// counter. Messages keep the historical `[tower:state-corrupt]` wording.
+// State semantics that a structural schema cannot express: uniqueness,
+// status vocabularies, review exemption and per-kind mission fields (#149).
 // @ts-check
+import { FINDING_STATUSES, MERGE_VERDICTS, REVIEW_STATUS_RE } from '../mission.js'
+import { BATCH_STATUSES } from '../batch.js'
 import { TowerToolError } from '../errors.js'
-import { FINDING_STATUSES, MERGE_VERDICTS, MISSION_STATUSES, REVIEW_STATUS_RE } from '../mission.js'
+import { isShapeKind, shapeFor } from '../shapes/index.js'
 
 /** @typedef {import('../../types/index.js').TowerState} TowerState */
 
@@ -19,11 +17,52 @@ function fail(message) {
 }
 
 /**
- * @param {unknown} value
- * @returns {boolean}
+ * A build mission may carry a worktree/branch/merge projection; a survey may
+ * not, and carries the read fingerprint instead. The shape declares which
+ * dimensions its document owns, so this module never compares kinds.
+ * @param {Record<string, any>} mission
+ * @param {string} where
+ * @returns {void}
  */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
+function assertMissionShapeFields(mission, where) {
+  if (!isShapeKind(mission.kind)) {
+    fail(`mission ${mission.id} has unknown kind ${String(mission.kind)}${where}`)
+  }
+  const shape = shapeFor(mission.kind)
+  if (!shape.fields.worktree) {
+    if (mission.worktree !== undefined && mission.worktree !== null) {
+      fail(`mission ${mission.id} is a ${shape.kind} and may not have a worktree record${where}`)
+    }
+    for (const key of ['branch', 'baseCommit', 'mergedCommit', 'mergedAt']) {
+      if (mission[key] !== undefined && mission[key] !== null) {
+        fail(`mission ${mission.id} is a ${shape.kind} and may not have ${key}${where}`)
+      }
+    }
+  }
+  if (shape.fields.worktree) {
+    if (mission.sandbox !== undefined) {
+      fail(`mission ${mission.id} is a ${shape.kind} and may not have a sandbox${where}`)
+    }
+  } else if (shape.fields.sandbox) {
+    // A detached survey sandbox is a recorded path, never a worktree record: it
+    // has no branch, base commit or merge projection.
+    if (mission.sandbox !== undefined && (typeof mission.sandbox !== 'string' || mission.sandbox.length === 0)) {
+      fail(`mission ${mission.id} has an invalid sandbox path${where}`)
+    }
+  } else if (mission.sandbox !== undefined) {
+    fail(`mission ${mission.id} is a ${shape.kind} and may not have a sandbox${where}`)
+  }
+  if (shape.fields.readCommit) {
+    if (typeof mission.readCommit !== 'string' || mission.readCommit.length === 0) {
+      fail(`mission ${mission.id} is a ${shape.kind} and needs a readCommit${where}`)
+    }
+    if (mission.readDirty === undefined) return
+    if (!Array.isArray(mission.readDirty) || mission.readDirty.some((entry) => typeof entry !== 'string')) {
+      fail(`mission ${mission.id} has an invalid readDirty fingerprint${where}`)
+    }
+  } else if (mission.readCommit !== undefined || mission.readDirty !== undefined) {
+    fail(`mission ${mission.id} is a ${shape.kind} and may not have readCommit/readDirty${where}`)
+  }
 }
 
 /**
@@ -42,6 +81,14 @@ function assertWorktreeRecord(mission, where) {
   if (invalid) fail(`mission ${mission.id} has an invalid worktree record${where}`)
 }
 
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
 /**
  * @param {unknown} state
  * @param {string} where
@@ -56,8 +103,9 @@ export function assertStateSemantics(state, where) {
   for (const mission of record.missions) {
     if (missionIds.has(mission.id)) fail(`duplicate mission id ${mission.id}${where}`)
     missionIds.add(mission.id)
-    if (!MISSION_STATUSES.includes(mission.status)) {
-      fail(`mission ${mission.id} has unknown status ${mission.status}${where}`)
+    const shape = shapeFor(mission.kind)
+    if (!shape.statuses.includes(mission.status)) {
+      fail(`mission ${mission.id} has unknown status ${mission.status} for a ${shape.kind} mission${where}`)
     }
     if (mission.reviewPolicy !== undefined && !['required-clean', 'none'].includes(mission.reviewPolicy)) {
       fail(`mission ${mission.id} has unknown reviewPolicy ${mission.reviewPolicy}${where}`)
@@ -65,7 +113,24 @@ export function assertStateSemantics(state, where) {
     if (mission.reviewPolicy === 'none' && !String(mission.reviewExemptionReason ?? '').trim()) {
       fail(`mission ${mission.id} has reviewPolicy none without a reason${where}`)
     }
+    assertMissionShapeFields(mission, where)
     assertWorktreeRecord(mission, where)
+    // W3: `blocked` is derived from open blockers, never an independent stop
+    // state. A non-terminal mission is blocked exactly when it records a
+    // blocker, so the two can never disagree (a paused mission has no blockers;
+    // a blocker supersedes a pause). Terminal missions keep blockers as history.
+    const blockers = mission.blockers ?? []
+    if (!Array.isArray(blockers) || blockers.some((entry) => typeof entry !== 'string')) {
+      fail(`mission ${mission.id} has invalid blockers${where}`)
+    }
+    if (!shape.isTerminal(mission.status)) {
+      if (mission.status === 'blocked' && blockers.length === 0) {
+        fail(`mission ${mission.id} is blocked but records no blocker; blocked is derived from open blockers${where}`)
+      }
+      if (mission.status !== 'blocked' && blockers.length > 0) {
+        fail(`mission ${mission.id} has open blockers but is ${mission.status}; blocked is derived from open blockers${where}`)
+      }
+    }
   }
   if (record.roster !== undefined) {
     const names = new Set()
@@ -113,5 +178,20 @@ export function assertStateSemantics(state, where) {
       }
     }
   }
+  // Batches have their own generic lifecycle (#149 W3), not a mission shape. The
+  // ledger may only carry canonical statuses; legacy synonyms are normalized by
+  // the v5 state migration, never accepted at rest.
+  if (record.batches !== undefined) {
+    const ids = new Set()
+    for (const batch of record.batches) {
+      if (!isPlainObject(batch)) fail(`invalid batch record${where}`)
+      if (ids.has(batch.id)) fail(`duplicate batch id ${batch.id}${where}`)
+      ids.add(batch.id)
+      const status = typeof batch.status === 'string' ? batch.status : ''
+      if (!BATCH_STATUSES.includes(status)) {
+        fail(`batch ${batch.id} has unknown status ${batch.status}${where}`)
+      }
+    }
+  }
   return /** @type {TowerState} */ (record)
 }

package/domain/state.js

@@ -150,7 +150,10 @@ export function validateState(state, statePath) {
  *
  * @param {unknown} state
  * @param {string} [statePath]
- * @param {{ migrations?: readonly StateMigration[] }} [options]
+ * @param {{
+ *   migrations?: readonly StateMigration[],
+ *   legacySurveyRead?: import('./state/migrations.js').LegacySurveyRead | null,
+ * }} [options]
  * @returns {{ state: TowerState, from: number, to: number, migrated: MigrationStep[], changed: boolean }}
  */
 export function prepareState(state, statePath, options = {}) {
@@ -169,6 +172,7 @@ export function prepareState(state, statePath, options = {}) {
     statePath,
     to: info.supportedVersion,
     migrations: options.migrations,
+    legacySurveyRead: options.legacySurveyRead ?? null,
   })
   // Validation runs on the *target* document: a shape that was invalid under
   // the old schema (a missing `tasks` array, say) may be valid after a backfill,

package/domain/summary.js

@@ -2,6 +2,7 @@
 // @ts-check
 import { FINDING_STATUSES } from './mission.js'
 import { completionReportBytes } from './missions/completion.js'
+import { shapeFor } from './shapes/index.js'
 
 /** @typedef {import('../types/index.js').Finding} Finding */
 /** @typedef {import('../types/index.js').FindingSummary} FindingSummary */
@@ -31,7 +32,8 @@ function taskCounts(tasks) {
  * @returns {MissionSummary}
  */
 export function missionSummary(mission) {
-  return {
+  const shape = shapeFor(mission.kind)
+  return /** @type {MissionSummary} */ ({
     id: mission.id,
     title: mission.title,
     kind: mission.kind,
@@ -39,24 +41,16 @@ export function missionSummary(mission) {
     scope: mission.scope,
     deps: mission.deps,
     owner: mission.owner ?? null,
-    worktree: mission.worktree
-      ? {
-          path: mission.worktree.path,
-          branch: mission.worktree.branch,
-          baseCommit: mission.worktree.baseCommit,
-        }
-      : null,
+    ...shape.summary(mission),
     blockers: mission.blockers ?? [],
     tasks: taskCounts(mission.tasks ?? []),
     scopeGeneration: mission.scopeGeneration ?? 1,
     ownerGeneration: mission.ownerGeneration ?? 0,
     pauseCause: mission.pauseCause ?? null,
     reviewPolicy: mission.reviewPolicy ?? 'required-clean',
-    mergedCommit: mission.mergedCommit ?? null,
-    mergedAt: mission.mergedAt ?? null,
     reportBytes: completionReportBytes(mission.completionReport),
     updatedAt: mission.updatedAt,
-  }
+  })
 }
 
 /**

package/domain/vocabulary.js

@@ -13,6 +13,7 @@ import {
   PAUSE_CAUSES,
 } from './mission.js'
 import { ROSTER_INACTIVE_STATES } from './roster.js'
+import { SHAPE_KINDS } from './shapes/index.js'
 
 export {
   FINDING_SEVERITIES,
@@ -24,44 +25,25 @@ export {
   ROSTER_INACTIVE_STATES,
 }
 
-// Mission inputs accepted by tower_plan.
+// Mission inputs accepted by tower_plan: the registry's kinds, in order.
 /** @type {readonly string[]} */
-export const MISSION_KINDS = ['build', 'survey']
+export const MISSION_KINDS = SHAPE_KINDS
 /** @type {readonly string[]} */
 export const REVIEW_POLICIES = ['required-clean', 'none']
 
 // Roster actors (the caller resolved by actorFor) and createable agent roles.
-export const ROLE = Object.freeze({
-  tower: 'tower',
-  worker: 'worker',
-  reviewer: 'reviewer',
-  unknown: 'unknown',
-})
-/** @type {readonly string[]} */
-export const ROLES = Object.freeze([ROLE.worker, ROLE.reviewer])
-/** @type {readonly string[]} */
-export const ACTOR_ROLES = Object.freeze([ROLE.tower, ROLE.worker, ROLE.reviewer, ROLE.unknown])
-export const DEFAULT_ROLE = ROLE.worker
-
-/** @param {string | null | undefined} role */
-export function isTowerRole(role) {
-  return role === ROLE.tower
-}
-
-/** @param {string | null | undefined} role */
-export function isWorkerRole(role) {
-  return role === ROLE.worker
-}
-
-/** @param {string | null | undefined} role */
-export function isReviewerRole(role) {
-  return role === ROLE.reviewer
-}
-
-/** @param {string | null | undefined} role */
-export function isUnknownRole(role) {
-  return role === ROLE.unknown
-}
+// One definition lives in domain/roles.js so roster/vocabulary have no cycle.
+import { ROLE } from './roles.js'
+export {
+  ACTOR_ROLES,
+  DEFAULT_ROLE,
+  ROLE,
+  ROLES,
+  isReviewerRole,
+  isTowerRole,
+  isUnknownRole,
+  isWorkerRole,
+} from './roles.js'
 
 // Inbox recipients: a roster name, the tower, or a broadcast.
 export const RECIPIENT = Object.freeze({ tower: ROLE.tower, all: 'all' })

package/host/capability-registry.js

@@ -25,6 +25,7 @@ export const TOWER_COMPONENT_IDS = Object.freeze([
   'tower-archive',
   'tower-hmr',
   'preset-tower-reviewer',
+  'tower-survey',
 ])
 
 /** Tool ids each code component owns; the preset row owns no tool. */
@@ -38,6 +39,7 @@ export const COMPONENT_TOOLS = Object.freeze({
   'tower-archive': Object.freeze([]),
   'tower-hmr': Object.freeze(['tower_reload']),
   'preset-tower-reviewer': Object.freeze([]),
+  'tower-survey': Object.freeze([]),
 })
 
 /** id -> number of live registrations (redelivery/HMR can overlap briefly). */
@@ -86,23 +88,37 @@ export function disabledReason(id) {
   return `disabled by component ${id}`
 }
 
-/** Reviewer-preset availability from the optional agent-presets service. */
-async function reviewerPresetAvailable(ctx) {
+/**
+ * Availability of one declarative preset row from the optional agent-presets
+ * service. Preset rows (`preset-tower-reviewer`, `tower-survey`) mount an agent
+ * preset instead of a code entry point, so the process-local component registry
+ * cannot see them.
+ * @param {any} ctx
+ * @param {string} presetId the agent-preset id the row registers
+ * @returns {Promise<boolean | null>} null when the service cannot answer
+ */
+export async function presetAvailable(ctx, presetId) {
   const service = ctx?.get?.('agentPresets')
   if (!service || typeof service.list !== 'function') return null
   try {
     const presets = await service.list()
-    return Array.isArray(presets) && presets.some((entry) => String(entry?.id) === 'tower-reviewer')
+    return Array.isArray(presets) && presets.some((entry) => String(entry?.id) === presetId)
   } catch {
     return null
   }
 }
 
+/** Component rows whose switch is a declarative agent-preset registration. */
+export const PRESET_ROW_COMPONENTS = Object.freeze({
+  'preset-tower-reviewer': 'tower-reviewer',
+  'tower-survey': 'tower-survey',
+})
+
 /**
- * Report every optional component as enabled or disabled. The reviewer preset
- * is not a code entry point: its row mounts an agent preset, so availability is
- * read from `agentPresets` and reported as unknown (omitted) when that service
- * is absent, exactly as the doctor's preset check does.
+ * Report every optional component as enabled or disabled. A preset row is not a
+ * code entry point: its availability is read from `agentPresets` and reported as
+ * unknown (omitted) when that service is absent, exactly as the doctor's preset
+ * check does.
  *
  * @param {any} ctx
  * @returns {Promise<{ enabled: string[], disabled: Array<{ id: string, reason: string }> }>}
@@ -111,8 +127,8 @@ export async function componentReport(ctx) {
   const enabled = []
   const disabled = []
   for (const id of TOWER_COMPONENT_IDS) {
-    if (id === 'preset-tower-reviewer') {
-      const available = await reviewerPresetAvailable(ctx)
+    if (PRESET_ROW_COMPONENTS[id]) {
+      const available = await presetAvailable(ctx, PRESET_ROW_COMPONENTS[id])
       if (available === false) disabled.push({ id, reason: disabledReason(id) })
       else if (available === true) enabled.push(id)
       continue

package/host/config.js

@@ -24,6 +24,7 @@ import {
   resolveTowerConfig,
 } from '../domain/config/schema.js'
 import { TowerToolError } from '../domain/errors.js'
+import { materializeVolatile, resolveReviewPolicy, reviewUnavailable } from '../domain/integration/review.js'
 
 export { Config, DEFAULT_DENY_TOOLS, resolveTowerConfig }
 
@@ -31,11 +32,16 @@ const REPO_CONFIG_MAX_BYTES = 1024 * 1024
 
 // The last raw profile config `apply()` received; repository config is merged
 // over it so a repo can tune spawn/merge/review without editing the profile.
+//
+// #M40: this must stay the *raw* object. A `.volatile()` field arrives as a
+// live reference that Cordis updates in place on a settings write, and cloning
+// (JSON) would freeze a copy and hide the new value from runtimeConfig(). Only
+// readers that need plain data (profileConfig) materialize it.
 let profileRaw = {}
 
 export function configureRuntime(config) {
-  profileRaw = clone(config ?? {}) ?? {}
-  return resolveTowerConfig(config)
+  profileRaw = config ?? {}
+  return resolveTowerConfig(profileRaw)
 }
 
 export function runtimeConfig() {
@@ -44,7 +50,7 @@ export function runtimeConfig() {
 
 /** Raw profile config before defaults are materialized (for doctor warnings). */
 export function profileConfig() {
-  return clone(profileRaw) ?? {}
+  return clone(materializeVolatile(profileRaw)) ?? {}
 }
 
 export function repoConfigPath(commonDir) {
@@ -92,6 +98,10 @@ export async function readRepoConfig(commonDir) {
     // Validate value types without letting the schema's defaults win over the
     // profile layer: merge into an empty raw object and discard the result.
     Config(parsed)
+    // #M39: the schema accepts both review keys; only the resolver knows that an
+    // explicit `requireReview:true` next to a conflicting `review.mode` is a
+    // contradiction. Reject it here, before the layer can be merged.
+    resolveReviewPolicy(parsed.review)
   } catch (error) {
     throw new TowerToolError('config-invalid', `repo config at ${file} is invalid: ${String(error?.message ?? error)}`)
   }
@@ -130,6 +140,33 @@ export async function resolveRepoConfig(repo) {
   if (!Array.isArray(merged.mode?.denyTools) || merged.mode.denyTools.length === 0) {
     merged.mode = { ...(merged.mode ?? {}), denyTools: [...DEFAULT_DENY_TOOLS] }
   }
+  // #M39: the review policy is resolved per layer instead of deep-merging two
+  // resolved shapes. A resolved base always carries both `review.mode` and its
+  // mirrored alias, so a repository layer that sets only one of the two would
+  // otherwise pair a stale inherited `mode` with the new alias. The repository
+  // layer wins as a whole when it names either key; a layer that names neither
+  // inherits the profile policy untouched.
+  const repoReview = repoLayer.review
+  if (repoReview && typeof repoReview === 'object' && !Array.isArray(repoReview)) {
+    const explicit = repoReview.mode !== undefined || repoReview.requireReview !== undefined
+    if (explicit) {
+      const repoPolicy = resolveReviewPolicy(repoReview)
+      if (reviewUnavailable(base) && repoPolicy.mode !== 'off') {
+        // The tool surface is fixed when the plugin applies: a profile with
+        // review off never registered tower_review, so a repository may relax
+        // review further but cannot re-enable a tool that does not exist.
+        throw new TowerToolError(
+          'config-invalid',
+          `review.mode is off in the profile, so tower_review is not registered; repository config cannot set review.mode:${repoPolicy.mode}. Set review.mode in the profile instead.`,
+        )
+      }
+      merged.review = {
+        ...(merged.review ?? {}),
+        mode: repoPolicy.mode,
+        requireReview: repoPolicy.mode === 'required',
+      }
+    }
+  }
   merged.section = merged.mode?.promptSection ?? merged.section ?? ''
   return {
     ...merged,

package/host/doctor.js

@@ -12,7 +12,9 @@ import { inspectStateVersion } from '../domain/state.js'
 import { SCHEMA_VERSION } from '../domain/mission.js'
 import { DEFAULT_MAX_REPORT_BYTES, completionReportBytes } from '../domain/missions/completion.js'
 import { comparisonMode } from '../domain/scope.js'
+import { hasTestReceipts } from '../domain/evidence.js'
 import { configSurface } from '../domain/config/schema.js'
+import { reviewPolicyView, reviewRequired } from '../domain/integration/review.js'
 import { parseBaseline, surfaceLine, SURFACE_BASELINE_FILE } from '../domain/surface.js'
 import { assessHostVersion, detectHostVersion, readCompatibility } from './compatibility.js'
 import { profileConfig } from './config.js'
@@ -242,8 +244,11 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
   const config = tower.config ?? {}
   const profile = profileConfig()
   const staleDefaults = []
-  if (profile.review && profile.review.requireReview === undefined) {
-    staleDefaults.push('review.requireReview now defaults to false (2.0.3)')
+  // #M39: `review.mode` replaces the deprecated boolean. A profile that names
+  // neither key relies on the default (optional), so say so rather than letting
+  // a reader assume review is enforced.
+  if (profile.review && profile.review.mode === undefined && profile.review.requireReview === undefined) {
+    staleDefaults.push('review.mode defaults to optional; review.requireReview is a deprecated alias')
   }
   if (profile.mode && profile.mode.allowAgentControl === undefined) {
     staleDefaults.push('mode.allowAgentControl now defaults to true (2.0.4)')
@@ -261,6 +266,11 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
       'optional: add <git-common-dir>/dsh-tower/config.json',
     ),
   )
+  // #M39: the resolved review mode is its own diagnostic fact. `off` is a
+  // supported, intentional posture (not a degradation), so it is a pass whose
+  // detail says exactly what is unavailable.
+  const reviewPolicy = reviewPolicyView(config)
+  checks.push(check('review', 'pass', reviewPolicy.detail))
   // #84: report the concept-budget surface instead of implying it. The counts
   // are the live schema/tool surface; the date is the committed baseline, so a
   // reader sees both the number and the decision it was frozen at.
@@ -288,7 +298,7 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
         ),
   )
   const presets = ctx.get?.('agentPresets')
-  const reviewerRequired = config.review?.requireReview === true
+  const reviewerRequired = reviewRequired(config)
   if (presets && typeof presets.list === 'function') {
     try {
       const available = (await presets.list()).map((entry) => String(entry.id))
@@ -296,9 +306,10 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
       const reviewer = config.spawn?.reviewerPreset ?? 'tower-reviewer'
       const required = reviewerRequired ? [worker, reviewer] : [worker]
       const missing = required.filter((id) => !available.includes(id))
-      // #121: `preset-tower-reviewer` is a conditional component. Its off state
-      // is supported while review.requireReview is false; with the gate on it is
-      // a fail, because no independent review can be dispatched.
+      // #121/#M39: `preset-tower-reviewer` is a conditional component. Its off
+      // state is supported while review is off or optional; with
+      // `review.mode:required` it is a fail, because no independent review can
+      // be dispatched.
       if (missing.length === 0) {
         const reviewerNote = available.includes(reviewer)
           ? `reviewer=${reviewer}`
@@ -309,7 +320,7 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
           check(
             'presets',
             'fail',
-            `missing preset(s): ${missing.join(', ')}${reviewerRequired && missing.includes(reviewer) ? ' (review.requireReview is true, so preset-tower-reviewer may not be off)' : ''}`,
+            `missing preset(s): ${missing.join(', ')}${reviewerRequired && missing.includes(reviewer) ? ' (review.mode is required, so preset-tower-reviewer may not be off)' : ''}`,
             'enable the Tower preset component and retry',
           ),
         )
@@ -444,7 +455,7 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
           : check('worktrees', 'pass', `all registered worktrees are valid${removedNote}`),
     )
 
-    const testConfigured = state.missions?.some((mission) => mission.testRuns !== undefined)
+    const testConfigured = state.missions?.some((mission) => hasTestReceipts(mission))
     // #136: the `tower-tests` component row is the only switch (there is no
     // tests.enabled), so this check reads the registry and nothing else.
     const testsDisabled = components.disabled.some((entry) => entry.id === 'tower-tests')
@@ -596,6 +607,7 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
 // reports (from #89) and archive (from #73) are both kept
     reports: reportsReport,
     surface: surfaceReport,
+    review: reviewPolicy,
     components,
     archive: {
       missions: state ? state.missions.length : null,

package/host/preset-survey-sandbox.js

@@ -0,0 +1,19 @@
+// Tower detached-survey preset declaration (#148 W2): the sandbox preset's own
+// Plugins-page label. This is the writable twin of `host/preset-survey.js`: the
+// row config stays in `cordis.patch.yml` and this module forwards it to the
+// injected `agentPresets` service, which owns mount/unmount. A Tower-owned
+// specifier gives the row a distinct locale
+// (`dsh-tower/preset-survey-sandbox/locale/<lang>.json`).
+export const name = 'dsh-tower/preset-survey-sandbox'
+
+export const inject = ['agentPresets']
+
+/**
+ * Register the detached-survey preset with the profile's preset registry.
+ * @param {{ agentPresets: { register: (config: any) => Promise<() => Promise<void> | void> } }} ctx
+ * @param {any} config the `cordis.patch.yml` row config (id/name/description/order/plugins)
+ * @returns {Promise<() => Promise<void> | void>} the registry's unregister disposer
+ */
+export async function apply(ctx, config) {
+  return ctx.agentPresets.register(config)
+}