@ucsandman/legcli 0.7.0

package/src/session-detail.mjs

@@ -0,0 +1,129 @@
+// What one terminal card's drawer shows: the agent's last messages, the files
+// this session changed, and the diff for one of them. Read-only, and every
+// string is scrubbed on the way out: a transcript and a diff can both carry a
+// key the agent printed, and neither has ever left this machine before.
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+import { readEvents, workRoot } from './sessions.mjs'
+import { realPath } from './fsx.mjs'
+import { scrub } from './redact.mjs'
+import { transcriptTail as claudeTail } from './taps/claude.mjs'
+import { transcriptTail as codexTail } from './taps/codex.mjs'
+import { resumeVerdict, verdictForBoard } from './resume.mjs'
+
+export const MESSAGE_LIMIT = 8
+export const DIFF_MAX_LINES = 400
+export const EVENT_LIMIT = 200
+
+export class DiffInputError extends Error {}
+
+function git(root, args) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], { windowsHide: true, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, timeout: 5000, env: { ...process.env, MSYS_NO_PATHCONV: '1' }, stdio: ['ignore', 'pipe', 'ignore'] })
+  } catch { return null }
+}
+
+// A path the session recorded (relative, or absolute in another form: a short
+// 8.3 prefix, a symlinked temp dir) → its path inside this session's own tree,
+// or null when it is not in that tree at all.
+function insideRoot(root, file) {
+  if (!root || !file) return null
+  const rootR = realPath(root)
+  const absR = realPath(isAbsolute(file) ? file : resolve(rootR, file))
+  const rel = relative(rootR, absR)
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) return null
+  return { rel: rel.split(sep).join('/'), abs: absR }
+}
+
+export function sessionMessages(session, limit = MESSAGE_LIMIT) {
+  const path = session?.transcript_path
+  if (!path) return []
+  const tail = session.agent === 'claude' ? claudeTail(path, limit)
+    : session.agent === 'codex' ? codexTail(path, limit)
+      : [] // agy keeps no transcript Baton can read
+  return tail.map((m) => ({ role: m.role === 'user' ? 'user' : 'assistant', text: scrub(m.text), ts: m.ts ?? null }))
+}
+
+// path → {adds, dels} for everything git can compare against HEAD. A file the
+// agent created is not in here; it is still listed, with no counts.
+function numstat(root) {
+  const out = git(root, ['diff', '--numstat', 'HEAD'])
+  const counts = new Map()
+  for (const line of (out ?? '').split('\n')) {
+    const [adds, dels, path] = line.split('\t')
+    if (!path) continue
+    counts.set(path.trim(), { adds: Number(adds) || 0, dels: Number(dels) || 0 })
+  }
+  return counts
+}
+
+// Is this a path git already has? A file with no counts against HEAD is either
+// one the agent created (nobody tracks it, ignored files included) or one that
+// already landed in a commit, and the drawer must not call those the same.
+function isTracked(root, rel) {
+  const out = git(root, ['ls-files', '--error-unmatch', '--', rel])
+  return typeof out === 'string' && out.trim().length > 0
+}
+
+export function sessionFiles(session) {
+  const root = workRoot(session)
+  if (!root) return []
+  const counts = numstat(root)
+  const dirty = new Set()
+  for (const f of session.files_dirty ?? []) { const i = insideRoot(root, f); if (i) dirty.add(i.rel) }
+  const files = new Map()
+  for (const f of [...(session.files_touched ?? []), ...(session.files_dirty ?? [])]) {
+    const i = insideRoot(root, f)
+    if (!i || files.has(i.rel)) continue
+    const c = counts.get(i.rel) ?? null
+    const state = c ? 'modified' : (isTracked(root, i.rel) ? 'committed' : 'new')
+    files.set(i.rel, { path: i.rel, adds: c?.adds ?? null, dels: c?.dels ?? null, dirty: dirty.has(i.rel), state })
+  }
+  return [...files.values()].sort((a, b) => a.path.localeCompare(b.path))
+}
+
+export function sessionDiff(session, file) {
+  const root = workRoot(session)
+  if (!root) throw new DiffInputError('this terminal has no repository to diff')
+  const inside = insideRoot(root, String(file ?? ''))
+  if (!inside) throw new DiffInputError('that file is not in this terminal\'s tree')
+  let out = git(root, ['diff', 'HEAD', '--', inside.rel]) ?? ''
+  let state = 'modified'
+  if (!out.trim()) {
+    // nothing to compare against is not one situation: the agent created this
+    // file, or it already landed in a commit, or it is gone. Say which.
+    const isFile = existsSync(inside.abs) && statSync(inside.abs).isFile()
+    if (isFile && !isTracked(root, inside.rel)) {
+      let body = ''
+      try { body = readFileSync(inside.abs, 'utf8') } catch { body = '' }
+      if (body) out = `--- /dev/null\n+++ b/${inside.rel}\n` + body.split('\n').map((l) => '+' + l).join('\n')
+      state = 'new'
+    } else state = existsSync(inside.abs) ? 'committed' : 'gone'
+  }
+  const lines = scrub(out).split('\n')
+  const truncated = lines.length > DIFF_MAX_LINES
+  return { file: inside.rel, diff: lines.slice(0, DIFF_MAX_LINES).join('\n'), truncated, state }
+}
+
+// Is the resume pointer in this terminal's checkout still describing the repo
+// the reader will find? Recomputed from git on every drawer poll, and handed
+// over without its local paths: a screenshot of the drawer travels further
+// than this machine.
+function resumeFor(session) {
+  const root = workRoot(session)
+  if (!root) return null
+  try { return verdictForBoard(resumeVerdict(root)) } catch { return null }
+}
+
+export function sessionDetail(session) {
+  return {
+    session_id: session.session_id,
+    messages: sessionMessages(session),
+    files: sessionFiles(session),
+    events: readEvents(session.session_id).slice(-EVENT_LIMIT),
+    bundle: session.bundle ?? null,
+    resume: resumeFor(session),
+    ts: new Date().toISOString(),
+  }
+}

package/src/sessions.mjs

@@ -0,0 +1,202 @@
+// sessions — the store behind `baton claude|codex|agy`. One directory per
+// interactive terminal session under $BATON_HOME/sessions/<id>/:
+//   session.json   the live record the board renders (atomic writes)
+//   events.jsonl   timeline (started, turn, warning, limit, handoff, ended)
+//   control.json   board → runner requests ({ handoff: true })
+// The runner (src/attach.mjs) is the only writer of session.json; hooks and
+// taps go through recordFromTap() so every write is one atomic replace.
+import { existsSync, mkdirSync, readdirSync, readFileSync, appendFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { home } from './store.mjs'
+import { writeJsonAtomic, withFileLock } from './fsx.mjs'
+import { scrub } from './redact.mjs'
+import { HANDOFF_AGENTS, normalizeHandoffOrder } from './preferences.mjs'
+
+export const AGENTS = HANDOFF_AGENTS
+export const HANDOFF_ORDER_CAPABILITY = 'handoff_order_v1'
+export const SESSION_STATUSES = ['starting', 'running', 'warning', 'limit', 'handing_off', 'waiting', 'handed_off', 'ended', 'lost']
+const ACTIVE = ['starting', 'running', 'warning', 'limit', 'handing_off', 'waiting']
+
+const now = () => new Date().toISOString()
+
+export function sessionsRoot() { return join(home(), 'sessions') }
+export function sessionDir(id) { return join(sessionsRoot(), id) }
+
+export function newSessionId(agent) {
+  const d = new Date()
+  const pad = (n) => String(n).padStart(2, '0')
+  return `s-${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}-${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}-${agent}-${randomBytes(2).toString('hex')}`
+}
+
+export function readSession(id) {
+  const f = join(sessionDir(id), 'session.json')
+  if (!existsSync(f)) return null
+  try { return JSON.parse(readFileSync(f, 'utf8')) } catch { return null }
+}
+
+export function listSessions() {
+  const root = sessionsRoot()
+  if (!existsSync(root)) return []
+  return readdirSync(root).filter((n) => n.startsWith('s-')).sort().map(readSession).filter(Boolean)
+}
+
+export function isActive(s) { return ACTIVE.includes(s?.status) }
+
+// The checkout this session's files live in: its own worktree when Baton gave
+// it one (repo stays the main checkout, for grouping and landing), else the repo.
+export function workRoot(s) { return s?.worktree?.path ?? s?.repo ?? s?.cwd ?? null }
+
+export function createSession({ id, agent, account = 'default', cwd, repo = null, branch = null, argv = [], runner_pid = process.pid, chain = [], worktree = null, owner = null, handoffOrder = AGENTS, installed = null, runtimeCapabilities = [] }) {
+  const session = {
+    session_id: id, agent, account, cwd, repo, branch, argv, worktree, owner,
+    repo_name: repo ? repo.split(/[\\/]/).filter(Boolean).pop() : null,
+    status: 'starting', runner_pid, pid: null,
+    started_at: now(), updated_at: now(), ended_at: null, last_activity: now(),
+    agent_session_id: null, transcript_path: null,
+    task: null, turns: 0,
+    files_touched: [], files_dirty: [], head: null, head_at_start: null,
+    limits: null, limit: null, warning: null,
+    bundle: null, handoff: null, chain,
+    handoff_order: normalizeHandoffOrder(handoffOrder), installed,
+    runtime_capabilities: [...new Set(runtimeCapabilities)],
+    lineage: { from: null, to: null },
+    exit_code: null,
+  }
+  mkdirSync(sessionDir(id), { recursive: true })
+  writeJsonAtomic(join(sessionDir(id), 'session.json'), session)
+  appendEvent(id, { type: 'started', summary: `${agent} (${account}) started in ${cwd}` })
+  return session
+}
+
+// Patch the record; arrays replace, `merge` deep-merges one level (limits).
+// `patch` may be a function (cur) => delta: the read, the compute and the write
+// then happen inside one cross-process lock, so concurrent hook/tap/poller
+// processes cannot lose an accumulated field (files_touched, turns) to a
+// last-writer-wins race. Callers that only set fixed values pass a plain object.
+export function updateSession(id, patch, { event } = {}) {
+  return withFileLock(join(sessionDir(id), '.session.lock'), () => {
+    const cur = readSession(id)
+    if (!cur) return null
+    const delta = typeof patch === 'function' ? patch(cur) : patch
+    const next = { ...cur, ...delta, updated_at: now() }
+    if (delta.limits && cur.limits) next.limits = { ...cur.limits, ...delta.limits }
+    writeJsonAtomic(join(sessionDir(id), 'session.json'), next)
+    if (event) appendEvent(id, event)
+    return next
+  })
+}
+
+export function appendEvent(id, ev) {
+  const dir = sessionDir(id)
+  if (!existsSync(dir)) return
+  const line = { ts: now(), session_id: id, ...ev, summary: scrub(String(ev.summary ?? '')) }
+  if (line.body) line.body = scrub(String(line.body)).slice(0, 4000)
+  appendFileSync(join(dir, 'events.jsonl'), JSON.stringify(line) + '\n')
+}
+
+export function readEvents(id) {
+  const f = join(sessionDir(id), 'events.jsonl')
+  if (!existsSync(f)) return []
+  return readFileSync(f, 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l) } catch { return null } }).filter(Boolean)
+}
+
+// Board → runner. The runner polls this file; a consumed request is deleted.
+// Merge, never replace: an `end` and a later `handoff` (or a second board
+// command in the same poll window) both survive to be seen by takeControl,
+// instead of the second write silently dropping the first.
+export function requestControl(id, req) {
+  const f = join(sessionDir(id), 'control.json')
+  return withFileLock(join(sessionDir(id), '.control.lock'), () => {
+    let existing = {}
+    if (existsSync(f)) { try { existing = JSON.parse(readFileSync(f, 'utf8')) } catch {} }
+    writeJsonAtomic(f, { ...existing, ...req, requested_at: now() })
+  })
+}
+export function takeControl(id) {
+  const f = join(sessionDir(id), 'control.json')
+  return withFileLock(join(sessionDir(id), '.control.lock'), () => {
+    if (!existsSync(f)) return null
+    let req = null
+    try { req = JSON.parse(readFileSync(f, 'utf8')) } catch {}
+    rmSync(f, { force: true })
+    return req
+  })
+}
+
+export function removeSession(id) { rmSync(sessionDir(id), { recursive: true, force: true }) }
+
+// Land state for one session: land.json is written by the board server only
+// (the runner owns session.json), so a land result never races a tap write.
+export function readLand(id) {
+  const f = join(sessionDir(id), 'land.json')
+  if (!existsSync(f)) return null
+  try { return JSON.parse(readFileSync(f, 'utf8')) } catch { return null }
+}
+export function writeLand(id, land) {
+  if (!existsSync(sessionDir(id))) return
+  writeJsonAtomic(join(sessionDir(id), 'land.json'), land)
+}
+
+// Hand-off requests from another human (share mode). Server-owned, like land.json.
+export function readRequests(id) {
+  const f = join(sessionDir(id), 'requests.json')
+  if (!existsSync(f)) return []
+  try { const j = JSON.parse(readFileSync(f, 'utf8')); return Array.isArray(j) ? j : [] } catch { return [] }
+}
+export function writeRequests(id, list) {
+  if (!existsSync(sessionDir(id))) return
+  writeJsonAtomic(join(sessionDir(id), 'requests.json'), list.slice(-20))
+}
+
+// Who landed what: one line per landing, kept after the session is removed.
+const landingsFile = () => join(home(), 'landings.jsonl')
+export function appendLanding(entry) {
+  mkdirSync(home(), { recursive: true })
+  appendFileSync(landingsFile(), JSON.stringify({ ts: now(), ...entry }) + '\n')
+}
+export function readLandings() {
+  if (!existsSync(landingsFile())) return []
+  return readFileSync(landingsFile(), 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l) } catch { return null } }).filter(Boolean)
+}
+
+function pidAlive(pid) {
+  if (!pid) return false
+  // EPERM means the process exists but is not ours to signal (e.g. an elevated
+  // terminal): it is alive. Only ESRCH ("no such process") means gone.
+  try { process.kill(pid, 0); return true } catch (e) { return e.code === 'EPERM' }
+}
+
+// A session whose runner process is gone (terminal closed, crash) is marked
+// lost so the board never shows a dead terminal as live.
+export function reapLost(sessions = listSessions()) {
+  const out = []
+  for (const s of sessions) {
+    if (isActive(s) && !pidAlive(s.runner_pid)) {
+      out.push(updateSession(s.session_id, { status: 'lost', ended_at: now() }, { event: { type: 'lost', summary: `runner pid ${s.runner_pid} is gone; session marked lost` } }) ?? s)
+    } else out.push(s)
+  }
+  return out
+}
+
+// Two live sessions on one repo touching the same file: both get flagged.
+export function overlaps(sessions) {
+  const live = sessions.filter(isActive).filter((s) => s.repo)
+  const out = new Map()
+  for (let i = 0; i < live.length; i++) {
+    for (let j = i + 1; j < live.length; j++) {
+      const a = live[i]; const b = live[j]
+      if (a.repo.toLowerCase() !== b.repo.toLowerCase()) continue
+      const setB = new Set([...(b.files_touched ?? []), ...(b.files_dirty ?? [])])
+      const shared = [...new Set([...(a.files_touched ?? []), ...(a.files_dirty ?? [])])].filter((f) => setB.has(f))
+      if (!shared.length) continue
+      // separate: each has its own checkout, so the clash waits for the second landing
+      const separate = String(workRoot(a)).toLowerCase() !== String(workRoot(b)).toLowerCase()
+      for (const [x, y] of [[a, b], [b, a]]) {
+        if (!out.has(x.session_id)) out.set(x.session_id, [])
+        out.get(x.session_id).push({ session_id: y.session_id, agent: y.agent, files: shared, separate })
+      }
+    }
+  }
+  return out
+}

package/src/share.mjs

@@ -0,0 +1,163 @@
+// share — optional multiplayer for the board, off until `baton share on`
+// writes $BATON_HOME/share.json. With it on, the board binds the Tailscale or
+// LAN address, every human has a name and their own token (kept as a sha256
+// hash: a token is printed once and `baton share rotate` issues a new one),
+// and every session belongs to the human whose terminal started it
+// (`BATON_PERSON`, else the owner). With it off nothing changes: loopback is
+// open and `BATON_TOKEN` is the only token.
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+import { existsSync, readFileSync, mkdirSync } from 'node:fs'
+import { networkInterfaces, userInfo } from 'node:os'
+import { createSocket } from 'node:dgram'
+import { join } from 'node:path'
+import { home } from './store.mjs'
+import { writeJsonAtomic } from './fsx.mjs'
+
+export const OFF = { version: 1, on: false, bind: null, bind_kind: null, port: null, owner: null, people: [] }
+export const ROLES = ['owner', 'guest']
+
+export function sharePath() { return join(home(), 'share.json') }
+
+export function readShare() {
+  const f = sharePath()
+  if (!existsSync(f)) return { ...OFF }
+  try {
+    const s = JSON.parse(readFileSync(f, 'utf8'))
+    return { ...OFF, ...s, people: Array.isArray(s.people) ? s.people : [] }
+  } catch { return { ...OFF } }
+}
+
+export function writeShare(share) {
+  mkdirSync(home(), { recursive: true })
+  writeJsonAtomic(sharePath(), share)
+  return share
+}
+
+// On means: turned on, bound somewhere, and at least one person to let in.
+export function isOn(share = readShare()) { return Boolean(share.on && share.people.length && share.bind) }
+
+export function hashToken(token) { return createHash('sha256').update(String(token)).digest('hex') }
+export function newToken() { return randomBytes(24).toString('base64url') }
+export function validName(name) { return /^[a-z0-9][a-z0-9_-]{0,31}$/i.test(String(name ?? '')) }
+
+// Which person presented this token, in constant time. null for no match.
+export function identify(share, presented) {
+  if (!presented || !share?.people?.length) return null
+  const h = Buffer.from(hashToken(presented))
+  let found = null
+  for (const p of share.people) {
+    const q = Buffer.from(String(p.token_sha256 ?? '').padEnd(h.length, '0').slice(0, h.length))
+    if (timingSafeEqual(h, q) && p.token_sha256) found = found ?? p
+  }
+  return found
+}
+
+export function personNamed(share, name) { return share.people.find((p) => p.name.toLowerCase() === String(name ?? '').toLowerCase()) ?? null }
+export function isOwner(person) { return person?.role === 'owner' }
+
+export function addPerson(name, { role = 'guest', share = readShare() } = {}) {
+  if (!validName(name)) throw new Error(`bad name "${name}": letters, digits, dash and underscore, up to 32 characters`)
+  if (!ROLES.includes(role)) throw new Error(`bad role "${role}" (owner|guest)`)
+  if (personNamed(share, name)) throw new Error(`"${name}" is already on the board; baton share rotate ${name} issues a new link`)
+  const token = newToken()
+  const person = { name, role, token_sha256: hashToken(token), created_at: new Date().toISOString(), last_seen: null }
+  share.people.push(person)
+  writeShare(share)
+  return { person, token, share }
+}
+
+export function removePerson(name, share = readShare()) {
+  const person = personNamed(share, name)
+  if (!person) throw new Error(`no one called "${name}" on this board`)
+  // a shared board with no owner locks this machine's own browser out of it
+  if (isOwner(person) && isOn(share) && !share.people.some((p) => isOwner(p) && p !== person)) {
+    throw new Error(`"${name}" is the only owner of this board: leg share add <someone> --role owner first, or leg share off`)
+  }
+  share.people = share.people.filter((p) => p.name.toLowerCase() !== String(name).toLowerCase())
+  if (share.owner && share.owner.toLowerCase() === String(name).toLowerCase()) share.owner = share.people.find((p) => p.role === 'owner')?.name ?? null
+  writeShare(share)
+  return share
+}
+
+export function rotate(name, share = readShare()) {
+  const person = personNamed(share, name)
+  if (!person) throw new Error(`no one called "${name}" on this board`)
+  const token = newToken()
+  person.token_sha256 = hashToken(token)
+  person.rotated_at = new Date().toISOString()
+  writeShare(share)
+  return { person, token, share }
+}
+
+function ipv4s() {
+  const out = []
+  for (const [name, list] of Object.entries(networkInterfaces())) for (const a of list ?? []) if (a.family === 'IPv4' && !a.internal) out.push({ name, address: a.address })
+  return out
+}
+
+// The address of the interface the default route uses, without sending a byte.
+function defaultRouteAddress() {
+  return new Promise((resolvePromise) => {
+    const s = createSocket('udp4')
+    const done = (v) => { try { s.close() } catch {} resolvePromise(v) }
+    s.on('error', () => done(null))
+    try { s.connect(53, '8.8.8.8', () => { try { done(s.address().address) } catch { done(null) } }) } catch { done(null) }
+  })
+}
+
+// 'tailscale' (default), 'lan', or an address to use as given.
+export async function resolveBind(kind = 'tailscale') {
+  const want = String(kind).toLowerCase()
+  if (!['tailscale', 'lan'].includes(want)) return want
+  const addrs = ipv4s()
+  if (want === 'tailscale') {
+    const ts = addrs.find((a) => /tailscale/i.test(a.name) || /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(a.address))
+    if (!ts) throw new Error('no Tailscale address on this machine: use --bind lan, or --bind <address>')
+    return ts.address
+  }
+  const viaRoute = await defaultRouteAddress()
+  if (viaRoute && addrs.some((a) => a.address === viaRoute)) return viaRoute
+  const lan = addrs.find((a) => /^(192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/.test(a.address) && !/tailscale|virtual|default switch|wsl/i.test(a.name))
+  if (!lan) throw new Error('no LAN address found: pass --bind <address>')
+  return lan.address
+}
+
+export function linkFor(share, token) { return `http://${share.bind}:${share.port}/?token=${token}` }
+
+// Whose terminal this is: BATON_PERSON, else the board's owner, else 'local'.
+export function whoami(share = readShare()) {
+  const named = String(process.env.LEG_PERSON ?? process.env.BATON_PERSON ?? '').trim()
+  if (named && validName(named)) return named
+  return share.owner || 'local'
+}
+
+export async function turnOn({ bind = 'tailscale', port = Number(process.env.LEG_PORT || process.env.BATON_PORT || 4747), owner } = {}) {
+  const share = readShare()
+  const address = await resolveBind(bind)
+  share.on = true
+  share.bind = address
+  share.bind_kind = ['tailscale', 'lan'].includes(String(bind).toLowerCase()) ? String(bind).toLowerCase() : 'address'
+  share.port = port
+  // being first in the roster is not being the owner: a board with nobody in
+  // the owner role gets one of its own, so the machine that shares it keeps it
+  const named = personNamed(share, share.owner)
+  const existing = isOwner(named) ? named : share.people.find((p) => isOwner(p)) ?? null
+  if (!existing) {
+    const name = validName(owner) ? owner : (validName(userInfo().username) ? userInfo().username.toLowerCase() : 'owner')
+    if (personNamed(share, name)) throw new Error(`no one on this board is an owner: leg share add <you> --role owner`)
+    share.owner = name
+    writeShare(share)
+    const added = addPerson(name, { role: 'owner', share })
+    return { share: added.share, owner: added.person, token: added.token }
+  }
+  share.owner = existing.name
+  writeShare(share)
+  return { share, owner: existing, token: null }
+}
+
+export function turnOff() {
+  const share = readShare()
+  share.on = false
+  writeShare(share)
+  return share
+}

package/src/stations/agent.mjs

@@ -0,0 +1,42 @@
+// Station kind: agent. One chain leg runs here (or, after `baton down` or a
+// crashed server, the orchestrator re-attaches to the run it left behind),
+// the run is settled, and its verdict is applied to the card. `ops` are the
+// orchestrator's helpers; this module never imports the orchestrator.
+export async function run({ id, card, station, worktree, actor, ops }) {
+  const { unsettledRun, pidAlive, ledgerAppend, patchRun, waitForRun, runLeg, settleRun, readCard, handoffOn, transition, apply, step, log } = ops
+  const pending = unsettledRun(id)
+  if (pending?.driver_pid && pending.driver_pid !== process.pid && pidAlive(pending.driver_pid)) {
+    log(`card ${id}: run ${pending.run} is driven by pid ${pending.driver_pid}; not attaching`)
+    return { card, done: true }
+  }
+  if (pending) {
+    ledgerAppend(id, { type: 'status', station: station.name, leg: card.leg, summary: `re-attached to run ${pending.run} (${pending.status}); no new leg launched` })
+    patchRun(id, pending.run, { driver_pid: process.pid })
+  }
+  const runRecord = pending ? await waitForRun(id, pending.run) : await runLeg(card, station, worktree)
+  settleRun(id, runRecord)
+  const fresh = readCard(id)
+  if (fresh.status !== 'running') {
+    // A human acted while the leg ran; the machine already moved the card.
+    // paused: keep the context for Resume. handing_off: the human asked for
+    // the bundle, so write it and queue the next leg. queued: reassigned, and
+    // the loop starts the new adapter. killed: nothing more to do.
+    if (fresh.status === 'paused') handoffOn(fresh, station, runRecord, worktree, ['paused by a human; resume continues from this bundle'])
+    if (fresh.status === 'handing_off') {
+      handoffOn(fresh, station, runRecord, worktree, ['hand-off requested by a human; the running leg was stopped'])
+      return { card: step(id, 'bundle_written', {}, actor) }
+    }
+    return { card: fresh, done: fresh.status !== 'queued' }
+  }
+  const before = fresh
+  const result = transition(before, 'leg_result', {
+    outcome: runRecord.outcome, handoff: runRecord.handoff, signal: runRecord.signal,
+    adapter: station.chain[before.leg]?.adapter, run: runRecord.run,
+  })
+  let next = apply(id, before, result, actor)
+  if (next.status === 'handing_off') {
+    handoffOn(next, station, runRecord, worktree)
+    next = step(id, 'bundle_written', {}, actor)
+  }
+  return { card: next }
+}

package/src/stations/build.mjs

@@ -0,0 +1,9 @@
+// Station prompt template: build. The agent implements the task.
+export default {
+  goal: 'Implement the task in this working directory.',
+  deliverables: [
+    'Make the code change the task describes, with tests where the repository has a test suite.',
+    'Run the repository\'s own checks (tests, lint) when they exist and fix what you broke.',
+    'If PLAN.md exists, follow it; note any deviation in .leg/PROGRESS.md.',
+  ],
+}

package/src/stations/human.mjs

@@ -0,0 +1,5 @@
+// Station kind: human. Nothing runs; the card parks in waiting_human until a
+// person presses Approve (or Kill / Reassign) on the board.
+export async function run({ id, actor, ops }) {
+  return { card: ops.step(id, 'start', {}, actor), done: true }
+}

package/src/stations/land.mjs

@@ -0,0 +1,6 @@
+// Station template: land. No agent runs here; the merge queue does the work
+// (src/mergequeue.mjs). Kept so every station kind has a template entry.
+export default {
+  goal: 'Rebase onto trunk, run the repository tests, fast-forward trunk.',
+  deliverables: [],
+}

package/src/stations/plan.mjs

@@ -0,0 +1,8 @@
+// Station prompt template: plan. The agent turns the task into a plan file.
+export default {
+  goal: 'Turn the task into a concrete plan before any code changes.',
+  deliverables: [
+    'Write PLAN.md at the repository root: goal, the files you expect to touch, the steps in order, how each step is verified, and open questions.',
+    'Do not implement anything in this station; planning only.',
+  ],
+}

package/src/stations/pr.mjs

@@ -0,0 +1,31 @@
+// pr — the opt-in land mode. Instead of fast-forwarding trunk, build the
+// `gh pr create` argv and run it through BATON_GH_BIN. This run never
+// executes a real gh (hard stop: no remotes); tests point BATON_GH_BIN at a
+// stub that logs its argv and prints a URL.
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { branchName } from '../worktree.mjs'
+import { scrub } from '../runner.mjs'
+
+export function prArgv({ card, bodyFile }) {
+  return ['pr', 'create', '--base', card.trunk || 'main', '--head', branchName(card.card_id), '--title', card.title || card.card_id, '--body-file', bodyFile]
+}
+
+export function prBody(card, bundleSummary = '') {
+  return `## Task\n\n${card.task}\n\n## Leg\n\ncard ${card.card_id}, pipeline ${card.pipeline.map((s) => s.name).join(' → ')}\n\n${bundleSummary ? `## Handoff summary\n\n${bundleSummary}\n` : ''}`
+}
+
+export function openPr({ card, runDir, bundleSummary = '' }) {
+  const bin = (process.env.LEG_GH_BIN || process.env.BATON_GH_BIN)
+  if (!bin) return { ok: false, error: 'LEG_GH_BIN or BATON_GH_BIN is not set; pr land mode is stub-only in this build (no live gh)' }
+  mkdirSync(runDir, { recursive: true })
+  const bodyFile = join(runDir, 'pr-body.md')
+  writeFileSync(bodyFile, prBody(card, bundleSummary))
+  const argv = prArgv({ card, bodyFile })
+  const viaNode = /\.(mjs|cjs|js)$/.test(bin)
+  const r = spawnSync(viaNode ? process.execPath : bin, viaNode ? [bin, ...argv] : argv, { cwd: card.worktree ?? card.repo, windowsHide: true, encoding: 'utf8', timeout: 60000, env: process.env })
+  if (r.error || r.status !== 0) return { ok: false, error: scrub(r.error?.message || r.stderr || r.stdout).slice(0, 300), argv }
+  const url = (r.stdout.match(/https?:\/\/\S+/) || [null])[0]
+  return { ok: true, url, argv, stdout: r.stdout.trim() }
+}

package/src/stations/review.mjs

@@ -0,0 +1,8 @@
+// Station prompt template: review. The agent reviews the branch and fixes blockers.
+export default {
+  goal: 'Review the changes on this branch against the trunk and fix anything blocking.',
+  deliverables: [
+    'Write REVIEW.md at the repository root: findings ordered by severity, each with file:line and a one-line fix.',
+    'Fix every blocking finding (bugs, broken tests, security) in place; leave non-blocking ones listed.',
+  ],
+}

package/src/stations/test.mjs

@@ -0,0 +1,27 @@
+// Station kind: test. Runs the repo's test command in the worktree; green
+// advances the card, red bounces it to the build station with the tail in
+// the handoff bundle (the attempt cap is shared with the land station).
+export async function run({ id, card, station, worktree, actor, ops }) {
+  const { resolveTestCommand, runTestCommand, ledgerAppend, step, transition, handoffOn, apply, readCard } = ops
+  const cmd = station.command ?? resolveTestCommand(card, worktree).command
+  if (!cmd) {
+    ledgerAppend(id, { type: 'status', station: station.name, leg: 0, summary: 'test station: no test command configured; treating as green' })
+    return { card: step(id, 'test_result', { green: true }, actor) }
+  }
+  const t = await runTestCommand(cmd, worktree)
+  ledgerAppend(id, { type: 'status', station: station.name, leg: 0, summary: `test ${t.green ? 'green' : 'red'}: ${t.command}${t.timedOut ? ' (timed out)' : ''}`, body: t.tail })
+  // the suite ran for a while: a human may have killed or paused the card
+  // meanwhile, and a result applied to that stale status would undo them
+  const fresh = readCard(id)
+  if (fresh.status !== 'running') {
+    ledgerAppend(id, { type: 'status', station: station.name, leg: 0, summary: `test result not applied: the card was ${fresh.status} by then` })
+    return { card: fresh, done: fresh.status !== 'queued' }
+  }
+  if (!t.green) {
+    const bounced = transition(fresh, 'test_result', { green: false, reason: `test red (${t.command}, exit ${t.status}): ${t.tail.split('\n').slice(-5).join(' | ')}` })
+    // Attach the failure to a bundle so the next build leg starts from it.
+    handoffOn(fresh, { name: station.name, chain: [] }, { outcome: 'test_red', reason: t.tail, exit_code: t.status, adapter: 'test' }, worktree, [`test red: ${t.command}`, t.tail.slice(0, 1500)])
+    return { card: apply(id, fresh, bounced, actor) }
+  }
+  return { card: step(id, 'test_result', { green: true }, actor) }
+}