@ucsandman/legcli 0.11.0 → 0.12.0

package/docs/DEMO.md

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

package/docs/DEVIATIONS.md

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

package/docs/ERRORS.md

@@ -582,3 +582,44 @@ it), and check whether a board was listening on 4747 at the time.
   in the hand-off as in flight, or the next agent ships without it. And a
   cache keyed on a directory's mtime sees files added and removed, never a
   file rewritten in place.
+
+## The 0.12.0 redesign review confirmed 51 findings before the fix pass, 23 of them high (2026-09-18)
+
+- **What happened.** The eight-step redesign (per-model buckets, the ladder,
+  the capacity strip, cards reborn) was reviewed before commit by six finders
+  and three refuters per finding: 174 agents, 51 findings confirmed, 23 high.
+  The highs were all in code that had passed its own tests: `binding()`
+  short-circuited on the first active bucket instead of the one that stops
+  the requested model, `summarize()` parsed the ledger once per card per
+  refresh, the take-over route handed out a command for a card with no
+  checkout, `cardWorkRoot()` fell back to the main checkout, and the guest
+  payload leaked buckets, walls and hand-off reasons through the new fields.
+- **Fix.** Three parallel fix passes, one owner per file group, every finding
+  closed with a regression test in the same change; the suite went from 783
+  to 830 tests. The lockfile's root `repository` field, lost when Playwright
+  was installed, was restored so `scripts/npm-publish-gate.mjs` passes.
+- **The lesson that generalises.** A feature's own tests prove the feature's
+  own model of itself. The defects a review finds sit where two new pieces
+  meet (a new field and an old redaction list, a new route and an old helper),
+  and the review has to run on the uncommitted tree, before the commit exists
+  to be pushed by someone else. A `npm i` that regenerates the lockfile is a
+  release change and gets the publish gate run in the same turn.
+
+## A seeded board's End-as-card button wrote into a real repo (2026-09-17)
+
+- **What happened.** Driving the new "End, and keep going as a card" verb in
+  a browser against `scripts/seed-wes-board.mjs`'s board, the click on the
+  recruiting-tool row hit `POST /api/sessions/:id/end-as-card`, which did
+  exactly its job: it wrote a hand-off bundle under
+  `C:\Projects\recruiting-tool\.context-handoffs\` and cut a worktree and a
+  `leg/card-...` branch there. The seed's rows named real repositories on this
+  machine because long real paths were what the layout had to be measured
+  against. Nothing ran in the worktree (the server was stopped within a
+  minute); the worktree was deregistered and the branch deleted, and the
+  directory and bundle were left for a hand delete.
+- **Fix.** The seed's repo paths now live under `C:\Projects-seed\...`, which
+  does not exist, so every git-backed action on a seeded row answers 409
+  instead of touching a checkout. The row still prints the same length.
+- **The lesson that generalises.** A seeded board is safe to look at and not
+  safe to click: any row that names a path that exists is a live control on
+  that path. Seed paths must be realistic in shape and impossible in fact.

package/docs/ROADMAP-v2.md

@@ -1,6 +1,23 @@
 # Roadmap v2: the software factory
 
-**Unreleased (2026-09-17) opened the chain and finished the share story.** grok is
+**0.12.0 (2026-09-17) added the model dimension and made cards a first-class
+surface.** A hand-off destination is now a rung of (agent, login, model), not
+just an agent, so a Fable wall moves the terminal to opus on the same
+subscription before it moves to another CLI, and for claude that move keeps
+the conversation (`claude --resume <id> --model <alias>`). The **Hand off now
+to** picker lists those rungs with their models, whether each keeps the
+conversation, and why a greyed one buys nothing; the same list is a ladder
+editor in Settings, in a terminal's expansion and behind `leg ladder`. Live
+cards left the drawer and became rows in a **Background** panel directly under
+Terminals, with a one-line entry and the thirteen-field dialog demoted to
+**More settings**; `End, and keep going as a card` and `Take over` are the two
+doors between a terminal and a card. The board top became a capacity strip
+over a **Capacity and models** drawer, a row says `waiting on you` with the
+question when Claude Code's `Notification` hook fires, and a burn-rate figure
+prints only with its sample count. That closes the model dimension, the
+picker's second half, and the cards item below.
+
+**0.11.0 (2026-09-17) opened the chain and finished the share story.** grok is
 a registered card adapter; any other CLI becomes one from a JSON spec
 (`leg adapter add`, no code); **Hand off now** can name its destination
 instead of taking the next in the order; `leg share` grew TLS from a
@@ -41,8 +58,8 @@ event names its actor, a board that reads only the ledger, and an auth/bind seam
 
 ## Next
 
-1. ~~**Multi-human network access**~~ — done. 0.3.0 shipped `leg share`; the
-   unreleased work of 2026-09-17 shipped the three that were left: TLS (`leg share on --tls-cert/--tls-key`,
+1. ~~**Multi-human network access**~~ — done. 0.3.0 shipped `leg share`; 0.11.0
+   shipped the three that were left: TLS (`leg share on --tls-cert/--tls-key`,
    or `LEG_TLS_CERT`/`LEG_TLS_KEY`, from a pair you supply — Leg issues none),
    the `operator` role between owner and guest, and the audit trail
    (`/api/audit`, Settings → Audit trail).
@@ -62,7 +79,35 @@ event names its actor, a board that reads only the ledger, and an auth/bind seam
    (`plugins.allow`): the verb table in `src/sync/workboard.mjs` is the only
    thing to check against `openclaw workboard --help`.
 
+6. **Probe `codex resume <id> -m <model>`.** The `resume` subcommand and the
+   `-m` flag are each verified from `codex --help`; composing them is not, so
+   a codex rung ships primed from the bundle and only the claude rungs claim
+   to keep the conversation. One real run on a live codex session settles it.
+   The same probe shape applies to naming the terminal tab: whether codex, agy
+   and grok leave an OSC 2 title alone once the child starts drawing is
+   assumed, not known, which is why the tab title is the browser's and not the
+   terminal's.
+
 Also on the list: per-station prompt templates editable from the board, lease
 suggestions from the diff of the previous leg, and a floor view that shows
-lease contention over time. (The "hand off now to \<adapter>" picker landed
-2026-09-17, unreleased: Details → **Hand off now to**, or `leg sessions handoff <id> --to`.)
+lease contention over time. (The "hand off now to \<adapter>" picker landed in
+0.11.0: Details → **Hand off now to**, or `leg sessions handoff <id> --to`.
+0.12.0 put models on its rows.)
+
+## Ruled out, with the reason
+
+- **Phone or push notifications.** They need a relay, which means a server
+  that is not this machine holding a token that can reach you. Leg is
+  local-first, so the notice surfaces are the ones the machine already owns:
+  the browser tab badge (always on, no permission), a browser toast on the
+  board (off by default, gated on a secure context), and a terminal toast
+  through Claude Code's `Notification` hook (on by default).
+- **Percentages for agy.** Antigravity CLI publishes no usage figure at all,
+  so there is nothing to read. agy's token says `no figure`, and its terminals
+  are shown by elapsed time instead. A number here could only be invented.
+- **Dollars for subscription sessions.** No transcript Leg reads carries a
+  cost field. codex's `credits.balance` can be printed as a measured fact with
+  the word `credits`, and is never summed with an estimate.
+- **Per-terminal attribution of a shared login.** Nothing publishes which
+  terminal spent which part of a window. The board says it once, at the
+  Terminals head (`4 share the claude login`), rather than guessing per row.

package/docs/VOCABULARY.md

@@ -45,6 +45,7 @@ Source: the `appendEvent`/`updateSession` call sites in `src/attach.mjs`,
 | `limit` | a usage limit was detected; carries the agent's own wording, `(simulated)` when `leg sessions simulate-limit` produced it |
 | `handoff_requested` | someone pressed Hand off now, ran `leg sessions handoff`, or (on a shared board) asked for or approved a hand-off; `by` names the human (a dismissed request logs as `status` instead) |
 | `handoff` | the switch happened: from, to, reason, bundle id |
+| `waiting` | a claude `Notification` said a human is being waited on: the type (`permission_prompt`, `idle_prompt`, `agent_needs_input`) and the question verbatim; the next prompt or the end of the turn clears it |
 | `all_out` | every option is walled; the resets are printed and the terminal waits for the first one (`ended` with "quit while waiting" if Ctrl-C or End cuts the wait short, exit 3) |
 | `agent_exit` | the agent process exited, with its code |
 | `continued` | the session was started by `leg history continue` on a conversation the agent's own store holds; `session.json` carries `continued_from: { id, provider, native_id }` |
@@ -61,6 +62,32 @@ Source: the `appendEvent`/`updateSession` call sites in `src/attach.mjs`,
 | `bounced` | the landing stopped with a [bounce reason](#bounce-reasons-land-station); the full detail is in `body` |
 | `land_noop` | Land found nothing on the branch beyond its base |
 
+## Routing and capacity words
+
+The words the ladder, the usage record and the board top use. Source:
+`src/preferences.mjs` (`RUNG_COSTS`, `WHEN_RE`, `defaultLadder`),
+`src/usage.mjs` (`binding`, `burn`, `emptyRecord`), `src/buckets.mjs`
+(`bucketFromWall`) and `src/board/sessions.js`.
+
+| word | meaning |
+|------|---------|
+| rung | one destination on the ladder: `{agent, account, model, when, cost}`. `leg ladder` writes `claude/default/opus`; a rung with `model: null` means "whatever that CLI's default is", never a guess |
+| ladder | the ordered list of rungs a terminal falls down, `preferences.handoff_ladder`. `handoff_order` is its older, narrower form and is derived from it, so both stay true |
+| `when` | when a rung may be taken: `always`, `below:N` (only while that login's binding percent is under N), or `walled-only` (only when every rung above it is walled, never when they are merely slow) |
+| `cost` | what a rung spends: `free`, `plan`, `credits` or `metered`. Computed at the moment of choosing, never trusted from disk, because `credits` depends on whether the login has extra usage enabled right now |
+| `may_spend` | off by default. While it is off, an automatic hand-off skips any `credits` or `metered` rung and says so in the ledger. A hand-off a human presses is not automatic and is not gated |
+| `reserve` | a per-login floor, `{agent: percent}`. An automatic hand-off skips a rung past the floor so a background card cannot eat what you kept for yourself; a human pick still takes it and the picker says `past your N% reserve` |
+| `climb_back` | `next-handoff` (the default: the ladder is walked from rung 1 every time, so a reset model is picked up at the next hand-off) or `never` (stay put until **Back to fable**). Leg never interrupts a running turn to climb |
+| bucket | one measured window in a usage record's `buckets[]`: `kind` (`session`, `weekly_all`, `weekly_scoped`), `model` (set only on `weekly_scoped`), `percent`, `resets_at`, `is_active`. A percentage, always measured, never inferred from wording |
+| binding bucket | the bucket that will stop this login first, what `binding(u, model)` returns. The strip, the verdict and the row all print this one rather than whichever window happened to be stored |
+| wall scope | how far a wall reaches, from `bucketFromWall`. `model` walls one model family and writes `walls[model]`, leaving the login open; `account` walls the whole login through `limited_until`. Wording Leg cannot parse is `account`, and the row prints the evidence it failed on |
+| capacity | the phrase a row prints for its own binding bucket: `63% of the fable week`, or nothing when there is no reading. Computed per request, never persisted |
+| forecast | a time figure from `burn()`, and only ever with its sample count: `about 2h 40m of Fable left, from 9 samples over 4h`. Under three samples spanning ten minutes, or on a flat or falling line, or across a reset, it prints nothing at all |
+| waiting on you | a row's status word when `session.waiting` is set by a claude `Notification` hook. It sorts the row first, counts in the Terminals head and puts `(N) Leg` with a dotted favicon in the browser tab. Only claude publishes this signal; other agents say `quiet Nm` and never claim to be waiting |
+| Background | the panel of live cards directly under Terminals. Liveness decides the surface, not kind: `backlog`, `queued`, `running`, `handing_off`, `needs_approval`, `waiting_human` and `paused` are rows here, and `done`, `failed` and `killed` collapse into one ledger line |
+| end as a card | the second verb on a terminal's End confirm row (`POST /api/sessions/:id/end-as-card`): writes the bundle, hands the terminal's own worktree to a card starting at the terminal's current rung, and records the terminal as its `lineage.from` |
+| take over | the reverse, in a card's expansion (`POST /api/cards/:id/take-over`): pauses the card and prints `leg claude --resume-card <id>`, the one command a browser cannot run for you |
+
 ## Harness states (terminal cards, drawer, `leg harness`)
 
 Source: `STATES` in `src/harness/index.mjs`; recorded on `session.harness.state`.