dsh-tower 2.0.3 → 2.0.4

package/lib/tools.js

@@ -4,6 +4,7 @@ import { TowerToolError, classifyError } from './errors.js'
 import { git, resolveRepo, hasAnyCommit } from './git.js'
 import { runtimeConfig } from './config.js'
 import { createHmrBridge } from './hmr.js'
+import { readStateLock } from './store.js'
 import { readDiscoveryConfig, normalizeDiscovery, runDiscovery } from './tests.js'
 import { validateCreate as validateBatchCreate, validateClose as validateBatchClose, summarize as summarizeBatch, BatchError } from './batch.js'
 import { acquireLease, releaseLease, inspectLeases } from './leases.js'
@@ -248,6 +249,10 @@ const SCHEMAS = {
     ['ok', 'scheduled'],
   ),
   doctor: S.obj({ ok: S.bool, checks: S.arr(S.obj()), environmentContract: S.obj() }, ['ok', 'checks']),
+  recover: S.obj(
+    { ok: S.bool, action: S.str, stateLock: S.any, cleared: S.bool, backup: S.any, error: S.str },
+    ['ok', 'action'],
+  ),
   test: S.obj(
     {
       ok: S.bool,
@@ -298,26 +303,40 @@ function normalizeToolArgs(args, aliases = {}) {
   return out
 }
 
-function fail(message) {
-  throw new Error(message)
-}
-
-/** Resolve the calling agent to a roster role; unknown callers are the tower. */
+/** Resolve the calling agent to a roster role; unknown callers are rejected. */
 async function actorFor(tower, exec) {
   const agentId = exec?.agent?.id !== undefined ? String(exec.agent.id) : null
-  if (!agentId) return { name: 'tower', role: 'tower', agentId: null }
+  const unknown = { name: 'unknown', role: 'unknown', agentId }
+  if (!agentId) return unknown
+  let state
+  try {
+    state = await tower.load()
+  } catch (error) {
+    if (!/not initialized/i.test(String(error?.message ?? error))) throw error
+    // No readable state: only tower_init may claim ownership (handled in that tool).
+    return unknown
+  }
+  if (state.towerAgentId && String(state.towerAgentId) === agentId) {
+    return { name: 'tower', role: 'tower', agentId }
+  }
   let view
   try {
     view = await tower.rosterView()
   } catch {
-    // Before tower_init there is no state; the caller is the tower.
-    return { name: 'tower', role: 'tower', agentId }
+    return unknown
   }
   const self = view.roster.find((entry) => entry.agentId === agentId)
-  if (!self) return { name: 'tower', role: 'tower', agentId }
+  if (!self) return unknown
+  if (self.role === 'tower') return { name: self.name, role: 'tower', agentId }
   return { name: self.name, role: self.role, agentId }
 }
 
+function requireKnownActor(actor, action) {
+  if (!actor || actor.role === 'unknown') {
+    throw new TowerToolError('not-authorized', `${action} requires a registered roster agent or the tower`)
+  }
+}
+
 function requireTowerActor(actor, action) {
   if (actor.role !== 'tower') {
     throw new TowerToolError('not-authorized', `only the tower can ${action}; ${actor.name} is a ${actor.role}`)
@@ -366,6 +385,37 @@ function checkSendRate(config, repoRoot) {
   bucket.count += 1
 }
 
+async function verifyBatchReceiptFiles(root, batch, args) {
+  const problems = []
+  const frozen = new Set(batch.receiptPaths ?? [])
+  const declared = new Map()
+  for (const [rawPath, rawHash] of Object.entries(args.receiptHashes ?? {})) {
+    declared.set(String(rawPath), String(rawHash).trim().toLowerCase())
+  }
+  for (const entry of args.receipts ?? []) {
+    if (entry && typeof entry.path === 'string' && typeof entry.hash === 'string') {
+      declared.set(entry.path, entry.hash.trim().toLowerCase())
+    }
+  }
+  for (const [rel, reported] of declared) {
+    if (frozen.size > 0 && !frozen.has(rel)) continue
+    let actual
+    try {
+      const abs = path.resolve(root, rel)
+      const relative = path.relative(root, abs)
+      if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('path escapes the repository')
+      actual = crypto.createHash('sha256').update(await fsp.readFile(abs)).digest('hex')
+    } catch (error) {
+      problems.push({ code: 'batch-invalid', detail: `receipt "${rel}" cannot be read: ${String(error?.message ?? error)}` })
+      continue
+    }
+    if (reported && reported !== actual) {
+      problems.push({ code: 'batch-invalid', detail: `receipt "${rel}" hash ${reported.slice(0, 12)} does not match the file (${actual.slice(0, 12)})` })
+    }
+  }
+  return problems
+}
+
 async function interruptRosterAgent(ctx, tower, exec, input) {
   const subagents = ctx.get('subagents')
   if (!subagents || typeof subagents.interrupt !== 'function') {
@@ -459,7 +509,7 @@ function define(ctx, definition) {
         }
         if (typeof normalized.repoRoot === 'string') watchRepo(normalized.repoRoot)
         const event = rest.name.startsWith('tower_') ? rest.name.slice('tower_'.length) : null
-        if (event && !['mode', 'control', 'reload'].includes(event)) {
+        if (event) {
           try {
             ctx.emit?.(`tower/${event}`, {
               tool: rest.name,
@@ -795,10 +845,29 @@ export function registerTowerTools(ctx, options = {}) {
       const initConfig = tower.config.init ?? {}
       const snapshotDirty =
         args.snapshotDirty === true || (args.snapshotDirty === undefined && initConfig.snapshotDirty === true)
-      const actor = await actorFor(tower, exec)
-      requireTowerActor(actor, 'initialize Tower state')
+      const agentId = exec?.agent?.id !== undefined ? String(exec.agent.id) : null
+      if (!agentId) {
+        throw new TowerToolError('not-authorized', 'tower_init requires a caller agent id; refusing to treat an unidentified caller as the tower')
+      }
+      let state = null
+      try {
+        state = await tower.load()
+      } catch {
+        state = null
+      }
+      if (state?.towerAgentId) {
+        const actor = await actorFor(tower, exec)
+        requireTowerActor(actor, 'initialize Tower state')
+      } else if (state) {
+        // Legacy state predating owner binding: an explicit tower_init may
+        // claim ownership once. Other tools remain fail-closed until then.
+        const actor = await actorFor(tower, exec)
+        if (actor.role !== 'tower' && actor.role !== 'unknown') {
+          requireTowerActor(actor, 'claim Tower ownership')
+        }
+      }
       const base = args.base ?? workspaceHook?.basePreference?.(exec) ?? undefined
-      return tower.init({ base, snapshotDirty, reanchor: args.reanchor })
+      return tower.init({ base, snapshotDirty, reanchor: args.reanchor, towerAgentId: agentId })
     },
   })
 
@@ -831,7 +900,7 @@ export function registerTowerTools(ctx, options = {}) {
               reviewPolicy: {
                 type: 'string',
                 enum: ['required-clean', 'none'],
-                description: 'required-clean (default) requires a clean review before merge; none needs reviewExemptionReason and gates.allowReviewExemption.',
+                description: 'required-clean (mission default) means a clean review is required when review.requireReview is on; none needs reviewExemptionReason, and with the review gate on it also needs gates.allowReviewExemption.',
               },
               reviewExemptionReason: {
                 type: 'string',
@@ -898,6 +967,7 @@ export function registerTowerTools(ctx, options = {}) {
     async execute(args, exec) {
       const tower = await Tower.open(args.repoRoot)
       const actor = await actorFor(tower, exec)
+      requireKnownActor(actor, 'tower_mission')
       return tower.mission({
         actor,
         id: args.id,
@@ -1024,7 +1094,7 @@ export function registerTowerTools(ctx, options = {}) {
       const actor = await actorFor(tower, exec)
       requireTowerActor(actor, 'spawn tower agents')
       const role = args.role ?? 'worker'
-      if (!ROLE_ENUM.includes(role)) fail(`role must be one of ${ROLE_ENUM.join('|')}`)
+      if (!ROLE_ENUM.includes(role)) throw new TowerToolError('invalid-argument', `role must be one of ${ROLE_ENUM.join('|')}`)
       // Repository config (if any) already overrides the profile config here.
       const config = tower.config
       const preset = role === 'reviewer' ? config.spawn.reviewerPreset : config.spawn.workerPreset
@@ -1032,14 +1102,15 @@ export function registerTowerTools(ctx, options = {}) {
       const context = await tower.missionContext(args.missionId)
       if (role === 'reviewer') {
         if (!context.mission.worktree) {
-          fail('reviewer needs an existing mission worktree; spawn a worker first')
+          throw new TowerToolError('reviewer-prerequisite', 'reviewer needs an existing mission worktree; spawn a worker first')
         }
         if (context.mission.status !== 'completed') {
-          fail(`reviewer requires a completed mission awaiting review; ${context.mission.id} is ${context.mission.status}`)
+          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)) {
-        fail(
+        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`,
         )
       }
@@ -1125,15 +1196,15 @@ export function registerTowerTools(ctx, options = {}) {
         // Service/provider/preset checks happen before provisioning, so a failed
         // precheck cannot leave a worktree or roster revision behind.
         const subagents = ctx.get('subagents')
-        if (!subagents) fail('subagents service is unavailable; cannot spawn')
+        if (!subagents) throw new TowerToolError('spawn-unavailable', 'subagents service is unavailable; cannot spawn')
         const providers = subagents.list()
         const provider = config.spawn.provider || (providers.includes('spawn') ? 'spawn' : providers[0])
-        if (!provider) fail('no subagent provider is registered')
+        if (!provider) throw new TowerToolError('provider-missing', 'no subagent provider is registered')
         const presets = ctx.get('agentPresets')
         if (presets && typeof presets.list === 'function') {
           const available = await presets.list()
           if (!available.some((entry) => String(entry.id) === preset)) {
-            fail('agent preset "' + preset + '" is not registered; check the Tower bundle preset rows and restart DSH')
+            throw new TowerToolError('preset-missing', 'agent preset "' + preset + '" is not registered; check the Tower bundle preset rows and restart DSH')
           }
         }
         if (typeof config.spawn.requireLease === 'string' && config.spawn.requireLease.trim()) {
@@ -1210,6 +1281,14 @@ export function registerTowerTools(ctx, options = {}) {
         let activation = null
         let agentId = null
         let entry = null
+        await tower.reserveRoster({
+          missionId: mission.id,
+          name,
+          role,
+          parentSessionId: String(exec.agent.id),
+          cwd: worktree.path,
+          branch: worktree.branch,
+        })
         try {
           activation = await subagents.startActivation({
             provider,
@@ -1237,16 +1316,24 @@ export function registerTowerTools(ctx, options = {}) {
             takeover,
           })
         } catch (error) {
-          // The child may already be running even when recordSpawn failed (for
-          // example a race on a roster name): stop it so it cannot keep writing
-          // unobserved, then surface the real error.
+          // The child may already be running even when recordSpawn failed: stop
+          // it and mark the reserved entry failed so it cannot keep writing
+          // unobserved.
           if (agentId) {
             try {
-              subagents.interrupt(agentId, { kind: 'ancestor', agent: exec.agent })
+              await Promise.resolve(subagents.interrupt(agentId, { kind: 'ancestor', agent: exec.agent }))
             } catch {
               // best effort; the error below is the actionable one
             }
           }
+          await tower
+            .recordSpawnOutcome({
+              missionId: mission.id,
+              name,
+              state: 'failed',
+              detail: `spawn failed${agentId ? ` after activation ${agentId}` : ' before activation'}: ${String(error?.message ?? error).slice(0, 300)}`,
+            })
+            .catch(() => {})
           throw error
         }
 
@@ -1330,7 +1417,7 @@ export function registerTowerTools(ctx, options = {}) {
       const tower = await Tower.open(args.repoRoot)
       const view = await tower.rosterView()
       const subagents = ctx.get('subagents')
-      if (!subagents) fail('subagents service is unavailable; cannot observe roster')
+      if (!subagents) throw new TowerToolError('spawn-unavailable', 'subagents service is unavailable; cannot observe roster')
 
       const parents = [...new Set(view.roster.map((entry) => entry.parentSessionId).filter(Boolean))]
       const activity = new Map()
@@ -1444,7 +1531,7 @@ export function registerTowerTools(ctx, options = {}) {
       requireTowerActor(actor, 'adopt the roster')
       const view = await tower.rosterView()
       const subagents = ctx.get('subagents')
-      if (!subagents) fail('subagents service is unavailable; cannot adopt')
+      if (!subagents) throw new TowerToolError('spawn-unavailable', 'subagents service is unavailable; cannot adopt')
 
       const parents = [...new Set(view.roster.map((entry) => entry.parentSessionId).filter(Boolean))]
       const activity = new Map()
@@ -1460,11 +1547,19 @@ export function registerTowerTools(ctx, options = {}) {
       }
 
       const retiredCandidates = []
+      const presentIds = []
+      const absentIds = []
       for (const entry of view.roster) {
         if (entry.state === 'retired') continue
         if (parentStatus[entry.parentSessionId] !== 'ok') continue
-        if (!activity.has(entry.agentId)) retiredCandidates.push(entry.agentId)
+        if (activity.has(entry.agentId)) {
+          presentIds.push(entry.agentId)
+        } else {
+          absentIds.push(entry.agentId)
+        }
       }
+      const observations = await tower.recordRosterObservations({ present: presentIds, absent: absentIds, confirmations: 2 })
+      retiredCandidates.push(...observations.candidates)
       const retireMissing = args.retireMissing !== false
       const { retired } = retireMissing ? await tower.markRetired(retiredCandidates) : { retired: [] }
       const { missing } = retireMissing ? { missing: [] } : await tower.markMissing(retiredCandidates)
@@ -1472,6 +1567,7 @@ export function registerTowerTools(ctx, options = {}) {
       return {
         retired,
         missing,
+        unconfirmed: absentIds.filter((agentId) => !retiredCandidates.includes(agentId)),
         skippedUnknownParents: Object.entries(parentStatus)
           .filter(([, status]) => status !== 'ok')
           .map(([parent]) => parent),
@@ -1511,11 +1607,33 @@ export function registerTowerTools(ctx, options = {}) {
       const actor = await actorFor(tower, exec)
       const view = await tower.rosterView()
       const from = actor.role === 'tower' ? 'tower' : actor.name
+      if (actor.role === 'unknown') {
+        throw new TowerToolError('not-authorized', 'tower_send requires a registered roster agent or the tower')
+      }
+      if (args.to === 'all' && actor.role !== 'tower') {
+        throw new TowerToolError('not-authorized', 'only the tower may broadcast to "all"')
+      }
+      const sendConfig = tower.config.send ?? {}
+      const interrupt =
+        args.interrupt === undefined ? sendConfig.interruptDefault === true : args.interrupt === true
+      if (interrupt && actor.role !== 'tower') {
+        throw new TowerToolError('not-authorized', 'only the tower may interrupt a recipient with tower_send')
+      }
+      if (actor.role !== 'tower') {
+        const self = view.roster.find((entry) => entry.agentId === actor.agentId)
+        const target = view.roster.find((entry) => entry.name === args.to)
+        const allowed =
+          args.to === 'tower' ||
+          (self && target && target.agentId !== self.agentId && target.missionId === self.missionId)
+        if (!allowed) {
+          throw new TowerToolError('not-authorized', `${actor.name} may only message the tower or agents on the same mission`)
+        }
+      }
       if (typeof args.subject !== 'string' || args.subject.trim().length === 0) {
-        fail('tower_send requires a subject')
+        throw new TowerToolError('invalid-argument', 'tower_send requires a subject')
       }
       if (typeof args.body !== 'string' || args.body.trim().length === 0) {
-        fail('tower_send requires a body')
+        throw new TowerToolError('invalid-argument', 'tower_send requires a body')
       }
       const message = await tower.recordMessage({
         from,
@@ -1542,9 +1660,6 @@ export function registerTowerTools(ctx, options = {}) {
             // an unreadable parent catalog only means "do not wake it"
           }
         }
-        const sendConfig = tower.config.send ?? {}
-        const interrupt =
-          args.interrupt === undefined ? sendConfig.interruptDefault === true : args.interrupt === true
         const targets =
           args.to === 'all' ? roster.map((entry) => entry.name) : [args.to]
         for (const targetName of targets) {
@@ -1566,6 +1681,10 @@ export function registerTowerTools(ctx, options = {}) {
             try {
               subagents.interrupt(entry.agentId, { kind: 'ancestor', agent: exec.agent })
               interrupted = true
+              await tower.recordInterrupt({
+                agentId: entry.agentId,
+                reason: `tower_send${message?.id ? ` ${message.id}` : ''}: ${args.subject.trim().slice(0, 120)}`,
+              })
             } catch (error) {
               results.push({ target: targetName, pushed: false, reason: `interrupt failed: ${String(error?.message ?? error)}` })
               continue
@@ -1626,7 +1745,7 @@ export function registerTowerTools(ctx, options = {}) {
   define(ctx, {
     name: 'tower_complete',
     description:
-      'Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base, and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. Stores the full report; completion means awaiting review, not merged.',
+      'Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base, and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. Stores the full report; completion means ready for preflight and optional review, not merged.',
     parameters: {
       type: 'object',
       properties: {
@@ -1714,6 +1833,8 @@ export function registerTowerTools(ctx, options = {}) {
     output: output(SCHEMAS.finding),
     async execute(args, exec) {
       const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireKnownActor(actor, 'tower_finding')
       const view = await tower.rosterView()
       const self = view.roster.find((entry) => entry.agentId === String(exec.agent.id))
       return tower.addFinding({
@@ -1759,6 +1880,8 @@ export function registerTowerTools(ctx, options = {}) {
     output: output(SCHEMAS.findings),
     async execute(args, exec) {
       const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireKnownActor(actor, 'tower_findings')
       const view = await tower.rosterView()
       const self = view.roster.find((entry) => entry.agentId === String(exec.agent.id))
       return tower.findings({
@@ -1801,9 +1924,17 @@ export function registerTowerTools(ctx, options = {}) {
     output: output(SCHEMAS.review),
     async execute(args, exec) {
       const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      if (!['reviewer', 'tower'].includes(actor.role)) {
+        throw new TowerToolError('not-authorized', `only an assigned reviewer or the tower may review; ${actor.name} is ${actor.role}`)
+      }
+      if (actor.role === 'tower' && (typeof args.breakGlassReason !== 'string' || args.breakGlassReason.trim().length === 0)) {
+        throw new TowerToolError('not-authorized', 'a tower-submitted review is break-glass and requires a non-empty breakGlassReason')
+      }
       return tower.submitReview({
         missionId: args.missionId,
         agentId: String(exec.agent.id),
+        actor,
         status: args.status,
         merge: args.merge,
         findings: args.findings,
@@ -1817,7 +1948,7 @@ export function registerTowerTools(ctx, options = {}) {
   define(ctx, {
     name: 'tower_preflight',
     description:
-      'Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, read-only-survey, stale-base, no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards). Never changes anything.',
+      'Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, read-only-survey, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.requireReview is on. Never changes anything.',
     parameters: {
       type: 'object',
       properties: {
@@ -1963,10 +2094,72 @@ export function registerTowerTools(ctx, options = {}) {
       additionalProperties: false,
     },
     output: output(SCHEMAS.doctor),
+    async execute(args, exec) {
+      let tower
+      let configError = null
+      try {
+        tower = await Tower.open(args.repoRoot)
+      } catch (error) {
+        const message = String(error?.message ?? error)
+        if (!/config-(invalid|unknown-key)/.test(message) && error?.code !== 'config-invalid' && error?.code !== 'config-unknown-key') throw error
+        configError = message
+        const repo = await resolveRepo(args.repoRoot)
+        tower = new Tower(repo, { ...runtimeConfig(), configPath: null, repoConfigPresent: true })
+      }
+      const report = await runDoctor({ tower, ctx, agent: exec.agent })
+      if (!configError) return report
+      return {
+        ...report,
+        ok: false,
+        checks: [
+          {
+            id: 'config',
+            status: 'fail',
+            detail: configError,
+            fix: 'repair <git-common-dir>/dsh-tower/config.json and re-run tower_doctor',
+          },
+          ...(report.checks ?? []),
+        ],
+      }
+    },
+  })
+
+  define(ctx, {
+    name: 'tower_recover',
+    description:
+      'Read-only recovery diagnostics and an explicit stale-state-lock repair. status reports the state lock owner; clear-stale-lock requires confirm:"CLEAR_STALE_LOCK" and only moves a lock whose PID is provably dead to a backup file. It never resets Tower state or worktrees.',
+    parameters: {
+      type: 'object',
+      properties: {
+        repoRoot: { type: 'string', description: 'Absolute path inside the target Git repository.' },
+        action: { type: 'string', enum: ['status', 'clear-stale-lock'], description: 'Recovery action.' },
+        confirm: { type: 'string', description: 'Required literal CLEAR_STALE_LOCK for clear-stale-lock.' },
+      },
+      required: ['repoRoot', 'action'],
+      additionalProperties: false,
+    },
+    output: output(SCHEMAS.recover),
     async execute(args, exec) {
       const tower = await Tower.open(args.repoRoot)
-      await actorFor(tower, exec)
-      return runDoctor({ tower, ctx, agent: exec.agent })
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'recover Tower state')
+      const lock = await readStateLock(tower.paths)
+      const publicLock = lock.record
+        ? { pid: lock.record.pid ?? null, startedAt: lock.record.startedAt ?? null, at: lock.record.at ?? null, alive: lock.alive }
+        : null
+      if (args.action === 'status') {
+        return { ok: true, action: 'status', stateLock: publicLock, cleared: false }
+      }
+      if (args.confirm !== 'CLEAR_STALE_LOCK') {
+        throw new TowerToolError('invalid-argument', 'clear-stale-lock requires confirm:"CLEAR_STALE_LOCK"')
+      }
+      if (!lock.record) return { ok: true, action: 'clear-stale-lock', stateLock: null, cleared: false }
+      if (lock.alive !== false) {
+        throw new TowerToolError('state-locked', `state lock pid ${lock.record.pid ?? 'unknown'} is still alive; refusing to clear it`)
+      }
+      const backup = `${tower.paths.lock}.recovered-${Date.now()}`
+      await fsp.rename(tower.paths.lock, backup)
+      return { ok: true, action: 'clear-stale-lock', stateLock: publicLock, cleared: true, backup }
     },
   })
 
@@ -1990,11 +2183,12 @@ export function registerTowerTools(ctx, options = {}) {
     async execute(args, exec) {
       const tower = await Tower.open(args.repoRoot)
       const actor = await actorFor(tower, exec)
+      requireKnownActor(actor, 'tower_test')
       const context = await tower.missionContext(args.missionId)
-      if (!context.mission.worktree) fail(`mission ${args.missionId} has no worktree`)
-      if (actor.role === 'reviewer') fail('reviewers may not run test discovery')
+      if (!context.mission.worktree) throw new TowerToolError('invalid-transition', `mission ${args.missionId} has no worktree`)
+      if (actor.role === 'reviewer') throw new TowerToolError('not-authorized', 'reviewers may not run test discovery')
       if (actor.role === 'worker' && context.mission.owner && context.mission.owner !== actor.name) {
-        fail(`worker ${actor.name} does not own mission ${args.missionId}`)
+        throw new TowerToolError('not-authorized', `worker ${actor.name} does not own mission ${args.missionId}`)
       }
       await tower.assertWorktree(context.mission.worktree)
       const discovery = await runMissionDiscovery(tower, context.mission)
@@ -2053,7 +2247,7 @@ export function registerTowerTools(ctx, options = {}) {
         const batch = args.batchId
           ? (state.batches ?? []).find((entry) => entry.id === args.batchId)
           : null
-        if (args.batchId && !batch) fail(`unknown batch "${args.batchId}"`)
+        if (args.batchId && !batch) throw new TowerToolError('invalid-argument', `unknown batch "${args.batchId}"`)
         return {
           ok: true,
           action: 'status',
@@ -2068,12 +2262,20 @@ export function registerTowerTools(ctx, options = {}) {
         return { ok: true, action: 'create', batch, batches: (await tower.batchStatus()).batches }
       }
       if (typeof args.batchId !== 'string' || args.batchId.trim().length === 0) {
-        fail(`tower_batch ${args.action} requires batchId`)
+        throw new TowerToolError('invalid-argument', `tower_batch ${args.action} requires batchId`)
       }
       if (args.action === 'abandon') {
         const result = await tower.abandonBatch(args.batchId.trim(), actor.name, args.reason)
         return { ok: true, action: 'abandon', batch: result.batch, blockers: [] }
       }
+      const closeState = await tower.load()
+      const closeBatch = (closeState.batches ?? []).find((entry) => entry.id === args.batchId.trim())
+      if (closeBatch) {
+        const receiptProblems = await verifyBatchReceiptFiles(tower.root, closeBatch, args)
+        if (receiptProblems.length > 0) {
+          return { ok: false, action: 'close', batch: closeBatch, blockers: receiptProblems, checks: [] }
+        }
+      }
       const result = await tower.closeBatch(args.batchId.trim(), {
         checks: args.checks,
         treeTip: args.treeTip,
@@ -2116,12 +2318,16 @@ export function registerTowerTools(ctx, options = {}) {
     async execute(args, exec) {
       const tower = await Tower.open(args.repoRoot)
       const actor = await actorFor(tower, exec)
+      const redact = (leases) => leases.map(({ token, ...lease }) => lease)
       if (args.action === 'status') {
         const info = await inspectLeases(tower.commonDir)
-        return { ok: true, action: 'status', leases: info.leases, ...info }
+        const leases = redact(info.leases ?? [])
+        return { ok: true, action: 'status', ...info, leases }
       }
       requireTowerActor(actor, args.action === 'acquire' ? 'acquire a lease' : 'release a lease')
-      if (typeof args.name !== 'string' || args.name.trim().length === 0) fail('tower_resource requires name')
+      if (typeof args.name !== 'string' || args.name.trim().length === 0) {
+        throw new TowerToolError('invalid-argument', 'tower_resource requires name')
+      }
       const name = args.name.trim()
       const ttlMs = Number(args.ttlMs ?? tower.config.leases?.ttlMs ?? 900000)
       if (args.action === 'acquire') {
@@ -2135,9 +2341,11 @@ export function registerTowerTools(ctx, options = {}) {
         return { ok: true, action: 'acquire', lease }
       }
       const token = args.token
-      if (typeof token !== 'string' || token.length === 0) fail('tower_resource release requires token')
+      if (typeof token !== 'string' || token.length === 0) {
+        throw new TowerToolError('invalid-argument', 'tower_resource release requires token')
+      }
       const released = await releaseLease(tower.commonDir, { name, token, force: args.force === true })
-      return { ok: true, action: 'release', released, leases: (await inspectLeases(tower.commonDir)).leases }
+      return { ok: true, action: 'release', released, leases: redact((await inspectLeases(tower.commonDir)).leases) }
     },
   })
 
@@ -2196,7 +2404,9 @@ export function registerTowerTools(ctx, options = {}) {
       }
       requireTowerActor(actor, 'map a legacy mission')
       const validation = validateLegacyMap(state, args)
-      if (validation.ok !== true) fail(validation.error ?? 'invalid legacy mapping')
+      if (validation.ok !== true) {
+        throw new TowerToolError('invalid-argument', validation.error ?? 'invalid legacy mapping')
+      }
       const map = { ...validation.map, by: actor.name, at: Date.now() }
       const recorded = await tower.recordLegacyMap(map)
       return { ok: true, map: recorded.map, maps: [...(state.legacyMaps ?? []), recorded.map] }