dsh-tower 2.6.0 → 2.7.0

package/scripts/surface-baseline.json

@@ -4,7 +4,7 @@
   "surfaces": {
     "configKeys": {
       "seed": 64,
-      "value": 54,
+      "value": 56,
       "decisions": [
         {
           "from": 64,
@@ -19,13 +19,70 @@
           "date": "2026-11-03",
           "adr": "docs/adr/0005-component-surface.md",
           "note": "#M39: one new key, review.mode (off/optional/required), replaces the deprecated review.requireReview boolean as the review policy. It is not a fifth component row: the reviewer preset row stays a capability, and the mode decides whether it is required (required) or unused (off). review.requireReview remains accepted for one release as a normalized alias, so it is a deprecated key rather than a removed one and the surface grows by exactly one."
+        },
+        {
+          "from": 54,
+          "to": 57,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148/#149: the shape redesign adds the survey routing keys spawn.surveyPreset (core) and spawn.surveyModel (tuning), plus survey.sandbox (tuning) in the new survey section. tower-survey is the capability row; the preset/model names only route the read-only agent."
+        },
+        {
+          "from": 57,
+          "to": 55,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "Review round 2 contracts the shape surface before release: spawn.surveyPreset could never be read (a survey's preset is shape-owned, so the key could only disagree with the registry) and survey.sandbox advertised a placement W1 does not implement. Only spawn.surveyModel remains as the optional model route; both removals are recorded here rather than silently shrinking the two-way surface."
+        },
+        {
+          "from": 55,
+          "to": 56,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148 W2 implements the detached survey sandbox, so survey.sandbox returns as one tuning key: none (read-only shared checkout, the default and unchanged W1 behavior) or detached (a disposable detached worktree with a write/shell-capable preset). It is placement tuning, not a capability row or a second routing key; spawn.surveyPreset stays removed because the shape resolves the preset."
+        },
+        {
+          "from": 56,
+          "to": 57,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148 W2 D5 adds gates.requireFreshSurvey (default false): the survey-stale dependency warning is advisory by default and becomes a merge blocker only when this gate is true. It is a merge-gate strictness key like the other gates.* entries, not a component."
+        },
+        {
+          "from": 57,
+          "to": 56,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#149 W4 contracts the surface by one: `tests.autoChecks` existed only to copy a discovery projection into the completion report, which made a second evidence shape. The receipt in mission.testRuns is now the one evidence shape read by domain/evidence.js, so the key has no remaining meaning and is removed rather than kept as a dead tuning switch."
         }
       ]
     },
     "sections": {
       "seed": 15,
-      "value": 14,
-      "decisions": []
+      "value": 15,
+      "decisions": [
+        {
+          "from": 15,
+          "to": 15,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148/#149 restore the section count to its seed: survey.sandbox needs a home, so the survey section returns the 15 sections that #121 shrank to 14. Net zero against the seed; no other section changed."
+        },
+        {
+          "from": 15,
+          "to": 14,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "Review round 2 removes the survey section with its only key: survey.sandbox advertised a detached read-only checkout W1 does not implement. The section existed only to hold that key, so the count returns to 14."
+        },
+        {
+          "from": 14,
+          "to": 15,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148 W2 restores the survey section for its one tuning key, survey.sandbox (placement: none|detached). The section count returns to the 15 of the earlier shape cut; no other section changed and no component row was added (the sandbox preset is an internal child of the existing tower-survey group)."
+        }
+      ]
     },
     "tools": {
       "seed": 27,
@@ -45,7 +102,7 @@
     },
     "components": {
       "seed": 4,
-      "value": 11,
+      "value": 12,
       "decisions": [
         {
           "from": 4,
@@ -81,6 +138,13 @@
           "date": "2026-11-02",
           "adr": "docs/adr/0005-component-surface.md",
           "note": "#134: the gate reads every shipped cordis.patch.yml, so the tower-ui row in ui-bundle/cordis.patch.yml joins the counted surface. The row was always shipped and unclassified; counting it is not new surface, it is the existing surface becoming visible to the policy."
+        },
+        {
+          "from": 11,
+          "to": 12,
+          "date": "2026-11-10",
+          "adr": "docs/adr/0006-mission-shapes.md",
+          "note": "#148/#149: tower-survey is a visible optional row: off means surveys cannot be planned and no survey agent is dispatched; build missions are unaffected."
         }
       ]
     }

package/survey-sandbox.js

@@ -0,0 +1,48 @@
+// tower-survey-sandbox preset policy (#148 W2): a survey that reads in a
+// disposable detached sandbox may write and run commands *inside that sandbox*,
+// but it still owns no branch, never commits, and may not merge, rebase, review
+// or spawn. The allow-list is the structural guarantee: the denied tools do not
+// exist in the session, so a prompt cannot talk the agent into using them.
+//
+// The shared-checkout survey preset (`dsh-tower/survey`) stays strictly
+// read-only; this module is mounted only for a detached sandbox.
+export const name = 'dsh-tower/survey-sandbox'
+export const inject = ['tools', 'systemPrompt']
+
+const ALLOW = [
+  'read',
+  'write',
+  'edit',
+  'glob',
+  'grep',
+  'pwsh',
+  'tower_mission',
+  'tower_status',
+  'tower_finding',
+  'tower_findings',
+  'tower_inbox',
+  'tower_complete',
+  'skill',
+]
+
+const PROTOCOL = [
+  'You are a Tower survey worker reading one recorded commit in a disposable detached sandbox.',
+  'Work only inside the sandbox path named in your briefing; never modify the main checkout.',
+  'You may write files and run shell commands inside the sandbox, but do not commit: completion requires',
+  'the sandbox HEAD to still be the recorded commit and zero new commits. The sandbox is removed when the mission completes.',
+  'You cannot spawn, merge, rebase, review or diff. Acknowledge inbox mail with tower_inbox; unread messages block completion.',
+  'Finish with tower_complete (report + checks evidence, optionally result:{paths,symbols,plan,notes}); the result is survey evidence only.',
+].join(' ')
+
+export function apply(ctx) {
+  try {
+    ctx.tools.restrict({ allow: ALLOW })
+  } catch {
+    // a composition without the tool registry still gets the protocol text
+  }
+  try {
+    ctx.systemPrompt.section({ name: 'tower:survey-sandbox-protocol', order: 12000, text: PROTOCOL })
+  } catch {
+    // prompt assembly remains valid without the section
+  }
+}

package/survey.js

@@ -0,0 +1,40 @@
+// tower-survey preset policy: a read-only inspection surface. The allow-list is
+// the structural read-only guarantee (#148): a survey cannot write, edit, run a
+// shell, commit, or merge because the tools do not exist in its session.
+export const name = 'dsh-tower/survey'
+export const inject = ['tools', 'systemPrompt']
+
+const ALLOW = [
+  'read',
+  'glob',
+  'grep',
+  'tower_mission',
+  'tower_status',
+  'tower_finding',
+  'tower_findings',
+  'tower_inbox',
+  'tower_complete',
+  'skill',
+]
+
+const PROTOCOL = [
+  'You are a Tower survey worker in a DeepSeek Harness Tower workspace.',
+  'You read one recorded commit in the shared checkout and never modify it: do not write, edit, run a shell,',
+  'commit, rebase, or merge. Your tools are read, glob, grep, skill, and the Tower mission/status/finding/inbox/complete tools.',
+  'Acknowledge inbox mail with tower_inbox (it records Tower state, not a repository write): unread messages block completion.',
+  'Finish with tower_complete (report + checks evidence, optionally result:{paths,symbols,notes}); completion requires',
+  'HEAD to still be the recorded commit, the tracked-file status set to be unchanged, and zero commits.',
+].join(' ')
+
+export function apply(ctx) {
+  try {
+    ctx.tools.restrict({ allow: ALLOW })
+  } catch {
+    // a composition without the tool registry still gets the protocol text
+  }
+  try {
+    ctx.systemPrompt.section({ name: 'tower:survey-protocol', order: 12000, text: PROTOCOL })
+  } catch {
+    // prompt assembly remains valid without the section
+  }
+}

package/tools/complete.js

@@ -13,7 +13,7 @@ export function registerCompleteTool(ctx, deps) {
   define(ctx, {
     name: 'tower_complete',
     description:
-      'Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base, and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. Stores the full report, capped at gates.maxReportBytes (default 32768 UTF-8 bytes); a larger report is rejected with invalid-argument and an actionable nextAction, never truncated. Persists reportBytes on the stored report. completion means ready for preflight and optional review, not merged.',
+      'Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base (zero commits plus HEAD pinned to readCommit for a survey; zero commits in its detached sandbox with HEAD pinned for a sandboxed survey), and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. result is survey-only evidence ({paths?,symbols?,plan?,notes?}); a build completion that carries one is refused. Stores the full report, capped at gates.maxReportBytes (default 32768 UTF-8 bytes); a larger report is rejected with invalid-argument and an actionable nextAction, never truncated. Persists reportBytes on the stored report. completion means ready for preflight and optional review, not merged.',
     parameters: CompleteInput,
     aliases: {"missionId":["id"]},
     requiresMissionId: true,
@@ -38,15 +38,15 @@ export function registerCompleteTool(ctx, deps) {
         if (discovery.configured && discovery.receipt.ok !== true) {
           throw new TowerToolError('tests-failed', `test discovery failed for ${args.missionId}: ${discovery.receipt.error}`)
         }
-        if (discovery.configured && testsConfig.autoChecks !== false && discovery.check) {
-          if (checks.length >= 20) checks[19] = discovery.check
-          else checks.push(discovery.check)
-        }
       }
+      // #149 W4: the receipt already lives in mission.testRuns and is read by
+      // domain/evidence.js. Copying a `tests` projection into the completion
+      // report would be a second evidence shape, so it is not done here.
       return tower.complete({
         missionId: args.missionId,
         agentId: String(exec.agent.id),
         report: args.report,
+        result: args.result,
         checks,
       })
     },

package/tools/diff.js

@@ -18,7 +18,7 @@ import { DiffInput } from '../domain/contracts/tool-inputs/index.js'
 
 /**
  * @param {any} ctx
- * @param {{ define: import('../types/index.js').DefineTool, openTower: any }} deps
+ * @param {{ define: import('../types/index.js').DefineTool, openTower: any, actorFor: any }} deps
  */
 export function registerDiffTool(ctx, deps) {
   // openTower is injected by the composition root (#69).
@@ -31,9 +31,11 @@ export function registerDiffTool(ctx, deps) {
     aliases: {"missionId":["id"]},
     requiresMissionId: true,
     output: output(SCHEMAS.diff),
-    async execute(args) {
+    async execute(args, exec) {
       const tower = await deps.openTower(args.repoRoot)
-      return tower.diff({ missionId: args.missionId, maxBytes: args.maxBytes })
+      // A reviewer's diff is bound to its recorded review commit (#149 W3).
+      const actor = await deps.actorFor(tower, exec)
+      return tower.diff({ missionId: args.missionId, maxBytes: args.maxBytes, actor })
     },
   })
 }

package/tools/plan.js

@@ -25,7 +25,7 @@ export function registerPlanTool(ctx, deps) {
   define(ctx, {
     name: 'tower_plan',
     description:
-      'Plan one or more missions in an initialized repository. Each mission has a printable-Unicode title (NFC-normalized, at most 120 characters), relative scope globs, optional task checklist, optional mission-id dependencies, and kind build|survey. Assigns M1.. ids and auto-adds a dependency when build scopes overlap (serializes merges); rejects dependency cycles.',
+      'Plan one or more missions in an initialized repository. Each mission has a printable-Unicode title (NFC-normalized, at most 120 characters), relative scope globs, optional task checklist, optional mission-id dependencies, and kind build|survey. Assigns M1.. ids and auto-adds a dependency when build scopes overlap (serializes merges); rejects dependency cycles. Returns survey-stale warnings for a build that depends on a survey whose recorded readCommit is not an ancestor of the base; those warnings are advisory and gates.requireFreshSurvey promotes them to merge blockers.',
     parameters: PlanInput,
     board: true,
     output: output(SCHEMAS.plan),

package/tools/preflight.js

@@ -12,7 +12,7 @@ export function registerPreflightTool(ctx, deps) {
   define(ctx, {
     name: 'tower_preflight',
     description:
-      'Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, read-only-survey, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.mode is required; review.mode off and optional skip them. Never changes anything.',
+      'Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards) and warnings (survey-stale). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.mode is required; review.mode off and optional skip them. survey-stale reports a build dependency on a survey whose readCommit is not an ancestor-or-equal of the build base; it is a warning by default and a blocker only when gates.requireFreshSurvey is true. A survey has no merge gate: it is refused with invalid-transition (tower_complete checks HEAD/readCommit and zero commits). Never changes anything.',
     parameters: PreflightInput,
     aliases: {"missionId":["id"]},
     requiresMissionId: true,
@@ -20,10 +20,11 @@ export function registerPreflightTool(ctx, deps) {
     async execute(args) {
       const tower = await deps.openTower(args.repoRoot)
       const { activity, parentStatus } = await observeActivity(ctx, tower)
-      const gate = await tower.evaluateGate({ missionId: args.missionId, activity, parentStatus })
+      const gate = await tower.evaluateGate({ missionId: args.missionId, activity, parentStatus, action: 'preflight' })
       return {
         ok: gate.ok,
         blockers: gate.blockers,
+        warnings: gate.warnings ?? [],
         missionId: args.missionId,
         branchTip: gate.branchTip ?? null,
         baseTip: gate.baseTip ?? null,

package/tools/spawn.js

@@ -2,47 +2,27 @@
 import { SCHEMAS, output } from '../domain/contracts/outputs.js'
 import { TowerToolError, classifyError } from '../domain/errors.js'
 import { SpawnInput } from '../domain/contracts/tool-inputs/index.js'
-import { DEFAULT_ROLE, ROLES as ROLE_ENUM, SPAWN_OUTCOME, isCompletedStopReason, isReviewerRole, isSpawnAdmission, isWorkerRole } from '../domain/vocabulary.js'
+import { defaultPresetFor, shapeFor } from '../domain/shapes/index.js'
+import { DEFAULT_ROLE, ROLES as ROLE_ENUM, SPAWN_OUTCOME, isCompletedStopReason, isSpawnAdmission } from '../domain/vocabulary.js'
+import { resolveRoleSpawn, roleSpawnDiscovery } from '../domain/roles.js'
 import {
   assertSpawnableMission,
   precheckSpawnServices,
   precheckWorkerOwnership,
   resolveRosterName,
 } from '../app/spawn-prechecks.js'
-import { buildAgentOptions, buildSpawnBriefing, waitForSpawnResult } from '../app/spawn-support.js'
-
-/**
- * @param {any} ctx
- * @param {{
- *   define: import('../types/index.js').DefineTool,
- *   openTower: any,
- *   actorFor: any,
- *   requireTowerActor: any,
- *   enqueueSpawn: any,
- *   observeActivity: any,
- *   spawnBackoffState: any,
- *   recordSpawnThrottle: any,
- *   recordSpawnSuccess: any,
- *   runMissionDiscovery: any,
- *   textOf: any, inspectLeases: any,
- *   leaseComponent?: () => { enabled: boolean, reason: string },
- * }} deps
- */
+import { buildAgentOptions, provisionSpawnPlacement, waitForSpawnResult } from '../app/spawn-support.js'
+import { cleanupReviewCheckout } from '../app/reviewCheckout.js'
+/** @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, [key: string]: any }} deps */
 export function registerSpawnTool(ctx, deps) {
-  const {
-    define, actorFor, requireTowerActor, enqueueSpawn, observeActivity,
-    spawnBackoffState, recordSpawnThrottle, recordSpawnSuccess,
-    runMissionDiscovery, textOf,
-  } = deps
+  const { define, actorFor, requireTowerActor, enqueueSpawn, observeActivity, spawnBackoffState, recordSpawnThrottle, recordSpawnSuccess, runMissionDiscovery, textOf } = deps
   define(ctx, {
     name: 'tower_spawn',
     description:
-      'Spawn a worker or reviewer for a mission. Workers use the tower-worker preset; reviewers require a completed mission and use the read-only tower-reviewer preset, and the reviewer role is refused when review.mode is off. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing, and starts a background subagent in that worktree. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns record the branch tip so a reviewer that modifies the branch cannot submit a review. Returns immediately unless wait=true.',
-    parameters: SpawnInput,
+      'Spawn a worker or reviewer for a mission. Workers use the mission shape\'s preset (tower-worker for a build, tower-survey for a read-only shared survey, tower-survey-sandbox for a detached survey with survey.sandbox=detached); reviewers require a completed build mission and use the read-only tower-reviewer preset, and the reviewer role is refused when review.mode is off. A build provisions (or reuses) the mission git worktree and branch; a shared survey runs in the shared checkout because it reads one commit; a detached survey provisions (or reuses) a disposable detached worktree at its readCommit with no branch. Generates a self-contained briefing (including dependency survey result evidence) and starts a background subagent. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns get a disposable detached checkout at the recorded branch tip, and the verdict is stamped with that commit (never a live worktree HEAD). Returns immediately unless wait=true.', parameters: SpawnInput,
     aliases: {"missionId":["id"],"waitMs":["wait_ms"]},
-    requiresMissionId: true,
-    board: true,
-    output: output(SCHEMAS.spawn),
+    requiresMissionId: true, board: true, output: output(SCHEMAS.spawn),
     async execute(args, exec) {
       const tower = await deps.openTower(args.repoRoot)
       const actor = await actorFor(tower, exec)
@@ -51,10 +31,18 @@ export function registerSpawnTool(ctx, deps) {
       if (!ROLE_ENUM.includes(role)) throw new TowerToolError('invalid-argument', `role must be one of ${ROLE_ENUM.join('|')}`)
       // Repository config (if any) already overrides the profile config here.
       const config = tower.config
-      const preset = isReviewerRole(role) ? config.spawn.reviewerPreset : config.spawn.workerPreset
-      const model = isReviewerRole(role) ? config.spawn.reviewerModel : config.spawn.workerModel
       const context = await tower.missionContext(args.missionId)
       assertSpawnableMission({ role, context, config })
+      const shape = shapeFor(context.mission.kind)
+      // #148 W2: the shape resolves its preset from tuning config, so a detached
+      // survey gets the sandbox preset and a shared survey stays read-only.
+      // #149 W4: role resolution (preset row, model route, placement, briefing)
+      // is one contract, orthogonal to the shape that supplies the facts.
+      const shapePreset = defaultPresetFor(context.mission.kind, config, context.mission)
+      const roleSpawn = resolveRoleSpawn(role, { config, shape, shapePreset })
+      if (!roleSpawn) throw new TowerToolError('invalid-argument', `role must be one of ${ROLE_ENUM.join('|')}`)
+      const preset = roleSpawn.preset
+      const model = roleSpawn.model
       const spawned = await enqueueSpawn(tower.root, async () => {
         const observed = await observeActivity(ctx, tower)
         await tower.reconcileObservedInactive(observed.activity)
@@ -65,26 +53,25 @@ export function registerSpawnTool(ctx, deps) {
         }
         const view = await tower.rosterView()
         const name = resolveRosterName({ role, missionId: args.missionId, requested: args.name, roster: view.roster })
-        const takeover = await precheckWorkerOwnership({
-          role, tower, ctx, view, missionId: args.missionId, takeover: args.takeover,
-          maxLiveWorkers: config.spawn.maxLiveWorkers, budget: backoff.budget, observeActivity,
-        })
+        const takeover = await precheckWorkerOwnership({ role, tower, ctx, view, missionId: args.missionId, takeover: args.takeover, maxLiveWorkers: config.spawn.maxLiveWorkers, budget: backoff.budget, observeActivity })
         const { subagents, provider } = await precheckSpawnServices({
           tower, ctx, config, preset, actor, exec, inspectLeases: deps.inspectLeases,
           // #131: the app layer only needs the row fact; the root owns the registry.
           leaseComponent: deps.leaseComponent,
         })
 
-        const provisioned = await tower.provision({
-          missionId: args.missionId,
+        const { mission, worktree, cwd, branch, review, briefing, provisioning, created, sandbox } = await provisionSpawnPlacement(tower, {
+          role,
+          context,
+          missionId: /** @type {string} */ (args.missionId),
+          name,
           worktreeRoot: args.worktreeRoot,
-          includeDirtyBase: args.includeDirtyBase !== false,
+          includeDirtyBase: args.includeDirtyBase,
+          instructions: args.instructions,
         })
-        const { mission, worktree } = provisioned
-        const briefing = buildSpawnBriefing({ role, towerRoot: tower.root, context, worktree, instructions: args.instructions })
         const agentOptions = buildAgentOptions(model)
 
-        if (isWorkerRole(role) && isSpawnAdmission(tower.config.tests?.admission)) {
+        if (roleSpawnDiscovery(role, shape) && isSpawnAdmission(tower.config.tests?.admission)) {
           const discovery = await runMissionDiscovery(tower, mission)
           if (discovery.configured && discovery.receipt.ok !== true) {
             throw new TowerToolError(
@@ -102,15 +89,17 @@ export function registerSpawnTool(ctx, deps) {
           name,
           role,
           parentSessionId: String(exec.agent.id),
-          cwd: worktree.path,
-          branch: worktree.branch,
+          cwd,
+          branch,
+          reviewCommit: review?.commit,
+          reviewCheckout: review?.path,
         })
         try {
           activation = await subagents.startActivation({
             provider,
             label: name,
             request: {
-              cwd: worktree.path,
+              cwd,
               agentPreset: preset,
               prompt: [{ type: 'text', text: briefing }],
               parent: exec.agent,
@@ -127,8 +116,10 @@ export function registerSpawnTool(ctx, deps) {
             role,
             agentId,
             parentSessionId: String(exec.agent.id),
-            cwd: worktree.path,
-            branch: worktree.branch,
+            cwd,
+            branch,
+            reviewCommit: review?.commit,
+            reviewCheckout: review?.path,
             takeover,
           })
           recordSpawnSuccess(tower.root, config.spawn.maxLiveWorkers)
@@ -152,6 +143,10 @@ export function registerSpawnTool(ctx, deps) {
               detail: `spawn failed${agentId ? ` after activation ${agentId}` : ' before activation'}: ${String(error?.message ?? error).slice(0, 300)}`,
             })
             .catch(() => {})
+          // A failed review spawn must not leak its detached evidence checkout.
+          if (review) {
+            await cleanupReviewCheckout(tower, { name, missionId: mission.id }).catch(() => {})
+          }
           throw error
         }
 
@@ -167,8 +162,11 @@ export function registerSpawnTool(ctx, deps) {
           provider,
           maxDepth: config.spawn.maxDepth ?? 1,
           ...(Object.keys(agentOptions).length > 0 ? { agentOptions } : {}),
-          worktree: { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit },
-          created: provisioned.created,
+          worktree: worktree ? { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit } : null,
+          sandbox,
+          review: review ? { commit: review.commit, checkout: review.path } : null,
+          provisioning,
+          created,
           briefingChars: briefing.length,
           takeover,
           rosterEntry: entry,

package/tools/test.js

@@ -46,6 +46,8 @@ export function registerTestTool(ctx, deps) {
         return { ok: false, configured: false, error, tests: [], commands: [] }
       }
       const receipt = discovery.receipt
+      // #149 W4: the receipt is returned as recorded; there is no derived
+      // `checks` copy. Completion/batch read it through domain/evidence.js.
       return {
         ok: receipt.ok === true,
         configured: true,
@@ -54,7 +56,6 @@ export function registerTestTool(ctx, deps) {
         commands: receipt.commands ?? [],
         error: receipt.error ?? undefined,
         receipt,
-        checks: discovery.check ? [discovery.check] : [],
       }
     },
   })

package/types/index.d.ts

@@ -149,11 +149,25 @@ export interface RebaseRecord {
   baseTip?: string
 }
 
-export interface Mission {
+/** Evidence a survey may record when it completes (optional). */
+export interface SurveyResult {
+  paths?: string[]
+  symbols?: string[]
+  /** Ordered plan / next steps the read recommends (bounded array of strings). */
+  plan?: string[]
+  notes?: string
+  [key: string]: unknown
+}
+
+/**
+ * Fields every mission carries regardless of shape. The per-shape arms below
+ * declare which document dimensions a kind owns; the state schema v4 union and
+ * `domain/state/semantics.js` enforce the same split at runtime.
+ */
+export interface MissionBase {
   id: string
   title: string
   status: MissionStatus
-  kind: MissionKind
   scope: string[]
   deps: string[]
   /**
@@ -165,22 +179,59 @@ export interface Mission {
   blockers?: string[]
   reviewPolicy?: ReviewPolicy
   reviewExemptionReason?: string | null
-  worktree?: MissionWorktree | null
   owner?: string | null
   notes?: string[]
   completionReport?: CompletionReport | null
   testRuns?: TestRun[]
   rebase?: RebaseRecord | null
-  mergedCommit?: string | null
-  mergedAt?: number | null
   scopeGeneration?: number
   ownerGeneration?: number
   pauseCause?: string | null
   updatedAt?: number
   references?: string[]
   authorizationRef?: string | null
+  /**
+   * Survey evidence; the completion transition refuses a result on a shape that
+   * does not accept one, so the type stays permissive for the shared draft.
+   */
+  result?: SurveyResult | null
 }
 
+/** A build mission owns a private branch/worktree and lands by merging. */
+export interface BuildMission extends MissionBase {
+  kind: 'build'
+  worktree?: MissionWorktree | null
+  mergedCommit?: string | null
+  mergedAt?: number | null
+  readCommit?: never
+  readDirty?: never
+  sandbox?: never
+}
+
+/** A survey reads one commit in the shared checkout; it never merges. */
+export interface SurveyMission extends MissionBase {
+  kind: 'survey'
+  readCommit: string
+  readDirty?: string[]
+  result?: SurveyResult | null
+  /**
+   * #148 W2: the disposable detached sandbox path when `survey.sandbox` is
+   * `detached`. It has no branch and is removed on completion/abandon; a
+   * cleanup failure keeps the path plus `sandboxCleanupError` so the record and
+   * the filesystem do not silently disagree.
+   */
+  sandbox?: string
+  sandboxCleanupError?: string
+  sandboxRemovedAt?: number
+  worktree?: never
+  branch?: never
+  baseCommit?: never
+  mergedCommit?: never
+  mergedAt?: never
+}
+
+export type Mission = BuildMission | SurveyMission
+
 /**
  * Compact archived-mission entry (`archive/index.json`). It keeps enough of the
  * mission for ordering, dependency lookups and id allocation without loading the
@@ -255,6 +306,10 @@ export interface RosterEntry {
   missionId?: string | null
   parentSessionId?: string | null
   spawnTip?: string | null
+  /** The commit a reviewer's verdict is stamped with (#149 W3). */
+  reviewCommit?: string | null
+  /** The disposable detached checkout the reviewer reads, when recorded. */
+  reviewCheckout?: string | null
   stale?: boolean
   [key: string]: unknown
 }
@@ -326,6 +381,12 @@ export interface MissionSummary {
   reviewPolicy: ReviewPolicy
   mergedCommit: string | null
   mergedAt: number | null
+  /** Survey projection: the commit the survey read (null for a build). */
+  readCommit?: string | null
+  /** Survey projection: the tracked-status fingerprint captured at plan time. */
+  readDirty?: string[]
+  /** Survey projection: the disposable detached sandbox path (null otherwise). */
+  sandbox?: string | null
   /** Size of the completion report without loading its body; null when absent. */
   reportBytes: number | null
   updatedAt?: number