dsh-tower 2.5.0 → 2.7.0

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 : [] })
 }

package/app/plan.js

@@ -1,4 +1,5 @@
 // Mission planning use case.
+import { TowerToolError } from '../domain/errors.js'
 import { nextMissionNumber, addAutoDeps, assertAcyclic } from '../domain/planning.js'
 import {
   normalizePlanMissions,
@@ -7,15 +8,58 @@ import {
   newMission,
   applyPlan,
 } from '../domain/missions/plan.js'
+import { shapeFor } from '../domain/shapes/index.js'
 import { validateState } from '../domain/state.js'
 import { fullMission } from '../domain/summary.js'
 import { sweepArchive } from './archive.js'
+import { surveyStaleWarnings } from './freshness.js'
+import { readFacts } from './sharedCheckout.js'
+
+/**
+ * Planning a shape whose optional component is off must fail with an actionable
+ * message, not silently plan work nothing can execute. Preset rows are only
+ * visible through the async probe: the synchronous `enabled` switch cannot see
+ * a declarative agent-preset registration.
+ * @param {any} tower
+ * @param {any} input
+ * @returns {Promise<void>}
+ */
+async function assertShapeComponents(tower, input) {
+  const components = tower.deps?.components
+  if (!components) return
+  for (const mission of input?.missions ?? []) {
+    const required = shapeFor(mission?.kind).requiredComponent
+    if (!required) continue
+    if (typeof components.available === 'function') {
+      // null means "cannot tell" (no agent-presets service): let the plan pass,
+      // exactly as a host without the component port did before shapes existed.
+      if ((await components.available(required)) !== false) continue
+    } else if (components.enabled(required) === true) continue
+    throw new TowerToolError(
+      'invalid-argument',
+      `the ${required} component is off: surveys cannot be planned; build missions are unaffected`,
+      { nextAction: `enable the ${required} component and plan the survey again` },
+    )
+  }
+}
+
+/**
+ * @param {any} input
+ * @returns {boolean}
+ */
+function planNeedsRead(input) {
+  return (input?.missions ?? []).some((mission) => shapeFor(mission?.kind).fields.readCommit)
+}
 
 export async function plan(tower, input = {}) {
-  const prepared = normalizePlanMissions(input)
   return tower.deps.store.withLock(tower.paths, async () => {
     const state = await tower.load()
     const now = Date.now()
+    // A survey records the commit it reads and the tracked-status fingerprint at
+    // plan time; a build plan reads nothing extra.
+    await assertShapeComponents(tower, input)
+    const read = planNeedsRead(input) ? await readFacts(tower, state.base) : {}
+    const prepared = normalizePlanMissions(input, read)
     // Archived ids stay in the known set: a new mission must not reuse an id
     // and a merged dependency may live in the archive index (#73).
     const archive = await tower.archiveIndex()
@@ -29,6 +73,24 @@ export async function plan(tower, input = {}) {
 
     const created = assigned.map((mission) => newMission(mission.id, mission, now))
     const applied = applyPlan(state, created)
+    // #148 W2: report survey evidence freshness at plan time. New builds have no
+    // provisioned base yet, so the warning compares against the state base; it
+    // is advisory here and never blocks the plan. Archived survey dependencies
+    // keep their read commit on the archive index, so they are checked too.
+    const archivedMissions = new Map(
+      (archive.ok ? archive.missions : []).map((entry) => [entry.id, entry]),
+    )
+    const warnings = []
+    for (const mission of created) {
+      warnings.push(
+        ...(await surveyStaleWarnings(tower, {
+          mission,
+          state,
+          missions: state.missions,
+          archived: archivedMissions,
+        })),
+      )
+    }
     const swept = await sweepArchive(tower, state, { now })
     state.revision += 1
     state.updatedAt = now
@@ -46,6 +108,7 @@ export async function plan(tower, input = {}) {
     return {
       revision: state.revision,
       missions: created.map((mission) => fullMission(mission)),
+      ...(warnings.length > 0 ? { warnings } : {}),
       ...(swept.archived.length > 0 ? { archived: swept.archived } : {}),
       ...(swept.error ? { archiveError: swept.error } : {}),
     }