dsh-tower 2.5.0 → 2.7.0

package/app/reviewCheckout.js

@@ -0,0 +1,133 @@
+// Review evidence checkouts (#149 W3).
+//
+// A review verdict is stamped with a commit, not with whatever a live worktree
+// HEAD happens to be when the reviewer submits. When a reviewer is spawned the
+// tower creates a disposable detached checkout at the mission branch tip and
+// records that commit on the roster row. The reviewer reads (and tower_diff
+// shows) that commit; the verdict uses it; the merge gate compares it to the
+// current branch tip with the existing `tip-moved` blocker. The checkout is
+// removed as soon as the verdict is recorded, so it can never silently drift.
+//
+// This module owns only the checkout lifecycle. The commit stamp and the
+// admission rules live in `domain/missions/review.js` and `app/review.js`.
+import path from 'node:path'
+import { TowerToolError } from '../domain/errors.js'
+import { validateState } from '../domain/state.js'
+import { removeSandbox } from './sandbox.js'
+import { resolveCheckoutRoot } from './provision.js'
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * Deterministic per-reviewer checkout path. `-review-` cannot collide with the
+ * `-sandbox` survey suffix or a mission worktree directory.
+ * @param {string} root
+ * @param {string} missionId
+ * @param {string} reviewerName
+ * @returns {string}
+ */
+export function reviewCheckoutPath(root, missionId, reviewerName) {
+  const safeName = String(reviewerName).replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 64)
+  return path.join(root, `${missionId}-review-${safeName}`)
+}
+
+/**
+ * Provision the detached review checkout for a completed mission at its current
+ * branch tip. Returns the mission, the checkout path and the commit the reviewer
+ * is bound to.
+ * @param {any} tower
+ * @param {{ missionId?: unknown, name?: unknown, worktreeRoot?: string }} input
+ * @returns {Promise<{ mission: any, path: string, commit: string }>}
+ */
+export async function provisionReviewCheckout(tower, input = {}) {
+  const missionId = input.missionId
+  if (typeof missionId !== 'string' || missionId.trim().length === 0) fail('tower_spawn requires missionId in this version')
+  if (typeof input.name !== 'string' || input.name.trim().length === 0) fail('a review checkout needs the reviewer name')
+  const state = await tower.load()
+  const mission = state.missions.find((entry) => entry.id === missionId)
+  if (!mission) fail(`unknown mission "${missionId}"`, 'mission-not-found')
+  if (!mission.worktree) fail(`mission ${mission.id} has no branch to review`, 'reviewer-prerequisite')
+  if (mission.status !== 'completed') {
+    fail(`mission ${mission.id} is ${mission.status}; only a completed mission can be reviewed`, 'reviewer-prerequisite')
+  }
+  const commit = await tower.branchTip(mission)
+  const root = resolveCheckoutRoot(tower, input)
+  await tower.deps.store.ensureDir(root)
+  const checkout = reviewCheckoutPath(root, mission.id, input.name.trim())
+  await tower.deps.store.withGitLock(tower.paths, async () => {
+    if (await tower.deps.store.exists(checkout)) {
+      const registered = (await tower.deps.vcs.listWorktrees(tower.root)).some(
+        (entry) => path.resolve(entry.path) === path.resolve(checkout),
+      )
+      if (!registered) {
+        fail(`review checkout path already exists and is not a git worktree: ${checkout}; remove it and retry`)
+      }
+      // A leftover checkout from a failed spawn is disposable evidence for a
+      // review that never happened; recreate it at the recorded tip.
+      await tower.git(tower.root, ['worktree', 'remove', '--force', checkout]).catch(() => {})
+    }
+    await tower.git(tower.root, ['worktree', 'add', '--detach', checkout, commit])
+    await tower.ensureExcluded(checkout)
+  }, tower.gitMutexOptions({ phase: 'review' }))
+  const head = await tower.revParse(checkout, 'HEAD')
+  if (head !== commit) {
+    await removeSandbox(tower, checkout)
+    fail(`review checkout ${checkout} was created at ${String(head).slice(0, 12)} instead of ${commit.slice(0, 12)}; no reviewer was started`)
+  }
+  return { mission, path: checkout, commit }
+}
+
+/**
+ * Remove one review checkout. Advisory and bounded: a failed cleanup never
+ * blocks the verdict, and `tower_teardown`/`tower_recover` retry it later.
+ * @param {any} tower
+ * @param {string} checkout
+ * @returns {Promise<{ ok: boolean, removed: boolean, attempts: number, error?: string }>}
+ */
+export async function removeReviewCheckout(tower, checkout) {
+  return removeSandbox(tower, checkout)
+}
+
+/**
+ * Remove a reviewer's checkout and clear the recorded path on its roster row.
+ * The recorded commit stays: it is the evidence the review was based on.
+ * @param {any} tower
+ * @param {{ name: string, missionId?: string | null }} input
+ * @returns {Promise<{ entry: any, removal: { ok: boolean, removed: boolean, attempts: number, error?: string } } | null>}
+ */
+export async function cleanupReviewCheckout(tower, input) {
+  const removal = await tower.deps.store.withLock(tower.paths, async () => {
+    const state = await tower.load()
+    const entry = (state.roster ?? []).find(
+      (row) =>
+        row.name === input.name &&
+        (input.missionId === undefined || input.missionId === null || row.missionId === input.missionId),
+    )
+    if (!entry || typeof entry.reviewCheckout !== 'string' || entry.reviewCheckout.length === 0) return null
+    return { checkout: entry.reviewCheckout, entryName: entry.name, missionId: entry.missionId }
+  })
+  if (!removal) return null
+  const result = await removeSandbox(tower, removal.checkout)
+  // A failed removal keeps the path on the row so teardown can retry it; the
+  // verdict itself never depends on this advisory cleanup.
+  if (!result.ok) return { entry: null, removal: result }
+  const written = await tower.deps.store.withLock(tower.paths, async () => {
+    const state = await tower.load()
+    const entry = (state.roster ?? []).find((row) => row.name === removal.entryName)
+    if (!entry || entry.reviewCheckout !== removal.checkout) return entry ?? null
+    delete entry.reviewCheckout
+    state.revision += 1
+    state.updatedAt = Date.now()
+    validateState(state, tower.paths.state)
+    await tower.deps.store.writeJsonAtomic(tower.paths.state, state)
+    return entry
+  })
+  return { entry: written, removal: result }
+}

package/app/sandbox.js

@@ -0,0 +1,121 @@
+// Disposable detached survey sandboxes (#148 W2).
+//
+// A `survey.sandbox: 'detached'` survey reads in a detached git worktree with no
+// branch. The checkout is disposable: completion, abandon and teardown remove it
+// with a bounded retry. Cleanup is advisory — a removal failure leaves the
+// recorded path and a visible diagnostic in state, and never fails or corrupts
+// the transition that triggered it.
+// @ts-check
+import path from 'node:path'
+import { validateState } from '../domain/state.js'
+
+/** Bounded cleanup attempts: a transient git lock or busy file is retried. */
+export const SANDBOX_CLEANUP_ATTEMPTS = 3
+export const SANDBOX_RETRY_DELAY_MS = 50
+
+/** @param {number} ms */
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * @param {any} tower
+ * @param {string} sandbox
+ * @returns {Promise<boolean>}
+ */
+async function registered(tower, sandbox) {
+  try {
+    const entries = await tower.deps.vcs.listWorktrees(tower.root)
+    return entries.some((entry) => entry.path && path.resolve(entry.path) === path.resolve(sandbox))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Remove one detached sandbox worktree, retrying a bounded number of times.
+ * Never throws: the result is the diagnostic. A path git no longer registers is
+ * treated as already removed, so a half-finished cleanup is not an error.
+ * @param {any} tower
+ * @param {string} sandbox
+ * @param {{ attempts?: number, delayMs?: number }} [options]
+ * @returns {Promise<{ ok: boolean, removed: boolean, attempts: number, error?: string }>}
+ */
+export async function removeSandbox(tower, sandbox, options = {}) {
+  const attempts = Math.max(1, options.attempts ?? SANDBOX_CLEANUP_ATTEMPTS)
+  const delayMs = options.delayMs ?? SANDBOX_RETRY_DELAY_MS
+  /** @type {unknown} */
+  let lastError = null
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      if (!(await registered(tower, sandbox))) return { ok: true, removed: false, attempts: attempt }
+      await tower.deps.store.withGitLock(tower.paths, async () => {
+        await tower.git(tower.root, ['worktree', 'remove', '--force', sandbox])
+      }, tower.gitMutexOptions({ phase: 'sandbox-cleanup' }))
+      // Removing the registered worktree also removes its directory. Verify
+      // both, so a git that reports success but leaves the entry is retried.
+      if (!(await tower.deps.store.exists(sandbox)) && !(await registered(tower, sandbox))) {
+        return { ok: true, removed: true, attempts: attempt }
+      }
+      lastError = new Error(`git still reports ${sandbox} after worktree remove`)
+    } catch (error) {
+      lastError = error
+      if (!(await registered(tower, sandbox))) return { ok: true, removed: false, attempts: attempt }
+    }
+    if (attempt < attempts && delayMs > 0) await delay(delayMs)
+  }
+  return {
+    ok: false,
+    removed: false,
+    attempts,
+    error: String(/** @type {{ message?: unknown }} */ (lastError)?.message ?? lastError ?? 'sandbox cleanup failed').slice(0, 400),
+  }
+}
+
+/**
+ * Remove a mission's recorded sandbox and persist the outcome under a short
+ * state lock. Success clears `mission.sandbox`; failure keeps it and records an
+ * actionable `sandboxCleanupError` plus an activity entry, so the tower can see
+ * the retained path and retry without the state contradicting the filesystem.
+ *
+ * Returns null when the mission has no sandbox (or no longer exists).
+ * @param {any} tower
+ * @param {string} missionId
+ * @param {{ attempts?: number, delayMs?: number }} [options]
+ * @returns {Promise<{ ok: boolean, removed: boolean, attempts: number, path: string, error?: string } | null>}
+ */
+export async function cleanupSandbox(tower, missionId, options = {}) {
+  const state = await tower.load()
+  const mission = state.missions.find((entry) => entry.id === missionId)
+  const sandbox = mission && typeof /** @type {any} */ (mission).sandbox === 'string' ? /** @type {any} */ (mission).sandbox : null
+  if (!sandbox) return null
+  const removal = await removeSandbox(tower, sandbox, options)
+  const now = Date.now()
+  await tower.deps.store.withLock(tower.paths, async () => {
+    const fresh = await tower.load()
+    const current = fresh.missions.find((entry) => entry.id === missionId)
+    if (!current || /** @type {any} */ (current).sandbox !== sandbox) return
+    const record = /** @type {any} */ (current)
+    if (removal.ok) {
+      delete record.sandbox
+      delete record.sandboxCleanupError
+      record.sandboxRemovedAt = now
+    } else {
+      record.sandboxCleanupError = removal.error
+    }
+    current.updatedAt = now
+    fresh.revision += 1
+    fresh.updatedAt = now
+    validateState(fresh, tower.paths.state)
+    await tower.deps.store.writeJsonAtomic(tower.paths.state, fresh)
+    await tower.deps.store.appendJsonl(tower.paths.activity, {
+      at: now,
+      type: 'sandbox',
+      missionId,
+      text: removal.ok
+        ? `removed detached sandbox at ${sandbox}`
+        : `sandbox cleanup failed after ${removal.attempts} attempt(s): ${removal.error}; path retained at ${sandbox} — remove it with "git worktree remove --force ${sandbox}" and call tower_teardown to retry the record`,
+    }).catch(() => {})
+  })
+  return { ...removal, path: sandbox }
+}

package/app/sharedCheckout.js

@@ -0,0 +1,90 @@
+// Shared-checkout helpers for the survey shape (#148).
+//
+// A survey reads one commit in the shared checkout. The fingerprint recorded at
+// plan time is the set of *tracked* changed paths; untracked files (node_modules,
+// tmp output) are intentionally ignored so a read-only survey is not blocked by
+// build artefacts it never touched.
+// @ts-check
+
+import { TowerToolError } from '../domain/errors.js'
+
+/**
+ * @param {string} porcelain `git status --porcelain` output
+ * @returns {string[]} sorted tracked changed paths
+ */
+export function trackedFingerprint(porcelain) {
+  /** @type {string[]} */
+  const paths = []
+  for (const line of String(porcelain ?? '').split(/\r?\n/)) {
+    if (line.length < 4) continue
+    const status = line.slice(0, 2)
+    if (status === '??' || status === '!!') continue
+    let path = line.slice(3)
+    const rename = path.indexOf(' -> ')
+    if (rename >= 0) path = path.slice(rename + 4)
+    paths.push(path.replace(/^"|"$/g, ''))
+  }
+  return paths.sort()
+}
+
+/**
+ * Resolve the commit a survey reads and fingerprint the tracked status at the
+ * same moment.
+ * @param {{ revParse(cwd: string, ref: string): Promise<string>, git(cwd: string, args: string[]): Promise<string>, root: string }} tower
+ * @param {string} ref
+ * @returns {Promise<{ commit: string, dirty: string[] }>}
+ */
+export async function readFacts(tower, ref) {
+  const commit = await tower.revParse(tower.root, ref)
+  // A survey reads the shared checkout as it stands, so the checkout must be at
+  // the base it records. Otherwise every later completion check would compare
+  // against a commit the worker never saw (or block it for the wrong reason).
+  const head = await tower.revParse(tower.root, 'HEAD')
+  if (head !== commit) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `the shared checkout is not at ${ref}: HEAD is ${head.slice(0, 12)} but ${ref} reads ${commit.slice(0, 12)}`,
+      { nextAction: `check out ${ref} in the shared checkout and plan the survey again` },
+    )
+  }
+  const porcelain = await tower.git(tower.root, ['status', '--porcelain'])
+  return { commit, dirty: trackedFingerprint(porcelain) }
+}
+
+/**
+ * Load-time resolver for a legacy survey that recorded no base at all (#149).
+ * A 2.6.0 survey planned but never provisioned is a valid document with no
+ * `baseCommit` and no worktree; the v3 -> v4 migration must anchor it at the
+ * state's base ref as that ref resolves *now*, together with the tracked-status
+ * fingerprint at the same moment (never a fabricated empty set).
+ *
+ * HEAD is deliberately not compared with the base here: a migration must load
+ * even when the shared checkout is parked on another branch. The plan-time
+ * guard in `readFacts` is what enforces HEAD === the recorded commit for a new
+ * survey.
+ *
+ * Returns null when the document records no base ref at all; the migration then
+ * fails with its own clear message instead of inventing a commit.
+ * @param {{ revParse(cwd: string, ref: string): Promise<string>, git(cwd: string, args: string[]): Promise<string>, root: string }} tower
+ * @param {Record<string, any>} rawState
+ * @returns {Promise<{ readCommit: string, readDirty: string[] } | null>}
+ */
+export async function resolveLegacySurveyRead(tower, rawState) {
+  const base = rawState?.base
+  if (typeof base !== 'string' || base.length === 0) return null
+  let readCommit
+  try {
+    readCommit = await tower.revParse(tower.root, base)
+  } catch (error) {
+    throw new TowerToolError(
+      'state-migration-failed',
+      `cannot anchor a planned-but-never-provisioned legacy survey: the state base "${base}" does not resolve (${String(error?.message ?? error)})`,
+      {
+        cause: error,
+        nextAction: `restore or check out the base ref "${base}" in the shared checkout, then load tower again; state.json was not modified`,
+      },
+    )
+  }
+  const porcelain = await tower.git(tower.root, ['status', '--porcelain'])
+  return { readCommit, readDirty: trackedFingerprint(porcelain) }
+}

package/app/spawn-prechecks.js

@@ -2,6 +2,9 @@
 // service/provider/lease validation. Split out of tools/spawn.js; no I/O.
 import { TowerToolError } from '../domain/errors.js'
 import { ROSTER_INACTIVE_STATES } from '../domain/roster.js'
+import { reviewUnavailable } from '../domain/integration/review.js'
+import { shapeFor } from '../domain/shapes/index.js'
+import { roleCountsTowardBudget, roleMissionBlockers, roleTracksMission } from '../domain/roles.js'
 
 /**
  * Pick a unique roster name before any activation.
@@ -27,23 +30,21 @@ export function resolveRosterName({ role, missionId, requested, roster }) {
 
 /**
  * Role/mission preconditions checked before any provisioning.
- * @param {{ role: string, context: any }} input
+ * `config` is the repository-resolved Tower config (#M39): with
+ * `review.mode:off` there is no review to dispatch, so the reviewer role is
+ * refused before a worktree, preset or activation is touched.
+ * @param {{ role: string, context: any, config?: any }} input
  */
-export function assertSpawnableMission({ role, context }) {
-  if (role === 'reviewer') {
-    if (!context.mission.worktree) {
-      throw new TowerToolError('reviewer-prerequisite', 'reviewer needs an existing mission worktree; spawn a worker first')
-    }
-    if (context.mission.status !== 'completed') {
-      throw new TowerToolError('reviewer-prerequisite', `reviewer requires a completed mission; ${context.mission.id} is ${context.mission.status}`)
-    }
-  }
-  if (role === 'worker' && ['merged', 'abandoned'].includes(context.mission.status)) {
-    throw new TowerToolError(
-      'invalid-transition',
-      `mission ${context.mission.id} is ${context.mission.status}; a worker can only be spawned for a planned or active mission`,
-    )
-  }
+export function assertSpawnableMission({ role, context, config }) {
+  const shape = shapeFor(context.mission.kind)
+  // #149 W4: the role contract owns the prerequisites; the shape only supplies
+  // facts (can it merge? does it have a worktree? which statuses accept a spawn).
+  const [blocker] = roleMissionBlockers(role, {
+    shape,
+    mission: context.mission,
+    reviewAvailable: !reviewUnavailable(config),
+  })
+  if (blocker) throw new TowerToolError(blocker.code, blocker.message)
 }
 
 /**
@@ -73,10 +74,16 @@ export async function precheckWorkerOwnership({
   observeActivity,
 }) {
   let effectiveTakeover = takeover === true
-  if (role !== 'worker') return effectiveTakeover
+  if (!roleTracksMission(role)) return effectiveTakeover
+  // #148: a read-only survey worker must not consume a build worker slot, but
+  // the single-owner rule still applies to every worker entry.
+  const state = await tower.load()
+  const kinds = new Map(state.missions.map((entry) => [entry.id, entry.kind]))
+  const budgeted = (entry) => roleCountsTowardBudget(entry.role, shapeFor(kinds.get(entry.missionId)))
   const liveWorkers = view.roster.filter(
-    (entry) => entry.role === 'worker' && !ROSTER_INACTIVE_STATES.includes(entry.state),
+    (entry) => roleTracksMission(entry.role) && !ROSTER_INACTIVE_STATES.includes(entry.state),
   )
+  const budgetWorkers = liveWorkers.filter(budgeted)
   const sameMission = liveWorkers.filter((entry) => entry.missionId === missionId)
   if (sameMission.length > 1) {
     throw new TowerToolError(
@@ -118,9 +125,13 @@ export async function precheckWorkerOwnership({
     }
   }
   const replacing = effectiveTakeover ? sameMission : []
-  const remaining = liveWorkers.filter((entry) => !replacing.includes(entry))
+  const remaining = budgetWorkers.filter((entry) => !replacing.includes(entry))
   const max = Math.min(Number(maxLiveWorkers) || 4, budget)
-  if (remaining.length >= max) {
+  // The new mission's shape decides whether this spawn consumes a build slot: a
+  // survey does not, so it is allowed while every build slot is busy (#148).
+  const mission = state.missions.find((entry) => entry.id === missionId)
+  const countsTowardBudget = roleCountsTowardBudget(role, shapeFor(mission?.kind))
+  if (countsTowardBudget && remaining.length >= max) {
     throw new TowerToolError(
       'worker-limit',
       'live worker limit reached (' + max + '); stop a worker with tower_interrupt or raise spawn.maxLiveWorkers',

package/app/spawn-support.js

@@ -1,7 +1,55 @@
 // tower_spawn support (#56 P3c): briefing assembly, agent options, and the
 // wait/result settling path. Split out of tools/spawn.js; no I/O of its own.
+import { shapeFor } from '../domain/shapes/index.js'
+import { roleBriefingKind, rolePlacement } from '../domain/roles.js'
 import { workerBriefing, reviewerBriefing } from './briefing.js'
 
+/**
+ * Resolve where a spawn runs (#149 W3). A worker gets the shape's provisioning
+ * (branch worktree, shared checkout, or detached survey sandbox); a reviewer
+ * gets a disposable detached checkout at the recorded branch tip, so the
+ * verdict is stamped with a commit instead of a live worktree HEAD.
+ * @param {any} tower
+ * @param {{ role: string, context: any, missionId: string, name: string, worktreeRoot?: string, includeDirtyBase?: boolean, instructions?: string }} input
+ */
+export async function provisionSpawnPlacement(tower, { role, context, missionId, name, worktreeRoot, includeDirtyBase, instructions }) {
+  // #149 W4: the role contract decides the placement; the shape supplies the
+  // mission provisioning facts it does not own.
+  const reviewCheckout = rolePlacement(role) === 'review-checkout'
+  const shape = shapeFor(context.mission.kind)
+  const provisioned = reviewCheckout
+    ? null
+    : await tower.provision({ missionId, worktreeRoot, includeDirtyBase: includeDirtyBase !== false })
+  const review = reviewCheckout
+    ? await tower.provisionReviewCheckout({ missionId, name, worktreeRoot })
+    : null
+  const mission = review ? review.mission : provisioned.mission
+  const worktree = review ? mission.worktree : provisioned.worktree
+  const cwd = review ? review.path : (provisioned.cwd ?? worktree.path)
+  const branch = worktree?.branch ?? null
+  // The briefing must describe the checkout that actually exists: a detached
+  // sandbox is recorded only after provision, so use the provisioned mission.
+  const briefing = buildSpawnBriefing({
+    role,
+    towerRoot: tower.root,
+    context: /** @type {any} */ ({ ...context, mission }),
+    worktree,
+    review,
+    instructions,
+  })
+  return {
+    mission,
+    worktree,
+    cwd,
+    branch,
+    review,
+    briefing,
+    provisioning: review ? 'review-checkout' : (provisioned.provisioning ?? shape.provisioning),
+    created: review ? true : provisioned.created,
+    sandbox: provisioned?.sandbox ?? null,
+  }
+}
+
 /**
  * @param {any} model
  */
@@ -14,25 +62,28 @@ export function buildAgentOptions(model) {
 }
 
 /**
- * @param {{ role: string, towerRoot: string, context: any, worktree: any, instructions: string | undefined }} input
+ * @param {{ role: string, towerRoot: string, context: any, worktree: any, review?: any, instructions: string | undefined }} input
  */
-export function buildSpawnBriefing({ role, towerRoot, context, worktree, instructions }) {
-  const mission = {
-    ...context.mission,
-    worktree: { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit },
-  }
+export function buildSpawnBriefing({ role, towerRoot, context, worktree, review = null, instructions }) {
+  // Only a shape that owns a worktree gets the git checkout projection; a survey
+  // reads the shared checkout and must not see a worktree record it does not own.
+  const shape = shapeFor(context.mission.kind)
+  const mission = shape.fields.worktree
+    ? { ...context.mission, worktree: { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit } }
+    : { ...context.mission }
   const briefing = {
     repoRoot: towerRoot,
     base: context.base,
     mission,
     deps: context.deps,
-    worktree,
+    worktree: worktree ?? null,
+    review,
     instructions,
     reviews: context.reviews,
     findings: context.findings,
     completionReport: context.completionReport,
   }
-  return role === 'worker' ? workerBriefing(briefing) : reviewerBriefing(briefing)
+  return roleBriefingKind(role) === 'reviewer' ? reviewerBriefing(briefing) : workerBriefing(briefing)
 }
 
 /**

package/app/spawn.js

@@ -96,6 +96,9 @@ export async function recordSpawn(tower, input) {
     const now = Date.now()
     const entry = recordSpawnEntry({
       roster: state.roster,
+      // The live-worker count resolves each roster row's kind, so the whole
+      // mission list is required: a survey row is not a build worker (#148).
+      missions: state.missions,
       mission,
       input,
       spawnTip,

package/app/teardown.js

@@ -21,6 +21,106 @@ import {
   teardownRemovedDecision,
 } from '../domain/integration/teardown.js'
 import { sweepArchive } from './archive.js'
+import { cleanupSandbox } from './sandbox.js'
+import { cleanupReviewCheckout } from './reviewCheckout.js'
+
+/**
+ * Disposable review checkouts (#149 W3). A reviewer works in a detached checkout
+ * at its recorded review commit and the checkout is removed when the verdict is
+ * recorded; a failed spawn or an interrupted reviewer leaves it behind, so
+ * teardown retries the bounded removal and clears the recorded path. A checkout
+ * whose reviewer is still active is kept. This runs before the worktree phase so
+ * its state revisions never invalidate the worktree claims.
+ * @param {any} tower
+ * @param {any} input
+ * @returns {Promise<{ decisions: any[], removed: string[] }>}
+ */
+async function teardownReviewCheckouts(tower, input) {
+  const state = await tower.load()
+  const exclude = new Set(input.exclude ?? [])
+  const decisions = []
+  const removed = []
+  for (const entry of state.roster ?? []) {
+    const checkout = typeof entry.reviewCheckout === 'string' ? entry.reviewCheckout : null
+    if (!checkout) continue
+    const row = { name: entry.name, missionId: entry.missionId ?? null, checkout }
+    if (exclude.has(entry.missionId)) {
+      decisions.push({ ...row, action: 'keep', reason: 'excluded' })
+      continue
+    }
+    if (entry.state === 'active') {
+      decisions.push({ ...row, action: 'keep', reason: 'reviewer is active' })
+      continue
+    }
+    if (input.dryRun === true) {
+      decisions.push({ ...row, action: 'remove', reason: 'eligible' })
+      continue
+    }
+    const outcome = await cleanupReviewCheckout(tower, { name: entry.name, missionId: entry.missionId })
+    if (!outcome || outcome.removal.ok) {
+      decisions.push({ ...row, action: 'removed', reason: outcome ? 'checkout was already gone' : 'checkout and record were already gone' })
+      removed.push(entry.name)
+      continue
+    }
+    decisions.push({
+      ...row,
+      action: 'keep',
+      reason: `checkout cleanup failed after ${outcome.removal.attempts} attempt(s): ${outcome.removal.error}`,
+    })
+  }
+  return { decisions, removed }
+}
+
+/**
+ * Disposable detached survey sandboxes (#148 W2). A terminal survey may still
+ * carry a sandbox after a failed cleanup; teardown retries with the same bounded
+ * removal as completion. Run before the worktree phase so its state revisions
+ * never invalidate the worktree claims.
+ * @param {any} tower
+ * @param {any} input
+ * @returns {Promise<{ decisions: any[], removed: string[] }>}
+ */
+async function teardownSandboxes(tower, input) {
+  const state = await tower.load()
+  const activity = input.activity ?? {}
+  const exclude = new Set(input.exclude ?? [])
+  const decisions = []
+  const removed = []
+  for (const mission of state.missions) {
+    const sandbox = typeof /** @type {any} */ (mission).sandbox === 'string' ? /** @type {any} */ (mission).sandbox : null
+    if (!sandbox) continue
+    if (exclude.has(mission.id)) {
+      decisions.push({ missionId: mission.id, action: 'keep', sandbox, reason: 'excluded' })
+      continue
+    }
+    if (hasLiveAgent(state, mission.id, activity)) {
+      decisions.push({ missionId: mission.id, action: 'keep', sandbox, reason: 'live agent' })
+      continue
+    }
+    if (!['completed', 'abandoned'].includes(mission.status)) {
+      decisions.push({ missionId: mission.id, action: 'keep', sandbox, reason: `mission is ${mission.status}` })
+      continue
+    }
+    if (input.dryRun === true) {
+      decisions.push({ missionId: mission.id, action: 'remove', sandbox, reason: 'eligible' })
+      continue
+    }
+    const outcome = await cleanupSandbox(tower, mission.id)
+    if (!outcome) {
+      decisions.push({ missionId: mission.id, action: 'removed', sandbox, reason: 'sandbox was already gone' })
+      removed.push(mission.id)
+      continue
+    }
+    if (outcome.ok) removed.push(mission.id)
+    decisions.push({
+      missionId: mission.id,
+      action: outcome.ok ? 'removed' : 'keep',
+      sandbox,
+      ...(outcome.ok ? {} : { reason: `sandbox cleanup failed after ${outcome.attempts} attempt(s): ${outcome.error}` }),
+    })
+  }
+  return { decisions, removed }
+}
 
 /**
  * Phase 1 (#51): decide every keep/remove outcome without holding the state
@@ -87,8 +187,23 @@ async function claimRemoval(tower, candidate, expectedRevision, input) {
 }
 
 export async function teardown(tower, input) {
+  // Sandbox cleanup runs first: it owns its own short locks and revisions, so
+  // the worktree prepare/act/commit phases below see a stable revision.
+  // Review checkout cleanup first: it owns its own short locks and revisions, so
+  // the worktree prepare/act/commit phases below see a stable revision.
+  const reviews = await teardownReviewCheckouts(tower, input)
+  const sandboxes = await teardownSandboxes(tower, input)
   const prepared = await prepareTeardown(tower, input)
-  if (prepared.dryRun) return { ok: true, dryRun: true, removed: [], decisions: prepared.decisions }
+  if (prepared.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      removed: [],
+      decisions: [...reviews.decisions, ...sandboxes.decisions, ...prepared.decisions],
+      reviewCheckoutsRemoved: [],
+      sandboxesRemoved: [],
+    }
+  }
 
   const removed = []
   let expectedRevision = prepared.stateRevision
@@ -197,7 +312,9 @@ export async function teardown(tower, input) {
     ok: true,
     dryRun: false,
     removed,
-    decisions: prepared.decisions,
+    decisions: [...reviews.decisions, ...sandboxes.decisions, ...prepared.decisions],
+    reviewCheckoutsRemoved: reviews.removed,
+    sandboxesRemoved: sandboxes.removed,
     archived: archive.archived,
     ...(archive.error ? { archiveError: archive.error } : {}),
   }