@ucsandman/legcli 0.11.0 → 0.12.0

package/docs/board-guide.md

@@ -2,7 +2,8 @@
 
 For anyone using the Leg board day to day: what every element means and when
 it shows up. The board is one page, read top to bottom: **the verdict** (one
-sentence saying what to do next), **the logins** (one panel each), **Terminals**
+sentence saying what to do next), **the capacity strip** (one token per login,
+with the login panels behind its disclosure), **Terminals**
 (one row each), **the ledger** (finished terminals, what landed, background
 tasks, as three counts that open), then **Settings**. Start a session
 (`leg claude`) or the background-task board (`npm start`), see
@@ -13,17 +14,22 @@ The visual system, and why it is what it is, is `DESIGN.md` at the repo root.
 ## Screenshots
 
 `docs/screenshots/` (listed here so you know what exists before you look for
-one). All nineteen were retaken on 2026-09-15 against the current build, after
-the dark-product-surface redesign and the card-row port that followed it:
+one). Nine were retaken on 2026-09-17 against this build, on a board seeded by
+`scripts/seed-wes-board.mjs` plus `scripts/seed-fake-cards.mjs --count 1
+--finished 10 --live 3`; the rest are from the 2026-09-15 sweep and are noted
+below:
 
 ```
-terminals-1280.png        the board at 1280 px, four terminals on one login
-board-400px.png           the same board at 400 px
-board-details-open.png    a terminal with its expansion open
+terminals-1280.png        the whole board at 1280 px (2026-09-17)
+board-400px.png           the same board at 400 px (2026-09-17)
+capacity-drawer-1280.png  the strip with Capacity and models open (2026-09-17)
+board-details-open.png    a terminal row with its expansion open (2026-09-17)
+board-handoff.png         one row waiting on you, with the question (2026-09-17)
+background-1280.png       the Background panel and the one-line entry (2026-09-17)
+settings-ladder-1280.png  the ladder editor in Settings (2026-09-17)
 board-empty.png           no background tasks at all
-board-running.png         one card running its first agent
-board-handoff.png         the limit hit, the card waiting on you
-board-drawer.png          that card expanded: bundle, runs, timeline
+board-running.png         one card running its first agent (2026-09-17)
+board-drawer.png          that card expanded: where, runs, take over, timeline (2026-09-17)
 board-done.png            the card finished, on the agent that finished it
 floor.png                 /floor with nothing queued
 floor-landing.png         /floor with every lane full
@@ -41,6 +47,14 @@ demo-5-done.png            done, both legs on the chain
 The five `demo-*.png` are one run of the sequence in [DEMO.md](DEMO.md), all at
 1280 px.
 
+**Still stale, as of 2026-09-17:** `share-owner-1280.png`,
+`share-guest-1280.png`, `board-empty.png`, `board-done.png` and the five
+`demo-*.png` show the old top of the board (a 56px verdict over a column of
+login panels) rather than the capacity strip and its drawer, and the card shots
+among them predate the Background panel. Their terminal rows and their floor
+are still accurate. Retake them with the commands below rather than trusting
+the top band of any of those pictures.
+
 To retake one, seed a board with the shape a real one has and drive it to the
 state the shot needs:
 
@@ -60,35 +74,115 @@ rows while the real screen showed 400px.
 
 ## The verdict and the logins
 
-`src/board/sessions.js` draws both, from the `accounts` array of
+`src/board/sessions.js` draws all of it, from the `accounts` array of
 `GET /api/sessions` and the sessions beside it.
 
 **The verdict** is the largest thing on the page and it is a sentence, not a
 number. It names the one fact that decides what happens next:
 
 ```
-All 4 terminals are on claude, and claude has 5% left.
+Fable is at 63% of its week, the only login open.
 ```
 
-One login carrying every terminal is one point of failure, so that is what the
-sentence says. With the terminals spread across logins it names the one closest
-to a wall instead; with nothing running it says so, and names any login that is
-walled. The number it prints is what is **left**, because that is the quantity
-you are deciding against.
+The sentence comes from a branch table with a fixed precedence, and the order
+is what the table is for. A human waiting on a terminal outranks every usage
+figure, because attention is the scarcer thing. Then a login whose whole
+account is nearly spent (`claude has 3% left, shared by every model.`), because
+no model switch can help there. Then a single model at its wall with the login
+still open (`Fable is out until 9:14 PM; opus is open.`), which is the one case
+where a same-login switch is the answer. Then the burn rate, when it is known
+(`About 2h 40m of Fable left.`), because the decision is about the afternoon
+and not about the number. A model bucket that came back while a terminal is
+still downshifted (`Fable is back; leg#7f3a is still on opus.`) sits right after
+the walled-model sentence, since a state change outranks a standing figure.
+Then one login carrying every terminal, several logins carrying work, and the
+quiet states: nothing running and no figure anywhere. Everything walled
+(`Every login is at its limit; codex is back first.`) is decided before any
+per-login sentence, because it is a fact about the whole board. There is
+always a sentence.
+
+**Every time figure carries the volume it was drawn from**, always:
+`From 9 samples over 4h. Opus and Sonnet have their own buckets.` The rate is
+measured from the readings Leg has kept for that one bucket, and three rules
+hold it honest. Under **three samples spanning ten minutes** there is no time
+at all: the row prints the percentage and the reset clock instead, because a
+slope drawn through two readings a minute apart is a guess printed in the
+largest type on the page. A rate **never crosses a reset**: the samples are
+cleared when the window rolls over, and the time is capped at the reset even
+when the slope says there is more. A figure that has held flat for an hour is a
+measured zero, not a forecast, and a percentage that fell inside one window is
+a data error rather than a refund; neither prints a time. The second sentence
+names the other models on that login, because a Fable figure is not the login's
+figure and the reader who takes it for one plans the wrong afternoon; on a
+login where every model shares the window it says `Shared by every model.`
+
+The headline is capped at **56 characters**, and that number is a measurement,
+not a preference: at 1280 the verdict column is 26ch and 300 sampled sentences
+per length still fit two 52px lines at 60 characters, so 56 is that ceiling
+with slack for a long login name. `test/board-verdict.test.mjs` holds every
+branch under it, including branches fed deliberately long repository and
+account names. A headline that wrapped to three lines is what put a thousand
+pixels between the top of the page and the first terminal row.
 
 Under it, one line carrying the age of the reading and which direction it is
 wrong in:
 
 ```
-Measured 2h 13m ago. 4 terminals have been running since, so the real figure is
-higher than 95 percent, never lower.
+Measured 2h 13m ago. 4 terminals run on it, so the real figure is higher, never
+lower.
 ```
 
 A reading taken two hours ago is a floor, not a measurement, and saying so is
 the entire reason to print its age. Any login at a wall other than the one in
 the headline is named on the same line.
 
-**The logins** sit under the verdict, one panel each, and how much surface a
+**The capacity strip** is the band under the verdict: one token per login, a
+dot in its identity colour, its name, a 120 by 6 track and one figure. The
+figure is the **binding** bucket, the one that will actually stop the work:
+the bucket the endpoint itself marks active, else the highest percentage it
+reported, else the hottest of the two legacy windows. That distinction is the
+reason the strip exists. A login whose weekly account window reads 95% and
+whose active Fable bucket reads 63% is stopped by the 63, and the board used to
+print the 95.
+
+```
+claude |=======---| 63% fable week      codex |==========| back Sat 10:11 PM
+agy    no figure                        grok  no reading
+```
+
+- `63% fable week` is a fresh reading with its bucket word.
+- `100% Tue 9:55 AM` is a reading older than five minutes: the percentage with
+  the clock it was taken at, because it describes a moment, not now.
+- `back Sat 10:11 PM` is a login at its wall. The track fills in the wall
+  colour and the words carry the state, which is the one place on the board a
+  word may wear a severity colour: the word is itself the failure.
+- `no figure` is agy, which publishes no percentage, ever. **No track is
+  drawn.** An empty track reads as a measurement of zero.
+- `no reading` is a login that has a window and has never reported it.
+- `not shared` is what a guest sees: usage figures are the owner's.
+
+Each track is a `meter` with an `aria-valuetext` carrying the percentage, the
+reset, the source, any wall and the age of the reading, the same sentence the
+gauges carry. A login with no percentage is not a `meter` at all, because
+`aria-valuenow` would have to be a number nobody measured.
+
+**`Capacity and models >`**, at the end of the strip, opens a drawer holding
+the login panels unchanged, plus a rail of model chips on each panel head:
+`fable 63%` for a measured bucket, `fable out until 9:14 PM` for a model at its
+wall, and a bare model name where Leg has a name but no figure. A percentage is
+measured and a wall is attributed from wording, so the two are never printed as
+each other. The drawer remembers whether you left it open. The
+`Times are local.` caption lives inside it.
+
+An **open chip is a button**: pressing it puts that rung at the top of one
+terminal's ladder, so the next hand-off takes it. The terminal is the one whose
+expansion is open if it is on this login, else the first live row on it, and the
+press is the same `POST /api/sessions/:id/handoff-order` the ladder editor
+makes. A chip stays plain text when it is walled, when it is the model that
+terminal is already running, or when no live terminal on this login can take a
+ladder change: a control that would do nothing is not drawn as one.
+
+**The login panels**, in that drawer, are one per login, and how much surface a
 panel gets is the design saying how much it matters:
 
 - The login carrying the terminals gets a wide panel, lit one step brighter than
@@ -113,7 +207,7 @@ one it does not have.
 Nothing here is on hover. A screen reader gets the whole answer from each
 track's `aria-valuetext`, including the reset, the source and the staleness; a
 window with no value is not a `meter` at all and carries the same sentence as
-its label. The caption under the logins reads `Times are local.`
+its label. The caption at the foot of the drawer reads `Times are local.`
 
 For Codex, the board reads the app-server's read-only
 `account/rateLimits/read` response every 60 seconds and maps its 300- and
@@ -131,7 +225,11 @@ within a second of the agent's first turn.`
 
 The region head carries one verdict with its volume: `3 running, 2 waiting on
 you`, or `3 running, nothing is waiting on you`, or `nothing is running`, with
-`, last landed 11:02 PM` appended when a terminal on the page has landed.
+`, 3 share the claude login` when two or more live rows are on one login, and
+`, last landed 11:02 PM` appended when a terminal on the page has landed. The
+share clause is the only place per-login burn is addressed: a figure on a row
+is per model, which is real, and the reader who would add three rows' figures
+together is stopped here, once, at the region.
 
 ### Terminal row
 
@@ -143,11 +241,25 @@ the state is never carried by colour or position alone.
 Reading across the row: what it is doing, what it is working on, how long it has
 been at it, and what you can do about it.
 
-- **The register**, one line of the smallest type on the board: the status word
-  with its dot, then where the work is (`leg on main`, or the folder when it
-  is not a repo), then anything unusual about this terminal as plain words, the
-  account when it is not `default`, the owner on a shared board, `from <agent>`
-  when it was handed off, `own worktree, from main` when it cut its own.
+- **The register**, one line of the smallest type on the board, read left to
+  right: the status word with its dot, then where the work is (`leg on main`,
+  or the folder when it is not a repo), then `dirty 3` and `ahead 2` when the
+  git poll has counted them, then the model token `claude/fable`, then
+  `quiet 4m` when the terminal has said nothing for two minutes or more. After
+  those come the words that are unusual about this terminal: the account when
+  it is not `default`, the owner on a shared board, `from <agent>` when it was
+  handed off, `own worktree, from main` when it cut its own.
+  - `dirty 3` is `files_dirty`, `ahead 2` is the commit count against the base.
+    Neither is printed as a zero, and `ahead` is absent on a record written by
+    an older Leg rather than shown as `ahead 0`.
+  - The model token is the agent and the model this leg resolved to
+    (`claude/fable`, `codex/gpt-5.6-sol`). With no model on the record it is the
+    agent alone, `claude`: a printed model nobody chose is a wrong number in
+    disguise, so there is never a default. For Claude it is refreshed from the
+    transcript, so a silent fallback off Fable shows up here.
+  - `quiet 4m` is `last_activity`, in the muted tone, for every agent. It is an
+    observation, not a demand. A terminal that is waiting on you says that
+    instead, and a finished one says nothing: it has stopped, not gone quiet.
 - **The prompt**, as a button: the first prompt of the session, carried in full
   in its tooltip and in the expansion. A pasted screenshot arrives as an
   `<image name=... path=...>` tag with an absolute temp path in it; the tag is
@@ -161,6 +273,34 @@ been at it, and what you can do about it.
   file another live session is also touching is printed in the warning colour.
   A terminal that is merely running prints no sentence at all: its own row
   already says so, and four rows each saying `activity` is four lines of noise.
+- **The capacity phrase**, at the right of the files line: `63% of the fable
+  week`, the bucket that will actually stop THIS terminal. It is
+  `binding(usage, session.model)`, computed per request, so a row on Fable and a
+  row on Sonnet in the same login can print different figures and both are
+  true. The figure is per model; the reader who would add three rows' figures
+  together is stopped by the share clause at the region head, once. Nothing is
+  printed when no bucket is known: a percentage nobody measured is worse than
+  no percentage at all.
+  - Once that bucket has **three readings spanning ten minutes**, the phrase
+    becomes the time instead: `about 2h 40m of fable left, from 9 samples over
+    4h`. The sample count is part of the phrase and is never dropped. Under the
+    gate it stays the percentage and the reset clock, and the time never runs
+    past the reset: a rate measured in this window says nothing about the next
+    one.
+  - The strip token above keeps the percentage even while the row says the
+    time. The strip is the measurement and the time is the inference, and the
+    inference lives where its sample count can sit beside it.
+- **`Back to fable`**, a link on the capacity line beside that figure, on a row
+  that Leg dropped to a lower model and can climb again. It appears only when
+  both facts are known: the row's model is below the top rung of its own
+  login's ladder, and that top rung is open (no wall on the model, no wall on
+  the login, and either no bucket for it or a bucket under 100). Pressing it
+  replaces the button row with one sentence, `Hands off now. The current turn
+  stops and fable continues from the bundle.`, or `from the conversation` when
+  that rung is one a `--resume` keeps. Confirming posts the hand-off with the
+  model on it; a rung that walled between the draw and the press comes back as
+  the server's own 409 sentence in the row. It is a link and not a fifth button:
+  the 2x2 grid is the shipped shape and does not reflow.
 - **The clock**: elapsed since the session started (`4h 24m`), and the session's
   short id. The id used to print as `claude-7f3a` immediately after the word
   `claude`; the prefix is the agent name twice and it is gone.
@@ -170,6 +310,16 @@ been at it, and what you can do about it.
   because a disabled control should not wear the one accent colour in the
   design. When Land is disabled its reason is printed, never left in a tooltip.
 
+**A terminal waiting on a human says so, and the tab says it too.** Claude
+Code's Notification hook writes `waiting` on the record when it puts up a
+permission prompt, when it has been idle at the prompt, or when a subagent asks
+for input; the row's status word becomes `waiting on you`, its sentence is the
+question itself (rank 3 below), and it sorts to the top of the region and into
+the region head's count. While any row is waiting the tab title reads
+`(1) Leg` and the favicon carries a dot, always, with no permission and no
+setting. codex, agy and grok publish no such signal, so their rows never say
+`waiting on you`; they say `quiet 4m`.
+
 **A fact true of every row is said once, at the region.** Three rows all reading
 `this terminal works in the checkout itself: there is no branch of its own to
 land` is one fact and two lines of noise, so it is hoisted to the region head as
@@ -199,12 +349,13 @@ rest behind `also:`. Rank 1 is worst.
 |------|--------------|
 | 1 | `every option is out, first back: codex 10:11 PM`, or `limit: <reason>, back <time>` |
 | 2 | a bounced Land, or `the landing was cut off (the board restarted); press Land again` |
-| 3 | an overlap with another live session |
+| 3 | `waiting on you: permission to run Bash(git push origin HEAD), asked 40s ago`, `waiting on you: idle since 11:04 PM`, or an overlap with another live session |
 | 4 | `sam asked to take this terminal at 11:04 PM` |
 | 5 | `waiting for codex at 10:11 PM` |
 | 6 | `handing off to codex, <reason>, 2m` |
 | 7 | `landing <branch> onto main: commit, rebase, test, fast-forward` |
 | 8 | `near the 5h wall, next: codex` |
+| 8.5 | `fable at 92% of its week; Hand off > claude/opus keeps this terminal`, or `claude at 97%, shared by every model; next off claude: codex` |
 | 9 | a finished Land, `nothing to land`, or the button you last pressed |
 | 10 | `turn 14, last activity 11:04 PM`, the fallback that is always true |
 
@@ -246,6 +397,15 @@ is counting down to the first reset; its sentence reads `waiting for <agent> at
 <time>`, and End quits that terminal with exit 3. `lost` means the runner
 process that owned that terminal is gone. It is never counted as live.
 
+A tenth word, `waiting on you`, replaces the status word on any row that needs a
+human. Two different things live on the record's `waiting` key and the board
+tells them apart by `type`, never by which fields are set: `type: reset` is the
+all-out countdown above, where the child is already dead and nobody is being
+waited on, and `permission_prompt`, `idle_prompt`, `agent_needs_input` and
+`quota_auto_resume` are a human being waited on. `quota_auto_resume` is the one
+that prints `Claude Code is waiting at the limit itself; Leg is not handing this
+one off.`, because two waiters on one terminal is the failure to avoid.
+
 ### Terminal buttons
 
 The order is fixed, Land, Hand off now, Details, End, and it never reflows by
@@ -257,16 +417,18 @@ availability: a button that does not apply is omitted, never moved.
 | Request handoff | the board is shared and this terminal is someone else's | `POST /api/sessions/:id/request-handoff` (202): asks the owner; nothing happens until they approve |
 | Approve `<name>` / Dismiss `<name>` | the board is shared and someone asked for a hand-off on your terminal | `POST /api/sessions/:id/requests/<name>/approve` (or `/dismiss`): approving hands the terminal off, and the event says who it was for |
 | Details | any terminal of yours | `GET /api/sessions/:id/detail`: the transcript, the files changed with their line counts, the timeline and the current bundle; `GET /api/sessions/:id/diff?file=<path>` for one file, capped at 400 lines, refused for any path outside that terminal's own tree |
-| Hand off now | the session is active | `POST /api/sessions/:id/handoff`: saves the bundle, stops this agent, starts the next option in the same terminal |
-| Change order | inside the expansion, while the status is `starting`, `running`, `warning`, `limit` or `waiting` | saves its validated claude/codex/agy priority; an older wrapper instead saves the machine default and says to restart the terminal |
+| Hand off now | the session is active | asks first in the row's confirm row (`Hands off to the first open rung of this terminal's ladder. The current turn stops.`), then `POST /api/sessions/:id/handoff`: saves the bundle, stops this agent, starts the next option in the same terminal. It stops a working agent mid-turn, so it asks whether the mouse or the `h` key pressed it |
+| Change the ladder | inside the expansion, while the status is `starting`, `running`, `warning`, `limit` or `waiting` | `POST /api/sessions/:id/handoff-order` with the whole `handoff_ladder`; an older wrapper instead saves the machine default and says to restart the terminal |
 | End | the session is active | `POST /api/sessions/:id/end`: stops the agent, ends the session |
 | Remove | the session is not active | `DELETE /api/sessions/:id`: safely prunes the session record, worktree, and merged branch only when the worktree is clean and the branch is already on its base; otherwise it leaves them and explains why |
 | Remove record | the session is not active and has an own worktree | `DELETE /api/sessions/:id?force=1&keep_worktree=1`: removes only Leg's record and keeps the worktree, branch, unmerged commits, and dirty files |
 
 End, Remove and Remove record confirm first: the button row is replaced in place
-by one sentence and two buttons, focus moves to Cancel, and Escape cancels.
-There is no modal and no browser `confirm()`. Settings has the same order editor
-for the default copied by new terminals.
+by one sentence and its buttons, focus moves to Cancel, and Escape cancels. End
+offers a second verb, **End, and keep going as a card**, when the terminal is in
+a repository and the reader may use cards.
+There is no modal and no browser `confirm()`. Settings has the same ladder
+editor for the default copied by new terminals.
 
 ### The expansion
 
@@ -289,11 +451,12 @@ from the right, and the page keeps one scroll container
    `new` or `committed` when there are no counts against `HEAD`. A row expands
    to that file's diff, capped at 400 lines.
 6. **Timeline**: the last 40 events, newest first.
-7. **What happens next**: `now: claude, then codex, then agy`, which fallback is
-   preferred and which is eligible now, the line `Used after a usage limit or
-   Hand off now. A normal exit ends this terminal.`, the **Change order**
-   editor, the current bundle id, and whether `.leg/RESUME.md` still describes
-   the repository (recomputed from git on every poll).
+7. **What happens next**: `now: claude / opus, then claude / fable, then
+   claude / sonnet, then codex, then agy`, which rung is preferred and which is
+   eligible now, the line `Used after a usage limit or Hand off now. A normal
+   exit ends this terminal.`, the **Hand off now to** picker, the **Change the
+   ladder** editor, the current bundle id, and whether `.leg/RESUME.md` still
+   describes the repository (recomputed from git on every poll).
 8. **Harness** (only when the [portable harness](harness.md) is on): the
    source client, when it was captured and synced, the policy, one line for
    the leg now running (`codex harness partial · 8/8 components, 3 dropped ·
@@ -309,11 +472,73 @@ stays live, so the panel's own buttons keep working. Messages and diffs are
 scrubbed for secrets on the way out, and the whole region is refused for a
 terminal that belongs to someone else. **Close** or the Escape key closes it.
 
-**Change order** moves the three agents without removing one; same-agent
-secondary accounts still come before the other agents. The list is an absolute
-priority: an agent moved to the bottom is tried last from every starting agent.
-The editor previews the resulting priority, with the agent running now skipped,
-before saving.
+**The Hand off now to picker** lists one row per rung of this terminal's ladder,
+each of them three fields separated by a middot:
+
+```
+claude / opus · same terminal, keeps the conversation · ready
+claude / sonnet · new agent, from the bundle · ready
+codex · new agent, from the bundle · at its usage limit until Sat 10:11 PM
+claude / fable · new agent, from the bundle · ready, spends usage credits
+agy · new agent, from the bundle · only when every rung above it is walled
+```
+
+The rung first, then what taking it does to the conversation, then what it costs
+you right now. The state word is `ready` for a rung that is simply open; a rung
+that cannot be taken carries **the server's own reason**, verbatim, and is
+disabled, with `until <clock>` when there is a reset to name. A rung that is
+open but worth a warning keeps its reason as plain text and stays clickable:
+`past your 10% reserve` is the one you will see, because a human pressing this
+button ignores the reserve and a floor you cannot see is a floor you swear at.
+The refusal that reads `shares the window that is out, buys nothing` is a
+same-login rung under an account-wide wall: every model shares that window, so
+switching model would buy nothing. The rung Leg would take on its own is not in
+the list twice; the terminal's current rung is not in it at all. Picking one
+replaces the row's button grid with a sentence naming the destination and
+whether the conversation survives, and the hand-off carries the model. The
+choice survives the expansion's 3-second refetch: it is held as a rung, so the
+row it names is still selected after the list is rebuilt, or reordered, under
+it, and the poll stands down entirely while the select has focus.
+
+**Change the ladder** edits this terminal's own copy. Each rung is a numbered
+row: the agent and model with the login's dot, a `when` select (`always`,
+`below N%` with a number from 0 to 100, which is the range the server itself
+accepts, or `walled only`), the cost word, and **Up**, **Down**, **Remove**.
+Clearing the number box puts the rung back to `always` rather than inventing a
+percentage; a stored `below:0` or `below:100` is shown as the number that is
+stored, with a line saying what it does (`below 0% is never true: this rung is
+never taken`), and is never quietly rewritten. `+ Add a rung` takes an agent and
+one of its models, or `default` for the model the CLI picks itself; a rung the
+ladder already carries is refused in the status line by name and position
+(`claude / opus is already rung 2.`), never silently. There is no drag: a
+list this short is faster with two buttons and a drag has no keyboard. Saving
+posts the whole ladder; a rung the server will not accept comes back as its own
+sentence (`claude has no model "gpt-5"`) in the status line, and nothing is
+saved. The draft line under the list previews what this terminal would try
+next, with the rung it is on skipped.
+
+**Settings** carries the same editor for the machine default, under
+`New terminal handoff ladder`, plus the three rules that are machine-wide:
+
+- **Let an automatic hand-off spend**, with the sentence `A rung that spends
+  usage credits or metered balance may be taken by an automatic hand-off.` Off
+  by default. While it is off, a `credits` or `metered` rung is skipped by an
+  unattended hand-off and the ledger says which and why; a human pressing Hand
+  off can still take it. When the claude login reports credits off, the panel
+  adds `Usage credits are off, so there is nothing to spend through the wall.`
+  and offers no button to turn them on, because that cannot be done from here.
+- **Climbing back**, two radios: `Leg climbs back to the top rung at the next
+  hand-off.` (the default) or `Stay on the lower rung until you press Back to
+  fable.` Under them, the rule that is not a choice:
+  `Leg never interrupts a running turn to climb.`
+- **Keep N% of `<login>` for your own terminals**, one number per login on the
+  ladder. 0 keeps nothing back. An automatic hand-off skips a rung whose login
+  is past the floor; a hand-off you press yourself still takes it, and the
+  picker prints `past your 10% reserve` on that row rather than hiding it.
+
+Saving Settings writes `handoff_ladder`, `climb_back`, `may_spend` and
+`reserve` in one `PATCH /api/settings`, and the status line reports the
+`handoff_order` the ladder derives, which is what older terminals still read.
 
 ## The ledger
 
@@ -353,9 +578,10 @@ heading, a line of detail and a button that opens the detail below the row.
   or `N uncommitted`. Nothing here is pushed over the live stream; the count
   re-reads itself once a minute while the drawer is closed. On a shared board
   a guest sees `The owner of this machine sees them.` and nothing else.
-- **N background tasks**, the card runtime below, as a count with **View N
-  cards**, plus **New card**. With none it reads `Nothing is queued. Leg starts
-  the next login only when a terminal hands off.`
+- **N finished cards**, `3 finished cards, 2 done, 1 failed, last 11:02 PM`,
+  with **View** opening them newest first. Live cards are not here: they are
+  rows in the Background panel under Terminals, with the one-line entry under
+  it. With none finished it reads `No finished cards`.
 
 ## A shared board (more than one human)
 
@@ -378,9 +604,14 @@ link: that side belongs to the owner of the machine, and the API answers 403.
 
 ## Background tasks: page layout
 
-Everything from here down is the v0.1 card runtime. Each card runs separately
-from the interactive terminal conversations, in its own git worktree. It is the
-third ledger cell, and its rows open in a drawer under the ledger.
+Everything from here down is the card runtime. Each card runs separately from
+the interactive terminal conversations, in its own git worktree. Liveness, not
+kind, decides where a card appears: a live card (`backlog`, `queued`,
+`running`, `handing_off`, `needs_approval`, `waiting_human`, `paused`) is a row
+in the **Background** panel directly under Terminals, in the terminal row's own
+shape; a finished one (`done`, `failed`, `killed`) collapses into the ledger
+cell, `10 finished cards, 5 done, 5 failed, last 8:15 PM`, whose **View** opens
+them newest first. Ten finished cards are one row, not ten.
 
 The masthead (`src/board/index.html`) has the Leg wordmark on the left and, on
 the right, the connection word (`connecting` / `live` / `reconnecting…`) with its
@@ -389,15 +620,42 @@ dot, the scheduler status (`scheduler running, 2 max`), and the **Floor** link.
 last region of the page, in flow. Nothing on the board is sticky: the verdict is
 what you came for and it is at the top, so there is nothing to pin.
 
-With no cards the region prints `No background task. New card queues one. They
-run headless in their own worktree and report on the floor.` With cards the
-region head prints the counts instead: `2 running, 1 queued, 3 finished`.
+With no live cards the Background panel's rows are gone and only its entry line
+is left; with live cards the region head prints the same counts a terminals
+head does, `1 running, 1 waiting on you`. Under the rows sits the entry: a
+single field, `Run in the background:`, a **Start** button, and an inferred
+sentence whose nouns are buttons, `in leg on main, with claude/fable then
+claude/opus then codex, build only`, plus **More settings** for the full form.
+Start with an empty task is disabled and says why.
+
+The sentence describes exactly what Start posts, noun by noun. The branch is
+the repo's own default (the server reads `origin/HEAD`, then `main`, `master`
+and `trunk`, then the branch the checkout is on) and it is sent with the card,
+so a repo whose default is `master` or `develop` starts one instead of being
+refused by a trunk that does not exist. The ladder clause is one leg per rung
+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.
 
 **Settings** holds the **API token** field (only needed when the server is bound
 off loopback; see [configuration.md](configuration.md#network-exposure)), the
-**New terminal handoff order** editor used by terminals started after you save,
-and the board's own facts: version and bind address, who you are signed in as,
-whether share is on, the scheduler, and the board home. Its region head says
+**New terminal handoff ladder** editor used by terminals started after you save
+(the rungs, the spend rule, the climb-back policy and the per-login reserve),
+**Notifications**, and the board's own facts: version and bind address, who you are signed in as,
+whether share is on, the scheduler, and the board home. **Notifications** holds
+two toggles, both about a terminal that is waiting on you: *Terminal toast when
+a terminal waits on you* (on by default, Claude Code only: an OSC 9 sequence
+returned by the Notification hook, which is the toast Windows Terminal renders
+in the window the agent is already running in) and *Browser notification when a
+terminal waits on you* (off by default; the browser asks for permission the
+first time you turn it on, and it fires on the transition into waiting, never on
+every refresh). The board toggle reads `window.isSecureContext` when it renders;
+where that is false it is disabled and says `This page is not a secure context.
+Open the board at http://localhost:<port> to turn toasts on.` The tab title
+badge has no toggle: it needs no permission, so it is always on. Its region head
+says
 `No API token set, requests reach 127.0.0.1:4747 unauthenticated`, or `API token
 set, sent to 127.0.0.1:4747 as a bearer token` once a token is stored.
 
@@ -428,12 +686,21 @@ Each card row reads in the same four registers as a terminal panel:
 - **What**: the title (the card's `title`, or the first 60 characters of the
   task) as a button that opens the [expansion](#card-expansion), and one
   sentence under it.
-- **Where**: `repo@trunk`, the worktree path shortened to its tail with the full
-  path in its tooltip, the chain rail, and the lease chips, one per claimed
-  lease or `**` (the whole repo) when none were set, plus `blocked by lease`
-  when the scheduler says so.
-- **When**: the elapsed clock, `mm:ss` while a leg is running and `--:--`
-  otherwise, then the buttons.
+- **Where**: `<repo> on <branch>`, where the branch is the one that checkout is
+  actually on: `leg/<card-id>` for a worktree the card cut, and the terminal's
+  own branch for one it adopted from "End, and keep going as a card", which is
+  not a name anyone can derive from the card id. It is shortened to 32
+  characters on the row with the whole line in the tooltip, so what you copy
+  into `git checkout` is a branch git has. A card with no checkout yet prints
+  the trunk it will branch from. Then the chain rail, and the lease chips, one
+  per claimed lease or `**` (the whole repo) when none were set, plus `blocked
+  by lease` when the scheduler says so.
+- **When**: the elapsed clock, then the buttons. `mm:ss` (or `hh:mm:ss`) counts
+  the leg that is running now, exactly as a terminal row's clock does. A live
+  card between runs has no leg to time, so it prints `idle 12m`, the time since
+  its last state change, labelled for what it is: the card's own age in that
+  column would read `24:05:00` for a card that sat in the backlog for a day. A
+  card that has never run prints `--:--`.
 
 The log is not on the row. It is in the expansion.
 
@@ -536,6 +803,33 @@ is fixed: Approve, Run, Resume, Pause, Hand off now, Rerun, Reassign, Kill.
 | Reassign | any non-terminal status, and the current station is an `agent` station | pick a different adapter/mode for the current leg from a picker |
 | Rerun | `done`, `failed`, `killed` | start the station over from the last bundle |
 | Remove | `done`, `failed`, `killed` | delete the card record, its events and its runs; the worktree is kept (confirms first) |
+| Take over | any non-terminal status, in the [expansion](#card-expansion) | you take the card's checkout yourself |
+
+**Take over** is the one place the board hands you a command, because a browser
+tab cannot open a terminal: it prints `leg claude --resume-card 3e1c`, which
+starts an interactive terminal in the card's own worktree, primed from the
+card's bundle. Before it prints anything the card is moved to `paused`,
+whatever it was doing: a running one has its child killed and its bundle
+written, and a `queued` or `handing_off` one is taken out of the set the
+scheduler starts from, so nothing launches a leg into the checkout you are
+about to sit down in. The card's ledger gets one `taken_over` line with your
+name on it. **Resume** puts it back to work when you are done. A card that is
+`done`, `failed` or `killed` has nothing to take over and says so.
+
+**End, and keep going as a card** is the same trade in the other direction: it
+is the second verb on a terminal's End confirm row (shown for a terminal in a
+git repository, to the owner or an operator). It writes the terminal's hand-off
+bundle, makes a card whose task is the terminal's prompt plus `Continue from
+the bundle at <path>`, starts its ladder at the rung that terminal was on, and
+then ends the terminal. Where the card works depends on what the terminal had:
+a terminal with a worktree of its own hands it over, and the card waits in the
+backlog until that terminal has really stopped, because `End` is a request its
+runner reads on its own poll and two agents in one working tree is the thing
+this whole feature exists to avoid. A terminal working in the repo itself gets
+the card a checkout of its own, cut from the same branch, with the uncommitted
+work carried into it: the tracked edits as a patch and every file git has not
+seen copied across. If that work cannot be read or cannot be carried, nothing
+is created and the terminal is left running with the reason.
 
 ## What a state looks like
 
@@ -549,13 +843,21 @@ is fixed: Approve, Run, Resume, Pause, Hand off now, Rerun, Reassign, Kill.
 | needs approval | 0 | needs approval | Approve, Kill, Reassign* |
 | waiting human | 0 | waiting human (or PR open) | Approve, Kill |
 | paused | 3 | paused | Resume, Kill, Reassign* |
-| done | 6 | done | Rerun, Remove |
-| failed | 1 | failed | Rerun, Remove |
-| killed | 1 | killed | Rerun, Remove |
+| done | not a row | done | none on the board |
+| failed | not a row | failed | none on the board |
+| killed | not a row | killed | none on the board |
 
 \* Reassign only shows when the current station is an `agent` station.
 † Hand off now only shows when that station has a later chain entry.
 
+The last three are not rows at all. A finished card is one line in the ledger
+drawer (`finishedLine` in `src/board/board.js`), `done after 3 runs, landed
+7f3a2c1` or `failed at station build after 2 runs: <last event>`, with no
+buttons beside it. `availableActions` in `src/chain.mjs` still returns `rerun`
+for a terminal status, and Remove is its own `DELETE /api/cards/:id`, so both
+verbs remain reachable through the API and `bin/leg.mjs`; the board simply
+stops spending a row on work that has stopped.
+
 ## Floor view
 
 `/floor` (`docs/screenshots/floor.png`) is the scheduler-eye view across every
@@ -585,9 +887,42 @@ running or handing-off card.
   summaries) gets a visible focus ring: `outline: 2px solid var(--focus);
   outline-offset: 2px` on `:focus-visible` only (`src/board/board.css`). There
   is no bare `:focus` rule, so a mouse click leaves no ring behind it.
-- Escape closes the open expansion, the terminal's and the card's. If a confirm
-  row is open, Escape cancels that first. The floor has neither, so Escape does
-  nothing there.
+- Escape closes the open expansion, the terminal's and the card's. If the
+  keyboard map is open, Escape closes that first, then a confirm row if one is
+  open. The floor has neither, so Escape does nothing there.
+- **The keyboard map.** `?` opens and closes a small panel listing every
+  binding. Every key CLICKS a button that is already on the row, so no key is a
+  second way to do anything:
+
+  | key | what it does |
+  |-----|--------------|
+  | `j` | move the ring to the next terminal |
+  | `k` | move the ring to the previous terminal |
+  | `1` to `9` | move the ring to that terminal |
+  | `h` | press Hand off now on the terminal the ring is on |
+  | `l` | press Land on the terminal the ring is on |
+  | `d` | press Details on the terminal the ring is on |
+  | `e` | press End on the terminal the ring is on |
+  | `?` | open and close the map |
+  | `Escape` | close the map, cancel a confirm row, or close an expansion |
+
+  The ring is a bar down the left edge of the row, and moving it also moves
+  keyboard focus to that row's first button, which is its prompt, so a screen
+  reader announces which terminal the ring landed on rather than a bare `Land`.
+  A disabled button is never clicked, so `l` does nothing on a row that cannot
+  land. While an input, a select or a textarea has focus, every one of these
+  keys is text and nothing else.
+
+  The ring belongs to a TERMINAL, not to a position: the grid re-sorts whenever
+  a row starts waiting on you, and the ring stays on the terminal you put it on.
+  If that terminal ends and moves to the ledger, the ring is cleared rather than
+  inherited by whatever row took its place.
+
+  With no ring set, `h`, `l`, `d` and `e` only set the ring on the first row and
+  paint it; it takes a second press to act, so no key ever acts on a terminal
+  that was not marked on screen first. Every one of these keys stands down while
+  a dialog is open, while the keyboard map is open (`?` and Escape still close
+  it), and while a confirm row is waiting for its answer.
 - Buttons carry descriptive `aria-label`s (for example "Pause `<card title>`",
   "Reassign adapter for `<card title>`") so a screen reader announces which card
   an action applies to, not just the button label.