dsh-tower 2.6.0 → 2.7.0

package/app/briefing.js

@@ -1,10 +1,34 @@
 // Mission briefings: pure text builders for worker/reviewer prompts.
+import { shapeFor } from '../domain/shapes/index.js'
 
 function clip(text, max = 2000) {
   const value = String(text ?? '')
   return value.length > max ? `${value.slice(0, max)}\n… truncated` : value
 }
 
+/**
+ * Dependency lines shared by the worker and reviewer briefings. A survey
+ * dependency carries its recorded result (#148 D6) alongside its status, with
+ * bounded formatting so a large evidence set cannot crowd out the mission.
+ * @param {any[]} deps
+ * @returns {string[]}
+ */
+function dependencyLines(deps) {
+  const lines = []
+  for (const dep of deps) {
+    lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status}${dep.kind ? `, ${dep.kind}` : ''})`)
+    const result = dep.result
+    if (!result || typeof result !== 'object') continue
+    const evidence = []
+    if (Array.isArray(result.paths) && result.paths.length > 0) evidence.push(`paths: ${result.paths.slice(0, 20).join(', ')}`)
+    if (Array.isArray(result.symbols) && result.symbols.length > 0) evidence.push(`symbols: ${result.symbols.slice(0, 20).join(', ')}`)
+    if (Array.isArray(result.plan) && result.plan.length > 0) evidence.push(`plan: ${clip(result.plan.slice(0, 20).join('; '), 1200)}`)
+    if (typeof result.notes === 'string' && result.notes.trim()) evidence.push(`notes: ${clip(result.notes.trim(), 1200)}`)
+    if (evidence.length > 0) lines.push(`  evidence: ${evidence.join(' | ')}`)
+  }
+  return lines
+}
+
 export function workerBriefing({
   repoRoot,
   base,
@@ -17,25 +41,44 @@ export function workerBriefing({
   completionReport = null,
 }) {
   const completion = /** @type {import('../types/index.js').CompletionReport | null} */ (completionReport)
+  const shape = shapeFor(mission.kind)
+  // The checkout the worker actually runs in: a recorded detached sandbox wins
+  // over the (absent) worktree, then a build worktree, then the shared main
+  // checkout. The spawn cwd uses the same precedence, so the prompt matches the
+  // process the agent is started in.
+  const cwd = mission.sandbox ?? worktree?.path ?? repoRoot
   const lines = []
   lines.push(`# Tower mission ${mission.id} — ${mission.title}`)
   lines.push('')
   lines.push(`You are the tower worker for mission ${mission.id} in repository ${repoRoot}.`)
   lines.push('')
-  lines.push(`Work ONLY in this git worktree: ${worktree.path}`)
-  lines.push(`Branch: ${worktree.branch} (based on ${base} @ ${String(worktree.baseCommit).slice(0, 12)})`)
-  lines.push('')
-  lines.push(`Kind: ${mission.kind}`)
   lines.push(
-    `Scope (only files you may touch): ${mission.scope.length > 0 ? mission.scope.join(', ') : '(none — survey is read-only)'}`,
+    ...shape.briefing(mission, {
+      repoRoot,
+      base,
+      worktree,
+      readCommit: /** @type {string | undefined} */ (mission.readCommit),
+      readDirty: mission.readDirty,
+    }),
   )
+  lines.push('')
+  lines.push(`Kind: ${mission.kind}`)
+  // The empty scope means different things by shape: a build still owns its
+  // worktree, a detached survey owns a disposable writable sandbox, and only a
+  // shared survey is strictly read-only.
+  const emptyScope = shape.fields.worktree
+    ? '(none declared — stay inside your worktree)'
+    : shape.fields.sandbox && mission.sandbox
+      ? '(none declared — the detached survey sandbox is disposable: write and run commands inside it, but never commit or leave it)'
+      : '(none — survey is read-only)'
+  lines.push(`Scope (only files you may touch): ${mission.scope.length > 0 ? mission.scope.join(', ') : emptyScope}`)
   if (mission.tasks.length > 0) {
     lines.push('Tasks:')
     for (const task of mission.tasks) lines.push(`- [${task.status}] ${task.text}`)
   }
   if (deps.length > 0) {
     lines.push('Dependencies:')
-    for (const dep of deps) lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status})`)
+    lines.push(...dependencyLines(deps))
   }
   if (mission.context) {
     lines.push('Context (verbatim from the user):')
@@ -57,6 +100,11 @@ export function workerBriefing({
       for (const check of completion.checks ?? []) lines.push(`- ${check.name}${check.exitCode !== undefined ? ` (exit ${check.exitCode})` : ''}`)
     }
   }
+  if (mission.result) {
+    lines.push('')
+    lines.push('Recorded evidence (from a previous completion):')
+    lines.push(`- ${JSON.stringify(mission.result)}`)
+  }
   if (reviews.length > 0) {
     lines.push('')
     lines.push('Previous review rounds for this branch (newest first) — address every finding:')
@@ -73,16 +121,34 @@ export function workerBriefing({
   }
   lines.push('')
   lines.push('Rules:')
-  lines.push(`- Pass workdir="${worktree.path}" on every shell command; never edit the main checkout.`)
-  lines.push('- Stay inside the declared scope; out-of-scope changes are rejected later.')
-  lines.push('- Commit your work on the mission branch. Do not merge, push, or spawn other agents.')
+  if (shape.fields.worktree) {
+    lines.push(`- Pass workdir="${cwd}" on every shell command; never edit the main checkout.`)
+    lines.push('- Stay inside the declared scope; out-of-scope changes are rejected later.')
+    lines.push('- Commit your work on the mission branch. Do not merge, push, or spawn other agents.')
+  } else if (shape.fields.sandbox && mission.sandbox) {
+    lines.push(`- Pass workdir="${mission.sandbox}" on every shell command; that checkout is a disposable detached sandbox, not the main checkout.`)
+    lines.push('- You may write files and run commands inside the sandbox, but never commit: completion requires the sandbox HEAD to still equal the recorded commit and zero new commits.')
+    lines.push(`- Stay inside the sandbox; never edit the main checkout ${repoRoot}. Do not merge, push, or spawn other agents.`)
+  } else {
+    lines.push(`- Read the shared checkout at ${cwd}; it is the main checkout, not your own worktree.`)
+    lines.push(
+      '- Make no commits: this mission reads one fixed commit. Do not write, edit, merge, push, rebase, or spawn other agents.',
+    )
+  }
   lines.push(
     `- Update progress: tower_mission({repoRoot:"${repoRoot}",id:"${mission.id}",task_done:"..."}) or blocker:"...".`,
   )
+  const resultHint = shape.acceptsResult
+    ? ' Optionally record evidence as result:{paths?:string[],symbols?:string[],plan?:string[],notes?:string}.'
+    : ''
+  lines.push(
+    `- When the work is finished and every task is closed, call tower_complete({repoRoot:"${repoRoot}",missionId:"${mission.id}",report:"<full handoff>",checks:[{name,command,exitCode,evidence}]}).${resultHint} Unread inbox messages block completion, so read them with tower_inbox first.`,
+  )
   lines.push(
-    `- When the work is finished and every task is closed, call tower_complete({repoRoot:"${repoRoot}",missionId:"${mission.id}",report:"<full handoff>",checks:[{name,command,exitCode,evidence}]}). Unread inbox messages block completion, so read them with tower_inbox first.`,
+    shape.fields.worktree
+      ? '- Your final message is the full handoff: files changed, how you verified, what remains.'
+      : '- Your final message is the full handoff: what you inspected, how you verified it, what remains.',
   )
-  lines.push('- Your final message is the full handoff: files changed, how you verified, what remains.')
   if (instructions) {
     lines.push('')
     lines.push('Extra tower instructions:')
@@ -91,12 +157,19 @@ export function workerBriefing({
   return lines.join('\n')
 }
 
+/**
+ * @param {{ repoRoot: string, base: string, mission: any, deps: any[],
+ *   worktree: any, review?: { commit: string, path: string } | null,
+ *   instructions?: string, reviews?: any[], findings?: any[],
+ *   completionReport?: any }} input
+ */
 export function reviewerBriefing({
   repoRoot,
   base,
   mission,
   deps,
   worktree,
+  review = null,
   instructions,
   reviews = [],
   findings = [],
@@ -111,6 +184,12 @@ export function reviewerBriefing({
   lines.push(`Review branch: ${worktree.branch}`)
   lines.push(`Worktree: ${worktree.path}`)
   lines.push(`Reviewed base: ${base} @ ${String(worktree.baseCommit).slice(0, 12)}`)
+  if (review) {
+    lines.push(`Review commit: ${String(review.commit).slice(0, 12)} (the evidence your verdict is stamped with)`)
+    lines.push(`Checkout: ${review.path}`)
+    lines.push('')
+    lines.push(`Read and inspect the review commit in ${review.path}; that checkout is removed after your verdict.`)
+  }
   lines.push('')
   lines.push(`Kind: ${mission.kind}`)
   if (mission.tasks.length > 0) {
@@ -119,7 +198,7 @@ export function reviewerBriefing({
   }
   if (deps.length > 0) {
     lines.push('Dependencies:')
-    for (const dep of deps) lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status})`)
+    lines.push(...dependencyLines(deps))
   }
   if (mission.context) {
     lines.push('Context (verbatim from the user):')
@@ -158,6 +237,10 @@ export function reviewerBriefing({
   lines.push('')
   lines.push('Rules:')
   lines.push('- Read-only: do not modify files, commit, or merge.')
+  if (review) {
+    lines.push(`- Pass workdir="${review.path}" on every command: the checkout is a detached read of commit ${String(review.commit).slice(0, 12)}, not the mutable mission worktree.`)
+    lines.push('- tower_diff shows the recorded commit your verdict will stamp; do not review anything newer.')
+  }
   lines.push('- Inspect the diff from the reviewed base to the branch tip and map every task to the diff.')
   lines.push('- Check scope, correctness, tests, and security. Report severity and concrete evidence.')
   lines.push(

package/app/checkCompletion.js

@@ -1,4 +1,5 @@
 // Worker completion preparation and commit use cases.
+import path from 'node:path'
 import { TowerToolError } from '../domain/errors.js'
 import {
   normalizeChecks,
@@ -7,12 +8,79 @@ import {
   completionReport,
   applyCompletion,
 } from '../domain/missions/completion.js'
+import { shapeFor } from '../domain/shapes/index.js'
 import { fullMission } from '../domain/summary.js'
 import { validateState } from '../domain/state.js'
 import { sweepArchive } from './archive.js'
+import { cleanupSandbox } from './sandbox.js'
+import { trackedFingerprint } from './sharedCheckout.js'
 
 export { normalizeChecks }
 
+/**
+ * Read the primitives the shape's completion invariants need. Which reads happen
+ * is declared by the shape, so this layer never asks "is this a survey?"; a
+ * detached sandbox declares `requiresSandbox` and its HEAD/commit count is read
+ * from the recorded sandbox path instead of the shared checkout (#148 W2).
+ * @param {any} tower
+ * @param {import('../types/index.js').Mission} mission
+ * @param {any} invariants
+ * @returns {Promise<{ commits: number, clean: boolean, dirtyPaths: string[], head: string, trackedChanged: string[], readCommit?: string, sandbox?: string | null }>}
+ */
+async function completionFacts(tower, mission, invariants) {
+  const worktree = /** @type {any} */ (mission.worktree)
+  const sandbox = invariants.requiresSandbox ? String(/** @type {any} */ (mission).sandbox ?? '') : ''
+  /** @type {{ commits: number, clean: boolean, dirtyPaths: string[], head: string, trackedChanged: string[], readCommit?: string, sandbox?: string | null }} */
+  const facts = { commits: 0, clean: true, dirtyPaths: [], head: '', trackedChanged: [], sandbox: sandbox || null }
+  if (invariants.requiresSandbox) {
+    if (!sandbox) {
+      throw new TowerToolError('invalid-argument', `mission ${mission.id} has no detached sandbox recorded; re-provision it or abandon the survey`)
+    }
+    const entries = await tower.deps.vcs.listWorktrees(tower.root)
+    if (!entries.some((entry) => entry.path && path.resolve(entry.path) === path.resolve(sandbox))) {
+      throw new TowerToolError(
+        'invalid-argument',
+        `mission ${mission.id} detached sandbox ${sandbox} is not registered with git; the disposable checkout was removed — re-provision the survey`,
+      )
+    }
+  }
+  if (invariants.requiresWorktree) await tower.assertWorktree(worktree)
+  const cwd = sandbox || worktree?.path
+  if (invariants.requiresCommits) {
+    const base = invariants.requiresSandbox ? /** @type {string} */ (mission.readCommit) : worktree.baseCommit
+    facts.commits = await tower.deps.vcs.countCommits(cwd, base)
+  }
+  if (invariants.requiresClean) {
+    facts.clean = await tower.deps.vcs.isClean(cwd)
+    if (!facts.clean) {
+      facts.dirtyPaths = (await tower.git(cwd, ['status', '--porcelain']))
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => line.slice(3).trim())
+    }
+  }
+  facts.readCommit = /** @type {string | undefined} */ (mission.readCommit)
+  if (invariants.requiresHeadMatch || invariants.requiresTrackedStatus) {
+    // A shared survey reads the shared checkout: HEAD and the tracked fingerprint
+    // must match the plan-time record exactly (a path that changed either way
+    // counts). A detached sandbox reads its own disposable checkout: only HEAD
+    // must still equal the recorded commit; writes there are expected.
+    facts.head = await tower.revParse(invariants.requiresSandbox ? sandbox : tower.root, 'HEAD')
+    if (invariants.requiresTrackedStatus) {
+      const current = trackedFingerprint(await tower.git(tower.root, ['status', '--porcelain']))
+      const planned = new Set(mission.readDirty ?? [])
+      const currentSet = new Set(current)
+      facts.trackedChanged = [
+        ...new Set([
+          ...current.filter((path) => !planned.has(path)),
+          ...(mission.readDirty ?? []).filter((path) => !currentSet.has(path)),
+        ]),
+      ].sort()
+    }
+  }
+  return facts
+}
+
 export async function checkCompletion(tower, input) {
   const state = await tower.load()
   const mission = state.missions.find((entry) => entry.id === input.missionId)
@@ -25,24 +93,22 @@ export async function checkCompletion(tower, input) {
     input,
     maxReportBytes: tower.config.gates?.maxReportBytes,
   })
-  await tower.assertWorktree(mission.worktree)
-  const commits = await tower.deps.vcs.countCommits(mission.worktree.path, mission.worktree.baseCommit)
-  if (commits < 1) {
-    throw new TowerToolError(
-      'invalid-argument',
-      `mission branch has no commits since ${String(mission.worktree.baseCommit).slice(0, 12)}`,
-    )
+  const shape = shapeFor(mission.kind)
+  const invariants = /** @type {{
+   *   requiresWorktree: boolean, requiresSandbox: boolean, requiresCommits: boolean,
+   *   requiresClean: boolean, requiresHeadMatch: boolean, requiresTrackedStatus: boolean,
+   *   check: (ctx: any) => { commits: number },
+   * }} */ ('resolveCompletion' in shape && typeof shape.resolveCompletion === 'function'
+    ? shape.resolveCompletion(mission, tower.config)
+    : shape.completion)
+  if (invariants.requiresWorktree && !mission.worktree) {
+    throw new TowerToolError('invalid-argument', `mission ${mission.id} has no worktree`)
   }
-  if (!(await tower.deps.vcs.isClean(mission.worktree.path))) {
-    const dirty = (await tower.git(mission.worktree.path, ['status', '--porcelain']))
-      .split('\n')
-      .filter(Boolean)
-      .map((line) => line.slice(3).trim())
-    throw new TowerToolError(
-      'worktree-dirty',
-      `mission ${mission.id} worktree has uncommitted changes (${dirty.slice(0, 8).join(', ')}${dirty.length > 8 ? ', …' : ''}); commit, remove, or record them before tower_complete`,
-    )
+  if (invariants.requiresSandbox && !/** @type {any} */ (mission).sandbox) {
+    throw new TowerToolError('invalid-argument', `mission ${mission.id} has no detached sandbox; re-provision it or abandon the survey`)
   }
+  const facts = await completionFacts(tower, mission, invariants)
+  const { commits } = invariants.check({ mission, ...facts })
   const unread = tower.unreadFor(state, worker.name)
   assertCompletionInbox({ mission, worker, unread })
   return { state, mission, worker, commits }
@@ -52,7 +118,7 @@ export async function complete(tower, input) {
   // Two-phase pilot (#51): expensive git/state checks run before the lock;
   // the lock only revalidates the state revision and commits the transition.
   const prepared = await tower.checkCompletion(input)
-  return tower.deps.store.withLock(tower.paths, async () => {
+  const result = await tower.deps.store.withLock(tower.paths, async () => {
     const state = await tower.load()
     if (state.revision !== prepared.state.revision) {
       throw new TowerToolError('stale-base', 'tower state changed while completion was being prepared; retry')
@@ -69,7 +135,7 @@ export async function complete(tower, input) {
       now,
       maxReportBytes: tower.config.gates?.maxReportBytes,
     })
-    const applied = applyCompletion({ mission, report: storedReport, now })
+    const applied = applyCompletion({ mission, report: storedReport, now, result: input.result })
     await sweepArchive(tower, state, { now })
     state.revision += 1
     state.updatedAt = now
@@ -85,4 +151,27 @@ export async function complete(tower, input) {
     tower.emitEvents(applied.events, { revision: state.revision, at: now })
     return { mission: fullMission(mission), commits, unread: 0 }
   })
+  // The completion transition is durable at this point. Removing the disposable
+  // sandbox is advisory: a failed cleanup is reported, never rolled back into
+  // the mission state or allowed to fail the completion.
+  let sandboxCleanup = null
+  if (result.mission.sandbox) {
+    const sandbox = result.mission.sandbox
+    try {
+      sandboxCleanup = await cleanupSandbox(tower, input.missionId)
+    } catch (error) {
+      sandboxCleanup = {
+        ok: false,
+        removed: false,
+        attempts: 0,
+        path: sandbox,
+        error: String(error?.message ?? error).slice(0, 400),
+      }
+    }
+    if (sandboxCleanup?.ok) {
+      delete result.mission.sandbox
+      delete result.mission.sandboxCleanupError
+    }
+  }
+  return { ...result, ...(sandboxCleanup ? { sandboxCleanup } : {}) }
 }

package/app/enrichedMissions.js

@@ -12,7 +12,7 @@ export async function enrichedMissions(tower, state, onlyIds) {
     let tipMoved = false
     if (latest && mission.worktree && (await tower.deps.store.exists(mission.worktree.path))) {
       try {
-        const tip = await tower.deps.vcs.revParse(mission.worktree.path, 'HEAD')
+        const tip = await tower.branchTip(mission)
         tipMoved = tip !== latest.reviewedCommit
       } catch {
         tipMoved = false

package/app/freshness.js

@@ -0,0 +1,77 @@
+// Dependency freshness (#148 W2 / D5): a build that depends on a survey wants
+// the survey's evidence to describe the code it starts from. A survey records
+// the exact commit it read; when that commit is not an ancestor-or-equal of the
+// build's base, the evidence may be stale. This is advisory by default and a
+// blocker only when `gates.requireFreshSurvey` is true.
+// @ts-check
+import { shapeFor } from '../domain/shapes/index.js'
+
+/**
+ * @typedef {import('../types/index.js').Mission} Mission
+ * @typedef {import('../types/index.js').TowerState} TowerState
+ */
+
+/**
+ * One stable, self-describing freshness warning. The same shape is promoted to a
+ * blocker (with `detail` carrying the message) when the gate asks for it.
+ * @param {{ missionId: string, dep: { id: string }, readCommit: string, baseCommit: string }} input
+ * @returns {{ code: 'survey-stale', missionId: string, depId: string, readCommit: string, baseCommit: string, message: string }}
+ */
+export function surveyStaleWarning({ missionId, dep, readCommit, baseCommit }) {
+  const read = String(readCommit).slice(0, 12)
+  const base = String(baseCommit).slice(0, 12)
+  return {
+    code: 'survey-stale',
+    missionId,
+    depId: dep.id,
+    readCommit,
+    baseCommit,
+    message: `survey ${dep.id} read ${read}, which is not an ancestor of ${missionId}'s base ${base}; the survey evidence may not describe the code this mission starts from — re-plan the survey against the current base, or record why the read is still valid`,
+  }
+}
+
+/**
+ * Compute `survey-stale` warnings for one build mission's survey dependencies.
+ * A survey dependency is recognised through the shape contract (`fields.readCommit`),
+ * not a kind literal. The base is `mission.baseCommit` for a provisioned build,
+ * otherwise the current state base (resolved once by the caller or here).
+ * @param {any} tower
+ * @param {object} input
+ * @param {Mission} input.mission
+ * @param {TowerState} input.state
+ * @param {Mission[]} [input.missions]
+ * @param {Map<string, { id?: string, status: string, kind?: string, readCommit?: string }>} [input.archived]
+ * @param {string | null} [input.baseCommit] already-resolved build base
+ * @returns {Promise<Array<ReturnType<typeof surveyStaleWarning>>>}
+ */
+export async function surveyStaleWarnings(tower, { mission, state, missions, archived = new Map(), baseCommit = null }) {
+  if (!shapeFor(mission.kind).fields.worktree) return []
+  const deps = mission.deps ?? []
+  if (deps.length === 0) return []
+  let base = baseCommit ?? /** @type {any} */ (mission).baseCommit ?? null
+  if (typeof base !== 'string' || base.length === 0) {
+    try {
+      base = await tower.revParse(tower.root, state.base)
+    } catch {
+      return []
+    }
+  }
+  const byId = new Map((missions ?? state.missions).map((entry) => [entry.id, entry]))
+  /** @type {Array<ReturnType<typeof surveyStaleWarning>>} */
+  const warnings = []
+  for (const depId of deps) {
+    const dep = byId.get(depId) ?? archived.get(depId)
+    if (!dep || !shapeFor(dep.kind).fields.readCommit) continue
+    const readCommit = typeof /** @type {any} */ (dep).readCommit === 'string' ? /** @type {any} */ (dep).readCommit : null
+    if (!readCommit) continue
+    let fresh = false
+    try {
+      fresh = await tower.isAncestor(tower.root, readCommit, base)
+    } catch {
+      fresh = false
+    }
+    if (fresh) continue
+    warnings.push(surveyStaleWarning({ missionId: mission.id, dep: /** @type {{ id: string }} */ (dep), readCommit, baseCommit: base }))
+  }
+  return warnings
+}

package/app/gate.js

@@ -3,6 +3,7 @@ import { ROSTER_INACTIVE_STATES } from '../domain/roster.js'
 import { completionBlockers, mergeGateBlockers } from '../domain/gate.js'
 import { fullMission } from '../domain/summary.js'
 import { latestReview, reviewsForBranch } from '../domain/integration/review.js'
+import { assertActionSupported } from '../domain/shapes/index.js'
 import {
   baseDirtyBlocker,
   baseWrongBranchBlocker,
@@ -14,8 +15,8 @@ import {
   outOfScopeBlocker,
   overwrittenPaths,
   staleBaseBlocker,
-  surveyChangedFilesBlocker,
 } from '../domain/integration/gate.js'
+import { surveyStaleWarnings } from './freshness.js'
 
 export async function evaluateGate(tower, input) {
     const state = await tower.load()
@@ -31,6 +32,9 @@ export async function evaluateGate(tower, input) {
       }
     }
     if (!mission) return missingMissionGateResult(input.missionId)
+    // A shape without a branch has no merge gate at all; refuse before doing
+    // any git work so the caller gets one actionable code (#148 D4).
+    assertActionSupported(mission, input.action === 'merge' ? 'merge' : 'preflight')
     const archiveIndex = await tower.archiveIndex()
     const archivedMissions = new Map(
       (archiveIndex.ok ? archiveIndex.missions : []).map((entry) => [entry.id, entry]),
@@ -56,7 +60,7 @@ export async function evaluateGate(tower, input) {
     } else {
       try {
         await tower.assertWorktree(worktree)
-        branchTip = await tower.revParse(worktree.path, 'HEAD')
+        branchTip = await tower.branchTip(mission)
         baseTip = await tower.revParse(tower.root, state.base)
         const mergeBase = (await tower.git(worktree.path, ['merge-base', baseTip, branchTip])).trim()
         changedFiles = (await tower.git(worktree.path, ['diff', '--name-only', `${mergeBase}..${branchTip}`]))
@@ -66,20 +70,14 @@ export async function evaluateGate(tower, input) {
           const blocker = staleBaseBlocker({ branch: worktree.branch, base: state.base, baseTip })
           push(blocker.code, blocker.detail)
         }
-        if (mission.kind === 'survey') {
-          const blocker = surveyChangedFilesBlocker({ missionId: mission.id, changedFiles })
-          if (blocker) push(blocker.code, blocker.detail)
-        }
-        if (mission.kind !== 'survey') {
-          const blocker = outOfScopeBlocker({ mission, changedFiles, caseInsensitive: state.caseInsensitive === true })
-          if (blocker) push(blocker.code, blocker.detail)
-        }
+        const scopeBlocker = outOfScopeBlocker({ mission, changedFiles, caseInsensitive: state.caseInsensitive === true })
+        if (scopeBlocker) push(scopeBlocker.code, scopeBlocker.detail)
         const dirty = (await tower.git(tower.root, ['status', '--porcelain']))
           .split('\n')
           .filter(Boolean)
           .map((line) => line.slice(3).trim())
-        const blocker = baseDirtyBlocker(overwrittenPaths(changedFiles, dirty))
-        if (blocker) push(blocker.code, blocker.detail)
+        const dirtyBlocker = baseDirtyBlocker(overwrittenPaths(changedFiles, dirty))
+        if (dirtyBlocker) push(dirtyBlocker.code, dirtyBlocker.detail)
       } catch (error) {
         push('branch-missing', String(error?.message ?? error))
       }
@@ -89,6 +87,21 @@ export async function evaluateGate(tower, input) {
       push(blocker.code, blocker.detail)
     }
 
+    // #148 W2: survey evidence freshness is advisory by default. The stable
+    // warning shape is what plan/preflight report; `gates.requireFreshSurvey`
+    // promotes the same code to a blocker for repositories that need the read
+    // to describe the exact base they start from.
+    const sandboxWarnings = await surveyStaleWarnings(tower, {
+      mission,
+      state,
+      missions: state.missions,
+      archived: archivedMissions,
+      baseCommit: mission.baseCommit ?? null,
+    })
+    if (tower.config.gates?.requireFreshSurvey === true) {
+      for (const warning of sandboxWarnings) blockers.push({ ...warning, detail: warning.message })
+    }
+
     const branch = worktree ? worktree.branch : null
     const latest = latestReview(reviewsForBranch(reviews, branch))
     // #140: `mergeGateBlockers` is pure and may not read the component registry, so
@@ -132,6 +145,7 @@ export async function evaluateGate(tower, input) {
         review: latest,
         blockers,
       }),
+      warnings: sandboxWarnings,
       ...(archivedEntry ? { archived: true } : {}),
     }
   }

package/app/merge.js

@@ -18,6 +18,8 @@
 // prepare stale, so the whole prepare is retried, never partially applied.
 import path from 'node:path'
 import { validateState } from '../domain/state.js'
+import { assertActionSupported } from '../domain/shapes/index.js'
+import { markBlocked } from '../domain/missions/lifecycle.js'
 import {
   alreadyMergedResult,
   applyLandedMerge,
@@ -134,7 +136,7 @@ async function observeLandedMerge(tower, state, mission) {
   let branchTip
   try {
     baseTip = await tower.revParse(tower.root, state.base)
-    branchTip = await tower.revParse(mission.worktree.path, 'HEAD')
+    branchTip = await tower.branchTip(mission)
   } catch {
     return null
   }
@@ -238,6 +240,8 @@ async function prepareFromState(tower, input, deps) {
     if (archived.ok && archived.entry) mission = archived.entry.mission
   }
   if (!mission) return { result: missionMissingResult(input.missionId) }
+  // A branchless shape has no merge to prepare; refuse before any git work.
+  assertActionSupported(mission, 'merge')
 
   // Reconcile a stale merge intent: Git runs here, outside every state lock.
   if (state.mergeIntent && state.mergeIntent.missionId === mission.id) {
@@ -272,7 +276,7 @@ async function prepareFromState(tower, input, deps) {
   // Capture the exact commits this merge is allowed to integrate. The merge
   // command below uses the captured branch SHA, never the mutable branch name.
   const baseTip = await tower.revParse(tower.root, 'HEAD')
-  const branchTip = await tower.revParse(worktree.path, 'HEAD')
+  const branchTip = await tower.branchTip(mission)
   const drift = gateTipDrift({
     missionId: mission.id,
     gateBaseTip: gate.baseTip,
@@ -522,8 +526,7 @@ async function commitMerge(tower, plan, recorded, outcome) {
     const now = Date.now()
     if (intentActive) delete state.mergeIntent
     if (conflict) {
-      mission.status = 'blocked'
-      mission.blockers.push(mergeConflictNote(outcome.detail))
+      markBlocked(mission, mergeConflictNote(outcome.detail), now)
     } else {
       mission.notes.push(mergeHookFailureNote(outcome.detail, mission.status))
     }

package/app/mission.js

@@ -4,6 +4,7 @@ import { applyMissionUpdate } from '../domain/missions/lifecycle.js'
 import { validateState } from '../domain/state.js'
 import { fullMission } from '../domain/summary.js'
 import { sweepArchive } from './archive.js'
+import { cleanupSandbox } from './sandbox.js'
 
 function fail(message, code = 'invalid-argument') {
   throw new TowerToolError(code, message)
@@ -12,7 +13,7 @@ function fail(message, code = 'invalid-argument') {
 export async function updateMission(tower, input = {}) {
   const missionId = typeof input.id === 'string' ? input.id.trim() : input.id
   if (typeof missionId !== 'string' || missionId.length === 0) fail('tower_mission requires id')
-  return tower.deps.store.withLock(tower.paths, async () => {
+  const result = await tower.deps.store.withLock(tower.paths, async () => {
     const state = await tower.load()
     const mission = state.missions.find((entry) => entry.id === missionId)
     if (!mission) fail(`unknown mission "${missionId}"`, 'mission-not-found')
@@ -34,4 +35,26 @@ export async function updateMission(tower, input = {}) {
     tower.emitEvents(events, { revision: state.revision, at: now })
     return { revision: state.revision, mission: fullMission(mission) }
   })
+  // Abandoning a detached survey disposes its sandbox. The state transition is
+  // already durable; cleanup is advisory and reports rather than throws.
+  let sandboxCleanup = null
+  if (result.mission.status === 'abandoned' && result.mission.sandbox) {
+    const sandbox = result.mission.sandbox
+    try {
+      sandboxCleanup = await cleanupSandbox(tower, missionId)
+    } catch (error) {
+      sandboxCleanup = {
+        ok: false,
+        removed: false,
+        attempts: 0,
+        path: sandbox,
+        error: String(error?.message ?? error).slice(0, 400),
+      }
+    }
+    if (sandboxCleanup?.ok) {
+      delete result.mission.sandbox
+      delete result.mission.sandboxCleanupError
+    }
+  }
+  return { ...result, ...(sandboxCleanup ? { sandboxCleanup } : {}) }
 }

package/app/missionContext.js

@@ -10,5 +10,6 @@ export async function missionContext(tower, missionId) {
   const state = await tower.load()
   const mission = state.missions.find((entry) => entry.id === missionId)
   if (!mission) fail(`unknown mission "${missionId}"`, 'mission-not-found')
-  return missionContextView({ state, mission })
+  const archived = await tower.archiveIndex()
+  return missionContextView({ state, mission, archived: archived.ok ? archived.missions : [] })
 }