@ucsandman/legcli 0.7.0

package/src/pipeline.mjs

@@ -0,0 +1,100 @@
+// Pipeline = ordered stations a card moves through. Board columns derive from
+// it (phase 6). Validation happens at card creation so a forbidden mode or a
+// misplaced land station never reaches a worktree.
+import { readFileSync } from 'node:fs'
+import { PRESETS, PRESET_NAMES } from './presets.mjs'
+import { get as getAdapter, names as adapterNames } from './adapters/index.mjs'
+
+export const KINDS = ['agent', 'human', 'test', 'land']
+const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,29}$/
+
+// chain entry: { adapter, mode?, maxTurns?, approve?, network?, fakeMode?, model? }
+export function normalizeChainEntry(e) {
+  if (!e || typeof e !== 'object' || typeof e.adapter !== 'string') throw new Error('chain entry needs an adapter name')
+  const out = { adapter: e.adapter }
+  if (e.mode !== undefined && e.mode !== null) out.mode = String(e.mode)
+  const mt = e.maxTurns ?? e.max_turns
+  if (mt !== undefined && mt !== null) {
+    out.maxTurns = Number(mt)
+    if (!Number.isInteger(out.maxTurns) || out.maxTurns < 1) throw new Error(`chain entry ${e.adapter}: maxTurns must be a positive integer`)
+  }
+  if (e.approve) out.approve = true
+  if (e.network) out.network = true
+  if (e.fakeMode !== undefined) out.fakeMode = String(e.fakeMode)
+  for (const k of ['fakeFixture', 'fakeTarget', 'fakeContent']) if (e[k] !== undefined && e[k] !== null) out[k] = String(e[k])
+  if (e.model !== undefined && e.model !== null) out.model = String(e.model)
+  return out
+}
+
+// "claude,codex" | [{adapter}] → normalized entries
+export function parseChain(raw) {
+  if (Array.isArray(raw)) return raw.map(normalizeChainEntry)
+  if (typeof raw === 'string') {
+    const s = raw.trim()
+    if (s.startsWith('[')) return JSON.parse(s).map(normalizeChainEntry)
+    return s.split(',').map((x) => x.trim()).filter(Boolean).map((adapter) => ({ adapter }))
+  }
+  throw new Error('chain must be a comma list or a JSON array')
+}
+
+// preset name | path to a JSON file | array → stations with the default chain applied
+export function buildPipeline({ preset, file, stations, chain }) {
+  let base
+  if (Array.isArray(stations)) base = stations
+  else if (file) base = JSON.parse(readFileSync(file, 'utf8'))
+  else base = PRESETS[preset ?? 'build']
+  if (!base) throw new Error(`unknown pipeline preset "${preset}" (known: ${PRESET_NAMES.join(', ')})`)
+  if (!Array.isArray(base)) throw new Error('pipeline must be an array of stations')
+  return base.map((s) => {
+    const st = { name: s.name, kind: s.kind }
+    if (s.prompt) st.prompt = s.prompt
+    if (s.kind === 'agent') st.chain = (s.chain ?? chain ?? []).map(normalizeChainEntry)
+    if (s.command) st.command = s.command
+    return st
+  })
+}
+
+// Registered adapters with their allowed modes, for validation.
+export async function loadAdapterModes(names = adapterNames()) {
+  const out = {}
+  for (const n of names) {
+    const a = await getAdapter(n)
+    out[n] = { allowed: a.modes.allowed, default: a.modes.default }
+  }
+  return out
+}
+
+// Throws a named error on: empty pipeline, duplicate names, unknown kinds,
+// agent station without a chain, unregistered adapter, forbidden mode, land
+// station not last or more than one.
+export function validatePipeline(pipeline, adapterModes) {
+  if (!Array.isArray(pipeline) || pipeline.length === 0) throw new Error('pipeline is empty')
+  const seen = new Set()
+  pipeline.forEach((s, i) => {
+    if (!s || typeof s.name !== 'string' || !NAME_RE.test(s.name)) throw new Error(`station ${i}: invalid name "${s?.name}"`)
+    if (seen.has(s.name)) throw new Error(`duplicate station name "${s.name}"`)
+    seen.add(s.name)
+    if (!KINDS.includes(s.kind)) throw new Error(`station "${s.name}": unknown kind "${s.kind}" (allowed: ${KINDS.join(', ')})`)
+    if (s.kind === 'agent') {
+      if (!Array.isArray(s.chain) || s.chain.length === 0) throw new Error(`station "${s.name}": agent station needs a non-empty chain`)
+      for (const e of s.chain) {
+        const modes = adapterModes[e.adapter]
+        if (!modes) throw new Error(`station "${s.name}": unknown adapter "${e.adapter}" (registered: ${Object.keys(adapterModes).join(', ')})`)
+        if (e.mode !== undefined && !modes.allowed.includes(e.mode)) {
+          throw new Error(`forbidden mode "${e.mode}" for ${e.adapter} (allowed: ${modes.allowed.join(', ')})`)
+        }
+      }
+    }
+    if (s.kind === 'land' && i !== pipeline.length - 1) throw new Error(`station "${s.name}": a land station must be last`)
+  })
+  if (pipeline.filter((s) => s.kind === 'land').length > 1) throw new Error('at most one land station')
+  return pipeline
+}
+
+export function stationIndex(pipeline, name) {
+  return pipeline.findIndex((s) => s.name === name)
+}
+
+export function columns(pipeline) {
+  return ['backlog', ...pipeline.map((s) => s.name), 'done']
+}

package/src/preferences.mjs

@@ -0,0 +1,47 @@
+// Machine-wide defaults for interactive Baton terminals. A new terminal takes
+// a copy of these preferences when it starts; later edits do not silently
+// change terminals that are already running.
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { home } from './store.mjs'
+import { writeJsonAtomic, withFileLock } from './fsx.mjs'
+
+export const HANDOFF_AGENTS = ['claude', 'codex', 'agy']
+
+export function validHandoffOrder(value) {
+  return Array.isArray(value) && value.length === HANDOFF_AGENTS.length &&
+    new Set(value).size === HANDOFF_AGENTS.length &&
+    value.every((agent) => HANDOFF_AGENTS.includes(agent))
+}
+
+export function normalizeHandoffOrder(value) {
+  return validHandoffOrder(value) ? [...value] : [...HANDOFF_AGENTS]
+}
+
+export function requireHandoffOrder(value) {
+  if (!validHandoffOrder(value)) throw new TypeError('handoff_order must contain claude, codex, and agy exactly once')
+  return [...value]
+}
+
+export function preferencesFile() { return join(home(), 'preferences.json') }
+
+export function readPreferences() {
+  const file = preferencesFile()
+  if (!existsSync(file)) return { handoff_order: [...HANDOFF_AGENTS] }
+  try {
+    const value = JSON.parse(readFileSync(file, 'utf8'))
+    return { handoff_order: normalizeHandoffOrder(value?.handoff_order) }
+  } catch {
+    return { handoff_order: [...HANDOFF_AGENTS] }
+  }
+}
+
+export function writePreferences(patch) {
+  const order = requireHandoffOrder(patch?.handoff_order)
+  mkdirSync(home(), { recursive: true })
+  return withFileLock(preferencesFile() + '.lock', () => {
+    const next = { ...readPreferences(), handoff_order: order }
+    writeJsonAtomic(preferencesFile(), next)
+    return next
+  })
+}

package/src/presets.mjs

@@ -0,0 +1,23 @@
+// Pipeline presets. A station is { name, kind, chain?, prompt? }; kinds are
+// agent | human | test | land. `chain` on an agent station defaults to the
+// card's chain when omitted (src/pipeline.mjs applies it). The v1 limit
+// handoff runs inside any agent station; `factory` is where v2 is headed.
+export const PRESETS = {
+  factory: [
+    { name: 'plan', kind: 'agent', prompt: 'plan' },
+    { name: 'build', kind: 'agent', prompt: 'build' },
+    { name: 'review', kind: 'agent', prompt: 'review' },
+    { name: 'test', kind: 'test' },
+    { name: 'land', kind: 'land' },
+  ],
+  build: [
+    { name: 'build', kind: 'agent', prompt: 'build' },
+  ],
+  'build-land': [
+    { name: 'build', kind: 'agent', prompt: 'build' },
+    { name: 'test', kind: 'test' },
+    { name: 'land', kind: 'land' },
+  ],
+}
+
+export const PRESET_NAMES = Object.keys(PRESETS)

package/src/ratelimit.mjs

@@ -0,0 +1,49 @@
+// ratelimit — fixed windows for the board's API, in memory (one process, and a
+// restart is a fresh window). Two buckets: requests per identity (a person's
+// name when they are known, else the client address) so one client cannot
+// flood the board, and failed authorizations per address so a token cannot be
+// guessed at speed. Both are deliberately generous: the board itself polls.
+import { createHash } from 'node:crypto'
+
+const WINDOW_MS = 60000
+
+export function createLimiter({
+  windowMs = WINDOW_MS,
+  max = Number((process.env.LEG_RATE_MAX || process.env.BATON_RATE_MAX) || 600),
+  maxFailures = Number((process.env.LEG_RATE_MAX_FAILURES || process.env.BATON_RATE_MAX_FAILURES) || 20),
+} = {}) {
+  const hits = new Map()
+  const fails = new Map()
+  const tried = new Map()
+  const sweep = (map, now) => { for (const [k, v] of map) if (now - v.start >= windowMs) map.delete(k) }
+  const bump = (map, key, limit, now) => {
+    if (map.size > 1000) sweep(map, now)
+    const cur = map.get(key)
+    if (!cur || now - cur.start >= windowMs) { map.set(key, { start: now, n: 1 }); return { ok: true, count: 1, retry_after: 0 } }
+    cur.n += 1
+    if (cur.n > limit) return { ok: false, count: cur.n, retry_after: Math.max(1, Math.ceil((cur.start + windowMs - now) / 1000)) }
+    return { ok: true, count: cur.n, retry_after: 0 }
+  }
+  // Guessing means trying tokens; a board page retrying the one token it was
+  // given (a tab open since `share rotate`) is not, and must not lock the
+  // machine it runs on out of its own board. One value counts once a window.
+  const guess = (key, token, now) => {
+    if (!token) return true
+    const h = createHash('sha256').update(String(token)).digest('hex')
+    const cur = tried.get(key)
+    if (!cur || now - cur.start >= windowMs) { if (tried.size > 1000) sweep(tried, now); tried.set(key, { start: now, seen: new Set([h]) }); return true }
+    if (cur.seen.has(h)) return false
+    cur.seen.add(h)
+    return true
+  }
+  return {
+    request: (key, now = Date.now()) => bump(hits, key, max, now),
+    failure: (key, token = null, now = Date.now()) => (guess(key, token, now) ? bump(fails, key, maxFailures, now) : { ok: true, count: fails.get(key)?.n ?? 0, retry_after: 0 }),
+    // true once this address has spent its failed-token budget for the window
+    lockedOut: (key, now = Date.now()) => { const cur = fails.get(key); return Boolean(cur && now - cur.start < windowMs && cur.n > maxFailures) },
+    retryAfter: (key, now = Date.now()) => { const cur = fails.get(key); return cur ? Math.max(1, Math.ceil((cur.start + windowMs - now) / 1000)) : 1 },
+    reset: () => { hits.clear(); fails.clear(); tried.clear() },
+    max,
+    maxFailures,
+  }
+}

package/src/redact.mjs

@@ -0,0 +1,47 @@
+// redact — the one list of secret shapes. `scrub()` rewrites (logs, bundles,
+// launcher output); the ledger's assertNoSecrets refuses (src/ledger.mjs).
+// The source tooling kept two copies on purpose; Baton keeps one here.
+// Values the launcher's own process holds for the well-known key variables
+// are read once at startup and never printed.
+// Every prefix shape starts at a token boundary: the `sk-` inside
+// "task-management-system" is a word, not a key, and the ledger refuses a card
+// whose task matches.
+const PATTERNS = [
+  ['api key (sk-)', /(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{8,}/g],
+  ['Anthropic key (sk-ant-)', /(?<![A-Za-z0-9_-])sk-ant-[A-Za-z0-9_-]{8,}/g],
+  ['DashClaw key (oc_live_)', /(?<![A-Za-z0-9_-])oc_live_[a-f0-9]\w*/g],
+  ['bearer token', /Bearer\s+[A-Za-z0-9._-]{16,}/g],
+  ['GitHub token (ghp_)', /(?<![A-Za-z0-9_-])ghp_[A-Za-z0-9]{20,}/g],
+  ['GitHub server token (ghs_)', /(?<![A-Za-z0-9_-])ghs_[A-Za-z0-9]{20,}/g],
+  ['GitHub fine-grained token (github_pat_)', /(?<![A-Za-z0-9_-])github_pat_[A-Za-z0-9_]{20,}/g],
+  ['AWS key (AKIA)', /(?<![A-Za-z0-9_-])AKIA[0-9A-Z]{12,}/g],
+  ['Slack token (xox)', /(?<![A-Za-z0-9_-])xox[bp]-\S*/g],
+  ['key=value secret', /api[_-]?key\s*[=:]\s*\S+/gi],
+]
+
+export const SECRET_RES = PATTERNS.map(([, re]) => re)
+// non-global copies for `.test()` (a /g regex carries lastIndex state)
+export const SECRET_PATTERNS = PATTERNS.map(([name, re]) => [name, new RegExp(re.source, re.flags.replace('g', ''))])
+
+const ENV_KEYS = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'OPENAI_API_KEY', 'DASHCLAW_API_KEY', 'BATON_TOKEN', 'GITHUB_TOKEN', 'GH_TOKEN']
+let envValues = null
+function heldValues() {
+  if (envValues) return envValues
+  envValues = ENV_KEYS.map((k) => process.env[k]).filter((v) => typeof v === 'string' && v.length >= 8)
+  return envValues
+}
+
+export function scrub(s) {
+  let out = String(s)
+  for (const re of SECRET_RES) { re.lastIndex = 0; out = out.replace(re, '[REDACTED]') }
+  return out
+}
+
+export function redact(line) {
+  let out = scrub(line)
+  for (const v of heldValues()) out = out.split(v).join('[REDACTED]')
+  return out
+}
+
+// tests plant a value and need the cache dropped
+export function _resetHeldValues() { envValues = null }

package/src/resume.mjs

@@ -0,0 +1,354 @@
+// resume — the pointer that cannot describe a picture that is no longer true.
+//
+// `.baton/RESUME.md` is the file humans and other agents open by habit. It used
+// to be an unowned convenience copy: written once per hand-off, never touched
+// again, with no stamp and no expiry, so a normally exited terminal left hours
+// old text sitting there looking live.
+//
+// Two rules fix that, and they are the whole module:
+//   1. Every resume file Baton writes carries a stamp of the git state and the
+//      live terminals it was written against (an HTML comment, invisible in
+//      rendered markdown).
+//   2. Freshness is never remembered — it is recomputed from git at READ time.
+//      A file cannot lie about HEAD to a reader who re-asks git.
+// Baton owns the file: it rewrites it when a session ends and when the board
+// starts, so nothing is left describing a terminal that is gone.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { dirname, join, resolve } from 'node:path'
+import { canonPath } from './fsx.mjs'
+import { isActive, listSessions, reapLost, workRoot } from './sessions.mjs'
+
+export const STAMP_PREFIX = '<!-- leg-resume '
+export const LEGACY_STAMP_PREFIX = '<!-- baton-resume '
+const STAMP_SUFFIX = ' -->'
+const STAMP_VERSION = 1
+// Baton's own directories dirty the tree on every write; a reader must not see
+// Baton's bookkeeping as the human's work moving on.
+const LEG_DIRS = /^(\.leg|\.baton|\.context-handoffs|\.dashclaw-local)[\\/]/
+const MAX_REASONS = 5
+
+// fresh and its idle twin are the only states a script should keep going on.
+export const EXIT = { fresh: 0, stale: 1, unstamped: 1, missing: 3 }
+
+function git(cwd, args) {
+  const r = spawnSync('git', args, { cwd, windowsHide: true, encoding: 'utf8', timeout: 5000, env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+  return r.status === 0 ? r.stdout.trim() : ''
+}
+
+// A count and a sorted hash, never the names: a shared board must not leak
+// what the human is working on, and a list would make the stamp unbounded.
+export function dirtyFingerprint(cwd) {
+  const lines = git(cwd, ['status', '--porcelain']).split('\n').filter(Boolean)
+    .map((l) => l.slice(3).replace(/^"|"$/g, ''))
+    .filter((f) => !LEG_DIRS.test(f))
+    .sort()
+  if (!lines.length) return { count: 0, hash: null }
+  return { count: lines.length, hash: createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 12) }
+}
+
+// What git says right now. Every field is null outside a repository, which
+// makes a pointer in a non-repo directory permanently undriftable rather than
+// permanently stale.
+export function gitState(cwd) {
+  const head = git(cwd, ['rev-parse', 'HEAD']) || null
+  const branch = head ? (git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']) || null) : null
+  return { head, short: head ? head.slice(0, 7) : null, branch, dirty: dirtyFingerprint(cwd) }
+}
+
+// How many commits landed between the stamp's HEAD and this one. null when the
+// two are not on one line of history (a rebase, a reset, a different clone).
+function commitsSince(cwd, then) {
+  if (!then) return null
+  const n = git(cwd, ['rev-list', '--count', `${then}..HEAD`])
+  return /^\d+$/.test(n) ? Number(n) : null
+}
+
+export function resumeFile(cwd) {
+  const leg = join(cwd, '.leg', 'RESUME.md')
+  const baton = join(cwd, '.baton', 'RESUME.md')
+  if (existsSync(leg)) return leg
+  if (existsSync(baton)) return baton
+  if (existsSync(join(cwd, '.baton')) && !existsSync(join(cwd, '.leg'))) return baton
+  return leg
+}
+export function perSessionFile(cwd, id) {
+  const leg = join(cwd, '.leg', `RESUME-${id}.md`)
+  const baton = join(cwd, '.baton', `RESUME-${id}.md`)
+  if (existsSync(leg)) return leg
+  if (existsSync(baton)) return baton
+  if (existsSync(join(cwd, '.baton')) && !existsSync(join(cwd, '.leg'))) return baton
+  return leg
+}
+
+// An agent started deeper in the tree still finds its checkout's pointer.
+export function findResume(startDir) {
+  // resolve(), not realPath(). The walk only needs an absolute path, and
+  // realPath() also rewrites the spelling: on a Windows host whose temp
+  // directory is reached by an 8.3 short name it returns C:\Users\runneradmin
+  // for a caller who said C:\Users\RUNNER~1, so the root handed back names a
+  // path the caller never used. Two spellings of one checkout are reconciled by
+  // canonPath() at the points that compare them, not by quietly renaming the
+  // directory the caller asked about.
+  let dir = resolve(startDir)
+  for (;;) {
+    const file = resumeFile(dir)
+    if (existsSync(file)) return { root: dir, file }
+    const up = dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+}
+
+// ---- the stamp ----
+
+export function renderStamp(stamp) { return STAMP_PREFIX + JSON.stringify(stamp) + STAMP_SUFFIX }
+
+export function readStamp(text) {
+  const line = String(text ?? '').split('\n', 1)[0].trim()
+  let pfx = null;
+  if (line.startsWith(STAMP_PREFIX)) pfx = STAMP_PREFIX;
+  else if (line.startsWith(LEGACY_STAMP_PREFIX)) pfx = LEGACY_STAMP_PREFIX;
+  if (!pfx || !line.endsWith(STAMP_SUFFIX)) return null;
+  try {
+    const stamp = JSON.parse(line.slice(pfx.length, -STAMP_SUFFIX.length))
+    return stamp && typeof stamp === 'object' ? stamp : null
+  } catch { return null }
+}
+
+// The text without its stamp: what a human reads and what `baton resume` prints.
+export function bodyOf(text) {
+  const s = String(text ?? '')
+  return readStamp(s) ? s.slice(s.indexOf('\n') + 1).replace(/^\n+/, '') : s
+}
+
+// Stamp a body, replacing any stamp it already carries so re-writes never stack.
+export function stampBody(stamp, body) { return `${renderStamp(stamp)}\n\n${bodyOf(body).replace(/^\n+/, '')}` }
+
+// The live terminals in one checkout, oldest first. This is the set a pointer
+// is written against: when it changes, the pointer is describing a different
+// room than the one the reader is standing in.
+export function liveIn(root, sessions = listSessions()) {
+  const key = canonPath(root)
+  return sessions.filter(isActive).filter((s) => { const r = workRoot(s); return r && canonPath(r) === key })
+}
+
+function makeStamp({ kind, session, root, why, bundle, live }) {
+  const g = gitState(root)
+  return {
+    v: STAMP_VERSION, kind,
+    session: session?.session_id ?? null,
+    agent: session?.agent ?? null,
+    account: session?.account ?? null,
+    head: g.head, branch: g.branch, dirty: g.dirty,
+    live: live.map((s) => ({ id: s.session_id, agent: s.agent })),
+    bundle: bundle?.id ?? null,
+    why: why ?? null,
+    written_at: new Date().toISOString(),
+  }
+}
+
+// ---- writing the pointer ----
+
+function note(session, others) {
+  const mine = `This file describes Leg terminal ${session.session_id} (${session.agent}); its own copy is .leg/RESUME-${session.session_id}.md.`
+  if (!others.length) return mine
+  const rest = others.map((o) => `${o.session_id} (${o.agent}), whose own hand-off would be .leg/RESUME-${o.session_id}.md`).join('; ')
+  return `${mine}\nAlso live in this checkout: ${rest}. RESUME.md describes only the terminal named above.`
+}
+
+// The hand-off pointer: one stamped body in .baton/RESUME-<session>.md (the
+// file the next agent's prompt names) and the same text in RESUME.md (the file
+// everyone opens). Returns the text written.
+export function writeHandoffPointer(session, body, { bundle = null, why = null } = {}) {
+  const root = workRoot(session)
+  if (!root) return null
+  const dir = existsSync(join(root, '.baton')) && !existsSync(join(root, '.leg')) ? join(root, '.baton') : join(root, '.leg')
+  mkdirSync(dir, { recursive: true })
+  const live = liveIn(root)
+  const others = live.filter((s) => s.session_id !== session.session_id)
+  const stamp = makeStamp({ kind: 'handoff', session, root, why, bundle, live: live.length ? live : [session] })
+  const text = stampBody(stamp, `${note(session, others)}\n\n${bodyOf(body)}`)
+  writeFileSync(perSessionFile(root, session.session_id), text)
+  try { writeFileSync(resumeFile(root), text) } catch { /* a read-only checkout still gets the per-session file */ }
+  return text
+}
+
+// The newest hand-off this checkout has seen, for the "nothing in flight"
+// pointer to name. Sessions outlive their terminals, so this survives the one
+// that wrote the hand-off ending.
+export function lastHandoffIn(root, sessions = listSessions()) {
+  const key = canonPath(root)
+  const when = (s) => s.handoff?.at ?? s.bundle?.updated_at ?? s.ended_at ?? s.updated_at ?? ''
+  const rows = sessions
+    .filter((s) => { const r = workRoot(s); return r && canonPath(r) === key })
+    .filter((s) => s.lineage?.to || s.bundle)
+    .sort((a, b) => (when(a) < when(b) ? 1 : -1))
+  const s = rows[0]
+  if (!s) return null
+  const file = perSessionFile(root, s.session_id)
+  return {
+    session_id: s.session_id, agent: s.agent,
+    from: s.lineage?.from ?? s.agent, to: s.lineage?.to ?? null,
+    at: when(s) || null, bundle: s.bundle?.id ?? null,
+    // a checkpoint bundle is not a hand-off, and only a hand-off leaves a
+    // per-session resume file; naming one that was never written is the same
+    // class of lie this module exists to stop
+    handed_off: Boolean(s.lineage?.to), file: existsSync(file) ? (file.includes('.leg') ? `.leg/RESUME-${s.session_id}.md` : `.baton/RESUME-${s.session_id}.md`) : null,
+  }
+}
+
+function idleBody(last, live) {
+  const lines = ['# Baton: nothing in flight', '']
+  lines.push(live.length
+    ? `No hand-off is waiting to be picked up here. Still live in this checkout: ${live.map((s) => `${s.session_id} (${s.agent})`).join(', ')}.`
+    : 'No Baton terminal is live in this checkout.')
+  lines.push('')
+  if (last) {
+    const at = last.at ? String(last.at).slice(0, 16).replace('T', ' ') : 'an unrecorded time'
+    const bundle = last.bundle ? ` (bundle ${last.bundle})` : ''
+    lines.push(last.handed_off
+      ? `The last hand-off here was ${last.from ?? 'an agent'} -> ${last.to} on ${at}${bundle}, in terminal ${last.session_id}.`
+      : `The last bundle saved here was a checkpoint from terminal ${last.session_id} (${last.agent ?? 'an agent'}) on ${at}${bundle}; no agent handed off.`)
+    if (last.file) lines.push(`Its full text is still in ${last.file}. It describes that moment, not this one.`)
+  } else {
+    lines.push('No hand-off has been recorded in this checkout.')
+  }
+  lines.push('', 'Before you trust any resume file here, run `leg resume --check`: it recomputes freshness from git at read time and exits non-zero when the file no longer matches the repository.')
+  lines.push('')
+  return lines.join('\n')
+}
+
+// The "nothing in flight" pointer. Always writes; the callers that must not
+// create a file in a checkout Baton never handed off in check first.
+export function writeIdlePointer(root, { sessions = listSessions() } = {}) {
+  if (!root) return null
+  const dir = existsSync(join(root, '.baton')) && !existsSync(join(root, '.leg')) ? join(root, '.baton') : join(root, '.leg')
+  mkdirSync(dir, { recursive: true })
+  const live = liveIn(root, sessions)
+  const last = lastHandoffIn(root, sessions)
+  const stamp = makeStamp({ kind: 'idle', session: null, root, why: 'session ended', bundle: last?.bundle ? { id: last.bundle } : null, live })
+  const text = stampBody(stamp, idleBody(last, live))
+  writeFileSync(resumeFile(root), text)
+  return text
+}
+
+// A session ending must not leave its hand-off sitting there looking live.
+// Only ever rewrites a pointer that already exists: Baton owns RESUME.md where
+// it wrote one, and creates none in a checkout it never handed off in.
+export function endSessionPointer(session) {
+  const root = workRoot(session)
+  if (!root || !existsSync(resumeFile(root))) return null
+  return writeIdlePointer(root)
+}
+
+// Board start: every checkout Baton wrote a pointer in gets it recomputed, so a
+// terminal that crashed instead of exiting cannot leave a live-looking hand-off
+// behind. A checkout whose terminal really is live keeps its hand-off text.
+// Returns the roots rewritten.
+export function refreshPointers() {
+  // a crashed terminal still reads `running` until its dead pid is noticed
+  const sessions = reapLost()
+  const roots = new Map()
+  for (const s of sessions) {
+    const r = workRoot(s)
+    if (r && existsSync(resumeFile(r))) roots.set(canonPath(r), r)
+  }
+  const touched = []
+  for (const root of roots.values()) {
+    const v = resumeVerdict(root, { sessions })
+    if (v.state === 'fresh') continue
+    // The terminal that wrote a hand-off owns it while it is still running: its
+    // text is the live description, and "the repo moved on" is for `baton resume
+    // --check` to report, not for the board to overwrite. Anything else — a
+    // hand-off from a terminal that is gone, a file no Baton stamped — is
+    // replaced even when some OTHER terminal happens to be live in the
+    // checkout, which is the case that left three day old text sitting there.
+    if (v.session?.active) continue
+    // the raw root, the way the session recorded it: this list is deduped by
+    // canonPath() above and then only logged, so normalising the spelling here
+    // renamed the checkout in the log line for no gain
+    try { writeIdlePointer(root, { sessions }); touched.push(root) } catch { /* a checkout that moved or went read-only */ }
+  }
+  return touched
+}
+
+// ---- reading the pointer: the verdict, from git, now ----
+
+function describe(list) { return list.map((s) => `${s.id ?? s.session_id} (${s.agent})`).join(', ') }
+
+// Recomputed on every read. Nothing here trusts the file about the present:
+// the stamp says what was true when it was written, git says what is true now,
+// and the verdict is the difference.
+export function resumeVerdict(cwd, { sessions = listSessions() } = {}) {
+  const found = findResume(cwd)
+  if (!found) {
+    return { state: 'missing', exit_code: EXIT.missing, root: null, file: null, kind: null, stamp: null, reasons: ['there is no .baton/RESUME.md in this checkout'], summary: 'no resume pointer in this checkout', head: null, dirty: null, live: null, session: null, written_at: null, age_ms: null }
+  }
+  const { root, file } = found
+  let text = ''
+  try { text = readFileSync(file, 'utf8') } catch { /* raced a rewrite */ }
+  const stamp = readStamp(text)
+  if (!stamp) {
+    return { state: 'unstamped', exit_code: EXIT.unstamped, root, file, kind: null, stamp: null, reasons: ['this file carries no Baton stamp, so its freshness cannot be checked against git'], summary: 'cannot be checked: no Baton stamp', head: null, dirty: null, live: null, session: null, written_at: null, age_ms: null }
+  }
+
+  const now = gitState(root)
+  const headMoved = Boolean(stamp.head) && Boolean(now.head) && stamp.head !== now.head
+  const since = headMoved ? commitsSince(root, stamp.head) : 0
+  const thenDirty = stamp.dirty ?? { count: 0, hash: null }
+  const dirtyChanged = (thenDirty.hash ?? null) !== (now.dirty.hash ?? null)
+  const live = liveIn(root, sessions)
+  const wasLive = Array.isArray(stamp.live) ? stamp.live : []
+  const gone = wasLive.filter((w) => !live.some((s) => s.session_id === w.id))
+  const started = live.filter((s) => !wasLive.some((w) => w.id === s.session_id))
+  const named = stamp.session ? sessions.find((s) => s.session_id === stamp.session) ?? null : null
+  const written = stamp.written_at ? Date.parse(stamp.written_at) : NaN
+
+  const reasons = []
+  // A hand-off describes a moment in the repository; a commit or an edit since
+  // then means the description no longer matches what the reader will see.
+  if (stamp.kind === 'handoff') {
+    if (headMoved) reasons.push(since === null ? 'HEAD is a different commit than this was written at' : `${since} commit${since === 1 ? '' : 's'} landed since this was written`)
+    if (dirtyChanged) reasons.push(`the working tree changed since this was written (${thenDirty.count} uncommitted file${thenDirty.count === 1 ? '' : 's'} then, ${now.dirty.count} now)`)
+  }
+  // Both kinds claim which terminals are live. That claim is falsifiable now.
+  if (gone.length) reasons.push(`terminal ${describe(gone)} is no longer live`)
+  if (started.length) reasons.push(`terminal ${describe(started)} started after this was written`)
+
+  const state = reasons.length ? 'stale' : 'fresh'
+  const summary = state === 'fresh'
+    ? `current${Number.isFinite(written) ? ` (written ${ago(Date.now() - written)})` : ''}`
+    : reasons.slice(0, MAX_REASONS).join('; ')
+  return {
+    state, exit_code: EXIT[state], root, file,
+    kind: stamp.kind ?? null, stamp,
+    reasons: reasons.slice(0, MAX_REASONS), summary,
+    head: { then: stamp.head ?? null, now: now.head, moved: headMoved, commits_since: since, branch: now.branch },
+    dirty: { then: thenDirty.count, now: now.dirty.count, changed: dirtyChanged },
+    live: live.map((s) => ({ id: s.session_id, agent: s.agent, status: s.status })),
+    session: stamp.session ? { id: stamp.session, status: named?.status ?? null, active: Boolean(named && isActive(named)) } : null,
+    written_at: stamp.written_at ?? null,
+    age_ms: Number.isFinite(written) ? Date.now() - written : null,
+  }
+}
+
+export function ago(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 'just now'
+  const m = Math.round(ms / 60000)
+  if (m < 1) return 'less than a minute ago'
+  if (m < 60) return `${m} minute${m === 1 ? '' : 's'} ago`
+  const h = Math.round(m / 60)
+  if (h < 48) return `${h} hour${h === 1 ? '' : 's'} ago`
+  return `${Math.round(h / 24)} days ago`
+}
+
+// What the board may see: the verdict without the local paths. A guest never
+// reaches the drawer, but a screenshot of it travels further than the machine.
+export function verdictForBoard(v) {
+  if (!v) return null
+  const { root, file, stamp, ...rest } = v
+  void root; void file; void stamp
+  return { ...rest, bundle: stamp?.bundle ?? null, why: stamp?.why ?? null }
+}