@ucsandman/legcli 0.7.0

package/src/live-capture.mjs

@@ -0,0 +1,69 @@
+// live-capture — the first time a real limit signal arrives from an agent
+// (claude StopFailure, codex usage_limit_exceeded, agy RESOURCE_EXHAUSTED),
+// keep the payload with secrets scrubbed, so the docs rows that say
+// "docs-only" can become "observed-live" with evidence. One file per
+// (agent, signal); a later arrival never overwrites the first. A payload a
+// `baton sessions simulate-limit` produced is marked and never captured.
+// Where: BATON_LIVE_DIR, else this checkout's fixtures/live/ when it exists
+// (a dev clone), else <BATON_HOME>/live/. In a dev clone the matching docs
+// rows are flipped in the same call (scripts/live-limits.mjs).
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { homedir } from 'node:os'
+import { spawnSync } from 'node:child_process'
+import { redact } from './redact.mjs'
+import { home } from './store.mjs'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const FIXTURES_LIVE = join(ROOT, 'fixtures', 'live')
+const FLIP_SCRIPT = join(ROOT, 'scripts', 'live-limits.mjs')
+
+// A real limit payload (claude StopFailure, codex, agy) carries cwd,
+// transcript_path and scratchpad_dir. redact() strips secret shapes and the
+// values of the well-known key variables this process holds; this also folds
+// the home and repo roots to placeholders (in every slash form, including the
+// doubled backslashes JSON escaping produces) so nothing path-shaped is written
+// into a git-tracked fixtures/live/ file.
+function redactPaths(s) {
+  let out = redact(String(s))
+  for (const [root, tag] of [[homedir(), '[redacted-home]'], [ROOT, '[redacted-repo]']]) {
+    if (!root) continue
+    for (const variant of [root.replace(/\\/g, '\\\\'), root.replace(/\\/g, '/'), root]) out = out.split(variant).join(tag)
+  }
+  return out
+}
+
+export function liveDir() {
+  if (process.env.LEG_LIVE_DIR || process.env.BATON_LIVE_DIR) return process.env.LEG_LIVE_DIR || process.env.BATON_LIVE_DIR
+  if (existsSync(FIXTURES_LIVE) && existsSync(join(ROOT, '.git'))) return FIXTURES_LIVE
+  return join(home(), 'live')
+}
+
+export function isSimulated(payload) {
+  if (payload && typeof payload === 'object' && (payload.leg_simulated || payload.baton_simulated)) return true
+  return /simulated by (?:leg|baton)/i.test(typeof payload === 'string' ? payload : JSON.stringify(payload ?? ''))
+}
+
+export function livePath(agent, signal, dir = liveDir()) {
+  return join(dir, agent, `limit-${String(signal).replace(/[^a-z0-9_-]+/gi, '_')}.json`)
+}
+
+// → { path, written: bool } | null (simulated, or nothing to keep)
+export function captureLive(agent, signal, payload, { sessionId = null, flipDocs = true } = {}) {
+  if (!agent || !signal || payload === undefined || isSimulated(payload)) return null
+  const dir = liveDir()
+  const file = livePath(agent, signal, dir)
+  if (existsSync(file)) return { path: file, written: false }
+  mkdirSync(dirname(file), { recursive: true })
+  const record = {
+    agent, signal, captured_at: new Date().toISOString(), session_id: sessionId,
+    source: 'observed-live',
+    payload: JSON.parse(redactPaths(JSON.stringify(payload))),
+  }
+  writeFileSync(file, JSON.stringify(record, null, 2) + '\n')
+  if (flipDocs && dir === FIXTURES_LIVE) {
+    try { spawnSync(process.execPath, [FLIP_SCRIPT], { windowsHide: true, encoding: 'utf8', timeout: 8000 }) } catch {}
+  }
+  return { path: file, written: true }
+}

package/src/mergequeue.mjs

@@ -0,0 +1,225 @@
+// mergequeue — the land station. One land at a time per repo root, FIFO: the
+// queue key is the canonical root (two spellings of one path are one queue) and
+// the turn itself is a file lock under BATON_HOME, so a `baton card run` CLI
+// and the board server cannot land into one checkout at the same time.
+// land(card, worktree):
+//   1. root must be on <trunk> and clean, else bounce `dirty-trunk` (root untouched)
+//   1b. commit whatever the agents left uncommitted in the worktree
+//   2. rebase the card branch onto trunk in the worktree; abort + bounce `rebase-conflict` with the file list, or `rebase-failed` when git failed for another reason
+//   3. run the test command (card.test_command → package.json test → pytest → none + land_warning); red → bounce `tests-red` with the tail
+//   4. from the root: git merge --ff-only baton/<id>; trunk moved meanwhile → one retry, then bounce `trunk-moved`
+//   5. success → { landed, sha, files, insertions, deletions, duration_ms }
+// No force flags, no remote writes, no hard resets on the root, ever.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { createHash } from 'node:crypto'
+import { branchName } from './worktree.mjs'
+import { runCommandAsync } from './commands.mjs'
+import { canonPath, withFileLock, writeJsonAtomic } from './fsx.mjs'
+import { home } from './store.mjs'
+
+const TEST_TIMEOUT_MS = Number((process.env.LEG_LAND_TEST_TIMEOUT_MS || process.env.BATON_LAND_TEST_TIMEOUT_MS) || 600000)
+const queues = new Map() // canonical repo root → tail promise
+// A turn covers the commit, the rebase and the repo's whole test run, so a
+// claim is only stale once its holder died: the test budget plus the git work
+// around it. The guard lock around the claim file protects two file writes and
+// keeps a short staleness of its own.
+const LOCK_STALE_MS = TEST_TIMEOUT_MS + 120000
+const LOCK_GUARD_STALE_MS = 5000
+const LOCK_POLL_MS = 250
+
+function git(cwd, args, { ok = true } = {}) {
+  const r = spawnSync('git', args, { cwd, windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+  if (ok && r.status !== 0) throw new Error(`git ${args.join(' ')} failed (exit ${r.status}): ${(r.stderr || r.stdout).trim().slice(0, 500)}`)
+  return r
+}
+
+// A rebase/merge/cherry-pick the agent or a human left mid-flight. Landing must
+// never commit that half-state and must never abort an operation it did not
+// start (aborting a rebase throws away the uncommitted work sitting on it).
+function operationInProgress(worktree) {
+  for (const p of ['rebase-merge', 'rebase-apply', 'MERGE_HEAD', 'CHERRY_PICK_HEAD']) {
+    const rel = git(worktree, ['rev-parse', '--git-path', p], { ok: false }).stdout.trim()
+    if (rel && existsSync(resolve(worktree, rel))) return p
+  }
+  return null
+}
+
+export function trunkHead(repo) {
+  return git(repo, ['rev-parse', 'HEAD']).stdout.trim()
+}
+
+export function rootState(repo, trunk) {
+  const branch = git(repo, ['symbolic-ref', '--short', '-q', 'HEAD'], { ok: false }).stdout.trim() || 'DETACHED'
+  const dirty = git(repo, ['status', '--porcelain']).stdout.split(/\r?\n/).filter(Boolean)
+  return { branch, onTrunk: branch === trunk, dirty }
+}
+
+// Commit the agents' work so the branch can be rebased and merged. The commit
+// skips git hooks (--no-verify): the repo's test command is Baton's gate, and
+// interactive commit hooks (linters, wire-dark style checks) belong to humans
+// typing commits. BATON_COMMIT_VERIFY=1 runs them anyway.
+export function commitWorktree(worktree, message) {
+  const dirty = git(worktree, ['status', '--porcelain']).stdout.split(/\r?\n/).filter(Boolean)
+  if (!dirty.length) return { committed: false }
+  git(worktree, ['add', '-A'])
+  const verify = (process.env.LEG_COMMIT_VERIFY || process.env.BATON_COMMIT_VERIFY) === '1' ? [] : ['--no-verify']
+  git(worktree, ['-c', 'user.email=baton@localhost', '-c', 'user.name=baton', 'commit', '-q', ...verify, '-m', message])
+  return { committed: true, files: dirty.length }
+}
+
+export function resolveTestCommand(card, worktree) {
+  if (card.test_command) return { command: card.test_command, source: 'card' }
+  const pkg = join(worktree, 'package.json')
+  if (existsSync(pkg)) {
+    try {
+      const p = JSON.parse(readFileSync(pkg, 'utf8'))
+      if (p.scripts?.test) return { command: 'npm test', source: 'package.json' }
+    } catch {}
+  }
+  if (existsSync(join(worktree, 'pyproject.toml'))) return { command: 'pytest', source: 'pyproject.toml' }
+  return { command: null, source: 'none' }
+}
+
+function runTests(command, worktree) {
+  return runCommandAsync(command, worktree, { timeoutMs: TEST_TIMEOUT_MS, tailLines: 40 })
+}
+
+function bounce(reason, detail, extra = {}) {
+  return { landed: false, bounced: true, reason, detail, ...extra }
+}
+
+// A non-zero `git rebase` is a conflict only when git names unmerged files.
+// Anything else (a hook that refuses, an upstream git cannot use) is a
+// different failure, and the bounce reason is the next agent's brief: it must
+// never read as a conflict in files git never mentioned.
+function rebaseBounce(worktree, trunk, result, preSha, when) {
+  const files = git(worktree, ['diff', '--name-only', '--diff-filter=U'], { ok: false }).stdout.split(/\r?\n/).filter(Boolean)
+  git(worktree, ['rebase', '--abort'], { ok: false })
+  const detail = (result.stderr || result.stdout).trim().slice(0, 300)
+  if (files.length) return bounce('rebase-conflict', `rebase onto ${trunk}${when} conflicted in: ${files.join(', ')}`, { files, pre_sha: preSha })
+  return bounce('rebase-failed', `rebase onto ${trunk}${when} failed: ${detail || '(no git output)'}`, { files, pre_sha: preSha })
+}
+
+function claimFile(key) {
+  const dir = join(home(), 'locks')
+  mkdirSync(dir, { recursive: true })
+  return join(dir, `land-${createHash('sha1').update(key).digest('hex').slice(0, 16)}.json`)
+}
+
+function claimHolder(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return null }
+}
+
+// withFileLock guards the read-modify-write of the claim; the claim it leaves
+// behind outlives that guard, which is what makes the turn last a whole land.
+function takeTurn(file, token) {
+  return withFileLock(`${file}.lock`, () => {
+    const held = claimHolder(file)
+    if (held && held.token !== token && Date.now() - held.ts < LOCK_STALE_MS) return false
+    writeJsonAtomic(file, { token, pid: process.pid, ts: Date.now() })
+    return true
+  }, { staleMs: LOCK_GUARD_STALE_MS })
+}
+
+function dropTurn(file, token) {
+  withFileLock(`${file}.lock`, () => {
+    const held = claimHolder(file)
+    if (!held || held.token === token) { try { unlinkSync(file) } catch {} }
+  }, { staleMs: LOCK_GUARD_STALE_MS })
+}
+
+async function withRepoTurn(repo, fn) {
+  const file = claimFile(canonPath(repo))
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+  while (!takeTurn(file, token)) await new Promise((r) => setTimeout(r, LOCK_POLL_MS))
+  try { return await fn() } finally { dropTurn(file, token) }
+}
+
+async function landNow(card, worktree, { onWarning = () => {}, allowDirtyRoot = false } = {}) {
+  const t0 = Date.now()
+  const repo = card.repo
+  const trunk = card.trunk || 'main'
+  const branch = branchName(card.card_id)
+
+  const checkedOut = git(worktree, ['symbolic-ref', '--short', '-q', 'HEAD'], { ok: false }).stdout.trim() || 'DETACHED'
+  if (checkedOut !== branch) return bounce('worktree-branch', `worktree is on ${checkedOut}, not ${branch}; switch it back before landing`)
+
+  const busy = operationInProgress(worktree)
+  if (busy) return bounce('worktree-busy', `a ${busy.replace(/-/g, ' ')} is already in progress in ${worktree}; finish or abort it there before landing (Baton will not touch a rebase it did not start)`)
+
+  const root = rootState(repo, trunk)
+  if (!root.onTrunk) return bounce('dirty-trunk', `repo root is on ${root.branch}, not ${trunk}; check out ${trunk} and retry`)
+  // allowDirtyRoot (a terminal's Land): the root is a live checkout, dirty by
+  // nature; git's own fast-forward still refuses to overwrite a local change
+  if (root.dirty.length && !allowDirtyRoot) return bounce('dirty-trunk', `repo root has ${root.dirty.length} uncommitted change(s): ${root.dirty.slice(0, 10).join(', ')}`)
+
+  const committed = commitWorktree(worktree, `baton: ${card.title ?? card.card_id}`)
+  const preSha = git(worktree, ['rev-parse', 'HEAD']).stdout.trim()
+  const trunkBefore = trunkHead(repo)
+
+  const rebase = git(worktree, ['rebase', trunk], { ok: false })
+  if (rebase.status !== 0) return rebaseBounce(worktree, trunk, rebase, preSha, '')
+
+  const tc = resolveTestCommand(card, worktree)
+  let tests = null
+  if (!tc.command) {
+    onWarning(`no test command (card, package.json, pyproject.toml); landing untested`)
+  } else {
+    tests = await runTests(tc.command, worktree)
+    if (!tests.green) {
+      return bounce('tests-red', `${tests.command} exit ${tests.status}${tests.timedOut ? ' (timed out)' : ''}:\n${tests.tail}`, { test_tail: tests.tail, pre_sha: preSha })
+    }
+  }
+
+  let merge = git(repo, ['merge', '--ff-only', branch], { ok: false })
+  let retried = false
+  if (merge.status !== 0 && trunkHead(repo) !== trunkBefore) {
+    // trunk moved while we tested: rebase once more and retry the ff
+    retried = true
+    const again = git(worktree, ['rebase', trunk], { ok: false })
+    if (again.status !== 0) return rebaseBounce(worktree, trunk, again, preSha, ` after ${trunk} moved`)
+    if (tc.command) {
+      tests = await runTests(tc.command, worktree)
+      if (!tests.green) {
+        return bounce('tests-red', `${tests.command} exit ${tests.status}${tests.timedOut ? ' (timed out)' : ''} after ${trunk} moved:\n${tests.tail}`, { test_tail: tests.tail, pre_sha: preSha })
+      }
+    }
+    merge = git(repo, ['merge', '--ff-only', branch], { ok: false })
+  }
+  if (merge.status !== 0 && /would be overwritten by merge/.test(merge.stderr || merge.stdout)) {
+    const files = (merge.stderr || merge.stdout).split(/\r?\n/).filter((l) => /^\s+\S/.test(l)).map((l) => l.trim())
+    return bounce('dirty-trunk', `the ${trunk} checkout has local changes this landing would overwrite: ${files.join(', ') || '(see git output)'}`, { files })
+  }
+  if (merge.status !== 0) {
+    return bounce('trunk-moved', `fast-forward of ${trunk} failed${retried ? ' after one retry' : ''}: ${(merge.stderr || merge.stdout).trim().slice(0, 300)}`, { retried })
+  }
+  const sha = trunkHead(repo)
+  const stat = git(repo, ['diff', '--shortstat', `${trunkBefore}..${sha}`], { ok: false }).stdout.trim()
+  const files = git(repo, ['diff', '--name-only', `${trunkBefore}..${sha}`], { ok: false }).stdout.split(/\r?\n/).filter(Boolean)
+  const m = /(\d+) insertion/.exec(stat)
+  const d = /(\d+) deletion/.exec(stat)
+  return {
+    landed: true, sha, sha_before: trunkBefore, files, insertions: m ? Number(m[1]) : 0, deletions: d ? Number(d[1]) : 0,
+    duration_ms: Date.now() - t0, retried, committed: committed.committed, tests: tests ? { command: tests.command, tail: tests.tail.split('\n').slice(-3).join(' | ') } : null,
+    summary: `landed on ${trunk}: ${trunkBefore.slice(0, 7)} → ${sha.slice(0, 7)} (${files.length} file${files.length === 1 ? '' : 's'}, +${m ? m[1] : 0}/-${d ? d[1] : 0})${tests ? '' : ' [untested]'}`,
+    body: JSON.stringify({ sha, files, insertions: m ? Number(m[1]) : 0, deletions: d ? Number(d[1]) : 0, duration_ms: Date.now() - t0, retried, tests: tests?.command ?? null }),
+  }
+}
+
+// FIFO per repo root: the caller awaits its turn, here and in every other
+// process landing into the same root.
+export function land(card, worktree, opts) {
+  const key = canonPath(card.repo)
+  const prev = queues.get(key) ?? Promise.resolve()
+  const mine = prev.catch(() => {}).then(() => withRepoTurn(card.repo, () => landNow(card, worktree, opts)))
+  queues.set(key, mine)
+  // the bookkeeping chain must never reject on its own: landNow's throw is the
+  // caller's to handle (it returns `mine`), and an unhandled rejection here
+  // would take the whole board server process down with it
+  mine.catch(() => {}).finally(() => { if (queues.get(key) === mine) queues.delete(key) })
+  return mine
+}
+
+export function isLanding(repo) { return queues.has(canonPath(repo)) }

package/src/orchestrator.mjs

@@ -0,0 +1,365 @@
+// orchestrator — moves one card through its pipeline: worktree, contract,
+// runner legs, classification (from run.json), chain transitions, handoff
+// bundles, test and (stub) land stations. Every state change goes through the
+// ledger with an actor; the chain machine (src/chain.mjs) decides, this file
+// only executes.
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { transition } from './chain.mjs'
+import { stationIndex } from './pipeline.mjs'
+import { ensure as ensureWorktree } from './worktree.mjs'
+import { renderContract, writeContract, legPrompt } from './contract.mjs'
+import { writeHandoff, loadResume } from './handoff.mjs'
+import { runCommandAsync } from './commands.mjs'
+import { landCard } from './land.mjs'
+import { resolveTestCommand } from './mergequeue.mjs'
+import {
+  RUNNER, BATON_ACTOR, readCard, ledgerAppend, ledgerUpdate, cardDir, sleep,
+} from './store.mjs'
+import { scrub, updateRun } from './runner.mjs'
+import * as agentStation from './stations/agent.mjs'
+import * as testStation from './stations/test.mjs'
+import * as humanStation from './stations/human.mjs'
+
+// Station kinds that run inside runCard; land stays inline below (it drives
+// the merge queue). Each handler gets the orchestrator's helpers as `ops`.
+const KIND_HANDLERS = { agent: agentStation, test: testStation, human: humanStation }
+
+const POLL_MS = Number(process.env.BATON_POLL_MS || 2000)
+const WAITING = ['done', 'failed', 'killed', 'paused', 'waiting_human', 'needs_approval']
+// Patchable card keys the chain machine may change; everything else is a
+// named ledger flag.
+const PATCH_KEYS = ['pipeline', 'leases', 'land_attempts', 'bounce_reason', 'kill_requested', 'next_leg', 'handoff_outcome', 'resume_from_bundle', 'failure', 'pr_url']
+
+const log = (msg) => { if (process.env.BATON_QUIET !== '1') process.stderr.write(`[baton] ${msg}\n`) }
+
+// Persist a chain transition: card fields via ledger update, events via append.
+export function apply(id, before, result, actor = BATON_ACTOR) {
+  const next = result.card
+  const patch = {}
+  for (const k of PATCH_KEYS) {
+    if (JSON.stringify(next[k]) !== JSON.stringify(before[k])) patch[k] = next[k] ?? null
+  }
+  ledgerUpdate(id, {
+    status: next.status !== before.status ? next.status : undefined,
+    station: next.station !== before.station ? next.station : undefined,
+    leg: next.leg !== before.leg ? next.leg : undefined,
+    patch,
+  })
+  for (const e of result.events) {
+    ledgerAppend(id, { actor, type: e.type, summary: e.summary, body: e.body, station: next.station, leg: next.leg })
+  }
+  return readCard(id)
+}
+
+export function step(id, action, payload, actor = BATON_ACTOR) {
+  const card = readCard(id)
+  if (!card) throw new Error(`card not found: ${id}`)
+  return apply(id, card, transition(card, action, payload), actor)
+}
+
+function runJsonPath(id, n) { return join(cardDir(id), 'runs', String(n), 'run.json') }
+
+function latestRun(id) {
+  const dir = join(cardDir(id), 'runs')
+  if (!existsSync(dir)) return null
+  const ns = readdirSync(dir).map(Number).filter(Number.isInteger).sort((a, b) => b - a)
+  for (const n of ns) { try { return JSON.parse(readFileSync(runJsonPath(id, n), 'utf8')) } catch {} }
+  return null
+}
+
+// A run whose verdict no orchestrator has consumed: the latest run has no
+// settled_at. Happens after `baton down` (agents killed, the supervisor wrote
+// its verdict, the server that would apply it was already gone) or a crashed
+// server. runCard re-attaches to it instead of launching a fresh leg.
+export function unsettledRun(id) {
+  const r = latestRun(id)
+  return r && !r.settled_at ? r : null
+}
+
+// A run nobody alive is driving: unsettled and its driver (the orchestrator
+// process that launched or re-attached to it) is gone. The scheduler picks
+// these up; a live driver is left alone so two processes never apply one verdict.
+export function orphanedRun(id) {
+  const r = unsettledRun(id)
+  return r && !(r.driver_pid && pidAlive(r.driver_pid)) ? r : null
+}
+
+// The claim on a card: one file per card, created atomically ('wx') at the top
+// of runCard and removed when it returns. run.json's driver_pid only exists
+// once a leg has launched; before that (worktree add, the start step, the
+// contract) a card had no owner, and a `card run` beside a scheduler tick, or
+// two schedulers, could both launch a leg into one worktree.
+function driverLockPath(id) { return join(cardDir(id), 'driver.lock') }
+
+function readDriver(id) {
+  try { return JSON.parse(readFileSync(driverLockPath(id), 'utf8')) } catch { return null }
+}
+
+// The pid of another live process driving this card, else null.
+export function driverAlive(id) {
+  const d = readDriver(id)
+  return d?.pid && d.pid !== process.pid && pidAlive(d.pid) ? d.pid : null
+}
+
+function claimDriver(id) {
+  const f = driverLockPath(id)
+  for (let i = 0; i < 3; i++) {
+    try {
+      writeFileSync(f, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }) + '\n', { flag: 'wx' })
+      return { ok: true }
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err
+    }
+    const d = readDriver(id)
+    if (d?.pid === process.pid) return { ok: true }
+    if (d?.pid && pidAlive(d.pid)) return { ok: false, pid: d.pid }
+    // the holder died, or the file is not readable yet: a claim being written
+    // right now is younger than a second, a torn one from a crash is not
+    let stale = Boolean(d?.pid)
+    if (!stale) { try { stale = Date.now() - statSync(f).mtimeMs > 1000 } catch { stale = true } }
+    if (!stale) { const t = Date.now() + 50; while (Date.now() < t) { /* spin */ } continue }
+    try { unlinkSync(f) } catch {}
+  }
+  return { ok: false, pid: readDriver(id)?.pid ?? null }
+}
+
+function releaseDriver(id) {
+  if (readDriver(id)?.pid === process.pid) { try { unlinkSync(driverLockPath(id)) } catch {} }
+}
+
+function patchRun(id, n, fields) {
+  if (!n) return
+  try { updateRun(id, n, (cur) => (cur ? { ...cur, ...fields } : null)) } catch {}
+}
+
+function settleRun(id, run) { patchRun(id, run?.run, { settled_at: new Date().toISOString() }) }
+
+function pidAlive(pid) {
+  if (!pid) return false
+  try { process.kill(pid, 0); return true } catch { return false }
+}
+
+const FINAL_RUN = ['exited', 'killed', 'failed', 'orphaned']
+
+async function waitForRun(id, n, { pollMs = POLL_MS } = {}) {
+  let deadSince = null
+  let interrupted = null
+  for (;;) {
+    let run = null
+    try { run = JSON.parse(readFileSync(runJsonPath(id, n), 'utf8')) } catch {}
+    if (run && FINAL_RUN.includes(run.status)) {
+      if (run.status === 'orphaned' && !run.outcome) return { ...run, outcome: 'failed', handoff: true, signal: 'none', reason: 'supervisor died before the leg finished' }
+      return run
+    }
+    const supervisorAlive = Boolean(run?.supervisor_pid) && pidAlive(run.supervisor_pid)
+    // A human acted on the card (kill, pause, hand off now, reassign): the leg
+    // is over for us. Wait for the supervisor to finish writing (it is
+    // classifying the kill) so the next leg's launch never finds this run
+    // still active, then report the interruption.
+    const card = readCard(id)
+    if (card && card.status !== 'running') interrupted ??= { ...(run ?? {}), status: 'interrupted', outcome: 'killed', handoff: false }
+    if (interrupted && (!run || !supervisorAlive)) return interrupted
+    // A dead supervisor never writes `exited`; do not wait on it forever.
+    if (run && ['launching', 'running'].includes(run.status) && run.supervisor_pid && !supervisorAlive) {
+      deadSince ??= Date.now()
+      if (Date.now() - deadSince > 5000) {
+        patchRun(id, n, { status: 'orphaned' })
+        return { ...run, status: 'orphaned', outcome: 'failed', handoff: true, signal: 'none', reason: `supervisor pid ${run.supervisor_pid} died before the leg finished` }
+      }
+    } else deadSince = null
+    await sleep(pollMs)
+  }
+}
+
+function changedFiles(worktree) {
+  const r = spawnSync('git', ['status', '--porcelain'], { cwd: worktree, windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+  if (r.status !== 0) return []
+  return r.stdout.split(/\r?\n/).filter(Boolean).map((l) => l.slice(3).trim()).filter((f) => f && !f.startsWith('.baton'))
+}
+
+function diffStat(worktree) {
+  const r = spawnSync('git', ['diff', '--stat'], { cwd: worktree, windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+  return r.status === 0 ? r.stdout : ''
+}
+
+async function runLeg(card, station, worktree) {
+  const entry = station.chain[card.leg]
+  if (!entry) throw new Error(`no chain entry for leg ${card.leg} at ${station.name}`)
+  const resumed = card.leg > 0 || card.resume_from_bundle === true
+  const contractText = await renderContract({ card, station, leg: card.leg, entry, worktree, resumed, bounceReason: card.bounce_reason })
+  writeContract(worktree, contractText)
+  let resumeText = null
+  if (resumed) {
+    try { resumeText = loadResume(worktree) } catch (err) { log(`no bundle to resume from: ${err.message}`) }
+  }
+  const prompt = legPrompt({ contractText, resumeText })
+  const promptFile = join(cardDir(card.card_id), `prompt-${station.name}-leg${card.leg}.txt`)
+  writeFileSync(promptFile, prompt)
+  const args = ['launch', '--card', card.card_id, '--adapter', entry.adapter, '--prompt-file', promptFile, '--cwd', worktree, '--driver-pid', String(process.pid)]
+  if (entry.mode) args.push('--mode', entry.mode)
+  if (entry.maxTurns) args.push('--max-turns', String(entry.maxTurns))
+  if (entry.model) args.push('--model', String(entry.model))
+  if (entry.network) args.push('--network', '1')
+  const extraEnv = {}
+  if (entry.fakeMode) {
+    // "a;b;c" = one mode per landing attempt (demo: break-test on the first run, fix-test after the bounce)
+    const modes = String(entry.fakeMode).split(';').map((m) => m.trim()).filter(Boolean)
+    extraEnv.FAKE_MODE = modes[Math.min(card.land_attempts ?? 0, modes.length - 1)]
+  }
+  if (entry.fakeFixture) extraEnv.FAKE_LIMIT_FIXTURE = entry.fakeFixture
+  if (entry.fakeTarget) extraEnv.FAKE_TARGET = entry.fakeTarget
+  if (entry.fakeContent) extraEnv.FAKE_CONTENT = entry.fakeContent
+  extraEnv.FAKE_TRUNK = card.trunk || 'main'
+  if (Object.keys(extraEnv).length) args.push('--env-json', JSON.stringify(extraEnv))
+  let launch
+  try {
+    launch = JSON.parse(execFileSync(process.execPath, [RUNNER, ...args], { windowsHide: true, encoding: 'utf8', env: process.env }))
+  } catch (err) {
+    const text = String(err.stderr ?? err.stdout ?? err.message)
+    return { status: 'failed', outcome: 'launch_failed', handoff: true, signal: 'none', reason: scrub(text).slice(0, 300), run: null, exit_code: null }
+  }
+  if (card.resume_from_bundle) ledgerUpdate(card.card_id, { patch: { resume_from_bundle: false } })
+  const run = await waitForRun(card.card_id, launch.run)
+  return run
+}
+
+export { resolveCommand } from './commands.mjs'
+// async: the test station runs inside the board server's scheduler, and a
+// long suite must not freeze the board (src/commands.mjs)
+const runTestCommand = (cmd, cwd) => runCommandAsync(cmd, cwd, { tailLines: 20 })
+
+function handoffOn(card, station, run, worktree, extra = []) {
+  const entry = station.chain[card.leg]
+  const runDir = run?.run ? join(cardDir(card.card_id), 'runs', String(run.run)) : null
+  try {
+    const h = writeHandoff({ card, station, leg: card.leg, entry, run, worktree, runDir, extra, changedFiles: changedFiles(worktree), diffStat: diffStat(worktree) })
+    ledgerUpdate(card.card_id, { patch: { last_bundle: h.bundle_id } })
+    ledgerAppend(card.card_id, {
+      type: 'handoff_written', station: station.name, leg: card.leg,
+      summary: `handoff bundle ${h.bundle_id} (${h.quality ?? 'unscored'}) after ${run?.outcome ?? 'handoff'}; next: ${station.chain[card.leg + 1]?.adapter ?? 'none'}`,
+      body: `notes: ${h.notes_path}`,
+    })
+    return h
+  } catch (err) {
+    ledgerAppend(card.card_id, { type: 'error', station: station.name, leg: card.leg, summary: `handoff bundle failed: ${scrub(err.message).slice(0, 200)}` })
+    return null
+  }
+}
+
+// Run a card until it reaches a waiting or terminal state. Returns the card.
+export async function runCard(id, { actor = BATON_ACTOR } = {}) {
+  let card = readCard(id)
+  if (!card) throw new Error(`card not found: ${id}`)
+  const claim = claimDriver(id)
+  if (!claim.ok) {
+    log(`card ${id} is driven by pid ${claim.pid}; not attaching`)
+    return card
+  }
+  try {
+    return await driveCard(id, card, actor)
+  } finally { releaseDriver(id) }
+}
+
+async function driveCard(id, card, actor) {
+  if (card.status === 'backlog') card = step(id, 'enqueue', {}, actor)
+  const wt = ensureWorktree(card.repo, card.card_id, { trunk: card.trunk || 'main' })
+  if (card.worktree !== wt.path) {
+    ledgerUpdate(id, { patch: { worktree: wt.path } })
+    card = readCard(id)
+  }
+  for (;;) {
+    card = readCard(id)
+    if (WAITING.includes(card.status)) return card
+    if (card.status === 'handing_off') {
+      // Recovering a crash mid-handoff: finish the handoff step.
+      const st = card.pipeline[stationIndex(card.pipeline, card.station)]
+      card = step(id, 'bundle_written', {}, actor)
+      void st
+      continue
+    }
+    if (card.status === 'queued') {
+      card = step(id, 'start', {}, actor)
+      if (card.status !== 'running') return card
+    }
+    if (card.status !== 'running') return card
+    const st = card.pipeline[stationIndex(card.pipeline, card.station)]
+    if (!st) throw new Error(`card ${id}: unknown station ${card.station}`)
+    const handler = KIND_HANDLERS[st.kind]
+    if (handler) {
+      const r = await handler.run({ id, card, station: st, worktree: wt.path, actor, ops: OPS })
+      card = r.card
+      if (r.done) return card
+      continue
+    }
+    if (st.kind === 'land') {
+      const r = await landCard(card, wt.path)
+      const fresh = readCard(id)
+      if (fresh.status !== 'running') {
+        // a human acted while the land ran; trunk may have moved anyway, and
+        // the ledger must say so even though the card no longer advances
+        if (r.landed) ledgerAppend(id, { type: 'landed', station: st.name, leg: 0, summary: `landed on trunk after the card was ${fresh.status}` })
+        return fresh
+      }
+      if (r.bounced) {
+        // the failure travels with the card: Open findings of the bounce bundle
+        handoffOn(card, { name: st.name, chain: [] }, { outcome: `land-${r.reason}`, reason: r.detail ?? r.reason, exit_code: null, adapter: 'land' }, wt.path,
+          [`land failure: ${r.reason}`, r.detail ?? '', ...(r.files?.length ? [`conflicting files: ${r.files.join(', ')}`] : [])].filter(Boolean))
+      }
+      if (!r.landed && !r.bounced && !r.pr) {
+        ledgerAppend(id, { type: 'error', station: st.name, leg: 0, summary: `land failed: ${scrub(r.reason ?? 'unknown').slice(0, 200)}` })
+        card = step(id, 'land_result', { bounced: true, reason: r.reason }, actor)
+        continue
+      }
+      card = step(id, 'land_result', { ...r, reason: r.detail ? `${r.reason}: ${r.detail}` : r.reason }, actor)
+      continue
+    }
+    throw new Error(`unknown station kind ${st.kind}`)
+  }
+}
+
+// Human actions from the CLI or the board. Returns the updated card.
+export function humanAction(id, action, payload = {}, actor = { type: 'human', id: 'local' }) {
+  const card = readCard(id)
+  if (!card) throw new Error(`card not found: ${id}`)
+  const result = transition(card, action, payload)
+  const next = apply(id, card, result, actor)
+  if (['kill', 'pause', 'reassign', 'handoff_now'].includes(action) && card.status === 'running') killActiveRun(id)
+  return next
+}
+
+// Kill the agent process of the active run. The run record gets
+// kill_requested so the supervisor classifies the exit as `killed` (a human
+// decision), not `stalled` or `failed`. A run still `launching` has no
+// agent_pid yet: its supervisor is killed with its whole tree instead, so an
+// agent it spawns a moment later dies with it rather than running a full leg
+// under a card the board already shows as killed.
+export function killActiveRun(id) {
+  const runsDir = join(cardDir(id), 'runs')
+  if (!existsSync(runsDir)) return false
+  let killed = false
+  const runs = readdirSync(runsDir).map(Number).filter((n) => Number.isInteger(n) && n > 0)
+  for (const n of runs) {
+    let run
+    try { run = JSON.parse(readFileSync(join(runsDir, String(n), 'run.json'), 'utf8')) } catch { continue }
+    if (!['launching', 'running'].includes(run.status)) continue
+    patchRun(id, n, { kill_requested: true })
+    if (run.agent_pid) {
+      if (process.platform === 'win32') spawnSync('taskkill', ['/PID', String(run.agent_pid), '/T', '/F'], { windowsHide: true, encoding: 'utf8' })
+      else { try { process.kill(run.agent_pid, 'SIGKILL') } catch {} }
+      killed = true
+    } else if (run.supervisor_pid && pidAlive(run.supervisor_pid)) {
+      if (process.platform === 'win32') spawnSync('taskkill', ['/PID', String(run.supervisor_pid), '/T', '/F'], { windowsHide: true, encoding: 'utf8' })
+      else { try { process.kill(-run.supervisor_pid, 'SIGKILL') } catch { try { process.kill(run.supervisor_pid, 'SIGKILL') } catch {} } }
+      killed = true
+    }
+  }
+  return killed
+}
+
+// Helpers handed to the station-kind modules (see src/stations/*.mjs).
+const OPS = {
+  readCard, ledgerAppend, step, apply, transition, handoffOn, runLeg, waitForRun,
+  unsettledRun, settleRun, patchRun, pidAlive, log, resolveTestCommand, runTestCommand,
+}