dsh-tower 2.0.3 → 2.1.0-beta.1

package/tools/resource.js

@@ -0,0 +1,54 @@
+// tower_resource: advisory resource leases.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { acquireLease, releaseLease, inspectLeases } from '../lib/leases.js'
+import { ResourceInput } from '../domain/contracts/tool-inputs/index.js'
+import { LEASE_ACTION } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any }} deps
+ */
+export function registerResourceTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor } = deps
+  define(ctx, {
+    name: 'tower_resource',
+    description:
+      'Advisory resource leases per repository (coordination only; no OS CPU/memory hard cap). acquire/release require a token and are tower-only; status is read-only. Expired leases are never taken over silently.',
+    parameters: ResourceInput,
+    output: output(SCHEMAS.resource),
+    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 === LEASE_ACTION.status) {
+        const info = await inspectLeases(tower.commonDir)
+        const leases = redact(info.leases ?? [])
+        return { ok: true, action: LEASE_ACTION.status, ...info, leases }
+      }
+      requireTowerActor(actor, args.action === LEASE_ACTION.acquire ? 'acquire a lease' : 'release a lease')
+      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 === LEASE_ACTION.acquire) {
+        const lease = await acquireLease(tower.commonDir, {
+          name,
+          holder: args.holder ?? actor.name,
+          token: args.token ?? crypto.randomUUID(),
+          pid: process.pid,
+          ttlMs,
+        })
+        return { ok: true, action: LEASE_ACTION.acquire, lease }
+      }
+      const token = args.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: LEASE_ACTION.release, released, leases: redact((await inspectLeases(tower.commonDir)).leases) }
+    },
+  })
+}

package/tools/review.js

@@ -0,0 +1,45 @@
+// tower_review: independent review verdict.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { ReviewInput } from '../domain/contracts/tool-inputs/index.js'
+import { isReviewerRole, isTowerRole } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any }} deps
+ */
+export function registerReviewTool(ctx, deps) {
+  const { define, actorFor } = deps
+  define(ctx, {
+    name: 'tower_review',
+    description:
+      'Submit an independent review verdict for a completed mission, bound to the current branch tip. status is "clean", "p1-Nitems", or "p2-Nitems"; merge is "merge", "fix-then-merge", or "hold" (only clean + merge is later approval). Non-clean returns the mission to active. Reviewers are capped at 5 rounds per branch; a tower-submitted review is break-glass and requires breakGlassReason.',
+    parameters: ReviewInput,
+    aliases: {"missionId":["id"]},
+    requiresMissionId: true,
+    board: true,
+    output: output(SCHEMAS.review),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      if (!isReviewerRole(actor.role) && !isTowerRole(actor.role)) {
+        throw new TowerToolError('not-authorized', `only an assigned reviewer or the tower may review; ${actor.name} is ${actor.role}`)
+      }
+      if (isTowerRole(actor.role) && (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,
+        checks: args.checks,
+        decision: args.decision,
+        breakGlassReason: args.breakGlassReason,
+      })
+    },
+  })
+}

package/tools/roster.js

@@ -0,0 +1,60 @@
+// tower_roster: authoritative roster activity.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { RosterInput } from '../domain/contracts/tool-inputs/index.js'
+import { PARENT_STATUS_OK, ROSTER_ACTIVITY, ROSTER_GONE_STATES } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool }} deps
+ */
+export function registerRosterTool(ctx, deps) {
+  const { define } = deps
+  define(ctx, {
+    name: 'tower_roster',
+    description:
+      'List tower roster agents with authoritative live activity from the subagent catalog (running/inactive/missing/unknown). Read-only; never resumes children. Use before completion or merge decisions.',
+    parameters: RosterInput,
+    output: output(SCHEMAS.roster),
+    async execute(args) {
+      const tower = await Tower.open(args.repoRoot)
+      const view = await tower.rosterView()
+      const subagents = ctx.get('subagents')
+      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()
+      const parentStatus = {}
+      for (const parent of parents) {
+        try {
+          const rows = await subagents.listDescendants(parent)
+          for (const row of rows) activity.set(String(row.id), row.activity ?? ROSTER_ACTIVITY.unknown)
+          parentStatus[parent] = PARENT_STATUS_OK
+        } catch (error) {
+          parentStatus[parent] = `unavailable: ${String(error?.message ?? error)}`
+        }
+      }
+
+      const staleMs = Number(tower.config.spawn?.staleMs) || 0
+      const now = Date.now()
+      const roster = view.roster.map((entry) => {
+        const observed = activity.get(entry.agentId)
+        const known = parentStatus[entry.parentSessionId] === PARENT_STATUS_OK
+        const stale =
+          staleMs > 0 &&
+          observed === undefined &&
+          known &&
+          !ROSTER_GONE_STATES.includes(entry.state) &&
+          now - Number(entry.spawnedAt ?? 0) > staleMs
+        return {
+          ...entry,
+          activity: observed ?? (known ? ROSTER_ACTIVITY.missing : ROSTER_ACTIVITY.unknown),
+          observed: observed !== undefined,
+          stale,
+        }
+      })
+      return { revision: view.revision, roster, parentStatus, missions: view.missions }
+    },
+  })
+}

package/tools/send.js

@@ -0,0 +1,147 @@
+// tower_send: durable inbox message delivery.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError } from '../domain/errors.js'
+import { SendInput } from '../domain/contracts/tool-inputs/index.js'
+import {
+  ROLE,
+  ROSTER_ACTIVITY,
+  isBroadcast,
+  isRunningActivity,
+  isTowerRecipient,
+  isTowerRole,
+  isUnknownRole,
+} from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{
+ *   define: import('../types/index.js').DefineTool,
+ *   actorFor: any,
+ *   checkSendRate: any,
+ * }} deps
+ */
+export function registerSendTool(ctx, deps) {
+  const { define, actorFor, checkSendRate } = deps
+  define(ctx, {
+    name: 'tower_send',
+    description:
+      'Send a durable inbox message to a tower participant: a roster agent name, "tower", or "all" (broadcast). The message is persisted first; when the recipient is a currently running roster agent the tower also steers it into that child\'s current turn. Returns delivery results.',
+    parameters: SendInput,
+    aliases: { consentRef: ['consent_ref'] },
+    output: output(SCHEMAS.send),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      checkSendRate(tower.config, args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      const view = await tower.rosterView()
+      const from = isTowerRole(actor.role) ? ROLE.tower : actor.name
+      if (isUnknownRole(actor.role)) {
+        throw new TowerToolError('not-authorized', 'tower_send requires a registered roster agent or the tower')
+      }
+      if (isBroadcast(args.to) && !isTowerRole(actor.role)) {
+        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 && !isTowerRole(actor.role)) {
+        throw new TowerToolError('not-authorized', 'only the tower may interrupt a recipient with tower_send')
+      }
+      if (!isTowerRole(actor.role)) {
+        const self = view.roster.find((entry) => entry.agentId === actor.agentId)
+        const target = view.roster.find((entry) => entry.name === args.to)
+        const allowed =
+          isTowerRecipient(args.to) ||
+          (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) {
+        throw new TowerToolError('invalid-argument', 'tower_send requires a subject')
+      }
+      if (typeof args.body !== 'string' || args.body.trim().length === 0) {
+        throw new TowerToolError('invalid-argument', 'tower_send requires a body')
+      }
+      const message = await tower.recordMessage({
+        from,
+        to: args.to,
+        subject: args.subject.trim(),
+        body: args.body,
+        scope: args.scope,
+        consentRef: args.consentRef,
+      })
+
+      const subagents = ctx.get('subagents')
+      const results = []
+      if (!subagents) {
+        results.push({ target: '*', pushed: false, reason: 'subagents service unavailable; persisted only' })
+      } else {
+        const roster = view.roster
+        const parents = [...new Set(roster.map((entry) => entry.parentSessionId).filter(Boolean))]
+        const activity = new Map()
+        for (const parent of parents) {
+          try {
+            const rows = await subagents.listDescendants(parent)
+            for (const row of rows) activity.set(String(row.id), row.activity ?? ROSTER_ACTIVITY.unknown)
+          } catch {
+            // an unreadable parent catalog only means "do not wake it"
+          }
+        }
+        const targets =
+          isBroadcast(args.to) ? roster.map((entry) => entry.name) : [args.to]
+        for (const targetName of targets) {
+          if (isTowerRecipient(targetName)) {
+            results.push({ target: ROLE.tower, pushed: false, reason: 'tower reads its inbox' })
+            continue
+          }
+          const entry = roster.find((candidate) => candidate.name === targetName)
+          if (!entry) {
+            results.push({ target: targetName, pushed: false, reason: 'not in roster' })
+            continue
+          }
+          if (!isRunningActivity(activity.get(entry.agentId))) {
+            results.push({ target: targetName, pushed: false, reason: 'not running; queued in inbox' })
+            continue
+          }
+          let interrupted = false
+          if (interrupt) {
+            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
+            }
+          }
+          try {
+            await subagents.sendMessage(
+              exec.agent,
+              entry.agentId,
+              [
+                {
+                  type: 'text',
+                  text: `[tower inbox ${message.id}] ${message.subject}\n\n${message.body}`,
+                },
+              ],
+              { signal: exec.signal },
+            )
+            results.push({ target: targetName, pushed: true, interrupted })
+          } catch (error) {
+            results.push({ target: targetName, pushed: false, reason: String(error?.message ?? error) })
+          }
+        }
+      }
+      if (results.length > 0) await tower.recordDelivery(message.id, results)
+      return {
+        message: { id: message.id, from, to: message.to, subject: message.subject },
+        deliveries: results,
+      }
+    },
+  })
+}

package/tools/spawn.js

@@ -0,0 +1,196 @@
+// tower_spawn: provision and start a worker/reviewer.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TowerToolError, classifyError } from '../domain/errors.js'
+import { SpawnInput } from '../domain/contracts/tool-inputs/index.js'
+import { DEFAULT_ROLE, ROLES as ROLE_ENUM, SPAWN_OUTCOME, isCompletedStopReason, isReviewerRole, isSpawnAdmission, isWorkerRole } from '../domain/vocabulary.js'
+import {
+  assertSpawnableMission,
+  precheckSpawnServices,
+  precheckWorkerOwnership,
+  resolveRosterName,
+} from '../lib/spawn-prechecks.js'
+import { buildAgentOptions, buildSpawnBriefing, waitForSpawnResult } from '../lib/spawn-support.js'
+
+/**
+ * @param {any} ctx
+ * @param {{
+ *   define: import('../types/index.js').DefineTool,
+ *   actorFor: any,
+ *   requireTowerActor: any,
+ *   enqueueSpawn: any,
+ *   observeActivity: any,
+ *   spawnBackoffState: any,
+ *   recordSpawnThrottle: any,
+ *   recordSpawnSuccess: any,
+ *   runMissionDiscovery: any,
+ *   textOf: any,
+ * }} deps
+ */
+export function registerSpawnTool(ctx, deps) {
+  const {
+    define, actorFor, requireTowerActor, enqueueSpawn, observeActivity,
+    spawnBackoffState, recordSpawnThrottle, recordSpawnSuccess,
+    runMissionDiscovery, textOf,
+  } = deps
+  define(ctx, {
+    name: 'tower_spawn',
+    description:
+      'Spawn a worker or reviewer for a mission. Workers use the tower-worker preset; reviewers require a completed mission and use the read-only tower-reviewer preset. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing, and starts a background subagent in that worktree. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns record the branch tip so a reviewer that modifies the branch cannot submit a review. Returns immediately unless wait=true.',
+    parameters: SpawnInput,
+    aliases: {"missionId":["id"],"waitMs":["wait_ms"]},
+    requiresMissionId: true,
+    board: true,
+    output: output(SCHEMAS.spawn),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'spawn tower agents')
+      const role = args.role ?? DEFAULT_ROLE
+      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 = isReviewerRole(role) ? config.spawn.reviewerPreset : config.spawn.workerPreset
+      const model = isReviewerRole(role) ? config.spawn.reviewerModel : config.spawn.workerModel
+      const context = await tower.missionContext(args.missionId)
+      assertSpawnableMission({ role, context })
+      const spawned = await enqueueSpawn(tower.root, async () => {
+        const observed = await observeActivity(ctx, tower)
+        await tower.reconcileObservedInactive(observed.activity)
+        const backoff = spawnBackoffState(tower.root, config.spawn.maxLiveWorkers)
+        if (backoff.blockedUntil > Date.now()) {
+          const seconds = Math.ceil((backoff.blockedUntil - Date.now()) / 1000)
+          throw new TowerToolError('provider-cooldown', `provider cooldown active; retry in ${seconds}s (${backoff.failures} recent failures)`)
+        }
+        const view = await tower.rosterView()
+        const name = resolveRosterName({ role, missionId: args.missionId, requested: args.name, roster: view.roster })
+        const takeover = await precheckWorkerOwnership({
+          role, tower, ctx, view, missionId: args.missionId, takeover: args.takeover,
+          maxLiveWorkers: config.spawn.maxLiveWorkers, budget: backoff.budget, observeActivity,
+        })
+        const { subagents, provider } = await precheckSpawnServices({ tower, ctx, config, preset, actor, exec })
+
+        const provisioned = await tower.provision({
+          missionId: args.missionId,
+          worktreeRoot: args.worktreeRoot,
+          includeDirtyBase: args.includeDirtyBase !== false,
+        })
+        const { mission, worktree } = provisioned
+        const briefing = buildSpawnBriefing({ role, towerRoot: tower.root, context, worktree, instructions: args.instructions })
+        const agentOptions = buildAgentOptions(model)
+
+        if (isWorkerRole(role) && isSpawnAdmission(tower.config.tests?.admission)) {
+          const discovery = await runMissionDiscovery(tower, mission)
+          if (discovery.configured && discovery.receipt.ok !== true) {
+            throw new TowerToolError(
+              'tests-failed',
+              `test admission failed for ${mission.id}: ${discovery.receipt.error}; no child was started`,
+            )
+          }
+        }
+
+        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,
+            label: name,
+            request: {
+              cwd: worktree.path,
+              agentPreset: preset,
+              prompt: [{ type: 'text', text: briefing }],
+              parent: exec.agent,
+              maxDepth: config.spawn.maxDepth ?? 1,
+              ...(Object.keys(agentOptions).length > 0 ? { agentOptions } : {}),
+            },
+            signal: exec.signal,
+            delivery: 'parent',
+          })
+          agentId = String(activation.childId)
+          entry = await tower.recordSpawn({
+            missionId: mission.id,
+            name,
+            role,
+            agentId,
+            parentSessionId: String(exec.agent.id),
+            cwd: worktree.path,
+            branch: worktree.branch,
+            takeover,
+          })
+          recordSpawnSuccess(tower.root, config.spawn.maxLiveWorkers)
+        } catch (error) {
+          if (classifyError(error).retryable === true) {
+            recordSpawnThrottle(tower.root, config.spawn.maxLiveWorkers)
+          }
+          // 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 {
+              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: SPAWN_OUTCOME.failed,
+              detail: `spawn failed${agentId ? ` after activation ${agentId}` : ' before activation'}: ${String(error?.message ?? error).slice(0, 300)}`,
+            })
+            .catch(() => {})
+          throw error
+        }
+
+        const recordOutcome = (state, detail) =>
+          tower.recordSpawnOutcome({ missionId: mission.id, name, state, detail }).catch(() => {})
+
+        const report = {
+          name,
+          agentId,
+          role,
+          missionId: mission.id,
+          preset,
+          provider,
+          maxDepth: config.spawn.maxDepth ?? 1,
+          ...(Object.keys(agentOptions).length > 0 ? { agentOptions } : {}),
+          worktree: { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit },
+          created: provisioned.created,
+          briefingChars: briefing.length,
+          takeover,
+          rosterEntry: entry,
+        }
+
+        return { report, activation, recordOutcome }
+      })
+      const { report, activation, recordOutcome } = spawned
+      if (args.wait !== true) {
+        activation.result
+          .then((result) => {
+            const state = isCompletedStopReason(result?.stopReason) ? SPAWN_OUTCOME.inactive : SPAWN_OUTCOME.failed
+            return recordOutcome(state, result?.diagnostic ?? result?.stopReason ?? null)
+          })
+          .catch((error) => recordOutcome(SPAWN_OUTCOME.failed, String(error?.message ?? error)))
+        return report
+      }
+      return waitForSpawnResult({
+        activation,
+        report,
+        recordOutcome,
+        maxWaitMs: config.spawn.maxWaitMs ?? 90000,
+        requestedWaitMs: args.waitMs ?? 180000,
+        textOf,
+      })
+    },
+  })
+}

package/tools/status.js

@@ -0,0 +1,94 @@
+// tower_status: dashboard and mission detail.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { classifyError } from '../domain/errors.js'
+import { StatusInput } from '../domain/contracts/tool-inputs/index.js'
+import { ROSTER_INACTIVE_STATES, isMarkdownFormat, isReservedState, isWorkerRole } from '../domain/vocabulary.js'
+
+/**
+ * @param {any} ctx
+ * @param {{
+ *   define: import('../types/index.js').DefineTool,
+ *   workspaceHook: any,
+ *   spawnBackoffView: any,
+ *   observeActivity: any,
+ * }} deps
+ */
+export function registerStatusTool(ctx, deps) {
+  const { define, workspaceHook, spawnBackoffView, observeActivity } = deps
+  define(ctx, {
+    name: 'tower_status',
+    description:
+      'Read the Tower dashboard for a repository: state path, base branch, revision, mission status counts, paged mission summaries (scope/deps/tasks/worktree/owner), roster size, findings, config path and the activity tail. Pass missionId for one full mission (tasks, notes, reviews, findings, completion report); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; format:"markdown" returns the human-readable mission board. Read-only.',
+    parameters: StatusInput,
+    aliases: { mission_id: ['missionId'], include_gate: ['includeGate'] },
+    output: output(SCHEMAS.status),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const boardPath = tower.boardFile()
+      const mode = workspaceHook?.modeInfo?.(exec) ?? null
+      const statusState = await tower.load()
+      const inflight = (statusState.roster ?? []).filter(
+        (entry) => isWorkerRole(entry.role) && !ROSTER_INACTIVE_STATES.includes(entry.state) && !isReservedState(entry.state),
+      ).length
+      const spawn = spawnBackoffView(tower.root, tower.config.spawn?.maxLiveWorkers, inflight)
+      if (args.missionId) {
+        const [status, detail] = await Promise.all([
+          tower.status({ missionIds: [args.missionId] }),
+          tower.missionDetail(args.missionId),
+        ])
+        return {
+          ...status,
+          missions: status.missions.filter((mission) => mission.id === args.missionId),
+          missionId: args.missionId,
+          detail,
+          boardPath,
+          mode,
+          spawn,
+        }
+      }
+      const state = await tower.load()
+      const total = state.missions.length
+      const offset = typeof args.offset === 'number' && Number.isInteger(args.offset) && args.offset > 0 ? args.offset : 0
+      const limit = typeof args.limit === 'number' && Number.isInteger(args.limit) ? Math.max(1, Math.min(100, args.limit)) : 20
+      const pageIds = state.missions.slice(offset, offset + limit).map((mission) => mission.id)
+      const status = await tower.status({ missionIds: pageIds })
+      let page = status.missions
+      if (args.includeGate === true) {
+        const { activity, parentStatus } = await observeActivity(ctx, tower)
+        page = await Promise.all(
+          page.map(async (mission) => {
+            try {
+              const gate = await tower.evaluateGate({ missionId: mission.id, activity, parentStatus })
+              return {
+                ...mission,
+                gate: {
+                  ok: gate.ok,
+                  blockers: (gate.blockers ?? []).map((blocker) => ({ code: blocker.code, detail: blocker.detail })),
+                },
+              }
+            } catch (error) {
+              return { ...mission, gate: { ok: false, error: classifyError(error).message } }
+            }
+          }),
+        )
+      }
+      const result = {
+        ...status,
+        missions: page,
+        total,
+        offset,
+        nextOffset: offset + page.length < total ? offset + page.length : null,
+        boardPath,
+        mode,
+        spawn,
+      }
+      if (isMarkdownFormat(args.format)) {
+        const state = await tower.load()
+        const output = /** @type {any} */ (result)
+        output.markdown = tower.boardMarkdown(state)
+      }
+      return result
+    },
+  })
+}

package/tools/teardown.js

@@ -0,0 +1,42 @@
+// tower_teardown — remove eligible mission worktrees.
+// 
+// Input: TeardownInput (dryRun, force, exclude) from contracts.
+// Output: removed/kept decisions for every mission.
+// Authorization: tower only; live agents always keep their worktree.
+// Side effects: removes worktrees/branches, persists activity.
+// Failure modes: dirty without force, branch delete failure.
+// Pure eligibility decisions live in domain/integration.
+// See docs/reference/tools.generated.md for the public shape.
+// tower_teardown: remove eligible mission worktrees.
+import { Tower } from '../app/tower.js'
+import { SCHEMAS, output } from '../domain/contracts/outputs.js'
+import { TeardownInput } from '../domain/contracts/tool-inputs/index.js'
+
+/**
+ * @param {any} ctx
+ * @param {{ define: import('../types/index.js').DefineTool, actorFor: any, requireTowerActor: any, observeActivity: any }} deps
+ */
+export function registerTeardownTool(ctx, deps) {
+  const { define, actorFor, requireTowerActor, observeActivity } = deps
+  define(ctx, {
+    name: 'tower_teardown',
+    description:
+      'Tear down eligible mission worktrees after their missions are merged or abandoned. A worktree whose roster agent is running is always kept (force cannot override); dirty worktrees need force; exclude keeps named missions. dry_run previews the remove/keep decisions without changing anything.',
+    parameters: TeardownInput,
+    aliases: {"dry_run":["dryRun"]},
+    board: true,
+    output: output(SCHEMAS.teardown),
+    async execute(args, exec) {
+      const tower = await Tower.open(args.repoRoot)
+      const actor = await actorFor(tower, exec)
+      requireTowerActor(actor, 'tear down worktrees')
+      const { activity } = await observeActivity(ctx, tower)
+      return tower.teardown({
+        force: args.force === true,
+        exclude: args.exclude,
+        dryRun: args.dry_run === true,
+        activity,
+      })
+    },
+  })
+}