dsh-tower 2.5.0 → 2.7.0

package/domain/shapes/survey.js

@@ -0,0 +1,445 @@
+// The survey shape (#148/#149): a read of one commit, not a write of a branch.
+//
+// A survey has no worktree, no branch and no commit of its own. By default it
+// runs in the shared checkout with a read-only preset allow-list. With
+// `survey.sandbox: 'detached'` the read moves into a disposable detached git
+// worktree at the recorded commit (#148 W2): the sandbox preset may write and
+// run commands there, but the sandbox has no branch, never merges, is removed
+// when the mission completes or is abandoned, and must still end at the
+// recorded commit with zero commits. Both placements record the commit read
+// plus the tracked-status fingerprint captured at plan time; only the shared
+// placement enforces the fingerprint as a completion invariant.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { hasCheckEvidence } from '../evidence.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').Blocker} Blocker */
+/** @typedef {import('../../types/index.js').TowerConfig} TowerConfig */
+
+/** @type {readonly string[]} */
+export const SURVEY_STATUSES = Object.freeze(['planned', 'active', 'completed', 'blocked', 'paused', 'abandoned'])
+
+/**
+ * The evidence this shape accepts (#149 W4). A survey has no branch and no
+ * tree tip, so a discovery receipt cannot appertain; its completion checks are
+ * still accepted through the same one reader.
+ * @type {import('../evidence.js').EvidenceContract}
+ */
+export const EVIDENCE = Object.freeze({
+  completionChecks: true,
+  testReceipts: /** @type {const} */ (false),
+})
+
+/**
+ * The survey shape's path reach (#149 W4): a survey owns no paths. Its scope is
+ * empty by construction and any changed path is a fence violation; the
+ * placement (shared read-only checkout or detached disposable sandbox) changes
+ * where it runs, not what it may change.
+ * @type {{ ownsPaths: boolean, fence: 'scope' | 'read-only' }}
+ */
+export const REACH = Object.freeze({
+  ownsPaths: false,
+  fence: /** @type {const} */ ('read-only'),
+})
+
+/**
+ * A survey has no `merged` row or column: it is never merged, only completed.
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const SURVEY_TRANSITIONS = Object.freeze({
+  planned: Object.freeze(['active', 'blocked', 'abandoned']),
+  active: Object.freeze(['completed', 'blocked', 'paused', 'abandoned']),
+  // W3: `blocked` is derived from open blockers; clearing them is the only way
+  // out, and a blocker always wins over a pause (hence paused -> blocked).
+  blocked: Object.freeze(['active', 'abandoned']),
+  paused: Object.freeze(['active', 'blocked', 'abandoned']),
+  completed: Object.freeze([]),
+  abandoned: Object.freeze([]),
+})
+
+/**
+ * @param {string} status
+ * @returns {boolean}
+ */
+export function isTerminal(status) {
+  return status === 'completed' || status === 'abandoned'
+}
+
+/**
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function canTransition(from, to) {
+  return (SURVEY_TRANSITIONS[from] ?? []).includes(to)
+}
+
+/**
+ * Survey planning records what is being read, not what will be written: the
+ * commit and the tracked-status fingerprint at plan time. Scope is empty.
+ * @param {{ readCommit?: unknown, readDirty?: unknown }} context
+ * @returns {{ scope: string[], readCommit: string, readDirty: string[] }}
+ */
+export function planFields(context) {
+  const readCommit = context.readCommit
+  if (typeof readCommit !== 'string' || readCommit.length === 0) {
+    throw new TowerToolError('invalid-argument', 'a survey needs the commit it reads (state.base did not resolve)', {
+      nextAction: 'run tower_init so the base branch resolves to a commit, then plan the survey again',
+    })
+  }
+  const readDirty = Array.isArray(context.readDirty)
+    ? context.readDirty.filter((entry) => typeof entry === 'string')
+    : []
+  return { scope: [], readCommit, readDirty }
+}
+
+/**
+ * Completion invariants for a survey that reads the shared checkout: zero
+ * commits, same HEAD, same tracked files. The app layer supplies the observed
+ * primitives.
+ * @param {{ mission: Mission, head: string, readCommit: string, trackedChanged: string[] }} context
+ * @returns {{ commits: number }}
+ */
+export function checkCompletion({ mission, head, readCommit, trackedChanged }) {
+  if (head !== readCommit) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `survey ${mission.id} moved HEAD from ${String(readCommit).slice(0, 12)} to ${String(head).slice(0, 12)}; a survey reads one commit and makes no commits`,
+      { nextAction: 'reset the shared checkout to the recorded readCommit; do not commit survey work' },
+    )
+  }
+  if (trackedChanged.length > 0) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `survey ${mission.id} changed tracked files: ${trackedChanged.join(', ')}; a survey is read-only`,
+      { nextAction: 'restore the shared checkout tracked files to the status captured at plan time' },
+    )
+  }
+  return { commits: 0 }
+}
+
+/**
+ * Completion invariants for a detached survey sandbox: the disposable checkout
+ * is allowed to contain write/shell side effects, but it may not commit and it
+ * must still be at the recorded commit. The sandbox itself is removed after a
+ * successful completion.
+ * @param {{ mission: Mission, head: string, readCommit: string, commits: number, sandbox: string }} context
+ * @returns {{ commits: number }}
+ */
+export function checkSandboxCompletion({ mission, head, readCommit, commits, sandbox }) {
+  if (!sandbox || sandbox !== mission.sandbox) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `detached survey ${mission.id} has no recorded sandbox; re-provision the survey or abandon it`,
+      { nextAction: 'run tower_spawn to create the detached sandbox again, then complete' },
+    )
+  }
+  if (commits !== 0) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `survey ${mission.id} made ${commits} commit(s) in its detached sandbox; a survey reads one commit and records no commit of its own`,
+      { nextAction: `reset --hard ${String(readCommit).slice(0, 12)} in ${sandbox}; the sandbox is disposable but its HEAD must stay at the recorded commit` },
+    )
+  }
+  if (head !== readCommit) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `survey ${mission.id} moved the detached sandbox HEAD from ${String(readCommit).slice(0, 12)} to ${String(head).slice(0, 12)}; a survey reads one commit and makes no commits`,
+      { nextAction: `reset --hard ${String(readCommit).slice(0, 12)} in ${sandbox}; the sandbox is removed on completion` },
+    )
+  }
+  return { commits: 0 }
+}
+
+/**
+ * Resolve the survey placement (#148 W2). The shape owns the decision so
+ * generic layers never compare `mission.kind` or read the raw key.
+ *
+ * A sandbox already recorded on the mission is authoritative: provisioned
+ * state must win over current config, otherwise flipping `survey.sandbox`
+ * between provision and completion would silently move the mission to the
+ * shared checkout (or make the completion invariants disagree with the
+ * checkout that actually exists). Config only decides initial provisioning.
+ * @param {Mission | null | undefined} [mission]
+ * @param {TowerConfig} [config]
+ * @returns {'shared' | 'detached'}
+ */
+export function resolveProvisioning(mission, config = /** @type {TowerConfig} */ ({})) {
+  const recorded = mission && typeof mission.sandbox === 'string' ? mission.sandbox.trim() : ''
+  if (recorded.length > 0) return 'detached'
+  return config.survey?.sandbox === 'detached' ? 'detached' : 'shared'
+}
+
+/**
+ * The preset that executes a survey in the resolved placement. Shared surveys
+ * stay strictly read-only; a detached sandbox gets a preset that may write and
+ * run commands inside the disposable checkout.
+ * @param {Mission | null | undefined} [mission]
+ * @param {TowerConfig} [config]
+ * @returns {'tower-survey' | 'tower-survey-sandbox'}
+ */
+export function resolvePreset(mission, config = /** @type {TowerConfig} */ ({})) {
+  return resolveProvisioning(mission, config) === 'detached' ? 'tower-survey-sandbox' : 'tower-survey'
+}
+
+/** Shared-checkout completion invariants (the default placement). */
+const SHARED_COMPLETION = Object.freeze({
+  requiresWorktree: false,
+  requiresSandbox: false,
+  requiresCommits: false,
+  requiresClean: false,
+  requiresHeadMatch: true,
+  requiresTrackedStatus: true,
+  check: /** @type {(ctx: any) => { commits: number }} */ (checkCompletion),
+})
+
+/** Detached-sandbox completion invariants. */
+const SANDBOX_COMPLETION = Object.freeze({
+  requiresWorktree: false,
+  requiresSandbox: true,
+  requiresCommits: true,
+  requiresClean: false,
+  requiresHeadMatch: true,
+  requiresTrackedStatus: false,
+  check: /** @type {(ctx: any) => { commits: number }} */ (checkSandboxCompletion),
+})
+
+/**
+ * The completion invariants for the checkout the mission was provisioned in.
+ * Placement is read from the recorded `mission.sandbox`, never from current
+ * config: a detached sandbox still enforces its HEAD/zero-commit invariants and
+ * is removed after a config flip to `none`, and a survey that never got a
+ * sandbox keeps the shared invariants even if config now asks for `detached`.
+ * The config parameter stays in the shape contract for symmetry with other
+ * hooks, but is intentionally not consulted here.
+ * @param {Mission} mission
+ * @param {TowerConfig} [_config]
+ * @returns {typeof SHARED_COMPLETION | typeof SANDBOX_COMPLETION}
+ */
+export function resolveCompletion(mission, _config = /** @type {TowerConfig} */ ({})) {
+  return resolveProvisioning(mission) === 'detached' ? SANDBOX_COMPLETION : SHARED_COMPLETION
+}
+
+/**
+ * Completion blockers for a survey. A survey is never merged, so the build-only
+ * "closed mission owns a branch" blocker does not exist for it.
+ * @param {Mission} mission
+ * @param {TowerConfig} [config]
+ * @returns {Blocker[]}
+ */
+export function completionBlockers(mission, config = /** @type {TowerConfig} */ ({})) {
+  /** @type {Blocker[]} */
+  const blockers = []
+  if (mission.status !== 'completed') {
+    blockers.push({
+      code: 'mission-not-completed',
+      detail:
+        mission.status === 'blocked'
+          ? `mission ${mission.id} is blocked: ${(mission.blockers ?? []).join('; ')}; clear the blockers to resume it`
+          : `mission ${mission.id} is ${mission.status}; completion is required`,
+    })
+  }
+  const open = (mission.tasks ?? []).filter((task) => task.status === 'open')
+  if (open.length > 0) {
+    blockers.push({ code: 'tasks-open', detail: `${open.length} open task(s): ${open.map((task) => task.text).join('; ')}` })
+  }
+  if ((mission.blockers ?? []).length > 0) {
+    blockers.push({ code: 'blockers-present', detail: (mission.blockers ?? []).join('; ') })
+  }
+  if (config.gates?.requireChecks && !hasCheckEvidence(EVIDENCE, mission)) {
+    blockers.push({
+      code: 'no-check-evidence',
+      detail: `mission ${mission.id} has no completion checks; gates.requireChecks is enabled`,
+    })
+  }
+  return blockers
+}
+
+/**
+ * A completed survey satisfies its dependents; its read commit is part of the
+ * evidence, but the shape contract only needs the terminal status.
+ * @param {Pick<Mission, 'status'>} dep
+ * @returns {boolean}
+ */
+export function dependencySatisfied(dep) {
+  return dep.status === 'completed' || dep.status === 'abandoned'
+}
+
+/**
+ * Worker spawn constraints: a survey worker runs in the shared checkout (or,
+ * with `survey.sandbox: 'detached'`, in a disposable detached worktree) and
+ * never provisions a branch. The concrete placement/preset is resolved by
+ * `resolveProvisioning`/`resolvePreset`.
+ * @type {{ provisioning: 'shared', missionStatuses: readonly string[], worktree: false, defaultPreset: string, countsTowardWorkerBudget: boolean, model: string }}
+ */
+export const spawn = Object.freeze({
+  provisioning: /** @type {const} */ ('shared'),
+  missionStatuses: Object.freeze(['planned', 'active', 'blocked', 'paused']),
+  worktree: /** @type {const} */ (false),
+  defaultPreset: 'tower-survey',
+  countsTowardWorkerBudget: false,
+  model: 'survey',
+})
+
+/**
+ * Mission briefing lines that are specific to the survey shape. A detached
+ * sandbox is named explicitly so the worker never edits the main checkout and
+ * knows the checkout is disposable but the recorded commit is pinned.
+ * @param {Mission} mission
+ * @param {{ repoRoot: string, worktree?: unknown }} context
+ * @returns {string[]}
+ */
+export function briefing(mission, context) {
+  const short = String(mission.readCommit ?? '').slice(0, 12)
+  const fingerprint = (mission.readDirty ?? []).length
+  if (mission.sandbox) {
+    return [
+      `Read and work in the disposable detached sandbox: ${mission.sandbox} (no branch, no commit of your own; the sandbox is removed when the mission completes)`,
+      `The sandbox HEAD is pinned to ${short}. Write and shell side effects stay inside the sandbox; completion requires HEAD to still be ${short} and zero new commits.`,
+      `Pass workdir="${mission.sandbox}" on every shell command; never modify the main checkout ${context.repoRoot}.`,
+    ]
+  }
+  return [
+    `Read only: commit ${short} in the shared checkout ${context.repoRoot} (no branch, no worktree, no commits)`,
+    `Completion invariants: HEAD must still be ${short} and the tracked-status set captured at plan time (${fingerprint} path(s)) must be unchanged. Complete with zero commits.`,
+  ]
+}
+
+/**
+ * Projection of the survey-specific mission fields for summaries/board rows.
+ * @param {Mission} mission
+ * @returns {Record<string, any>}
+ */
+export function summary(mission) {
+  return {
+    worktree: null,
+    sandbox: mission.sandbox ?? null,
+    readCommit: mission.readCommit ?? null,
+    readDirty: [...(mission.readDirty ?? [])],
+    mergedCommit: null,
+    mergedAt: null,
+  }
+}
+
+/**
+ * One-line human description of where the mission reads, used by reports.
+ * @param {Mission} mission
+ * @returns {string | null}
+ */
+export function describe(mission) {
+  return mission.readCommit ? `read at ${String(mission.readCommit).slice(0, 12)}` : null
+}
+
+/**
+ * v3 -> v4 migration hook (#148). A legacy survey reads the commit its
+ * branch-shaped worktree was based on, keeps its completion report, and loses
+ * the worktree/branch/merge projection. A legacy survey that was merged becomes
+ * completed: a survey is never merged in v4.
+ * @param {Record<string, any>} mission
+ * @returns {boolean}
+ */
+export function isLegacy(mission) {
+  return mission.kind === 'survey'
+}
+
+/**
+ * The commit a legacy (v3, branch-shaped) survey recorded, in fallback order:
+ * the v4 field, the worktree it was based on, then the mission-level base
+ * commit. A survey planned and never provisioned (or whose spawn failed before
+ * provisioning) has none of the three.
+ * @param {Record<string, any>} mission
+ * @returns {string | null}
+ */
+export function legacyReadCommit(mission) {
+  const recorded = mission.readCommit ?? mission.worktree?.baseCommit ?? mission.baseCommit
+  return typeof recorded === 'string' && recorded.length > 0 ? recorded : null
+}
+
+/**
+ * True when a legacy survey has no base of its own: the state loader must
+ * resolve one from the repository before migration can anchor the survey.
+ * @param {Record<string, any>} mission
+ * @returns {boolean}
+ */
+export function needsLegacyRead(mission) {
+  return legacyReadCommit(mission) === null
+}
+
+/**
+ * @param {Record<string, any>} mission
+ * @param {{ legacySurveyRead?: { readCommit?: unknown, readDirty?: unknown } | null }} [options]
+ * @returns {Record<string, any>}
+ */
+export function migrateLegacy(mission, options = {}) {
+  const recorded = legacyReadCommit(mission)
+  // The loader resolves the state base once for the whole document; only a
+  // survey that recorded no base of its own may consume that resolution. A
+  // recorded commit always wins, so re-running the step is a fixed point.
+  const resolved = recorded === null ? options.legacySurveyRead : null
+  const readCommit = recorded ?? resolved?.readCommit
+  if (typeof readCommit !== 'string' || readCommit.length === 0) {
+    throw new Error(
+      `survey ${String(mission.id)} has no recorded base commit to read; the state loader must resolve the base ref for a planned-but-never-provisioned survey`,
+    )
+  }
+  const readDirty =
+    recorded === null
+      ? Array.isArray(resolved?.readDirty)
+        ? resolved.readDirty.filter((entry) => typeof entry === 'string')
+        : []
+      : Array.isArray(mission.readDirty)
+        ? [...mission.readDirty]
+        : []
+  const next = /** @type {Record<string, any>} */ ({
+    ...mission,
+    kind: 'survey',
+    scope: [],
+    readCommit,
+    readDirty,
+  })
+  if (next.status === 'merged') next.status = 'completed'
+  delete next.worktree
+  delete next.worktreeRemovedAt
+  delete next.sandbox
+  delete next.sandboxCleanupError
+  delete next.sandboxRemovedAt
+  delete next.branch
+  delete next.baseCommit
+  delete next.mergedCommit
+  delete next.mergedAt
+  return next
+}
+
+export const surveyShape = Object.freeze({
+  kind: /** @type {const} */ ('survey'),
+  statuses: SURVEY_STATUSES,
+  transitions: SURVEY_TRANSITIONS,
+  isTerminal,
+  canTransition,
+  isLegacy,
+  migrateLegacy,
+  needsLegacyRead,
+  canMerge: false,
+  canRebase: false,
+  provisioning: /** @type {const} */ ('shared'),
+  reach: REACH,
+  // Document dimensions this shape owns; the state validator reads these.
+  fields: Object.freeze({ worktree: false, readCommit: true, merge: false, sandbox: true }),
+  // A survey needs its optional component row; a build does not.
+  requiredComponent: 'tower-survey',
+  // Only a survey records `result` evidence on completion.
+  acceptsResult: true,
+  evidence: EVIDENCE,
+  planFields,
+  resolveProvisioning,
+  resolvePreset,
+  resolveCompletion,
+  completion: SHARED_COMPLETION,
+  completionBlockers,
+  dependencySatisfied,
+  spawn,
+  briefing,
+  summary,
+  describe,
+})

package/domain/state/archive.js

@@ -11,7 +11,8 @@
 // writing the files, and the lock that makes them atomic with state.json, live
 // in `adapters/archive.js` and `app/archive.js`.
 // @ts-check
-import { isTerminal } from '../mission.js'
+import { normalizeResult } from '../missions/completion.js'
+import { shapeFor } from '../shapes/index.js'
 
 /** @typedef {import('../../types/index.js').Finding} Finding */
 /** @typedef {import('../../types/index.js').Mission} Mission */
@@ -63,7 +64,8 @@ export function terminalTimestamp(mission) {
  * Select the terminal missions the policy wants moved out of state.json.
  *
  * Eligibility:
- *   - status is `merged` or `abandoned` (terminal);
+ *   - the mission's shape reports its status as terminal (`merged`/`abandoned`
+ *     for a build, `completed`/`abandoned` for a survey);
  *   - the worktree is gone (never provisioned, or removed by teardown);
  *   - the caller did not protect it (open batch members, live agents).
  *
@@ -85,7 +87,7 @@ export function selectForArchive(missions, policy = {}, options = {}) {
   const afterDays = Number.isFinite(policy?.afterDays) ? /** @type {number} */ (policy.afterDays) : 30
   const maxMissions = Number.isFinite(policy?.maxMissions) ? /** @type {number} */ (policy.maxMissions) : 100
   const eligible = missions.filter(
-    (mission) => isTerminal(mission.status) && !hasLiveWorktree(mission) && !protectedIds.has(mission.id),
+    (mission) => shapeFor(mission.kind).isTerminal(mission.status) && !hasLiveWorktree(mission) && !protectedIds.has(mission.id),
   )
   if (eligible.length === 0) return []
   if (options.force === true) return eligible
@@ -140,10 +142,30 @@ export function archiveYearFor(now) {
   return new Date(now).getUTCFullYear()
 }
 
+/**
+ * Keep the bounded survey evidence on the index entry. The value was already
+ * normalized when the survey completed, but re-normalizing is cheap and makes
+ * a hand-edited or legacy document safe to archive.
+ * @param {Mission} mission
+ * @returns {Record<string, any> | null}
+ */
+function boundedResult(mission) {
+  const record = /** @type {Record<string, any>} */ (mission)
+  if (record.result === undefined || record.result === null) return null
+  try {
+    return normalizeResult(record.result)
+  } catch {
+    return null
+  }
+}
+
 /**
  * The compact entry written to `archive/index.json` (and referenced by
  * `tower_status`). It carries enough fields to keep ordering, dependency
- * lookups and mission-id allocation working without loading a year file.
+ * lookups, freshness checks and mission-id allocation working without loading a
+ * year file: `readCommit` and the bounded survey `result` stay on the index so
+ * an archived survey dependency keeps its evidence and cannot fail the
+ * `gates.requireFreshSurvey` check open.
  * @param {Mission} mission
  * @param {ArchiveMeta} meta
  * @returns {Record<string, any>}
@@ -158,6 +180,8 @@ export function archiveIndexEntry(mission, meta) {
     kind: record.kind ?? 'build',
     scope: Array.isArray(record.scope) ? record.scope : [],
     deps: Array.isArray(record.deps) ? record.deps : [],
+    readCommit: record.readCommit ?? null,
+    result: boundedResult(mission),
     owner: record.owner ?? null,
     branch,
     mergedCommit: record.mergedCommit ?? null,

package/domain/state/migrations.js

@@ -12,8 +12,12 @@
 // @ts-check
 import { TowerToolError } from '../errors.js'
 import { SCHEMA_VERSION } from '../mission.js'
+import { SHAPE_KINDS, shapeFor } from '../shapes/index.js'
+import { normalizeBatchStatus } from '../batch.js'
 
-/** @typedef {{ from: number, to: number, migrate: (state: Record<string, any>) => Record<string, any> }} StateMigration */
+/** @typedef {{ readCommit: string, readDirty: string[] }} LegacySurveyRead */
+/** @typedef {{ legacySurveyRead?: LegacySurveyRead | null }} MigrationContext */
+/** @typedef {{ from: number, to: number, migrate: (state: Record<string, any>, context?: MigrationContext) => Record<string, any> }} StateMigration */
 
 /**
  * @param {unknown} value
@@ -57,10 +61,109 @@ export function migrateV2ToV3(state) {
   return { ...state, caseInsensitive: null }
 }
 
+/**
+ * v3 -> v4. Mission state becomes per-shape (#149). Every mission is stamped with
+ * its kind; a legacy branch-shaped survey keeps the commit it read (the
+ * worktree's base commit) and drops the worktree/branch/merge fields it no
+ * longer owns. Build missions keep their document unchanged.
+ *
+ * The step is pure and one-way. Re-running it on a v4 document is a fixed point:
+ * every mission already has a kind, so the same shape migration rewrites it to
+ * the same values.
+ *
+ * A legacy survey planned but never provisioned records no base commit at all
+ * (2.6.0 wrote neither `baseCommit` nor a worktree at plan time). The loader
+ * resolves the state base once and passes it as `context.legacySurveyRead`; the
+ * survey shape consumes it only when it has no recorded base of its own.
+ * @param {Record<string, any>} state
+ * @param {MigrationContext} [context]
+ * @returns {Record<string, any>}
+ */
+export function migrateV3ToV4(state, context = {}) {
+  const next = { ...state }
+  next.missions = (Array.isArray(next.missions) ? next.missions : []).map((mission) => {
+    if (!isPlainObject(mission)) return mission
+    const shape = SHAPE_KINDS.map((kind) => shapeFor(kind)).find((candidate) => candidate.isLegacy(mission))
+    return shape ? shape.migrateLegacy(mission, context) : mission
+  })
+  return next
+}
+
+/**
+ * v4 -> v5. Two contracts that used to overlap are made exact (#149 W3):
+ *
+ * - `blocked` is derived from open blockers, not an independent stop state. A
+ *   non-terminal mission that says `blocked` without a blocker gets one explicit
+ *   legacy blocker (it stays blocked; `clear_blockers` resumes it); a
+ *   non-terminal mission that carries blockers under any other status becomes
+ *   `blocked` because a blocker wins over a pause or a fresh status. Terminal
+ *   missions keep their blockers as history and are never reopened.
+ * - A batch's status vocabulary is normalized to `open|closed|abandoned`;
+ *   pre-v5 documents used `created|active|pending` as synonyms for `open`.
+ *
+ * The step is pure and one-way. Re-running it on a v5 document is a fixed point.
+ * @param {Record<string, any>} state
+ * @returns {Record<string, any>}
+ */
+export function migrateV4ToV5(state) {
+  const next = { ...state }
+  next.missions = (Array.isArray(next.missions) ? next.missions : []).map((mission) => {
+    if (!isPlainObject(mission)) return mission
+    const shape = shapeFor(mission.kind)
+    const blockers = Array.isArray(mission.blockers) ? [...mission.blockers] : []
+    if (shape.isTerminal(mission.status)) return { ...mission, blockers }
+    if (mission.status === 'blocked' && blockers.length === 0) {
+      return {
+        ...mission,
+        blockers: ['(legacy blocked state: no blocker was recorded; clear_blockers resumes the mission)'],
+      }
+    }
+    if (mission.status !== 'blocked' && blockers.length > 0) {
+      const migrated = { ...mission, status: 'blocked', blockers }
+      // A blocker supersedes a pause: the pause cause no longer describes why
+      // the mission is stopped.
+      delete migrated.pauseCause
+      return migrated
+    }
+    return mission
+  })
+  if (Array.isArray(next.batches)) {
+    next.batches = next.batches.map((batch) => {
+      if (!isPlainObject(batch)) return batch
+      const status = normalizeBatchStatus(batch.status)
+      return status === batch.status ? batch : { ...batch, status }
+    })
+  }
+  return next
+}
+
+/**
+ * True when a pre-v4 document contains at least one legacy mission whose shape
+ * cannot anchor its read from the document alone (a survey planned but never
+ * provisioned). The load path must resolve the repository base before migration
+ * runs; a document that recorded its own commit needs no resolver, and a
+ * current-version document is never re-migrated.
+ * @param {unknown} state
+ * @returns {boolean}
+ */export function legacySurveyNeedsRead(state) {
+  if (!isPlainObject(state)) return false
+  const document = /** @type {Record<string, any>} */ (state)
+  const version = document.schemaVersion
+  if (!Number.isInteger(version) || version < 1 || version >= SCHEMA_VERSION) return false
+  const missions = Array.isArray(document.missions) ? document.missions : []
+  return missions.some((mission) => {
+    if (!isPlainObject(mission)) return false
+    const shape = SHAPE_KINDS.map((kind) => shapeFor(kind)).find((candidate) => candidate.isLegacy(mission))
+    return typeof shape?.needsLegacyRead === 'function' && shape.needsLegacyRead(mission)
+  })
+}
+
 /** Ordered registry: entry 0 moves 1 -> 2, entry 1 moves 2 -> 3, and so on. */
 export const STATE_MIGRATIONS = Object.freeze([
   Object.freeze({ from: 1, to: 2, migrate: migrateV1ToV2 }),
   Object.freeze({ from: 2, to: 3, migrate: migrateV2ToV3 }),
+  Object.freeze({ from: 3, to: 4, migrate: migrateV3ToV4 }),
+  Object.freeze({ from: 4, to: 5, migrate: migrateV4ToV5 }),
 ])
 
 /**
@@ -91,16 +194,20 @@ export function migrationChain(from, to = SCHEMA_VERSION, migrations = STATE_MIG
 
 /**
  * Apply the registry to a parsed document. Pure: the input object is never
- * touched and the returned document has the target `schemaVersion`.
+ * touched and the returned document has the target `schemaVersion`. The same
+ * `MigrationContext` object reaches every step, so a step may consume a value
+ * the loader resolved once (the legacy survey read).
  *
  * @param {Record<string, any>} state
- * @param {{ statePath?: string, to?: number, migrations?: readonly StateMigration[] }} [options]
+ * @param {{ statePath?: string, to?: number, migrations?: readonly StateMigration[] } & MigrationContext} [options]
  * @returns {{ state: Record<string, any>, from: number, to: number, steps: Array<{ from: number, to: number }> }}
  */
 export function migrateState(state, options = {}) {
   const where = options.statePath ? ` at ${options.statePath}` : ''
   const to = options.to ?? SCHEMA_VERSION
   const migrations = options.migrations ?? STATE_MIGRATIONS
+  /** @type {MigrationContext} */
+  const context = { legacySurveyRead: options.legacySurveyRead }
   const from = state?.schemaVersion
   const chain = migrationChain(from, to, migrations)
   if (!chain || chain.length === 0) {
@@ -120,7 +227,7 @@ export function migrateState(state, options = {}) {
     /** @type {Record<string, any>} */
     let next
     try {
-      next = step.migrate(current)
+      next = step.migrate(current, context)
     } catch (error) {
       throw new TowerToolError(
         'state-migration-failed',