@ucsandman/legcli 0.7.0

package/src/bundle.mjs

@@ -0,0 +1,103 @@
+// bundle — keeps a context-handoff-bundle current for an interactive session
+// and turns it into the prompt the next agent starts from. Reuses the v0.1
+// seam (src/handoff.mjs: chb(), resolveChb) so the CLI is still the only
+// writer of bundle files. One bundle per session (`save --update <slug>`).
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { join } from 'node:path'
+import { chb, ensureExcluded } from './handoff.mjs'
+import { scrub } from './redact.mjs'
+import { updateSession, workRoot } from './sessions.mjs'
+import { perSessionFile, writeHandoffPointer } from './resume.mjs'
+
+const LEG_DIRS = /^(\.leg|\.baton|\.context-handoffs|\.dashclaw-local)[\\/]/
+const bullets = (items) => items.filter(Boolean).map((x) => `- ${String(x).replace(/\r?\n/g, ' ').trim()}`)
+
+function git(cwd, args) {
+  const r = spawnSync('git', args, { cwd, windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+  // trimEnd only: a porcelain line starts with a space (" M README.md")
+  return r.status === 0 ? r.stdout.trimEnd() : ''
+}
+
+export function slugFor(session) { return `leg-${session.session_id}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').slice(0, 80) }
+
+// Notes in the CLI's section vocabulary; see src/handoff.mjs buildNotes.
+export function sessionNotes(session, { messages = [], why = 'handoff' } = {}) {
+  const cwd = workRoot(session)
+  const stat = git(cwd, ['diff', '--stat'])
+  const dirty = git(cwd, ['status', '--porcelain']).split('\n').filter(Boolean).map((l) => l.slice(3).replace(/^"|"$/g, '')).filter((f) => !LEG_DIRS.test(f)).slice(0, 60)
+  const recent = git(cwd, ['log', '--oneline', '-5'])
+  const lines = [
+    '## Scope', '',
+    `Task: ${session.task ?? '(no prompt recorded yet; read the transcript)'}`,
+    `Interactive ${session.agent} session ${session.session_id} in ${session.cwd}${session.branch ? ` on branch ${session.branch}` : ''} stopped: ${why}. The next agent continues in the same directory.`,
+    '', '## Projects mentioned', '', `- ${session.repo_name ?? session.cwd}`, '',
+    '## Findings', '',
+    ...bullets(messages.slice(-8).map((m, i) => `${m.role === 'user' ? 'Human said' : 'Agent said'} (${i + 1}): ${m.text.slice(0, 600)}`)),
+    ...bullets([`Diff since session start: ${stat ? stat.split('\n').pop() : 'clean working tree'}`]),
+    ...bullets(dirty.map((f) => `Dirty file: ${f}`)),
+    ...bullets((session.files_touched ?? []).slice(0, 50).map((f) => `Edited this session: ${f}`)),
+    ...bullets(recent ? [`Recent commits: ${recent.replace(/\n/g, ' | ')}`] : []),
+    '', '## Opportunities', '',
+    ...bullets(['Next agent: read this bundle, inspect `git status` and `git diff`, continue the task from the last agent message, and do not ask the human to restate the task.']),
+    '', '## Open questions', '',
+    ...bullets([`Why the previous agent stopped: ${why}`, session.limit?.detail ? `Limit text: ${session.limit.detail}` : null]),
+    '', '## Evidence anchors', '',
+    ...bullets([...dirty, ...(session.files_touched ?? [])].slice(0, 50)),
+    ...bullets([session.transcript_path ? `transcript: ${session.transcript_path}` : null]),
+    '',
+  ]
+  return scrub(lines.join('\n'))
+}
+
+// Save (or refresh) the session's bundle. Returns { bundle_id, path } or throws.
+export function saveSessionBundle(session, { messages = [], why = 'checkpoint' } = {}) {
+  // a session in its own worktree keeps its bundle and RESUME.md there, where the next agent starts
+  const cwd = workRoot(session)
+  const legDir = join(cwd, '.leg')
+  mkdirSync(legDir, { recursive: true })
+  if (session.repo) for (const pat of ['.leg/', '.baton/', '.context-handoffs/']) ensureExcluded(session.repo, pat)
+  const notesPath = join(legDir, `session-${session.session_id}.md`)
+  writeFileSync(notesPath, sessionNotes(session, { messages, why }))
+  const slug = slugFor(session)
+  const title = `leg ${session.agent} session ${session.session_id}`
+  const base = ['save', '--repo-local', '--title', title, '--slug', slug, '--notes', notesPath, '--tag', 'leg', '--tag', session.agent]
+  let r = session.bundle?.id ? chb([...base, '--update', slug], { cwd }) : { status: 1 }
+  if (r.status !== 0) r = chb(base, { cwd })
+  if (r.status !== 0) throw new Error(`context-handoff-bundle save failed (exit ${r.status}): ${scrub(r.stderr || r.stdout).slice(0, 400)}`)
+  let out
+  try { out = JSON.parse(r.stdout) } catch { throw new Error(`context-handoff-bundle save printed no JSON: ${scrub(r.stdout).slice(0, 200)}`) }
+  const bundle = { id: out.bundle_id, path: join(cwd, '.context-handoffs', out.bundle_id), notes: notesPath, quality: out.quality ?? null, updated_at: new Date().toISOString(), why }
+  updateSession(session.session_id, { bundle })
+  return bundle
+}
+
+// The resume text for the next agent: chb load into .baton/RESUME.md, plus a
+// short pointer prompt (argv stays small; the bundle carries the context).
+export function resumePrompt(session, bundle, next) {
+  const cwd = workRoot(session)
+  let loaded = ''
+  try {
+    const r = chb(['load', bundle.id], { cwd })
+    if (r.status === 0) loaded = r.stdout
+  } catch {}
+  const header = `# Leg handoff\n\nPrevious agent: ${session.agent} (${session.account}). Reason: ${session.limit?.reason ?? session.handoff?.reason ?? 'handoff requested'}${session.limit?.detail ? `, ${session.limit.detail}` : ''}.\nNext agent: ${next.agent} (${next.account}).\nBundle: ${bundle.path}\n\n`
+  const body = header + (loaded || readFileSync(bundle.notes, 'utf8'))
+  // src/resume.mjs owns both files: the per-session one so two sessions sharing
+  // one checkout (--no-worktree, or two started in the same instant) never
+  // overwrite each other's handoff, and RESUME.md, the copy everyone opens.
+  // Both are stamped with the git state and the live terminals they describe,
+  // so `baton resume --check` can tell a reader when they stopped being true.
+  const why = session.limit?.reason ?? session.handoff?.reason ?? 'handoff requested'
+  writeHandoffPointer(session, body, { bundle, why })
+  const perSession = perSessionFile(cwd, session.session_id)
+  const task = session.task ? `\n\nThe task, as the human first stated it: ${session.task.slice(0, 700)}` : ''
+  // the absolute path: the next agent is spawned in the session's cwd, which is
+  // a subdirectory of the work root whenever Baton was started in one
+  return `You are taking over an interactive coding session from ${session.agent}, which hit its usage limit. Read ${perSession} (the context handoff bundle is at ${bundle.path}), check git status and git diff, then continue the work from where it stopped. Do not ask the human to restate the task.${task}`
+}
+
+// Freshness, never existence: src/resume.mjs recomputes it from git at read
+// time. `resumeFileExists` used to live here and answered "a file is on disk",
+// which every caller then read as "the handoff it describes is still true".
+export { resumeVerdict } from './resume.mjs'

package/src/cards.mjs

@@ -0,0 +1,114 @@
+// cards — create a card from loosely typed input (CLI flags or a JSON body):
+// parse the chain, build and validate the pipeline, then hand the ledger the
+// exact shape. Shared by bin/baton.mjs and src/server.mjs.
+import { execFileSync } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+import { resolve, sep, join } from 'node:path'
+import { canonPath } from './fsx.mjs'
+import { homedir } from 'node:os'
+import { buildPipeline, validatePipeline, loadAdapterModes, parseChain } from './pipeline.mjs'
+import { PRESET_NAMES } from './presets.mjs'
+import { ledgerCreate, readCard } from './store.mjs'
+import { humanAction } from './orchestrator.mjs'
+
+export class CardInputError extends Error {}
+
+function samePath(a, b) {
+  return canonPath(a) === canonPath(b)
+}
+
+function isParentOf(parent, child) {
+  return canonPath(child).startsWith(canonPath(parent) + sep)
+}
+
+function list(v) {
+  if (Array.isArray(v)) return v.map(String).map((x) => x.trim()).filter(Boolean)
+  return String(v ?? '').split(',').map((x) => x.trim()).filter(Boolean)
+}
+
+// "adapter=value,adapter=value" or {adapter: value}
+function kv(raw) {
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) return raw
+  const m = {}
+  for (const part of list(raw)) {
+    const eq = part.indexOf('=')
+    if (eq <= 0) throw new CardInputError(`expected adapter=value, got "${part}"`)
+    m[part.slice(0, eq).trim()] = part.slice(eq + 1)
+  }
+  return m
+}
+
+export async function createCard(input, actor = { type: 'human', id: 'local' }) {
+  if (!input.repo) throw new CardInputError('missing repo')
+  // stored as given (resolved); every comparison below is canonical, and the
+  // worktree path is derived from the real long form in src/worktree.mjs
+  const repo = resolve(String(input.repo))
+  if (!existsSync(repo)) throw new CardInputError(`repo not found: ${repo}`)
+  if (!statSync(repo).isDirectory()) throw new CardInputError(`repo is not a directory: ${repo}`)
+  let top
+  try {
+    top = execFileSync('git', ['-C', repo, 'rev-parse', '--show-toplevel'], { windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } }).trim()
+  } catch {
+    throw new CardInputError(`repo is not a git repository: ${repo}`)
+  }
+  const resolvedTop = resolve(top)
+  if (!samePath(resolvedTop, repo)) throw new CardInputError(`repo is not the repository root: ${repo} (root is ${resolvedTop})`)
+  // the trunk must exist now: a card whose trunk is missing would otherwise be
+  // refused by the worktree step on every scheduler tick, an error event each time
+  const trunk = String(input.trunk || 'main')
+  const gitq = (args) => { try { return execFileSync('git', ['-C', repo, ...args], { windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' }, stdio: ['ignore', 'pipe', 'ignore'] }).trim() } catch { return null } }
+  if (gitq(['rev-parse', '--verify', '--quiet', `refs/heads/${trunk}`]) === null) {
+    const actual = gitq(['symbolic-ref', '--short', 'HEAD'])
+    throw new CardInputError(`trunk ${trunk} does not exist in ${repo}${actual ? `; this repo's default branch is ${actual} (add the card with --trunk ${actual})` : ''}`)
+  }
+  const legHome = resolve(process.env.LEG_HOME || process.env.BATON_HOME || (existsSync(join(homedir(), '.leg')) ? join(homedir(), '.leg') : existsSync(join(homedir(), '.baton')) ? join(homedir(), '.baton') : join(homedir(), '.leg')))
+  if (samePath(repo, legHome) || isParentOf(repo, legHome)) throw new CardInputError('repo cannot contain LEG_HOME')
+  const task = String(input.task ?? '').trim()
+  if (!task) throw new CardInputError('missing task')
+  if (!input.chain || (Array.isArray(input.chain) && !input.chain.length)) throw new CardInputError('missing chain (e.g. claude,codex)')
+  let chain
+  try { chain = parseChain(input.chain) } catch (err) { throw new CardInputError(err.message) }
+  const modes = kv(input.mode)
+  const turns = kv(input.maxTurns ?? input.max_turns)
+  const fakeModes = kv(input.fakeMode ?? input.fake_mode)
+  const fakeFixtures = kv(input.fakeFixture ?? input.fake_fixture)
+  const fakeTargets = kv(input.fakeTarget ?? input.fake_target)
+  const fakeContents = kv(input.fakeContent ?? input.fake_content)
+  const models = kv(input.model)
+  const approve = list(input.approve)
+  chain = chain.map((e) => ({
+    ...e,
+    ...(modes[e.adapter] ? { mode: modes[e.adapter] } : {}),
+    ...(turns[e.adapter] ? { maxTurns: parseInt(turns[e.adapter], 10) } : {}),
+    ...(models[e.adapter] ? { model: models[e.adapter] } : {}),
+    ...(fakeModes[e.adapter] ? { fakeMode: fakeModes[e.adapter] } : {}),
+    ...(fakeFixtures[e.adapter] ? { fakeFixture: fakeFixtures[e.adapter] } : {}),
+    ...(fakeTargets[e.adapter] ? { fakeTarget: fakeTargets[e.adapter] } : {}),
+    ...(fakeContents[e.adapter] ? { fakeContent: fakeContents[e.adapter] } : {}),
+    ...(approve.includes(e.adapter) ? { approve: true } : {}),
+  }))
+  const pipelineArg = input.pipeline ?? 'build'
+  let pipeline
+  try {
+    if (Array.isArray(pipelineArg)) pipeline = buildPipeline({ stations: pipelineArg, chain })
+    else if (typeof pipelineArg === 'string' && pipelineArg.trim().startsWith('[')) pipeline = buildPipeline({ stations: JSON.parse(pipelineArg), chain })
+    else if (PRESET_NAMES.includes(pipelineArg)) pipeline = buildPipeline({ preset: pipelineArg, chain })
+    else pipeline = buildPipeline({ file: pipelineArg, chain })
+    validatePipeline(pipeline, await loadAdapterModes())
+  } catch (err) {
+    throw new CardInputError(`invalid pipeline: ${err.message}`)
+  }
+  const landMode = input.landMode ?? input.land_mode ?? 'ff'
+  if (!['ff', 'pr'].includes(landMode)) throw new CardInputError(`invalid land mode "${landMode}" (ff or pr)`)
+  const leases = list(input.leases)
+  const slug = (input.slug || task.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 30)) || 'card'
+  const id = ledgerCreate({
+    slug, task, repo,
+    chain: chain.map((e) => ({ adapter: e.adapter, mode: e.mode ?? null, max_turns: e.maxTurns ?? null, ...(e.model ? { model: e.model } : {}) })),
+    pipeline, leases, trunk: input.trunk || 'main', 'land-mode': landMode,
+    'test-command': input.testCommand ?? input.test_command ?? null, title: input.title || null,
+    actor: JSON.stringify(actor),
+  })
+  if (input.queue) humanAction(id, 'enqueue', {}, actor)
+  return readCard(id)
+}

package/src/chain.mjs

@@ -0,0 +1,264 @@
+// chain — the card state machine. Pure: `transition(card, action, payload)`
+// returns the patched card plus the ledger events to append; no I/O. Two
+// machines live here: the station machine (a card moves through its pipeline)
+// and the chain machine (inside an agent station, legs hand off to the next
+// adapter on limit / incomplete / no_progress / stalled / failed).
+// TRANSITIONS is data so tests print the table and docs embed it.
+import { stationIndex } from './pipeline.mjs'
+
+export const TERMINAL = ['done', 'failed', 'killed']
+export const NON_TERMINAL = ['backlog', 'queued', 'running', 'handing_off', 'waiting_human', 'needs_approval', 'paused']
+
+// [from, action, to, note]
+export const TRANSITIONS = [
+  ['backlog', 'enqueue', 'queued', 'human adds the card to the floor (or `card run`)'],
+  ['queued', 'start', 'running', 'scheduler starts a leg (agent/test/land station) under the card\'s leases'],
+  ['queued', 'reach_human', 'waiting_human', 'a human station is next'],
+  ['running', 'leg:completed', 'queued', 'agent leg completed → next station (leg 0)'],
+  ['running', 'leg:completed', 'done', 'agent leg completed and it was the last station'],
+  ['running', 'leg:completed', 'waiting_human', 'agent leg completed and a human station is next'],
+  ['running', 'leg:handoff', 'handing_off', 'limit | incomplete | no_progress | stalled | failed and the chain has a next leg'],
+  ['running', 'leg:handoff', 'failed', 'same outcomes with the chain exhausted'],
+  ['running', 'leg:auth_failed', 'failed', 'Baton/environment fault; no advance; human fixes and clicks Rerun'],
+  ['running', 'leg:launch_failed', 'failed', 'same'],
+  ['running', 'leg:killed', 'killed', 'the leg was killed from the board'],
+  ['handing_off', 'bundle_written', 'queued', 'next leg (leg+1) queued at the same station'],
+  ['handing_off', 'bundle_written', 'needs_approval', 'next chain entry has approve: true'],
+  ['running', 'test:green', 'queued', 'test station passed → next station'],
+  ['running', 'test:green', 'done', 'test station passed and it was last'],
+  ['running', 'test:red', 'queued', 'bounce to the nearest earlier build station (or the first agent station) with bounce_reason'],
+  ['running', 'land:landed', 'done', 'land station merged (phase 7: real merge queue)'],
+  ['running', 'land:bounced', 'queued', 'land red/conflict → bounce to build with the failure attached (phase 7)'],
+  ['running', 'land:failed', 'failed', 'land attempts exhausted (phase 7)'],
+  ['running', 'pause', 'paused', 'human: kill the child, write a bundle'],
+  ['paused', 'resume', 'queued', 'human: same station and leg; prompt = bundle load + contract'],
+  ['*non-terminal*', 'kill', 'killed', 'human'],
+  ['*non-terminal*', 'reassign', 'queued', 'human: rewrite the current station\'s chain from the current leg'],
+  ['running', 'handoff_now', 'handing_off', 'human: as if the leg ended incomplete'],
+  ['needs_approval', 'approve', 'queued', 'human'],
+  ['waiting_human', 'approve', 'queued', 'human: the human station is done → next station'],
+  ['waiting_human', 'approve', 'done', 'human station was last'],
+  ['*terminal*', 'rerun', 'queued', 'human: station 0, leg 0, same worktree, new run number'],
+]
+
+export class IllegalTransition extends Error {
+  constructor(from, action, to) {
+    super(`illegal transition ${from} --${action}--> ${to ?? '?'}`)
+    this.name = 'IllegalTransition'
+  }
+}
+
+const HANDOFF_OUTCOMES = ['limit', 'incomplete', 'no_progress', 'stalled', 'failed']
+const NO_ADVANCE_OUTCOMES = ['auth_failed', 'launch_failed']
+
+function station(card) {
+  const i = stationIndex(card.pipeline, card.station)
+  return { i, s: card.pipeline[i] ?? null }
+}
+
+function ev(type, summary, body) {
+  const e = { type, summary }
+  if (body) e.body = body
+  return e
+}
+
+// Where the card goes after the station at index i is done.
+function advance(card, i, events) {
+  const next = card.pipeline[i + 1]
+  events.push(ev('station_done', `station ${card.pipeline[i].name} done${next ? ` → ${next.name}` : ''}`))
+  if (!next) {
+    events.push(ev('done', `card done: all ${card.pipeline.length} station(s) complete`))
+    return { ...card, status: 'done', leg: 0 }
+  }
+  if (next.kind === 'human') return { ...card, station: next.name, leg: 0, status: 'waiting_human' }
+  return { ...card, station: next.name, leg: 0, status: 'queued' }
+}
+
+// The agent station a red test or a bounced land goes back to: the nearest
+// earlier `build`, else the first agent station BEFORE the failing one. An
+// agent station after it is never a target: the card would skip the station
+// it just failed and finish `done` with red tests.
+function bounceTarget(card, i) {
+  for (let k = i - 1; k >= 0; k--) {
+    const s = card.pipeline[k]
+    if (s.kind === 'agent' && s.name === 'build') return s
+  }
+  return card.pipeline.slice(0, i).find((s) => s.kind === 'agent') ?? null
+}
+
+function assertStatus(card, action, allowed) {
+  if (!allowed.includes(card.status)) throw new IllegalTransition(card.status, action)
+}
+
+export function transition(card, action, payload = {}) {
+  const events = []
+  const { i, s } = station(card)
+
+  switch (action) {
+    case 'enqueue': {
+      assertStatus(card, action, ['backlog'])
+      const first = card.pipeline[0]
+      if (!first) throw new IllegalTransition(card.status, action, 'queued')
+      // No ledger event: the status change itself is the record (the board
+      // reads card.json); events are reserved for things that happened.
+      if (first.kind === 'human') return { card: { ...card, station: first.name, leg: 0, status: 'waiting_human' }, events: [] }
+      return { card: { ...card, station: first.name, leg: 0, status: 'queued' }, events: [] }
+    }
+    case 'start': {
+      assertStatus(card, action, ['queued'])
+      if (!s) throw new IllegalTransition(card.status, action, 'running')
+      if (s.kind === 'human') return { card: { ...card, status: 'waiting_human' }, events: [] }
+      return { card: { ...card, status: 'running' }, events: [] }
+    }
+    case 'leg_result': {
+      // payload: { outcome, handoff, signal, adapter, run }
+      assertStatus(card, action, ['running'])
+      if (!s || s.kind !== 'agent') throw new IllegalTransition(card.status, action)
+      const { outcome } = payload
+      const tag = `${payload.adapter ?? s.chain[card.leg]?.adapter} leg ${card.leg}${payload.signal && payload.signal !== 'none' ? ` (${payload.signal})` : ''}`
+      if (outcome === 'completed') return { card: advance(card, i, events), events }
+      if (outcome === 'killed') {
+        events.push(ev('killed', `${tag} killed`))
+        return { card: { ...card, status: 'killed' }, events }
+      }
+      if (NO_ADVANCE_OUTCOMES.includes(outcome)) {
+        events.push(ev('failed', `${tag}: ${outcome}; not advancing (fix the environment and rerun)`))
+        return { card: { ...card, status: 'failed', failure: outcome }, events }
+      }
+      if (HANDOFF_OUTCOMES.includes(outcome)) {
+        const next = s.chain[card.leg + 1]
+        if (!next) {
+          events.push(ev('failed', `${tag}: ${outcome}; chain exhausted at ${s.name}`))
+          return { card: { ...card, status: 'failed', failure: outcome }, events }
+        }
+        return { card: { ...card, status: 'handing_off', handoff_outcome: outcome, next_leg: card.leg + 1 }, events }
+      }
+      throw new Error(`unknown leg outcome "${outcome}"`)
+    }
+    case 'bundle_written': {
+      assertStatus(card, action, ['handing_off'])
+      const nextLeg = card.next_leg ?? card.leg + 1
+      const entry = s?.chain?.[nextLeg]
+      if (!entry) throw new IllegalTransition(card.status, action)
+      const from = s.chain[card.leg]?.adapter
+      if (entry.approve) {
+        events.push(ev('approval_needed', `${from} → ${entry.adapter} needs approval before leg ${nextLeg}`))
+        return { card: { ...card, leg: nextLeg, status: 'needs_approval', next_leg: null }, events }
+      }
+      // The handoff_written event (orchestrator) already names from → to; the
+      // next leg_started (supervisor) names the adapter. No extra event here.
+      void from
+      return { card: { ...card, leg: nextLeg, status: 'queued', next_leg: null }, events }
+    }
+    case 'test_result': {
+      assertStatus(card, action, ['running'])
+      if (!s || s.kind !== 'test') throw new IllegalTransition(card.status, action)
+      if (payload.green) return { card: advance(card, i, events), events }
+      const target = bounceTarget(card, i)
+      // test and land bounces share one counter (land_attempts) and one cap, so a
+      // card that never goes green cannot loop forever
+      const attempts = (card.land_attempts ?? 0) + 1
+      const max = Math.max(1, parseInt((process.env.LEG_MAX_LAND_ATTEMPTS || process.env.BATON_MAX_LAND_ATTEMPTS) || '3', 10) || 3)
+      if (!target || attempts >= max) {
+        events.push(ev('failed', target ? `test red after ${attempts} attempt(s)` : 'test red and no agent station to bounce to', payload.reason))
+        return { card: { ...card, status: 'failed', failure: 'test', land_attempts: attempts }, events }
+      }
+      events.push(ev('bounced', `test red (attempt ${attempts}) → ${target.name}`, payload.reason))
+      // the next build leg starts from the bounce bundle (the failure is in its Open findings)
+      return { card: { ...card, station: target.name, leg: 0, status: 'queued', land_attempts: attempts, bounce_reason: payload.reason ?? 'test red', resume_from_bundle: true }, events }
+    }
+    case 'land_result': {
+      // payload: { landed, bounced, reason } — phase 7 fills the real queue
+      assertStatus(card, action, ['running'])
+      if (!s || s.kind !== 'land') throw new IllegalTransition(card.status, action)
+      if (payload.landed) {
+        events.push(ev('landed', payload.summary ?? 'landed on trunk', payload.body))
+        return { card: advance(card, i, events), events }
+      }
+      if (payload.pr) {
+        // pr land mode: the human merges; the card waits at the land station
+        events.push(ev('approval_needed', payload.summary ?? `pull request opened: ${payload.url ?? ''}`))
+        return { card: { ...card, status: 'waiting_human', pr_url: payload.url ?? null }, events }
+      }
+      const attempts = (card.land_attempts ?? 0) + 1
+      const maxAttempts = Math.max(1, parseInt((process.env.LEG_MAX_LAND_ATTEMPTS || process.env.BATON_MAX_LAND_ATTEMPTS) || '3', 10) || 3)
+      const target = payload.bounced ? bounceTarget(card, i) : null
+      if (target && attempts < maxAttempts) {
+        events.push(ev('bounced', `land bounced (attempt ${attempts}) → ${target.name}`, payload.reason))
+        return { card: { ...card, station: target.name, leg: 0, status: 'queued', land_attempts: attempts, bounce_reason: payload.reason ?? 'land bounced', resume_from_bundle: true }, events }
+      }
+      events.push(ev('failed', payload.bounced && !target ? 'land bounced and no agent station to bounce to' : `land failed after ${attempts} attempt(s)`, payload.reason))
+      return { card: { ...card, status: 'failed', land_attempts: attempts, failure: 'land' }, events }
+    }
+    // ---- human actions ----
+    case 'pause': {
+      assertStatus(card, action, ['running'])
+      events.push(ev('paused', 'paused by human'))
+      return { card: { ...card, status: 'paused' }, events }
+    }
+    case 'resume': {
+      assertStatus(card, action, ['paused'])
+      events.push(ev('resumed', `resumed at ${card.station} leg ${card.leg}`))
+      return { card: { ...card, status: 'queued', resume_from_bundle: true }, events }
+    }
+    case 'kill': {
+      assertStatus(card, action, NON_TERMINAL)
+      events.push(ev('killed', 'killed by human'))
+      return { card: { ...card, status: 'killed', kill_requested: true }, events }
+    }
+    case 'reassign': {
+      assertStatus(card, action, NON_TERMINAL)
+      if (!s || s.kind !== 'agent') throw new IllegalTransition(card.status, action)
+      if (!payload.adapter) throw new Error('reassign needs an adapter')
+      const entry = { adapter: payload.adapter }
+      if (payload.mode) entry.mode = payload.mode
+      const chain = [...s.chain.slice(0, card.leg), entry, ...s.chain.slice(card.leg + 1)]
+      const pipeline = card.pipeline.map((st) => (st.name === s.name ? { ...st, chain } : st))
+      events.push(ev('reassigned', `leg ${card.leg} at ${s.name} reassigned to ${payload.adapter}${payload.mode ? ` (${payload.mode})` : ''}`))
+      return { card: { ...card, pipeline, status: 'queued', kill_requested: card.status === 'running' }, events }
+    }
+    case 'handoff_now': {
+      assertStatus(card, action, ['running'])
+      if (!s || s.kind !== 'agent') throw new IllegalTransition(card.status, action)
+      const next = s.chain[card.leg + 1]
+      if (!next) throw new IllegalTransition(card.status, action, 'handing_off')
+      events.push(ev('status', 'handoff requested by human'))
+      return { card: { ...card, status: 'handing_off', handoff_outcome: 'incomplete', next_leg: card.leg + 1, kill_requested: true }, events }
+    }
+    case 'approve': {
+      assertStatus(card, action, ['needs_approval', 'waiting_human'])
+      if (card.status === 'needs_approval') {
+        events.push(ev('approved', `leg ${card.leg} at ${card.station} approved`))
+        return { card: { ...card, status: 'queued' }, events }
+      }
+      events.push(ev('approved', `human station ${card.station} approved`))
+      return { card: advance(card, i, events), events }
+    }
+    case 'rerun': {
+      assertStatus(card, action, TERMINAL)
+      const first = card.pipeline[0]
+      events.push(ev('status', `rerun from ${first.name} leg 0`))
+      return { card: { ...card, station: first.name, leg: 0, status: first.kind === 'human' ? 'waiting_human' : 'queued', land_attempts: 0, bounce_reason: null, failure: null, kill_requested: false }, events }
+    }
+    default:
+      throw new Error(`unknown action "${action}"`)
+  }
+}
+
+export const HUMAN_ACTIONS = ['pause', 'resume', 'kill', 'reassign', 'handoff_now', 'approve', 'rerun']
+
+// Which human buttons make sense for a card right now (the board asks this).
+export function availableActions(card) {
+  const out = []
+  const st = card.status
+  const { s } = station(card)
+  if (st === 'running') out.push('pause')
+  // the transition refuses handoff_now without a next chain entry, so the board must not offer it
+  if (st === 'running' && s?.kind === 'agent' && s.chain?.[card.leg + 1]) out.push('handoff_now')
+  if (st === 'paused') out.push('resume')
+  if (st === 'needs_approval' || st === 'waiting_human') out.push('approve')
+  if (NON_TERMINAL.includes(st)) { out.push('kill'); if (s?.kind === 'agent') out.push('reassign') }
+  if (TERMINAL.includes(st)) out.push('rerun')
+  if (st === 'backlog') out.push('enqueue')
+  return out
+}

package/src/commands.mjs

@@ -0,0 +1,79 @@
+// commands — run a repository command (tests) as argv, never through a shell.
+// `npm`/`npx`/`node` resolve to node + their JS entry so the Windows .cmd shim
+// is never needed (LESSONS 07-11).
+import { spawnSync, spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { resolveNpmCliEntry } from './adapters/resolve.mjs'
+import { scrub } from './runner.mjs'
+
+function tokenize(cmd) {
+  return cmd.match(/(?:[^\s"]+|"[^"]*")+/g)?.map((t) => t.replace(/^"|"$/g, '')) ?? []
+}
+
+export function resolveCommand(cmd) {
+  const tokens = tokenize(cmd)
+  if (!tokens.length) throw new Error('empty test command')
+  const [bin, ...rest] = tokens
+  if (bin === 'node') return { bin: process.execPath, args: rest }
+  if (bin === 'npm' || bin === 'npx') {
+    const entry = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', `${bin}-cli.js`)
+    const found = existsSync(entry) ? entry : resolveNpmCliEntry('npm', bin)
+    if (!found) throw new Error(`cannot resolve ${bin}'s JS entry`)
+    return { bin: process.execPath, args: [found, ...rest] }
+  }
+  return { bin, args: rest }
+}
+
+// A nested `node --test` inherits NODE_TEST_CONTEXT from a parent test runner
+// and then reports to that parent instead of exiting red; the repo's tests
+// must run as a plain process.
+function commandEnv() {
+  const env = { ...process.env, MSYS_NO_PATHCONV: '1', CI: '1' }
+  for (const k of Object.keys(env)) if (k.startsWith('NODE_TEST')) delete env[k]
+  return env
+}
+
+export function runCommand(cmd, cwd, { timeoutMs = 600000, tailLines = 40 } = {}) {
+  const { bin, args } = resolveCommand(cmd)
+  const r = spawnSync(bin, args, { cwd, windowsHide: true, encoding: 'utf8', timeout: timeoutMs, env: commandEnv() })
+  const tail = scrub(`${r.stdout ?? ''}\n${r.stderr ?? ''}`).trim().split('\n').slice(-tailLines).join('\n')
+  return { green: r.status === 0, status: r.status, timedOut: r.error?.code === 'ETIMEDOUT', tail, command: `${bin} ${args.join(' ')}` }
+}
+
+// The same result without blocking the event loop: the board server lands a
+// terminal's branch in-process, and a long test run must not freeze the board.
+export function runCommandAsync(cmd, cwd, { timeoutMs = 600000, tailLines = 40 } = {}) {
+  const { bin, args } = resolveCommand(cmd)
+  return new Promise((resolvePromise) => {
+    let out = ''
+    let timedOut = false
+    let done = false
+    const child = spawn(bin, args, { cwd, windowsHide: true, env: commandEnv() })
+    const keep = (d) => { out += d; if (out.length > 2e6) out = out.slice(-1e6) }
+    child.stdout.on('data', keep)
+    child.stderr.on('data', keep)
+    // On timeout, kill the whole process TREE: child.kill() ends only the npm
+    // node process, and a grandchild (a watcher, a dev server) keeps the stdio
+    // pipes open so 'close' never fires and the landing hangs in 'landing'
+    // forever, wedging the repo's merge queue. taskkill /T /F takes the tree.
+    const timer = setTimeout(() => {
+      timedOut = true
+      if (process.platform === 'win32' && child.pid) { try { spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true }) } catch {} }
+      else { try { child.kill('SIGKILL') } catch {} }
+    }, timeoutMs)
+    const finish = (status, err) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      const tail = scrub(`${out}${err ? `\n${err.message}` : ''}`).trim().split('\n').slice(-tailLines).join('\n')
+      resolvePromise({ green: status === 0 && !timedOut, status, timedOut, tail, command: `${bin} ${args.join(' ')}` })
+    }
+    child.on('error', (err) => finish(null, err))
+    // resolve on 'exit' (fires when the process ends) as well as 'close' (waits
+    // for every inherited pipe to close, which a detached grandchild can hold
+    // open indefinitely); finish is idempotent via `done`
+    child.on('exit', (code) => finish(code))
+    child.on('close', (code) => finish(code))
+  })
+}

package/src/contract.mjs

@@ -0,0 +1,73 @@
+// contract — the per-leg prompt. Every CLI gets the same contract file at
+// .baton/CONTRACT.md in the worktree (CLI-agnostic completion: write
+// .baton/DONE when finished). Leg 1 prompt = the contract; a later leg or a
+// resume = the handoff bundle's resume text + the contract.
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const TEMPLATES = {
+  plan: () => import('./stations/plan.mjs'),
+  build: () => import('./stations/build.mjs'),
+  review: () => import('./stations/review.mjs'),
+}
+
+export async function stationTemplate(name = 'build') {
+  const load = TEMPLATES[name] ?? TEMPLATES.build
+  return (await load()).default
+}
+
+export async function renderContract({ card, station, leg, entry, worktree, resumed = false, bounceReason = null }) {
+  const t = await stationTemplate(station.prompt ?? station.name)
+  const lines = [
+    `# Leg contract, card ${card.card_id}, station ${station.name}, leg ${leg} (${entry?.adapter ?? 'agent'})`,
+    '',
+    '## Task',
+    '',
+    card.task,
+    '',
+    '## Station goal',
+    '',
+    t.goal,
+    '',
+    ...t.deliverables.map((d) => `- ${d}`),
+    '',
+  ]
+  if (bounceReason) {
+    lines.push('## Why this card came back', '', bounceReason, '')
+  }
+  if (resumed) {
+    lines.push('## Continuation', '',
+      'A previous agent already worked on this card in this same directory. Its handoff resume is above this contract; .leg/PROGRESS.md holds its notes. Continue from there; do not start over.', '')
+  }
+  lines.push(
+    '## Rules',
+    '',
+    `- Work only inside this directory: ${worktree}. It is a git worktree on its own branch; commit as you go or leave changes uncommitted, both are fine.`,
+    '- Keep .leg/PROGRESS.md updated as you go: one line per meaningful step, newest last. It is how the next agent (or a human) picks up if you stop early.',
+    '- Do not push, do not create remotes, do not open pull requests, do not change git config.',
+    '- Do not touch anything under .leg/ except PROGRESS.md and DONE.',
+    '- No interactive prompt will be answered; if you need a permission you do not have, write what you need to .leg/PROGRESS.md and stop.',
+    '',
+    '## Finish',
+    '',
+    'When the task is finished and verified, write the file .leg/DONE containing one line that summarizes what you did. Without that file Leg treats the run as unfinished and hands it to the next agent.',
+    '',
+  )
+  return lines.join('\n')
+}
+
+export function writeContract(worktree, text) {
+  const dir = join(worktree, '.leg')
+  mkdirSync(dir, { recursive: true })
+  const path = join(dir, 'CONTRACT.md')
+  writeFileSync(path, text)
+  return path
+}
+
+export function legPrompt({ contractText, resumeText = null }) {
+  const head = 'You are working on a Leg card. The contract below is also saved at .leg/CONTRACT.md.'
+  if (resumeText) {
+    return `${head}\n\n=== HANDOFF RESUME (from the previous agent) ===\n\n${resumeText.trim()}\n\n=== CONTRACT ===\n\n${contractText}`
+  }
+  return `${head}\n\n${contractText}`
+}