@ucsandman/legcli 0.10.0 → 0.11.0

package/src/adapters/custom.mjs

@@ -0,0 +1,271 @@
+// custom adapters — any coding-agent CLI becomes a Leg adapter through a JSON
+// spec in $LEG_HOME/adapters/<name>.json, with no code in this package.
+//
+// This is what makes the chain open-ended: claude, codex, agy and grok ship
+// with taps and a probe, and anything else (Muse, Amp, aider, a house script)
+// joins as "argv in, JSON out". A custom adapter is a CARD adapter: it runs
+// headless in a worktree and hands off like any other leg. It is not an
+// interactive `leg <agent>` terminal, because that needs a usage tap and a
+// wall signal that only the four supervised CLIs expose.
+//
+// Spec:
+//   {
+//     "name": "muse",
+//     "bin": "muse",                        // argv[0]; never a shell string
+//     "stdin": "ignore",                    // "pipe" sends the prompt on stdin
+//     "args": ["run", "--json",
+//              ["--dir", "{{cwd}}"],        // a group is dropped when a
+//              ["--model", "{{model}}"],    //   placeholder inside it is unset
+//              "{{prompt}}"],
+//     "modes": { "default": "auto", "allowed": ["auto", "readonly"] },
+//     "forbiddenFlags": ["--yolo"],
+//     "result": { "format": "json", "sessionId": "session_id",
+//                 "message": "result", "stopReason": "stop_reason" }
+//   }
+//
+// Placeholders: {{prompt}} {{promptFile}} {{cwd}} {{mode}} {{model}}
+// {{resume}} {{maxTurns}} {{runDir}}. A bare string is always kept, so put
+// anything optional in a group.
+//
+// result.format: "json" (first parseable object in stdout), "jsonl" (the last
+// line that carries the message field) or "text" (no parsing; the leg is then
+// judged by its .leg/DONE marker and its diff, as every adapter is when
+// parseResult returns null). sessionId/message/stopReason are dotted paths.
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { home } from '../store.mjs'
+import { sanitizeEnv } from '../env.mjs'
+import { assertAllowed } from './common.mjs'
+
+export const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,29}$/
+export const PLACEHOLDERS = ['prompt', 'promptFile', 'cwd', 'mode', 'model', 'resume', 'maxTurns', 'runDir']
+export const FORMATS = ['json', 'jsonl', 'text']
+
+// Never allowed in a spec, whoever wrote it: these are the flags that turn a
+// supervised agent into an unsupervised one, and Leg's whole permission story
+// is that no adapter passes them. The same list the built-ins are tested for.
+export const NEVER_ALLOWED = [
+  '--dangerously-skip-permissions', '--allow-dangerously-skip-permissions', // not allowed
+  '--dangerously-bypass-approvals-and-sandbox', '--dangerous-mode', // not allowed
+  '--yolo', '--always-approve', '--full-auto', '--approve-for-me', // not allowed
+  'bypassPermissions', 'danger-full-access', // not allowed
+]
+
+export class SpecError extends Error {
+  constructor(msg) { super(msg); this.name = 'SpecError' }
+}
+
+export function adaptersDir() { return join(home(), 'adapters') }
+export function specPath(name) { return join(adaptersDir(), `${name}.json`) }
+
+function str(v) { return typeof v === 'string' ? v : null }
+
+// Throws SpecError with a sentence naming the field. Returns the normalized spec.
+export function validateSpec(raw, { reserved = [] } = {}) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new SpecError('a spec is a JSON object')
+  const name = str(raw.name)
+  if (!name || !NAME_RE.test(name)) throw new SpecError(`name "${raw.name ?? ''}": lowercase letters, digits, dash and underscore, up to 30 characters`)
+  if (reserved.includes(name)) throw new SpecError(`"${name}" is a built-in adapter; choose another name`)
+  const bin = str(raw.bin)
+  if (!bin) throw new SpecError(`${name}: "bin" must be the executable to run (argv[0]), not a shell command line`)
+  if (/[<>|&;]/.test(bin)) throw new SpecError(`${name}: "bin" is spawned directly, never through a shell, so it cannot contain < > | & or ;`)
+  const stdin = raw.stdin ?? 'ignore'
+  if (!['pipe', 'ignore'].includes(stdin)) throw new SpecError(`${name}: "stdin" is "pipe" or "ignore"`)
+  if (!Array.isArray(raw.args)) throw new SpecError(`${name}: "args" must be an array of strings and groups`)
+
+  const flat = []
+  const args = raw.args.map((entry, i) => {
+    if (typeof entry === 'string') { flat.push(entry); return entry }
+    if (Array.isArray(entry) && entry.every((x) => typeof x === 'string')) { flat.push(...entry); return [...entry] }
+    throw new SpecError(`${name}: args[${i}] must be a string or an array of strings`)
+  })
+  for (const piece of flat) {
+    for (const [, key] of piece.matchAll(/\{\{\s*([a-zA-Z]+)\s*\}\}/g)) {
+      if (!PLACEHOLDERS.includes(key)) throw new SpecError(`${name}: unknown placeholder {{${key}}} (known: ${PLACEHOLDERS.join(', ')})`)
+    }
+    const banned = NEVER_ALLOWED.find((f) => piece === f || piece.startsWith(`${f}=`) || piece.endsWith(`=${f}`))
+    if (banned) throw new SpecError(`${name}: args carry ${banned}, which no Leg adapter may pass`)
+  }
+  const usesPrompt = flat.some((p) => p.includes('{{prompt}}') || p.includes('{{promptFile}}'))
+  if (stdin !== 'pipe' && !usesPrompt) throw new SpecError(`${name}: nothing carries the prompt — put {{prompt}} or {{promptFile}} in args, or set "stdin": "pipe"`)
+
+  const modes = raw.modes ?? {}
+  const allowed = Array.isArray(modes.allowed) && modes.allowed.length ? modes.allowed.map(String) : ['default']
+  const def = str(modes.default) ?? allowed[0]
+  if (!allowed.includes(def)) throw new SpecError(`${name}: modes.default "${def}" is not in modes.allowed (${allowed.join(', ')})`)
+  for (const m of allowed) if (NEVER_ALLOWED.includes(m)) throw new SpecError(`${name}: mode "${m}" is never allowed`)
+
+  const forbidden = Array.isArray(raw.forbiddenFlags) ? raw.forbiddenFlags.map(String) : []
+  const result = raw.result ?? {}
+  const format = str(result.format) ?? 'json'
+  if (!FORMATS.includes(format)) throw new SpecError(`${name}: result.format is one of ${FORMATS.join(', ')}`)
+
+  return {
+    name,
+    bin,
+    stdin,
+    args,
+    modes: { default: def, allowed },
+    // the never-allowed list is refused on top of whatever the spec adds
+    forbiddenFlags: [...new Set([...forbidden, ...NEVER_ALLOWED])],
+    result: {
+      format,
+      sessionId: str(result.sessionId) ?? 'session_id',
+      message: str(result.message) ?? 'result',
+      stopReason: str(result.stopReason) ?? 'stop_reason',
+    },
+  }
+}
+
+function dig(obj, path) {
+  let cur = obj
+  for (const key of String(path).split('.')) {
+    if (cur === null || typeof cur !== 'object') return null
+    cur = cur[key]
+  }
+  return cur ?? null
+}
+
+function fill(piece, values) {
+  return piece.replace(/\{\{\s*([a-zA-Z]+)\s*\}\}/g, (_, key) => (values[key] === undefined || values[key] === null ? '' : String(values[key])))
+}
+
+function hasUnset(piece, values) {
+  for (const [, key] of piece.matchAll(/\{\{\s*([a-zA-Z]+)\s*\}\}/g)) {
+    const v = values[key]
+    if (v === undefined || v === null || v === '') return true
+  }
+  return false
+}
+
+// spec → the adapter object every other module expects (see common.mjs).
+export function makeAdapter(spec) {
+  const adapter = {
+    name: spec.name,
+    stdin: spec.stdin,
+    modes: spec.modes,
+    forbiddenFlags: spec.forbiddenFlags,
+    custom: true,
+    spec,
+    resolve() {
+      const override = process.env[`LEG_${spec.name.toUpperCase().replace(/-/g, '_')}_BIN`]
+      const bin = override || spec.bin
+      return { bin, viaNode: /\.(mjs|cjs|js)$/.test(bin), entry: null }
+    },
+    argv(opts = {}) {
+      const mode = assertAllowed(adapter, opts)
+      const { bin, viaNode } = adapter.resolve()
+      const values = {
+        prompt: opts.prompt ?? '',
+        promptFile: opts.promptFile ?? null,
+        cwd: opts.cwd ?? process.cwd(),
+        mode,
+        model: opts.model ?? null,
+        resume: opts.resume ?? null,
+        maxTurns: opts.maxTurns ?? null,
+        runDir: opts.runDir ?? null,
+      }
+      const args = []
+      for (const entry of spec.args) {
+        if (typeof entry === 'string') { args.push(fill(entry, values)); continue }
+        // a group survives only when every placeholder in it resolved
+        if (entry.some((piece) => hasUnset(piece, values))) continue
+        for (const piece of entry) args.push(fill(piece, values))
+      }
+      return viaNode ? { bin: process.execPath, args: [bin, ...args] } : { bin, args }
+    },
+    env(base) { return sanitizeEnv(base) },
+    parseResult(text) {
+      const s = String(text)
+      if (spec.result.format === 'text') return null
+      const shape = (j) => ({
+        session_id: dig(j, spec.result.sessionId),
+        last_message: typeof dig(j, spec.result.message) === 'string' ? dig(j, spec.result.message) : null,
+        stop_reason: dig(j, spec.result.stopReason),
+        raw: j,
+      })
+      if (spec.result.format === 'jsonl') {
+        const objs = []
+        for (const line of s.split('\n')) {
+          const t = line.trim()
+          if (!t.startsWith('{')) continue
+          try { objs.push(JSON.parse(t)) } catch { continue }
+        }
+        if (!objs.length) return null
+        // the last line that actually carries a message, else the last line
+        const withMsg = objs.filter((j) => typeof dig(j, spec.result.message) === 'string')
+        return shape(withMsg.length ? withMsg[withMsg.length - 1] : objs[objs.length - 1])
+      }
+      for (let i = s.indexOf('{'); i !== -1; i = s.indexOf('{', i + 1)) {
+        try {
+          const j = JSON.parse(s.slice(i))
+          if (j && typeof j === 'object') return shape(j)
+        } catch { continue }
+      }
+      return null
+    },
+  }
+  return adapter
+}
+
+// names() is on the board's hot path — /api/health asks every adapter where
+// its binary is, which called this once for the list and once per custom
+// adapter — so the parsed result is cached against the spec directory's mtime
+// and a one-second floor. A spec added or removed changes the directory mtime
+// and is picked up at once; a spec edited in place lands within the second.
+// Without this, one board poll was a readdir plus a readFile and a JSON.parse
+// per spec, on the same event loop the terminals lane is pushed from.
+// The key is the directory listing itself, not its mtime: one readdir is a
+// single cheap syscall, and a directory's mtime is too coarse on Windows to
+// notice a spec added in the same tick as the last read. So a spec appearing
+// or disappearing is seen at once, and only a spec edited in place waits out
+// the one-second floor.
+const SPEC_TTL_MS = 1000
+let specCache = { key: null, at: 0, specs: null }
+
+export function clearSpecCache() { specCache = { key: null, at: 0, specs: null } }
+
+// Every spec on disk. A broken file is reported, never thrown, so one bad spec
+// cannot stop the board, the scheduler or `leg card add`.
+// → [{ name, spec, adapter, file, error }]
+export function listSpecs({ reserved = [] } = {}) {
+  const dir = adaptersDir()
+  if (!existsSync(dir)) return []
+  const files = readdirSync(dir).sort().filter((f) => f.endsWith('.json'))
+  const key = `${dir}|${reserved.join(',')}|${files.join(',')}`
+  if (specCache.specs && specCache.key === key && Date.now() - specCache.at < SPEC_TTL_MS) return specCache.specs
+  const out = []
+  for (const file of files) {
+    const full = join(dir, file)
+    const stem = file.slice(0, -5)
+    try {
+      const raw = JSON.parse(readFileSync(full, 'utf8'))
+      if (raw && typeof raw === 'object' && raw.name === undefined) raw.name = stem
+      const spec = validateSpec(raw, { reserved })
+      if (spec.name !== stem) throw new SpecError(`name "${spec.name}" does not match the file name ${file}`)
+      out.push({ name: spec.name, spec, adapter: makeAdapter(spec), file: full, error: null })
+    } catch (err) {
+      out.push({ name: stem, spec: null, adapter: null, file: full, error: err.message })
+    }
+  }
+  specCache = { key, at: Date.now(), specs: out }
+  return out
+}
+
+export function loadSpec(name, { reserved = [] } = {}) {
+  const f = specPath(name)
+  if (!existsSync(f)) return null
+  const raw = JSON.parse(readFileSync(f, 'utf8'))
+  if (raw && typeof raw === 'object' && raw.name === undefined) raw.name = name
+  return validateSpec(raw, { reserved })
+}
+
+export const TEMPLATE = {
+  name: 'my-agent',
+  bin: 'my-agent',
+  stdin: 'ignore',
+  args: ['--json', ['--dir', '{{cwd}}'], ['--model', '{{model}}'], ['--resume', '{{resume}}'], '{{prompt}}'],
+  modes: { default: 'default', allowed: ['default'] },
+  forbiddenFlags: [],
+  result: { format: 'json', sessionId: 'session_id', message: 'result', stopReason: 'stop_reason' },
+}

package/src/adapters/grok.mjs

@@ -1,5 +1,15 @@
-// grok adapter - Grok CLI headless (`grok -p <prompt> --output-format json`).
-// Registered in index.mjs alongside claude, codex, and agy.
+// grok adapter — Grok CLI headless (`grok -p <prompt> --output-format json`).
+// Facts and sources: docs/cli-contracts.md § grok. Every flag below was read
+// from `grok --help` on grok 1.0.34 (3736acbc8658) on 2026-09-17:
+//   -p, --single <PROMPT>        single-turn prompt, prints the response and exits
+//   --prompt-file <PATH>         the same prompt from a file (no argv length limit)
+//   --output-format <plain|json|streaming-json|streaming-messages-json>
+//   --permission-mode <default|acceptEdits|auto|dontAsk|plan>, and one more
+//     that Leg never passes and refuses in a chain entry (see modes.allowed)
+//   --cwd <CWD>, -m <MODEL>, -r <SESSION_ID_OR_TITLE>
+// --cwd is passed explicitly rather than relying on the spawn's cwd: grok can
+// run against a shared leader process (~/.grok/leader.sock), and a leg must
+// edit its own worktree, never whatever directory the leader was started in.
 import { join } from 'node:path'
 import { homedir } from 'node:os'
 import { sanitizeEnv } from '../env.mjs'
@@ -7,9 +17,10 @@ import { assertAllowed, firstExisting } from './common.mjs'
 
 const adapter = {
   name: 'grok',
-  stdin: 'ignore',
+  stdin: 'ignore', // the prompt travels by --prompt-file or argv, never stdin
   modes: {
     default: 'acceptEdits',
+    // grok 1.0.34 --permission-mode choices; the bypass mode is never allowed.
     allowed: ['default', 'acceptEdits', 'auto', 'dontAsk', 'plan'],
   },
   forbiddenFlags: ['--always-approve', 'bypassPermissions', '--permission-mode=bypassPermissions'],
@@ -22,24 +33,54 @@ const adapter = {
   argv(opts = {}) {
     const mode = assertAllowed(adapter, opts)
     const { bin, viaNode } = adapter.resolve()
-    const args = ['-p', opts.prompt ?? '', '--output-format', 'json', '--permission-mode', mode]
+    const cwd = opts.cwd ?? process.cwd()
+    // A hand-off prompt carries the whole bundle summary and can run to
+    // thousands of characters; Windows caps one command line at ~32k, so the
+    // file form is used whenever the runner has written one.
+    const args = opts.promptFile
+      ? ['--prompt-file', opts.promptFile]
+      : ['-p', opts.prompt ?? '']
+    args.push('--output-format', 'json', '--permission-mode', mode, '--cwd', cwd)
+    if (opts.maxTurns) args.push('--max-turns', String(opts.maxTurns))
     if (opts.model) args.push('-m', opts.model)
     if (opts.resume) args.push('-r', opts.resume)
     return viaNode ? { bin: process.execPath, args: [bin, ...args] } : { bin, args }
   },
   env(base) { return sanitizeEnv(base) },
+  // grok's headless writer emits the Claude Code result envelope. The field
+  // names were read out of the shipped grok.exe on 2026-09-17 ("type":"result",
+  // subtype, is_error, session_id, "result", num_turns, stop_reason, total_cost)
+  // and the error envelope was observed live the same day:
+  //   {"type":"error","message":"Internal error: { \"message\": \"API error
+  //    (status 402 Payment Required): Grok Build usage balance exhausted\" }"}
+  // The scan starts at each `{` because --output-format json still lets a
+  // plugin or a warning print a line before the envelope.
   parseResult(text) {
     const s = String(text)
     for (let i = s.indexOf('{'); i !== -1; i = s.indexOf('{', i + 1)) {
-      try {
-        const j = JSON.parse(s.slice(i))
+      let j
+      try { j = JSON.parse(s.slice(i)) } catch { continue }
+      if (!j || typeof j !== 'object') continue
+      if (j.type === 'error') {
         return {
-          session_id: j.session_id ?? j.sessionId ?? null,
-          last_message: typeof j.response === 'string' ? j.response : (typeof j.result === 'string' ? j.result : (typeof j.text === 'string' ? j.text : null)),
-          stop_reason: j.stop_reason ?? j.stopReason ?? null,
+          session_id: j.session_id ?? null,
+          last_message: typeof j.message === 'string' ? j.message : null,
+          stop_reason: 'error',
+          subtype: null,
+          is_error: true,
+          num_turns: null,
           raw: j,
         }
-      } catch { continue }
+      }
+      return {
+        session_id: j.session_id ?? j.sessionId ?? null,
+        last_message: typeof j.result === 'string' ? j.result : (typeof j.response === 'string' ? j.response : null),
+        stop_reason: j.stop_reason ?? j.stopReason ?? null,
+        subtype: j.subtype ?? null,
+        is_error: j.is_error ?? null,
+        num_turns: j.num_turns ?? null,
+        raw: j,
+      }
     }
     return null
   },

package/src/adapters/index.mjs

@@ -1,9 +1,19 @@
 // Adapter registry. Adapters are loaded lazily so a typo fails with a named
 // error before anything is spawned. Every real CLI here was probed live
 // through the runner in phase 3 (fixtures/live/<name>/, docs/cli-contracts.md).
-// grok.mjs exists but is NOT registered: the build machine had no grok login
-// (the probe printed a device-code prompt and exited "Cancelled"). Register it
-// after `grok` is logged in and scripts/probe.mjs --adapter grok passes.
+// grok joined on 2026-09-17: its flags were read from `grok --help` on 1.0.34
+// and its headless envelope out of the shipped binary, and the probe reached
+// the account (a 402 "usage balance exhausted", classified `limit`). The
+// success path of a grok leg is still unprobed — that needs balance on the
+// account — so a grok card falls back to the DONE marker and the diff, which
+// is what every adapter does when parseResult comes back null.
+//
+// Anything else is a custom adapter: a JSON spec in $LEG_HOME/adapters/*.json
+// (src/adapters/custom.mjs, `leg adapter add`). Built-in names always win, and
+// the spec directory is re-read on every call so a spec added while the board
+// is up shows in the New card form without a restart.
+import { listSpecs } from './custom.mjs'
+
 const REGISTRY = {
   fake: { path: './fake.mjs' },
   'fake-claude': { path: './fake.mjs', fake: ['fake-claude', 'pipe'] },
@@ -13,15 +23,32 @@ const REGISTRY = {
   claude: { path: './claude.mjs' },
   codex: { path: './codex.mjs' },
   agy: { path: './agy.mjs' },
+  grok: { path: './grok.mjs' },
 }
 
-export function names() { return Object.keys(REGISTRY) }
+export const BUILTIN_NAMES = Object.keys(REGISTRY)
+
+// Every spec on disk, including the broken ones (each carries its `error`).
+export function customSpecs() { return listSpecs({ reserved: BUILTIN_NAMES }) }
+
+// Only the specs that loaded. A broken file is not an adapter; `leg adapter
+// list` is where its error is shown, so a typo is visible instead of silent.
+export function customNames() { return customSpecs().filter((s) => s.adapter).map((s) => s.name) }
+
+export function names() { return [...BUILTIN_NAMES, ...customNames()] }
 
 export function isFake(name) { return Boolean(REGISTRY[name]?.fake) || name === 'fake' }
 
+export function isCustom(name) { return !REGISTRY[name] && customNames().includes(name) }
+
 export async function get(name) {
   const entry = REGISTRY[name]
-  if (!entry) throw new Error(`unknown adapter: ${name}`)
-  const mod = await import(entry.path)
-  return entry.fake ? mod.makeFake(...entry.fake) : mod.default
+  if (entry) {
+    const mod = await import(entry.path)
+    return entry.fake ? mod.makeFake(...entry.fake) : mod.default
+  }
+  const hit = customSpecs().find((s) => s.name === name)
+  if (hit?.adapter) return hit.adapter
+  if (hit?.error) throw new Error(`adapter ${name} is on disk but its spec does not load: ${hit.error}`)
+  throw new Error(`unknown adapter: ${name}`)
 }

package/src/attach.mjs

@@ -263,7 +263,10 @@ export async function spawnSpec(agent, { account, args, sessionId, prompt, cwd,
 }
 
 // ---- one agent leg ----
-// Returns { reason: 'exit'|'limit'|'handoff', code }
+// Returns { reason: 'exit'|'limit'|'handoff', code, target } — `target` is the
+// destination a human picked on the board ("Hand off now to codex"), carried
+// out to the loop below, which is what chooses the next leg.
+
 async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApprove = resolveAutoApprove() }) {
   const sid = session.session_id
   refreshAccount(agent, account)
@@ -474,8 +477,12 @@ async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApp
       // record can carry both; End (stop entirely) is the stronger, latest intent
       if (ctl?.end) { if (ctl.by) appendEvent(sid, { type: 'status', by: ctl.by, summary: `end requested from the board by ${ctl.by}` }); clearInterval(timer); killTree(child.pid); restoreTerminal(); stop({ reason: 'exit', code: null, ended: true }); return }
       if (ctl?.handoff) {
-        updateSession(sid, { status: 'handing_off', handoff: { reason: `requested from the board${ctl.by ? ` by ${ctl.by}` : ''}`, at: new Date().toISOString(), by: ctl.by ?? null } }, { event: { type: 'handoff_requested', by: ctl.by ?? null, summary: `hand off requested from the board${ctl.by ? ` by ${ctl.by}` : ''}` } })
-        clearInterval(timer); killTree(child.pid); restoreTerminal(); stop({ reason: 'handoff', code: null }); return
+        const picked = ctl.target && typeof ctl.target === 'object' && ctl.target.agent
+          ? { agent: String(ctl.target.agent), account: String(ctl.target.account ?? 'default') }
+          : null
+        const toWhom = picked ? ` to ${picked.agent}${picked.account !== 'default' ? '/' + picked.account : ''}` : ''
+        updateSession(sid, { status: 'handing_off', handoff: { reason: `requested from the board${ctl.by ? ` by ${ctl.by}` : ''}`, at: new Date().toISOString(), by: ctl.by ?? null, requested_to: picked } }, { event: { type: 'handoff_requested', by: ctl.by ?? null, summary: `hand off${toWhom} requested from the board${ctl.by ? ` by ${ctl.by}` : ''}` } })
+        clearInterval(timer); killTree(child.pid); restoreTerminal(); stop({ reason: 'handoff', code: null, target: picked }); return
       }
       // a stale warning patch can overwrite status:'limit' from the hook, but the
       // limit OBJECT survives the clobber — hand off on either signal
@@ -529,14 +536,14 @@ function messagesFor(agent, s) {
 // an order save is consumed here, or the editor sees handing_off and refuses.
 // No eligible choice leaves the session unclaimed so all-out waiting can keep
 // accepting order edits.
-export function claimHandoffChoice({ sid, agent, account, installed, bundle = null, reason = 'limit', nowS = Math.floor(Date.now() / 1000), exclude = [] }) {
+export function claimHandoffChoice({ sid, agent, account, installed, bundle = null, reason = 'limit', nowS = Math.floor(Date.now() / 1000), exclude = [], prefer = null }) {
   let choice = { next: null, out: [] }
   let claimed = false
   const session = updateSession(sid, (current) => {
     const accounts = readAccounts()
     const order = normalizeHandoffOrder(current.handoff_order)
-    choice = chooseNext({ agent, account, accounts, installed, order, nowS, exclude })
-    if (!choice.next && isAvailable(readUsage(agent, account), nowS) && !exclude.some((x) => x.agent === agent && x.account === account)) choice = { next: { agent, account }, out: [] }
+    choice = chooseNext({ agent, account, accounts, installed, order, nowS, exclude, prefer })
+    if (!choice.next && isAvailable(readUsage(agent, account), nowS) && !exclude.some((x) => x.agent === agent && x.account === account)) choice = { next: { agent, account }, out: [], preferred_taken: false }
     if (!choice.next) return {}
     claimed = true
     return {
@@ -548,6 +555,10 @@ export function claimHandoffChoice({ sid, agent, account, installed, bundle = nu
         to: choice.next,
         bundle_id: bundle?.id ?? null,
         reason: reason === 'limit' ? 'usage limit' : 'requested',
+        // what was asked for, beside what was chosen: when a picked
+        // destination walled between the click and the hand-off, the card
+        // must say so rather than look like the pick was ignored
+        requested_to: prefer ?? null,
         at: new Date().toISOString(),
       },
     }
@@ -669,7 +680,9 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
     const notesFile = join(workRoot(cur) ?? cur.cwd, '.leg', `session-${sid}.md`)
     // destinations the strict harness policy refused during this hand-off
     const excluded = []
-    let claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason, exclude: excluded })
+    // the destination a human picked on the board, if they picked one
+    const prefer = r.target ?? null
+    let claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason, exclude: excluded, prefer })
     let choice = claim.choice
     let cancelled = false
     let blocked = false
@@ -690,7 +703,7 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
       updateSession(sid, { status: 'waiting', all_out: all, waiting: first ? { agent: first.agent, account: first.account, resets_at: first.resets_at, since: new Date().toISOString() } : null }, { event: { type: 'all_out', summary: `every option is out; waiting for ${label} at ${first ? fmtReset(first.resets_at) : 'unknown'}` } })
       const r2 = await waitInTerminal({ sid, label, resetsAt: first?.resets_at ?? null })
       if (r2 === 'cancelled') { cancelled = true; break }
-      claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason, exclude: excluded })
+      claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason, exclude: excluded, prefer })
       choice = claim.choice
     }
     if (cancelled) {
@@ -706,7 +719,7 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
       if (prepared.proceed) break
       excluded.push(choice.next)
       say(`${choice.next.agent} refused by the strict harness policy: ${prepared.reason ?? prepared.state}`)
-      claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason, exclude: excluded })
+      claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason, exclude: excluded, prefer })
       choice = claim.choice
       if (!choice.next) blocked = true
     }
@@ -717,6 +730,19 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
       break
     }
     const next = choice.next
+    // A pick that could not be taken is never silent: between the click and
+    // this moment that account can wall, or the strict harness policy can
+    // refuse it, and a terminal that quietly went somewhere else is the kind
+    // of surprise this board exists to remove.
+    if (prefer && !choice.preferred_taken) {
+      const asked = `${prefer.agent}${prefer.account !== 'default' ? '/' + prefer.account : ''}`
+      const got = `${next.agent}${next.account !== 'default' ? '/' + next.account : ''}`
+      const why = excluded.some((x) => x.agent === prefer.agent && x.account === prefer.account)
+        ? 'the strict harness policy refused it'
+        : `it is at its limit until ${fmtReset(readUsage(prefer.agent, prefer.account).limited_until)}`
+      say(`${asked} was picked but ${why}; handing off to ${got} instead`)
+      appendEvent(sid, { type: 'status', summary: `${asked} was picked for this hand-off but ${why}; ${got} took it instead` })
+    }
     // bound the number of hand-offs in one terminal so a chain that limits
     // instantly can never loop forever; stopping is explicit, not a silent exit 0
     if (leg >= 11) {

package/src/audit.mjs

@@ -0,0 +1,118 @@
+// audit — one list of who did what on this board, across every terminal and
+// every card, newest first.
+//
+// The ledger already names an actor on every event; until now you could only
+// read that one session or one card at a time, which is no use when the
+// question is "who landed that?" or "who handed my terminal off last night".
+// Nothing new is recorded here: this reads what is already on disk.
+//
+// Owner only (src/server.mjs): the trail names repositories and people.
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { home } from './store.mjs'
+import { listSessions, readEvents as readSessionEvents } from './sessions.mjs'
+import { readEvents as readCardEvents } from './ledger.mjs'
+
+// The types worth a line in an audit: something a person or an agent DID, not
+// the running commentary. A `status` line is commentary; a hand-off is not.
+export const AUDITED = [
+  'handoff', 'handoff_requested', 'handed_off', 'landed', 'land', 'bounced', 'killed',
+  'approved', 'approval_needed', 'reassigned', 'paused', 'resumed', 'ended', 'done',
+  'failed', 'trust', 'harness', 'worktree', 'station_done', 'leg_started', 'rerun',
+]
+
+export const ACTOR_KINDS = ['human', 'agent', 'leg']
+
+function actorOf(ev) {
+  // a card event carries a structured actor; a session event carries `by`
+  if (ev.actor && typeof ev.actor === 'object') {
+    if (ev.actor.type === 'human') return { kind: 'human', name: String(ev.actor.id ?? 'unknown') }
+    if (ev.actor.type === 'agent') return { kind: 'agent', name: String(ev.actor.adapter ?? 'agent') }
+    return { kind: 'leg', name: 'leg' }
+  }
+  if (ev.by) return { kind: 'human', name: String(ev.by) }
+  return { kind: 'leg', name: 'leg' }
+}
+
+function cardIds() {
+  const root = join(home(), 'cards')
+  if (!existsSync(root)) return []
+  try { return readdirSync(root).filter((d) => existsSync(join(root, d, 'card.json'))) } catch { return [] }
+}
+
+function cardMeta(id) {
+  try { return JSON.parse(readFileSync(join(home(), 'cards', id, 'card.json'), 'utf8')) } catch { return null }
+}
+
+// → { entries: [...], truncated, scanned: { sessions, cards, events } }
+// `scanned` is on the record deliberately: an empty audit from a board that
+// looked at nothing reads exactly like a quiet week, and the two are not the
+// same thing.
+export function auditTrail({ limit = 200, since = null, who = null, kind = null, types = null } = {}) {
+  const sinceMs = since ? Date.parse(since) : null
+  const wanted = Array.isArray(types) && types.length ? new Set(types) : new Set(AUDITED)
+  const rows = []
+  let events = 0
+
+  const sessions = listSessions()
+  for (const s of sessions) {
+    for (const ev of readSessionEvents(s.session_id)) {
+      events++
+      if (!wanted.has(ev.type)) continue
+      const at = Date.parse(ev.ts)
+      if (sinceMs && Number.isFinite(at) && at < sinceMs) continue
+      const actor = actorOf(ev)
+      rows.push({
+        at: ev.ts,
+        who: actor.name,
+        kind: actor.kind,
+        what: ev.type,
+        summary: String(ev.summary ?? ''),
+        where: 'terminal',
+        id: s.session_id,
+        agent: s.agent ?? null,
+        repo: s.repo ?? null,
+        branch: s.branch ?? null,
+      })
+    }
+  }
+
+  const ids = cardIds()
+  for (const id of ids) {
+    const card = cardMeta(id)
+    for (const ev of readCardEvents(id)) {
+      events++
+      if (!wanted.has(ev.type)) continue
+      const at = Date.parse(ev.ts)
+      if (sinceMs && Number.isFinite(at) && at < sinceMs) continue
+      const actor = actorOf(ev)
+      rows.push({
+        at: ev.ts,
+        who: actor.name,
+        kind: actor.kind,
+        what: ev.type,
+        summary: String(ev.summary ?? ''),
+        where: 'card',
+        id,
+        agent: ev.actor?.type === 'agent' ? ev.actor.adapter : null,
+        repo: card?.repo ?? null,
+        branch: card?.branch ?? null,
+      })
+    }
+  }
+
+  let filtered = rows
+  if (who) filtered = filtered.filter((r) => r.who.toLowerCase() === String(who).toLowerCase())
+  if (kind) filtered = filtered.filter((r) => r.kind === kind)
+  filtered.sort((a, b) => (Date.parse(b.at) || 0) - (Date.parse(a.at) || 0))
+  const capped = filtered.slice(0, Math.max(1, Math.min(limit, 1000)))
+
+  return {
+    entries: capped,
+    truncated: filtered.length > capped.length,
+    matched: filtered.length,
+    // L2: a verdict carries the volume it processed
+    scanned: { sessions: sessions.length, cards: ids.length, events },
+    people: [...new Set(rows.filter((r) => r.kind === 'human').map((r) => r.who))].sort(),
+  }
+}