dsh-tower 2.5.0 → 2.7.0

package/domain/collab/spawn.js

@@ -7,6 +7,8 @@
 // @ts-check
 import { TowerToolError } from '../errors.js'
 import { ROSTER_INACTIVE, countLiveWorkers, workerEntries } from '../roster.js'
+import { isReviewerRole, isWorkerRole } from '../roles.js'
+import { shapeFor } from '../shapes/index.js'
 import { clearStale } from './roster.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
@@ -14,19 +16,14 @@ import { clearStale } from './roster.js'
 
 /**
  * @param {string} message
+ * @param {string} [code]
  * @returns {never}
  */
-function fail(message) {
-  throw new TowerToolError('invalid-argument', message)
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
 }
 
-/**
- * @param {unknown} role
- * @returns {boolean}
- */
-export function isWorkerRole(role) {
-  return role === 'worker'
-}
+export { isWorkerRole } from '../roles.js'
 
 /**
  * The configured live-worker ceiling, defaulting to four.
@@ -67,6 +64,26 @@ export function applyInterrupt(entry, input, now) {
   return entry
 }
 
+/**
+ * A reviewer's evidence is the commit recorded here, never a live branch tip
+ * read later (#149 W3). The checkout is the disposable detached worktree the
+ * reviewer reads in; it is cleared when the verdict is recorded.
+ * @param {any} input
+ * @param {{ requireReviewCommit?: boolean }} [options]
+ * @returns {{ reviewCommit: string | null, reviewCheckout: string | null }}
+ */
+function reviewEvidence(input, options = {}) {
+  const reviewCommit = typeof input.reviewCommit === 'string' && input.reviewCommit.length > 0 ? input.reviewCommit : null
+  const reviewCheckout = typeof input.reviewCheckout === 'string' && input.reviewCheckout.length > 0 ? input.reviewCheckout : null
+  if (options.requireReviewCommit && isReviewerRole(input.role) && !reviewCommit) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `reviewer ${input.name} has no recorded review commit; spawn reviewers through tower_spawn (a review verdict is stamped with a commit, not a live branch tip)`,
+    )
+  }
+  return { reviewCommit, reviewCheckout }
+}
+
 /**
  * A reserved roster row: the name is claimed before activation so a failed
  * spawn remains recoverable.
@@ -75,6 +92,7 @@ export function applyInterrupt(entry, input, now) {
  * @returns {RosterEntry}
  */
 export function reservedRosterEntry(input, now) {
+  const evidence = reviewEvidence(input, { requireReviewCommit: true })
   return {
     name: input.name,
     role: input.role,
@@ -84,6 +102,8 @@ export function reservedRosterEntry(input, now) {
     missionId: input.missionId,
     cwd: input.cwd ?? null,
     branch: input.branch ?? null,
+    ...(evidence.reviewCommit ? { reviewCommit: evidence.reviewCommit } : {}),
+    ...(evidence.reviewCheckout ? { reviewCheckout: evidence.reviewCheckout } : {}),
     spawnTip: null,
     state: 'reserved',
     reservedAt: now,
@@ -104,10 +124,15 @@ export function reserveRosterEntry({ roster, input, now }) {
 /**
  * Validate and apply a spawn record. Mutates the roster (retiring prior worker
  * rows and inserting/reusing the entry) and the mission owner/status/gen.
- * @param {{ roster: RosterEntry[], mission: Mission, input: any, spawnTip: string | null, maxLiveWorkers: unknown, now: number }} params
+ *
+ * `missions` is the state's mission list, not just the spawned mission: the live
+ * worker count resolves every roster row's kind through the shape registry, so a
+ * survey row must not be counted as a build worker (#148). Callers that omit it
+ * (direct domain tests) keep the historical roster-only treatment.
+ * @param {{ roster: RosterEntry[], missions?: Mission[], mission: Mission, input: any, spawnTip: string | null, maxLiveWorkers: unknown, now: number }} params
  * @returns {RosterEntry}
  */
-export function recordSpawnEntry({ roster, mission, input, spawnTip, maxLiveWorkers, now }) {
+export function recordSpawnEntry({ roster, missions = [], mission, input, spawnTip, maxLiveWorkers, now }) {
   const reserved = roster.find((entry) => entry.name === input.name && entry.state === 'reserved' && !entry.agentId)
   if (!reserved && roster.some((entry) => entry.name === input.name)) {
     fail(`roster name already used: ${input.name}`)
@@ -115,7 +140,9 @@ export function recordSpawnEntry({ roster, mission, input, spawnTip, maxLiveWork
   if (roster.some((entry) => entry.agentId && entry.agentId === input.agentId)) {
     fail(`agent ${input.agentId} is already in the roster`)
   }
-  /** @type {RosterEntry} */
+  /** @type {{ reviewCommit?: string | null, reviewCheckout?: string | null }} */
+  const evidence = reviewEvidence(input, { requireReviewCommit: true })
+  /** @type {RosterEntry & { generation?: number }} */
   const entry = {
     name: input.name,
     role: input.role,
@@ -125,12 +152,14 @@ export function recordSpawnEntry({ roster, mission, input, spawnTip, maxLiveWork
     missionId: input.missionId,
     cwd: input.cwd ?? null,
     branch: input.branch ?? null,
+    ...(evidence.reviewCommit ? { reviewCommit: evidence.reviewCommit } : {}),
+    ...(evidence.reviewCheckout ? { reviewCheckout: evidence.reviewCheckout } : {}),
     spawnTip,
     state: 'active',
     spawnedAt: now,
   }
   if (isWorkerRole(input.role)) {
-    const snapshot = /** @type {any} */ ({ roster })
+    const snapshot = /** @type {any} */ ({ roster, missions })
     const previous = workerEntries(snapshot, mission.id)
     const live = previous.find((row) => !ROSTER_INACTIVE.has(row.state) && row.state !== 'reserved')
     if (live && !input.takeover) {
@@ -148,9 +177,17 @@ export function recordSpawnEntry({ roster, mission, input, spawnTip, maxLiveWork
       old.outcomeAt = now
       clearStale(old)
     }
-    const max = liveWorkerLimit(maxLiveWorkers)
-    if (countLiveWorkers(snapshot) >= max) {
-      fail(`live worker limit reached (${max}); stop a worker or raise spawn.maxLiveWorkers`)
+    // A shape that does not count toward the live-worker budget (the read-only
+    // survey) must pass even when every build slot is busy; otherwise the
+    // precheck and the record-level check disagree (#148).
+    if (shapeFor(mission.kind).spawn.countsTowardWorkerBudget !== false) {
+      const max = liveWorkerLimit(maxLiveWorkers)
+      if (countLiveWorkers(snapshot) >= max) {
+        fail(
+          `live worker limit reached (${max}); stop a worker or raise spawn.maxLiveWorkers`,
+          'worker-limit',
+        )
+      }
     }
     const generation = (mission.ownerGeneration ?? 0) + 1
     entry.generation = generation

package/domain/components.js

@@ -3,8 +3,11 @@
 // Principle 11 says optional capabilities are switches and the core is not. This
 // module is that policy as data plus the pure checks over it: the component rows
 // in `cordis.patch.yml`, the four-way classification of every config key, and
-// the forbidden-to-disable capabilities (host, health, recovery, review contract,
-// merge gates) that no group, row or boolean key may gate.
+// the forbidden-to-disable capabilities (host, health, recovery, merge gates)
+// that no group, row or boolean key may gate. The review policy is not one of
+// those never-switches: `review.mode` is the one tri-state control, and only the
+// gate it turns on in `required` mode (evidence, tip binding, exemption path) is
+// non-disableable.
 //
 // The single source of truth is `scripts/component-surface.json`. The generated
 // reference `docs/reference/component-surface.md` is a rendering of it, so
@@ -700,8 +703,13 @@ ${componentRows}
 
 ## 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.
 

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',
@@ -36,7 +37,7 @@ const LEGACY_KEYS = ['section', 'allowAgentControl']
 // #121: the `tools` group is gone. Every capability that used to be a
 // `tools.expose*` boolean is now a component row in `cordis.patch.yml`, and a
 // component row is the switch. What remains here is genuine tuning policy.
-const GROUP_KEYS = ['init', 'mode', 'review', 'merge', 'git', 'worktrees', 'spawn', 'send', 'tests', 'gates', 'docs', 'archive', 'leases', 'dev']
+const GROUP_KEYS = ['init', 'mode', 'review', 'merge', 'git', 'worktrees', 'spawn', 'send', 'survey', 'tests', 'gates', 'docs', 'archive', 'leases', 'dev']
 
 const SECTION_KEYS = {
   init: ['autoGitInit', 'snapshotDirty', 'autoExclude'],
@@ -57,7 +58,7 @@ const SECTION_KEYS = {
     'maxEntries',
     'lockTimeoutMs',
   ],
-  review: ['requireReview', 'maxRoundsPerReviewer'],
+  review: ['mode', 'requireReview', 'maxRoundsPerReviewer'],
   merge: ['timeoutMs', 'maxBufferBytes'],
   git: ['timeoutMs'],
   worktrees: ['root'],
@@ -68,40 +69,54 @@ const SECTION_KEYS = {
     'provider',
     'workerModel',
     'reviewerModel',
+    'surveyModel',
     'maxLiveWorkers',
     'staleMs',
     'maxWaitMs',
     'requireLease',
   ],
   send: ['maxPerMinute', 'interruptDefault'],
-  tests: ['admission', 'timeoutMs', 'maxBytes', 'autoChecks', 'allowPackageDiscovery'],
-  gates: ['requireChecks', 'requireTests', 'allowReviewExemption', 'maxReportBytes'],
+  // #148 W2: where a survey reads. This is tuning, not a component: the
+  // tower-survey row is the switch; the placement decides whether write/shell
+  // side effects are rejected (shared) or absorbed by a disposable checkout.
+  survey: ['sandbox'],
+  tests: ['admission', 'timeoutMs', 'maxBytes', 'allowPackageDiscovery'],
+  gates: ['requireChecks', 'requireTests', 'allowReviewExemption', 'requireFreshSurvey', 'maxReportBytes'],
   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>} */
+// #133/#135/#149: a removed key keeps failing as an unknown key — with an
+// upgrade note naming what replaced it. `docs.board` and `archive.enabled`
+// were component-shaped switches hiding in the config form, so their note
+// names the component row. `tests.autoChecks` existed only to copy a discovery
+// projection into the completion report; its replacement is the `testRuns`
+// receipt (whose concrete record path belongs to domain/evidence.js), so the
+// note names the receipt and the one reader instead of a row.
+/** @type {Record<string, { component?: string, note?: string }>} */
 const REMOVED_KEYS = {
-  'docs.board': 'tower-board',
-  'archive.enabled': 'tower-archive',
+  'docs.board': { component: 'tower-board' },
+  'archive.enabled': { component: 'tower-archive' },
+  'tests.autoChecks': {
+    note: 'tests.autoChecks was removed: test evidence is the testRuns receipt read by domain/evidence.js (see docs/adr/0006-mission-shapes.md)',
+  },
 }
 
 /**
- * Upgrade note for a removed component switch, appended to the unknown-key error.
+ * Upgrade note for a removed key, 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 entry = REMOVED_KEYS[`${group}.${key}`]
+  if (!entry) return ''
+  if (entry.component) {
+    return ` — ${group}.${key} was removed: the ${entry.component} component row in cordis.patch.yml is the switch (see docs/adr/0005-component-surface.md)`
+  }
+  return ` — ${entry.note}`
 }
 
 const MODEL_KEYS = ['provider', 'model', 'reasoningEffort', 'maxTokens']
@@ -169,13 +184,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.'),
@@ -193,12 +230,13 @@ export const Config = Schema.object({
     .default({})
     .description('Worktree placement.'),
   spawn: Schema.object({
-    workerPreset: Schema.string().default('tower-worker').description('Agent preset for worker missions.'),
+    workerPreset: Schema.string().default('tower-worker').description('Agent preset for build workers.'),
     reviewerPreset: Schema.string().default('tower-reviewer').description('Agent preset for reviewers.'),
     maxDepth: Schema.natural().min(1).default(1).description('Subagent depth requested when spawning tower agents.'),
     provider: Schema.string().description('Subagent provider id; empty picks spawn, then the first registered provider.'),
     workerModel: ModelSchema().description('Model route for workers; omitted inherits the parent session.'),
     reviewerModel: ModelSchema().description('Model route for reviewers; omitted inherits the parent session (recommended).'),
+    surveyModel: ModelSchema().description('Model route for survey workers; omitted inherits the parent session.'),
     maxLiveWorkers: Schema.natural()
       .min(1)
       .max(64)
@@ -228,6 +266,15 @@ export const Config = Schema.object({
   })
     .default({})
     .description('Message delivery policy.'),
+  survey: Schema.object({
+    sandbox: Schema.union(['none', 'detached'])
+      .default('none')
+      .description(
+        '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.',
+      ),
+  })
+    .default({})
+    .description('Survey placement. Tuning only: the tower-survey component row is the capability switch.'),
   tests: Schema.object({
     // #136: no `enabled` switch. The `tower-tests` component row *is* the
     // switch; a second boolean could only disagree with it, and a row-off
@@ -237,7 +284,6 @@ export const Config = Schema.object({
       .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).'),
     timeoutMs: Schema.natural().min(1000).max(1800000).default(60000).description('Per discovery command timeout.'),
     maxBytes: Schema.natural().min(1024).max(16 * 1024 * 1024).default(16 * 1024 * 1024).description('Maximum captured stdout bytes per command.'),
-    autoChecks: Schema.boolean().default(true).description('Attach a tests check to the completion report when discovery runs.'),
     allowPackageDiscovery: Schema.boolean()
       .default(true)
       .description('Allow package.json tower.testDiscovery commands from the mission worktree (executes repository code; see security docs).'),
@@ -247,13 +293,16 @@ export const Config = Schema.object({
   gates: Schema.object({
     requireChecks: Schema.boolean()
       .default(false)
-      .description('Require at least one completion check (tower_complete.checks) before a mission can merge.'),
+      .description('Require at least one recorded check (tower_complete.checks) or test-discovery receipt before a mission can merge.'),
     requireTests: Schema.boolean()
       .default(false)
       .description('Require a passing test-discovery receipt for the reviewed worktree tip before merge.'),
     allowReviewExemption: Schema.boolean()
       .default(false)
       .description('Allow reviewPolicy:none missions with a non-empty reviewExemptionReason to skip review blockers.'),
+    requireFreshSurvey: Schema.boolean()
+      .default(false)
+      .description('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).'),
     maxReportBytes: Schema.natural()
       .min(1024)
       .max(16 * 1024 * 1024)
@@ -406,6 +455,9 @@ export function assertKnownKeys(raw, label) {
     if ((group === 'spawn') && value.reviewerModel && typeof value.reviewerModel === 'object') {
       assertModelKeys(value.reviewerModel, `${label} spawn.reviewerModel`)
     }
+    if ((group === 'spawn') && value.surveyModel && typeof value.surveyModel === 'object') {
+      assertModelKeys(value.surveyModel, `${label} spawn.surveyModel`)
+    }
   }
 }
 
@@ -432,7 +484,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
@@ -464,16 +519,26 @@ export function resolveTowerConfig(rawConfig) {
   // `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,
     init: clone(parsed.init ?? {}),
     mode,
-    review: clone(parsed.review ?? {}),
+    review,
     merge: clone(parsed.merge ?? {}),
     git: clone(parsed.git ?? {}),
     worktrees: clone(parsed.worktrees ?? {}),
     spawn: clone(parsed.spawn ?? {}),
     send: clone(parsed.send ?? {}),
+    survey: clone(parsed.survey ?? {}),
     tests: clone(parsed.tests ?? {}),
     gates: clone(parsed.gates ?? {}),
     docs: clone(parsed.docs ?? {}),

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,
@@ -287,7 +289,6 @@ const SCHEMAS = {
       commands: S.arr(S.obj()),
       error: S.str,
       receipt: S.obj(),
-      checks: S.arr(S.obj()),
     },
     ['ok', 'configured'],
   ),

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

@@ -17,11 +17,11 @@ export const PlanInput = Type.Object({
       title: Type.String({ description: 'Printable Unicode mission title, NFC-normalized, at most 120 characters; used as the mission label.' }),
       scope: Type.Optional(Type.Array(Type.String(), { description: 'Relative file globs this mission may touch; empty only for survey.' })),
       tasks: Type.Optional(Type.Array(Type.String(), { description: 'Verifiable task items the worker ticks off.' })),
-      deps: Type.Optional(Type.Array(Type.String(), { description: 'Mission ids that must merge before this one.' })),
+      deps: Type.Optional(Type.Array(Type.String(), { description: 'Mission ids that must be satisfied before this one: merged for a build, completed for a survey.' })),
       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.' },
@@ -63,6 +63,14 @@ export const CompleteInput = Type.Object({
   missionId: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: id).' })),
   id: Type.Optional(Type.String({ description: 'Alias for missionId; both are accepted.' })),
   report: Type.String({ description: 'Full completion report for the tower and the next review round.' }),
+  result: Type.Optional(
+    Type.Object({
+      paths: Type.Optional(Type.Array(Type.String(), { maxItems: 200, description: 'Survey only: paths the read touched or found relevant.' })),
+      symbols: Type.Optional(Type.Array(Type.String(), { maxItems: 200, description: 'Survey only: symbols the read identified.' })),
+      plan: Type.Optional(Type.Array(Type.String(), { maxItems: 200, description: 'Survey only: the ordered plan or next steps the read recommends.' })),
+      notes: Type.Optional(Type.String({ description: 'Survey only: short free-form evidence (max 4000 chars).' })),
+    }, { additionalProperties: false, description: 'Survey evidence; a build completion may not carry one.' }),
+  ),
   checks: Type.Optional(
     Type.Array(
       Type.Object({

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',