@ucsandman/legcli 0.10.0 → 0.12.0

package/bin/leg.mjs

@@ -19,14 +19,17 @@ import { createScheduler, schedulerStatus, pidfile, MAX_CONCURRENT } from '../sr
 import { availableActions } from '../src/chain.mjs'
 import { up, down, stopBoard, status, openBoard } from '../src/launcher.mjs'
 import { attach, ensureBoard } from '../src/attach.mjs'
-import { readShare, addPerson, removePerson, rotate as rotateToken, turnOn, turnOff, linkFor, personNamed } from '../src/share.mjs'
+import { readShare, addPerson, removePerson, rotate as rotateToken, turnOn, turnOff, linkFor, personNamed, scheme, tlsConfigured, ROLES } from '../src/share.mjs'
+import { normalizeHandoffOrder, ladderFor, readPreferences, writePreferences } from '../src/preferences.mjs'
+import { MODEL_ALIASES } from '../src/buckets.mjs'
 import { SUPERVISED_AGENTS, listSessions, readSession, readEvents as readSessionEvents, requestControl, removeSession, isActive, readLand, sessionDir, appendEvent } from '../src/sessions.mjs'
-import { addAccount, removeAccount, listAccountRows, LAYOUT } from '../src/accounts.mjs'
-import { listUsage, fmtReset } from '../src/usage.mjs'
+import { addAccount, removeAccount, listAccountRows, readAccounts, LAYOUT } from '../src/accounts.mjs'
+import { listUsage, fmtReset, readUsage, isAvailable, candidates, binding, wallActive, evaluateLadder, rungLabel } from '../src/usage.mjs'
 import { home } from '../src/store.mjs'
 import { entitlement, allows, describe as describeLicense, activate as activateLicense, deactivate as deactivateLicense, refresh as refreshLicense, licensePath, BUY_URL } from '../src/license.mjs'
 import { resumeVerdict, bodyOf, ago } from '../src/resume.mjs'
 import { harnessCommand } from '../src/harness/cli.mjs'
+import { adapterCommand } from '../src/adapters/cli.mjs'
 import { historyCommand, worktreesCommand } from '../src/history/cli.mjs'
 
 const SRC = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'src')
@@ -71,13 +74,13 @@ async function cardAdd(args) {
 // start the next option in the same terminal. The payload is marked
 // simulated: it is never kept as live evidence, and the wall it records
 // clears after two minutes. codex has no Leg-owned input, so it is refused.
-function simulateLimit(s) {
+function simulateLimit(s, { message = null } = {}) {
   if (!isActive(s)) die(3, `session ${s.session_id} is not active`)
   if (['limit', 'handing_off'].includes(s.status)) die(3, `session ${s.session_id} is already ${s.status}`)
   if (s.agent === 'claude') {
     const payload = {
       hook_event_name: 'StopFailure', error: 'rate_limit', session_id: s.agent_session_id ?? undefined, transcript_path: s.transcript_path ?? undefined,
-      last_assistant_message: 'API Error: Rate limit reached (simulated by leg sessions simulate-limit)', leg_simulated: true, baton_simulated: true,
+      last_assistant_message: message ?? 'API Error: Rate limit reached (simulated by leg sessions simulate-limit)', leg_simulated: true, baton_simulated: true,
     }
     const r = spawnSync(process.execPath, [join(SRC, 'hook.mjs'), 'claude-hook', '--session', s.session_id], { input: JSON.stringify(payload), windowsHide: true, encoding: 'utf8', timeout: 15000 })
     if (r.status !== 0) die(1, `hook exited ${r.status}: ${(r.stderr || '').slice(0, 300)}`)
@@ -98,6 +101,96 @@ function simulateLimit(s) {
   die(2, `simulate-limit drives the claude hook path (and the agy/grok log); codex's wall comes from its own rollout file, which Leg never writes. Use "leg sessions handoff ${s.session_id}" to force the switch.`)
 }
 
+// `claude`, `claude/work`, `claude/opus`, `claude/work/opus`. Three parts are
+// unambiguous. Two are not, so the second is read as an account when that
+// account exists and as a model when the agent has one by that name; a word
+// that is neither is refused by name rather than guessed at.
+export function parseTarget(value, { die: fail = (code, msg) => { throw new Error(msg) } } = {}) {
+  const parts = String(value).split('/').filter(Boolean)
+  const agent = parts[0]
+  if (!agent) fail(2, 'usage: --to <agent>[/<account>[/<model>]]')
+  const models = MODEL_ALIASES[agent] ?? []
+  if (parts.length >= 3) return { agent, account: parts[1], model: parts[2].toLowerCase() }
+  if (parts.length === 2) {
+    const second = parts[1]
+    const accounts = readAccounts()[agent] ?? ['default']
+    if (accounts.includes(second)) return { agent, account: second, model: null }
+    if (models.includes(second.toLowerCase())) return { agent, account: 'default', model: second.toLowerCase() }
+    fail(2, `"${second}" is neither a ${agent} account (${accounts.join(', ')}) nor a ${agent} model (${models.join(', ') || 'none known'})`)
+  }
+  return { agent, account: 'default', model: null }
+}
+
+// What a rung is doing right now, in the words the board uses: the wall and its
+// clock, else the percentage of the bucket that binds it, else "no figure".
+// Never a guess: an agent that publishes no number says so.
+function rungState(rung) {
+  const u = readUsage(rung.agent, rung.account)
+  const wall = rung.model ? u.walls?.[rung.model] : null
+  if (wall && wallActive(wall)) return `${rung.model} out until ${fmtReset(wall.limited_until)}`
+  if (!isAvailable(u)) return `at its limit until ${fmtReset(u.limited_until)}`
+  const b = binding(u, rung.model ?? null)
+  if (b && Number.isFinite(b.percent)) return `${Math.round(b.percent)}% of the ${b.model ? b.model + ' ' : ''}${b.kind === 'session' || b.kind === 'five_hour' ? '5h' : 'week'} window`
+  return 'no figure'
+}
+
+function printLadder() {
+  const prefs = readPreferences()
+  const ladder = prefs.handoff_ladder
+  const rows = evaluateLadder({ from: null, list: ladder, maySpend: prefs.may_spend, reserve: prefs.reserve, automatic: true, climbBack: prefs.climb_back, ladder })
+  out('The ladder a terminal falls down when its login stops. Rung 1 first, every time.')
+  ladder.forEach((rung, i) => {
+    const r = rows[i]
+    const when = rung.when === 'always' ? '' : `  when ${rung.when}`
+    out(`  ${String(i + 1).padEnd(2)} ${rungLabel(rung).padEnd(20)} ${rungState(rung).padEnd(34)} ${r.ok ? 'ready' : r.reason}${when}`)
+  })
+  out('')
+  out(`spending: ${prefs.may_spend ? 'on (a credits or metered rung may be taken unattended)' : 'off (a credits or metered rung is skipped unattended)'} · leg ladder spend on|off`)
+  out(`climb back: ${prefs.climb_back === 'never' ? 'never (stay on the lower rung until you press Back)' : 'at the next hand-off'}`)
+  const reserve = Object.entries(prefs.reserve ?? {})
+  out(`reserve: ${reserve.length ? reserve.map(([a, p]) => `${a} ${p}%`).join(', ') : 'none'}`)
+  out(`order (what older readers see): ${prefs.handoff_order.join(' → ')}`)
+}
+
+function ladderCommand(cmd, args) {
+  if (!cmd || cmd === 'ls' || cmd === 'show') return printLadder()
+  const prefs = readPreferences()
+  const ladder = prefs.handoff_ladder.map((r) => ({ ...r }))
+  if (cmd === 'set') {
+    const [nRaw, target] = args._
+    const n = parseInt(nRaw, 10)
+    if (!Number.isFinite(n) || n < 1) die(2, 'usage: leg ladder set <n> <agent>[/<account>[/<model>]] [--when always|below:N|walled-only]')
+    if (!target) die(2, 'usage: leg ladder set <n> <agent>[/<account>[/<model>]] [--when always|below:N|walled-only]')
+    const want = parseTarget(target, { die })
+    const rung = { ...want, when: typeof args.when === 'string' ? args.when : 'always' }
+    const at = Math.min(n, ladder.length + 1) - 1
+    ladder[at] = rung
+    try {
+      const saved = writePreferences({ handoff_ladder: ladder })
+      out(`rung ${at + 1} is ${rungLabel(saved.handoff_ladder[at])}${rung.when !== 'always' ? `, when ${rung.when}` : ''}`)
+    } catch (err) { die(2, err.message) }
+    return printLadder()
+  }
+  if (cmd === 'rm') {
+    const n = parseInt(args._[0], 10)
+    if (!Number.isFinite(n) || n < 1 || n > ladder.length) die(2, `usage: leg ladder rm <n> (1..${ladder.length})`)
+    if (ladder.length === 1) die(2, 'that is the only rung left: a ladder with no rungs has nowhere to hand off to')
+    const [gone] = ladder.splice(n - 1, 1)
+    try { writePreferences({ handoff_ladder: ladder }) } catch (err) { die(2, err.message) }
+    out(`removed rung ${n}: ${rungLabel(gone)}`)
+    return printLadder()
+  }
+  if (cmd === 'spend') {
+    const v = args._[0]
+    if (!['on', 'off'].includes(v)) die(2, 'usage: leg ladder spend on|off')
+    const saved = writePreferences({ may_spend: v === 'on' })
+    return out(saved.may_spend
+      ? 'spending is ON: an unattended hand-off may take a rung that bills credits.'
+      : 'spending is OFF: an unattended hand-off skips any rung that bills credits, and says so in the ledger.')
+  }
+  die(2, `unknown ladder command "${cmd}" (ls|set <n> <agent>[/<account>[/<model>]]|rm <n>|spend on|off)`)
+}
+
 function fmtCard(c) {
   const st = c.pipeline?.find((s) => s.name === c.station)
   const leg = st?.kind === 'agent' ? ` leg ${c.leg}/${st.chain.length} (${st.chain[c.leg]?.adapter ?? '-'})` : ''
@@ -159,11 +252,35 @@ async function main() {
       for (const s of list) out(`${s.session_id}  [${s.status}]  ${s.agent}${s.account !== 'default' ? '/' + s.account : ''}  ${s.repo_name ?? s.cwd}${s.branch ? '@' + s.branch : ''}  turns=${s.turns}  ${s.limits ? `5h ${s.limits.five_hour?.pct ?? '-'}% 7d ${s.limits.seven_day?.pct ?? '-'}%` : ''}  ${String(s.task ?? '').slice(0, 50)}`)
       return
     }
-    const id = args._[0] || die(2, `usage: leg sessions ${cmd} <session-id>`)
+    const id = args._[0] || die(2, `usage: leg sessions ${cmd} <session-id>${cmd === 'handoff' ? ' [--to <agent>[/<account>]]' : ''}`)
     const s = readSession(id) || die(3, `session not found: ${id}`)
     if (cmd === 'show') return out(JSON.stringify({ session: s, events: readSessionEvents(id) }, null, 2))
     if (cmd === 'events') { for (const e of readSessionEvents(id)) out(`${e.ts}  ${String(e.type).padEnd(18)}  ${e.summary}`); return }
-    if (cmd === 'handoff') { if (!isActive(s)) die(3, `session ${id} is not active`); requestControl(id, { handoff: true }); return out(`handoff requested for ${id}`) }
+    if (cmd === 'handoff') {
+      if (!isActive(s)) die(3, `session ${id} is not active`)
+      // --to names the destination, the same choice the board's picker makes.
+      // Validated here for the same reason it is validated there: a pick that
+      // is not a destination, is not installed, or is at its wall must be
+      // refused now, not silently turn into "whatever is next".
+      if (typeof args.to === 'string') {
+        const want = parseTarget(args.to, { die })
+        const order = normalizeHandoffOrder(s.handoff_order)
+        const ladder = ladderFor(s)
+        const chain = candidates({ agent: s.agent, account: s.account, model: s.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) die(2, `${label} is not a destination for this terminal (${chain.map((c) => rungLabel(c)).join(', ') || 'none'})`)
+        if (s.installed && s.installed[want.agent] === false) die(3, `${label} is not installed on this machine`)
+        const u = readUsage(want.agent, want.account)
+        if (!isAvailable(u)) die(3, `${label} is at its usage limit until ${fmtReset(u.limited_until)}; pick another, or drop --to to take the next option in the order`)
+        if (hit.model && wallActive(u.walls?.[hit.model])) die(3, `${label} is out until ${fmtReset(u.walls[hit.model].limited_until)}; pick another rung, or drop --to to take the next open one`)
+        const target = { agent: hit.agent, account: hit.account, ...(hit.model ? { model: hit.model } : {}) }
+        requestControl(id, { handoff: true, target })
+        return out(`handoff to ${label} requested for ${id}`)
+      }
+      requestControl(id, { handoff: true })
+      return out(`handoff requested for ${id}`)
+    }
     if (cmd === 'end') { if (!isActive(s)) die(3, `session ${id} is not active`); requestControl(id, { end: true }); return out(`end requested for ${id}`) }
     if (cmd === 'rm') {
       if (isActive(s)) die(3, `session ${id} is still active; end it first`)
@@ -182,9 +299,18 @@ async function main() {
       }
       removeSession(id); return out(`removed ${id}`)
     }
-    if (cmd === 'simulate-limit') return simulateLimit(s)
+    // --message drives a particular wording through the real classifier, which
+    // is the only way to reach a per-model wall without waiting for one:
+    // --message "You've reached your Fable limit." walls fable and leaves the
+    // rest of the login open (src/buckets.mjs).
+    if (cmd === 'simulate-limit') return simulateLimit(s, { message: typeof args.message === 'string' ? args.message : null })
     die(2, `unknown sessions command "${cmd}" (ls|show|events|handoff|end|rm|simulate-limit)`)
   }
+  if (group === 'ladder') {
+    // The fallback ladder, in the terminal: the same rungs, the same live
+    // state and the same skip reasons the board's picker shows.
+    return ladderCommand(cmd, args)
+  }
   if (group === 'resume') {
     // The read side of the pointer. Freshness is never read out of the file:
     // it is recomputed from git here, now, so a resume file cannot describe a
@@ -226,7 +352,9 @@ async function main() {
     const showLink = (person, token, s) => {
       out(`${person.name} is on the board (${person.role}). Their link, shown once:`)
       out(`  ${linkFor(s, token)}`)
-      out(person.role === 'owner' ? 'Open it on this machine, or any machine that can reach that address.' : 'They see the terminals lane read-only: no prompts, no file names, no logs, no bundles. They can ask for a hand-off; you approve it on the card.')
+      out(person.role === 'owner' ? 'Open it on this machine, or any machine that can reach that address.'
+        : person.role === 'operator' ? 'They get the pipeline board — cards, the floor, the adapters — and their own terminals. Not this machine’s settings, not its history index, not anyone else’s terminal.'
+        : 'They see the terminals lane read-only: no prompts, no file names, no logs, no bundles. They can ask for a hand-off; you approve it on the card.')
     }
     if (!cmd || cmd === 'ls' || cmd === 'status') {
       if (!share.on || !share.people.length) {
@@ -234,9 +362,12 @@ async function main() {
         out('Turn it on: leg share on            (the Tailscale address; --bind lan, or --bind <address>)')
         return
       }
-      out(`share is on: http://${share.bind}:${share.port} (${share.bind_kind})`)
-      for (const p of share.people) out(`  ${p.name.padEnd(16)} ${p.role.padEnd(6)} added ${String(p.created_at).slice(0, 10)}${p.last_seen ? `  last seen ${String(p.last_seen).slice(0, 16).replace('T', ' ')}` : ''}`)
+      out(`share is on: ${scheme(share)}://${share.bind}:${share.port} (${share.bind_kind})`)
+      for (const p of share.people) out(`  ${p.name.padEnd(16)} ${p.role.padEnd(9)} added ${String(p.created_at).slice(0, 10)}${p.last_seen ? `  last seen ${String(p.last_seen).slice(0, 16).replace('T', ' ')}` : ''}`)
       out('')
+      out(tlsConfigured(share)
+        ? `TLS: certificate ${share.tls?.cert ?? '(from the environment)'}. The board on 127.0.0.1 stays plain http for this machine's own browser.`
+        : 'No TLS: keep this on Tailscale or a network you trust. Add one with leg share on --tls-cert <file> --tls-key <file> (tailscale cert <machine>.<tailnet>.ts.net issues a trusted pair).')
       out('A token is shown once. Lost one? leg share rotate <name>. Everyone out: leg share off')
       return
     }
@@ -246,19 +377,26 @@ async function main() {
       const ent = entitlement()
       if (!allows(ent, 'share')) die(2, ent.ok ? `leg share is part of the Team plan (per seat); this machine has a ${ent.plan} license. ${BUY_URL}` : describeLicense(ent))
       try {
-        const r = await turnOn({ bind: a.bind ?? 'tailscale', port: a.port ? parseInt(a.port, 10) : undefined, owner: a.owner })
+        const r = await turnOn({
+          bind: a.bind ?? 'tailscale', port: a.port ? parseInt(a.port, 10) : undefined, owner: a.owner,
+          tlsCert: typeof a['tls-cert'] === 'string' ? a['tls-cert'] : null,
+          tlsKey: typeof a['tls-key'] === 'string' ? a['tls-key'] : null,
+        })
         await restartBoard()
-        out(`share is on: the board is at http://${r.share.bind}:${r.share.port} (${r.share.bind_kind})`)
+        out(`share is on: the board is at ${scheme(r.share)}://${r.share.bind}:${r.share.port} (${r.share.bind_kind})`)
         if (r.token) showLink(r.owner, r.token, r.share)
-        out('Add someone: leg share add <name>')
-        out('No TLS: keep this on Tailscale or a network you trust. Anyone with a link sees that your terminals exist and how much usage is left.')
+        out('Add someone: leg share add <name> [--role operator|guest]')
+        out(tlsConfigured(r.share)
+          ? `TLS is on, from ${r.share.tls?.cert ?? 'the environment'}. Renew the pair and run leg down && leg up to pick up a new one.`
+          : 'No TLS: keep this on Tailscale or a network you trust. Anyone with a link sees that your terminals exist and how much usage is left. leg share on --tls-cert <file> --tls-key <file> turns it on; tailscale cert <machine>.<tailnet>.ts.net issues a trusted pair.')
       } catch (err) { die(2, err.message) }
       return
     }
     if (cmd === 'add') {
-      const name = args._[0] || die(2, 'usage: leg share add <name> [--role owner|guest]')
+      const name = args._[0] || die(2, `usage: leg share add <name> [--role ${ROLES.join('|')}]`)
       try {
-        const r = addPerson(name, { role: args.role === 'owner' ? 'owner' : 'guest', share })
+        if (args.role !== undefined && !ROLES.includes(String(args.role))) die(2, `bad role "${args.role}" (${ROLES.join('|')})`)
+      const r = addPerson(name, { role: typeof args.role === 'string' ? args.role : 'guest', share })
         showLink(r.person, r.token, r.share)
         if (!r.share.on) out('share is still off: leg share on')
       } catch (err) { die(2, err.message) }
@@ -330,6 +468,12 @@ async function main() {
     const code = await harnessCommand(cmd, args, { out, die })
     process.exit(code)
   }
+  if (group === 'adapter' || group === 'adapters') {
+    // Custom adapters: any CLI as a card agent, from a JSON spec on disk
+    // (src/adapters/custom.mjs). The built-ins need none of this.
+    const code = await adapterCommand(cmd, args, { out, die })
+    process.exit(code)
+  }
   if (group === 'history' || group === 'worktrees') {
     // Every conversation on this machine, Leg's own and the ones the agents'
     // stores hold: a read-only index (src/history/index.mjs). `continue`
@@ -470,13 +614,19 @@ async function main() {
     out(openBoard(url) ? `opened ${url}` : `could not open a browser; visit ${url}`)
     return
   }
-  if (group && group !== '--help' && group !== 'help') die(2, `unknown command "${group}" (claude|codex|agy|grok|sessions|history|worktrees|resume|accounts|harness|license|share|up|down|status|open|card|scheduler|uninstall)`)
+  if (group && group !== '--help' && group !== 'help') die(2, `unknown command "${group}" (claude|codex|agy|grok|sessions|ladder|history|worktrees|resume|accounts|harness|license|share|up|down|status|open|card|scheduler|uninstall)`)
   out(`leg ${VERSION}, your coding agents, with a board alongside and a handoff when one hits its limit
   claude|codex|agy|grok [args...]   the normal interactive agent in this terminal; args pass straight through
                                 the board opens once, the session shows as a card, usage is tracked, a limit hands off
                                 a second live session in one checkout gets its own worktree (--no-worktree to share)
                                 auto-approve mode (--no-auto-approve to opt out)
+                                --resume-card <id> takes over a background card: this terminal opens in that card's
+                                worktree, primed from its bundle (Take over on the board pauses it and prints this)
   sessions ls|show|events|handoff|end|rm|simulate-limit <id>
+                                handoff --to <agent>[/<account>[/<model>]] names the rung; simulate-limit --message "<text>"
+  ladder [ls]                   the fallback ladder: every rung, what it costs, and what it is doing right now
+  ladder set <n> <agent>[/<account>[/<model>]] [--when always|below:N|walled-only]
+  ladder rm <n> | ladder spend on|off
   history [ls] [--provider p] [--repo r] [--search q] [--json]
                                 every conversation on this machine: Leg's own, and the ones Claude Code, Codex,
                                 Grok, Antigravity and Copilot keep in their own stores (read only, nothing moved)

package/docs/DECISIONS.md

@@ -2,6 +2,16 @@
 
 Durable product and design decisions that the code does not explain on its own. One entry per decision, newest first.
 
+## 2026-09-17: a hand-off destination is a rung of (agent, account, model), and usage is a property of a row
+
+- **What.** `preferences.json` keeps `handoff_order` and derives it from a new `handoff_ladder` of rungs, each `{agent, account, model, when, cost}`. `chooseNext` walks the ladder from rung 1 every time. `spawnSpec` pushes the rung's model flag, so the interactive path finally carries `--model` the way every headless adapter already did. A claude downshift with a known session id starts `claude --resume <id> --model <alias>` and skips the bundle; every other rung is primed from the bundle. Usage stops being a region on the board: the binding bucket is one strip token at the top and one phrase on each row, and the four login panels move intact behind a **Capacity and models** disclosure. Live cards become rows in a **Background** panel directly under Terminals; finished cards collapse into one ledger line.
+- **Why a model is part of the destination.** Anthropic's session and weekly limits are shared across every model, and the Opus and Sonnet limits are family scoped: switching outside that family keeps you working (costs doc, line 132). So the cheapest hand-off available is usually not another CLI at all, it is another model on the subscription you already pay for, and until now Leg could not express it. Making the model part of the destination is what lets a Fable wall be a wall on Fable rather than on claude.
+- **Why downshift by `--resume` and upshift by bundle.** A same-login model change can hold the conversation, and holding it is worth more than anything the bundle carries, because the bundle is a summary and the transcript is the thing itself. `--resume` and `--model` are each verified in `claude --help`; composing them was probed and recorded at `fixtures/live/claude/resume-model-probe.json`, which is also where the cost of the other direction is written down: the resumed context is re-read at the new model's rates, so an upshift pays for that re-read at the higher price. Every other rung crosses a CLI boundary where no shared conversation exists, so it takes the bundle, which is the mechanism Leg already had. `codex resume <id> -m <model>` is the same shape and is not probed, so codex rungs take the bundle and do not claim to keep anything.
+- **Why `may_spend` is off by default.** An interactive Fable-on-credits request shows a consent prompt; with nobody at the terminal that prompt is held five minutes and the turn then ends; in `-p` mode, which is how every card runs, Claude Code never shows it and bills without asking (model-config doc, lines 68, 72 and 77). A stalled turn and a silent charge are both worse than a skipped rung, so an automatic hand-off refuses a `credits` or `metered` rung until a human says otherwise, and writes the reason to the ledger. A hand-off a human presses is not automatic and is not gated.
+- **Why usage became a strip and a row property.** On the seeded board the first terminal row sat at 1382px: about a thousand pixels of gauges before the thing the board is for. The gauges are not deleted, they move behind a disclosure, because every notch, degrade path and `aria-valuetext` in them is earned. What replaces them at the top is smaller and says more: the *binding* bucket per login rather than whichever window happened to be stored. The same figure on a row is per model and therefore real; the shared-login caveat is said once, at the region head, where adding three rows' figures together is stopped.
+- **Why cards live under Terminals.** A card is a terminal you are not sitting at: same register, same one sentence, same ladder, same bundle. Putting live cards in a drawer while live terminals are rows made the same object two shapes and taught nobody anything. Liveness, not kind, decides the surface, so ten finished cards are one ledger line and one running card is a row. The honest differences are printed rather than hidden: a `-p` leg is mute until it exits, so its sentence says so.
+- **What this rules out.** A number for agy (it publishes none), dollars for a subscription session (no transcript carries a cost field), and per-terminal attribution of a shared login (nothing publishes it).
+
 ## 2026-09-16: the portable harness is an opt-in subsystem over a vendored, hash-pinned engine
 
 - **What.** `leg harness` carries the source agent's working environment (rules, identity, hooks, skills, subagents, commands, MCP servers, permissions) to the agent a hand-off lands on. The capture, neutral bundle and apply engine is the Agnostic AI port engine (MIT), embedded byte for byte under `src/harness/vendor/agnostic-ai/` and driven through its library entry; Leg owns consent, policy, the client registry, state, the fingerprint, the trail and the hand-off decision (`src/harness/*.mjs`).

package/docs/DEMO.md

@@ -79,16 +79,19 @@ It prints a preflight table, then
 address in your browser. The board polls every three seconds, so nothing below
 needs a reload.
 
-The page is one column, read top to bottom: the instrument head with one row per
-login, then **Terminals**, **Landed on main**, **Background tasks**, and
-**Settings**. This demo happens entirely in **Background tasks**. On a fresh
-board home the head reads `no reading` on every rail, because no agent has
-reported usage into this home yet.
+The page is one column, read top to bottom: the verdict, the capacity strip
+(one token per login, with the login panels behind its `Capacity and models`
+disclosure), **Terminals**, **Background** (live cards only, hidden while none
+are running), the ledger (finished terminals, landed commits, conversations
+and finished cards, as four counts), and **Settings**. This demo happens
+entirely in **Background**. On a fresh board home the capacity strip reads
+`no reading` for every login, because no agent has reported usage into this
+home yet.
 
 ### 3. Queue the card
 
-Click **New card** in the **Background tasks** head. The dialog opens on **New
-background card**.
+Click **New card**, in the ledger's finished-cards cell below Terminals and
+Background. The dialog opens on **New background card**.
 
 1. **Repo path**: `C:\baton-demo\toy-demo`.
 2. **Task**: `Add a file greeting.txt containing 'hello from baton'`.
@@ -112,8 +115,9 @@ The recorded chain is `fake-claude>fake-codex`.
 
 ### 4. Leg 1, on fake-claude
 
-The card appears as a row in **Background tasks**. The line beside the region
-title reads `1 running`, and the row reads left to right:
+The card appears as a row in **Background**, directly under Terminals. The
+line beside the region title reads `1 running`, and the row reads left to
+right:
 
 - `fake-claude`, `build`, `running`
 - the title, and under it the one sentence
@@ -173,11 +177,13 @@ the bundle Leg wrote. The status word is `running` again, the run is `run=2`,
 and the chain reads `fake-claude · handed off · fake-codex · running`. This is
 `demo-4-codex-running.png`.
 
-Twenty seconds later the station finishes. The line beside the region title
-reads `1 finished`, the status word is `done`, the sentence is
-`done after 2 runs, card done: all 1 station(s) complete`, the chain reads
-`fake-claude · handed off · fake-codex · done`, and the buttons are **Rerun**
-and **Remove**. This is `demo-5-done.png`.
+Twenty seconds later the station finishes. The card leaves **Background**,
+which goes back to empty and hides itself, and the ledger's finished-cards
+cell reads `1 finished card, 1 done, last <time>`. Clicking **View** there
+opens the one line the drawer keeps for it: `done after 2 runs, card done:
+all 1 station(s) complete`. A finished card carries no buttons; Rerun and
+Remove apply to a live row, and this one no longer is one. This is
+`demo-5-done.png`.
 
 The worktree named in **Where** now holds the file the fake agent wrote,
 `hello-fake.txt`, and `.leg/DONE`.

package/docs/DEVIATIONS.md

@@ -180,3 +180,4 @@ tests. Rows for the shape changes a later reader would otherwise wonder about.
 | 2026-09-14 | src/resume.mjs `refreshPointers()` | the board was to skip any checkout with a live terminal, so a live hand-off is never clobbered | it skips only when the pointer's OWN stamped session is live | the case that started this had a hand-written three-day-old `RESUME.md` and a different terminal live in the same checkout; the first rule would have left it exactly as it was |
 | 2026-09-14 | src/resume.mjs idle pointer | a checkpoint bundle was described as "the last hand-off", and the per-session file was named unconditionally | `lineage.to` decides hand-off vs checkpoint, and the file is named only when it exists on disk | seen in the live pointer for this repo: it claimed a hand-off that never happened and pointed at a `RESUME-<id>.md` that was never written, which is the same class of lie the module exists to stop |
 | 2026-09-14 | src/board/sessions.js `renderDrawer()` | the whole panel is rebuilt every 3 s poll so relative timestamps stay honest | still rebuilt, but every scrollable box carries a stable `data-scroll-key` and its offset is carried across | the rebuild reset the task box, each message and the timeline to the top every three seconds, so a long message could not be read at all |
+| 2026-09-17 | src/board/sessions.js `verdictLines()` | spec A.5 lists "a model bucket came back and a terminal is still downshifted" below the two branches that print a standing percentage | the came-back branch is tested before them, right after the model-walled branch | as written it can never fire: "one login carries every live terminal" and "several logins carry work" both return for any login that has a figure at all, so the only state change worth telling a downshifted reader about was unreachable |

package/docs/ERRORS.md

@@ -3,6 +3,59 @@
 What broke, why, and what fixed it. One entry per failure, newest first. A first
 occurrence has to be written down or a repeat is never countable.
 
+## 2026-09-17: a new field on the session view leaked the owner's reset times to a guest, through the guest's own terminal
+
+**Fixed in `src/server.mjs` (`sessionsView` decides `guest` before the map and
+blanks `handoff_targets[].resets_at` for one). Caught by
+`test/share-security.test.mjs`, which was already asserting it.**
+
+The hand-off picker needed each destination's availability, so `handoff_targets`
+went onto every session in `sessionsView` carrying `resets_at`. The obvious
+mental model was "a guest gets `redactSession`, which lists its fields
+explicitly, so a new field is invisible to them". That is only true of someone
+else's terminal. `mine(s)` is true for a guest's **own** terminal, and that path
+spreads the whole object. So a guest's own card carried the exact reset
+timestamp of every account on the machine, including the owner's, which is
+precisely the usage data the share design keeps off a guest's board.
+
+The lesson is about where redaction lives, not about this field. There are two
+paths out of `sessionsView`: `redactSession` (allow-list, safe by default) and
+the `mine(s)` spread (deny-list, unsafe by default). **Any field added to a
+session object is visible to whoever owns that session, and a guest owns one.**
+A field that carries machine-level data has to be blanked where it is built, not
+left to a redactor that never sees it.
+
+What made this cheap: the security suite already asserted the whole guest
+response text contains no reset time, so the leak failed a test in the same run
+that introduced it. The test was written against the property ("a guest board
+carries no reset time"), not against the fields that existed when it was
+written, which is why it still caught a field invented months later.
+
+Two smaller ones from the same change, both worth the line:
+
+- Registering `grok` broke three tests that asserted `unknown adapter "grok"`.
+  A test that encodes "not supported yet" as an assertion becomes a tripwire on
+  the day support lands. Assert the refusal with a name nothing will ever
+  provide (`no-such-agent`), so the test outlives the gap it was describing.
+- `names()` started reading `$LEG_HOME/adapters` from disk, and `/api/health`
+  calls it once for the list and once per adapter. That put a readdir, a read
+  and a JSON parse per spec on the same event loop the terminals lane is pushed
+  from, and `/api/health` went over its 1 s budget in
+  `test/board-responsiveness.test.mjs`. Cached against the directory's entry
+  list with a one-second floor. The board's hot path is `/api/health` plus the
+  sessions view; anything new they call has to be counted, not assumed cheap.
+  (This is the same event-loop failure as the entry below, from the other end.)
+- `test/board-responsiveness.test.mjs` failed the ship twice at 1055 ms and
+  1140 ms against a hard `< 1000 ms`, and passed three times out of three when
+  run alone. An absolute millisecond budget on a four-way-concurrent runner
+  measures the machine, not the code. It now takes an idle baseline in the same
+  process and asserts the busy request is not 20x it, with a 3 s ceiling for the
+  symptom the test is named for. **It was only trusted after being made to
+  fail**: putting the original shape back (no floor, no fingerprint, a 1.2 s
+  blocking view on every watcher event) made it report 4,810 ms and fail both
+  assertions, which is the "four to fourteen seconds" the entry below describes.
+  A perf test that has never been watched failing is a number, not a guard.
+
 ## 2026-09-17: one running terminal saturated the board's event loop, and four separate symptoms came out of it
 
 **Fixed in `src/server.mjs` (watcher filter, stat fingerprint, push floor, cached
@@ -529,3 +582,44 @@ it), and check whether a board was listening on 4747 at the time.
   in the hand-off as in flight, or the next agent ships without it. And a
   cache keyed on a directory's mtime sees files added and removed, never a
   file rewritten in place.
+
+## The 0.12.0 redesign review confirmed 51 findings before the fix pass, 23 of them high (2026-09-18)
+
+- **What happened.** The eight-step redesign (per-model buckets, the ladder,
+  the capacity strip, cards reborn) was reviewed before commit by six finders
+  and three refuters per finding: 174 agents, 51 findings confirmed, 23 high.
+  The highs were all in code that had passed its own tests: `binding()`
+  short-circuited on the first active bucket instead of the one that stops
+  the requested model, `summarize()` parsed the ledger once per card per
+  refresh, the take-over route handed out a command for a card with no
+  checkout, `cardWorkRoot()` fell back to the main checkout, and the guest
+  payload leaked buckets, walls and hand-off reasons through the new fields.
+- **Fix.** Three parallel fix passes, one owner per file group, every finding
+  closed with a regression test in the same change; the suite went from 783
+  to 830 tests. The lockfile's root `repository` field, lost when Playwright
+  was installed, was restored so `scripts/npm-publish-gate.mjs` passes.
+- **The lesson that generalises.** A feature's own tests prove the feature's
+  own model of itself. The defects a review finds sit where two new pieces
+  meet (a new field and an old redaction list, a new route and an old helper),
+  and the review has to run on the uncommitted tree, before the commit exists
+  to be pushed by someone else. A `npm i` that regenerates the lockfile is a
+  release change and gets the publish gate run in the same turn.
+
+## A seeded board's End-as-card button wrote into a real repo (2026-09-17)
+
+- **What happened.** Driving the new "End, and keep going as a card" verb in
+  a browser against `scripts/seed-wes-board.mjs`'s board, the click on the
+  recruiting-tool row hit `POST /api/sessions/:id/end-as-card`, which did
+  exactly its job: it wrote a hand-off bundle under
+  `C:\Projects\recruiting-tool\.context-handoffs\` and cut a worktree and a
+  `leg/card-...` branch there. The seed's rows named real repositories on this
+  machine because long real paths were what the layout had to be measured
+  against. Nothing ran in the worktree (the server was stopped within a
+  minute); the worktree was deregistered and the branch deleted, and the
+  directory and bundle were left for a hand delete.
+- **Fix.** The seed's repo paths now live under `C:\Projects-seed\...`, which
+  does not exist, so every git-backed action on a seeded row answers 409
+  instead of touching a checkout. The row still prints the same length.
+- **The lesson that generalises.** A seeded board is safe to look at and not
+  safe to click: any row that names a path that exists is a live control on
+  that path. Seed paths must be realistic in shape and impossible in fact.

package/docs/ROADMAP-v2.md

@@ -1,5 +1,30 @@
 # Roadmap v2: the software factory
 
+**0.12.0 (2026-09-17) added the model dimension and made cards a first-class
+surface.** A hand-off destination is now a rung of (agent, login, model), not
+just an agent, so a Fable wall moves the terminal to opus on the same
+subscription before it moves to another CLI, and for claude that move keeps
+the conversation (`claude --resume <id> --model <alias>`). The **Hand off now
+to** picker lists those rungs with their models, whether each keeps the
+conversation, and why a greyed one buys nothing; the same list is a ladder
+editor in Settings, in a terminal's expansion and behind `leg ladder`. Live
+cards left the drawer and became rows in a **Background** panel directly under
+Terminals, with a one-line entry and the thirteen-field dialog demoted to
+**More settings**; `End, and keep going as a card` and `Take over` are the two
+doors between a terminal and a card. The board top became a capacity strip
+over a **Capacity and models** drawer, a row says `waiting on you` with the
+question when Claude Code's `Notification` hook fires, and a burn-rate figure
+prints only with its sample count. That closes the model dimension, the
+picker's second half, and the cards item below.
+
+**0.11.0 (2026-09-17) opened the chain and finished the share story.** grok is
+a registered card adapter; any other CLI becomes one from a JSON spec
+(`leg adapter add`, no code); **Hand off now** can name its destination
+instead of taking the next in the order; `leg share` grew TLS from a
+certificate pair you supply, an `operator` role between owner and guest, and
+an audit trail of who did what across every terminal and every card. That
+closes items 1 and 4 below, and the "hand off now to \<adapter>" picker.
+
 **0.3.0 (2026-09-11) shipped item 1 and the first half of continuous landing.**
 A second live session in one checkout gets its own worktree and branch, and
 **Land** on its card sends that branch through the merge queue (rebase, tests,
@@ -33,23 +58,56 @@ event names its actor, a board that reads only the ledger, and an auth/bind seam
 
 ## Next
 
-1. **Multi-human network access**, shipped in 0.3.0 as `leg share` (a token
-   and a name per human, per-human actor ids on every event, rate limits, a
-   guest's read-only redacted board). What is left: TLS termination, token
-   scopes finer than owner and guest, and an audit view of who did what across
-   sessions.
+1. ~~**Multi-human network access**~~ — done. 0.3.0 shipped `leg share`; 0.11.0
+   shipped the three that were left: TLS (`leg share on --tls-cert/--tls-key`,
+   or `LEG_TLS_CERT`/`LEG_TLS_KEY`, from a pair you supply — Leg issues none),
+   the `operator` role between owner and guest, and the audit trail
+   (`/api/audit`, Settings → Audit trail).
 2. **Review station with human reviewers**: a `human` station kind that shows
    the diff, the bundle and the test tail, with Approve / Request changes /
    Reassign as buttons; reviewer identity from the token.
 3. **`pr` land mode live**: `gh pr create` argv is built and stub-tested today;
    run it for real behind an explicit per-card opt-in and a remote allowlist.
-4. **More adapters**: grok (adapter written, unregistered until `grok login` and
-   a passing probe on the machine) and muse only if a real CLI is verified; a
-   generic "argv + JSON result" adapter for anything else.
+4. ~~**More adapters**~~ — done. grok is registered (2026-09-17: flags read
+   from `grok --help` on 1.0.34, envelope read from the shipped binary, probe
+   reached the account and returned a real 402 wall that classified `limit`;
+   the success path is still unprobed for want of balance). Anything else,
+   muse included, is a custom adapter: a JSON spec in
+   `$LEG_HOME/adapters/<name>.json`, `leg adapter add`, no code
+   ([adapters.md](adapters.md#custom-adapters)).
 5. **OpenClaw Workboard mirror** once the bundled plugin is allowed
    (`plugins.allow`): the verb table in `src/sync/workboard.mjs` is the only
    thing to check against `openclaw workboard --help`.
 
-Also on the list: per-station prompt templates editable from the board, a
-"hand off now to <adapter>" picker, lease suggestions from the diff of the
-previous leg, and a floor view that shows lease contention over time.
+6. **Probe `codex resume <id> -m <model>`.** The `resume` subcommand and the
+   `-m` flag are each verified from `codex --help`; composing them is not, so
+   a codex rung ships primed from the bundle and only the claude rungs claim
+   to keep the conversation. One real run on a live codex session settles it.
+   The same probe shape applies to naming the terminal tab: whether codex, agy
+   and grok leave an OSC 2 title alone once the child starts drawing is
+   assumed, not known, which is why the tab title is the browser's and not the
+   terminal's.
+
+Also on the list: per-station prompt templates editable from the board, lease
+suggestions from the diff of the previous leg, and a floor view that shows
+lease contention over time. (The "hand off now to \<adapter>" picker landed in
+0.11.0: Details → **Hand off now to**, or `leg sessions handoff <id> --to`.
+0.12.0 put models on its rows.)
+
+## Ruled out, with the reason
+
+- **Phone or push notifications.** They need a relay, which means a server
+  that is not this machine holding a token that can reach you. Leg is
+  local-first, so the notice surfaces are the ones the machine already owns:
+  the browser tab badge (always on, no permission), a browser toast on the
+  board (off by default, gated on a secure context), and a terminal toast
+  through Claude Code's `Notification` hook (on by default).
+- **Percentages for agy.** Antigravity CLI publishes no usage figure at all,
+  so there is nothing to read. agy's token says `no figure`, and its terminals
+  are shown by elapsed time instead. A number here could only be invented.
+- **Dollars for subscription sessions.** No transcript Leg reads carries a
+  cost field. codex's `credits.balance` can be printed as a measured fact with
+  the word `credits`, and is never summed with an estimate.
+- **Per-terminal attribution of a shared login.** Nothing publishes which
+  terminal spent which part of a window. The board says it once, at the
+  Terminals head (`4 share the claude login`), rather than guessing per row.