@ucsandman/legcli 0.11.0 → 0.13.0

package/src/server.mjs

@@ -7,7 +7,7 @@
 import http from 'node:http'
 import https from 'node:https'
 import { spawnSync, execFile } from 'node:child_process'
-import { existsSync, readFileSync, readdirSync, statSync, rmSync, watch as fsWatch, mkdirSync, openSync, fstatSync, readSync, closeSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, rmSync, watch as fsWatch, mkdirSync, openSync, fstatSync, readSync, closeSync } from 'node:fs'
 import { join, dirname, resolve, extname, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { checkBind, authorize, remoteAddress, presentedToken, isLoopback, isLoopbackRequest, tokenMatches } from './auth.mjs'
@@ -15,26 +15,31 @@ import { readShare, isOn as shareIsOn, sharePath, identify, personNamed, mayUseC
 import { auditTrail, ACTOR_KINDS } from './audit.mjs'
 import { createLimiter } from './ratelimit.mjs'
 import { realPath, canonPath } from './fsx.mjs'
-import { listCards, readCard, readRuns, readEvents, cardDir, home } from './store.mjs'
+import { listCards, readCard, readRuns, readEvents, cardDir, home, ledgerAppend, ledgerUpdate } from './store.mjs'
+import { saveSessionBundle } from './bundle.mjs'
+import { transcriptTail as claudeTranscriptTail } from './taps/claude.mjs'
 import { humanAction } from './orchestrator.mjs'
 import { createCard, CardInputError } from './cards.mjs'
-import { IllegalTransition, availableActions } from './chain.mjs'
+import { IllegalTransition, availableActions, NON_TERMINAL, TERMINAL } from './chain.mjs'
 import { held } from './leases.mjs'
 import { PRESETS } from './presets.mjs'
 import { names as adapterNames, get as getAdapter, isFake } from './adapters/index.mjs'
 import { createScheduler, schedulerStatus, MAX_CONCURRENT } from './scheduler.mjs'
-import { remove as removeWorktree, worktreeDirty } from './worktree.mjs'
+import { ensure as ensureWorktree, remove as removeWorktree, worktreeDirty } from './worktree.mjs'
 import { scrub } from './runner.mjs'
 import { resolveChb } from './handoff.mjs'
-import { listSessions, readSession, readEvents as readSessionEvents, requestControl, removeSession, overlaps, isActive, sessionsRoot, reapLost, readLand, readLandings, readRequests, writeRequests, appendEvent as appendSessionEvent, updateSession, HANDOFF_ORDER_CAPABILITY } from './sessions.mjs'
+import { listSessions, readSession, readEvents as readSessionEvents, requestControl, removeSession, overlaps, isActive, sessionsRoot, reapLost, readLand, readLandings, readRequests, writeRequests, appendEvent as appendSessionEvent, updateSession, HANDOFF_ORDER_CAPABILITY, SUPERVISED_AGENTS } from './sessions.mjs'
 import { sessionDetail, sessionDiff, DiffInputError } from './session-detail.mjs'
 import { hasRecentSynthesis } from './synthesis.mjs'
 import { refreshPointers } from './resume.mjs'
 import { landSession, landBlocker, landingNow, pruneSessionWorktree, canLand, prepareLanding, applyLandFix } from './land.mjs'
-import { readUsage, recordUsage, usageIsStale, candidates, isAvailable, fmtReset } from './usage.mjs'
-import { readAccounts, envFor, LAYOUT } from './accounts.mjs'
-import { readCodexUsage } from './taps/codex.mjs'
-import { readPreferences, writePreferences, normalizeHandoffOrder, requireHandoffOrder } from './preferences.mjs'
+import { readUsage, usageIsStale, candidates, isAvailable, fmtReset, binding, evaluateLadder, rungLabel, wallActive } from './usage.mjs'
+import { readAccounts } from './accounts.mjs'
+import { createUsagePollers, USAGE_AGENTS } from './usage-poll.mjs'
+import { readCodexUsage, transcriptTail as codexTranscriptTail } from './taps/codex.mjs'
+import { readPreferences, writePreferences, normalizeHandoffOrder, requireHandoffOrder, ladderFor, requireHandoffLadder, requireClimbBack, requireReserve, orderFromLadder } from './preferences.mjs'
+import { isDownshift } from './buckets.mjs'
+import { listModels } from './models.mjs'
 import { listHistory, findRecord, recordDetail, refreshIndex, readIndex, providerSupport, HistoryInputError, PROVIDER_NAMES } from './history/index.mjs'
 import { listWorktrees } from './history/worktrees.mjs'
 
@@ -75,16 +80,192 @@ export function columnOf(card) {
   return card.station
 }
 
-export function summarize(card) {
+// ---- the work stat on a live card's row (redesign C.3) --------------------
+// `4 files, +212 -18`. Parsed from git's own one-line summary, never counted
+// here: a part the line does not carry is left off the object, so the row can
+// print only what was measured and never estimate the rest.
+export function parseShortstat(line) {
+  const text = String(line ?? '')
+  const files = /(\d+)\s+files?\s+changed/.exec(text)
+  const ins = /(\d+)\s+insertions?\(\+\)/.exec(text)
+  const del = /(\d+)\s+deletions?\(-\)/.exec(text)
+  if (!files && !ins && !del) return null
+  const out = {}
+  if (files) out.files = parseInt(files[1], 10)
+  if (ins) out.insertions = parseInt(ins[1], 10)
+  if (del) out.deletions = parseInt(del[1], 10)
+  return out
+}
+
+function measureWork(card) {
+  if (!card.worktree || !existsSync(card.worktree)) return null
+  const base = card.trunk || 'main'
+  const r = spawnSync('git', ['diff', '--shortstat', `${base}..HEAD`], { cwd: card.worktree, windowsHide: true, encoding: 'utf8', timeout: 8000, env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+  if (r.status !== 0) return null
+  return parseShortstat(r.stdout)
+}
+
+// One `git diff` per live card per push would put a subprocess per card inside
+// the board's one event loop, which is the stall canLandFor already exists to
+// avoid. Keyed on the card's own revision, with the expiries spread across the
+// window so twenty cards never re-read together.
+const WORK_TTL = 15000
+const workCache = new Map()
+function workFor(card) {
+  const key = `${card.card_id}|${card.updated_at ?? ''}`
+  const hit = workCache.get(key)
+  if (hit && Date.now() < hit.until) return hit.data
+  let data = null
+  try { data = measureWork(card) } catch { data = null }
+  if (workCache.size > 300) workCache.clear()
+  workCache.set(key, { until: Date.now() + WORK_TTL / 2 + Math.random() * WORK_TTL, data })
+  return data
+}
+
+// The test and land verdicts a live card has already earned. Both are read from
+// the card's own ledger, because that is where each station records its result:
+// a test station writes no run.json (src/stations/test.mjs), and a landing is a
+// `landed` / `bounced` / `failed` event (src/chain.mjs). Last one wins; a card
+// that has run neither carries neither key.
+export function cardOutcomes(events) {
+  const out = {}
+  for (const ev of events ?? []) {
+    const summary = String(ev.summary ?? '')
+    const m = /^test (green|red)\b/.exec(summary)
+    if (m) out.tests = { state: m[1], at: ev.ts }
+    if (ev.type === 'landed') {
+      const sha = /\b([0-9a-f]{7,40})\b/.exec(summary)
+      out.land = { state: 'landed', reason: null, sha: sha ? sha[1] : null }
+    } else if (ev.type === 'bounced' && /^land bounced/.test(summary)) {
+      out.land = { state: 'bounced', reason: ev.body ? String(ev.body).slice(0, 200) : summary, sha: null }
+    } else if (ev.type === 'failed' && /\bland\b/.test(summary)) {
+      out.land = { state: 'failed', reason: ev.body ? String(ev.body).slice(0, 200) : summary, sha: null }
+    }
+  }
+  return out
+}
+
+// The last messages a hand-off bundle quotes, from the agent's own transcript.
+// An agent Leg cannot read a transcript for contributes none, and the bundle is
+// written from the record alone rather than with invented text.
+function sessionMessages(s) {
+  try {
+    if (s.agent === 'claude') return claudeTranscriptTail(s.transcript_path)
+    if (s.agent === 'codex') return codexTranscriptTail(s.transcript_path)
+  } catch { /* an unreadable transcript is not a reason to refuse the bundle */ }
+  return []
+}
+
+// This terminal's ladder from the rung it is standing on, downward. A card made
+// from a terminal starts where the terminal is, not at the top: the rungs above
+// it are the ones this work has already used up (redesign C.4).
+export function ladderFromCurrentRung(session) {
+  const ladder = ladderFor(session).filter((r) => r && r.agent)
+  const exact = ladder.findIndex((r) => r.agent === session.agent && (r.account ?? 'default') === (session.account ?? 'default') && (r.model ?? null) === (session.model ?? null))
+  const byAgent = exact >= 0 ? exact : ladder.findIndex((r) => r.agent === session.agent)
+  return byAgent >= 0 ? ladder.slice(byAgent) : ladder
+}
+
+// ---- carrying a checkout's uncommitted work into another one --------------
+// "End, and keep going as a card" on a lone terminal (the ordinary case: a
+// terminal only cuts a worktree of its own when a second live session shares
+// the checkout, src/attach.mjs isolate()) has to move the work the human was
+// looking at, not just the branch it sits on. Captured in two halves, because
+// git keeps them apart: a patch of everything it tracks, staged and unstaged
+// (`git diff HEAD --binary`), and the bytes of the files it does not
+// (`git ls-files --others`). The second half is the one `git stash create`
+// cannot carry, and it is where a terminal's newest file always is.
+const CARRY_SKIP = ['.git', '.leg-worktrees', '.baton-worktrees', '.context-handoffs', '.leg', '.baton', 'node_modules']
+const CARRY_MAX_BYTES = 8 * 1024 * 1024
+function gitIn(dir, args, opts = {}) {
+  const r = spawnSync('git', ['-C', dir, ...args], { windowsHide: true, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 30000, env: { ...process.env, MSYS_NO_PATHCONV: '1' }, ...opts })
+  if (r.error) throw r.error
+  if (r.status !== 0) throw new Error(`git ${args[0]} failed: ${String(r.stderr ?? '').trim().slice(0, 200)}`)
+  return r.stdout
+}
+
+export function captureUncommitted(dir) {
+  const status = gitIn(dir, ['status', '--porcelain'])
+  if (!status.trim()) return null
+  // --binary keeps a changed image or lockfile intact; the output is ASCII
+  const patch = gitIn(dir, ['diff', 'HEAD', '--binary'])
+  const files = []
+  for (const rel of gitIn(dir, ['ls-files', '--others', '--exclude-standard']).split('\n').map((s) => s.trim()).filter(Boolean)) {
+    if (CARRY_SKIP.includes(rel.split('/')[0])) continue
+    const from = join(dir, rel)
+    let st
+    try { st = statSync(from) } catch { continue }
+    if (!st.isFile()) continue
+    // refuse loudly rather than carry half the work: the caller turns this
+    // into a 409 and the terminal is left alone
+    if (st.size > CARRY_MAX_BYTES) throw new Error(`${rel} is ${Math.round(st.size / 1048576)}MB, too large to carry into the card's checkout`)
+    files.push({ rel, data: readFileSync(from) })
+  }
+  if (!patch.trim() && !files.length) return null
+  const names = new Set(status.trim().split('\n').map((l) => l.slice(3).trim()).filter(Boolean))
+  for (const f of files) names.add(f.rel)
+  return { patch, files, names: [...names] }
+}
+
+export function carryUncommitted(dir, carried) {
+  if (!carried) return 0
+  if (carried.patch.trim()) {
+    const r = spawnSync('git', ['-C', dir, 'apply', '--binary', '--whitespace=nowarn', '-'], { input: carried.patch, windowsHide: true, encoding: 'utf8', timeout: 30000, env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+    if (r.status !== 0) throw new Error(`the tracked changes did not apply: ${String(r.stderr ?? '').trim().slice(0, 200)}`)
+  }
+  for (const f of carried.files) {
+    const to = join(dir, f.rel)
+    mkdirSync(dirname(to), { recursive: true })
+    writeFileSync(to, f.data)
+  }
+  return (carried.names ?? []).length
+}
+
+// The cards waiting on a human, for the terminals verdict to read (redesign
+// C.5): `card 3e1c has waited on you for 12 minutes.` needs the id, the title,
+// the station and the moment it stopped, so a bare count cannot write the
+// sentence the spec asks for. The oldest one is `first`, because that is the
+// one the sentence names.
+// Cached for a beat: listCards() reads one file per card, and this is computed
+// on every sessions push.
+const CARDS_WAITING_TTL = 5000
+const WAITING_STATUSES = ['needs_approval', 'waiting_human']
+let cardsWaitingCache = { at: 0, data: null }
+function cardsWaiting() {
+  if (cardsWaitingCache.data && Date.now() - cardsWaitingCache.at < CARDS_WAITING_TTL) return cardsWaitingCache.data
+  let waiting = []
+  try { waiting = listCards().filter((c) => WAITING_STATUSES.includes(c.status)) } catch { waiting = [] }
+  // `updated_at` is when the card reached this state, which is what "has
+  // waited on you for 12 minutes" measures from
+  waiting.sort((a, b) => (String(a.updated_at ?? '') < String(b.updated_at ?? '') ? -1 : 1))
+  const first = waiting[0] ?? null
+  const data = {
+    count: waiting.length,
+    first: first ? { id: first.card_id, title: first.title ?? null, station: first.station ?? null, since: first.updated_at ?? null } : null,
+  }
+  cardsWaitingCache = { at: Date.now(), data }
+  return data
+}
+
+// `events` is the card's ledger, already read by the caller. readEvents() does
+// a readdir, a full readFileSync, a JSON.parse per line and a sort every call,
+// and this function needed it three times per push (the last event, the legs
+// that started at a finished station, and the test/land outcomes of a live
+// card) on the one event loop the board serves every request from. Read once,
+// reused; a caller that has no events passes none and pays for one read.
+export function summarize(card, events = null) {
   const st = (card.pipeline ?? []).find((s) => s.name === card.station) ?? null
-  const last = lastEventOf(card.card_id)
+  // `cards.map(summarize)` would hand this the array index, so the type is
+  // checked rather than the emptiness
+  const evs = Array.isArray(events) ? events : readEvents(card.card_id)
+  const last = evs.length ? evs[evs.length - 1] : null
   const runs = readRuns(card.card_id)
   const activeRun = runs.find((r) => ['launching', 'running'].includes(r.status)) ?? null
   // Once a station is over (done/failed) card.leg is reset, so the rail is
   // rebuilt from the legs that actually started at this station.
   const terminal = ['done', 'failed', 'killed'].includes(card.status)
   const startedLegs = terminal && st?.kind === 'agent'
-    ? readEvents(card.card_id).filter((ev) => ev.type === 'leg_started' && ev.station === card.station).map((ev) => ev.leg)
+    ? evs.filter((ev) => ev.type === 'leg_started' && ev.station === card.station).map((ev) => ev.leg)
     : []
   const lastLeg = startedLegs.length ? Math.max(...startedLegs) : card.leg
   // card.leg is reset when the station ends, so a finished card read its adapter
@@ -101,12 +282,23 @@ export function summarize(card) {
     if (i > card.leg) return 'pending'
     return ['running', 'handing_off'].includes(card.status) ? 'active' : 'pending'
   }
+  // What a live card is carrying right now: the diff it has built, the last
+  // test verdict, the last land verdict, and the rung it is on. Measured only
+  // for a card that is still going: a finished one is a single line in the
+  // ledger, and a git subprocess for each of ten of those buys nothing (C.1).
+  const live = NON_TERMINAL.includes(card.status)
+  const work = live ? workFor(card) : null
+  const outcomes = live ? cardOutcomes(evs) : {}
   return {
     ...card,
     column: columnOf(card),
     station_kind: st?.kind ?? null,
     active_adapter: entry?.adapter ?? null,
     active_mode: entry?.mode ?? null,
+    ...(work ? { work } : {}),
+    ...(outcomes.tests ? { tests: outcomes.tests } : {}),
+    ...(outcomes.land ? { land: outcomes.land } : {}),
+    ...(live && entry ? { agent_model: { agent: entry.adapter ?? null, model: entry.model ?? null } } : {}),
     chain_view: st?.kind === 'agent' ? st.chain.map((e, i) => ({
       adapter: e.adapter, mode: e.mode ?? null, approve: Boolean(e.approve),
       // a leg before the last one ended in a handoff (only the last leg can complete a station)
@@ -293,8 +485,18 @@ function trunkFor(repo) {
   const hit = trunkCache.get(repo)
   if (hit && Date.now() - hit.at < 15000) return hit.data
   const g = (args) => { const r = spawnSync('git', args, { cwd: repo, windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } }); return r.status === 0 ? r.stdout.trim() : null }
+  // The branch this repo actually calls its trunk: origin's default if there is
+  // one, then the usual names, then whatever this checkout is on. A repo whose
+  // default is `develop` used to read as "main" here, and the board's one-line
+  // entry then posted a card against a branch that does not exist.
   let branch = null
-  for (const b of ['main', 'master', 'trunk']) if (g(['rev-parse', '--verify', '--quiet', b]) !== null) { branch = b; break }
+  const originHead = g(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])
+  if (originHead) {
+    const name = originHead.replace(/^origin\//, '')
+    if (name && g(['rev-parse', '--verify', '--quiet', `refs/heads/${name}`]) !== null) branch = name
+  }
+  if (!branch) for (const b of ['main', 'master', 'trunk']) if (g(['rev-parse', '--verify', '--quiet', b]) !== null) { branch = b; break }
+  if (!branch) branch = g(['symbolic-ref', '--short', 'HEAD']) || null
   const log = branch ? g(['log', '--format=%h%x1f%s%x1f%cr%x1f%an', '-6', branch]) : null
   const data = {
     repo, repo_name: repo.split(/[\\/]/).filter(Boolean).pop(), branch,
@@ -319,14 +521,28 @@ function withLandings(t, landings) {
 // What another human sees of a terminal that is not theirs: that it is there,
 // nothing it has said, read or written. No task, no paths, no file names, no
 // limit text, no bundle, no events.
+// No usage either. `limits` is the five-hour and seven-day percentage of this
+// machine's login, written onto the record by the poller and by every claude
+// status line, and `warning` carries the same percentage with the clock it
+// resets on. Both are the number the capacity drawer, the accounts payload and
+// guestReason all withhold, so neither may ride out on a row instead
+// (.design/BOARD-DESIGN.md 6.13). The band survives, the figure does not.
 function redactSession(s) {
   return {
     session_id: s.session_id, agent: s.agent, account: s.account, status: s.status, active: s.active,
     started_at: s.started_at, elapsed_ms: s.elapsed_ms, turns: s.turns, repo_name: s.repo_name, branch: s.branch,
-    owner: s.owner ?? null, limits: s.limits ?? null, lineage: s.lineage ?? null,
-    warning: s.warning ? { window: s.warning.window, pct: s.warning.pct, resets_at: s.warning.resets_at } : null,
-    limit: s.limit ? { reason: s.limit.reason, resets_at: s.limit.resets_at ?? null } : null,
-    waiting: s.waiting ?? null,
+    owner: s.owner ?? null, lineage: s.lineage ?? null,
+    warning: s.warning ? { window: s.warning.window } : null,
+    limit: s.limit ? { reason: s.limit.reason } : null,
+    // `ahead` is owner-only for the same reason `files` is: how far someone
+    // else's branch has moved is a fact about their work, and the register
+    // prints it beside the dirty count that is already withheld here.
+    // `waiting` and `model` are owner-only, and a guest keeps both on their own
+    // terminal (that row is not redacted at all). On someone else's row they are
+    // dropped: `waiting` carries either the verbatim question an agent asked —
+    // the prompt text this function exists to hide — or a reset time, which is
+    // this machine's usage data (.design/BOARD-DESIGN.md 6.13); and `model` is
+    // which of this machine's model buckets someone else's work is spending.
     worktree: s.worktree ? { branch: s.worktree.branch, base: s.worktree.base } : null,
     // the branch is already on the worktree chip: naming it again costs nothing
     // and is what the board's land line reads
@@ -338,6 +554,48 @@ function redactSession(s) {
   }
 }
 
+// A guest's OWN terminal is not redacted: it is their work. The login it runs
+// on is still this machine's, though, and every figure on the record that was
+// measured from the owner's accounts is the same secret `capacity`, `buckets`
+// and the accounts payload already withhold: the two window percentages
+// (`limits`), the near-wall warning, the reset clock on a limit or an all-out
+// wait, and the name of the reading source. The row keeps every fact about the
+// work and loses every figure about the login (.design/BOARD-DESIGN.md 6.13).
+function scrubOwnerUsage(s) {
+  const out = { ...s }
+  delete out.limits
+  delete out.all_out
+  delete out.usage_source
+  delete out.usage_error
+  // the band survives, the figure and the clock do not: their own row may say
+  // it is near a wall, the same way a redacted row does
+  if (out.warning) out.warning = { window: out.warning.window }
+  if (out.limit) out.limit = { ...out.limit, resets_at: null }
+  // a 'reset' wait is a reset time with a sentence around it; the guest still
+  // learns that their terminal is waiting for one
+  if (out.waiting && out.waiting.type === 'reset') out.waiting = { type: 'reset', since: out.waiting.since ?? null }
+  return out
+}
+
+// The usage poller appends `claude usage unavailable since 9:03 AM: <reason>`
+// to every active session of a login, a guest's own terminal included
+// (src/usage-poll.mjs). That line is the owner's reading — the reason their
+// endpoint is refusing and the clock it started — so it leaves with the rest of
+// the figures scrubOwnerUsage withholds. The recovery line says nothing about
+// the login and stays.
+const isUsageFailureEvent = (e) => e?.type === 'status' && /^\w+ usage unavailable since /.test(String(e?.summary ?? ''))
+
+// A guest owns their own terminal, so its picker rows are theirs to read, but
+// a rung's reason can quote this machine's usage ("at 63%, not below 80%",
+// "past your 10% reserve"), and a percentage of this machine's login belongs to
+// nobody else (.design/BOARD-DESIGN.md 6.13). Only the reasons that say nothing
+// about how much is left survive the crossing.
+const GUEST_REASONS = new Set(['not installed on this machine', 'at its usage limit', 'shares the window that is out, buys nothing', 'refused for this hand-off'])
+function guestReason(reason) {
+  if (!reason) return null
+  return GUEST_REASONS.has(reason) ? reason : 'not available right now'
+}
+
 function visibleSessionFile(file) {
   const value = String(file ?? '')
   return !value.includes('*** Begin Patch') && !value.includes('*** End Patch')
@@ -353,13 +611,24 @@ export function sessionsView({ viewer = null, share = null } = {}) {
   const list = reapLost(listSessions())
   const ov = overlaps(list)
   const configuredAccounts = readAccounts()
+  // the spending rules the picker has to print, read once for the whole view
+  const prefs = readPreferences()
   const sessions = list.map((s) => {
     const land = readLand(s.session_id)
     const handoffOrder = normalizeHandoffOrder(s.handoff_order)
-    const chain = candidates({ agent: s.agent, account: s.account, accounts: configuredAccounts, order: handoffOrder })
+    // this terminal's own ladder, else the long-hand form of its order
+    const handoffLadder = ladderFor(s)
+    const from = { agent: s.agent, account: s.account, model: s.model ?? null }
+    const chain = candidates({ agent: s.agent, account: s.account, model: s.model ?? null, accounts: configuredAccounts, order: handoffOrder, ladder: handoffLadder })
     const preferredNext = chain[0] ?? null
     const availabilityKnown = Boolean(s.installed)
-    const eligibleNext = availabilityKnown ? (chain.find((next) => s.installed[next.agent] !== false && isAvailable(readUsage(next.agent, next.account))) ?? null) : null
+    // one pass, the same one the chooser makes, so a greyed row in the picker
+    // and the rung an automatic hand-off would take can never disagree. The
+    // picker is a human pressing a button, so the reserve is a note here, not
+    // a refusal (B.3).
+    const rungs = evaluateLadder({ from, list: chain, installed: availabilityKnown ? s.installed : null, maySpend: prefs.may_spend, reserve: prefs.reserve, automatic: false, climbBack: prefs.climb_back, ladder: handoffLadder })
+    const open = availabilityKnown ? rungs.find((r) => r.ok) : null
+    const eligibleNext = open ? { agent: open.agent, account: open.account, ...(open.model ? { model: open.model } : {}) } : null
     const can = s.worktree ? canLandFor(s) : { ok: false, blockers: [{ code: 'no_worktree', message: 'this terminal works in the checkout itself: there is no branch of its own to land', fix: null }] }
     return {
       ...s,
@@ -370,19 +639,38 @@ export function sessionsView({ viewer = null, share = null } = {}) {
       // every destination this terminal could be handed to, each with the
       // reason it cannot be picked right now. The board's picker renders this
       // list directly, so a greyed option always carries its own explanation.
-      handoff_targets: chain.map((c) => {
-        const u = readUsage(c.agent, c.account)
-        const missing = availabilityKnown && s.installed[c.agent] === false
-        const walled = !isAvailable(u)
-        return {
-          agent: c.agent,
-          account: c.account,
-          available: !missing && !walled,
-          reason: missing ? 'not installed on this machine' : walled ? 'at its usage limit' : null,
-          resets_at: walled && !guest ? (u.limited_until ?? null) : null,
-        }
-      }),
+      // one row per RUNG now: `claude/opus` and `claude/sonnet` are separate
+      // destinations, each with what it costs, whether it keeps the
+      // conversation, and the reason it cannot (or should not) be picked.
+      handoff_targets: rungs.map((r) => ({
+        agent: r.agent,
+        account: r.account,
+        model: r.model ?? null,
+        available: r.ok,
+        // A row that CAN be picked has nothing to explain: the reserve and the
+        // `below:N` rules come back as a note on an ok row (usage.mjs), and
+        // generalising that note reads as a refusal beside a button that works.
+        // A row that is blocked keeps a reason a guest may read.
+        reason: guest ? (r.ok ? null : guestReason(r.reason)) : r.reason,
+        resets_at: !guest ? (r.resets_at ?? null) : null,
+        // the probe in fixtures/live/claude/resume-model-probe.json: a claude
+        // downshift resumes the same conversation; everything else is primed
+        // from the bundle, codex included until its own resume is observed
+        keeps_conversation: Boolean(isDownshift(from, r) && r.agent === 'claude' && s.agent_session_id),
+        // the cost word is not static: `credits` on a claude/fable rung means
+        // this machine's login has usage credits switched on (preferences.mjs
+        // rungCost reads extra_usage.enabled), which is a fact about the
+        // owner's account that the accounts payload drops on purpose. A guest
+        // gets the row and not the word.
+        ...(guest ? {} : { cost: r.cost }),
+      })),
       handoff_availability_known: availabilityKnown,
+      handoff_ladder: handoffLadder,
+      // the bucket that will actually stop this terminal, computed per request
+      // and never persisted: it depends on the model the row is running, and
+      // the record only knows the login. A guest never gets it: it is a
+      // percentage of this machine's usage (.design/BOARD-DESIGN.md 6.13).
+      ...(guest ? {} : { capacity: binding(readUsage(s.agent, s.account), s.model ?? null) }),
       can_edit_handoff_order: s.runtime_capabilities?.includes(HANDOFF_ORDER_CAPABILITY) ?? false,
       active: isActive(s),
       has_synthesis: hasRecentSynthesis(s),
@@ -401,7 +689,15 @@ export function sessionsView({ viewer = null, share = null } = {}) {
   const accounts = []
   for (const agent of Object.keys(configuredAccounts)) for (const account of configuredAccounts[agent]) {
     const u = readUsage(agent, account)
-    accounts.push({ agent, account, five_hour: u.five_hour, seven_day: u.seven_day, limited_until: u.limited_until, limited_reason: u.limited_reason, source: u.source, observed_at: u.observed_at, updated_at: u.updated_at, stale: usageIsStale(u), live: sessions.filter((s) => s.active && s.agent === agent && s.account === account).length })
+    // buckets, walls, extra_usage and facts are owner-only for the same reason
+    // the percentages are: they say how much of this machine's login is gone.
+    // The guest branch at the bottom of this function drops the slot to
+    // {agent, account, live, shared}, so nothing here reaches them.
+    // `error`/`error_since` are the READING's health, not the login's: they say
+    // the board could not ask, which is why a percentage is old. Owner-only for
+    // the same reason the percentages are, and dropped by the guest branch below
+    // with the rest of the slot.
+    accounts.push({ agent, account, five_hour: u.five_hour, seven_day: u.seven_day, limited_until: u.limited_until, limited_reason: u.limited_reason, source: u.source, observed_at: u.observed_at, updated_at: u.updated_at, stale: usageIsStale(u), live: sessions.filter((s) => s.active && s.agent === agent && s.account === account).length, buckets: u.buckets ?? [], walls: u.walls ?? {}, extra_usage: u.extra_usage ?? null, facts: u.facts ?? null, error: u.error ?? null, error_since: u.error_since ?? null })
   }
   const repos = new Map()
   for (const s of sessions) if (s.repo && (s.active || s.worktree) && !repos.has(canonPath(s.repo))) repos.set(canonPath(s.repo), s.repo)
@@ -410,7 +706,11 @@ export function sessionsView({ viewer = null, share = null } = {}) {
   const landingsFor = (key) => landings.filter((l) => { if (!canon.has(l.repo)) canon.set(l.repo, canonPath(l.repo)); return canon.get(l.repo) === key })
   const trunk = [...repos].map(([key, r]) => { try { return withLandings(trunkFor(r), landingsFor(key)) } catch { return { repo: r, commits: [] } } })
   const mine = (s) => !shared || !viewer || viewer.role === 'owner' || (s.owner ?? share.owner) === viewer.name
-  const shown = sessions.map((s) => (mine(s) ? { ...s, requests: readRequests(s.session_id).filter((r) => r.state === 'pending') } : redactSession(s)))
+  const shown = sessions.map((s) => {
+    if (!mine(s)) return redactSession(s)
+    const row = { ...s, requests: readRequests(s.session_id).filter((r) => r.state === 'pending') }
+    return guest ? scrubOwnerUsage(row) : row
+  })
   return {
     sessions: shown,
     // a guest sees which accounts exist and which are busy, never how much of
@@ -421,6 +721,12 @@ export function sessionsView({ viewer = null, share = null } = {}) {
     // a guest sees what landed, not where the repo lives on this machine
     trunk: guest ? trunk.map((t) => ({ repo_name: t.repo_name, branch: t.branch, commits: t.commits ?? [] })) : trunk,
     you: viewer,
+    // the terminals verdict has to be able to say "card 3e1c has waited on you
+    // for 12 minutes" without reading the whole pipeline board (redesign C.5).
+    // A guest has no cards at all; an operator runs them, approves them and is
+    // exactly the human one can be waiting on, so the gate is the cards
+    // permission the /api/cards routes use, not the owner flag.
+    ...(!shared || mayUseCards(viewer?.role ?? 'owner') ? { cards_waiting: cardsWaiting() } : {}),
     share: { on: shared, bind: shared ? share.bind : null, people: shared ? share.people.length : 0 },
     preferences: guest ? null : readPreferences(),
     ts: new Date().toISOString(),
@@ -488,7 +794,7 @@ function createSse({ healthIntervalMs = 10000, debounceMs = 30, sessionsDebounce
     if (!card) { for (const c of clients) c.sig.delete(id); broadcast('removed', forOwner({ card_id: id })); return }
     const events = readEvents(id)
     // broadcast() refreshes each client's viewer (and drops revoked ones) first
-    broadcast('card', forOwner(summarize(card)))
+    broadcast('card', forOwner(summarize(card, events)))
     for (const c of [...clients]) {
       if (!c.viewer || !mayUseCards(c.viewer.role)) { c.sig.set(id, events.length); continue }
       const from = c.sig.get(id) ?? 0
@@ -611,8 +917,25 @@ function createSse({ healthIntervalMs = 10000, debounceMs = 30, sessionsDebounce
   return { add, stop, broadcast, clients }
 }
 
+// Which logins this board reads usage for. LEG_CLAUDE_BIN and LEG_GROK_BIN say
+// where a CLI lives, not that its login is fake, and gating on them switched
+// every percentage, every 5h/7d number and every usage_error off for a user
+// whose claude simply lives somewhere Leg's resolver does not look — with
+// nothing on the board to say why. codex is the one agent whose binary the
+// poller really needs, because it spawns the app-server to ask it; a stub there
+// cannot answer, so codex alone is skipped on its BIN var. A suite that must
+// reach no endpoint at all says so in one variable, LEG_NO_USAGE_POLL=1
+// (test/helpers.mjs sets it for every spawned board), and an injected fetcher
+// always wins: a test that supplied a reader is asking for it to be used.
+export function usageAgentsFor({ env = process.env, injected = {} } = {}) {
+  const set = (name) => env[`LEG_${name}`] || env[`BATON_${name}`]
+  const off = set('NO_USAGE_POLL') === '1'
+  const stubbedCodex = Boolean(set('CODEX_BIN'))
+  return USAGE_AGENTS.filter((a) => injected[a] || (!off && !(a === 'codex' && stubbedCodex)))
+}
+
 // ---- the server ----
-export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN || process.env.BATON_TOKEN || '', scheduler = (process.env.LEG_NO_SCHEDULER || process.env.BATON_NO_SCHEDULER) !== '1', share, usagePolling = false, usageReader = readCodexUsage } = {}) {
+export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN || process.env.BATON_TOKEN || '', scheduler = (process.env.LEG_NO_SCHEDULER || process.env.BATON_NO_SCHEDULER) !== '1', share, usagePolling = false, usageReader = readCodexUsage, usageFetchers = {} } = {}) {
   // An explicit `share` (tests) is fixed; the real server passes none and reads
   // share.json from disk, re-reading it per request (mtime-cached) so `leg
   // share add|rotate|rm` takes effect on a live board — a new link works at
@@ -655,28 +978,63 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
     return null
   }
   const sse = createSse({ viewFor, reauth: reauthClient })
-  let sched = null
-  let usageTimer = null
-  let usageController = null
-  let usageInFlight = null
-  const refreshCodexAccounts = () => {
-    if (!usagePolling || ((process.env.LEG_CODEX_BIN || process.env.BATON_CODEX_BIN) && usageReader === readCodexUsage) || usageInFlight) return usageInFlight
-    usageController = new AbortController()
-    const signal = usageController.signal
-    usageInFlight = Promise.all((readAccounts().codex ?? ['default']).map(async (account) => {
-      const codexHome = envFor('codex', account).CODEX_HOME || LAYOUT.codex.home()
-      const r = await usageReader({ codexHome, timeoutMs: 8000, signal })
-      if (!r.ok) return false
-      recordUsage('codex', account, r.limits, 'codex app-server account/rateLimits/read', { observed_at: r.observed_at, available: r.available })
-      return true
-    })).then((changed) => {
-      if (changed.some(Boolean)) sse.broadcast('sessions', (viewer) => viewFor(viewer))
-    }).catch((err) => log(`codex usage refresh: ${err.message}`)).finally(() => {
-      usageInFlight = null
-      usageController = null
-    })
-    return usageInFlight
+  // A card that adopted a live terminal's checkout waits in the backlog until
+  // that terminal has really stopped. `end` is a REQUEST: src/attach.mjs reads
+  // control.json on its own poll (2s by default) and kills the child at the
+  // next tick, while the scheduler ticks every second, so a card queued here
+  // would put a headless agent in the same working tree as the interactive one
+  // for at least a tick, and longer if the agent is mid-turn. The session
+  // record is how the board learns a terminal ended (attach writes `ended`,
+  // sessions.mjs reaps a lost one), so that is what this waits on.
+  const ENQUEUE_POLL_MS = Math.max(50, Number(process.env.LEG_END_AS_CARD_POLL_MS || process.env.BATON_END_AS_CARD_POLL_MS || 500))
+  const ENQUEUE_WAIT_MS = Math.max(1000, Number(process.env.LEG_END_AS_CARD_WAIT_MS || process.env.BATON_END_AS_CARD_WAIT_MS || 600000))
+  const enqueueTimers = new Map()
+  function enqueueWhenSessionEnds(cardId, sessionId, who) {
+    const from = Date.now()
+    const arm = () => {
+      const t = setTimeout(tick, ENQUEUE_POLL_MS)
+      t.unref?.()
+      enqueueTimers.set(cardId, t)
+    }
+    const tick = () => {
+      enqueueTimers.delete(cardId)
+      const card = readCard(cardId)
+      // killed, removed, or started by hand: it is not this timer's any more
+      if (!card || card.status !== 'backlog') return
+      const s = readSession(sessionId)
+      if (!s || !isActive(s)) {
+        try {
+          const next = humanAction(cardId, 'enqueue', {}, who)
+          log(`end-as-card ${cardId}: terminal ${sessionId} has stopped, the card is queued`)
+          sse.broadcast('card', forOwner(summarize(next)))
+        } catch (err) { log(`end-as-card ${cardId}: ${err.message}`) }
+        return
+      }
+      if (Date.now() - from > ENQUEUE_WAIT_MS) {
+        // never start it behind the human's back after a long wait: say why it
+        // is sitting there and leave Run to them
+        try { ledgerAppend(cardId, { actor: who, type: 'blocked_by', summary: `terminal ${sessionId} has not stopped, so this card is still in the backlog; press Run once it has` }) } catch { /* the log line below is the record */ }
+        log(`end-as-card ${cardId}: terminal ${sessionId} still active after ${Math.round(ENQUEUE_WAIT_MS / 1000)}s, left in the backlog`)
+        return
+      }
+      arm()
+    }
+    arm()
   }
+  let sched = null
+  // ---- usage polling: one poller per LOGIN, not one per terminal ----
+  // The terminals used to ask their agent's endpoint once a minute each, so a
+  // login with three of them drew three times the requests and three copies of
+  // every 429 (src/usage-poll.mjs). The board asks once per login, backs off on
+  // a failure, and pushes what it read onto that login's active sessions.
+  const usageFetchersFor = { codex: usageReader, ...usageFetchers }
+  const injectedUsage = { codex: usageReader !== readCodexUsage, claude: Boolean(usageFetchers.claude), grok: Boolean(usageFetchers.grok) }
+  const usagePollers = createUsagePollers({
+    agents: usageAgentsFor({ injected: injectedUsage }),
+    fetchers: usageFetchersFor,
+    onChange: () => sse.broadcast('sessions', (viewer) => viewFor(viewer)),
+    onLog: (msg) => log(msg),
+  })
 
   async function handle(req, res) {
     const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`)
@@ -719,7 +1077,7 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
     const canMachine = !shared || mayUseMachine(viewer.role)
     const ownsSession = (s) => !shared || viewer.role === 'owner' || (s.owner ?? share.owner) === viewer.name
     const parts = path.split('/').filter(Boolean) // ['api', ...]
-    if (!canCards && ['cards', 'floor', 'presets', 'adapters', 'leases'].includes(parts[1])) return send(res, 403, { error: 'the pipeline board belongs to the owner and the operators of this machine' })
+    if (!canCards && ['cards', 'floor', 'presets', 'adapters', 'leases', 'models'].includes(parts[1])) return send(res, 403, { error: 'the pipeline board belongs to the owner and the operators of this machine' })
     if (!canMachine && ['trunk', 'history', 'worktrees', 'audit'].includes(parts[1])) return send(res, 403, { error: 'this is the map of the machine itself: every repository path and every conversation on it. It belongs to the owner of this machine.' })
     try {
       if (req.method === 'GET' && path === '/api/health') {
@@ -730,14 +1088,22 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
       }
       if (req.method === 'GET' && path === '/api/adapters') return send(res, 200, { adapters: await adaptersInfo() })
       if (req.method === 'GET' && path === '/api/presets') return send(res, 200, { presets: PRESETS })
+      // Which models this machine can start each agent on (src/models.mjs).
+      // Sits beside /api/adapters because it answers the second half of the
+      // same question — an adapter says WHO can run, this says WHAT it runs as
+      // — and it is guarded the same way: a guest picking a model is a guest
+      // spending the owner's plan. Never waits on a child process: agy's and
+      // grok's lists come off an hourly cache and refresh behind the answer.
+      if (req.method === 'GET' && path === '/api/models') return send(res, 200, listModels())
       if (req.method === 'GET' && path === '/api/cards') {
         const cards = listCards()
-        return send(res, 200, { columns: columnsFor(cards), cards: cards.map(summarize) })
+        return send(res, 200, { columns: columnsFor(cards), cards: cards.map((c) => summarize(c)) })
       }
       if (req.method === 'POST' && path === '/api/cards') {
         const body = await readBody(req)
         try {
-          const card = await createCard(body, actor)
+          // a pipeline that names a file is a CLI flag, never a request body
+          const card = await createCard(body, actor, { allowPipelineFile: false })
           sse.broadcast('card', forOwner(summarize(card)))
           return send(res, 201, { card: summarize(card) })
         } catch (err) {
@@ -748,7 +1114,7 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
       if (req.method === 'GET' && path === '/api/events') {
         res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive', 'X-Accel-Buffering': 'no' })
         const cards = canCards ? listCards() : []
-        res.write(`event: hello\ndata: ${JSON.stringify({ columns: columnsFor(cards), cards: cards.map(summarize), sessions: viewFor(viewer), ts: new Date().toISOString() })}\n\n`)
+        res.write(`event: hello\ndata: ${JSON.stringify({ columns: columnsFor(cards), cards: cards.map((c) => summarize(c)), sessions: viewFor(viewer), ts: new Date().toISOString() })}\n\n`)
         sse.add(res, cards, viewer, { token: presentedToken(req, url), loopback: isLoopbackRequest(req) })
         return
       }
@@ -761,6 +1127,15 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
           try {
             const patch = {}
             if (body.handoff_order !== undefined) patch.handoff_order = requireHandoffOrder(body.handoff_order)
+            // the ladder and the rules around it (B.3). `handoff_order` is
+            // rewritten from the ladder inside writePreferences, so the two
+            // keys on disk can never disagree.
+            if (body.handoff_ladder !== undefined) patch.handoff_ladder = requireHandoffLadder(body.handoff_ladder)
+            if (body.climb_back !== undefined) patch.climb_back = requireClimbBack(body.climb_back)
+            if (body.may_spend !== undefined) patch.may_spend = Boolean(body.may_spend)
+            if (body.reserve !== undefined) patch.reserve = requireReserve(body.reserve)
+            if (body.notify_terminal !== undefined) patch.notify_terminal = Boolean(body.notify_terminal)
+            if (body.notify_board !== undefined) patch.notify_board = Boolean(body.notify_board)
             if (body.harness !== undefined) {
               // the board may narrow the policy or turn the feature off; turning
               // it on is the first-run consent flow, which shows what will be
@@ -771,7 +1146,7 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
               if (body.harness?.policy !== undefined && rank.indexOf(body.harness.policy) > rank.indexOf(current.policy)) return send(res, 400, { error: `the board may only narrow the harness policy (now ${current.policy}); widen it from a terminal: leg harness policy ${body.harness.policy}` })
               patch.harness = { policy: body.harness?.policy, enabled: body.harness?.enabled === false ? false : undefined }
             }
-            if (!Object.keys(patch).length) return send(res, 400, { error: 'nothing to change: send handoff_order or harness' })
+            if (!Object.keys(patch).length) return send(res, 400, { error: 'nothing to change: send handoff_ladder, handoff_order, climb_back, may_spend, reserve, notify_terminal, notify_board or harness' })
             const preferences = writePreferences(patch)
             sse.broadcast('sessions', (v) => viewFor(v))
             return send(res, 200, { preferences })
@@ -820,11 +1195,32 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
           sse.broadcast('sessions', (v) => viewFor(v))
           return send(res, 200, { ok: true, request: hit })
         }
-        if (req.method === 'GET' && parts.length === 3) return send(res, 200, { session: sess, events: readSessionEvents(id), requests: readRequests(id) })
+        // A guest owns their own terminal, so this route hands them the record
+        // verbatim — including the two window percentages, the reading source
+        // and the poller's usage_error, every one of which the LIST route
+        // scrubs (`scrubOwnerUsage`, sessionsView). One GET of their own
+        // session id was the whole share boundary walked around. The same scrub
+        // runs here, and the poller's failure line is kept off their timeline:
+        // it names the owner's reason and the clock it started.
+        if (req.method === 'GET' && parts.length === 3) {
+          const asGuest = shared && viewer.role !== 'owner'
+          const events = readSessionEvents(id)
+          return send(res, 200, {
+            session: asGuest ? scrubOwnerUsage(sess) : sess,
+            events: asGuest ? events.filter((e) => !isUsageFailureEvent(e)) : events,
+            requests: readRequests(id),
+          })
+        }
         // the card's drawer: what the agent last said, what it changed, what it
         // has done. Only ever this viewer's own terminal; the guard above sent
         // anyone else away before we read a transcript.
-        if (req.method === 'GET' && parts[3] === 'detail') return send(res, 200, sessionDetail(sess))
+        if (req.method === 'GET' && parts[3] === 'detail') {
+          const detail = sessionDetail(sess)
+          // the drawer of a guest's OWN terminal is theirs; the poller's line
+          // about the owner's login is not (the same event the route above drops)
+          if (shared && viewer.role !== 'owner') detail.events = detail.events.filter((e) => !isUsageFailureEvent(e))
+          return send(res, 200, detail)
+        }
         if (req.method === 'GET' && parts[3] === 'diff') {
           try {
             return send(res, 200, sessionDiff(sess, url.searchParams.get('file') ?? ''))
@@ -842,7 +1238,13 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
           }
           const body = await readBody(req)
           try {
-            const order = requireHandoffOrder(body.handoff_order)
+            // one route, two shapes: the old list of agents, and the ladder of
+            // rungs that replaced it. Sending either rewrites the other, the
+            // same way preferences.json keeps them in step.
+            const ladder = body.handoff_ladder !== undefined ? requireHandoffLadder(body.handoff_ladder) : null
+            const order = ladder ? orderFromLadder(ladder) : requireHandoffOrder(body.handoff_order)
+            const rungs = ladder ?? ladderFor({ handoff_order: order })
+            const summary = ladder ? `handoff ladder changed to ${rungs.map((r) => rungLabel(r)).join(' → ')}` : `handoff order changed to ${order.join(' → ')}`
             const next = updateSession(id, (current) => {
               if (!['starting', 'running', 'warning', 'limit', 'waiting'].includes(current.status)) {
                 const conflict = new Error(`handoff order cannot change while this terminal is ${current.status}`)
@@ -851,9 +1253,10 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
               }
               return {
                 handoff_order: order,
-                chain: candidates({ agent: current.agent, account: current.account, accounts: readAccounts(), order }),
+                handoff_ladder: rungs,
+                chain: candidates({ agent: current.agent, account: current.account, model: current.model ?? null, accounts: readAccounts(), order, ladder: rungs }),
               }
-            }, { event: { type: 'status', by: actor.id, summary: `handoff order changed to ${order.join(' → ')}` } })
+            }, { event: { type: 'status', by: actor.id, summary } })
             sse.broadcast('sessions', (v) => viewFor(v))
             return send(res, 200, { session: next })
           } catch (err) {
@@ -889,6 +1292,107 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
           log(`land requested for ${id} by ${actor.id}`)
           return send(res, 202, { ok: true, requested: 'land' })
         }
+        // "I have to leave, keep going." The terminal's context becomes a card
+        // that continues from the SAME rung, and the terminal then ends exactly
+        // the way End ends it. Where the card works depends on what the
+        // terminal had:
+        //   - its own worktree: the card adopts it (redesign G4; two worktrees
+        //     on one branch is the conflict machine the roadmap rejects) and
+        //     waits in the BACKLOG until the terminal has really stopped, since
+        //     `end` is a request the runner reads on its own poll and the
+        //     scheduler ticks once a second.
+        //   - no worktree of its own (the ordinary case): a checkout of its own
+        //     is cut from that branch and the uncommitted work is carried into
+        //     it, so the card continues from what the human was looking at
+        //     rather than from the last commit.
+        if (req.method === 'POST' && parts[3] === 'end-as-card') {
+          // a card is the pipeline board, which belongs to the owner and the
+          // operators of this machine even when the terminal is the caller's
+          if (!canCards) return send(res, 403, { error: 'the pipeline board belongs to the owner and the operators of this machine' })
+          if (!isActive(sess)) return send(res, 409, { error: `session ${id} is not active` })
+          if (!sess.repo) return send(res, 409, { error: 'this terminal is not in a git repository, so there is no branch for a card to continue on' })
+          let bundle
+          try {
+            bundle = saveSessionBundle(sess, { messages: sessionMessages(sess), why: 'ended as a card' })
+          } catch (err) {
+            // nothing has been ended yet: refuse rather than end a terminal
+            // whose context was never written down
+            return send(res, 409, { error: `the hand-off bundle could not be written, so this terminal was left alone: ${scrub(err.message).slice(0, 200)}` })
+          }
+          const rungs = ladderFromCurrentRung(sess)
+          // one model per adapter is all a card's chain can carry, so a ladder
+          // with claude/fable and claude/opus in it keeps the FIRST, which is
+          // the rung this terminal is on
+          const models = {}
+          for (const r of rungs) if (r.model && !models[r.agent]) models[r.agent] = r.model
+          const task = `${sess.task ?? 'Continue the work already under way in this checkout.'}\n\nContinue from the bundle at ${bundle.path}.`
+          const adopted = sess.worktree?.path && existsSync(sess.worktree.path) ? sess.worktree.path : null
+          const trunkBranch = sess.worktree?.base || sess.branch || 'main'
+          // The checkout the human has been working in. Read BEFORE anything is
+          // created or ended: if the work cannot be read, nothing has happened
+          // yet and the terminal is left exactly as it was.
+          // the repository root, which is what `git status --porcelain`,
+          // `git diff` and `git ls-files` all report paths against, so the
+          // patch and the file list line up with the new checkout's root
+          const workRoot = adopted ?? ((sess.repo && existsSync(sess.repo)) ? sess.repo : sess.cwd)
+          let carried = null
+          if (!adopted) {
+            try { carried = captureUncommitted(workRoot) } catch (err) {
+              return send(res, 409, { error: `the uncommitted work in this checkout could not be read, so this terminal was left alone: ${scrub(err.message).slice(0, 200)}` })
+            }
+          }
+          let card
+          try {
+            card = await createCard({
+              repo: sess.repo, task,
+              chain: rungs.map((r) => r.agent).join(',') || sess.agent,
+              model: models,
+              trunk: trunkBranch,
+              title: sess.task ? String(sess.task).slice(0, 60) : `continued from ${id}`,
+              // never queued here: the card is enqueued below, once its
+              // checkout is its own and nothing else is writing to it
+              queue: false,
+            }, actor)
+          } catch (err) {
+            if (err instanceof CardInputError) return send(res, 400, { error: `the card could not be created, so this terminal was left alone: ${err.message}` })
+            throw err
+          }
+          let carriedFiles = 0
+          if (adopted) {
+            ledgerUpdate(card.card_id, { patch: { lineage: { from: id }, worktree: adopted, worktree_adopted: true, worktree_branch: sess.worktree?.branch ?? null } })
+          } else {
+            try {
+              const wt = ensureWorktree(sess.repo, card.card_id, { trunk: trunkBranch })
+              carriedFiles = carryUncommitted(wt.path, carried)
+              ledgerUpdate(card.card_id, { patch: { lineage: { from: id }, worktree: wt.path, worktree_branch: wt.branch } })
+            } catch (err) {
+              // nothing has been ended and nothing has been queued: take the
+              // half-made card off the board rather than leave it there
+              try { removeWorktree(sess.repo, card.card_id, { force: true }) } catch { /* it may never have been cut */ }
+              try { rmSync(cardDir(card.card_id), { recursive: true, force: true }) } catch { /* the board never saw it */ }
+              return send(res, 409, { error: `the work in this checkout could not be carried into a checkout of its own, so this terminal was left alone: ${scrub(err.message).slice(0, 200)}` })
+            }
+          }
+          // `handoff_written` is the ledger's word for "a bundle was written and
+          // the work moved on", which is exactly what happened here. The audited
+          // line with the actor is on the terminal's side, below.
+          const where = adopted
+            ? ', in the terminal\'s own worktree, once that terminal has stopped'
+            : `, in a worktree of its own cut from ${trunkBranch}${carriedFiles ? `, carrying ${carriedFiles} uncommitted file(s) over` : ''}`
+          ledgerAppend(card.card_id, { actor, type: 'handoff_written', summary: `continued from terminal ${id}${where}` })
+          requestControl(id, { end: true, by: actor.id })
+          appendSessionEvent(id, { type: 'handed_off', by: actor.id, summary: `${actor.id} ended this terminal and kept it going as card ${card.card_id}` })
+          updateSession(id, (cur) => ({ lineage: { ...(cur.lineage ?? {}), to: card.card_id } }))
+          if (adopted) enqueueWhenSessionEnds(card.card_id, id, actor)
+          else {
+            try { humanAction(card.card_id, 'enqueue', {}, actor) } catch (err) { log(`end-as-card ${card.card_id}: ${err.message}`) }
+          }
+          log(`end-as-card for ${id} by ${actor.id}: ${card.card_id}${adopted ? ` in ${adopted} (queued when ${id} stops)` : ` in a checkout of its own${carriedFiles ? `, ${carriedFiles} file(s) carried` : ''}`}`)
+          const next = summarize(readCard(card.card_id))
+          sse.broadcast('card', forOwner(next))
+          sse.broadcast('sessions', (v) => viewFor(v))
+          return send(res, 201, { card: next, bundle: { id: bundle.id, path: bundle.path }, carried: { files: carriedFiles, adopted: Boolean(adopted) } })
+        }
         if (req.method === 'POST' && (parts[3] === 'handoff' || parts[3] === 'end')) {
           if (!isActive(sess)) return send(res, 409, { error: `session ${id} is not active` })
           if (parts[3] === 'end') {
@@ -901,19 +1405,21 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
           const body = await readBody(req)
           let target = null
           if (body && body.agent !== undefined && body.agent !== null && body.agent !== '') {
-            const want = { agent: String(body.agent), account: String(body.account ?? 'default') }
+            const want = { agent: String(body.agent), account: String(body.account ?? 'default'), model: body.model ? String(body.model).toLowerCase() : null }
             const order = normalizeHandoffOrder(sess.handoff_order)
-            const chain = candidates({ agent: sess.agent, account: sess.account, accounts: readAccounts(), order })
-            const hit = chain.find((c) => c.agent === want.agent && c.account === want.account)
-            const label = `${want.agent}${want.account !== 'default' ? '/' + want.account : ''}`
-            if (!hit) return send(res, 400, { error: `${label} is not a destination for this terminal (${chain.map((c) => c.agent + (c.account !== 'default' ? '/' + c.account : '')).join(', ') || 'none'})` })
+            const ladder = ladderFor(sess)
+            const chain = candidates({ agent: sess.agent, account: sess.account, model: sess.model ?? null, accounts: readAccounts(), order, ladder })
+            const hit = chain.find((c) => c.agent === want.agent && c.account === want.account && (want.model ? (c.model ?? null) === want.model : true))
+            const label = rungLabel(want)
+            if (!hit) return send(res, 400, { error: `${label} is not a destination for this terminal (${chain.map((c) => rungLabel(c)).join(', ') || 'none'})` })
             if (sess.installed && sess.installed[want.agent] === false) return send(res, 409, { error: `${label} is not installed on this machine` })
             const u = readUsage(want.agent, want.account)
             if (!isAvailable(u)) return send(res, 409, { error: `${label} is at its usage limit until ${fmtReset(u.limited_until)}; pick another or use Hand off now without a destination` })
-            target = hit
+            if (hit.model && wallActive(u.walls?.[hit.model])) return send(res, 409, { error: `${label} is out until ${fmtReset(u.walls[hit.model].limited_until)}; pick another rung or use Hand off now without a destination` })
+            target = { agent: hit.agent, account: hit.account, ...(hit.model ? { model: hit.model } : {}) }
           }
           requestControl(id, target ? { handoff: true, target, by: actor.id } : { handoff: true, by: actor.id })
-          log(`handoff requested for ${id} by ${actor.id}${target ? ` to ${target.agent}/${target.account}` : ''}`)
+          log(`handoff requested for ${id} by ${actor.id}${target ? ` to ${rungLabel(target)}` : ''}`)
           return send(res, 200, { ok: true, requested: 'handoff', target })
         }
         if (req.method === 'DELETE' && parts.length === 3) {
@@ -1039,6 +1545,48 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
           sse.broadcast('removed', forOwner({ card_id: id }))
           return send(res, 200, { removed: id })
         }
+        // Take over: sit down in the card's worktree yourself. The card is
+        // paused first (its child is killed and its bundle written by the
+        // existing transition), then Leg hands back the one command that opens
+        // a terminal there. This is the only command the board ever hands a
+        // human, because a browser tab cannot open one (redesign C.4).
+        if (req.method === 'POST' && parts[3] === 'take-over') {
+          if (TERMINAL.includes(card.status)) return send(res, 409, { error: `card ${id} is ${card.status}: there is nothing running to take over. Rerun it, or open its worktree yourself.` })
+          const raw = String(summarize(card).active_adapter ?? '')
+          const agent = [raw, raw.replace(/^fake-/, '')].find((n) => SUPERVISED_AGENTS.includes(n)) ?? null
+          if (!agent) return send(res, 409, { error: `this card's current leg runs ${raw || 'no agent'}, which is not one of the agents leg can open a terminal for (${SUPERVISED_AGENTS.join(', ')})` })
+          // Every non-terminal status moves to `paused` before the command is
+          // handed back, not just `running`. A `queued` or `handing_off` card
+          // is in the set the scheduler starts from, and it ticks once a
+          // second: the human would paste this command into a worktree an
+          // agent had just been launched in, which is the collision Take over
+          // exists to prevent. The transition also writes the actor's own
+          // `taken_over` line, so the audit trail names who has the checkout.
+          let next
+          try { next = humanAction(id, 'take_over', {}, actor) } catch (err) {
+            if (err instanceof IllegalTransition) return send(res, 409, { error: err.message })
+            throw err
+          }
+          // A card that never ran has no checkout of its own, and the terminal
+          // that takes it over must never open in the human's main checkout
+          // (src/attach.mjs cardWorkRoot refuses that). Cut its worktree now, on
+          // the trunk the card would have used, so the command below has a
+          // place to open.
+          const cur = readCard(id) ?? next
+          if (!(cur.worktree && existsSync(cur.worktree)) && cur.repo) {
+            try {
+              const wt = ensureWorktree(cur.repo, id, { trunk: cur.trunk || trunkFor(cur.repo).branch || 'main' })
+              ledgerUpdate(id, { patch: { worktree: wt.path, worktree_branch: wt.branch } })
+            } catch (err) {
+              return send(res, 409, { error: `could not cut a checkout for ${id}: ${err.message}` })
+            }
+          }
+          const command = `leg ${agent} --resume-card ${id}`
+          log(`take-over for ${id} by ${actor.id}: ${command}`)
+          const view = summarize(readCard(id) ?? next)
+          sse.broadcast('card', forOwner(view))
+          return send(res, 200, { card: view, command })
+        }
         if (req.method === 'POST' && parts[3]) {
           const map = { run: 'enqueue', queue: 'enqueue', approve: 'approve', reassign: 'reassign', pause: 'pause', resume: 'resume', kill: 'kill', handoff: 'handoff_now', 'handoff-now': 'handoff_now', rerun: 'rerun' }
           const action = map[parts[3]]
@@ -1099,9 +1647,7 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
             sched.run().catch((err) => log(`scheduler crashed: ${err.message}`))
           }
           if (usagePolling) {
-            refreshCodexAccounts()
-            usageTimer = setInterval(refreshCodexAccounts, 60000)
-            usageTimer.unref?.()
+            usagePollers.start().catch((err) => log(`usage polling: ${err.message}`))
           }
           if (loopbackCompanion) {
             loopbackCompanion.on('error', (err) => log(`loopback companion: ${err.message}`))
@@ -1112,8 +1658,9 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
       })
     },
     async stop() {
-      if (usageTimer) { clearInterval(usageTimer); usageTimer = null }
-      usageController?.abort()
+      usagePollers.stop()
+      for (const t of enqueueTimers.values()) clearTimeout(t)
+      enqueueTimers.clear()
       sse.stop()
       if (sched) sched.stop()
       if (loopbackCompanion) await new Promise((r) => { loopbackCompanion.closeAllConnections?.(); loopbackCompanion.close(() => r()) })