@ucsandman/legcli 0.10.0 → 0.12.0

package/src/attach.mjs

@@ -14,16 +14,19 @@ import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
 import { join, dirname, resolve, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { sanitizeEnv } from './env.mjs'
-import { home } from './store.mjs'
+import { home, readCard, listCards } from './store.mjs'
+import { loadResume } from './handoff.mjs'
+import { worktreePath } from './worktree.mjs'
 import { get as getAdapter } from './adapters/index.mjs'
 import { SUPERVISED_AGENTS, HANDOFF_ORDER_CAPABILITY, newSessionId, createSession, readSession, updateSession, appendEvent, takeControl, sessionDir, listSessions, reapLost, isActive, workRoot } from './sessions.mjs'
 import { ensure as ensureWorktree, remove as removeWorktree } from './worktree.mjs'
 import { canonPath, realPath } from './fsx.mjs'
 import { whoami, readShare, isOn as shareIsOn } from './share.mjs'
 import { readAccounts, envFor, refreshAccount } from './accounts.mjs'
-import { recordUsage, markLimited, chooseNext, candidates, fmtReset, WARN_PCT, readUsage, isAvailable } from './usage.mjs'
+import { recordUsage, markLimited, chooseNext, candidates, fmtReset, WARN_PCT, readUsage, isAvailable, wallActive, rungLabel, skipLine } from './usage.mjs'
 import { entitlement, allows, describe as describeLicense } from './license.mjs'
-import { writeSettings, userStatusLine, transcriptTail as claudeTail } from './taps/claude.mjs'
+import { writeSettings, userStatusLine, transcriptTail as claudeTail, modelAlias, modelFromTranscript, printable } from './taps/claude.mjs'
+import { modelFlagFor, isDownshift } from './buckets.mjs'
 import { ensureTrust, trustLine } from './trust.mjs'
 import { findRollout, createTail, parseLines, readCodexUsage, transcriptTail as codexTail } from './taps/codex.mjs'
 import { scanLog, promptsSince, logSize } from './taps/agy.mjs'
@@ -35,7 +38,7 @@ import { openBoard, pidfile } from './launcher.mjs'
 import { LAYOUT } from './accounts.mjs'
 import { captureLive } from './live-capture.mjs'
 import { waitForReset, fmtCountdown } from './wait.mjs'
-import { readPreferences, normalizeHandoffOrder, resolveAutoApprove } from './preferences.mjs'
+import { readPreferences, normalizeHandoffOrder, ladderFor, resolveAutoApprove } from './preferences.mjs'
 import { prepareHarnessForHandoff, harnessLine } from './harness/index.mjs'
 import { insideKnownStore } from './history/index.mjs'
 
@@ -58,7 +61,7 @@ const say = (line) => process.stderr.write(`[leg] ${line}\n`)
 async function refreshCodexUsage(account, codexHome, { timeoutMs = 8000, signal = null } = {}) {
   const r = await readCodexUsage({ codexHome, timeoutMs, signal })
   if (!r.ok) return r
-  const u = recordUsage('codex', account, r.limits, 'codex app-server account/rateLimits/read', { observed_at: r.observed_at, available: r.available })
+  const u = recordUsage('codex', account, { ...r.limits, facts: r.facts }, 'codex app-server account/rateLimits/read', { observed_at: r.observed_at, available: r.available })
   return { ...r, usage: u }
 }
 
@@ -156,6 +159,20 @@ export function gitInfo(cwd) {
   }
 }
 
+// How many commits this checkout is ahead of where the work started: the
+// upstream branch when the checkout tracks one, else the commit HEAD was at
+// when the session began. null when this is not a repo, when there is neither
+// an upstream nor a recorded start, or when git cannot answer. A count that
+// could not be taken is never printed as a zero (redesign A.4 row 8).
+export function aheadCount(cwd, fallbackBase = null) {
+  const upstream = git(cwd, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'])
+  const base = (upstream && upstream.trim()) || fallbackBase
+  if (!base) return null
+  const n = git(cwd, ['rev-list', '--count', `${base}..HEAD`])
+  const parsed = parseInt(String(n ?? '').trim(), 10)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
 // ---- collisions ----
 // Two agents in one working tree write over each other's files. When another
 // live session already works in this checkout, this one gets its own:
@@ -226,8 +243,126 @@ function restoreTerminal() {
   try { process.stdout.write(TERMINAL_RESET) } catch {}
 }
 
+// ---- model and terminal title ----
+// The model this leg resolved to, from the argv the human actually passed:
+// `--model x`, `-m x`, or the `--model=x` form. No default is invented — a
+// model token on a row that nobody chose is a wrong number in disguise, so the
+// answer for a bare `leg claude` is null until the transcript says otherwise.
+export function modelFromArgs(agent, args = []) {
+  const flag = modelFlagFor(agent)
+  const names = flag === '-m' ? ['-m', '--model'] : [flag, '-m'].filter(Boolean)
+  for (let i = 0; i < args.length; i++) {
+    const a = String(args[i] ?? '')
+    for (const n of names) {
+      if (a === n && args[i + 1] && !String(args[i + 1]).startsWith('-')) return modelAlias(agent, args[i + 1])
+      if (a.startsWith(n + '=')) return modelAlias(agent, a.slice(n.length + 1))
+    }
+  }
+  return null
+}
+
+export const shortId = (sessionId) => String(sessionId ?? '').split('-').pop()
+
+// ---- taking over a background card (redesign C.4) ----
+// Leg's own flags never reach the agent's argv, so they are lifted out of the
+// pass-through list before anything else looks at it. Both spellings, because
+// a human copying `--resume-card=<id>` out of a shell history is not wrong.
+export function takeFlagValue(args, flag) {
+  const out = []
+  let value = null
+  for (let i = 0; i < args.length; i++) {
+    const a = String(args[i] ?? '')
+    if (a === flag) {
+      const next = args[i + 1]
+      if (next !== undefined && !String(next).startsWith('-')) { value = String(next); i++ }
+      continue
+    }
+    if (a.startsWith(flag + '=')) { value = a.slice(flag.length + 1); continue }
+    out.push(args[i])
+  }
+  return { args: out, value }
+}
+
+// A card id in full, or the short tail the board prints. Ambiguity is an error
+// rather than a pick: opening a terminal in the wrong worktree is the one
+// outcome this whole feature exists to avoid.
+export function resolveCardId(want, cards = null) {
+  const wanted = String(want ?? '').trim()
+  if (!wanted) return { id: null, matches: [] }
+  if (readCard(wanted)) return { id: wanted, matches: [wanted] }
+  const ids = (cards ?? listCards()).map((c) => c.card_id)
+  const matches = ids.filter((id) => id === wanted || id.endsWith(`-${wanted}`) || id.includes(wanted))
+  return { id: matches.length === 1 ? matches[0] : null, matches }
+}
+
+// Where that card's work is: the worktree it recorded, else the one its id
+// names, else the repository itself. Never a path that is not there.
+export function cardWorkRoot(card) {
+  if (card?.worktree && existsSync(card.worktree)) return card.worktree
+  if (card?.repo) {
+    try { const p = worktreePath(card.repo, card.card_id); if (existsSync(p)) return p } catch { /* not a repo any more */ }
+  }
+  // never the main checkout: a card's work belongs in its own worktree, and a
+  // terminal opened in `card.repo` would edit the human's checkout under the
+  // card's name. The take-over route cuts a worktree before it hands out the
+  // command, so this is only reached for a card made by an older Leg.
+  return null
+}
+
+// The first prompt of a terminal that took a card over: the card's own bundle,
+// loaded through the same CLI every hand-off uses, with the card's task above
+// it. A bundle that will not load is said out loud and the terminal still opens.
+export function takeOverPrompt(card, cwd) {
+  let loaded = ''
+  try { loaded = loadResume(cwd, card.last_bundle ?? 'latest') } catch { loaded = '' }
+  const head = `# Taking over a background card\n\nCard ${card.card_id}, station ${card.station}, status ${card.status}. It is paused, so nothing else is running in this worktree.\n\nThe task: ${card.task ?? '(none recorded)'}\n\n`
+  return loaded
+    ? `${head}${loaded}`
+    : `${head}No bundle could be loaded. Read .leg/CONTRACT.md and .leg/PROGRESS.md in this directory, then check git status and git diff before continuing.`
+}
+
+// `leg#7f3a leg/main`: which terminal this window is, and where it is working.
+// Degrades to the id alone rather than printing a place that is not a repo.
+export function terminalTitle(session) {
+  const where = session?.repo_name ? `${session.repo_name}${session.branch ? '/' + session.branch : ''}` : null
+  return `leg#${shortId(session?.session_id)}${where ? ' ' + where : ''}`
+}
+
+// OSC 2 (set window title) for the CLIs with no title flag of their own.
+// ASSUMED: a VT terminal keeps the title once the child starts drawing. codex,
+// agy or grok may overwrite it with their own; nothing observed either way yet,
+// and the probe is to start each one and read the tab (redesign E, row 4).
+export function osc2(title) { return `\x1b]2;${printable(title)}\x07` }
+
+// Claude Code can wait at the usage limit itself when the human's own settings
+// re-enable autoContinueAtUsageLimit. Leg sets it false, but it does not own
+// that file, so when the `quota_auto_resume_fired` Notification arrives the
+// automatic hand-off stands down for that terminal: two waiters on one terminal
+// is the failure to avoid (redesign B.5). A human pressing Hand off > is not
+// affected — standing down is about what Leg does unasked.
+export function handoffStoodDown(session) {
+  return session?.waiting?.type === 'quota_auto_resume' ? (session.waiting.message ?? 'Claude Code is waiting at the limit itself') : null
+}
+
+// The model flag for a rung, or nothing. Nothing when the rung names no model,
+// when Leg does not know how that CLI spells one, or when the human already
+// passed a model themselves: an argv the human wrote is never overwritten.
+export function modelFlags(agent, args = [], model = null) {
+  if (!model) return []
+  const flag = modelFlagFor(agent)
+  if (!flag) return []
+  if (modelFromArgs(agent, args)) return []
+  return [flag, model]
+}
+
 // ---- spawn spec per agent ----
-export async function spawnSpec(agent, { account, args, sessionId, prompt, cwd, autoApprove = resolveAutoApprove() }) {
+// `model` is the rung's model (B.3); `resume` is the agent's own session id for
+// the one case where a hand-off keeps the conversation instead of the bundle:
+// a claude downshift (`--resume <id> --model <alias>`, settled by
+// fixtures/live/claude/resume-model-probe.json). codex has a `resume`
+// subcommand too, but composing it with `-m` is ASSUMED, not observed (codex
+// is walled on this machine until Saturday), so codex ships bundle-primed.
+export async function spawnSpec(agent, { account, args, sessionId, prompt, cwd, autoApprove = resolveAutoApprove(), model = null, resume = null }) {
   const adapter = await loadAdapter(agent)
   const { bin, viaNode, entry } = adapter.resolve()
   const argv = []
@@ -239,23 +374,32 @@ export async function spawnSpec(agent, { account, args, sessionId, prompt, cwd,
   if (agent === 'claude') {
     const settings = writeSettings(sessionId, { statusLine: userStatusLine(process.env.CLAUDE_CONFIG_DIR || (account !== 'default' ? envFor('claude', account).CLAUDE_CONFIG_DIR : undefined)) })
     const autoFlags = autoApprove && !args.includes('--dangerously-skip-permissions') ? ['--dangerously-skip-permissions'] : [] // auto-approve: not forbidden for interactive sessions
-    argv.push(...args, ...autoFlags, '--settings', settings)
+    // `-n, --name <name>`: "Set a display name for this session (shown in the
+    // prompt box, /resume picker, and terminal title)" — fixtures/help/claude.txt
+    // line 132, in the general Options section, not one of the flags marked
+    // "only works with --print", and two of its three surfaces (prompt box,
+    // /resume picker) exist only in interactive mode. A name the human passed
+    // themselves is never overwritten.
+    const named = args.some((a) => a === '-n' || a === '--name' || String(a).startsWith('--name='))
+    const nameFlags = named ? [] : ['-n', terminalTitle(readSession(sessionId) ?? { session_id: sessionId })]
+    const resumeFlags = resume ? ['--resume', String(resume)] : []
+    argv.push(...resumeFlags, ...args, ...modelFlags(agent, args, model), ...autoFlags, ...nameFlags, '--settings', settings)
     if (prompt) argv.push(prompt)
   } else if (agent === 'codex') {
     const hasApproval = args.includes('--ask-for-approval') || args.includes('-a') || args.some((x) => typeof x === 'string' && x.startsWith('--ask-for-approval='))
     const autoFlags = autoApprove && !hasApproval ? ['--ask-for-approval', 'never'] : []
-    argv.push(...args, ...autoFlags)
+    argv.push(...args, ...modelFlags(agent, args, model), ...autoFlags)
     if (prompt) argv.push(prompt)
   } else if (agent === 'agy') {
     const log = join(sessionDir(sessionId), 'agy.log')
     const autoFlags = autoApprove && !args.includes('--dangerously-skip-permissions') ? ['--dangerously-skip-permissions'] : [] // auto-approve: not forbidden for interactive sessions
-    argv.push(...args, ...autoFlags, '--log-file', log)
+    argv.push(...args, ...modelFlags(agent, args, model), ...autoFlags, '--log-file', log)
     if (prompt) argv.push('-i', prompt)
   } else if (agent === 'grok') {
     const log = join(sessionDir(sessionId), 'grok.log')
     const hasApprove = args.includes('--always-approve') || args.includes('--yolo') || args.includes('--approval-mode=yolo') // auto-approve check: not forbidden for interactive sessions
     const autoFlags = autoApprove && !hasApprove ? ['--always-approve'] : [] // auto-approve: not forbidden for interactive sessions
-    argv.push(...args, ...autoFlags, '--debug-file', log)
+    argv.push(...args, ...modelFlags(agent, args, model), ...autoFlags, '--debug-file', log)
     if (prompt) argv.push(prompt)
   }
   const env = { ...sanitizeEnv(process.env, { interactive: true }), ...envFor(agent, account), LEG_SESSION: sessionId, BATON_SESSION: sessionId }
@@ -263,8 +407,11 @@ export async function spawnSpec(agent, { account, args, sessionId, prompt, cwd,
 }
 
 // ---- one agent leg ----
-// Returns { reason: 'exit'|'limit'|'handoff', code }
-async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApprove = resolveAutoApprove() }) {
+// 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(), model = null, resume = null }) {
   const sid = session.session_id
   refreshAccount(agent, account)
   // A handoff happens when the limit hits, which is usually when nobody is
@@ -274,8 +421,8 @@ async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApp
   const trust = ensureTrust(agent, session.cwd, { cwd: session.cwd })
   const trusted = trustLine(trust)
   if (trusted) { say(trusted); appendEvent(sid, { type: 'trust', summary: trusted }) }
-  const spec = await spawnSpec(agent, { account, args, sessionId: sid, prompt, cwd: session.cwd, autoApprove })
-  appendEvent(sid, { type: 'leg', summary: `${agent} (${account}) starting${prompt ? ' from the handoff bundle' : ''}` })
+  const spec = await spawnSpec(agent, { account, args, sessionId: sid, prompt, cwd: session.cwd, autoApprove, model, resume })
+  appendEvent(sid, { type: 'leg', summary: `${agent}${model ? '/' + model : ''} (${account}) starting${resume ? ' with the conversation it already had' : prompt ? ' from the handoff bundle' : ''}` })
   const startedMs = Date.now()
   const turnsAtLegStart = session.turns ?? 0
   // agy appends to one log for the whole session: a second agy leg reads from
@@ -284,6 +431,12 @@ async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApp
   const agyTail = agyLog ? createTail(agyLog, { from: logSize(agyLog) }) : null
   const grokLog = agent === 'grok' ? join(sessionDir(sid), 'grok.log') : null
   const grokTail = grokLog ? createTail(grokLog, { from: logSize(grokLog) }) : null
+  // claude takes `-n` (spawnSpec). The other three have no title flag, so Leg
+  // writes the title itself, once, before the child owns the terminal. Only on
+  // a TTY: into a pipe or a log this would be four stray control bytes.
+  if (agent !== 'claude' && process.stdout.isTTY) {
+    try { process.stdout.write(osc2(terminalTitle(session))) } catch {}
+  }
   let child
   try {
     child = spawn(spec.bin, spec.args, { cwd: spec.cwd, env: spec.env, stdio: 'inherit', windowsHide: false })
@@ -293,7 +446,9 @@ async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApp
   }
   // every leg starts on its own card: the agent that just left takes its
   // percentages, its warning and its usage source with it
-  updateSession(sid, { pid: child.pid, agent, account, status: agent === 'claude' ? 'starting' : 'running', limit: null, warning: null, limits: null, usage_source: null, usage_error: null })
+  // the model goes with it: the next leg's argv is the only thing Leg knows
+  // about the model until that agent's own transcript says otherwise
+  updateSession(sid, { pid: child.pid, agent, account, model: modelFromArgs(agent, args) ?? model ?? null, status: agent === 'claude' ? 'starting' : 'running', limit: null, warning: null, limits: null, usage_source: null, usage_error: null })
 
   // taps
   let rollout = null; let tail = null
@@ -304,7 +459,7 @@ async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApp
     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 polls = 0; let warned = false; let stoodDown = false
   let stop = null
   const done = new Promise((res) => { stop = res })
   child.on('error', (err) => { appendEvent(sid, { type: 'error', summary: `${agent} spawn error: ${err.message}` }); stop({ reason: 'exit', code: 127 }) })
@@ -322,10 +477,20 @@ async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApp
       if (!isCurrentLeg(s, { pid: child.pid, agent, account })) return
       // a 404, a body that is not JSON, or a shape with no window at all: the
       // card says usage unknown and the StopFailure hook still owns the limit
+      // which model actually answered. The transcript path arrives on the
+      // SessionStart hook payload (src/taps/claude.mjs `handleHook`, `base`),
+      // so this only reads once Claude Code has told Leg where its jsonl is.
+      // A fallback off fable shows up here and nowhere else.
+      const seen = modelFromTranscript(s.transcript_path, { agent: 'claude' })
+      if (seen && seen !== s.model) {
+        updateSession(sid, { model: seen }, { event: { type: 'status', summary: `claude is answering on ${seen}${s.model ? ` (was ${s.model})` : ''}` } })
+      }
       const usable = r.ok && r.limits && (r.limits.five_hour || r.limits.seven_day)
       if (usable) {
         recordUsage('claude', account, r.limits, 'claude usage endpoint')
-        updateSession(sid, { limits: r.limits, usage_source: 'claude usage endpoint', usage_error: null })
+        // the session record keeps the two windows it always had: the buckets
+        // live on the usage record, which is per login and not per terminal
+        updateSession(sid, { limits: { five_hour: r.limits.five_hour, seven_day: r.limits.seven_day }, usage_source: 'claude usage endpoint', usage_error: null })
       } else if (!s.usage_error) {
         const why = r.error ?? 'the usage endpoint answered with no window'
         updateSession(sid, { usage_error: why }, { event: { type: 'status', summary: `claude usage unavailable: ${why}` } })
@@ -382,7 +547,7 @@ async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApp
       // git: which files this session is touching, where trunk is
       if (polls % GIT_EVERY === 1) {
         const g = gitInfo(s.cwd)
-        if (g.repo) { patch.files_dirty = g.dirty; patch.head = g.head; patch.branch = g.branch }
+        if (g.repo) { patch.files_dirty = g.dirty; patch.head = g.head; patch.branch = g.branch; patch.ahead = aheadCount(s.cwd, s.head_at_start) }
       }
       // codex: find + tail the rollout
       if (agent === 'codex') {
@@ -394,7 +559,7 @@ async function runLeg({ agent, account, args, session, prompt, boardUrl, autoApp
         if (tail) {
           const r = parseLines(tail.read())
           if (r.limits) {
-            const u = recordUsage('codex', account, r.limits, 'codex rollout token_count', { observed_at: r.limits_at })
+            const u = recordUsage('codex', account, { ...r.limits, facts: r.facts }, 'codex rollout token_count', { observed_at: r.limits_at })
             if (u.usage_applied) { patch.limits = r.limits; patch.last_activity = new Date().toISOString() }
           }
           const firstUser = r.messages.find((m) => m.role === 'user')
@@ -474,12 +639,24 @@ 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'), ...(ctl.target.model ? { model: String(ctl.target.model) } : {}) }
+          : null
+        const toWhom = picked ? ` to ${rungLabel(picked)}` : ''
+        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
       if ((next.status === 'limit' || next.limit) && (process.env.LEG_NO_HANDOFF || process.env.BATON_NO_HANDOFF) !== '1') {
+        // Claude Code is waiting at the limit itself: stand down rather than
+        // kill a child that is about to resume on its own. Said once, with the
+        // reason, so the terminal that did not hand off is never a mystery.
+        const standDown = handoffStoodDown(next)
+        if (standDown) {
+          if (!stoodDown) { stoodDown = true; say(standDown); appendEvent(sid, { type: 'status', summary: `hand-off stood down: ${standDown}` }) }
+          return
+        }
         clearInterval(timer); killTree(child.pid); restoreTerminal(); stop({ reason: 'limit', code: null })
       }
     } catch (err) {
@@ -529,14 +706,43 @@ 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 = [] }) {
-  let choice = { next: null, out: [] }
+// `automatic` is the fact, not a guess from the shape of the call: only the
+// usage limit (and the scheduler behind a card) hands off unasked. A human
+// pressing Hand off now sends no destination at all when they take the default
+// option, and inferring "automatic" from that missing target applied the
+// reserve, the cost gate and climb-back to a hand-off the human asked for, on
+// rungs the picker had just shown them as available (B.3).
+export function claimHandoffChoice({ sid, agent, account, model = null, installed, bundle = null, reason = 'limit', nowS = Math.floor(Date.now() / 1000), exclude = [], prefer = null, preferences = null, automatic = null }) {
+  let choice = { next: null, out: [], reasons: [] }
   let claimed = false
+  const auto = automatic === null ? reason === 'limit' : Boolean(automatic)
+  // The machine's spending rules are read once, here: a rung that costs credits
+  // is skipped unless the human allowed it, the reserve applies to automatic
+  // hand-offs only, and climb-back decides whether an automatic hand-off may
+  // walk back UP the ladder (B.3, B.7).
+  const prefs = preferences ?? readPreferences()
   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: [] }
+    // the terminal's own ladder, else the long-hand form of its order: a
+    // terminal started before ladders existed behaves exactly as it did.
+    const ladder = ladderFor(current)
+    const legModel = model ?? current.model ?? null
+    choice = chooseNext({
+      agent, account, model: legModel, accounts, installed, order, ladder, nowS, exclude, prefer,
+      maySpend: prefs.may_spend, reserve: prefs.reserve, climbBack: prefs.climb_back, automatic: auto,
+    })
+    // Nothing on the ladder: keep the login the terminal is already on, but
+    // only when it can really run the next leg. A model wall leaves the account
+    // open by design, so claiming {agent, account} with no model here respawned
+    // the CLI on the model that had just walled, walled again, and burned all
+    // twelve legs. The model rides the claimed rung for the same reason, and
+    // `out` is kept so the all-out wait below still has its reset clocks.
+    const own = readUsage(agent, account)
+    const ownOpen = isAvailable(own, nowS) && !(legModel && wallActive(own.walls?.[legModel], nowS))
+    if (!choice.next && ownOpen && !exclude.some((x) => x.agent === agent && x.account === account)) {
+      choice = { next: { agent, account, ...(legModel ? { model: legModel } : {}) }, out: choice.out ?? [], reasons: choice.reasons ?? [], preferred_taken: false }
+    }
     if (!choice.next) return {}
     claimed = true
     return {
@@ -548,6 +754,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(),
       },
     }
@@ -555,6 +765,25 @@ export function claimHandoffChoice({ sid, agent, account, installed, bundle = nu
   return { choice, claimed, session }
 }
 
+// A pick that could not be taken, said in the words the ladder already used.
+// `choice.reasons` carries {agent, account, model, reason} for every rung the
+// walk passed over, so the cost gate, the reserve and a `below:N` rule all have
+// their own sentence sitting there; re-deriving the explanation from the
+// account's `limited_until` printed "at its limit until unknown" for a rung
+// that was never walled at all. The limit sentence stays as the fallback for a
+// rung the walk never reached. Both names carry their model (rungLabel), or a
+// downshift reads as "claude was picked but ...; handing off to claude".
+// → { asked, got, why }
+export function pickedAside({ prefer, next, choice, excluded = [], read = readUsage }) {
+  const want = { agent: prefer.agent, account: prefer.account ?? 'default', model: prefer.model ?? null }
+  const asked = rungLabel(want)
+  const got = rungLabel(next)
+  if (excluded.some((x) => x.agent === want.agent && x.account === want.account)) return { asked, got, why: 'the strict harness policy refused it' }
+  const hit = (choice?.reasons ?? []).find((r) => r.agent === want.agent && r.account === want.account && (want.model ? (r.model ?? null) === want.model : true))
+  if (hit?.reason) return { asked, got, why: hit.reason }
+  return { asked, got, why: `it is at its limit until ${fmtReset(read(want.agent, want.account).limited_until)}` }
+}
+
 // The portable harness, decided before a leg starts (src/harness/index.mjs).
 // Off by default: then this records nothing and changes nothing. On, it
 // carries the source agent's working environment to the agent about to run,
@@ -581,8 +810,27 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
   // 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') || Boolean(continued)
+  // `--resume-card <id>`: Take over on the board paused a card and handed the
+  // human this command. The terminal opens in that card's own worktree, primed
+  // from its bundle (redesign C.4). Leg's flag, never the agent's.
+  const lifted = takeFlagValue(args, '--resume-card')
+  args = lifted.args
+  let card = null
+  if (lifted.value !== null) {
+    const hit = resolveCardId(lifted.value)
+    if (!hit.id) {
+      say(hit.matches.length
+        ? `"${lifted.value}" matches ${hit.matches.length} cards (${hit.matches.slice(0, 5).join(', ')}); use the full id`
+        : `no card matches "${lifted.value}" (leg card ls lists them)`)
+      return 3
+    }
+    card = readCard(hit.id)
+    if (!cardWorkRoot(card)) { say(`card ${hit.id} has no checkout on this machine yet; run it once, or open ${card.repo} yourself`); return 3 }
+  }
+  // --no-worktree is Leg's flag, not the agent's: it never passes through.
+  // A card take-over shares the card's checkout for the same reason: cutting a
+  // second worktree on its branch is what Take over exists to avoid.
+  const shareCheckout = args.includes('--no-worktree') || Boolean(continued) || Boolean(card)
   args = args.filter((a) => a !== '--no-worktree')
   let autoApproveCli = null
   if (args.includes('--no-auto-approve')) {
@@ -593,11 +841,16 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
     args = args.filter((a) => a !== '--auto-approve')
   }
   const autoApprove = resolveAutoApprove({ cliFlag: autoApproveCli })
-  const cwd = cwdOpt ? realPath(cwdOpt) : process.cwd()
+  const cwd = card ? realPath(cardWorkRoot(card)) : (cwdOpt ? realPath(cwdOpt) : process.cwd())
   const board = await ensureBoard({ open })
   let accounts = readAccounts()
   const installed = await installedAgents()
-  const handoffOrder = readPreferences().handoff_order
+  // The machine's preferences are copied into this terminal at start: the
+  // ladder it walks, and the spending rules it walks it under. Later edits
+  // reach a running terminal only through the board's per-terminal ladder.
+  const prefs = readPreferences()
+  const handoffOrder = prefs.handoff_order
+  const handoffLadder = prefs.handoff_ladder
   let account = process.env.LEG_ACCOUNT || process.env.BATON_ACCOUNT || 'default'
   if (!(accounts[agent] ?? ['default']).includes(account)) { say(`no ${agent} account "${account}"; using default`); account = 'default' }
   // A persisted wall is only a cache. Ask Codex's read-only account endpoint
@@ -612,20 +865,27 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
     await fetchGrokUsage({ configDir: grokHome }).catch(() => {})
   }
   // Start on an account that is not at its wall, if we already know one is.
+  let startModel = null
   const nowS = Math.floor(Date.now() / 1000)
   const u0 = readUsage(agent, account)
   if (u0.limited_until && u0.limited_until > nowS) {
-    const alt = chooseNext({ agent, account, accounts, installed, order: handoffOrder, nowS })
-    if (alt.next) { say(`${agent} (${account}) is at its limit until ${fmtReset(u0.limited_until)}; starting ${alt.next.agent} (${alt.next.account}) instead`); agent = alt.next.agent; account = alt.next.account }
+    // automatic: the human asked for this agent, not for this destination, so
+    // the machine's own floors (the reserve, the spending gate) still apply to
+    // the rung Leg substitutes for it.
+    const alt = chooseNext({ agent, account, accounts, installed, order: handoffOrder, ladder: handoffLadder, nowS, maySpend: prefs.may_spend, reserve: prefs.reserve, climbBack: prefs.climb_back, automatic: true })
+    if (alt.next) { say(`${agent} (${account}) is at its limit until ${fmtReset(u0.limited_until)}; starting ${rungLabel(alt.next)} instead`); agent = alt.next.agent; account = alt.next.account; startModel = alt.next.model ?? null }
     else say(`${agent} (${account}) is at its limit until ${fmtReset(u0.limited_until)}; starting anyway (every option is out)`)
   }
   const g = gitInfo(cwd)
   const sid = newSessionId(agent)
-  const chain = candidates({ agent, account, accounts, order: handoffOrder })
+  const chain = candidates({ agent, account, accounts, order: handoffOrder, ladder: handoffLadder, model: startModel ?? modelFromArgs(agent, args) })
   // record the session BEFORE cutting a worktree, so a crash or Ctrl-C during
   // `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] })
+  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], model: modelFromArgs(agent, args) ?? startModel })
+  // the ladder is a copy too, so the board can edit this terminal's rungs
+  // without changing the machine default under every other terminal
+  updateSession(sid, { handoff_ladder: handoffLadder })
   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
@@ -647,7 +907,17 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
   }
 
   let prompt = null
+  if (card) {
+    // the card's bundle is this terminal's first prompt, and the record says
+    // where this terminal came from, so the board can draw the line back
+    updateSession(sid, { lineage: { from: card.card_id, to: null }, task: card.task ?? null },
+      { event: { type: 'continued', summary: `taking over card ${card.card_id} (${card.status} at ${card.station}) in ${cwd}` } })
+    prompt = takeOverPrompt(card, cwd)
+    say(`taking over card ${card.card_id} in ${cwd}${card.last_bundle ? ` from bundle ${card.last_bundle}` : ''}`)
+  }
   let legArgs = args
+  let legModel = startModel
+  let legResume = null
   let exit = 0
   // the first leg is the agent the human chose: its harness is prepared per
   // policy and recorded, never refused (strict applies to hand-offs)
@@ -656,7 +926,7 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
   // bounds a wait; a normal session runs one leg and exits
   for (let leg = 0; ; leg++) {
     const s = readSession(sid)
-    const r = await runLeg({ agent, account, args: legArgs, session: s, prompt, boardUrl: board.url, autoApprove })
+    const r = await runLeg({ agent, account, args: legArgs, session: s, prompt, boardUrl: board.url, autoApprove, model: legModel, resume: legResume })
     if (r.reason === 'exit') { exit = r.code ?? 0; break }
     // limit or handoff: bundle, choose next, go again in this terminal
     const cur = readSession(sid)
@@ -669,7 +939,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, model: cur.model ?? null, installed, bundle, reason: r.reason, exclude: excluded, prefer, automatic: r.reason !== 'handoff' })
     let choice = claim.choice
     let cancelled = false
     let blocked = false
@@ -687,10 +959,13 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
       say(`every option is out. First back: ${label} at ${first ? fmtReset(first.resets_at) : 'unknown'}`)
       for (const o of all) say(`  ${o.agent}${o.account !== 'default' ? '/' + o.account : ''}: resets ${fmtReset(o.resets_at)}`)
       say(`waiting for ${label}; Ctrl-C to quit`)
-      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'}` } })
+      // `type: 'reset'` tells this apart from the Notification hook's
+      // `waiting` (a human being waited on). Same key, two shapes, one
+      // discriminator; see the field comment in src/sessions.mjs.
+      updateSession(sid, { status: 'waiting', all_out: all, waiting: first ? { type: 'reset', 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, model: cur.model ?? null, installed, bundle, reason: r.reason, exclude: excluded, prefer, automatic: r.reason !== 'handoff' })
       choice = claim.choice
     }
     if (cancelled) {
@@ -706,7 +981,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, model: cur.model ?? null, installed, bundle, reason: r.reason, exclude: excluded, prefer, automatic: r.reason !== 'handoff' })
       choice = claim.choice
       if (!choice.next) blocked = true
     }
@@ -717,6 +992,15 @@ 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, got, why } = pickedAside({ prefer, next, choice, excluded })
+      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) {
@@ -725,8 +1009,29 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
       exit = 3
       break
     }
-    appendEvent(sid, { type: 'handoff', summary: `${agent}${account !== 'default' ? '/' + account : ''} → ${next.agent}${next.account !== 'default' ? '/' + next.account : ''}${bundle ? ` (bundle ${bundle.id})` : ''}` })
-    if (bundle) {
+    // Every rung the ladder walked past, in the ledger, with the reason: a
+    // terminal that skipped claude/fable because credits are off must say so
+    // (B.3). "not installed" is left out: that one is about this machine, not
+    // about this hand-off, and it would repeat on every leg.
+    for (const why of choice.reasons ?? []) {
+      if (why.reason === 'not installed on this machine') continue
+      const line = skipLine(why)
+      say(line)
+      appendEvent(sid, { type: 'status', summary: line })
+    }
+    // The one hand-off that keeps the conversation: a claude downshift with the
+    // agent's own session id on the record. `--resume <id> --model <alias>`
+    // starts the next leg inside the same conversation, so the bundle is not
+    // written into a prompt and nothing is re-explained. Every other rung takes
+    // the bundle: an upshift back to fable (which would re-read the whole
+    // context at fable's rate), a second account, and codex, whose `resume`
+    // subcommand exists but has never been seen composing with `-m` here.
+    const fromRung = { agent, account, model: cur.model ?? null }
+    const keepsConversation = Boolean(next.agent === 'claude' && isDownshift(fromRung, next) && cur.agent_session_id)
+    appendEvent(sid, { type: 'handoff', summary: `${rungLabel(fromRung)} → ${rungLabel(next)}${keepsConversation ? ' (kept the conversation)' : bundle ? ` (bundle ${bundle.id})` : ''}` })
+    if (keepsConversation) {
+      prompt = null
+    } else if (bundle) {
       prompt = resumePrompt(cur, bundle, next)
     } else {
       const delta = sessionCommitDelta(workRoot(cur) ?? cur.cwd, cur)
@@ -735,13 +1040,16 @@ export async function attach(agent, args = [], { open = true, cwd: cwdOpt = null
         : 'Check git status and git diff, then continue the work.'
       prompt = `You are taking over an interactive coding session from ${agent}.${existsSync(notesFile) ? ` Read ${notesFile} in this directory first (the previous agent's notes: task, last messages, dirty files).` : ''} ${fallbackAction} The task: ${cur.task ?? 'see the recent changes'}`
     }
-    say(`starting ${next.agent}${next.account !== 'default' ? '/' + next.account : ''} in this terminal from the bundle`)
+    say(`starting ${rungLabel(next)} in this terminal ${keepsConversation ? 'with --resume: kept the conversation' : 'from the bundle'}`)
+    legResume = keepsConversation ? cur.agent_session_id : null
+    legModel = next.model ?? null
     agent = next.agent; account = next.account; legArgs = []
     // the chain is what comes after the agent now taking over, not after the
     // one that started the session: the card's "next" names a live option
     updateSession(sid, (fresh) => {
       const freshOrder = normalizeHandoffOrder(fresh.handoff_order)
-      return { lineage: { from: cur.agent, to: next.agent }, chain: candidates({ agent: next.agent, account: next.account, accounts: readAccounts(), order: freshOrder }) }
+      const freshLadder = ladderFor(fresh)
+      return { lineage: { from: cur.agent, to: next.agent }, chain: candidates({ agent: next.agent, account: next.account, model: next.model ?? null, accounts: readAccounts(), order: freshOrder, ladder: freshLadder }) }
     })
   }
   const fin = readSession(sid)