dsh-tower 2.6.0 → 2.7.0

package/app/review.js

@@ -3,11 +3,11 @@ 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,
@@ -19,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
@@ -45,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 })
@@ -90,68 +120,74 @@ export async function submitReview(tower, input) {
   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

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

@@ -3,6 +3,8 @@
 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.
@@ -34,26 +36,15 @@ export function resolveRosterName({ role, missionId, requested, roster }) {
  * @param {{ role: string, context: any, config?: any }} input
  */
 export function assertSpawnableMission({ role, context, config }) {
-  if (role === 'reviewer') {
-    if (reviewUnavailable(config)) {
-      throw new TowerToolError(
-        'review-disabled',
-        'review.mode is off, so review is unavailable and a reviewer cannot be spawned',
-      )
-    }
-    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`,
-    )
-  }
+  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)
 }
 
 /**
@@ -83,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(
@@ -128,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',