@ucsandman/legcli 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,147 @@
 # Changelog
 
+## 0.12.0 (2026-09-17)
+
+The board is rebuilt around the two questions you actually open it to answer:
+which terminal needs you, and which model is about to run out. Usage stops
+being a region and becomes one strip plus a property of every row; a hand-off
+can now change the model instead of the CLI; and background work comes back as
+rows you can read at a glance instead of a ledger you have to dig through.
+
+- **The board top: a capacity strip, and the login panels behind one
+  disclosure.** Under the verdict, one strip prints each login's *binding*
+  bucket rather than whichever window happened to be stored: `claude 63%
+  6:01 PM`, `codex back Sat 10:11 PM`, `agy no figure`, `grok no reading`. The
+  four login panels are not rewritten, they move intact behind **Capacity and
+  models** with every gauge, notch and `aria-valuetext` they had, and the
+  claude panel head grows a model rail whose chips read `fable 63%` and
+  `opus 12%`. Every branch of `verdictLines()` is now asserted under
+  `VERDICT_CH` by `test/board-verdict.test.mjs`, so a 52px headline can no
+  longer wrap to three lines. Measured on the seeded board at 1280: the first
+  terminal row sits at 536px, where it used to sit at 1382px.
+- **A terminal row says what it is doing, on which model.** The register reads
+  `waiting on you  baton on main  dirty 3  ahead 2  claude/fable`, and a quiet
+  agent carries `quiet 5m`. `ahead` is one `git rev-list --count` on the
+  existing poll; the model is the alias the leg resolved to, updated from the
+  transcript for claude so a silent fallback off Fable becomes visible, and
+  never a guessed default. Under the prompt the row prints its binding bucket,
+  `63% of the fable week`, and past the warn threshold the rung that would keep
+  the terminal.
+- **A terminal waiting on a human says so, everywhere.** Leg now wires Claude
+  Code's `Notification` hook (`permission_prompt`, `idle_prompt`,
+  `agent_needs_input`). The row's status word becomes `waiting on you` and it
+  carries the question verbatim: `waiting on you: permission to run Bash(git
+  push origin HEAD), asked 2m ago`. That sorts the row first, counts it in the
+  region head (`4 running, 2 waiting on you, 4 share the claude login`) and in
+  the tab, which becomes `(2) Leg` with a dotted favicon. Codex, agy and grok
+  publish no such signal, so their rows say `quiet Nm` and never claim to be
+  waiting. `permission_prompt` fires after about six seconds and mostly when
+  you look away, so this is a reliable notice, not an instant one.
+- **A hand-off can now change the model, not just the CLI.** Destinations are
+  rungs of `(agent, account, model)`. The ladder's default is `claude/fable`,
+  `claude/opus`, `claude/sonnet`, then each remaining installed agent, and a
+  terminal's expansion prints it: `now: claude / fable, then claude / opus,
+  then claude / sonnet, then codex, then agy` with `first eligible now:
+  claude / opus` under it. A claude downshift with a known session id starts
+  `claude --resume <id> --model <alias>` and skips the bundle, so the
+  conversation survives the switch; every other rung is primed from the bundle
+  as before. `leg ladder` prints and edits the same thing from a terminal
+  (`ls`, `set <n> <agent>[/<account>[/<model>]]`, `rm <n>`, `spend on|off`),
+  and `leg sessions handoff <id> --to claude/default/opus` names a rung.
+- **The wall is attributed to what it actually walled.** A Fable limit walls
+  Fable, not the login: `walls{}` is keyed by model and `limited_until` is left
+  alone, so `claude/sonnet` keeps working. A session, weekly or spend limit is
+  account scoped, and a same-login model rung is then refused as a wasted
+  switch with the reason on the row. Wording Leg cannot parse walls the whole
+  login and prints the evidence it failed on rather than guessing.
+- **Nothing spends money unless you said it could.** `may_spend` is off. An
+  automatic hand-off skips any rung that bills credits or a metered balance and
+  writes the reason to the ledger; the Settings sentence is *A rung that spends
+  usage credits or metered balance may be taken by an automatic hand-off*, and
+  today it adds *Usage credits are off, so there is nothing to spend through
+  the wall.* rather than offering a dead control. A `reserve` per login holds a
+  floor back from automatic hand-offs only: *An automatic hand-off skips a rung
+  past the floor; a hand-off you press yourself still takes it, and the picker
+  says so.* Climbing back is a radio with the rule printed under it: *Leg never
+  interrupts a running turn to climb.*
+- **Cards are terminals you are not sitting at.** Live cards are rows in a
+  **Background** panel directly under Terminals, in the terminal row's
+  register with a measured work stat and the same button grid; a running card
+  says `no message until this leg ends, started 8:15 PM`, because `-p
+  --output-format json` is mute until the leg exits. Finished cards fall into
+  one ledger line, `10 finished cards, 5 done, 5 failed, last 8:15 PM`, so ten
+  done cards are one row and not ten. Starting one is a single field,
+  `Run in the background:`, over an inferred sentence whose nouns are buttons
+  (*in recruiting-tool on main, with claude/fable then claude/opus then
+  claude/sonnet then codex then agy, build only*); the old thirteen-field
+  dialog is still there as **More settings**.
+- **Two verbs for leaving and coming back.** The End confirm row grows
+  **End, and keep going as a card**: it writes the bundle, hands the
+  terminal's own worktree to a card with its lineage, and says where the work
+  went. On a card, **Take over** pauses it and hands back the one command a
+  browser cannot run, `leg claude --resume-card <id>`, in an interactive
+  terminal primed from the card's bundle.
+- **A time figure, or nothing, and never a time without its sample count.**
+  `burn()` reads a per-bucket history ring and prints a rate only with at least
+  three samples spanning ten minutes inside the current window; the estimate is
+  the endpoint slope, capped at the reset, and a flat or falling line prints
+  nothing at all. Where it can speak, the row and the verdict say *about 2h 40m
+  of Fable left, from 9 samples over 4h*. A reading that comes back unchanged
+  more than ten minutes after the last sample is still recorded, so a flat hour
+  is a measured zero rather than a starved gate.
+
+Fixes:
+
+- **Fixed: the only live Claude wall Leg ever captured was classified as no
+  progress.** The fixture pattern matched `You've hit your Fable limit` and
+  Anthropic now writes `You've reached your Fable limit`, so a real wall on the
+  headless path scored `{outcome: "no_progress", signal: "none"}` and the
+  terminal sat on a dead login. The pattern takes both wordings, and
+  `fixtures/limits/claude/claude-fable-limit.json` is a new `observed-live`
+  fixture produced from the captured response rather than from the docs.
+- **Fixed: the board printed the wrong percentage for a claude login.** The tap
+  kept only `five_hour` and `seven_day` out of the usage response and threw the
+  rest away, so a login whose binding bucket was the Fable week was reported at
+  the account-wide figure. The whole `limits[]` array is now read into
+  `buckets[]`, and the strip, the verdict and the row all print the bucket that
+  will actually stop you.
+- **Fixed: a seeded board's rows were live controls on real repositories.**
+  `scripts/seed-wes-board.mjs` named real paths, and a click on a seeded row
+  cut a worktree in a real checkout. The seed now names `C:\Projects-seed\...`,
+  realistic in shape and impossible in fact. `docs/ERRORS.md` carries the
+  entry.
+
+Migration:
+
+- `preferences.json` keeps `handoff_order` and now derives it from the ladder,
+  so `validHandoffOrder`, `requireHandoffOrder` and every older terminal keep
+  working unchanged. It gains `handoff_ladder` (rungs of `{agent, account,
+  model, when, cost}`), `may_spend` (default `false`), `climb_back` (default
+  `next-handoff`, or `never`), `reserve` (`{agent: percent}`),
+  `notify_terminal` (default `true`) and `notify_board` (default `false`). A
+  bare `handoff_order` expands into one `model: null, when: always` rung per
+  agent, so behaviour is unchanged until you edit a rung.
+- Usage records under `$LEG_HOME/usage/` gain `buckets`, `walls`, `history`,
+  `extra_usage` and `facts`. An older Leg ignores them; a record without them
+  falls back to the two windows it has always had.
+- Session records gain `model`, `waiting` and `ahead`, all nullable. On a
+  shared board all three are dropped from someone else's row (`waiting` carries
+  the verbatim question, `model` and `ahead` describe this machine's usage and
+  someone else's work). Your own terminal is never redacted, so you keep all
+  three on it whichever role you hold.
+- `playwright` is a dev dependency now, so `scripts/board-shots.mjs` runs from
+  a fresh `npm install`. It is not shipped in the package.
+
+Still assumed, and marked as such:
+
+- Whether `codex resume <id> -m <model>` composes. The `resume` subcommand and
+  the `-m` flag are each verified from `codex --help`; putting them together is
+  not. A codex rung therefore ships primed from the bundle, and only the claude
+  rungs claim to keep the conversation.
+- Whether codex, agy and grok leave an OSC 2 terminal title alone once the
+  child starts drawing. That is why naming the terminal tab is not in this
+  release: the browser tab badge needs no such assumption, and ships.
+
 ## 0.11.0 (2026-09-17)
 
 - **grok is a card adapter, not just a terminal.** `--chain grok` works. Its

package/README.md

@@ -11,7 +11,7 @@
 
 *Claude hits the five-hour wall. The terminal reads `handing off to codex`, and codex carries on there. Nothing is retyped. ([the full 53-second run](https://legcli.com/#handoff))*
 
-![The Leg board at 1280px: a headline reading "All 4 terminals are on claude, and claude has 5% left", under it the staleness of the reading; a lit claude panel with its 7 day gauge at 95 percent past the reserve notch and its 5 hour gauge at 38; half panels for codex, at the wall, and agy, which publishes no figure; four terminal rows with their prompts and buttons; and counts for finished terminals, what landed and background tasks](https://legcli.com/img/docs/terminals-1280.png)
+![The Leg board at 1280px: a headline naming the terminal that has waited on you longest; under it a capacity strip with claude at 63 percent of its fable week, codex back on Saturday, agy with no figure and grok with no reading, and a button that opens the login panels; then four terminal rows, each with its status, repo and branch, uncommitted and unpushed counts, agent and model, the prompt, the one thing worth knowing and four buttons; then a Background panel of live cards and a one-line field for starting another; then counts for finished terminals, what landed, conversations and finished cards](https://legcli.com/img/docs/terminals-1280.png)
 
 You keep using your coding agents exactly as you do today, in any terminal,
 from your own config directory: Leg adds its hooks in a separate per-session
@@ -21,11 +21,16 @@ files and regions). `leg claude --model opus` is
 `claude --model opus` with four things running alongside it:
 
 1. **A board.** Opened once in your browser, reused after that. Every Leg
-   session in every terminal is a card on it: agent, account, repo and branch,
-   the task, the files it is touching, its 5h and 7d usage, what has landed on
-   trunk. Two sessions editing the same file in one repo are flagged on both
-   cards, and a second session in a checkout that already has one gets its
-   own worktree and a **Land** button instead of writing over the first.
+   session in every terminal is a row on it, and the row's register reads
+   status, repo on branch, uncommitted and unpushed counts, agent and model,
+   and how long it has been quiet: `waiting on you  baton on main  dirty 3
+   ahead 2  claude/fable`. Under that come the prompt, the one thing worth
+   knowing, the files it is touching and the usage bucket that will stop it.
+   Capacity is one strip at the top rather than a region, with the login
+   panels and their gauges behind **Capacity and models**. Two sessions
+   editing the same file in one repo are flagged on both rows, and a second
+   session in a checkout that already has one gets its own worktree and a
+   **Land** button instead of writing over the first.
 2. **Usage tracking** per agent and account, from what each CLI already
    exposes: Claude Code's usage endpoint and its `StopFailure` hook, Codex's
    read-only app-server rate-limit read, agy's log, and Grok's billing proxy endpoint.
@@ -33,12 +38,18 @@ files and regions). `leg claude --model opus` is
    refreshed as the session goes, so the work is always ready to hand off.
 4. **The handoff itself.** Near the limit you get a warning. At the limit Leg
    saves the bundle, stops the agent, and starts the next option in the same
-   terminal from that bundle: another login of the same agent if you added
-   one, otherwise the next agent in the order shown on the terminal card.
-   The default is claude -> codex -> agy (with grok supported in handoff order),
-   and Settings changes the default for new terminals. Nothing is retyped.
-   When every option is out, it tells you which resets first and when, waits
-   for that reset with a countdown, and starts that agent from the bundle.
+   terminal from that bundle. The options are a ladder of rungs, and a rung is
+   an agent, a login and a model: the default is `claude/fable`,
+   `claude/opus`, `claude/sonnet`, then each remaining installed agent. A
+   Fable limit walls Fable and not the login, so the first move is usually to
+   another model on the same subscription, and for claude that move is
+   `claude --resume <id> --model opus`, which keeps the conversation instead
+   of replaying the bundle. Only when every claude rung is out does it move to
+   another CLI. Settings holds the ladder for new terminals, `leg ladder`
+   edits it from a shell, and **Details** on a row edits the copy that
+   terminal is running. Nothing is retyped. When every rung is out, Leg tells
+   you which resets first and when, waits for that reset with a countdown, and
+   starts that agent from the bundle.
 
 Subscription logins only: Leg strips `ANTHROPIC_API_KEY`,
 `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_CUSTOM_HEADERS`,
@@ -183,21 +194,23 @@ presenting it as current.
    both are stamped with the commit and the live terminals they describe.
    `claude "<prompt>"`, `codex "<prompt>"` and `agy -i "<prompt>"` all open the
    normal interactive session with that first turn.
-5. **Order.** Other accounts of the same agent come first, then every other
-   agent in the saved order, each tried once. The order is a priority list, not
-   a rotation: put agy at the bottom and agy is the last option from a Claude
-   terminal and from a Codex terminal alike. The board shows the exact
-   sequence with the agent running now skipped, plus the preferred option and
-   the first option eligible from current install and limit state. Use **Change
-   order** on a terminal card to change that terminal, or Settings to set the
-   default copied by new terminals. An option whose CLI is missing or whose
-   wall has not reset is skipped.
+5. **The ladder.** A rung is an agent, a login and a model, and Leg walks from
+   rung 1 every time. Other models on the same login come first, then other
+   accounts of the same agent, then every other agent in the saved order, each
+   tried once. It is a priority list, not a rotation: put agy at the bottom and
+   agy is the last rung from a Claude terminal and from a Codex terminal alike.
+   The board prints the exact sequence with the rung running now marked, plus
+   the first rung eligible from current install and limit state. Use **Change
+   the ladder** in a terminal's expansion to change that terminal, `leg ladder`
+   to do it from a shell, or Settings to set the default copied by new
+   terminals. A rung whose CLI is missing, whose wall has not reset, or that
+   shares the window that is already out, is skipped with its reason.
 6. **All out.** The terminal prints each option with its reset time, soonest
    first, then stays open with a countdown to the first reset and starts that
-   agent from the bundle when it arrives. The card says `waiting for <agent>
-   at <time>`. Ctrl-C (or End on the card) quits with exit 3 instead.
+   agent from the bundle when it arrives. The row says `waiting for <agent>
+   at <time>`. Ctrl-C (or End on the row) quits with exit 3 instead.
 
-You can force a handoff any time: the **Hand off now** button on the card, or
+You can force a handoff any time: the **Hand off now** button on the row, or
 `leg sessions handoff <id>`. Verified on this machine: `leg claude` opened
 the real Claude Code TUI with Leg's hooks firing into the session log, the
 usage poll recorded 36 % of the 5h window and 74 % of the 7d window, the
@@ -216,10 +229,12 @@ row flipped to observed-live (`node scripts/live-limits.mjs`). The same
 capture is wired for codex `usage_limit_exceeded` and agy `RESOURCE_EXHAUSTED`;
 no payload for either has been kept yet.
 
-Terminals started by this version can change order while they run. An older
-terminal stays on the order it started with; its card says a restart is needed
-and can save the desired default for the next launch. A normal agent exit ends
-the terminal. It does not trigger a handoff.
+Terminals started by this version can change their ladder while they run:
+Settings holds the default for new terminals, and **Details** on a row edits
+the copy that terminal is running. An older terminal stays on the order it
+started with; its row says a restart is needed and can save the desired
+default for the next launch. A normal agent exit ends the terminal. It does
+not trigger a handoff.
 
 ### The working environment travels too (optional)
 
@@ -350,22 +365,28 @@ only: the trail names repositories and people.
 
 `leg <agent>` opens it; `leg open` reopens it; `leg down` stops it.
 
-- **Instrument head**: one row per login, sticky at the top of the board and of
-  the floor. Each row carries the 5h and 7d rails, the percentage, when that
-  window resets and how long that is, a burn-rate sentence under the 5h rail,
-  where and when Leg read the number, and one word for the state: `under 60`,
-  `over 60`, `over 85`, `stale <n>m`, `at the wall` or `no reading`. A login
-  at its wall keeps both rails and gains `at the wall`, `back <day time>` and
-  `in <duration>` beside them.
-- **Terminals**: one full-width panel per session, the ones that need an answer
-  first. Agent and session tail, the status word, the first prompt as a button,
-  exactly one sentence (the highest-ranked thing true about the terminal), an
-  `also:` disclosure naming the rest, the files as comma-separated text,
-  `repo@branch`, `own worktree, from main` when the session cut its own
-  worktree, and an elapsed clock. Two live sessions in one repo touching the
-  same file print `codex (codex-99ab) is changing src/server.mjs in another
-  checkout; whoever lands second rebases` on both panels, and a panel that needs
-  you rises one step and says `waiting on you` in place of its status word.
+- **Verdict and capacity strip**: the largest sentence on the page, then one
+  strip with a token per login carrying the binding bucket, a short track, the
+  percentage and one state word or clock: `claude 63% 6:01 PM`, `codex back
+  Sat 10:11 PM`, `agy no figure`, `grok no reading`. **Capacity and models**
+  opens a drawer holding the full login panels: the 5h and 7d rails, the reset
+  and how long that is, where and when Leg read the number, `at the wall` with
+  its `back <day time>`, and on the claude panel a rail of model chips
+  (`fable 63%`, `opus 12%`, a walled one saying `out until 9:14 PM`). The
+  sticky instrument head is still what `/floor` puts at the top.
+- **Terminals**: one full-width row per session, the ones that need an answer
+  first. The register reads the status word, `repo on branch`, `dirty <n>` and
+  `ahead <n>`, `agent/model`, `quiet <n>m`, and `own worktree, from main` when
+  the session cut its own worktree; then the first prompt as a
+  button, exactly one sentence (the highest-ranked thing true about the
+  terminal), an `also:` disclosure naming the rest, the files as
+  comma-separated text, the binding bucket as `63% of the fable week`, and an
+  elapsed clock with the session tail. Two live sessions in one repo touching
+  the same file print `codex (codex-99ab) is changing src/server.mjs in
+  another checkout; whoever lands second rebases` on both rows. A Claude row
+  parked at a permission or idle prompt rises to the top, says `waiting on
+  you` in place of its status word, prints the question verbatim, and puts a
+  count in the browser tab (`(2) Leg`, with a dot on the favicon).
   After a Land the sentence is `landed on <base>, <7-char sha>, <n> files,
   +<added>/-<removed>`, or `Land was attempted at <time> onto <base> and
   bounced: <first line of the reason>. The branch still holds every commit;
@@ -376,21 +397,24 @@ only: the trail names repositories and people.
 - **Buttons**, in a fixed order that never reflows: Land, Hand off now,
   Details, End. Once a session has ended, Remove and Remove record take End's
   place. Details opens an expansion in flow under the panel.
-  **Hand off now** takes the next option in the order. To name the destination
-  instead, open Details and use **Hand off now to**, which lists every
-  destination with the reason a greyed one cannot be picked (`at its usage
-  limit, back 11:40`, `not installed on this machine`). `leg sessions handoff
-  <id> --to codex` is the same choice from a terminal. If the destination you
-  picked walls between the click and the hand-off, the work still continues
-  down the order and the terminal says which one took it instead.
+  **Hand off now** takes the first open rung of the ladder. To name the
+  destination instead, open Details and use **Hand off now to**, which lists
+  every rung with its model, whether it keeps the conversation, and the reason
+  a greyed one cannot be picked (`at its usage limit, back 11:40`, `shares the
+  window that is out, buys nothing`, `not installed on this machine`).
+  `leg sessions handoff <id> --to claude/default/opus` is the same choice from
+  a terminal. If the rung you picked walls between the click and the hand-off,
+  the work still continues down the ladder and the terminal says which one
+  took it instead.
 - Below it, **Conversations**: every coding-agent conversation on this machine
   as a count that opens, the ones Leg started and the ones Claude Code, Codex,
   Grok, Antigravity and Copilot keep in their own stores. Filter by agent,
   search, repository, or only what Leg started; a row opens its last messages
   in place, with the `leg history continue` command to copy where the agent
   can resume by id. The same drawer lists every checkout Leg can see. Then
-  optional **Background tasks** an agent runs in a separate worktree without
-  joining the terminal conversation (see below), then **Settings**.
+  **Settings**. Background tasks are not down here: a live card is a row in
+  the **Background** panel directly under Terminals (see below), and only the
+  finished ones collapse into a ledger line beside these counts.
 
 The board reads `~/.leg/sessions/*/session.json` over server-sent events; a
 session whose runner process is gone is marked `lost`, never shown as live.
@@ -547,17 +571,23 @@ terminal this is when the board is shared), `LEG_TLS_CERT` / `LEG_TLS_KEY`
 
 Version 0.1 was the other way round: you dropped a task card on the board and
 Leg ran the agents headless in a git worktree, one per card, with a fallback
-chain, path leases, a scheduler and a merge queue. All of that still works and
-lives below the terminals lane, but it is no longer the way in.
-
-The New background card form starts with a repo, task, and real first agent.
-**Run now** queues it; turning that off saves a draft in Backlog. The default
-**Build only** workflow stops with its changes in the card's worktree and does
-not merge them. The Advanced **Build, test, and merge** and **Factory**
-workflows include an automatic land station; their labels say so before you
-choose them. Fallback agents, permissions, approval gates, turn caps, leases,
-trunk, merge method, tests, title, and scripted test/demo adapters are also
-under Advanced options.
+chain, path leases, a scheduler and a merge queue. All of that still runs, and
+a card is now a terminal you are not sitting at: same register, same one
+sentence, same ladder, same bundle. Live cards are rows in the **Background**
+panel directly under Terminals; finished ones fall into one ledger line that
+opens.
+
+Starting one is a single field. `Run in the background:` takes the task, and
+the sentence under it is inferred with its nouns as buttons: the repo of the
+terminal you were last in, the saved ladder, and the `build` workflow, which
+stops with its changes in the card's worktree and does not merge them.
+**More settings** is the full form, with the **Build, test, and merge** and
+**Factory** workflows that include an automatic land station, plus fallback
+agents, permissions, approval gates, turn caps, leases, trunk, merge method,
+tests, title, and scripted test and demo adapters. **End, and keep going as a
+card** on a terminal's End row makes a card out of the work in front of you;
+**Take over** on a card gives you the command that turns it back into a
+terminal.
 
 - `leg up` boots the board with the scheduler and merge queue and streams
   redacted logs; `leg card add --repo <path> --task "<t>" --chain claude,codex --queue`
@@ -684,7 +714,7 @@ Leg is commercial software under the [Leg License Agreement](LICENSE).
 It ships as readable JavaScript so you can see what it does on your machine,
 and you may modify it for your own use, but not redistribute it or work
 around the license check. Versions 0.2.0 and 0.3.0 were published under MIT
-and remain available. The version in this source tree is 0.8.0; see
+and remain available. The version in this source tree is 0.12.0; see
 [npm](https://www.npmjs.com/package/legcli) for published versions and
 [CHANGELOG.md](CHANGELOG.md) for release notes.
 

package/bin/leg.mjs

@@ -20,10 +20,11 @@ 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, scheme, tlsConfigured, ROLES } from '../src/share.mjs'
-import { normalizeHandoffOrder } from '../src/preferences.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, readAccounts, LAYOUT } from '../src/accounts.mjs'
-import { listUsage, fmtReset, readUsage, isAvailable, candidates } from '../src/usage.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'
@@ -73,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)}`)
@@ -100,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 ?? '-'})` : ''
@@ -172,16 +263,19 @@ async function main() {
       // 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 [wantAgent, wantAccount = 'default'] = args.to.split('/')
+        const want = parseTarget(args.to, { die })
         const order = normalizeHandoffOrder(s.handoff_order)
-        const chain = candidates({ agent: s.agent, account: s.account, accounts: readAccounts(), order })
-        const hit = chain.find((c) => c.agent === wantAgent && c.account === wantAccount)
-        const label = `${wantAgent}${wantAccount !== 'default' ? '/' + wantAccount : ''}`
-        if (!hit) die(2, `${label} is not a destination for this terminal (${chain.map((c) => c.agent + (c.account !== 'default' ? '/' + c.account : '')).join(', ') || 'none'})`)
-        if (s.installed && s.installed[wantAgent] === false) die(3, `${label} is not installed on this machine`)
-        const u = readUsage(wantAgent, wantAccount)
+        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`)
-        requestControl(id, { handoff: true, target: hit })
+        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 })
@@ -205,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
@@ -511,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`).