@ucsandman/legcli 0.10.0 → 0.12.0

package/docs/cli-contracts.md

@@ -25,7 +25,7 @@ questions."
 | claude | 2.1.268 | exit 0, file yes, DONE yes, 20 s | `src/adapters/claude.mjs` |
 | codex | codex-cli 0.153.4 | exit 0, file yes, DONE yes, 28 s | `src/adapters/codex.mjs` |
 | agy | 1.2.0 | attempt 1 exit 0 but wrote to its scratch workspace; attempt 2 (`--add-dir`) exit 0, file yes, DONE yes, 41 s | `src/adapters/agy.mjs` |
-| grok | 0.2.51 | exit 0, `stopReason: Cancelled`, no file: not logged in (device-code prompt) | `src/adapters/grok.mjs` exists, NOT registered |
+| grok | 1.0.34 | exit 1, no file, no DONE: the account answered `402 Payment Required: Grok Build usage balance exhausted`, classified `limit` (re-probed 2026-09-17; the 2026-09-11 run on 0.2.51 was not logged in) | `src/adapters/grok.mjs` |
 
 The auth-source check: the build shell carried `ANTHROPIC_API_KEY` and
 `OPENAI_API_KEY` (injected by the shell profile). Every adapter's `env()` deletes
@@ -165,29 +165,48 @@ stderr are 0 bytes, and codex's is the one stdin notice. observed-live.
 
 ## grok
 
-- Version grok 0.2.51 (f4f85a649) [stable] (source: `grok --version`).
+- Version grok 1.0.34 (3736acbc8658) [stable] (source: `grok --version`,
+  2026-09-17). The 2026-09-11 sweep saw 0.2.51 on a machine with no login; every
+  line below was re-read on 1.0.34.
 - Binary: `~/.grok/bin/grok.exe` (native; also an npm shim on PATH);
   `LEG_GROK_BIN` overrides (source: `where grok`).
-- Headless argv (from cmd.txt): `grok.exe -p "<prompt>" --output-format json --permission-mode acceptEdits`; stdin `ignore`.
-  `--prompt-file <path>` also exists (source: `grok --help`).
-- Output: one JSON object `{text, stopReason, sessionId, requestId, thought}`
-  (observed-live, fixtures/live/grok/out.log).
+- Headless argv (from cmd.txt): `grok.exe --prompt-file <run>/prompt.txt
+  --output-format json --permission-mode acceptEdits --cwd <worktree>`; stdin
+  `ignore`. The file form is used whenever the runner has written a prompt file,
+  because a hand-off prompt carries the whole bundle summary and Windows caps a
+  command line near 32k; with none, the adapter falls back to `-p "<prompt>"`
+  (source: `grok --help`, `-p, --single <PROMPT>` and `--prompt-file <PATH>`).
+  `--cwd <CWD>` is passed explicitly rather than trusting the spawn's working
+  directory, because grok can run against a shared leader process
+  (`~/.grok/leader.sock`) and a leg must edit its own worktree.
+- Output: the Claude Code result envelope. `"type":"result"`, `subtype`,
+  `is_error`, `session_id`, `result`, `num_turns`, `stop_reason`, `total_cost`,
+  read out of the shipped `grok.exe` on 2026-09-17 alongside the streaming
+  types (`assistant`, `system`, `text`, `usage`, `end`, `error`). An error is
+  the other envelope, `{"type":"error","message":…}` (observed-live,
+  `fixtures/live/grok/out.log`).
 - Exit codes:
 
   | exit | meaning | source |
   |------|---------|--------|
-  | 0 | printed JSON with `stopReason:"Cancelled"` and did no work: the CLI was not logged in, printed a device-code prompt on stderr (`https://accounts.x.ai/oauth2/device?user_code=…`, "Waiting for authorization...") and gave up after ~58 s | observed-live, fixtures/live/grok/err.log |
-
-  A zero exit with no DONE marker and no diff is exactly the `no_progress` class
-  the completion contract exists for.
-- Permission modes: `default`, `acceptEdits`, `auto`, `dontAsk`,
-  `bypassPermissions`, `plan` (source: `grok --help`). Leg: default
-  `acceptEdits`; forbidden `bypassPermissions`, `--always-approve`.
+  | 1 | printed `{"type":"error","message":"Internal error: … API error (status 402 Payment Required): Grok Build usage balance exhausted"}` and did no work: the account had no balance left | observed-live 2026-09-17, fixtures/live/grok/out.log |
+  | 0 | printed JSON with `stopReason:"Cancelled"` and did no work: the CLI was not logged in, printed a device-code prompt on stderr and gave up after ~58 s | observed-live 2026-09-11 on 0.2.51 |
+
+  The 402 is a wall, not a failure: `fixtures/limits/grok/grok-balance-exhausted.json`
+  classifies it `limit`, so the card hands off instead of stopping. None of the
+  rate-limit strings the tap watched for appear in a 402, which is why an
+  exhausted grok terminal used to sit there; `src/taps/grok.mjs` reads it too now.
+- Permission modes: `default`, `acceptEdits`, `auto`, `dontAsk`, `plan`, and a
+  bypass mode Leg never passes (source: `grok --help`). Leg: default
+  `acceptEdits`; forbidden the bypass mode and `--always-approve`.
 - Login: `grok login` (source: `grok --help` Commands).
-- **Verdict: not verified, no adapter registered.** `src/adapters/grok.mjs` is
-  built from `--help` and unit-tested for shape and forbidden flags, but stays
-  out of `src/adapters/index.mjs` until `grok login` has been completed on the
-  machine and `node scripts/probe.mjs --adapter grok --repo <toy>` passes.
+- **Verdict: registered, wall path verified, success path not.** The probe
+  reached the account through the real runner, so the binary resolution, the
+  argv, the auth and the limit classification are all observed-live. A leg that
+  completes its task has not been seen, because that needs balance on the
+  account; until it is, a grok leg whose envelope does not parse is judged by
+  its `.leg/DONE` marker and its diff, as every adapter is. Re-run
+  `node scripts/probe.mjs --adapter grok --repo <toy>` with balance to close it.
 
 ## `leg harness` (the portable harness)
 
@@ -224,26 +243,78 @@ variable and `LEG_SESSION` (source: src/attach.mjs, src/env.mjs).
 
 ### claude tap
 
-- Attach: `claude <args> --settings <LEG_HOME>/sessions/<id>/claude-settings.json`
+- Attach: `claude <args> -n "leg#<short id> <repo>/<branch>" --settings <LEG_HOME>/sessions/<id>/claude-settings.json`
   (source: src/attach.mjs `spawnSpec`; src/taps/claude.mjs `writeSettings`).
   Hooks in a `--settings` file merge with the user's rather than replacing
   them; `statusLine` is the one key that replaces, so Leg runs the user's own
   command first (source: code.claude.com/docs/en/settings;
   src/taps/claude.mjs `userStatusLine`). observed-live 2026-09-11: a Leg
   session ran with every user hook still firing.
+- Terminal title: `-n, --name <name>` "Set a display name for this session
+  (shown in the prompt box, /resume picker, and terminal title)" —
+  fixtures/help/claude.txt line 132. It sits in the general Options block, not
+  among the flags marked "only works with --print", and two of its three
+  surfaces (the prompt box, the `/resume` picker) exist only in interactive
+  mode, so it is the interactive title flag. Leg passes
+  `leg#<short id> <repo>/<branch>`; a `-n` or `--name` the human passed is
+  never overwritten. codex, agy and grok have no such flag, so Leg writes OSC 2
+  (`\x1b]2;leg#7f3a leg/main\x07`) to stdout once before the child spawns, and
+  only on a TTY. **ASSUMED**: that the child does not overwrite the title once
+  it starts drawing; no terminal has been read either way yet.
 - Hooks written (source: src/taps/claude.mjs `settingsFor`): `SessionStart`,
   `UserPromptSubmit`, `PostToolUse` with matcher `Edit|Write|MultiEdit|NotebookEdit`,
+  `Notification` with matcher
+  `permission_prompt|idle_prompt|agent_needs_input|quota_auto_resume_fired`,
   `Stop`, `StopFailure`, `SessionEnd`, each
   `node <src>/hook.mjs claude-hook --session <id>` with a 20 s timeout.
-  observed-live 2026-09-11 (hook.log in the session directory).
+  observed-live 2026-09-11 for the six that shipped then (hook.log in the
+  session directory); the `Notification` entry is docs-only until a real
+  permission prompt is captured.
+- Waiting on a human: the `Notification` hook. It "matches on notification
+  type" and, not being one of the two narrower events (FileChanged,
+  StopFailure), takes `|` as its alternation separator
+  (https://code.claude.com/docs/en/hooks lines 1424, 173, 165). The payload
+  carries `message`, an optional `title` and `notification_type` (line 1480).
+  `permission_prompt`, `idle_prompt` and `agent_needs_input` write
+  `session.waiting = { type, message (verbatim, 160 chars), since }`;
+  `UserPromptSubmit` and `Stop` clear it. `permission_prompt` fires only after
+  the prompt has waited about six seconds and shares its timing with desktop
+  notifications, so in a terminal it arrives only when the human appears to be
+  away (lines 1162, 1443): "waiting on you" is late by design and must not be
+  sold as instant.
+- The toast: the hook prints `{"terminalSequence":"\x1b]9;<message>\x07"}`.
+  Notification hooks cannot block or modify anything and their `systemMessage`
+  and `continue` are discarded, but Claude Code still emits `terminalSequence`
+  for them (lines 1490, 622). The field is restricted to OSC 0/1/2/9/99/777 and
+  BEL, and is ignored wholesale if anything outside that rides in it (line
+  608), so control bytes in the message are stripped first. OSC 9 is what
+  Windows Terminal, iTerm2, ConEmu and WezTerm render (line 617). Gated on
+  `preferences.notify_terminal`, default true.
 - `autoContinueAtUsageLimit: false` in the same file, because Leg owns the
-  hand-off (source: src/taps/claude.mjs `settingsFor`).
+  hand-off (source: src/taps/claude.mjs `settingsFor`). If the human's own
+  settings re-enable it, the `quota_auto_resume_fired` notification arrives
+  anyway; Leg then writes `waiting = { type: 'quota_auto_resume' }` and the
+  automatic hand-off stands down for that terminal (src/attach.mjs
+  `handoffStoodDown`). Two waiters on one terminal is the failure to avoid.
+- The model that answered: each assistant line of the transcript carries
+  `message.model` (VERIFIED: 29 lines of the newest jsonl for this repo read
+  `claude-fable-5-1`). The runner reads the tail of that file on the usage poll
+  and says it as its alias (`fable`), so a silent fallback off Fable shows on
+  the row; an id matching no alias is kept raw (src/taps/claude.mjs
+  `modelFromTranscript`, `modelAlias`).
 - Usage: `GET https://api.anthropic.com/api/oauth/usage`
   (`LEG_CLAUDE_USAGE_URL` overrides) with `Authorization: Bearer <accessToken>`
   from `<CLAUDE_CONFIG_DIR>/.credentials.json` key `claudeAiOauth`, and header
   `anthropic-beta: oauth-2025-04-20`; response fields `five_hour` and
   `seven_day`, each `{ utilization, resets_at }`; polled every
   `LEG_USAGE_POLL_MS` ms, default 60000 (source: src/taps/claude-usage.mjs).
+  A `limits[]` array, when the response carries one, becomes the per-model
+  buckets; a row's `scope.model.display_name` is joined to the alias the rest of
+  Leg uses by matching a known name as a whole word, so `Fable 5.1` and
+  `Claude Opus 5` are `fable` and `opus` and a name Leg does not know keeps its
+  own lowercased text. A response with no `limits` key is an older endpoint
+  answering: the key is omitted rather than sent as `[]`, because that is no
+  information about buckets and must not erase the measured ones.
   observed-live 2026-09-11: real windows came back and were written to
   `<LEG_HOME>/usage/claude--default.json`; a seven_day window at 93 %
   raised the amber warning.
@@ -367,7 +438,11 @@ variable and `LEG_SESSION` (source: src/attach.mjs, src/env.mjs).
 
 - `<LEG_HOME>/usage/<agent>--<account>.json`:
   `{ five_hour: {pct, resets_at}, seven_day: {…}, limited_until,
-  limited_reason, source, updated_at }` (source: src/usage.mjs).
+  limited_reason, source, updated_at, buckets, walls, history, extra_usage,
+  facts }` (source: src/usage.mjs). The last five are the per-model half of the
+  record: measured buckets, walls attributed from wording, a 24-sample ring per
+  bucket, the credits block and agent-measured strings. See
+  [concepts.md](concepts.md).
 - Warning threshold `WARN_PCT`, default 85, from `LEG_WARN_PCT`; the warning
   is an amber card, an event, and one terminal bell (source: src/usage.mjs,
   src/attach.mjs).
@@ -391,6 +466,142 @@ in [VOCABULARY.md](VOCABULARY.md). Board routes: `GET /api/sessions`,
 `POST /api/sessions/:id/end`, `DELETE /api/sessions/:id`, with the list pushed
 as the SSE `sessions` event (source: src/server.mjs, src/board/sessions.js).
 
+`session.ahead` is the number of commits the checkout is past its upstream, or
+past `head_at_start` when it tracks nothing. It is counted with `git rev-list
+--count <base>..HEAD` on the runner's git poll and is `null`, never `0`, when
+this is not a repository or the count could not be taken (source:
+src/attach.mjs `aheadCount`). Like the dirty file list, it is owner-only:
+`redactSession` drops it from another human's row.
+
+`GET /api/sessions` also carries `cards_waiting`, so the terminals verdict can
+name a waiting card without reading the pipeline board:
+`{count, first: {id, title, station, since}}`, where `count` is the number
+of cards in `needs_approval` or `waiting_human` and `first` is the one that has
+been waiting longest (`since` is its `updated_at`), or `null` when none is. A
+count alone cannot write `card 3e1c has waited on you for 12 minutes.`, which
+is the sentence the field exists for (redesign C.5). It is sent to anyone who
+may use cards, which is the owner and any operator; a guest has no cards and is
+not sent it (source: src/server.mjs `cardsWaiting`).
+
+A guest's own row carries no figure that was measured from this machine's
+logins: `limits`, `all_out` and `usage_source` are dropped, `warning` keeps its
+window and loses its percentage and its clock, a
+`limit` or a `waiting` of type `reset` keeps its words and loses its
+`resets_at`, and a `handoff_targets` row carries no `cost` (the word `credits`
+on a `claude/fable` rung is the owner's `extra_usage` setting by another name).
+A row that is available carries no reason at all, because the reserve and
+`below:N` notes are advice for a human press, not a refusal. Someone else's row
+is redacted further: no `limits`, and `warning` is reduced to its window
+(source: src/server.mjs `redactSession`, `scrubOwnerUsage`).
+
+### Making a card over HTTP
+
+`POST /api/cards` takes the same body `createCard` takes from the CLI, with one
+difference: `pipeline` must be a preset name (`build`, `build-land`, `factory`)
+or an inline array of stations. A path to a JSON file is a CLI convenience
+(`leg card add --pipeline ./my.json`) and is refused here with `400
+invalid pipeline: pipeline must be one of the presets ... or a list of
+stations`, naming no path and quoting no bytes: an operator may post cards and
+may not read this machine, and the JSON parser's own message quotes the first
+characters of whatever file it opened (source: src/cards.mjs
+`allowPipelineFile`).
+
+`chain` is a comma list (`claude,codex`) or an array of entries
+(`[{adapter, model?, mode?, max_turns?}]`). The array form is what the board's
+one-line entry posts, because it is the only one that can put a different model
+on each leg: `[{adapter: 'claude', model: 'fable'}, {adapter: 'claude', model:
+'opus'}]` is two legs on one login, which `--model claude=fable` (one model per
+adapter) cannot express.
+
+### A terminal becomes a card, and a card becomes a terminal
+
+`POST /api/sessions/:id/end-as-card` (owner or operator; a guest is refused)
+writes the terminal's hand-off bundle with `saveSessionBundle`, creates a card
+whose task is the terminal's prompt plus `Continue from the bundle at <path>.`,
+starts the card's chain at the rung the terminal is standing on, records
+`lineage.from`, and then requests `end` on the terminal exactly as
+`POST /api/sessions/:id/end` does. `201` with
+`{card, bundle, carried: {files, adopted}}`. Where the card works, and when it
+starts, depend on what the terminal had:
+
+- **Its own worktree.** The card adopts it (`worktree_adopted: true`, so no
+  later run cuts a second worktree on that branch) and is created in
+  `backlog`, not `queued`: `end` is a request the terminal's runner reads on
+  its own poll, and the scheduler ticks once a second, so queuing it at once
+  would put a headless agent in the working tree the interactive one is still
+  writing to. The board polls the session record and enqueues the card the
+  moment it is no longer active; if the terminal is still going ten minutes
+  later, the card stays in the backlog with a `blocked_by` line saying so and
+  Run is left to the human. `heldByLiveTerminal` in src/scheduler.mjs refuses
+  to start such a card whatever queued it.
+- **No worktree of its own** (the ordinary case: a terminal cuts one only when
+  a second live session shares the checkout). A checkout of its own is cut from
+  the terminal's branch and the uncommitted work is carried into it before the
+  terminal is asked to stop: a patch of everything git tracks
+  (`git diff HEAD --binary`, applied with `git apply`) plus the bytes of every
+  file it does not (`git ls-files --others --exclude-standard`, skipping Leg's
+  own directories and `node_modules`). `carried.files` is how many paths moved.
+  The card is queued at once, because nothing else is in that checkout.
+
+The bundle is written first, and the uncommitted work is read before anything
+is created: if either fails, nothing is created, nothing is ended, and the
+terminal is left running with `409` (source: src/server.mjs).
+
+`POST /api/cards/:id/take-over` moves the card to `paused` through the
+`take_over` transition, killing the child of a running one, and answers `200`
+with `{card, command}`, where `command` is `leg <agent> --resume-card <card-id>`
+for the agent on the card's current leg. Every non-terminal status is paused,
+not only `running`: a `queued` or `handing_off` card is in the set the
+scheduler starts from, so leaving it there would launch a leg into the same
+worktree the human was just handed. One `taken_over` event with the caller's
+name is appended whatever the starting status, and it is in the audit trail. A
+card in `done`, `failed` or `killed` is refused with `409` (source:
+src/server.mjs, src/chain.mjs).
+
+`leg <agent> --resume-card <id>` is Leg's own flag and never reaches the
+agent's argv. It opens an ordinary interactive terminal in that card's
+worktree, whatever directory it was run from, primed with the card's bundle as
+the first prompt and with `lineage.from` naming the card. The id may be the
+full card id or a unique tail of it; an ambiguous one is refused by name with
+the matches listed, and an unknown one exits `3` (source: src/attach.mjs
+`takeFlagValue`, `resolveCardId`, `takeOverPrompt`).
+
+A live card's board payload carries what was measured and nothing else: `work`
+`{files, insertions, deletions}` parsed from `git diff --shortstat
+<trunk>..HEAD` in its worktree, `tests` `{state, at}` and `land` `{state,
+reason, sha}` read from the card's own ledger. A key that could not be measured
+is absent; a finished card carries none of them (source: src/server.mjs
+`parseShortstat`, `cardOutcomes`, `summarize`).
+
+### The hand-off ladder
+
+`leg sessions handoff <id> --to <agent>[/<account>[/<model>]]` names the rung
+directly. Three parts are unambiguous; with two, the second is read as an
+account when the agent has one by that name, else as a model when the agent
+has one by that name, else the command is refused by name rather than guessed
+at (source: bin/leg.mjs `parseTarget`). `leg sessions simulate-limit <id>
+--message "<text>"` drives that exact wording through the real classifier
+(`src/hook.mjs` for claude, the session's own log for agy and grok), which is
+how a per-model wall is reached without waiting for a real one; codex has no
+Leg-owned input to simulate through and is refused by name (source:
+bin/leg.mjs `simulateLimit`).
+
+`leg ladder` (also `leg ladder ls`) prints the ladder, rung 1 first, each with
+its live state (a wall and its clock, a percentage, or "no figure") and the
+reason it would be skipped right now, then the spending, climb-back, reserve
+and derived-order lines. `leg ladder set <n> <agent>[/<account>[/<model>]]
+[--when always|below:N|walled-only]` writes rung `n` (past the end of the
+ladder, it appends); `leg ladder rm <n>` removes rung `n` and refuses to
+remove the last rung left; `leg ladder spend on|off` flips `may_spend`
+(source: bin/leg.mjs `ladderCommand`).
+
+Board routes: `PATCH /api/settings` (owner only) also accepts
+`handoff_ladder`, `climb_back`, `may_spend`, `reserve`, `notify_terminal` and
+`notify_board`. `POST /api/sessions/:id/handoff-order` accepts either
+`{handoff_order}` or `{handoff_ladder}` and rewrites both on the session.
+`POST /api/sessions/:id/handoff` accepts `target.model` alongside
+`target.agent` and `target.account` (source: src/server.mjs).
+
 ### History index
 
 `<LEG_HOME>/history/index.json` is the one file `leg history` writes: per
@@ -428,12 +639,13 @@ non-zero exit → `failed`. Every outcome except `completed`, `auth_failed` and
 `killed` asks the chain to hand off.
 
 <!-- limits-table:start -->
-Generated by `node scripts/limits-table.mjs` from 22 fixtures (4 observed-live, 18 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Leg itself; `info` must never classify as a limit.
+Generated by `node scripts/limits-table.mjs` from 24 fixtures (6 observed-live, 18 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Leg itself; `info` must never classify as a limit.
 
 | id | adapter | class | where | source | text (excerpt) | produced by |
 |----|---------|-------|-------|--------|----------------|-------------|
 | agy-resource-exhausted | agy | limit | any | **docs-only** | resource-exhausted | `agy changelog` ("Fixed personal accounts hitting a resource-exhausted error at startup"); agy --help documents no limit wording; falls back to the generic matchers |
 | claude-budget-limit | claude | budget | any | **docs-only** | Budget limit reached | https://code.claude.com/docs/en/cli-reference (--max-budget-usd) |
+| claude-fable-limit | claude | limit | any | **observed-live** | You've reached your Fable limit. Run /usage-credits to continue or switch models with /mod | fixtures/live/claude/limit-rate_limit.json: StopFailure error rate_limit, last_assistant_message on the real run, 2026-09-11 (a per-model wall: the account's session and weekly windows were open) |
 | claude-max-turns | claude | budget | stdout | **observed-live** | {"type":"result","subtype":"error_max_turns","is_error":true,"stop_reason":"tool_use","ter | fixtures/real-run/leg1/out.log: `claude -p --max-turns 2` on the real run, 2026-09-10 (docs: https://code.claude.com/docs/en/cli-reference --max-turns "Exits with an error when the limit is reached") |
 | claude-model-limit | claude | limit | any | **docs-only** | You’ve hit your Opus limit | https://code.claude.com/docs/en/costs ("You’ve hit your Opus limit" / "You’ve hit your Sonnet limit") |
 | claude-session-limit | claude | limit | any | **docs-only** | You’ve hit your session limit | https://code.claude.com/docs/en/costs (section: When a developer asks about a limit) |
@@ -449,6 +661,7 @@ Generated by `node scripts/limits-table.mjs` from 22 fixtures (4 observed-live,
 | generic-rate-limit | * | limit | any | **docs-only** | rate limit | generic matcher; lowest priority |
 | generic-resource-exhausted | * | limit | any | **docs-only** | RESOURCE_EXHAUSTED | generic matcher (gRPC RESOURCE_EXHAUSTED); lowest priority |
 | generic-usage-limit | * | limit | any | **docs-only** | usage limit | generic matcher; lowest priority |
+| grok-balance-exhausted | grok | limit | any | **observed-live** | API error (status 402 Payment Required): Grok Build usage balance exhausted | grok 1.0.34 -p --output-format json on an account with no balance left, 2026-09-17: stdout {"type":"error","message":"Internal error: {   \"message\": \"API error (status 402 Payment Required): Grok Build usage balance exhausted\",   \"http_status\": 402 }"}, exit 1 |
 | grok-not-logged-in | grok | auth | stderr | **observed-live** | To sign in, open this URL in your browser:    https://accounts.x.ai/oauth2/device?user_cod | fixtures/live/grok/err.log from scripts/probe.mjs --adapter grok, 2026-09-10 (stdout JSON stopReason: Cancelled, exit 0) |
 | grok-rate-limit | grok | limit | any | **docs-only** | You've hit the rate limit for your plan. Try again later. | crates/codegen/xai-grok-shell/src/sampling/error.rs:18 (RATE_LIMITED_USER_MESSAGE_OAUTH: "You've hit the rate limit for your plan. Try again later.") |
 | auth-source-set | * | auth | stderr | **docs-only** | another auth source is set | project brief (Wes, 2026-09-10): stderr saying "another auth source is set" counts as a failed launch; wording not yet observed live |

package/docs/concepts.md

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