@ucsandman/legcli 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 0.13.0 (2026-09-18)
+
+The first day on 0.12.0 with three real terminals found five things. Usage
+polling moves out of the terminals into the board, so the endpoint stops
+answering 429 and the timeline stops repeating it. Every rung of a ladder can
+now name a model from a catalog Leg reads off the installed CLIs, and the new
+card form is rebuilt around that. The board holds still under a reader with a
+row expanded. The floor is a page you can start work from. And a page whose
+files are newer than the process serving them says so.
+
+- **One usage poll per login, in the board.** Every claude terminal used to
+  ask Claude's usage endpoint once a minute on its own; three terminals plus
+  Claude Code's own polling meant a 429 every other minute, and the terminal's
+  timeline logged `claude usage unavailable: usage endpoint 429: {...}` each
+  time the answer flipped. The board process now polls each login once per
+  `LEG_USAGE_POLL_MS` (60s), backs off to ten minutes on any refusal and snaps
+  back on the first good answer, and writes the two windows onto every active
+  session of that login. A refusal is recorded once on the usage record
+  (`error`, `error_since`, owner only) with one status line, `claude usage
+  unavailable since 9:03 AM: usage endpoint 429: rate_limit_error`, and one
+  `claude usage is back`; it never erases the measured buckets. Terminals
+  poll nothing, so a terminal started before this release keeps its old
+  minute-by-minute poll until it is restarted.
+- **A model catalog, read from the CLIs you have.** `GET /api/models` lists
+  what each provider can run today: claude's aliases (fable, opus, sonnet,
+  haiku); codex's `models_cache.json` entries with `visibility: list` plus the
+  default from `config.toml` (gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra,
+  gpt-5.6-luna, gpt-5.5 on the machine this shipped from); `agy models` and
+  `grok models`, each run at most once an hour behind the answer and cached
+  under `<LEG_HOME>/models/`. A rung's model is validated by shape for every
+  provider and by membership for claude only, so next month's codex model is
+  not refused and a saved ladder is never silently reset to the default.
+- **The new card form, rebuilt.** Task first, then the repository as a picker
+  of known repos or a typed path, the branch to cut from, and **Who runs it**:
+  one row per rung with provider, model, permissions, ask before start and max
+  turns, reorderable, prefilled from your ladder, with **Save as my default
+  ladder** writing it back to Settings. Advanced holds the workflow, scripted
+  first agent, leases, merge method, test command and title. The dialog posts
+  its chain as one object per rung, so `claude/fable` then `claude/opus` is
+  finally two legs and not one. Two columns at 900px, one below; it scrolls on
+  a short window instead of hiding Create card below the fold.
+- **The one-line entry row is never empty.** It derives its rungs from
+  `handoff_order` when a preferences file predates ladders, the ladder noun
+  opens both the rung and the model selects, and with only metered providers
+  and spending off it says so instead of "no agent is configured".
+- **The board holds still.** With a row expanded, a text selection live, the
+  pointer on a row or focus in the list, the needs-you re-sort is computed but
+  not drawn until you come out (hover and focus release after 30s on their
+  own). The expansion is never detached from the document, so its selection,
+  scroll offsets and open confirm row survive every 3-second poll; the
+  region's top is anchored against rows above it changing height; the
+  timeline appends new lines above you without moving what you read, and a
+  status line repeated word for word within a minute folds into one with
+  `×N`. `scripts/board-jump-probe.mjs` is the regression harness: it printed a
+  205px drift on 0.12.0 and 0px now.
+- **The floor is a page you start work from.** The four login panels move
+  behind the same **Capacity and models** disclosure as on the board, under
+  the same one-line strip; the **Run in the background** entry sits under it
+  and posts exactly what the board's does; Running, Waiting on you, Queued,
+  Backlog and Done today are Background-style rows with counts in their
+  headings, a queued row says its position and what it waits for, and j/k and
+  Enter work as on the board. `More settings` carries the typed task to the
+  board's dialog through `/#new-card=`. The strip and the entry row live once,
+  in `src/board/strip.js` and `src/board/entry.js`, loaded by both pages.
+- **A page newer than its process says so.** `/api/health` answers with the
+  process version; the page files carry theirs. When they differ the board and
+  the floor print `This board process runs leg 0.10.0 and the page files are
+  0.13.0. Restart it to match: leg down && leg up`, which is the state a board
+  left running across an `npm i -g` lands in, and the state that hid every
+  0.12.0 feature on the first morning.
+
 ## 0.12.0 (2026-09-17)
 
 The board is rebuilt around the two questions you actually open it to answer:

package/README.md

@@ -714,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.12.0; see
+and remain available. The version in this source tree is 0.13.0; see
 [npm](https://www.npmjs.com/package/legcli) for published versions and
 [CHANGELOG.md](CHANGELOG.md) for release notes.
 

package/docs/DECISIONS.md

@@ -2,6 +2,14 @@
 
 Durable product and design decisions that the code does not explain on its own. One entry per decision, newest first.
 
+## 2026-09-18: usage is polled by the board, once per login; a rung's model is a catalog entry validated by shape
+
+- **What.** The board process runs one usage poller per login (`src/usage-poll.mjs`): 60s, doubling to ten minutes on any refusal, one status line when a login's reading fails and one when it is back. Terminals poll nothing and receive the windows on their session record. `GET /api/models` lists what each installed CLI can run, read from claude's aliases, codex's `models_cache.json` and `config.toml`, and the `models` commands of agy and grok, cached an hour under `<LEG_HOME>/models/`. A rung's `model` is validated by shape (lower-case id characters) for every provider and by membership for claude only.
+- **Why the board and not the terminal.** The endpoint is per login and the reading is per login; a terminal is the wrong unit. Three terminals meant three polls a minute plus Claude Code's own, and the endpoint answered 429 every other minute. One poller per login is also the only shape that reads usage when no terminal is open, which is when a reader most wants the strip to be right. The cost is that a terminal started before this release keeps its own poll until it is restarted, which the timeline says.
+- **Why the failure is recorded once, on the record.** A 429 is a fact about the login, not an event in a terminal's life; logging it per poll per terminal made the timeline a wall of one sentence. The record carries `error` and `error_since`; the transition, not the state, is what a session sees.
+- **Why not freeze the catalog into validation.** `normalizeHandoffLadder` and `readPreferences` swallow a validation throw and fall back to the default ladder, so a catalog that refused next month's codex model would silently reset a saved ladder to `claude, codex, agy`. Shape validation refuses what would break a command line (`--model`, a space, an upper-case id that the normaliser would lower-case into a different id) and nothing else; the select is where membership lives, and an id that is not in the catalog is visibly absent from it rather than silently mangled.
+- **Why the page carries its own version.** A board started before `npm i -g` serves the new files from disk with the old process behind them; the first morning on 0.12.0 was spent on features the page drew and the process had no routes for. `/api/health` already said the process version; the page now says its own, and the two disagreeing is an error the reader can act on in one command.
+
 ## 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.

package/docs/ERRORS.md

@@ -583,6 +583,33 @@ it), and check whether a board was listening on 4747 at the time.
   cache keyed on a directory's mtime sees files added and removed, never a
   file rewritten in place.
 
+## The first morning on 0.12.0: a 0.10.0 process served the 0.12.0 page, and three terminals rate-limited the usage endpoint (2026-09-18)
+
+- **What happened.** Wes installed 0.12.0 and opened the board: no Fable
+  bucket anywhere, an empty agent select under "Run in the background", and a
+  timeline full of `claude usage unavailable: usage endpoint 429`. The board
+  process on 4747 had been started the day before from the repo checkout and
+  was still 0.10.0 in memory; it served the 0.12.0 page files straight from
+  disk, so the page drew controls the process had no data for (`handoff_ladder`
+  and `buckets` were simply absent from its payloads). The 429s were a second,
+  real defect: every claude terminal polled the usage endpoint once a minute
+  on its own, three terminals plus Claude Code's own polling, and each flip
+  from success to failure logged the whole JSON body into that terminal's
+  timeline.
+- **Fix.** The board and the floor carry the version their files shipped with
+  and print `This board process runs leg 0.10.0 and the page files are
+  0.13.0. Restart it to match: leg down && leg up` when `/api/health`
+  disagrees (`test/files-version.test.mjs` pins the constant to
+  `package.json`). Usage polling moved into the board, one poller per login
+  with backoff, one line on failure and one on recovery
+  (`src/usage-poll.mjs`, `test/usage-poller.test.mjs`).
+- **The lesson that generalises.** "Installed" is not "running". A release that
+  changes a long-lived process is verified by restarting that process and
+  reading its `/api/health` version, not by reading the page. And a reported
+  symptom that pattern-matches a known cause still gets driven to its own
+  evidence: two of the five symptoms this morning were the stale process, the
+  third was a polling design defect that the stale process was hiding.
+
 ## 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,

package/docs/board-guide.md

@@ -62,12 +62,20 @@ state the shot needs:
 node scripts/seed-wes-board.mjs     # 4 live terminals, 5 finished, long paths
 node scripts/seed-floor-board.mjs   # cards in every floor lane, plus a landing
 node scripts/board-shots.mjs <port> <tag>   # shoot 1280 and 400, print the numbers
+node scripts/board-jump-probe.mjs           # seeds, serves and drives its own board
 ```
 
 Each seeder writes a throwaway `LEG_HOME` under the OS temp dir; serve it on a
 spare port with `LEG_TRUST=never`. **Never use port 4747**, that is the live
 board, with real sessions on it.
 
+`board-jump-probe.mjs` needs no port and no seeder: it makes its own home, binds
+an ephemeral port, kills everything it started, and prints a table of where the
+expanded region sat in the viewport across thirteen pushes with the list
+re-sorting under it. Run it after any change to `renderSessions` or
+`renderDrawer`. A scroll-hold probe cannot see this class of defect: `scrollY`
+never moves, the content under it does.
+
 Measure against those seeds and never against a board of healthy terminals:
 styling scoped to live rows and measured on a clean board reported 40px terminal
 rows while the real screen showed 400px.
@@ -637,7 +645,20 @@ carrying that rung's model: `claude/fable then claude/opus then codex` posts
 three legs, the first two on one login and two different models, which is the
 hand-off the ladder exists for. Two rungs that name the same agent AND the same
 model are one leg, not two, so the sentence never lists a hand-off to a leg's
-own twin. Picking a lower rung in the ladder select starts the chain there.
+own twin. Pressing the ladder noun opens two selects: the rung the chain starts
+at, and the model that first leg runs on, taken from that provider's catalog
+([`GET /api/models`](cli-contracts.md#get-apimodels)). The model picked there
+applies to the leg that starts and nothing else; the fallbacks under it keep the
+models the ladder gave them, and the saved ladder is not touched. **More
+settings** below the line opens the full form with the same rows in it.
+
+A ladder Leg cannot read is never silently empty. An install whose
+`preferences.json` predates the ladder carries only `handoff_order`, and the
+line derives one rung per agent from it; a board that never got an answer from
+`/api/settings` at all falls back to the adapters that are installed. The
+sentence says `no agent is configured` only when there is genuinely nothing
+installed, and says `every agent here bills by the token, and spending is off`
+when there is, but the spend rule is holding it back.
 
 **Settings** holds the **API token** field (only needed when the server is bound
 off loopback; see [configuration.md](configuration.md#network-exposure)), the
@@ -765,23 +786,48 @@ bottom:
 
 ## New card form
 
-The dialog opened by **New card** (`src/board/index.html`):
+The dialog opened by **New card** (`src/board/index.html`,
+`docs/screenshots/new-card-dialog.png`):
+
+Two columns on a screen 900px or wider, one on a phone: what the work is on the
+left, who runs it on the right. It opens prefilled with the repo, branch and
+ladder the entry line above it would have used, so the dialog and that line say
+the same thing until you change one.
 
 | field | notes |
 |-------|-------|
-| Repo path | required; an absolute path to a git repository |
-| Task | required; the prompt every leg gets |
-| First agent | required; real agents appear here and Claude is preferred when installed |
+| Task | required, and takes the caret when the dialog opens; the prompt every leg gets |
+| Repository | a picker of every repo this board has seen, plus `Another path, typed below` |
+| Path | required; an absolute path to a git repository root. The picker fills it; you can type any path over it |
+| Branch to cut from | the repo's own default branch, read from the sessions payload, not a hardcoded `main` |
 | Run now | checked by default; unchecking saves the card as a draft in `backlog` |
+| Who runs it | the ordered list below; at least one row is required |
+| Save as my default ladder | writes the rows back to `preferences.handoff_ladder` through `PATCH /api/settings`, so the entry line and every new terminal use them too |
 | Workflow (Advanced) | Build only stops unmerged in the worktree; Build-land runs test then land; Factory runs plan, build, review, test, and land; custom JSON reveals a station-array textarea |
-| First-agent controls (Advanced) | allowed permission mode, approval gate, max turns, and scripted behavior when the test/demo override is selected |
-| Fallback agents (Advanced) | one understandable row per later adapter, tried in displayed order only if the previous agent cannot continue |
-| Scripted first agent (Advanced) | explicitly test/demo only; keeps fake adapters out of the normal first-agent default |
+| Scripted first agent (Advanced) | explicitly test/demo only; it replaces the agent on the first row |
 | File leases (Advanced) | comma-separated path globs to reserve so overlapping cards wait |
-| Trunk branch | default `main` |
-| Merge method | `ff` or `pr`; relevant to a workflow with a land station |
-| Test command | overrides the land station's auto-detected command |
-| Title | optional; defaults to the task's first 80 characters |
+| Merge method (Advanced) | `ff` or `pr`; relevant to a workflow with a land station |
+| Test command (Advanced) | overrides the land station's auto-detected command |
+| Card title (Advanced) | optional; defaults to the task's first 80 characters |
+
+**Who runs it** is one row per leg, in the order Leg tries them. The first row is
+the agent that starts; every row under it is a fallback, taken only when the row
+above it cannot continue. Each row carries:
+
+| control | notes |
+|---------|-------|
+| provider | the installed adapters; a test/demo adapter is labelled as one |
+| model | that provider's own catalog from [`GET /api/models`](cli-contracts.md#get-apimodels), with the provider's default as the first option. `codex` lists `gpt-6-astra`, `gpt-5.6-luna` and the rest of its visible models; `claude` lists Fable, Opus, Sonnet and Haiku |
+| permissions | the adapter's own allowed modes, its default preselected |
+| ask before start | gates that leg behind an approval |
+| max turns | a cap for that leg alone |
+| test behavior | scripted outcome, on a test/demo row only |
+| Up / Down / Remove | reorder or drop the row; the last remaining row cannot be removed |
+
+**Add a fallback** appends a row for the first installed agent no row already
+names. Every field is per row, so `claude/fable` then `claude/opus` are two real
+legs with their own models, permissions and limits: the older form keyed those
+by adapter and could not tell one claude row from another.
 
 **Cancel** closes without creating a card; **Create card** posts it and closes on
 success (errors show inline above the form).
@@ -861,25 +907,77 @@ stops spending a row on work that has stopped.
 ## Floor view
 
 `/floor` (`docs/screenshots/floor.png`) is the scheduler-eye view across every
-card. It carries the same instrument head as the board, then polls `/api/floor`
-and `/api/trunk?since=1h` every 2 seconds and refreshes on the same server-sent
-events as the board. Its top bar has the Leg floor brand, the same connection
-word and 24 px rule, a repos list, the scheduler status, running/queued/waiting/
-done counts, then a spacer and the **Board** link. Five tables:
-
-| section | columns |
-|---------|---------|
-| Running | Card, Station, Agent / leg, Leases, Last event, Elapsed, Actions |
-| Waiting on humans | Card, Station, Status, Since, Actions |
-| Queued | Card, Station, Leases, Blocked by |
-| Leases | Lease, Card, Station, Since |
-| Trunk lane | Time, Card, Summary |
-
-Each region head names its own count, `0 running`, `0 landed in the last hour`,
-and an empty table is replaced by a sentence saying what would put a row there.
-The Trunk lane lists commits landed in the last hour, newest first. The Leases
-table is `src/leases.mjs` `held()`: one row per lease currently claimed by a
-running or handing-off card.
+card, and it starts work as well as watching it. It polls `/api/floor` (the
+scheduler's own view: leases, blockers, the repos it knows), `/api/cards` (the
+rows), `/api/trunk?since=1h` and `/api/sessions` every 2 seconds, and refreshes
+on the same server-sent events as the board.
+
+Top to bottom:
+
+1. **The masthead.** The Leg floor brand, the connection word and its 24 px
+   rule, the scheduler status, the repos list and the **Board** link. The four
+   counts that used to sit here are beside the station headings now, with the
+   rows they count.
+2. **The capacity strip**, the same one the board draws and from the same file
+   (`src/board/strip.js`): one token per login carrying the bucket that will
+   actually stop the work. The four login panels are behind the same
+   `Capacity and models >` disclosure they are behind on the board, and whether
+   it is open is remembered for both pages. On the floor they used to be the
+   whole first screen, above every row the page exists to show.
+3. **The entry row**, the same one the board carries and from the same file
+   (`src/board/entry.js`): `Run in the background: [task] [Start]`, with the
+   sentence under it naming the repo, the branch, the ladder and the workflow,
+   each a button that opens a select in place. Start posts exactly what the
+   board's Start posts (`POST /api/cards`), the new card appears in Queued or
+   Backlog within one poll with no reload, and a toast names it. **More
+   settings** is the one thing the floor hands over: the New card dialog's
+   markup exists once, on the board, so the link carries the sentence you typed
+   in the hash (`/#new-card=<task>`) and the board opens the dialog with it
+   already in the field.
+4. **Five stations**, each a question with its count in the heading and, under
+   it, either the rows or one sentence saying what would put a row there:
+
+   | station | what is in it |
+   |---------|----------------|
+   | Running | `running`, `handing_off` |
+   | Waiting on you | `needs_approval`, `waiting_human`, `paused` |
+   | Queued | `queued`, each row with its position and what it waits for |
+   | Backlog | `backlog` |
+   | Done today | `done`, `failed`, `killed`, today only, collapsed behind View |
+
+   A row is the board's own card row (`.row`: state, station, repo on branch,
+   agent/model; the title; the one sentence; the run clock or `idle 12m`; the
+   short id; and at most four of its available actions in the fixed order).
+   The title is a link to that card on the board (`/#card=<id>`), which is
+   where the expansion, the log tail and Take over live: one copy of each.
+   **Reassign** opens the board's own picker in place of the row's buttons, an
+   adapter and a mode with Apply and Cancel, because the API refuses a reassign
+   with no adapter. Every other button posts its action straight away.
+   A queued row adds `2 of 3 in the queue` and, when the scheduler has said
+   why, its own words for what holds it; with the scheduler stopped it says
+   `the scheduler is stopped` rather than blaming a slot that nothing is going
+   to free. A row you have focus in is not rebuilt under your finger for 30
+   seconds, so a press, a picker or a selection survives the 2-second poll;
+   every other row in that station keeps updating meanwhile.
+5. **Leases** and **Trunk lane**, the two tables the floor alone has:
+
+   | section | columns |
+   |---------|---------|
+   | Leases | Lease, Card, Station, Since |
+   | Trunk lane | Time, Card, Summary |
+
+   The Trunk lane lists commits landed in the last hour, newest first. The
+   Leases table is `src/leases.mjs` `held()`: one row per lease currently
+   claimed by a running or handing-off card. `/api/trunk` is the map of the
+   machine and stays with the owner (`src/share.mjs` `mayUseMachine`), so an
+   operator sees this one table replaced by a line naming whose it is; the
+   stations, the entry row and the leases are theirs as usual.
+
+`j` and `k` move a ring down and up the rows, and Enter opens the ringed card on
+the board. Enter belongs to whatever has focus: on a button, a link or the
+disclosure it presses that control, and it only opens the ringed card when
+focus is on the page itself. At 400 px the page is one column: the row's
+actions move under its sentence and nothing scrolls sideways.
 
 ## Keyboard and accessibility
 

package/docs/cli-contracts.md

@@ -602,6 +602,48 @@ Board routes: `PATCH /api/settings` (owner only) also accepts
 `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

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` |
@@ -88,7 +89,7 @@ login stops (`src/preferences.mjs`), alongside the older `handoff_order`:
 
 | 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 one of that agent's names in `src/buckets.mjs` `MODEL_ALIASES` (only claude has any: `fable`, `opus`, `sonnet`, `haiku`). `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` |
+| `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 |
@@ -105,6 +106,11 @@ 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).

package/fixtures/verified.json

@@ -2,7 +2,7 @@
   "_comment": "The single source of truth for every dated, numbered claim Leg makes in public. scripts/check-claims.mjs asserts that each surface listed here states exactly these values, and --strict additionally compares the pinned CLI versions against what those CLIs currently publish. Re-verify on a real machine, then edit this file and every surface in the same commit.",
   "verifiedOn": "2026-09-11",
   "verifiedOnLong": "11 September 2026",
-  "tests": 830,
+  "tests": 926,
   "clis": {
     "claude": {
       "label": "Claude Code",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ucsandman/legcli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Usage-limit monitor and automatic handoff for Claude Code, Codex, agy and Grok. Type leg claude|codex|agy|grok and get the same interactive agent with a board alongside, auto-approve on by default, usage tracking per agent and account, a live context handoff bundle, and at the limit the next agent continuing in the same terminal. $79 once, 30-day money-back guarantee.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",