dsh-tower 2.5.0 → 2.7.0

package/app/provision.js

@@ -1,20 +1,30 @@
 // `tower_provision` use case, split into three phases (#51):
 //
 //   prepare — mission/base commit/worktree identity, all lock-free.
-//   act     — revalidate the prepared revision, then `git worktree add` (and
-//             its supporting exclude/canonical reads) under the git mutex.
+//   act     — revalidate the prepared revision, then the git mutation (and its
+//             supporting exclude/canonical reads) under the git mutex.
 //   commit  — one short state lock revalidates the revision and that the
 //             mission still has no worktree, then records it. A rejected
-//             commit rolls the created worktree/branch back outside the lock.
+//             commit rolls the created worktree/branch (or survey sandbox)
+//             back outside the lock.
+//
+// #148 W2: a survey resolves its placement through its shape. `shared` keeps the
+// old no-provisioning path; `detached` creates a disposable detached worktree at
+// the recorded readCommit (no branch, no baseCommit, never merged).
 import path from 'node:path'
 import { validateState } from '../domain/state.js'
 import { TowerToolError } from '../domain/errors.js'
+import { provisioningFor } from '../domain/shapes/index.js'
 import {
   baseCommitChoice,
   createdWorktreeResult,
+  detachedSandboxResult,
   existingWorktreeResult,
   hasMissionId,
   provisionActivityText,
+  sandboxActivityText,
+  sandboxPath,
+  sharedProvisionResult,
   worktreeBranch,
   worktreePath,
   worktreeRecord,
@@ -25,11 +35,76 @@ function fail(message, code = 'invalid-argument') {
   throw new TowerToolError(code, message)
 }
 
-/** Phase 1 of `Tower.provision` (#51). An existing worktree returns here. */
+/**
+ * Resolve the parent directory for mission checkouts and refuse an unsafe one.
+ * @param {any} tower
+ * @param {any} input
+ * @returns {string}
+ */
+export function resolveCheckoutRoot(tower, input) {
+  const root = worktreeRoot({
+    worktreeRoot: input.worktreeRoot,
+    configuredRoot: tower.config.worktrees.root,
+    repoRoot: tower.root,
+    commonDirHash: tower.deps.ids.shortHash(tower.commonDir),
+  })
+  if (!path.isAbsolute(root)) fail('worktreeRoot must be an absolute path')
+  tower.assertOutside(root)
+  return root
+}
+
+/**
+ * True when `mission.sandbox` is a worktree registered with git and still at the
+ * recorded readCommit. A recorded path that git no longer knows is treated as
+ * gone so a failed cleanup does not wedge a re-provision; a registered sandbox
+ * whose HEAD moved is a refusal (its contents are the worker's work, not ours
+ * to discard silently).
+ * @param {any} tower
+ * @param {import('../types/index.js').Mission} mission
+ * @returns {Promise<boolean>}
+ */
+async function sandboxIsCurrent(tower, mission) {
+  const sandbox = /** @type {any} */ (mission).sandbox
+  if (typeof sandbox !== 'string' || sandbox.length === 0) return false
+  const entries = await tower.deps.vcs.listWorktrees(tower.root)
+  const registered = entries.some((entry) => path.resolve(entry.path) === path.resolve(sandbox))
+  if (!registered) return false
+  const head = await tower.revParse(sandbox, 'HEAD')
+  if (head !== mission.readCommit) {
+    fail(
+      `detached sandbox ${sandbox} is at ${String(head).slice(0, 12)}, not the recorded readCommit ${String(mission.readCommit).slice(0, 12)}; inspect it or remove it before provisioning again`,
+    )
+  }
+  return true
+}
+
+/** Phase 1 of `Tower.provision` (#51). An existing checkout returns here. */
 async function prepareProvision(tower, input) {
   const state = await tower.load()
   const mission = state.missions.find((entry) => entry.id === input.missionId)
   if (!mission) fail(`unknown mission "${input.missionId}"`, 'mission-not-found')
+  const provisioning = provisioningFor(mission.kind, tower.config, mission)
+  // A shared-checkout shape reads one commit in the main checkout: no branch,
+  // no directory, no recorded worktree (#148 D1/D2).
+  if (provisioning === 'shared') {
+    return { early: sharedProvisionResult(mission, tower.root) }
+  }
+  // #148 W2: a detached survey owns a disposable checkout, not a mission
+  // branch. The recorded readCommit is the only base it has.
+  if (provisioning === 'detached') {
+    const readCommit = mission.readCommit
+    if (typeof readCommit !== 'string' || readCommit.length === 0) {
+      fail('a detached survey needs the commit it reads (readCommit); re-plan the survey from a resolved base', 'invalid-argument')
+    }
+    if (await sandboxIsCurrent(tower, mission)) {
+      return { early: detachedSandboxResult(mission, /** @type {string} */ (mission.sandbox), false) }
+    }
+    const root = resolveCheckoutRoot(tower, input)
+    await tower.deps.store.ensureDir(root)
+    const wtPath = sandboxPath(root, mission.id)
+    if (await tower.deps.store.exists(wtPath)) fail(`sandbox path already exists: ${wtPath}`)
+    return { stateRevision: state.revision, missionId: mission.id, mode: 'detached', readCommit, wtPath }
+  }
   if (mission.worktree) {
     await tower.assertWorktree(mission.worktree)
     return { early: existingWorktreeResult(mission, mission.worktree) }
@@ -47,14 +122,7 @@ async function prepareProvision(tower, input) {
   })
   const baseCommit = 'commit' in choice ? choice.commit : await tower.revParse(tower.root, state.base)
   const branch = worktreeBranch(mission)
-  const root = worktreeRoot({
-    worktreeRoot: input.worktreeRoot,
-    configuredRoot: tower.config.worktrees.root,
-    repoRoot: tower.root,
-    commonDirHash: tower.deps.ids.shortHash(tower.commonDir),
-  })
-  if (!path.isAbsolute(root)) fail('worktreeRoot must be an absolute path')
-  tower.assertOutside(root)
+  const root = resolveCheckoutRoot(tower, input)
   await tower.deps.store.ensureDir(root)
   const wtPath = worktreePath(root, mission.id)
   if (await tower.deps.store.exists(wtPath)) fail(`worktree path already exists: ${wtPath}`)
@@ -64,7 +132,7 @@ async function prepareProvision(tower, input) {
   return { stateRevision: state.revision, missionId: mission.id, baseCommit, branch, wtPath }
 }
 
-/** Phase 2 of `Tower.provision` (#51): no state lock, worktree add under the git mutex. */
+/** Phase 2 of `Tower.provision` (#51): no state lock, git work under the mutex. */
 async function actProvision(tower, prepared) {
   return tower.deps.store.withGitLock(tower.paths, async () => {
     let fresh
@@ -78,6 +146,17 @@ async function actProvision(tower, prepared) {
     }
     const mission = fresh.missions.find((entry) => entry.id === prepared.missionId)
     if (!mission) return { phase: 'missing' }
+    if (prepared.mode === 'detached') {
+      if (await sandboxIsCurrent(tower, mission)) {
+        return { phase: 'existing-sandbox', mission, sandbox: /** @type {any} */ (mission).sandbox }
+      }
+      if (await tower.deps.store.exists(prepared.wtPath)) fail(`sandbox path already exists: ${prepared.wtPath}`)
+      // `--detach` creates no branch: the sandbox is a read-only commit checkout
+      // that the agent may dirty, and it never participates in merge/stale-base.
+      await tower.git(tower.root, ['worktree', 'add', '--detach', prepared.wtPath, prepared.readCommit])
+      await tower.ensureExcluded(prepared.wtPath)
+      return { phase: 'created-sandbox', sandbox: prepared.wtPath }
+    }
     if (mission.worktree) {
       await tower.assertWorktree(mission.worktree)
       return { phase: 'existing', mission, worktree: mission.worktree }
@@ -99,7 +178,7 @@ async function actProvision(tower, prepared) {
   }, tower.gitMutexOptions({ phase: 'provision' }))
 }
 
-/** Phase 3 of `Tower.provision` (#51): record the worktree under a short lock. */
+/** Phase 3 of `Tower.provision` (#51): record the checkout under a short lock. */
 async function commitProvision(tower, prepared, acted) {
   return tower.deps.store.withLock(tower.paths, async () => {
     const state = await tower.load()
@@ -107,9 +186,30 @@ async function commitProvision(tower, prepared, acted) {
     if (!mission) throw new TowerToolError('mission-not-found', `unknown mission "${prepared.missionId}"`)
     // Revision revalidation: the plan was built from prepared.stateRevision.
     if (state.revision !== prepared.stateRevision) return { phase: 'stale', revision: state.revision }
+    const now = Date.now()
+    if (prepared.mode === 'detached') {
+      // Never overwrite a sandbox another writer recorded while git ran.
+      if (mission.sandbox) return { phase: 'existing-sandbox', mission, sandbox: mission.sandbox }
+      mission.sandbox = acted.sandbox
+      mission.updatedAt = now
+      state.revision += 1
+      state.updatedAt = now
+      try {
+        validateState(state, tower.paths.state)
+        await tower.deps.store.writeJsonAtomic(tower.paths.state, state)
+      } catch (error) {
+        return { phase: 'persist-error', error }
+      }
+      await tower.deps.store.appendJsonl(tower.paths.activity, {
+        at: now,
+        type: 'sandbox',
+        missionId: prepared.missionId,
+        text: sandboxActivityText(acted.sandbox, prepared.readCommit),
+      }).catch(() => {})
+      return { phase: 'committed-sandbox', mission, sandbox: acted.sandbox }
+    }
     // Never overwrite a worktree another writer recorded while git ran.
     if (mission.worktree) return { phase: 'existing', mission, worktree: mission.worktree }
-    const now = acted.worktree.createdAt
     mission.worktree = acted.worktree
     mission.baseCommit = prepared.baseCommit
     mission.updatedAt = now
@@ -131,11 +231,13 @@ async function commitProvision(tower, prepared, acted) {
   })
 }
 
-/** Undo a created worktree/branch outside the state lock (git mutex only). */
+/** Undo a created checkout outside the state lock (git mutex only). */
 async function rollbackProvision(tower, prepared) {
   await tower.deps.store.withGitLock(tower.paths, async () => {
     await tower.git(tower.root, ['worktree', 'remove', '--force', prepared.wtPath]).catch(() => {})
-    await tower.git(tower.root, ['branch', '-D', prepared.branch]).catch(() => {})
+    if (prepared.mode !== 'detached' && prepared.branch) {
+      await tower.git(tower.root, ['branch', '-D', prepared.branch]).catch(() => {})
+    }
   }, tower.gitMutexOptions({ phase: 'provision' }))
 }
 
@@ -150,6 +252,9 @@ export async function provision(tower, input = {}) {
 
   const acted = await actProvision(tower, prepared)
   if (acted.phase === 'existing') return existingWorktreeResult(acted.mission, acted.worktree)
+  if (acted.phase === 'existing-sandbox') {
+    return detachedSandboxResult(acted.mission, acted.sandbox, false)
+  }
   if (acted.phase === 'missing') fail(`unknown mission "${prepared.missionId}"`, 'mission-not-found')
   if (acted.phase === 'stale') {
     throw new TowerToolError(
@@ -162,8 +267,8 @@ export async function provision(tower, input = {}) {
   try {
     committed = await commitProvision(tower, prepared, acted)
   } catch (error) {
-    // The worktree already exists. A commit that cannot even take the state
-    // lock must not leave the mission wedged with an unrecorded worktree.
+    // The checkout already exists. A commit that cannot even take the state
+    // lock must not leave the mission wedged with an unrecorded checkout.
     await rollbackProvision(tower, prepared)
     throw error
   }
@@ -174,18 +279,24 @@ export async function provision(tower, input = {}) {
       `tower state changed while the worktree was being created (${prepared.stateRevision} -> ${committed.revision}); the new worktree was rolled back — retry`,
     )
   }
-  if (committed.phase === 'existing') {
-    // Another writer recorded a worktree for this mission while git ran; the
+  if (committed.phase === 'existing' || committed.phase === 'existing-sandbox') {
+    // Another writer recorded a checkout for this mission while git ran; the
     // one created here is orphaned, so remove it and report the recorded one.
     await rollbackProvision(tower, prepared)
+    if (committed.phase === 'existing-sandbox') {
+      return detachedSandboxResult(committed.mission, committed.sandbox, false)
+    }
     await tower.assertWorktree(committed.worktree)
     return existingWorktreeResult(committed.mission, committed.worktree)
   }
   if (committed.phase === 'persist-error') {
     // Preserve the single-phase rollback: a failed state write must not leave
-    // an untracked worktree/branch behind.
+    // an untracked worktree/branch (or survey sandbox) behind.
     await rollbackProvision(tower, prepared)
     throw committed.error
   }
+  if (committed.phase === 'committed-sandbox') {
+    return detachedSandboxResult(committed.mission, committed.sandbox, true)
+  }
   return createdWorktreeResult(committed.mission, committed.worktree)
 }

package/app/read.js

@@ -1,5 +1,7 @@
 // Read-only dashboard/detail use cases.
 import { TowerToolError } from '../domain/errors.js'
+import { isReviewerRole } from '../domain/roles.js'
+import { assertActionSupported } from '../domain/shapes/index.js'
 import { diffView, missionDetailView, statusView } from '../domain/read/views.js'
 import { archiveView, archivedSummary } from './archive.js'
 
@@ -7,6 +9,33 @@ function fail(message, code = 'invalid-argument') {
   throw new TowerToolError(code, message)
 }
 
+/**
+ * #149 W3: a reviewer diffs the commit recorded on its roster row — the same
+ * commit its verdict is stamped with — never the worker's live worktree HEAD.
+ * The checkout is only trusted while its HEAD still equals that commit.
+ * @returns {Promise<{ commit: string, cwd: string } | null>}
+ */
+async function reviewerBinding(tower, state, mission, actor) {
+  if (!actor || !isReviewerRole(actor.role) || !actor.agentId) return null
+  const row = (state.roster ?? []).find((entry) => entry.agentId === actor.agentId)
+  if (!row || typeof row.reviewCommit !== 'string' || row.reviewCommit.length === 0) {
+    fail(
+      `reviewer ${row?.name ?? actor.name} has no recorded review commit; spawn reviewers through tower_spawn so a verdict is bound to a commit`,
+    )
+  }
+  if (typeof row.reviewCheckout === 'string' && row.reviewCheckout.length > 0) {
+    const head = await tower.revParse(row.reviewCheckout, 'HEAD').catch(() => null)
+    if (head !== row.reviewCommit) {
+      const where = head ? head.slice(0, 12) : 'a missing checkout'
+      fail(
+        `reviewer ${row.name}'s checkout is at ${where} instead of the recorded review commit ${row.reviewCommit.slice(0, 12)}; spawn a fresh reviewer`,
+      )
+    }
+    return { commit: row.reviewCommit, cwd: row.reviewCheckout }
+  }
+  return { commit: row.reviewCommit, cwd: mission.worktree.path }
+}
+
 /**
  * Full detail for one mission. A mission that was archived is reconstructed
  * from its year file, including the reviews, findings and activity that left
@@ -91,22 +120,26 @@ export async function diff(tower, input = {}) {
   const state = await tower.load()
   const mission = state.missions.find((entry) => entry.id === input.missionId)
   if (!mission) fail(`unknown mission "${input.missionId}"`, 'mission-not-found')
+  assertActionSupported(mission, 'diff')
   if (!mission.worktree) fail(`mission ${mission.id} has no worktree to diff`)
   await tower.assertWorktree(mission.worktree)
+  const binding = await reviewerBinding(tower, state, mission, input.actor)
+  const cwd = binding?.cwd ?? mission.worktree.path
   const baseTip = await tower.revParse(tower.root, state.base)
-  const branchTip = await tower.revParse(mission.worktree.path, 'HEAD')
-  const mergeBase = (await tower.git(mission.worktree.path, ['merge-base', baseTip, branchTip])).trim()
-  const files = (await tower.git(mission.worktree.path, ['diff', '--name-status', `${mergeBase}..${branchTip}`]))
+  const branchTip = binding?.commit ?? (await tower.branchTip(mission))
+  const mergeBase = (await tower.git(cwd, ['merge-base', baseTip, branchTip])).trim()
+  const files = (await tower.git(cwd, ['diff', '--name-status', `${mergeBase}..${branchTip}`]))
     .split('\n')
     .filter(Boolean)
-  const commits = (await tower.git(mission.worktree.path, ['log', '--oneline', `${mergeBase}..${branchTip}`]))
+  const commits = (await tower.git(cwd, ['log', '--oneline', `${mergeBase}..${branchTip}`]))
     .split('\n')
     .filter(Boolean)
-  const fullPatch = await tower.git(mission.worktree.path, ['diff', `${mergeBase}..${branchTip}`])
+  const fullPatch = await tower.git(cwd, ['diff', `${mergeBase}..${branchTip}`])
   return diffView({
     mission,
     baseTip,
     branchTip,
+    reviewedCommit: binding?.commit ?? null,
     mergeBase,
     files,
     commits,

package/app/rebase.js

@@ -8,6 +8,8 @@
 // reviewed-tip waiver semantics the merge gate depends on.
 import { validateState } from '../domain/state.js'
 import { TowerToolError } from '../domain/errors.js'
+import { assertActionSupported } from '../domain/shapes/index.js'
+import { markBlocked, resolveBlockers } from '../domain/missions/lifecycle.js'
 import { liveAgentFor } from '../domain/integration/liveness.js'
 import {
   alreadyMergedRebaseResult,
@@ -17,6 +19,7 @@ import {
   classifyRebaseIntent,
   clearedRebaseIntentActivityText,
   dirtyWorktreeResult,
+  isRebaseConflictBlocker,
   malformedRebaseIntent,
   rebaseActivityText,
   rebaseConflictNote,
@@ -55,6 +58,7 @@ async function prepareRebase(tower, input) {
   const state = await tower.load()
   const mission = findMission(state, input.missionId)
   if (!mission) fail(`unknown mission "${input.missionId}"`)
+  assertActionSupported(mission, 'rebase')
   if (!mission.worktree) fail(`mission ${mission.id} has no worktree to rebase`)
   const activity = input.activity ?? {}
   const busy = liveAgentFor(state, mission.id, activity)
@@ -65,7 +69,7 @@ async function prepareRebase(tower, input) {
   if (!(await tower.isClean(mission.worktree.path))) {
     return { early: dirtyWorktreeResult(mission.worktree.path) }
   }
-  const oldTip = await tower.revParse(mission.worktree.path, 'HEAD')
+  const oldTip = await tower.branchTip(mission)
   const baseTip = await tower.revParse(tower.root, state.base)
   if (await tower.isAncestor(tower.root, oldTip, baseTip)) {
     // The branch is already contained in the base (manual merge, crashed
@@ -161,7 +165,7 @@ async function reconcileRebaseIntent(tower) {
       if (inspection.action === 'record' && mission) {
         const tip = /** @type {string} */ (inspection.tip)
         mission.rebase = { at: now, oldTip: intent.oldTip, newTip: tip, baseTip: intent.baseTip }
-        if (mission.status === 'blocked') mission.status = 'active'
+        resolveBlockers(mission, isRebaseConflictBlocker, now)
         mission.notes.push(rebaseReconcileNote({ oldTip: intent.oldTip, newTip: tip, baseTip: intent.baseTip }))
         mission.updatedAt = now
       }
@@ -221,7 +225,7 @@ export async function rebase(tower, input) {
   // Phase 2 (#51): the long git work runs under the git lock and never under
   // the state lock. Re-verify the snapshot right before rewriting the branch.
   const outcome = await tower.deps.store.withGitLock(tower.paths, async () => {
-    const currentTip = await tower.revParse(worktree.path, 'HEAD')
+    const currentTip = await tower.revParse(tower.root, `refs/heads/${worktree.branch}`)
     const currentBase = await tower.revParse(tower.root, prepared.base)
     if (rebaseTipsMoved({ oldTip: prepared.oldTip, baseTip: prepared.baseTip, currentTip, currentBase })) {
       return {
@@ -240,7 +244,7 @@ export async function rebase(tower, input) {
       await tower.git(worktree.path, ['rebase', '--abort']).catch(() => {})
       return { phase: 'conflict', detail: String(error?.message ?? error) }
     }
-    const newTip = await tower.revParse(worktree.path, 'HEAD')
+    const newTip = await tower.revParse(tower.root, `refs/heads/${worktree.branch}`)
     return { phase: 'done', newTip }
   }, tower.gitMutexOptions({ phase: 'rebase' }))
 
@@ -266,9 +270,7 @@ export async function rebase(tower, input) {
 
     if (outcome.phase === 'conflict') {
       delete state.rebaseIntent
-      mission.status = 'blocked'
-      mission.blockers.push(rebaseConflictNote(prepared.base, prepared.baseTip))
-      mission.updatedAt = now
+      markBlocked(mission, rebaseConflictNote(prepared.base, prepared.baseTip), now)
       state.revision += 1
       state.updatedAt = now
       validateState(state, tower.paths.state)
@@ -280,7 +282,7 @@ export async function rebase(tower, input) {
     const { newTip } = outcome
     delete state.rebaseIntent
     mission.rebase = { at: now, oldTip: prepared.oldTip, newTip, baseTip: prepared.baseTip }
-    if (mission.status === 'blocked') mission.status = 'active'
+    resolveBlockers(mission, isRebaseConflictBlocker, now)
     mission.notes.push(
       rebaseSuccessNote({ oldTip: prepared.oldTip, newTip, baseTip: prepared.baseTip }),
     )

package/app/review.js

@@ -2,11 +2,12 @@
 import { sweepArchive } from './archive.js'
 import { validateState } from '../domain/state.js'
 import { TowerToolError } from '../domain/errors.js'
+import { reviewUnavailable } from '../domain/integration/review.js'
+import { cleanupReviewCheckout } from './reviewCheckout.js'
 import {
   assertReviewableMission,
   resolveReviewActor,
   normalizeReviewVerdict,
-  assertReviewerSpawnTip,
   reviewAdmission,
   reviewRound,
   reviewOutcome,
@@ -18,6 +19,37 @@ function fail(message, code = 'invalid-argument') {
   throw new TowerToolError(code, message)
 }
 
+/**
+ * The commit a verdict is stamped with (#149 W3).
+ *
+ * A spawned reviewer is bound to the review commit recorded on its roster row
+ * and reads it in a disposable detached checkout; that checkout must still be
+ * at the recorded commit, so a verdict can never review a moving target. The
+ * tower's break-glass review has no checkout and stamps the current branch tip.
+ * @param {any} tower
+ * @param {{ mission: any, caller: any, reviewerRole: string }} input
+ * @returns {Promise<string>}
+ */
+async function reviewCommitFor(tower, { mission, caller, reviewerRole }) {
+  if (reviewerRole === 'tower') return tower.branchTip(mission)
+  const recorded = caller?.reviewCommit
+  if (typeof recorded !== 'string' || recorded.length === 0) {
+    fail(
+      `reviewer ${caller?.name ?? '?'} has no recorded review commit; spawn reviewers through tower_spawn (a verdict is stamped with a commit, not a live branch tip)`,
+    )
+  }
+  if (typeof caller.reviewCheckout === 'string' && caller.reviewCheckout.length > 0) {
+    const head = await tower.revParse(caller.reviewCheckout, 'HEAD').catch(() => null)
+    if (head !== recorded) {
+      const where = head ? head.slice(0, 12) : 'a missing checkout'
+      fail(
+        `reviewer ${caller.name}'s checkout is at ${where} instead of the recorded review commit ${recorded.slice(0, 12)}; spawn a fresh reviewer`,
+      )
+    }
+  }
+  return recorded
+}
+
 /**
  * Phase 1 (#51): load state and capture everything the review needs — actor
  * checks, worktree ownership, branch tip, and round counters — without holding
@@ -44,9 +76,8 @@ async function prepareReview(tower, input) {
   const verdict = normalizeReviewVerdict(input)
 
   await tower.assertWorktree(mission.worktree)
-  const tip = await tower.revParse(mission.worktree.path, 'HEAD')
+  const tip = await reviewCommitFor(tower, { mission, caller, reviewerRole })
   const branch = mission.worktree.branch
-  assertReviewerSpawnTip(caller, tip)
   // #108: a later route may append to the round that returned the mission to
   // active, but only for the tip that round reviewed.
   const admission = reviewAdmission({ mission, reviews: state.reviews, branch, tip })
@@ -78,73 +109,85 @@ async function prepareReview(tower, input) {
 }
 
 export async function submitReview(tower, input) {
+  // #M39: `review.mode:off` means review is intentionally unavailable. The tool
+  // is not registered in that profile, but the repository layer can also turn it
+  // off, so the app layer refuses before any state is read.
+  if (reviewUnavailable(tower.config)) {
+    throw new TowerToolError('review-disabled', 'review.mode is off, so tower_review cannot record a verdict')
+  }
   // Two-phase (#51): the lock is held only for the state reload, revision
   // revalidation, and write; every git call happens in prepareReview.
   for (let attempt = 0; attempt < 2; attempt += 1) {
     const prepared = await prepareReview(tower, input)
     try {
-      return await tower.deps.store.withLock(tower.paths, async () => {
-    const state = await tower.load()
-    if (state.revision !== prepared.stateRevision) {
-      throw new TowerToolError('stale-base', 'tower state changed while the review was being prepared; retry')
-    }
-    const mission = state.missions.find((entry) => entry.id === input.missionId)
-    if (!mission) fail(`unknown mission "${input.missionId}"`)
+      const result = await tower.deps.store.withLock(tower.paths, async () => {
+        const state = await tower.load()
+        if (state.revision !== prepared.stateRevision) {
+          throw new TowerToolError('stale-base', 'tower state changed while the review was being prepared; retry')
+        }
+        const mission = state.missions.find((entry) => entry.id === input.missionId)
+        if (!mission) fail(`unknown mission "${input.missionId}"`)
 
-    const now = Date.now()
-    const seq = (state.reviewSeq ?? 0) + 1
-    state.reviewSeq = seq
-    const review = reviewRecord({
-      seq,
-      missionId: mission.id,
-      branch: prepared.branch,
-      tip: prepared.tip,
-      verdict: {
-        status: prepared.status,
-        merge: prepared.merge,
-        findings: prepared.findings,
-        checks: prepared.checks,
-        decision: prepared.decision,
-      },
-      reviewerName: prepared.reviewerName,
-      reviewerRole: prepared.reviewerRole,
-      round: prepared.round,
-      now,
-      breakGlassReason: prepared.breakGlassReason,
-    })
-    if (!Array.isArray(state.reviews)) state.reviews = []
-    state.reviews.push(review)
+        const now = Date.now()
+        const seq = (state.reviewSeq ?? 0) + 1
+        state.reviewSeq = seq
+        const review = reviewRecord({
+          seq,
+          missionId: mission.id,
+          branch: prepared.branch,
+          tip: prepared.tip,
+          verdict: {
+            status: prepared.status,
+            merge: prepared.merge,
+            findings: prepared.findings,
+            checks: prepared.checks,
+            decision: prepared.decision,
+          },
+          reviewerName: prepared.reviewerName,
+          reviewerRole: prepared.reviewerRole,
+          round: prepared.round,
+          now,
+          breakGlassReason: prepared.breakGlassReason,
+        })
+        if (!Array.isArray(state.reviews)) state.reviews = []
+        state.reviews.push(review)
 
-    const outcome = reviewOutcome({
-      status: prepared.status,
-      merge: prepared.merge,
-      round: prepared.round,
-      reviewerName: prepared.reviewerName,
-      appended: prepared.appended,
-    })
-    const applied = applyReviewOutcome({ mission, outcome, now })
-    await sweepArchive(tower, state, { now })
-    state.revision += 1
-    state.updatedAt = now
+        const outcome = reviewOutcome({
+          status: prepared.status,
+          merge: prepared.merge,
+          round: prepared.round,
+          reviewerName: prepared.reviewerName,
+          appended: prepared.appended,
+        })
+        const applied = applyReviewOutcome({ mission, outcome, now })
+        await sweepArchive(tower, state, { now })
+        state.revision += 1
+        state.updatedAt = now
 
-    validateState(state, tower.paths.state)
-    await tower.deps.store.writeJsonAtomic(tower.paths.state, state)
-    await tower.deps.store.appendJsonl(tower.paths.activity, {
-      at: now,
-      type: 'review',
-      missionId: mission.id,
-      text: `round ${prepared.round} ${prepared.reviewerName}: ${prepared.status} / ${prepared.merge} @ ${prepared.tip.slice(0, 12)}`,
-    })
-    tower.emitEvents(applied.events, { revision: state.revision, at: now })
-    return {
-      review,
-      branchTip: prepared.tip,
-      missionStatus: mission.status,
-      round: prepared.round,
-      appended: prepared.appended,
-      reviewerRounds: prepared.reviewerRounds + 1,
-    }
+        validateState(state, tower.paths.state)
+        await tower.deps.store.writeJsonAtomic(tower.paths.state, state)
+        await tower.deps.store.appendJsonl(tower.paths.activity, {
+          at: now,
+          type: 'review',
+          missionId: mission.id,
+          text: `round ${prepared.round} ${prepared.reviewerName}: ${prepared.status} / ${prepared.merge} @ ${prepared.tip.slice(0, 12)}`,
+        })
+        tower.emitEvents(applied.events, { revision: state.revision, at: now })
+        return {
+          review,
+          branchTip: prepared.tip,
+          missionStatus: mission.status,
+          round: prepared.round,
+          appended: prepared.appended,
+          reviewerRounds: prepared.reviewerRounds + 1,
+        }
       })
+      // The verdict is recorded, so the reviewer's evidence checkout has served
+      // its purpose. Removal is advisory: a failed cleanup is retried by teardown.
+      if (prepared.reviewerRole === 'reviewer') {
+        await cleanupReviewCheckout(tower, { name: prepared.reviewerName, missionId: prepared.missionId }).catch(() => {})
+      }
+      return result
     } catch (error) {
       if (error.code === 'stale-base' && attempt === 0) continue
       throw error