@ucsandman/legcli 0.9.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

@@ -8,6 +8,7 @@
 // same terminal from that bundle. Subscription logins only: API keys are
 // stripped from the child environment (src/env.mjs).
 import http from 'node:http'
+import net from 'node:net'
 import { spawn, spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
 import { join, dirname, resolve, relative } from 'node:path'
@@ -36,6 +37,7 @@ import { captureLive } from './live-capture.mjs'
 import { waitForReset, fmtCountdown } from './wait.mjs'
 import { readPreferences, normalizeHandoffOrder, resolveAutoApprove } from './preferences.mjs'
 import { prepareHarnessForHandoff, harnessLine } from './harness/index.mjs'
+import { insideKnownStore } from './history/index.mjs'
 
 const SRC = dirname(fileURLToPath(import.meta.url))
 function resolveServer() {
@@ -80,6 +82,19 @@ function health(port, host = '127.0.0.1') {
   })
 }
 
+// Does anything own this port? A completed TCP connect is the question, so a
+// board too busy to answer /api/health still counts as one. Nothing is sent.
+function portTaken(port, host = '127.0.0.1') {
+  return new Promise((res) => {
+    const sock = net.connect({ host: host === '0.0.0.0' ? '127.0.0.1' : host, port })
+    const done = (v) => { sock.destroy(); res(v) }
+    sock.setTimeout(2000)
+    sock.on('connect', () => done(true))
+    sock.on('error', () => done(false))
+    sock.on('timeout', () => done(false))
+  })
+}
+
 export async function ensureBoard({ open = true } = {}) {
   // with share on the board lives on the shared address, not loopback
   const share = readShare()
@@ -88,7 +103,20 @@ export async function ensureBoard({ open = true } = {}) {
   const host = shared ? share.bind : '127.0.0.1'
   const url = `http://${host}:${port}`
   if ((process.env.LEG_NO_BOARD || process.env.BATON_NO_BOARD) === '1') return { url: null, started: false, skipped: true }
-  if (await health(port, host)) return { url, started: false }
+  // the board is opened whether or not this terminal is the one that started
+  // it: `leg claude` in a second terminal still means "show me the board"
+  if (await health(port, host)) { if (open) openBoard(url); return { url, started: false } }
+  // A board that is merely busy misses the health deadline while still owning
+  // the port. Treating that as "no board" spawned a second server that could
+  // only die of EADDRINUSE, and the poll below then waited the full fifteen
+  // seconds for a child already gone — the whole delay before the agent
+  // starts, and the reason no browser ever opened. A listener on the port is
+  // a board: attach to it and open it.
+  if (await portTaken(port, host)) {
+    say(`the board on ${url} is busy; attaching to it`)
+    if (open) openBoard(url)
+    return { url, started: false, busy: true }
+  }
   mkdirSync(home(), { recursive: true })
   const logFd = (await import('node:fs')).openSync(join(home(), 'board.log'), 'a')
   const child = spawn(process.execPath, [SERVER], { detached: true, windowsHide: true, stdio: ['ignore', logFd, logFd], env: { ...process.env, LEG_PORT: String(port), LEG_BIND: host, LEG_QUIET: '0', BATON_PORT: String(port), BATON_BIND: host, BATON_QUIET: '0' } })
@@ -235,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)
@@ -269,6 +300,13 @@ async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApp
 
   // taps
   let rollout = null; let tail = null
+  // a continued codex thread appends to its old rollout, which findRollout
+  // (newest file since this leg started) would never pick: bind it up front
+  // and read only what the thread writes from here on
+  if (agent === 'codex' && !prompt && session.transcript_path && session.agent_session_id && existsSync(session.transcript_path)) {
+    rollout = { path: session.transcript_path, meta: { id: session.agent_session_id } }
+    tail = createTail(rollout.path, { from: logSize(rollout.path) })
+  }
   let polls = 0; let warned = false
   let stop = null
   const done = new Promise((res) => { stop = res })
@@ -439,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
@@ -494,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 {
@@ -513,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(),
       },
     }
@@ -536,14 +582,18 @@ function prepareLegHarness({ sid, from, to }) {
 }
 
 // ---- the command ----
-export async function attach(agent, args = [], { open = true } = {}) {
+// `cwd` and `continued` are how `leg history continue` starts a leg on a
+// conversation the agent's own store holds (src/history/cli.mjs): the leg runs
+// in that conversation's folder, shares the checkout (its files are already
+// there), and the session record carries the agent's id from the start.
+export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null, continued = null } = {}) {
   if (!SUPERVISED_AGENTS.includes(agent)) throw new Error(`unknown agent "${agent}" (claude|codex|agy|grok)`)
   // the paid gate: a valid key, or no session (exit 4). The bare agent is never
   // affected; only what Leg adds is licensed.
   const ent = entitlement()
   if (!allows(ent, 'run')) { say(describeLicense(ent)); return 4 }
   // --no-worktree is Leg's flag, not the agent's: it never passes through
-  const shareCheckout = args.includes('--no-worktree')
+  const shareCheckout = args.includes('--no-worktree') || Boolean(continued)
   args = args.filter((a) => a !== '--no-worktree')
   let autoApproveCli = null
   if (args.includes('--no-auto-approve')) {
@@ -554,7 +604,7 @@ export async function attach(agent, args = [], { open = true } = {}) {
     args = args.filter((a) => a !== '--auto-approve')
   }
   const autoApprove = resolveAutoApprove({ cliFlag: autoApproveCli })
-  const cwd = process.cwd()
+  const cwd = cwdOpt ? realPath(cwdOpt) : process.cwd()
   const board = await ensureBoard({ open })
   let accounts = readAccounts()
   const installed = await installedAgents()
@@ -587,6 +637,13 @@ export async function attach(agent, args = [], { open = true } = {}) {
   // `git worktree add` still leaves a card (with a Remove button), never a
   // silent orphan under .baton-worktrees with no record and no button
   createSession({ id: sid, agent, account, cwd, repo: g.repo, branch: g.branch, argv: args, chain, worktree: null, owner: whoami(), handoffOrder, installed, runtimeCapabilities: [HANDOFF_ORDER_CAPABILITY] })
+  if (continued) {
+    // the agent's own id and transcript are known before the first turn, so
+    // history dedups this leg against the conversation it continues at once
+    const safeTranscript = (continued.transcript_path && insideKnownStore(continued.transcript_path)) ? continued.transcript_path : null
+    updateSession(sid, { agent_session_id: continued.native_id ?? null, transcript_path: safeTranscript, task: continued.title ?? null, continued_from: { id: continued.id, provider: continued.provider, native_id: continued.native_id ?? null } },
+      { event: { type: 'continued', summary: `continuing ${continued.id}${continued.title ? `: ${String(continued.title).slice(0, 120)}` : ''}` } })
+  }
   let iso = null
   if (g.repo && !shareCheckout) {
     try { iso = isolate({ g, cwd, sid }) } catch (err) { say(`could not make a worktree (${String(err.message).split('\n')[0].slice(0, 200)}); sharing the checkout`); try { removeWorktree(g.repo, sid) } catch {} }
@@ -623,7 +680,9 @@ export async function attach(agent, args = [], { open = true } = {}) {
     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
@@ -644,7 +703,7 @@ export async function attach(agent, args = [], { open = true } = {}) {
       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) {
@@ -660,7 +719,7 @@ export async function attach(agent, args = [], { open = true } = {}) {
       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
     }
@@ -671,6 +730,19 @@ export async function attach(agent, args = [], { open = true } = {}) {
       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) {