@ucsandman/legcli 0.11.0 → 0.13.0

package/docs/cli-contracts.md

@@ -243,26 +243,78 @@ variable and `LEG_SESSION` (source: src/attach.mjs, src/env.mjs).
 
 ### claude tap
 
-- Attach: `claude <args> --settings <LEG_HOME>/sessions/<id>/claude-settings.json`
+- Attach: `claude <args> -n "leg#<short id> <repo>/<branch>" --settings <LEG_HOME>/sessions/<id>/claude-settings.json`
   (source: src/attach.mjs `spawnSpec`; src/taps/claude.mjs `writeSettings`).
   Hooks in a `--settings` file merge with the user's rather than replacing
   them; `statusLine` is the one key that replaces, so Leg runs the user's own
   command first (source: code.claude.com/docs/en/settings;
   src/taps/claude.mjs `userStatusLine`). observed-live 2026-09-11: a Leg
   session ran with every user hook still firing.
+- Terminal title: `-n, --name <name>` "Set a display name for this session
+  (shown in the prompt box, /resume picker, and terminal title)" —
+  fixtures/help/claude.txt line 132. It sits in the general Options block, not
+  among the flags marked "only works with --print", and two of its three
+  surfaces (the prompt box, the `/resume` picker) exist only in interactive
+  mode, so it is the interactive title flag. Leg passes
+  `leg#<short id> <repo>/<branch>`; a `-n` or `--name` the human passed is
+  never overwritten. codex, agy and grok have no such flag, so Leg writes OSC 2
+  (`\x1b]2;leg#7f3a leg/main\x07`) to stdout once before the child spawns, and
+  only on a TTY. **ASSUMED**: that the child does not overwrite the title once
+  it starts drawing; no terminal has been read either way yet.
 - Hooks written (source: src/taps/claude.mjs `settingsFor`): `SessionStart`,
   `UserPromptSubmit`, `PostToolUse` with matcher `Edit|Write|MultiEdit|NotebookEdit`,
+  `Notification` with matcher
+  `permission_prompt|idle_prompt|agent_needs_input|quota_auto_resume_fired`,
   `Stop`, `StopFailure`, `SessionEnd`, each
   `node <src>/hook.mjs claude-hook --session <id>` with a 20 s timeout.
-  observed-live 2026-09-11 (hook.log in the session directory).
+  observed-live 2026-09-11 for the six that shipped then (hook.log in the
+  session directory); the `Notification` entry is docs-only until a real
+  permission prompt is captured.
+- Waiting on a human: the `Notification` hook. It "matches on notification
+  type" and, not being one of the two narrower events (FileChanged,
+  StopFailure), takes `|` as its alternation separator
+  (https://code.claude.com/docs/en/hooks lines 1424, 173, 165). The payload
+  carries `message`, an optional `title` and `notification_type` (line 1480).
+  `permission_prompt`, `idle_prompt` and `agent_needs_input` write
+  `session.waiting = { type, message (verbatim, 160 chars), since }`;
+  `UserPromptSubmit` and `Stop` clear it. `permission_prompt` fires only after
+  the prompt has waited about six seconds and shares its timing with desktop
+  notifications, so in a terminal it arrives only when the human appears to be
+  away (lines 1162, 1443): "waiting on you" is late by design and must not be
+  sold as instant.
+- The toast: the hook prints `{"terminalSequence":"\x1b]9;<message>\x07"}`.
+  Notification hooks cannot block or modify anything and their `systemMessage`
+  and `continue` are discarded, but Claude Code still emits `terminalSequence`
+  for them (lines 1490, 622). The field is restricted to OSC 0/1/2/9/99/777 and
+  BEL, and is ignored wholesale if anything outside that rides in it (line
+  608), so control bytes in the message are stripped first. OSC 9 is what
+  Windows Terminal, iTerm2, ConEmu and WezTerm render (line 617). Gated on
+  `preferences.notify_terminal`, default true.
 - `autoContinueAtUsageLimit: false` in the same file, because Leg owns the
-  hand-off (source: src/taps/claude.mjs `settingsFor`).
+  hand-off (source: src/taps/claude.mjs `settingsFor`). If the human's own
+  settings re-enable it, the `quota_auto_resume_fired` notification arrives
+  anyway; Leg then writes `waiting = { type: 'quota_auto_resume' }` and the
+  automatic hand-off stands down for that terminal (src/attach.mjs
+  `handoffStoodDown`). Two waiters on one terminal is the failure to avoid.
+- The model that answered: each assistant line of the transcript carries
+  `message.model` (VERIFIED: 29 lines of the newest jsonl for this repo read
+  `claude-fable-5-1`). The runner reads the tail of that file on the usage poll
+  and says it as its alias (`fable`), so a silent fallback off Fable shows on
+  the row; an id matching no alias is kept raw (src/taps/claude.mjs
+  `modelFromTranscript`, `modelAlias`).
 - Usage: `GET https://api.anthropic.com/api/oauth/usage`
   (`LEG_CLAUDE_USAGE_URL` overrides) with `Authorization: Bearer <accessToken>`
   from `<CLAUDE_CONFIG_DIR>/.credentials.json` key `claudeAiOauth`, and header
   `anthropic-beta: oauth-2025-04-20`; response fields `five_hour` and
   `seven_day`, each `{ utilization, resets_at }`; polled every
   `LEG_USAGE_POLL_MS` ms, default 60000 (source: src/taps/claude-usage.mjs).
+  A `limits[]` array, when the response carries one, becomes the per-model
+  buckets; a row's `scope.model.display_name` is joined to the alias the rest of
+  Leg uses by matching a known name as a whole word, so `Fable 5.1` and
+  `Claude Opus 5` are `fable` and `opus` and a name Leg does not know keeps its
+  own lowercased text. A response with no `limits` key is an older endpoint
+  answering: the key is omitted rather than sent as `[]`, because that is no
+  information about buckets and must not erase the measured ones.
   observed-live 2026-09-11: real windows came back and were written to
   `<LEG_HOME>/usage/claude--default.json`; a seven_day window at 93 %
   raised the amber warning.
@@ -386,7 +438,11 @@ variable and `LEG_SESSION` (source: src/attach.mjs, src/env.mjs).
 
 - `<LEG_HOME>/usage/<agent>--<account>.json`:
   `{ five_hour: {pct, resets_at}, seven_day: {…}, limited_until,
-  limited_reason, source, updated_at }` (source: src/usage.mjs).
+  limited_reason, source, updated_at, buckets, walls, history, extra_usage,
+  facts }` (source: src/usage.mjs). The last five are the per-model half of the
+  record: measured buckets, walls attributed from wording, a 24-sample ring per
+  bucket, the credits block and agent-measured strings. See
+  [concepts.md](concepts.md).
 - Warning threshold `WARN_PCT`, default 85, from `LEG_WARN_PCT`; the warning
   is an amber card, an event, and one terminal bell (source: src/usage.mjs,
   src/attach.mjs).
@@ -410,6 +466,184 @@ in [VOCABULARY.md](VOCABULARY.md). Board routes: `GET /api/sessions`,
 `POST /api/sessions/:id/end`, `DELETE /api/sessions/:id`, with the list pushed
 as the SSE `sessions` event (source: src/server.mjs, src/board/sessions.js).
 
+`session.ahead` is the number of commits the checkout is past its upstream, or
+past `head_at_start` when it tracks nothing. It is counted with `git rev-list
+--count <base>..HEAD` on the runner's git poll and is `null`, never `0`, when
+this is not a repository or the count could not be taken (source:
+src/attach.mjs `aheadCount`). Like the dirty file list, it is owner-only:
+`redactSession` drops it from another human's row.
+
+`GET /api/sessions` also carries `cards_waiting`, so the terminals verdict can
+name a waiting card without reading the pipeline board:
+`{count, first: {id, title, station, since}}`, where `count` is the number
+of cards in `needs_approval` or `waiting_human` and `first` is the one that has
+been waiting longest (`since` is its `updated_at`), or `null` when none is. A
+count alone cannot write `card 3e1c has waited on you for 12 minutes.`, which
+is the sentence the field exists for (redesign C.5). It is sent to anyone who
+may use cards, which is the owner and any operator; a guest has no cards and is
+not sent it (source: src/server.mjs `cardsWaiting`).
+
+A guest's own row carries no figure that was measured from this machine's
+logins: `limits`, `all_out` and `usage_source` are dropped, `warning` keeps its
+window and loses its percentage and its clock, a
+`limit` or a `waiting` of type `reset` keeps its words and loses its
+`resets_at`, and a `handoff_targets` row carries no `cost` (the word `credits`
+on a `claude/fable` rung is the owner's `extra_usage` setting by another name).
+A row that is available carries no reason at all, because the reserve and
+`below:N` notes are advice for a human press, not a refusal. Someone else's row
+is redacted further: no `limits`, and `warning` is reduced to its window
+(source: src/server.mjs `redactSession`, `scrubOwnerUsage`).
+
+### Making a card over HTTP
+
+`POST /api/cards` takes the same body `createCard` takes from the CLI, with one
+difference: `pipeline` must be a preset name (`build`, `build-land`, `factory`)
+or an inline array of stations. A path to a JSON file is a CLI convenience
+(`leg card add --pipeline ./my.json`) and is refused here with `400
+invalid pipeline: pipeline must be one of the presets ... or a list of
+stations`, naming no path and quoting no bytes: an operator may post cards and
+may not read this machine, and the JSON parser's own message quotes the first
+characters of whatever file it opened (source: src/cards.mjs
+`allowPipelineFile`).
+
+`chain` is a comma list (`claude,codex`) or an array of entries
+(`[{adapter, model?, mode?, max_turns?}]`). The array form is what the board's
+one-line entry posts, because it is the only one that can put a different model
+on each leg: `[{adapter: 'claude', model: 'fable'}, {adapter: 'claude', model:
+'opus'}]` is two legs on one login, which `--model claude=fable` (one model per
+adapter) cannot express.
+
+### A terminal becomes a card, and a card becomes a terminal
+
+`POST /api/sessions/:id/end-as-card` (owner or operator; a guest is refused)
+writes the terminal's hand-off bundle with `saveSessionBundle`, creates a card
+whose task is the terminal's prompt plus `Continue from the bundle at <path>.`,
+starts the card's chain at the rung the terminal is standing on, records
+`lineage.from`, and then requests `end` on the terminal exactly as
+`POST /api/sessions/:id/end` does. `201` with
+`{card, bundle, carried: {files, adopted}}`. Where the card works, and when it
+starts, depend on what the terminal had:
+
+- **Its own worktree.** The card adopts it (`worktree_adopted: true`, so no
+  later run cuts a second worktree on that branch) and is created in
+  `backlog`, not `queued`: `end` is a request the terminal's runner reads on
+  its own poll, and the scheduler ticks once a second, so queuing it at once
+  would put a headless agent in the working tree the interactive one is still
+  writing to. The board polls the session record and enqueues the card the
+  moment it is no longer active; if the terminal is still going ten minutes
+  later, the card stays in the backlog with a `blocked_by` line saying so and
+  Run is left to the human. `heldByLiveTerminal` in src/scheduler.mjs refuses
+  to start such a card whatever queued it.
+- **No worktree of its own** (the ordinary case: a terminal cuts one only when
+  a second live session shares the checkout). A checkout of its own is cut from
+  the terminal's branch and the uncommitted work is carried into it before the
+  terminal is asked to stop: a patch of everything git tracks
+  (`git diff HEAD --binary`, applied with `git apply`) plus the bytes of every
+  file it does not (`git ls-files --others --exclude-standard`, skipping Leg's
+  own directories and `node_modules`). `carried.files` is how many paths moved.
+  The card is queued at once, because nothing else is in that checkout.
+
+The bundle is written first, and the uncommitted work is read before anything
+is created: if either fails, nothing is created, nothing is ended, and the
+terminal is left running with `409` (source: src/server.mjs).
+
+`POST /api/cards/:id/take-over` moves the card to `paused` through the
+`take_over` transition, killing the child of a running one, and answers `200`
+with `{card, command}`, where `command` is `leg <agent> --resume-card <card-id>`
+for the agent on the card's current leg. Every non-terminal status is paused,
+not only `running`: a `queued` or `handing_off` card is in the set the
+scheduler starts from, so leaving it there would launch a leg into the same
+worktree the human was just handed. One `taken_over` event with the caller's
+name is appended whatever the starting status, and it is in the audit trail. A
+card in `done`, `failed` or `killed` is refused with `409` (source:
+src/server.mjs, src/chain.mjs).
+
+`leg <agent> --resume-card <id>` is Leg's own flag and never reaches the
+agent's argv. It opens an ordinary interactive terminal in that card's
+worktree, whatever directory it was run from, primed with the card's bundle as
+the first prompt and with `lineage.from` naming the card. The id may be the
+full card id or a unique tail of it; an ambiguous one is refused by name with
+the matches listed, and an unknown one exits `3` (source: src/attach.mjs
+`takeFlagValue`, `resolveCardId`, `takeOverPrompt`).
+
+A live card's board payload carries what was measured and nothing else: `work`
+`{files, insertions, deletions}` parsed from `git diff --shortstat
+<trunk>..HEAD` in its worktree, `tests` `{state, at}` and `land` `{state,
+reason, sha}` read from the card's own ledger. A key that could not be measured
+is absent; a finished card carries none of them (source: src/server.mjs
+`parseShortstat`, `cardOutcomes`, `summarize`).
+
+### The hand-off ladder
+
+`leg sessions handoff <id> --to <agent>[/<account>[/<model>]]` names the rung
+directly. Three parts are unambiguous; with two, the second is read as an
+account when the agent has one by that name, else as a model when the agent
+has one by that name, else the command is refused by name rather than guessed
+at (source: bin/leg.mjs `parseTarget`). `leg sessions simulate-limit <id>
+--message "<text>"` drives that exact wording through the real classifier
+(`src/hook.mjs` for claude, the session's own log for agy and grok), which is
+how a per-model wall is reached without waiting for a real one; codex has no
+Leg-owned input to simulate through and is refused by name (source:
+bin/leg.mjs `simulateLimit`).
+
+`leg ladder` (also `leg ladder ls`) prints the ladder, rung 1 first, each with
+its live state (a wall and its clock, a percentage, or "no figure") and the
+reason it would be skipped right now, then the spending, climb-back, reserve
+and derived-order lines. `leg ladder set <n> <agent>[/<account>[/<model>]]
+[--when always|below:N|walled-only]` writes rung `n` (past the end of the
+ladder, it appends); `leg ladder rm <n>` removes rung `n` and refuses to
+remove the last rung left; `leg ladder spend on|off` flips `may_spend`
+(source: bin/leg.mjs `ladderCommand`).
+
+Board routes: `PATCH /api/settings` (owner only) also accepts
+`handoff_ladder`, `climb_back`, `may_spend`, `reserve`, `notify_terminal` and
+`notify_board`. `POST /api/sessions/:id/handoff-order` accepts either
+`{handoff_order}` or `{handoff_ladder}` and rewrites both on the session.
+`POST /api/sessions/:id/handoff` accepts `target.model` alongside
+`target.agent` and `target.account` (source: src/server.mjs).
+
+### GET /api/models
+
+The models this machine can start each agent on, so a rung and a card can name
+one. Owner and operator only; a guest gets the same 403 `/api/adapters` and
+`/api/presets` give, because picking a model is spending the owner's plan
+(source: src/server.mjs, src/models.mjs).
+
+```json
+{
+  "models": {
+    "claude": [{ "id": "fable", "label": "Claude Fable", "default": false }],
+    "codex":  [{ "id": "gpt-6-astra", "label": "GPT-6-Astra", "default": true }],
+    "agy":    [{ "id": "gemini-3.8-flash-high", "label": "Gemini 3.8 Flash (High)", "default": false }],
+    "grok":   [{ "id": "grok-4.6", "label": "grok-4.6", "default": true }]
+  },
+  "observed_at": "2026-09-18T14:37:01.577Z"
+}
+```
+
+Where each list comes from, all observed live on 2026-09-18 and captured under
+`fixtures/models/`:
+
+| agent | source | today's ids | default |
+|-------|--------|-------------|---------|
+| claude | `MODEL_ALIASES.claude` in src/buckets.mjs; four aliases Claude Code resolves itself, not service-side ids | `fable`, `opus`, `sonnet`, `haiku` | none: a bare `claude` picks for itself, and naming one would be Leg making a choice nobody made |
+| codex | `<CODEX_HOME>/models_cache.json`, `models[]` where `visibility` is `"list"` (`"hide"` covers `gpt-reserve` and `codex-auto-review`) | `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5` | the top-level `model = "..."` in `<CODEX_HOME>/config.toml`, never a `[profiles.x]` one |
+| agy | `agy models`, one `id<TAB>label` per line after a `Fetching available models...` line | 14, from `gemini-3.8-flash-high` to `gpt-oss-120b-medium`, including `claude-opus-4-6-thinking` | agy publishes none |
+| grok | `grok models`, `  * id (default)` / `  - id` bullets under a `Default model: X` line; it lists them even when it is not logged in | `grok-4.6`, `grok-4.5` | `grok-4.6` |
+
+`agy` and `grok` each cost a process, so their answers are cached in
+`<LEG_HOME>/models/<agent>.json` for an hour with a 20s probe timeout. A request
+never waits on one: the cached list is served and the refresh runs behind the
+answer. A probe that fails leaves the cache exactly as it was.
+
+An id from any of these lists may go on a ladder rung's `model` and on a card's
+chain entry, and reaches the CLI through `modelFlagFor` in src/buckets.mjs
+(`claude --model`, `agy --model`, `codex -m`, `grok -m`). Rung validation is by
+SHAPE for every agent (`/^[a-z0-9][a-z0-9._:-]{0,63}$/`, so a flag or a path can
+never become an argv element) and by MEMBERSHIP for claude alone, whose list is
+closed; the other three catalogs are live and the CLI itself is the authority on
+its own.
+
 ### History index
 
 `<LEG_HOME>/history/index.json` is the one file `leg history` writes: per
@@ -447,12 +681,13 @@ non-zero exit → `failed`. Every outcome except `completed`, `auth_failed` and
 `killed` asks the chain to hand off.
 
 <!-- limits-table:start -->
-Generated by `node scripts/limits-table.mjs` from 22 fixtures (4 observed-live, 18 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Leg itself; `info` must never classify as a limit.
+Generated by `node scripts/limits-table.mjs` from 24 fixtures (6 observed-live, 18 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Leg itself; `info` must never classify as a limit.
 
 | id | adapter | class | where | source | text (excerpt) | produced by |
 |----|---------|-------|-------|--------|----------------|-------------|
 | agy-resource-exhausted | agy | limit | any | **docs-only** | resource-exhausted | `agy changelog` ("Fixed personal accounts hitting a resource-exhausted error at startup"); agy --help documents no limit wording; falls back to the generic matchers |
 | claude-budget-limit | claude | budget | any | **docs-only** | Budget limit reached | https://code.claude.com/docs/en/cli-reference (--max-budget-usd) |
+| claude-fable-limit | claude | limit | any | **observed-live** | You've reached your Fable limit. Run /usage-credits to continue or switch models with /mod | fixtures/live/claude/limit-rate_limit.json: StopFailure error rate_limit, last_assistant_message on the real run, 2026-09-11 (a per-model wall: the account's session and weekly windows were open) |
 | claude-max-turns | claude | budget | stdout | **observed-live** | {"type":"result","subtype":"error_max_turns","is_error":true,"stop_reason":"tool_use","ter | fixtures/real-run/leg1/out.log: `claude -p --max-turns 2` on the real run, 2026-09-10 (docs: https://code.claude.com/docs/en/cli-reference --max-turns "Exits with an error when the limit is reached") |
 | claude-model-limit | claude | limit | any | **docs-only** | You’ve hit your Opus limit | https://code.claude.com/docs/en/costs ("You’ve hit your Opus limit" / "You’ve hit your Sonnet limit") |
 | claude-session-limit | claude | limit | any | **docs-only** | You’ve hit your session limit | https://code.claude.com/docs/en/costs (section: When a developer asks about a limit) |
@@ -468,6 +703,7 @@ Generated by `node scripts/limits-table.mjs` from 22 fixtures (4 observed-live,
 | generic-rate-limit | * | limit | any | **docs-only** | rate limit | generic matcher; lowest priority |
 | generic-resource-exhausted | * | limit | any | **docs-only** | RESOURCE_EXHAUSTED | generic matcher (gRPC RESOURCE_EXHAUSTED); lowest priority |
 | generic-usage-limit | * | limit | any | **docs-only** | usage limit | generic matcher; lowest priority |
+| grok-balance-exhausted | grok | limit | any | **observed-live** | API error (status 402 Payment Required): Grok Build usage balance exhausted | grok 1.0.34 -p --output-format json on an account with no balance left, 2026-09-17: stdout {"type":"error","message":"Internal error: {   \"message\": \"API error (status 402 Payment Required): Grok Build usage balance exhausted\",   \"http_status\": 402 }"}, exit 1 |
 | grok-not-logged-in | grok | auth | stderr | **observed-live** | To sign in, open this URL in your browser:    https://accounts.x.ai/oauth2/device?user_cod | fixtures/live/grok/err.log from scripts/probe.mjs --adapter grok, 2026-09-10 (stdout JSON stopReason: Cancelled, exit 0) |
 | grok-rate-limit | grok | limit | any | **docs-only** | You've hit the rate limit for your plan. Try again later. | crates/codegen/xai-grok-shell/src/sampling/error.rs:18 (RATE_LIMITED_USER_MESSAGE_OAUTH: "You've hit the rate limit for your plan. Try again later.") |
 | auth-source-set | * | auth | stderr | **docs-only** | another auth source is set | project brief (Wes, 2026-09-10): stderr saying "another auth source is set" counts as a failed launch; wording not yet observed live |

package/docs/concepts.md

@@ -33,6 +33,28 @@ A session's status is one of `starting`, `running`, `warning`, `limit`,
 that owned the terminal is gone (closed window, crash); the board never shows
 it as live.
 
+Two fields on `session.json` say what the row is running and what it is stuck
+on. `model` is the model this leg resolved to: the `--model` or `-m` the human
+passed, else null. It is never a guessed default, because a model token nobody
+chose is a wrong number in disguise. For claude the runner corrects it from the
+transcript's per-message `model` while the agent works, so a silent fallback
+off Fable is visible instead of being reported as the model you asked for.
+
+`waiting` is null, or what this terminal is waiting for, in one of two shapes
+told apart by `type`. `{ type: 'reset', agent, account, resets_at, since }` is
+the all-out countdown: every option is walled and the terminal is waiting for
+the first one back. `{ type, message, since }` with `type` one of
+`permission_prompt`, `idle_prompt`, `agent_needs_input` or `quota_auto_resume`
+is a human being waited on, from Claude Code's `Notification` hook (claude
+sessions only); `message` is the question verbatim, cut at 160 characters, and
+the next prompt or the end of the turn clears it. `quota_auto_resume` means
+Claude Code is waiting at the limit by itself, and Leg's automatic hand-off
+stands down for that terminal rather than making it wait twice.
+
+Both are owner-only on a shared board, and a guest keeps both on their own
+terminal: a terminal stopped at a permission prompt is useless to the person
+sitting at it if the board will not say so, and it is nobody else's business.
+
 The board is started detached on `127.0.0.1:4747` by the first session that
 finds it down, and opened once. Later sessions reuse it.
 
@@ -69,9 +91,32 @@ keeps the latest reading per (agent, account) in
 
 ```
 { five_hour: {pct, resets_at}, seven_day: {pct, resets_at},
-  limited_until, limited_reason, source, updated_at }
+  limited_until, limited_reason, source, updated_at,
+  buckets, walls, history, extra_usage, facts }
 ```
 
+A login can be limited per model as well as per account, so the record carries
+both kinds of fact and keeps them apart. `buckets` is measured: one row per
+bucket the agent publishes (`{kind, group, model, percent, resets_at,
+is_active, severity}`, from Claude's `limits[]`), and `binding(u, model)` picks
+the row that will actually stop a terminal. `walls` is attributed from wording
+rather than measured: `bucketFromWall()` in `src/buckets.mjs` reads the wall
+message, and a model-scoped wall goes to `walls[model]` while the login stays
+open, so a Fable wall never stops `claude/sonnet`; a model wall with no clock of
+its own is dated from that model's bucket, else from the weekly window, because
+a per-model limit is a weekly fact and the five-hour clock would hand the model
+back within the hour. `history` is a ring per bucket, capped by the clock first
+and by 24 samples second: at most one sample a minute, none older than the
+window it was measured in, and started again whenever that window resets (each
+sample carries its own `resets_at`, so a bucket that is missing from one reading
+cannot carry its old samples into the next window). Capping by count alone made
+the forecast vanish from any login with three terminals on it, because three
+pollers fill the ring three times as fast. `extra_usage` is the credits
+sentence, and `facts` holds strings the
+agent measured itself (codex's `plan_type` and `credits_balance`). An older Leg
+reading this file ignores all five, and an agent that publishes no buckets
+leaves them empty.
+
 Where each number comes from is per agent, and is in
 [adapters.md](adapters.md). The rules on top of them are shared:
 
@@ -79,15 +124,34 @@ Where each number comes from is per agent, and is in
   highest percentage across the known windows is the pressure; the hottest
   window names the warning.
 - **Wall.** `markLimited()` records `limited_until` from the reset time the CLI
-  itself reported. With no reset time it uses the soonest known window reset,
-  and with neither it assumes five hours.
+  itself reported. With no reset time, an account wall takes the window that
+  actually walled (the highest used percentage, so a weekly wall is not
+  recorded as the five-hour window's near reset) and a model wall takes that
+  model's own bucket, else the weekly window. With neither it assumes five
+  hours.
 - **Clearing.** A usage reading that arrives after `limited_until` has passed
   clears the wall.
 
 ## Handoff (interactive)
 
+A hand-off destination is a **rung**, not just an agent: `{agent, account,
+model, when, cost}`. A rung can name a model, so a hand-off can move from
+`claude/fable` to `claude/opus` without leaving the login, or it can leave the
+model out and behave exactly like the plain agent destinations Leg has always
+had. `preferences.json` keeps an ordered list of rungs, the **ladder**, tried
+top first (`src/preferences.mjs`; the keys are documented in
+[configuration.md](configuration.md)). `handoff_order`, the older list of
+agents, is never removed: it is derived from the ladder's distinct agent order
+every time the ladder is saved, so a reader that has never heard of rungs sees
+the same order it always did.
+
 When a session hits its limit, or you press **Hand off now**, Leg does four
-things in order (`src/attach.mjs`, `src/bundle.mjs`):
+things in order (`src/attach.mjs`, `src/bundle.mjs`). Which of the two it was
+decides the gates below: a hand-off nobody asked for (the usage limit, and a
+card the scheduler is driving) is **automatic** and keeps the `reserve` and the
+`climb_back` policy; pressing **Hand off now** is a human pick and is not held
+back by either, with or without a named destination, because the default option
+in that picker ("the next option in the order") is still a press of the button.
 
 1. **Bundle.** `sessionNotes()` writes the six sections
    `context-handoff-bundle` parses (Scope, Projects mentioned, Findings,
@@ -99,17 +163,44 @@ things in order (`src/attach.mjs`, `src/bundle.mjs`):
    in place. A checkpoint runs about every two minutes while the session has
    turns, and at every warning, limit and hand-off.
 2. **Choose.** `candidates()` lists the other accounts of the same agent first,
-   then every other agent in the terminal's saved order. That order is an
-   absolute priority list, not a rotation anchored on the agent running now:
-   an agent placed last is tried last whichever agent the terminal started on,
-   and every option is still tried once. The default order is claude, codex,
-   agy. `chooseNext()` skips a missing CLI or an option whose wall has not
-   reset. The board can save a new order for an active terminal; the wrapper reads
-   it again at the transition and during all-out waiting. Machine Settings is
-   copied only when a new terminal starts.
-3. **Switch.** The agent process is stopped and the terminal restored. The
-   bundle's `context-handoff-bundle load <id>` output (with the `## Synthesis`
-   section prepended if `.leg/SYNTHESIS-<session-id>.md` is present) is written to
+   then walks the ladder, and after each rung, the other accounts of that
+   rung's agent. `evaluateLadder()` walks that list top to bottom and takes the
+   first rung that clears every gate, checked in this order: the agent is
+   installed on this machine; the rung was not excluded for this hand-off; its
+   live cost (`rungCost()`, computed from usage, never trusted from disk) is
+   `free` or `plan`, or `may_spend` is on, else the rung is skipped with the
+   reason `it spends usage credits and you have not allowed that`; the rung
+   sits on the same login the terminal just fell off of and what stopped that
+   login is its own account-wide window, in which case another model there
+   cannot help and the rung is skipped as `shares the window that is out, buys
+   nothing`, whatever model it names; the account itself is not walled; the
+   model, if the rung names one, is not walled; on an automatic hand-off with
+   `climb_back` set to `never`, the rung is not a stronger model of the login
+   the terminal just left (a human's own pick still reaches it; only an
+   automatic climb is held back); the rung's login is not past its `reserve`
+   floor; and its `when` is satisfied (`always`; `below:N`, which needs the
+   rung's own bucket to read under N percent and is skipped with a reason when
+   there is no reading, because a threshold on a login with no figure is a
+   wrong number in disguise; `walled-only`, which only opens once no rung above
+   it could take the hand-off anyway: walled, at 100 percent, not installed on
+   this machine, or refused for this hand-off, but not merely slow and not
+   merely dearer than `may_spend` allows). Every rung the walk passes before the one it picks is
+   named in the session's ledger with its reason, one line each, for example
+   `skipped claude/fable: it spends usage credits and you have not allowed
+   that`; a rung is never passed over silently. The board can save a new
+   ladder for an active terminal; the wrapper reads it again at the transition
+   and during all-out waiting. Machine Settings is copied only when a new
+   terminal starts.
+3. **Switch.** The agent process is stopped and the terminal restored. A
+   same-login move to a weaker claude model (a downshift, by the
+   `fable, opus, sonnet, haiku` order) with the agent's own session id on the
+   record keeps the conversation instead: Leg runs
+   `claude --resume <agent_session_id> --model <alias>`, no bundle is written
+   into a prompt, and the ledger says so. Every other rung, including an
+   upshift back to a stronger model, a different account, or a different
+   agent, takes the bundle: the `context-handoff-bundle load <id>` output
+   (with the `## Synthesis` section prepended if
+   `.leg/SYNTHESIS-<session-id>.md` is present) is written to
    `.leg/RESUME-<session-id>.md` and copied to `.leg/RESUME.md`, and the next
    agent starts in the same terminal with a short pointer prompt as its first
    positional argument: `claude "<prompt>"`, `codex "<prompt>"`,
@@ -125,6 +216,13 @@ things in order (`src/attach.mjs`, `src/bundle.mjs`):
    (`{ agent, account, resets_at, since }`) and shows status `waiting`. Ctrl-C
    in the terminal, or End on the card, quits with exit 3.
 
+`climb_back` decides what happens once a lower rung's own login recovers.
+`next-handoff`, the default, needs no extra step: `chooseNext()` always walks
+from rung 1, so the next time this terminal hands off it is offered the
+higher rung again. `never` holds a terminal on the rung it downshifted to
+until a human hands it off there by name; an automatic hand-off will not walk
+back up on its own.
+
 ## The portable harness
 
 Off by default. `leg harness enable` adds a step to the hand-off, between
@@ -218,8 +316,54 @@ working; `leg share rotate <name>` replaces one.
 
 ## Cards, stations and pipelines
 
-Everything from here down is the v0.1 pipeline: headless agents in a git
-worktree, one per card. It has not changed since 0.2.0 and is not the way in.
+A **card is a terminal you are not sitting at.** It has the same register
+(state, where, model), the same one sentence, the same buttons, the same
+fallback ladder and the same hand-off bundle as a terminal. Two differences
+are real, and the board prints both: a card runs `-p --output-format json`,
+which says nothing until the leg exits, so its sentence reads `no message
+until this leg ends, started 11:04 PM`; and it never waits on a permission
+prompt, because its permissions are decided before it starts.
+
+Liveness decides where a card is drawn. A card in `backlog`, `queued`,
+`running`, `handing_off`, `needs_approval`, `waiting_human` or `paused` is a
+row in the Background panel under Terminals. A card in `done`, `failed` or
+`killed` is one line in the ledger: `3 finished cards, 2 done, 1 failed, last
+11:02 PM`. Ten finished cards are one row, not eleven.
+
+A live card's row carries a **work stat**, and only the parts of it that were
+measured: `4 files, +212 -18, tests green 6m ago`. The diff comes from `git
+diff --shortstat <trunk>..HEAD` run in the card's own worktree; the test and
+land verdicts come from that card's ledger. A part that was not measured is
+left off, never estimated.
+
+### A terminal becomes a card, and a card becomes a terminal
+
+`End, and keep going as a card` (the second verb on a terminal's End confirm
+row, `POST /api/sessions/<id>/end-as-card`) is for "I have to leave, keep
+going". It writes the terminal's hand-off bundle at the path every hand-off
+uses, creates a card whose task is the terminal's prompt plus `Continue from
+the bundle at <path>.`, and then ends the terminal exactly the way End does.
+The card **continues in the terminal's own worktree** rather than a fresh one:
+two worktrees on one branch is a conflict machine, and the card carries
+`worktree_adopted: true` so no later run cuts a second one over the top. Its
+chain starts at the rung the terminal was standing on, not at the top of the
+ladder, and `lineage.from` names the terminal it came from.
+
+`Take over` in a card's expansion (`POST /api/cards/<id>/take-over`) is the way
+back. It pauses the card, which kills its child and writes its bundle, then
+hands back one command:
+
+```
+leg claude --resume-card card-20260917-2234-add-the-audit-csv-export
+```
+
+That opens an ordinary interactive terminal in the card's worktree, primed
+from the card's bundle, with `lineage.from` naming the card. This is the one
+place Leg hands a human a command to paste, because a terminal cannot be
+opened from a browser tab, and the board says so on the line above it.
+
+Everything from here down is the v0.1 pipeline mechanism: headless agents in a
+git worktree, one per card.
 
 A **card** is one task moving through a **pipeline**: an ordered list of
 **stations**. A station has a `kind`:
@@ -345,7 +489,9 @@ Alongside raw state, Leg supports an agent-maintained judgment record in `.leg/S
 ## Worktrees
 
 Every card runs in its own git worktree: `<repo>/.leg-worktrees/<card-id>`
-on branch `leg/<card-id>` (`src/worktree.mjs`). The repo root is never
+on branch `leg/<card-id>` (`src/worktree.mjs`), with one exception: a card born
+from `End, and keep going as a card` adopts the terminal's worktree and works
+there, exactly where the terminal stopped. The repo root is never
 touched by an agent directly. Every git call sets `MSYS_NO_PATHCONV=1` so
 Git Bash on Windows does not rewrite absolute path arguments. Leg never
 pushes, opens a remote, or removes a path outside
@@ -423,7 +569,9 @@ status (`backlog`, `queued`, `running`, `handing_off`, `waiting_human`,
 `needs_approval`, `paused`) straight to `killed`, and `rerun` moves any
 terminal status (`done`, `failed`, `killed`) back to `queued` (station 0,
 leg 0). `reassign` also applies to any non-terminal status when the current
-station is an agent station, staying in `queued`.
+station is an agent station, staying in `queued`, and `take_over` moves any
+non-terminal status to `paused` (a human is taking the card's checkout, so the
+scheduler must not start a leg in it).
 
 ```mermaid
 stateDiagram-v2

package/docs/configuration.md

@@ -33,7 +33,8 @@ These apply to `leg claude|codex|agy|grok`.
 | `LEG_NO_OPEN` | (unset, opens once) | set to `1` to start the board without opening a browser | `bin/leg.mjs` |
 | `LEG_NO_BOARD` | (unset) | set to `1` to run a session with no board at all (the record under `$LEG_HOME/sessions/` is still kept; the test suite uses this) | `src/attach.mjs` |
 | `LEG_WAIT_TICK_MS` | `1000` | how often the all-out countdown redraws and re-checks Ctrl-C / End while waiting for the first reset | `src/attach.mjs` |
-| `LEG_USAGE_POLL_MS` | `60000` | how often an active attach polls its usage source; Claude uses its usage endpoint and Codex uses read-only app-server rate limits | `src/attach.mjs` |
+| `LEG_USAGE_POLL_MS` | `60000` | how often the board asks each login's usage source (one poller per login, not one per terminal); Claude uses its usage endpoint, Codex read-only app-server rate limits, Grok its billing proxy | `src/usage-poll.mjs` |
+| `LEG_USAGE_POLL_MAX_MS` | `600000` | the longest the board waits between readings for one login: a refusal (429, timeout, no login) doubles the wait up to this, and the first good reading puts it back to `LEG_USAGE_POLL_MS` | `src/usage-poll.mjs` |
 | `LEG_ATTACH_POLL_MS` | `2000` | how often the session loop re-reads the taps; git is re-read every third poll | `src/attach.mjs` |
 | `LEG_CLAUDE_USAGE_URL` | `https://api.anthropic.com/api/oauth/usage` | the usage endpoint, for a test double | `src/taps/claude-usage.mjs` |
 | `LEG_CLAUDE_ARGS`, `LEG_CODEX_ARGS`, `LEG_AGY_ARGS` | (none) | space-separated extra arguments for a leg Leg starts on its own after a hand-off (your own `leg <agent> …` args never apply to the next agent); e.g. `LEG_CODEX_ARGS="-m gpt-5.3-codex-spark"` keeps a test chain on cheap models | `src/attach.mjs` |
@@ -65,6 +66,69 @@ To opt out and keep standard approval prompts:
 2. Environment variable: set `LEG_AUTO_APPROVE=0` or `LEG_NO_AUTO_APPROVE=1` (or legacy `BATON_AUTO_APPROVE=0` / `BATON_NO_AUTO_APPROVE=1`).
 3. Persistent preference: set `"auto_approve": false` in `~/.leg/preferences.json`.
 
+### The hand-off ladder
+
+`~/.leg/preferences.json` also holds the ladder a terminal falls down when its
+login stops (`src/preferences.mjs`), alongside the older `handoff_order`:
+
+```json
+{
+  "handoff_order": ["claude", "codex", "agy"],
+  "handoff_ladder": [
+    { "agent": "claude", "account": "default", "model": "fable",  "when": "always", "cost": "plan" },
+    { "agent": "claude", "account": "default", "model": "opus",   "when": "always", "cost": "plan" },
+    { "agent": "claude", "account": "default", "model": "sonnet", "when": "always", "cost": "plan" },
+    { "agent": "codex",  "account": "default", "model": null,     "when": "always", "cost": "plan" },
+    { "agent": "agy",    "account": "default", "model": null,     "when": "always", "cost": "free" }
+  ],
+  "climb_back": "next-handoff",
+  "may_spend": false,
+  "reserve": {}
+}
+```
+
+| key | default | meaning |
+|-----|---------|---------|
+| `handoff_ladder` | `claude/fable`, `claude/opus`, `claude/sonnet`, then one rung per remaining agent in `handoff_order` with model `null` | the fallback list, rung 1 first; each rung is `{agent, account, model, when, cost}`. `model` is `null` or a model id that agent publishes: claude's four aliases are a closed list (`fable`, `opus`, `sonnet`, `haiku`, from `src/buckets.mjs` `MODEL_ALIASES`) and a fifth word is refused by name, while codex, agy and grok take any id from their own live catalog (`src/models.mjs` reads each CLI's, and the board's model picker offers it) as long as it matches the shape gate: lower-case letters, digits, `.`, `_`, `:` and `-`, 64 characters at most. `account` is `default` or a name this machine has for that agent (`leg accounts ls`); anything else is refused with a sentence, because that string becomes the CLI's config dir and the usage record's file name. `when` is `always`, `below:N`, or `walled-only`. `cost` is `free`, `plan`, `credits`, or `metered`, and is a static label; the live cost a rung would spend right now is computed from the agent and the login, never read off this key, so a ladder migrated from an older `handoff_order` still meets the spending gate on `grok` |
+| `climb_back` | `next-handoff` | `next-handoff` picks a recovered higher rung up again at the very next hand-off, with no extra step; `never` keeps a terminal on the rung it downshifted to until a human hands it off there by name |
+| `may_spend` | `false` | while `false`, an automatic hand-off skips any rung whose live cost is `credits` or `metered`, and records why; a human's own pick is not gated by this |
+| `reserve` | `{}` | `{ "<agent>": percent }`; an automatic hand-off will not take a rung on that login once its binding bucket is above `100 - percent`. A human's own pick still reaches it, and the picker names the reserve on that row instead of hiding it |
+
+A fresh install with no `preferences.json` starts with `claude/fable`,
+`claude/opus`, `claude/sonnet`, then every other installed agent from
+`handoff_order` with `model: null`.
+
+Leg writes `handoff_ladder` and `handoff_order` together and keeps them in
+step: saving a ladder rewrites `handoff_order` from its distinct agent order,
+and saving a bare `handoff_order` rewrites the ladder as one `model: null`
+rung per agent, so an older install behaves exactly as it did until a rung is
+edited. If the file is hand-edited so the two disagree, `handoff_order` wins
+and the ladder is rebuilt from it, because the order is the shape a hand
+edit is more likely to have meant.
+
+A rung Leg cannot read (a misspelt claude alias, an account this machine no
+longer has) is dropped on its own and the rest of the ladder is kept, and Leg
+never writes that shortened ladder back: the file keeps the rungs you typed
+until you save a ladder yourself, from the board or with `leg ladder set`.
+
+`leg ladder` (`leg ladder ls`) prints the ladder with each rung's live state;
+`leg ladder set <n> <agent>[/<account>[/<model>]]`, `leg ladder rm <n>` and
+`leg ladder spend on|off` change it. See [cli-contracts.md](cli-contracts.md).
+
+### Notifications
+
+`~/.leg/preferences.json` also holds two toggles for a terminal that is
+waiting on you (`src/preferences.mjs` `defaults()`):
+
+| key | default | meaning |
+|-----|---------|---------|
+| `notify_terminal` | `true` | "Terminal toast when a terminal waits on you": on Claude Code's own `Notification` hook (`permission_prompt`, `idle_prompt`, `agent_needs_input`), send an OSC 9 toast to the window the agent is already running in |
+| `notify_board` | `false` | "Browser notification when a terminal waits on you": fire a browser `Notification()` the moment a terminal row becomes `needsYou` and the reader is not looking at the board (a waiting card raises the tab badge and the verdict, not the notification); the board reads `window.isSecureContext` at render time and disables the toggle with an explanatory sentence where that is false |
+
+Both are set from Settings on the board, or by writing the key directly. The
+tab title badge (`(1) Leg` plus a favicon dot) has no toggle: it needs no
+permission, so it is always on.
+
 ## Core
 
 | variable | default | meaning | read in |