dsh-tower 1.2.0 → 2.0.0

package/lib/tower.js

@@ -17,17 +17,21 @@ import {
   isAncestor,
   tryGit,
 } from './git.js'
+import { validateCreate as validateBatchCreate, validateClose as validateBatchClose, summarize as summarizeBatch } from './batch.js'
+import { assertOwnership, canonicalPath } from './worktreeOwnership.js'
 import {
   pathsFor,
   exists,
   ensureDir,
   readJson,
   writeJsonAtomic,
+  renameWithRetry,
   appendJsonl,
   readActivityTail,
   withLock,
   shortHash,
 } from './store.js'
+import { runtimeConfig, resolveRepoConfig } from './config.js'
 
 export const SCHEMA_VERSION = 1
 export const MISSION_STATUSES = [
@@ -40,6 +44,14 @@ export const MISSION_STATUSES = [
   'abandoned',
 ]
 const TERMINAL = new Set(['merged', 'abandoned'])
+/** Roster states that no longer represent a live writer. `inactive` is an idle
+ * child whose turn finished: it must not block a new owner or consume a worker
+ * slot. `unknown` is deliberately NOT included because it cannot be proven
+ * stopped. */
+export const ROSTER_INACTIVE_STATES = ['retired', 'failed', 'interrupted', 'missing', 'stale', 'inactive']
+const ROSTER_INACTIVE = new Set(ROSTER_INACTIVE_STATES)
+const SNAPSHOT_REF_PREFIX = 'refs/tower/snapshot/'
+const PAUSE_CAUSES = ['user', 'failure', 'resource', 'dependency']
 const TRANSITIONS = {
   planned: ['active', 'abandoned'],
   active: ['completed', 'blocked', 'paused', 'abandoned'],
@@ -62,14 +74,24 @@ function slugify(title) {
 
 export const FINDING_TYPES = ['bug', 'improve', 'vuln', 'idea']
 export const FINDING_SEVERITIES = ['low', 'medium', 'high', 'critical']
+export const FINDING_STATUSES = ['open', 'triaged', 'fixed', 'wontfix']
+export const FINDING_TRANSITIONS = {
+  open: ['triaged', 'fixed', 'wontfix'],
+  triaged: ['open', 'fixed', 'wontfix'],
+  fixed: ['open'],
+  wontfix: ['open'],
+}
 export const MERGE_VERDICTS = ['merge', 'fix-then-merge', 'hold']
 const MAX_REVIEW_ROUNDS = 5
 const REVIEW_STATUS_RE = /^(clean|p1-\d+items|p2-\d+items)$/
 const DEFAULT_MERGE_TIMEOUT_MS = 15 * 60 * 1000
 const MERGE_MAX_BUFFER = 64 * 1024 * 1024
 
-function mergeTimeoutMs(value) {
-  if (value === undefined || value === null) return DEFAULT_MERGE_TIMEOUT_MS
+function mergeTimeoutMs(value, config) {
+  if (value === undefined || value === null) {
+    const configured = (config ?? runtimeConfig()).merge.timeoutMs
+    return Number.isInteger(configured) && configured >= 1000 ? configured : DEFAULT_MERGE_TIMEOUT_MS
+  }
   const ms = Number(value)
   if (!Number.isInteger(ms) || ms < 1000) fail('timeoutMs must be an integer of at least 1000 milliseconds')
   return ms
@@ -280,7 +302,26 @@ function normalizeMissionInput(input, index) {
     }
   }
   const context = typeof input.context === 'string' ? input.context.slice(0, 4096) : ''
-  return { title, kind, scope, tasks, deps, context }
+  const references = []
+  if (input.references !== undefined) {
+    if (!Array.isArray(input.references)) fail(`missions[${index}].references must be an array of pointers`)
+    if (input.references.length > 20) fail(`missions[${index}].references supports at most 20 pointers`)
+    for (const reference of input.references) {
+      if (typeof reference !== 'string' || reference.trim().length === 0) {
+        fail(`missions[${index}].references entries must be non-empty strings`)
+      }
+      if (!references.includes(reference.trim())) references.push(reference.trim())
+    }
+  }
+  const reviewPolicy = input.reviewPolicy === undefined ? 'required-clean' : input.reviewPolicy
+  if (!['required-clean', 'none'].includes(reviewPolicy)) {
+    fail(`missions[${index}].reviewPolicy must be "required-clean" or "none"`)
+  }
+  const reviewExemptionReason = typeof input.reviewExemptionReason === 'string' ? input.reviewExemptionReason.trim() : ''
+  if (reviewPolicy === 'none' && reviewExemptionReason.length === 0) {
+    fail(`missions[${index}].reviewPolicy "none" requires a non-empty reviewExemptionReason`)
+  }
+  return { title, kind, scope, tasks, deps, context, references, reviewPolicy, reviewExemptionReason }
 }
 
 function newMission(id, input, now) {
@@ -292,6 +333,9 @@ function newMission(id, input, now) {
     tasks: input.tasks,
     deps: input.deps,
     context: input.context,
+    references: input.references ?? [],
+    reviewPolicy: input.reviewPolicy ?? 'required-clean',
+    reviewExemptionReason: input.reviewExemptionReason ?? '',
     status: 'planned',
     owner: null,
     blockers: [],
@@ -320,6 +364,24 @@ export function validateState(state, statePath) {
     }
     if (!Array.isArray(mission.tasks)) fail(`mission ${mission.id} has no tasks array${where}`)
     if (!Array.isArray(mission.deps)) fail(`mission ${mission.id} has no deps array${where}`)
+    if (mission.references !== undefined && !Array.isArray(mission.references)) {
+      fail(`mission ${mission.id} has no references array${where}`)
+    }
+    if (mission.reviewPolicy !== undefined && !['required-clean', 'none'].includes(mission.reviewPolicy)) {
+      fail(`mission ${mission.id} has unknown reviewPolicy ${mission.reviewPolicy}${where}`)
+    }
+    if (mission.reviewPolicy === 'none' && !String(mission.reviewExemptionReason ?? '').trim()) {
+      fail(`mission ${mission.id} has reviewPolicy none without a reason${where}`)
+    }
+    if (mission.testRuns !== undefined && !Array.isArray(mission.testRuns)) {
+      fail(`mission ${mission.id} has no testRuns array${where}`)
+    }
+  }
+  for (const key of ['batches', 'legacySnapshots', 'legacyMaps', 'deliveries']) {
+    if (state[key] !== undefined && !Array.isArray(state[key])) fail(`tower state ${key} is not an array${where}`)
+  }
+  if (state.mergeIntent !== undefined && state.mergeIntent !== null && !isPlainObject(state.mergeIntent)) {
+    fail(`tower state mergeIntent is not an object${where}`)
   }
   if (state.roster !== undefined) {
     if (!Array.isArray(state.roster)) fail(`tower state roster is not an array${where}`)
@@ -354,6 +416,9 @@ export function validateState(state, statePath) {
       if (!finding || typeof finding.id !== 'string') fail(`invalid finding entry${where}`)
       if (ids.has(finding.id)) fail(`duplicate finding id ${finding.id}${where}`)
       ids.add(finding.id)
+      if (finding.status !== undefined && !FINDING_STATUSES.includes(finding.status)) {
+        fail(`finding ${finding.id} has unknown status ${finding.status}${where}`)
+      }
     }
   }
   if (state.reviews !== undefined) {
@@ -403,6 +468,9 @@ export function missionSummary(mission) {
     blockers: mission.blockers ?? [],
     tasks: taskCounts(mission.tasks ?? []),
     scopeGeneration: mission.scopeGeneration ?? 1,
+    ownerGeneration: mission.ownerGeneration ?? 0,
+    pauseCause: mission.pauseCause ?? null,
+    reviewPolicy: mission.reviewPolicy ?? 'required-clean',
     mergedCommit: mission.mergedCommit ?? null,
     mergedAt: mission.mergedAt ?? null,
     updatedAt: mission.updatedAt,
@@ -414,20 +482,96 @@ function fullMission(mission) {
     ...missionSummary(mission),
     tasks: (mission.tasks ?? []).map((task) => ({ ...task })),
     notes: mission.notes ?? [],
+    completionReport: mission.completionReport ?? null,
+    authorizationRef: mission.authorizationRef ?? null,
+    references: mission.references ?? [],
+    reviewPolicy: mission.reviewPolicy ?? 'required-clean',
+    reviewExemptionReason: mission.reviewExemptionReason ?? '',
+    testRuns: mission.testRuns ?? [],
+  }
+}
+
+function findingSummary(finding) {
+  return {
+    id: finding.id,
+    seq: finding.seq ?? null,
+    type: finding.type,
+    title: finding.title,
+    severity: finding.severity ?? null,
+    status: finding.status ?? 'open',
+    missionId: finding.missionId ?? null,
+    branch: finding.branch ?? null,
+    reportedBy: finding.reportedBy ?? null,
+    at: finding.at ?? null,
+    updatedAt: finding.updatedAt ?? null,
+    closedAt: finding.closedAt ?? null,
   }
 }
 
+function countFindings(findings) {
+  const counts = {}
+  for (const status of FINDING_STATUSES) counts[status] = 0
+  for (const finding of findings) {
+    const status = finding.status ?? 'open'
+    counts[status] = (counts[status] ?? 0) + 1
+  }
+  return counts
+}
+
+function liveWorkerEntry(state, missionId) {
+  return (state.roster ?? []).find(
+    (entry) => entry.missionId === missionId && entry.role === 'worker' && !ROSTER_INACTIVE.has(entry.state),
+  )
+}
+
+function workerEntries(state, missionId) {
+  return (state.roster ?? []).filter((entry) => entry.missionId === missionId && entry.role === 'worker')
+}
+
+function countLiveWorkers(state) {
+  return (state.roster ?? []).filter((entry) => entry.role === 'worker' && !ROSTER_INACTIVE.has(entry.state)).length
+}
+
+function normalizePauseCause(value) {
+  if (value === undefined || value === null || value === '') return 'user'
+  if (!PAUSE_CAUSES.includes(value)) fail(`pause_cause must be one of ${PAUSE_CAUSES.join('|')}`)
+  return value
+}
+
+function normalizeChecks(checks) {
+  if (checks === undefined) return []
+  if (!Array.isArray(checks)) fail('checks must be an array')
+  if (checks.length > 20) fail('checks may contain at most 20 entries')
+  return checks.map((check, index) => {
+    if (!isPlainObject(check)) fail(`checks[${index}] must be an object`)
+    const name = typeof check.name === 'string' ? check.name.trim() : ''
+    if (!name) fail(`checks[${index}].name must be a non-empty string`)
+    const entry = { name }
+    if (typeof check.command === 'string' && check.command.trim()) entry.command = check.command.trim()
+    if (check.exitCode !== undefined && check.exitCode !== null) {
+      if (!Number.isInteger(check.exitCode)) fail(`checks[${index}].exitCode must be an integer`)
+      entry.exitCode = check.exitCode
+    }
+    if (typeof check.evidence === 'string' && check.evidence.trim()) entry.evidence = check.evidence.trim().slice(0, 4000)
+    return entry
+  })
+}
+
 export class Tower {
-  constructor(repo) {
+  constructor(repo, config) {
     this.root = repo.root
     this.commonDir = repo.commonDir
     this.branch = repo.branch
     this.paths = pathsFor(repo.commonDir)
+    // Effective config for this repository: code defaults < profile config <
+    // repo config file. Per-call tool arguments are applied by the caller.
+    this.config = config ?? { ...runtimeConfig(), configPath: null, repoConfigPresent: false }
   }
 
   static async open(repoRoot) {
     const repo = await resolveRepo(repoRoot)
-    return new Tower(repo)
+    const config = await resolveRepoConfig(repo)
+    return new Tower(repo, config)
   }
 
   async load() {
@@ -441,8 +585,52 @@ export class Tower {
   async init(input = {}) {
     await ensureDir(this.paths.dir)
     return withLock(this.paths, async () => {
+      const now = Date.now()
+      const dirty = !(await isClean(this.root))
+      const committed = await hasAnyCommit(this.root)
+      const resolveBase = async () => {
+        let base = typeof input.base === 'string' && input.base.trim() ? input.base.trim() : null
+        if (base) {
+          if (/^refs\//.test(base) || base.startsWith('origin/')) {
+            fail(`base must be a local branch name, not ${base}`)
+          }
+          if (committed && !(await localBranchExists(this.root, base))) {
+            fail(`base branch "${base}" does not exist locally`)
+          }
+          return base
+        }
+        base = this.branch
+        if (!base && !committed) base = 'main'
+        if (!base) fail('repository is in detached HEAD; pass an explicit local base branch')
+        return base
+      }
+
       if (await exists(this.paths.state)) {
         const state = await this.load()
+        let reanchored = false
+        if (input.reanchor === true) {
+          const active = state.missions.filter((mission) => !TERMINAL.has(mission.status))
+          if (active.length > 0) {
+            fail(`cannot reanchor base while ${active.length} mission(s) are not merged or abandoned`)
+          }
+          const base = await resolveBase()
+          if (base !== state.base) {
+            const refs = (await tryGit(this.root, ['for-each-ref', '--format=%(refname)', SNAPSHOT_REF_PREFIX])) ?? ''
+            for (const ref of refs.split('\n').map((line) => line.trim()).filter(Boolean)) {
+              await git(this.root, ['update-ref', '-d', ref]).catch(() => {})
+            }
+            state.base = base
+            state.baseChangedAt = now
+            delete state.snapshotCommit
+            delete state.snapshotRef
+            reanchored = true
+            state.revision += 1
+            state.updatedAt = now
+            validateState(state, this.paths.state)
+            await writeJsonAtomic(this.paths.state, state)
+            await appendJsonl(this.paths.activity, { at: now, type: 'init', text: `base reanchored to ${base}` })
+          }
+        }
         return {
           created: false,
           repoRoot: state.repoRoot,
@@ -451,23 +639,24 @@ export class Tower {
           base: state.base,
           revision: state.revision,
           missions: state.missions.length,
+          reanchored,
+          dirty,
+          snapshotCommit: state.snapshotCommit ?? null,
         }
       }
 
-      const now = Date.now()
-      const committed = await hasAnyCommit(this.root)
-      let base = typeof input.base === 'string' && input.base.trim() ? input.base.trim() : null
-      if (base) {
-        if (/^refs\//.test(base) || base.startsWith('origin/')) {
-          fail(`base must be a local branch name, not ${base}`)
-        }
-        if (committed && !(await localBranchExists(this.root, base))) {
-          fail(`base branch "${base}" does not exist locally`)
+      const base = await resolveBase()
+      let snapshotCommit = null
+      let snapshotRef = null
+      if (input.snapshotDirty === true && dirty) {
+        snapshotCommit = ((await tryGit(this.root, ['stash', 'create'])) ?? '').trim() || null
+        if (!snapshotCommit) {
+          fail('snapshotDirty was requested but no snapshot commit could be created; commit or stash the working tree first')
         }
-      } else {
-        base = this.branch
-        if (!base && !committed) base = 'main'
-        if (!base) fail('repository is in detached HEAD; pass an explicit local base branch')
+        // A dangling commit can be pruned by git gc; keep a ref so the mission
+        // baseline stays reachable for the life of the state.
+        snapshotRef = `${SNAPSHOT_REF_PREFIX}${snapshotCommit}`
+        await git(this.root, ['update-ref', snapshotRef, snapshotCommit])
       }
 
       const state = {
@@ -478,11 +667,17 @@ export class Tower {
         revision: 0,
         createdAt: now,
         updatedAt: now,
+        dirtyBase: dirty,
+        ...(snapshotCommit ? { snapshotCommit, snapshotRef } : {}),
         missions: [],
       }
       validateState(state, this.paths.state)
       await writeJsonAtomic(this.paths.state, state)
-      await appendJsonl(this.paths.activity, { at: now, type: 'init', text: `base ${base}` })
+      await appendJsonl(this.paths.activity, {
+        at: now,
+        type: 'init',
+        text: `base ${base}${snapshotCommit ? ` snapshot ${snapshotCommit.slice(0, 12)}` : ''}${dirty ? ' (dirty base)' : ''}`,
+      })
       return {
         created: true,
         repoRoot: this.root,
@@ -491,6 +686,10 @@ export class Tower {
         base,
         revision: 0,
         missions: 0,
+        reanchored: false,
+        dirty,
+        snapshotCommit,
+        snapshotRef,
       }
     })
   }
@@ -536,11 +735,36 @@ export class Tower {
   }
 
   async mission(input = {}) {
-    if (typeof input.id !== 'string' || input.id.trim().length === 0) fail('tower_mission requires id')
+    const missionId = typeof input.id === 'string' ? input.id.trim() : input.id
+    if (typeof missionId !== 'string' || missionId.length === 0) fail('tower_mission requires id')
     return withLock(this.paths, async () => {
       const state = await this.load()
-      const mission = state.missions.find((entry) => entry.id === input.id)
-      if (!mission) fail(`unknown mission "${input.id}"`)
+      const mission = state.missions.find((entry) => entry.id === missionId)
+      if (!mission) fail(`unknown mission "${missionId}"`)
+      const actor = input.actor ?? { name: 'tower', role: 'tower' }
+      const workerRequest = actor.role === 'worker'
+      if (actor.role === 'reviewer') {
+        fail('only the tower or a worker may update a mission; reviewers submit tower_review')
+      }
+      if (workerRequest && mission.owner && mission.owner !== actor.name) {
+        fail(`worker ${actor.name} does not own mission ${mission.id} (owner: ${mission.owner})`)
+      }
+      if (workerRequest) {
+        if (input.status !== undefined) {
+          fail('only the tower can change mission status directly; workers report completion with tower_complete')
+        }
+        if (input.scope !== undefined) fail('only the tower can change mission scope')
+        if (input.clear_blockers === true) fail('only the tower can clear blockers')
+        if (input.pause_cause !== undefined || input.authorization !== undefined) {
+          fail('only the tower can record pause/authorization metadata')
+        }
+      }
+      if (input.pause_cause !== undefined && input.status !== 'paused') {
+        fail('pause_cause is only valid together with status "paused"')
+      }
+      if (input.status === 'abandoned' && (typeof input.note !== 'string' || input.note.trim().length === 0)) {
+        fail('abandoning a mission requires a non-empty note (reason)')
+      }
       const now = Date.now()
       const changes = []
 
@@ -553,6 +777,20 @@ export class Tower {
         if (!allowed.includes(input.status)) {
           fail(`mission ${mission.id} cannot move from ${mission.status} to ${input.status}`)
         }
+        if (input.status === 'paused') {
+          mission.pauseCause = normalizePauseCause(input.pause_cause)
+        }
+        if (mission.status === 'paused' && input.status === 'active') {
+          const requireAuthorization = this.config.mode.requireResumeAuthorization === true
+          if (requireAuthorization && (mission.pauseCause ?? 'user') === 'user') {
+            if (typeof input.authorization !== 'string' || input.authorization.trim().length === 0) {
+              fail('resuming a user-paused mission requires a non-empty authorization reference')
+            }
+          }
+          if (typeof input.authorization === 'string' && input.authorization.trim()) {
+            mission.authorizationRef = input.authorization.trim()
+          }
+        }
         mission.status = input.status
         changes.push(`status=${input.status}`)
       }
@@ -586,6 +824,9 @@ export class Tower {
         if (typeof input.blocker !== 'string' || input.blocker.trim().length === 0) {
           fail('blocker must be a non-empty string')
         }
+        if (TERMINAL.has(mission.status)) {
+          fail(`mission ${mission.id} is ${mission.status}; a blocker cannot reopen a terminal mission`)
+        }
         mission.blockers.push(input.blocker.trim())
         mission.status = 'blocked'
         changes.push('blocker added')
@@ -657,24 +898,73 @@ export class Tower {
 
   async assertWorktree(worktree) {
     if (!worktree || typeof worktree.path !== 'string') fail('mission has no worktree')
-    const wtPath = path.resolve(worktree.path)
-    if (!(await exists(wtPath))) fail(`worktree is missing: ${wtPath}`)
-    const common = await currentCommonDir(wtPath)
-    if (!common) fail(`worktree ${wtPath} is not a Git worktree`)
-    if (path.resolve(common) !== path.resolve(this.commonDir)) {
-      fail(`worktree ${wtPath} belongs to a different repository`)
-    }
-    const branch = await currentBranch(wtPath)
-    if (branch !== worktree.branch) {
-      fail(`worktree ${wtPath} is on ${branch ?? 'detached HEAD'}, expected ${worktree.branch}`)
-    }
+    const owned = await assertOwnership({
+      storedPath: worktree.path,
+      storedRealPath: worktree.realPath,
+      branch: worktree.branch,
+      commonDir: this.commonDir,
+      missionId: worktree.missionId,
+    })
+    worktree.realPath = owned.realPath
     const registered = await listWorktrees(this.root)
-    if (!registered.some((entry) => path.resolve(entry.path) === wtPath)) {
-      fail(`worktree ${wtPath} is not registered with git`)
+    if (!registered.some((entry) => path.resolve(entry.path) === path.resolve(owned.path))) {
+      fail(`worktree ${owned.path} is not registered with git`)
     }
     return worktree
   }
 
+  /** Record that a spawned agent failed or went idle, so roster state is truthful. */
+  async recordSpawnOutcome(input) {
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      const entry = (state.roster ?? []).find((row) => row.name === input.name && row.missionId === input.missionId)
+      if (!entry) return null
+      const now = Date.now()
+      entry.state = input.state ?? 'failed'
+      entry.outcome = input.detail ? String(input.detail).slice(0, 1000) : null
+      entry.outcomeAt = now
+      state.revision += 1
+      state.updatedAt = now
+      validateState(state, this.paths.state)
+      await writeJsonAtomic(this.paths.state, state)
+      await appendJsonl(this.paths.activity, {
+        at: now,
+        type: 'spawn',
+        missionId: input.missionId,
+        text: `${entry.name} ${entry.state}${entry.outcome ? `: ${entry.outcome.slice(0, 160)}` : ''}`,
+      })
+      return entry
+    })
+  }
+
+  /** Record that a live agent was interrupted by the tower. */
+  async recordInterrupt(input) {
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      const entry = (state.roster ?? []).find(
+        (row) =>
+          (input.agentId !== undefined && row.agentId === input.agentId) ||
+          (input.name !== undefined && row.name === input.name),
+      )
+      if (!entry) fail(`unknown roster agent "${input.name ?? input.agentId}"`)
+      const now = Date.now()
+      entry.state = 'interrupted'
+      entry.outcome = String(input.reason ?? 'interrupted by tower').slice(0, 1000)
+      entry.outcomeAt = now
+      state.revision += 1
+      state.updatedAt = now
+      validateState(state, this.paths.state)
+      await writeJsonAtomic(this.paths.state, state)
+      await appendJsonl(this.paths.activity, {
+        at: now,
+        type: 'spawn',
+        missionId: entry.missionId,
+        text: `${entry.name} interrupted: ${entry.outcome}`,
+      })
+      return entry
+    })
+  }
+
   async provision(input = {}) {
     const missionId = input.missionId
     if (typeof missionId !== 'string' || missionId.trim().length === 0) {
@@ -689,11 +979,20 @@ export class Tower {
         return { mission, worktree: mission.worktree, created: false }
       }
 
-      const baseCommit = await revParse(this.root, state.base)
+      const baseCommit = input.baseCommit
+        ? String(input.baseCommit)
+        : input.includeDirtyBase === false
+          ? await revParse(this.root, state.base)
+          : state.snapshotCommit && (await tryGit(this.root, ['cat-file', '-e', `${state.snapshotCommit}^{commit}`])) !== null
+            ? state.snapshotCommit
+            : await revParse(this.root, state.base)
       const branch = `tower/${mission.id.toLowerCase()}-${slugify(mission.title)}`
+      const configuredRoot = this.config.worktrees.root
       const root = input.worktreeRoot
         ? path.resolve(input.worktreeRoot)
-        : path.join(path.dirname(this.root), '.dsh-tower-worktrees', shortHash(this.commonDir))
+        : configuredRoot
+          ? path.resolve(configuredRoot)
+          : path.join(path.dirname(this.root), '.dsh-tower-worktrees', shortHash(this.commonDir))
       if (!path.isAbsolute(root)) fail('worktreeRoot must be an absolute path')
       this.assertOutside(root)
       await ensureDir(root)
@@ -704,7 +1003,7 @@ export class Tower {
 
       await addWorktree(this.root, { path: wtPath, branch, commit: baseCommit })
       const now = Date.now()
-      const worktree = { path: wtPath, branch, baseCommit, createdAt: now }
+      const worktree = { path: wtPath, branch, baseCommit, createdAt: now, realPath: await canonicalPath(wtPath) }
       mission.worktree = worktree
       mission.baseCommit = baseCommit
       mission.updatedAt = now
@@ -728,9 +1027,37 @@ export class Tower {
     const mission = state.missions.find((entry) => entry.id === missionId)
     if (!mission) fail(`unknown mission "${missionId}"`)
     const byId = new Map(state.missions.map((entry) => [entry.id, entry]))
+    const branch = mission.worktree ? mission.worktree.branch : null
+    const reviews = branch
+      ? (state.reviews ?? [])
+          .filter((review) => review.branch === branch)
+          .slice()
+          .sort((a, b) => b.round - a.round)
+          .slice(0, 3)
+      : []
+    const findings = (state.findings ?? [])
+      .filter((finding) => finding.missionId === mission.id)
+      .slice()
+      .sort((a, b) => b.seq - a.seq)
+      .slice(0, 10)
     return {
       base: state.base,
       mission: fullMission(mission),
+      snapshotCommit: state.snapshotCommit ?? null,
+      completionReport: mission.completionReport ?? null,
+      reviews: reviews.map((review) => ({
+        id: review.id,
+        round: review.round,
+        status: review.status,
+        mergeVerdict: review.mergeVerdict,
+        reviewer: review.reviewer,
+        findings: review.findings,
+        checks: review.checks ?? [],
+        decision: review.decision,
+        reviewedCommit: review.reviewedCommit,
+        at: review.at,
+      })),
+      findings: findings.map((finding) => findingSummary(finding)),
       deps: (mission.deps ?? []).map((id) => {
         const dep = byId.get(id)
         return dep ? { id, title: dep.title, status: dep.status } : { id, title: null, status: 'unknown' }
@@ -751,6 +1078,7 @@ export class Tower {
         fail(`agent ${input.agentId} is already in the roster`)
       }
       const now = Date.now()
+      const spawnTip = input.cwd ? ((await tryGit(input.cwd, ['rev-parse', 'HEAD'])) ?? '').trim() || null : null
       const entry = {
         name: input.name,
         role: input.role,
@@ -760,14 +1088,39 @@ export class Tower {
         missionId: input.missionId,
         cwd: input.cwd ?? null,
         branch: input.branch ?? null,
+        spawnTip,
         state: 'active',
         spawnedAt: now,
       }
-      state.roster.push(entry)
       if (input.role === 'worker') {
+        const previous = workerEntries(state, mission.id)
+        const live = previous.find((entry) => !ROSTER_INACTIVE.has(entry.state))
+        if (live && !input.takeover) {
+          fail(
+            `mission ${mission.id} already has a live worker "${live.name}"; stop it with tower_interrupt, or pass takeover:true after it is no longer running`,
+          )
+        }
+        // A new owner always retires the mission's older worker entries, including
+        // idle `inactive` ones; otherwise the next spawn would see several entries
+        // for the same mission and the old idle worker would block forever.
+        for (const old of previous) {
+          if (old.state === 'retired') continue
+          old.state = 'retired'
+          old.outcome = `replaced by ${input.name}${input.takeover ? ' (takeover)' : ''}`
+          old.outcomeAt = now
+        }
+        const liveCount = countLiveWorkers(state)
+        const max = Number(this.config.spawn.maxLiveWorkers) || 4
+        if (liveCount >= max) {
+          fail(`live worker limit reached (${max}); stop a worker or raise spawn.maxLiveWorkers`)
+        }
+        const generation = (mission.ownerGeneration ?? 0) + 1
+        entry.generation = generation
+        mission.ownerGeneration = generation
         mission.owner = input.name
         if (mission.status === 'planned') mission.status = 'active'
       }
+      state.roster.push(entry)
       mission.updatedAt = now
       state.revision += 1
       state.updatedAt = now
@@ -804,6 +1157,129 @@ export class Tower {
     }
   }
 
+  async recordTestRun(input = {}) {
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      const mission = state.missions.find((entry) => entry.id === input.missionId)
+      if (!mission) fail(`unknown mission "${input.missionId}"`)
+      if (!mission.testRuns) mission.testRuns = []
+      const receipt = { ...input.receipt, recordedAt: Date.now() }
+      mission.testRuns.push(receipt)
+      if (mission.testRuns.length > 50) mission.testRuns = mission.testRuns.slice(-50)
+      state.revision += 1
+      state.updatedAt = Date.now()
+      validateState(state, this.paths.state)
+      await writeJsonAtomic(this.paths.state, state)
+      await appendJsonl(this.paths.activity, {
+        at: Date.now(),
+        type: 'test',
+        missionId: mission.id,
+        text: receipt.ok === true ? `passed ${receipt.tests?.length ?? 0} test(s)` : `failed: ${String(receipt.error ?? 'unknown').slice(0, 200)}`,
+      })
+      return receipt
+    })
+  }
+
+  async recordLegacySnapshot(snapshot) {
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      if (!Array.isArray(state.legacySnapshots)) state.legacySnapshots = []
+      const existing = state.legacySnapshots.find((entry) => entry.sourceHash === snapshot.sourceHash)
+      if (existing) return { snapshot: existing, duplicate: true }
+      state.legacySnapshots.push(snapshot)
+      state.revision += 1
+      state.updatedAt = Date.now()
+      validateState(state, this.paths.state)
+      await writeJsonAtomic(this.paths.state, state)
+      return { snapshot, duplicate: false }
+    })
+  }
+
+  async recordLegacyMap(map) {
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      if (!Array.isArray(state.legacyMaps)) state.legacyMaps = []
+      const existing = state.legacyMaps.find(
+        (entry) => entry.sourceHash === map.sourceHash && entry.oldId === map.oldId,
+      )
+      if (existing) return { map: existing, duplicate: true }
+      state.legacyMaps.push(map)
+      state.revision += 1
+      state.updatedAt = Date.now()
+      validateState(state, this.paths.state)
+      await writeJsonAtomic(this.paths.state, state)
+      return { map, duplicate: false }
+    })
+  }
+
+  async createBatch(input = {}, actor = 'tower') {
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      const normalized = validateBatchCreate(state, input)
+      if (!Array.isArray(state.batches)) state.batches = []
+      const max = state.batches.reduce((value, batch) => {
+        const match = /^B(\d+)$/.exec(String(batch.id ?? ''))
+        return match ? Math.max(value, Number(match[1])) : value
+      }, 0)
+      const batch = {
+        id: `B${max + 1}`,
+        status: 'open',
+        ...normalized,
+        createdBy: actor,
+        createdAt: Date.now(),
+      }
+      state.batches.push(batch)
+      state.revision += 1
+      state.updatedAt = batch.createdAt
+      validateState(state, this.paths.state)
+      await writeJsonAtomic(this.paths.state, state)
+      await appendJsonl(this.paths.activity, {
+        at: batch.createdAt,
+        type: 'batch',
+        text: `created ${batch.id}: ${batch.missionIds.join(', ')}`,
+      })
+      return batch
+    })
+  }
+
+  async closeBatch(batchId, options = {}, actor = 'tower') {
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      const batch = (state.batches ?? []).find((entry) => entry.id === batchId)
+      if (!batch) fail(`unknown batch "${batchId}"`)
+      const result = validateBatchClose(state, batch, { ...options, state })
+      const blockers = Array.isArray(result.blockers) ? result.blockers : []
+      if (blockers.length > 0) return { ok: false, batch, blockers, checks: result.checks ?? [] }
+      batch.status = 'closed'
+      batch.closedAt = Date.now()
+      batch.closedBy = actor
+      batch.close = {
+        checks: options.checks ?? [],
+        treeTip: options.treeTip ?? null,
+        receiptHashes: options.receiptHashes ?? {},
+        at: batch.closedAt,
+      }
+      state.revision += 1
+      state.updatedAt = batch.closedAt
+      validateState(state, this.paths.state)
+      await writeJsonAtomic(this.paths.state, state)
+      await appendJsonl(this.paths.activity, { at: batch.closedAt, type: 'batch', text: `closed ${batch.id}` })
+      return { ok: true, batch, blockers: [], checks: result.checks ?? [] }
+    })
+  }
+
+  async batchStatus(batchId) {
+    const state = await this.load()
+    const batch = batchId
+      ? (state.batches ?? []).find((entry) => entry.id === batchId)
+      : null
+    if (batchId && !batch) fail(`unknown batch "${batchId}"`)
+    return {
+      batches: (state.batches ?? []).map((entry) => summarizeBatch(state, entry)),
+      ...(batch ? { batch: summarizeBatch(state, batch) } : {}),
+    }
+  }
+
   async markRetired(agentIds) {
     if (!Array.isArray(agentIds) || agentIds.length === 0) return { retired: [] }
     return withLock(this.paths, async () => {
@@ -832,6 +1308,77 @@ export class Tower {
     })
   }
 
+  async markMissing(agentIds) {
+    if (!Array.isArray(agentIds) || agentIds.length === 0) return { missing: [] }
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      const missing = []
+      const now = Date.now()
+      for (const entry of state.roster ?? []) {
+        if (!ROSTER_INACTIVE.has(entry.state) && agentIds.includes(entry.agentId)) {
+          entry.state = 'missing'
+          entry.missingSince = now
+          missing.push(entry.agentId)
+        }
+      }
+      if (missing.length > 0) {
+        state.revision += 1
+        state.updatedAt = now
+        validateState(state, this.paths.state)
+        await writeJsonAtomic(this.paths.state, state)
+        await appendJsonl(this.paths.activity, { at: now, type: 'adopt', text: `missing ${missing.join(', ')}` })
+      }
+      return { missing }
+    })
+  }
+
+  /** Mark live roster entries whose catalog activity disappeared after staleMs.
+   * `authoritative` must be true only when the parent catalog was readable;
+   * unknown state is never treated as stopped. */
+  async sweepRoster(input = {}) {
+    const staleMs = Number(input.staleMs) || 0
+    if (staleMs <= 0 || input.authoritative !== true) return { marked: [], idled: [] }
+    const activity = input.activity ?? {}
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      const now = Date.now()
+      const marked = []
+      const idled = []
+      for (const entry of state.roster ?? []) {
+        if (ROSTER_INACTIVE.has(entry.state)) continue
+        const observed = activity[entry.agentId]
+        if (observed === 'inactive') {
+          entry.state = 'inactive'
+          entry.outcome = entry.outcome ?? 'idle (catalog)'
+          entry.outcomeAt = now
+          idled.push(entry.name)
+          continue
+        }
+        if (observed === 'running') continue
+        if (observed !== undefined) continue
+        const age = now - Number(entry.spawnedAt ?? now)
+        if (age > staleMs) {
+          entry.state = 'stale'
+          entry.stale = true
+          entry.staleAt = now
+          marked.push(entry.name)
+        }
+      }
+      if (marked.length > 0 || idled.length > 0) {
+        state.revision += 1
+        state.updatedAt = now
+        validateState(state, this.paths.state)
+        await writeJsonAtomic(this.paths.state, state)
+        await appendJsonl(this.paths.activity, {
+          at: now,
+          type: 'watchdog',
+          text: `stale ${marked.join(', ') || '-'}; idle ${idled.join(', ') || '-'}`,
+        })
+      }
+      return { marked, idled }
+    })
+  }
+
   unreadFor(state, name) {
     return (state.messages ?? []).filter((message) => {
       if (message.from === name) return false
@@ -861,6 +1408,7 @@ export class Tower {
         subject: input.subject,
         body: input.body,
         scope: input.scope ?? null,
+        consentRef: input.consentRef ?? null,
         at: now,
         readBy: [],
         delivery: [],
@@ -909,6 +1457,7 @@ export class Tower {
       for (const message of page) {
         if (!(message.readBy ?? []).includes(reader)) {
           message.readBy = [...(message.readBy ?? []), reader]
+          message.readAt = { ...(message.readAt ?? {}), [reader]: Date.now() }
           changed = true
         }
       }
@@ -929,6 +1478,8 @@ export class Tower {
           body: message.body,
           scope: message.scope ?? null,
           at: message.at,
+          delivery: message.delivery ?? [],
+          ackAt: message.readAt?.[reader] ?? null,
         })),
         pageSize: page.length,
         unreadRemaining,
@@ -936,50 +1487,64 @@ export class Tower {
     })
   }
 
+  /** Read-only completion preconditions shared by tower_complete and the tool
+   * layer's test-discovery preflight. Throws on the first failed condition. */
+  async checkCompletion(input) {
+    const state = await this.load()
+    const mission = state.missions.find((entry) => entry.id === input.missionId)
+    if (!mission) fail(`unknown mission "${input.missionId}"`)
+    const worker = (state.roster ?? []).find((entry) => entry.agentId === input.agentId)
+    if (!worker || worker.missionId !== mission.id) {
+      fail(`agent ${input.agentId} is not assigned to mission ${mission.id}`)
+    }
+    if (worker.role !== 'worker') fail(`agent ${worker.name} is a ${worker.role}, not a worker`)
+    if (['retired', 'failed', 'interrupted', 'missing', 'stale'].includes(worker.state)) {
+      fail(`agent ${worker.name} is ${worker.state}; a stopped worker cannot report completion`)
+    }
+    if (mission.owner && mission.owner !== worker.name) {
+      fail(`agent ${worker.name} is not the current owner of mission ${mission.id} (owner: ${mission.owner})`)
+    }
+    if (mission.status === 'completed') fail(`mission ${mission.id} is already completed`)
+    if (!['active', 'planned'].includes(mission.status)) {
+      fail(`mission ${mission.id} is ${mission.status}; it cannot be completed from that state`)
+    }
+    if (typeof input.report !== 'string' || input.report.trim().length === 0) {
+      fail('tower_complete requires a non-empty report')
+    }
+    const openTasks = mission.tasks.filter((task) => task.status === 'open')
+    if (openTasks.length > 0) {
+      fail(
+        `mission ${mission.id} still has ${openTasks.length} open task(s): ${openTasks
+          .map((task) => task.text)
+          .join('; ')}`,
+      )
+    }
+    if ((mission.blockers ?? []).length > 0) {
+      fail(`mission ${mission.id} has unresolved blockers: ${mission.blockers.join('; ')}`)
+    }
+    if (!mission.worktree) fail(`mission ${mission.id} has no worktree`)
+    await this.assertWorktree(mission.worktree)
+    const commits = await countCommits(mission.worktree.path, mission.worktree.baseCommit)
+    if (commits < 1) {
+      fail(`mission branch has no commits since ${String(mission.worktree.baseCommit).slice(0, 12)}`)
+    }
+    const unread = this.unreadFor(state, worker.name)
+    if (unread.length > 0) {
+      fail(
+        `mission ${mission.id} cannot complete with ${unread.length} unread inbox message(s) for ${worker.name}; call tower_inbox until unread is 0, incorporate them, then retry`,
+      )
+    }
+    return { state, mission, worker, commits }
+  }
+
   async complete(input) {
     return withLock(this.paths, async () => {
-      const state = await this.load()
-      const mission = state.missions.find((entry) => entry.id === input.missionId)
-      if (!mission) fail(`unknown mission "${input.missionId}"`)
-      const worker = (state.roster ?? []).find((entry) => entry.agentId === input.agentId)
-      if (!worker || worker.missionId !== mission.id) {
-        fail(`agent ${input.agentId} is not assigned to mission ${mission.id}`)
-      }
-      if (worker.role !== 'worker') fail(`agent ${worker.name} is a ${worker.role}, not a worker`)
-      if (mission.status === 'completed') fail(`mission ${mission.id} is already completed`)
-      if (!['active', 'planned'].includes(mission.status)) {
-        fail(`mission ${mission.id} is ${mission.status}; it cannot be completed from that state`)
-      }
-      if (typeof input.report !== 'string' || input.report.trim().length === 0) {
-        fail('tower_complete requires a non-empty report')
-      }
-      const openTasks = mission.tasks.filter((task) => task.status === 'open')
-      if (openTasks.length > 0) {
-        fail(
-          `mission ${mission.id} still has ${openTasks.length} open task(s): ${openTasks
-            .map((task) => task.text)
-            .join('; ')}`,
-        )
-      }
-      if ((mission.blockers ?? []).length > 0) {
-        fail(`mission ${mission.id} has unresolved blockers: ${mission.blockers.join('; ')}`)
-      }
-      if (!mission.worktree) fail(`mission ${mission.id} has no worktree`)
-      await this.assertWorktree(mission.worktree)
-      const commits = await countCommits(mission.worktree.path, mission.worktree.baseCommit)
-      if (commits < 1) {
-        fail(`mission branch has no commits since ${String(mission.worktree.baseCommit).slice(0, 12)}`)
-      }
-      const unread = this.unreadFor(state, worker.name)
-      if (unread.length > 0) {
-        fail(
-          `mission ${mission.id} cannot complete with ${unread.length} unread inbox message(s) for ${worker.name}; call tower_inbox until unread is 0, incorporate them, then retry`,
-        )
-      }
+      const { state, mission, worker, commits } = await this.checkCompletion(input)
 
+      const checks = normalizeChecks(input.checks)
       const now = Date.now()
       mission.status = 'completed'
-      mission.completionReport = { report: input.report.trim(), by: worker.name, at: now }
+      mission.completionReport = { report: input.report.trim(), by: worker.name, at: now, checks }
       mission.updatedAt = now
       state.revision += 1
       state.updatedAt = now
@@ -1055,6 +1620,111 @@ export class Tower {
     })
   }
 
+  /** List or read findings. Read-only paths never take the writer lock. */
+  async readFindings(input = {}) {
+    const state = await this.load()
+    const all = state.findings ?? []
+    const counts = countFindings(all)
+    if (input.id !== undefined && input.id !== null && input.id !== '') {
+      const finding = all.find((entry) => entry.id === input.id)
+      if (!finding) fail(`unknown finding "${input.id}"`)
+      return { finding: { ...finding }, counts, total: all.length, filtered: 1, action: 'read' }
+    }
+    if (input.status !== undefined && input.status !== 'all') {
+      if (!FINDING_STATUSES.includes(input.status)) {
+        fail(`finding status must be one of ${FINDING_STATUSES.join('|')}`)
+      }
+    }
+    let visible = all
+    if (input.status !== undefined && input.status !== 'all') {
+      visible = visible.filter((finding) => (finding.status ?? 'open') === input.status)
+    }
+    if (input.type !== undefined) {
+      if (!FINDING_TYPES.includes(input.type)) fail(`finding type must be one of ${FINDING_TYPES.join('|')}`)
+      visible = visible.filter((finding) => finding.type === input.type)
+    }
+    if (input.severity !== undefined) {
+      if (!FINDING_SEVERITIES.includes(input.severity)) {
+        fail(`finding severity must be one of ${FINDING_SEVERITIES.join('|')}`)
+      }
+      visible = visible.filter((finding) => finding.severity === input.severity)
+    }
+    if (input.missionId !== undefined && input.missionId !== null && input.missionId !== '') {
+      visible = visible.filter((finding) => finding.missionId === input.missionId)
+    }
+    if (input.open === true) {
+      visible = visible.filter((finding) => !['fixed', 'wontfix'].includes(finding.status ?? 'open'))
+    }
+    const limit = Math.max(1, Math.min(200, Number.isInteger(input.limit) ? input.limit : 50))
+    const page = visible.slice(-limit).reverse()
+    return {
+      findings: page.map((finding) => findingSummary(finding)),
+      counts,
+      total: all.length,
+      filtered: visible.length,
+      action: 'list',
+    }
+  }
+
+  /**
+   * List, read, or transition findings. Listing and reading are lock-free;
+   * only a transition takes the writer lock. Reviewers may only read.
+   */
+  async findings(input = {}) {
+    const actor = input.actor ?? { name: 'tower', role: 'tower' }
+    if (typeof actor.role !== 'string') fail('finding actor role must be a string')
+    const hasId = input.id !== undefined && input.id !== null && input.id !== ''
+    const wantsUpdate = hasId && (input.status !== undefined || input.note !== undefined)
+    if (!wantsUpdate) return this.readFindings(input)
+
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      const all = state.findings ?? []
+      const finding = all.find((entry) => entry.id === input.id)
+      if (!finding) fail(`unknown finding "${input.id}"`)
+      if (actor.role === 'reviewer') {
+        fail('reviewers may list and read findings, but only the tower or a worker may change finding status')
+      }
+      const now = Date.now()
+      if (input.status !== undefined) {
+        if (input.status === 'all') {
+          fail('finding status "all" is only a list filter; pass a concrete status when updating')
+        }
+        if (!FINDING_STATUSES.includes(input.status)) {
+          fail(`finding status must be one of ${FINDING_STATUSES.join('|')}`)
+        }
+        const current = finding.status ?? 'open'
+        const allowed = FINDING_TRANSITIONS[current] ?? []
+        if (!allowed.includes(input.status)) {
+          fail(`finding ${finding.id} cannot move from ${current} to ${input.status}`)
+        }
+        finding.status = input.status
+        if (input.status === 'fixed' || input.status === 'wontfix') finding.closedAt = now
+        else delete finding.closedAt
+      }
+      if (input.note !== undefined) {
+        if (typeof input.note !== 'string' || input.note.trim().length === 0) {
+          fail('finding note must be a non-empty string')
+        }
+        if (!Array.isArray(finding.notes)) finding.notes = []
+        finding.notes.push({ by: actor.name, at: now, text: input.note.trim() })
+      }
+      finding.updatedAt = now
+      state.revision += 1
+      state.updatedAt = now
+      validateState(state, this.paths.state)
+      await writeJsonAtomic(this.paths.state, state)
+      await appendJsonl(this.paths.activity, {
+        at: now,
+        type: 'finding',
+        missionId: finding.missionId,
+        text: `${finding.id} ${finding.status}${input.note !== undefined ? ' +note' : ''} (${actor.name})`,
+      })
+      // Counts must reflect the transition just recorded.
+      return { finding: { ...finding }, counts: countFindings(all), total: all.length, filtered: 1, action: 'updated' }
+    })
+  }
+
   async submitReview(input) {
     return withLock(this.paths, async () => {
       const state = await this.load()
@@ -1111,11 +1781,17 @@ export class Tower {
       await this.assertWorktree(mission.worktree)
       const tip = await revParse(mission.worktree.path, 'HEAD')
       const branch = mission.worktree.branch
+      if (caller && caller.role === 'reviewer' && caller.spawnTip && caller.spawnTip !== tip) {
+        fail(
+          `reviewer ${caller.name} modified the mission branch after it was spawned (${caller.spawnTip.slice(0, 7)} -> ${tip.slice(0, 7)}); reviewers must be read-only — spawn a fresh reviewer`,
+        )
+      }
       const prior = (state.reviews ?? []).filter((review) => review.branch === branch)
       const reviewerRounds = prior.filter((review) => review.reviewer === reviewerName).length
-      if (reviewerRounds >= MAX_REVIEW_ROUNDS) {
+      const maxReviewRounds = Number(this.config.review.maxRoundsPerReviewer) || MAX_REVIEW_ROUNDS
+      if (reviewerRounds >= maxReviewRounds) {
         fail(
-          `reviewer ${reviewerName} reached the ${MAX_REVIEW_ROUNDS}-round cap for ${branch}; continue with a different reviewer`,
+          `reviewer ${reviewerName} reached the ${maxReviewRounds}-round cap for ${branch}; continue with a different reviewer`,
         )
       }
       const round = prior.length === 0 ? 1 : Math.max(...prior.map((review) => review.round)) + 1
@@ -1173,9 +1849,105 @@ export class Tower {
     })
   }
 
-  async enrichedMissions(state) {
+  /** Full detail for one mission, including reviews, findings and recent activity. */
+  async missionDetail(missionId) {
+    const state = await this.load()
+    const mission = state.missions.find((entry) => entry.id === missionId)
+    if (!mission) fail(`unknown mission "${missionId}"`)
+    const branch = mission.worktree ? mission.worktree.branch : null
+    const reviews = (state.reviews ?? [])
+      .filter((review) => review.missionId === mission.id || (branch && review.branch === branch))
+      .slice()
+      .sort((a, b) => b.round - a.round)
+    const findings = (state.findings ?? []).filter((finding) => finding.missionId === mission.id)
+    const activity = (await readActivityTail(this.paths.activity, 200)).filter(
+      (entry) => entry.missionId === mission.id,
+    )
+    return {
+      mission: fullMission(mission),
+      reviews: reviews.slice(0, 10),
+      findings: findings.slice(-10).map((finding) => findingSummary(finding)),
+      activity: activity.slice(-20),
+    }
+  }
+
+  /** Human-readable mission board (markdown) for the current state. */
+  boardMarkdown(state) {
+    const lines = []
+    lines.push(`# Tower missions — ${state.repoRoot}`)
+    lines.push('')
+    lines.push(`Base: \`${state.base}\` · revision ${state.revision} · updated ${new Date(state.updatedAt ?? Date.now()).toISOString()}`)
+    const counts = {}
+    for (const status of MISSION_STATUSES) counts[status] = 0
+    for (const mission of state.missions) counts[mission.status] += 1
+    lines.push('')
+    lines.push(
+      `Missions: ${state.missions.length} · ` +
+        MISSION_STATUSES.map((status) => `${status} ${counts[status]}`).join(' · '),
+    )
+    const openFindings = (state.findings ?? []).filter((finding) => !['fixed', 'wontfix'].includes(finding.status ?? 'open'))
+    lines.push(`Findings: ${openFindings.length} open of ${(state.findings ?? []).length}`)
+    lines.push('')
+    lines.push('| Mission | Status | Kind | Title | Owner | Tasks (done/open/dropped) | Latest review | Merged |')
+    lines.push('|---|---|---|---|---|---|---|---|')
+    for (const mission of state.missions) {
+      const tasks = taskCounts(mission.tasks ?? [])
+      const branch = mission.worktree ? mission.worktree.branch : null
+      const reviews = branch ? (state.reviews ?? []).filter((review) => review.branch === branch) : []
+      const latest = reviews.length > 0 ? reviews.reduce((a, b) => (a.round >= b.round ? a : b)) : null
+      const reviewText = latest ? `R${latest.round} ${latest.status}/${latest.mergeVerdict}` : '—'
+      lines.push(
+        `| ${mission.id} | ${mission.status} | ${mission.kind} | ${String(mission.title).replaceAll('|', '\\|')} | ${
+          mission.owner ?? '—'
+        } | ${tasks.done}/${tasks.open}/${tasks.dropped} | ${reviewText} | ${
+          mission.mergedCommit ? mission.mergedCommit.slice(0, 8) : '—'
+        } |`,
+      )
+    }
+    if ((state.roster ?? []).length > 0) {
+      lines.push('')
+      lines.push('## Roster')
+      lines.push('')
+      lines.push('| Name | Role | Mission | State | Agent |')
+      lines.push('|---|---|---|---|---|')
+      for (const entry of state.roster) {
+        lines.push(
+          `| ${entry.name} | ${entry.role} | ${entry.missionId} | ${entry.state} | \`${entry.agentId}\` |`,
+        )
+      }
+    }
+    lines.push('')
+    return lines.join('\n')
+  }
+
+  /** Write the board when docs.board is enabled; failures never break a mutation. */
+  async writeBoard() {
+    if (this.config.docs?.board === false) return null
+    try {
+      const state = await this.load()
+      const file = this.config.docs?.boardLocation === 'repo'
+        ? path.join(this.root, 'MISSIONS.md')
+        : path.join(this.paths.dir, 'MISSIONS.md')
+      const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
+      await fsp.writeFile(tmp, this.boardMarkdown(state), 'utf8')
+      await renameWithRetry(tmp, file)
+      return file
+    } catch {
+      return null
+    }
+  }
+
+  boardFile() {
+    return this.config.docs?.boardLocation === 'repo'
+      ? path.join(this.root, 'MISSIONS.md')
+      : path.join(this.paths.dir, 'MISSIONS.md')
+  }
+
+  async enrichedMissions(state, onlyIds) {
+    const wanted = onlyIds ? new Set(onlyIds) : null
     const out = []
     for (const mission of state.missions) {
+      if (wanted && !wanted.has(mission.id)) continue
       const summary = missionSummary(mission)
       const branch = mission.worktree ? mission.worktree.branch : null
       const reviews = branch ? (state.reviews ?? []).filter((review) => review.branch === branch) : []
@@ -1237,6 +2009,18 @@ export class Tower {
     const openTasks = mission.tasks.filter((task) => task.status === 'open')
     if (openTasks.length > 0) push('tasks-open', `${openTasks.length} open task(s): ${openTasks.map((task) => task.text).join('; ')}`)
     if ((mission.blockers ?? []).length > 0) push('blockers-present', mission.blockers.join('; '))
+    if (this.config.gates.requireChecks === true) {
+      const checks = mission.completionReport?.checks ?? []
+      if (checks.length === 0) {
+        push('no-check-evidence', `mission ${mission.id} has no completion checks; gates.requireChecks is enabled`)
+      }
+    }
+    if (state.mergeIntent && state.mergeIntent.missionId === mission.id) {
+      push(
+        'merge-intent-pending',
+        `a merge intent for ${state.mergeIntent.missionId} was recorded at ${new Date(Number(state.mergeIntent.startedAt) || 0).toISOString()}; run tower_merge to reconcile it`,
+      )
+    }
 
     const worktree = mission.worktree ?? null
     let branchTip = null
@@ -1291,9 +2075,16 @@ export class Tower {
     const branch = worktree ? worktree.branch : null
     const reviews = branch ? (state.reviews ?? []).filter((review) => review.branch === branch) : []
     const latest = reviews.length > 0 ? reviews.reduce((a, b) => (a.round >= b.round ? a : b)) : null
-    if (!latest) {
+    const exempt =
+      mission.reviewPolicy === 'none' &&
+      this.config.gates.allowReviewExemption === true &&
+      String(mission.reviewExemptionReason ?? '').trim().length > 0
+    if (mission.reviewPolicy === 'none' && this.config.gates.allowReviewExemption !== true) {
+      push('review-exemption-invalid', `mission ${mission.id} requests no review but gates.allowReviewExemption is disabled`)
+    }
+    if (!exempt && !latest) {
       push('no-review', `branch ${branch ?? '(none)'} has no review; assign a reviewer first`)
-    } else {
+    } else if (!exempt) {
       const waived = this.rebaseWaived(mission, latest)
       if (latest.missionId !== mission.id) {
         push('review-mission-mismatch', `latest review belongs to mission ${latest.missionId}`)
@@ -1309,8 +2100,26 @@ export class Tower {
       }
     }
 
-    for (const entry of (state.roster ?? []).filter((row) => row.missionId === mission.id && row.state !== 'retired')) {
+    for (const entry of (state.roster ?? []).filter((row) => row.missionId === mission.id && !ROSTER_INACTIVE.has(row.state))) {
       if (activity[entry.agentId] === 'running') push('worker-busy', `agent ${entry.name} is still running`)
+      else if (input.parentStatus && entry.parentSessionId && input.parentStatus[entry.parentSessionId] !== 'ok') {
+        push(
+          'worker-status-unknown',
+          `cannot prove agent ${entry.name} is stopped: its parent catalog is unavailable`,
+        )
+      }
+    }
+    const staleWorkers = (state.roster ?? []).filter(
+      (row) => row.missionId === mission.id && (row.state === 'stale' || row.stale === true),
+    )
+    if (staleWorkers.length > 0) {
+      push('worker-stale', `stale worker(s) for ${mission.id}: ${staleWorkers.map((row) => row.name).join(', ')}; adopt or interrupt before merge`)
+    }
+    if (this.config.gates.requireTests === true) {
+      const runs = (mission.testRuns ?? []).filter((run) => run.ok === true && run.treeTip && branchTip && run.treeTip === branchTip)
+      if (runs.length === 0) {
+        push('tests-missing', `mission ${mission.id} has no passing test discovery for tip ${branchTip ? branchTip.slice(0, 7) : '(none)'}`)
+      }
     }
 
     const checkoutBranch = await currentBranch(this.root)
@@ -1330,6 +2139,37 @@ export class Tower {
     }
   }
 
+  /** Read-only mission diff for reviewers: branch changes against the merge base. */
+  async diff(input = {}) {
+    const state = await this.load()
+    const mission = state.missions.find((entry) => entry.id === input.missionId)
+    if (!mission) fail(`unknown mission "${input.missionId}"`)
+    if (!mission.worktree) fail(`mission ${mission.id} has no worktree to diff`)
+    await this.assertWorktree(mission.worktree)
+    const baseTip = await revParse(this.root, state.base)
+    const branchTip = await revParse(mission.worktree.path, 'HEAD')
+    const mergeBase = (await git(mission.worktree.path, ['merge-base', baseTip, branchTip])).trim()
+    const files = (await git(mission.worktree.path, ['diff', '--name-status', `${mergeBase}..${branchTip}`]))
+      .split('\n')
+      .filter(Boolean)
+    const commits = (await git(mission.worktree.path, ['log', '--oneline', `${mergeBase}..${branchTip}`]))
+      .split('\n')
+      .filter(Boolean)
+    const fullPatch = await git(mission.worktree.path, ['diff', `${mergeBase}..${branchTip}`])
+    const limit = Number.isInteger(input.maxBytes) && input.maxBytes > 0 ? input.maxBytes : 64 * 1024
+    return {
+      missionId: mission.id,
+      branch: mission.worktree.branch,
+      baseTip,
+      branchTip,
+      mergeBase,
+      files,
+      commits,
+      truncated: fullPatch.length > limit,
+      patch: fullPatch.slice(0, limit),
+    }
+  }
+
   /**
    * Record a merge that already landed in Git without being recorded here:
    * a crashed/timed-out merge, a manual merge, or a rebase that fast-forwarded
@@ -1337,14 +2177,60 @@ export class Tower {
    * exists and either the branch tip or the reviewed commit is already an
    * ancestor of the base.
    */
+  /** Clear a stale merge intent only when the crash left no merge in progress
+   * or no merge commit. Returns true when the intent was consumed. */
+  async reconcileMergeIntent(state, mission) {
+    const intent = state.mergeIntent
+    if (!intent || intent.missionId !== mission.id || !mission.worktree) return false
+    let head = null
+    try {
+      head = await revParse(this.root, 'HEAD')
+    } catch {
+      return false
+    }
+    const mergeHeadPath = path.join(this.commonDir, 'MERGE_HEAD')
+    const inProgress = await exists(mergeHeadPath)
+    if (inProgress) return false
+    let landed = null
+    if (head === intent.baseTip) {
+      landed = null // no merge commit was created; the intent is safe to drop
+    } else {
+      landed = await findLandedMerge(
+        this.root,
+        head,
+        new Set([intent.branchTip, intent.baseTip].filter(Boolean)),
+      ).catch(() => null)
+      if (!landed) return false
+    }
+    const now = Date.now()
+    delete state.mergeIntent
+    state.revision += 1
+    state.updatedAt = now
+    await writeJsonAtomic(this.paths.state, state)
+    await appendJsonl(this.paths.activity, {
+      at: now,
+      type: 'merge',
+      missionId: mission.id,
+      text: landed
+        ? `reconciled merge intent; found landed commit ${String(landed.commit).slice(0, 7)}`
+        : 'cleared a merge intent that created no commit',
+    })
+    return true
+  }
+
   async reconcileLandedMerge(state, mission) {
     if (!['completed', 'blocked'].includes(mission.status)) return null
     if (!mission.worktree) return null
     const branch = mission.worktree.branch
     const reviews = (state.reviews ?? []).filter((review) => review.branch === branch)
-    if (reviews.length === 0) return null
-    const latest = reviews.reduce((a, b) => (a.round >= b.round ? a : b))
-    if (latest.status !== 'clean' || latest.mergeVerdict !== 'merge') return null
+    const exempt =
+      mission.reviewPolicy === 'none' &&
+      this.config.gates.allowReviewExemption === true &&
+      String(mission.reviewExemptionReason ?? '').trim().length > 0
+    if (reviews.length === 0 && !exempt) return null
+    const latest = reviews.length > 0 ? reviews.reduce((a, b) => (a.round >= b.round ? a : b)) : null
+    if (latest && !exempt && (latest.status !== 'clean' || latest.mergeVerdict !== 'merge')) return null
+    if (!latest && !exempt) return null
     let baseTip
     let branchTip
     try {
@@ -1353,7 +2239,7 @@ export class Tower {
     } catch {
       return null
     }
-    const reviewedTip = latest.reviewedCommit
+    const reviewedTip = latest?.reviewedCommit ?? null
     const branchLanded = await isAncestor(this.root, branchTip, baseTip)
     const reviewedLanded = reviewedTip ? await isAncestor(this.root, reviewedTip, baseTip) : false
     if (!branchLanded && !reviewedLanded) return null
@@ -1361,6 +2247,7 @@ export class Tower {
     const found = await findLandedMerge(this.root, baseTip, tips)
     const mergedCommit = found ? found.commit : reviewedLanded ? reviewedTip : branchTip
     const now = Date.now()
+    if (state.mergeIntent?.missionId === mission.id) delete state.mergeIntent
     mission.status = 'merged'
     mission.mergedAt = now
     mission.mergedCommit = mergedCommit
@@ -1389,13 +2276,15 @@ export class Tower {
       baseTip,
       branchTip,
       parents: found ? found.parents : null,
-      review: {
-        round: latest.round,
-        status: latest.status,
-        mergeVerdict: latest.mergeVerdict,
-        reviewer: latest.reviewer,
-        reviewedCommit: reviewedTip,
-      },
+      review: latest
+        ? {
+            round: latest.round,
+            status: latest.status,
+            mergeVerdict: latest.mergeVerdict,
+            reviewer: latest.reviewer,
+            reviewedCommit: reviewedTip,
+          }
+        : null,
     }
   }
 
@@ -1406,6 +2295,7 @@ export class Tower {
       if (!mission) {
         return { ok: false, blockers: [{ code: 'mission-missing', detail: `unknown mission "${input.missionId}"` }] }
       }
+      await this.reconcileMergeIntent(state, mission)
       const baseTip = await revParse(this.root, state.base)
       if (mission.status === 'merged') {
         return { ok: true, alreadyMerged: true, mergedCommit: mission.mergedCommit ?? null, baseTip }
@@ -1418,13 +2308,25 @@ export class Tower {
       const worktree = mission.worktree
       const baseTipBefore = await revParse(this.root, 'HEAD')
       const branchTip = await revParse(worktree.path, 'HEAD')
-      const timeoutMs = mergeTimeoutMs(input.timeoutMs)
+      // Record the intent before touching Git; a crash between merge and state
+      // write can be reconciled by the next tower_merge/preflight instead of
+      // leaving an unexplained base tip.
+      state.mergeIntent = {
+        missionId: mission.id,
+        baseTip: baseTipBefore,
+        branchTip,
+        startedAt: Date.now(),
+      }
+      state.revision += 1
+      state.updatedAt = state.mergeIntent.startedAt
+      await writeJsonAtomic(this.paths.state, state)
+      const timeoutMs = mergeTimeoutMs(input.timeoutMs, this.config)
       let failure = null
       try {
         await git(
           this.root,
           ['merge', '--no-ff', worktree.branch, '-m', `tower: merge ${mission.id} — ${mission.title}`],
-          { timeoutMs, maxBuffer: MERGE_MAX_BUFFER },
+          { timeoutMs, maxBuffer: this.config.merge.maxBufferBytes || MERGE_MAX_BUFFER },
         )
       } catch (error) {
         failure = error
@@ -1494,6 +2396,7 @@ export class Tower {
         }
         const detail = describeGitFailure(failure).slice(0, 2000)
         const now = Date.now()
+        delete state.mergeIntent
         if (conflict) {
           mission.status = 'blocked'
           mission.blockers.push(`merge conflict: ${detail.slice(0, 240)}`)
@@ -1521,6 +2424,10 @@ export class Tower {
       }
 
       if (!expectedShape) {
+        delete state.mergeIntent
+        state.revision += 1
+        state.updatedAt = Date.now()
+        await writeJsonAtomic(this.paths.state, state).catch(() => {})
         return {
           ok: false,
           blockers: [
@@ -1533,6 +2440,7 @@ export class Tower {
       }
 
       const now = Date.now()
+      delete state.mergeIntent
       mission.status = 'merged'
       mission.mergedAt = now
       mission.mergedCommit = newTip
@@ -1566,7 +2474,7 @@ export class Tower {
       if (!mission) fail(`unknown mission "${input.missionId}"`)
       if (!mission.worktree) fail(`mission ${mission.id} has no worktree to rebase`)
       const activity = input.activity ?? {}
-      for (const entry of (state.roster ?? []).filter((row) => row.missionId === mission.id && row.state !== 'retired')) {
+      for (const entry of (state.roster ?? []).filter((row) => row.missionId === mission.id && !ROSTER_INACTIVE.has(row.state))) {
         if (activity[entry.agentId] === 'running') {
           return { ok: false, blockers: [{ code: 'worker-busy', detail: `agent ${entry.name} is running; rebase refused` }] }
         }
@@ -1645,7 +2553,7 @@ export class Tower {
           continue
         }
         const live = (state.roster ?? []).some(
-          (entry) => entry.missionId === mission.id && entry.state !== 'retired' && activity[entry.agentId] === 'running',
+          (entry) => entry.missionId === mission.id && !ROSTER_INACTIVE.has(entry.state) && activity[entry.agentId] === 'running',
         )
         if (live) {
           decisions.push({ missionId: mission.id, action: 'keep', reason: 'live agent' })
@@ -1698,13 +2606,19 @@ export class Tower {
     })
   }
 
-  async status() {
+  async status(input = {}) {
     const state = await this.load()
     const activity = await readActivityTail(this.paths.activity, 12)
     const counts = {}
     for (const status of MISSION_STATUSES) counts[status] = 0
     for (const mission of state.missions) counts[mission.status] = (counts[mission.status] ?? 0) + 1
     const openTasks = state.missions.reduce((sum, mission) => sum + taskCounts(mission.tasks).open, 0)
+    const findingsByStatus = {}
+    for (const status of FINDING_STATUSES) findingsByStatus[status] = 0
+    for (const finding of state.findings ?? []) {
+      const status = finding.status ?? 'open'
+      findingsByStatus[status] = (findingsByStatus[status] ?? 0) + 1
+    }
     return {
       repoRoot: state.repoRoot,
       commonDir: state.commonDir,
@@ -1717,17 +2631,27 @@ export class Tower {
       messages: (state.messages ?? []).length,
       unreadTower: this.unreadFor(state, 'tower').length,
       findings: (state.findings ?? []).length,
+      findingsByStatus,
       reviews: (state.reviews ?? []).length,
+      config: {
+        path: this.config.configPath ?? null,
+        repoConfigPresent: this.config.repoConfigPresent === true,
+        spawn: {
+          workerPreset: this.config.spawn?.workerPreset ?? null,
+          reviewerPreset: this.config.spawn?.reviewerPreset ?? null,
+        },
+      },
       recentFindings: (state.findings ?? []).slice(-5).map((finding) => ({
         id: finding.id,
         type: finding.type,
         severity: finding.severity,
+        status: finding.status ?? 'open',
         title: finding.title,
         missionId: finding.missionId,
         reportedBy: finding.reportedBy,
         at: finding.at,
       })),
-      missions: await this.enrichedMissions(state),
+      missions: await this.enrichedMissions(state, input.missionIds),
       activity,
     }
   }