@ucsandman/legcli 0.10.0 → 0.12.0

package/docs/configuration.md

@@ -65,6 +65,64 @@ To opt out and keep standard approval prompts:
 2. Environment variable: set `LEG_AUTO_APPROVE=0` or `LEG_NO_AUTO_APPROVE=1` (or legacy `BATON_AUTO_APPROVE=0` / `BATON_NO_AUTO_APPROVE=1`).
 3. Persistent preference: set `"auto_approve": false` in `~/.leg/preferences.json`.
 
+### The hand-off ladder
+
+`~/.leg/preferences.json` also holds the ladder a terminal falls down when its
+login stops (`src/preferences.mjs`), alongside the older `handoff_order`:
+
+```json
+{
+  "handoff_order": ["claude", "codex", "agy"],
+  "handoff_ladder": [
+    { "agent": "claude", "account": "default", "model": "fable",  "when": "always", "cost": "plan" },
+    { "agent": "claude", "account": "default", "model": "opus",   "when": "always", "cost": "plan" },
+    { "agent": "claude", "account": "default", "model": "sonnet", "when": "always", "cost": "plan" },
+    { "agent": "codex",  "account": "default", "model": null,     "when": "always", "cost": "plan" },
+    { "agent": "agy",    "account": "default", "model": null,     "when": "always", "cost": "free" }
+  ],
+  "climb_back": "next-handoff",
+  "may_spend": false,
+  "reserve": {}
+}
+```
+
+| key | default | meaning |
+|-----|---------|---------|
+| `handoff_ladder` | `claude/fable`, `claude/opus`, `claude/sonnet`, then one rung per remaining agent in `handoff_order` with model `null` | the fallback list, rung 1 first; each rung is `{agent, account, model, when, cost}`. `model` is `null` or one of that agent's names in `src/buckets.mjs` `MODEL_ALIASES` (only claude has any: `fable`, `opus`, `sonnet`, `haiku`). `account` is `default` or a name this machine has for that agent (`leg accounts ls`); anything else is refused with a sentence, because that string becomes the CLI's config dir and the usage record's file name. `when` is `always`, `below:N`, or `walled-only`. `cost` is `free`, `plan`, `credits`, or `metered`, and is a static label; the live cost a rung would spend right now is computed from the agent and the login, never read off this key, so a ladder migrated from an older `handoff_order` still meets the spending gate on `grok` |
+| `climb_back` | `next-handoff` | `next-handoff` picks a recovered higher rung up again at the very next hand-off, with no extra step; `never` keeps a terminal on the rung it downshifted to until a human hands it off there by name |
+| `may_spend` | `false` | while `false`, an automatic hand-off skips any rung whose live cost is `credits` or `metered`, and records why; a human's own pick is not gated by this |
+| `reserve` | `{}` | `{ "<agent>": percent }`; an automatic hand-off will not take a rung on that login once its binding bucket is above `100 - percent`. A human's own pick still reaches it, and the picker names the reserve on that row instead of hiding it |
+
+A fresh install with no `preferences.json` starts with `claude/fable`,
+`claude/opus`, `claude/sonnet`, then every other installed agent from
+`handoff_order` with `model: null`.
+
+Leg writes `handoff_ladder` and `handoff_order` together and keeps them in
+step: saving a ladder rewrites `handoff_order` from its distinct agent order,
+and saving a bare `handoff_order` rewrites the ladder as one `model: null`
+rung per agent, so an older install behaves exactly as it did until a rung is
+edited. If the file is hand-edited so the two disagree, `handoff_order` wins
+and the ladder is rebuilt from it, because the order is the shape a hand
+edit is more likely to have meant.
+
+`leg ladder` (`leg ladder ls`) prints the ladder with each rung's live state;
+`leg ladder set <n> <agent>[/<account>[/<model>]]`, `leg ladder rm <n>` and
+`leg ladder spend on|off` change it. See [cli-contracts.md](cli-contracts.md).
+
+### Notifications
+
+`~/.leg/preferences.json` also holds two toggles for a terminal that is
+waiting on you (`src/preferences.mjs` `defaults()`):
+
+| key | default | meaning |
+|-----|---------|---------|
+| `notify_terminal` | `true` | "Terminal toast when a terminal waits on you": on Claude Code's own `Notification` hook (`permission_prompt`, `idle_prompt`, `agent_needs_input`), send an OSC 9 toast to the window the agent is already running in |
+| `notify_board` | `false` | "Browser notification when a terminal waits on you": fire a browser `Notification()` the moment a terminal row becomes `needsYou` and the reader is not looking at the board (a waiting card raises the tab badge and the verdict, not the notification); the board reads `window.isSecureContext` at render time and disables the toggle with an explanatory sentence where that is false |
+
+Both are set from Settings on the board, or by writing the key directly. The
+tab title badge (`(1) Leg` plus a favicon dot) has no toggle: it needs no
+permission, so it is always on.
+
 ## Core
 
 | variable | default | meaning | read in |
@@ -126,7 +184,8 @@ resolves to by default.
 | `LEG_CLAUDE_BIN` | claude | `src/adapters/claude.mjs` |
 | `LEG_CODEX_BIN` | codex | `src/adapters/codex.mjs` |
 | `LEG_AGY_BIN` | agy | `src/adapters/agy.mjs` |
-| `LEG_GROK_BIN` | grok (not registered by default) | `src/adapters/grok.mjs` |
+| `LEG_GROK_BIN` | grok | `src/adapters/grok.mjs` |
+| `LEG_<NAME>_BIN` | a custom adapter called `<name>` (dashes become underscores, so `my-agent` reads `LEG_MY_AGENT_BIN`) | `src/adapters/custom.mjs` |
 | `LEG_GH_BIN` | the `pr` land-mode stub | `src/stations/pr.mjs`; unset, `land_mode: pr` returns an error rather than running a real `gh` |
 | `LEG_CHB_BIN` | `context-handoff-bundle` | `src/handoff.mjs`; unset, Leg tries `context-handoff-bundle` on PATH, then `python -m context_handoff_bundle` |
 
@@ -210,9 +269,10 @@ other address without also setting `LEG_TOKEN` makes the server refuse to
 start, exit code `3` (`src/auth.mjs` `checkBind`/`BindRefused`). With a
 token set, every `/api/*` request needs an `Authorization: Bearer <token>`
 header; the event stream (`EventSource`, which cannot set headers) accepts
-the same token as a `?token=` query parameter instead. There is no TLS; keep
-`LEG_BIND` on loopback unless you are using `leg share`, which gives
-each human their own token (see [Share](#share-more-than-one-human)).
+the same token as a `?token=` query parameter instead. Keep `LEG_BIND` on
+loopback unless you are using `leg share`, which gives each human their own
+token (see [Share](#share-more-than-one-human)) and can serve the board over
+TLS.
 
 ## Share (more than one human)
 
@@ -224,7 +284,8 @@ switch and the roster; the env variables below only tune the limits.
 | `on` | share is on (it also needs a `bind` and at least one person) |
 | `bind`, `bind_kind`, `port` | where the board listens: the Tailscale address by default, `lan`, or one you named |
 | `owner` | the name a terminal belongs to when nothing else says (`LEG_PERSON`), and the name a loopback browser is treated as |
-| `people[]` | `{ name, role: owner\|guest, token_sha256, created_at }`; the token itself is printed once and never stored |
+| `people[]` | `{ name, role: owner\|operator\|guest, token_sha256, created_at }`; the token itself is printed once and never stored |
+| `tls` | `{ cert, key }`, the paths to a certificate pair; absent means plain http |
 | `loopback_owner` | default `true`: a browser on this machine is the owner without a token. Set it to `false` to ask for a link even here |
 
 | variable | default | meaning | read in |
@@ -234,6 +295,53 @@ switch and the roster; the env variables below only tune the limits.
 
 `LEG_TOKEN` is the single-token mode and is ignored while share is on.
 
+### Roles
+
+| role | terminals | cards | this machine |
+|------|-----------|-------|--------------|
+| `owner` | every one | every one | settings, harness policy, the trunk's repo paths, the history index, the worktree map, the audit trail |
+| `operator` | their own; someone else's is read-only and redacted | adds, runs, approves, reassigns, kills | nothing: `/api/settings`, `/api/history`, `/api/worktrees`, `/api/trunk` and `/api/audit` all answer 403, and `/api/health` omits the home path |
+| `guest` | their own; someone else's is read-only and redacted, with **Request handoff** as the only button | nothing: 403 | nothing |
+
+A guest and an operator both see their own terminal's hand-off destinations,
+so they can use the picker on it — but never the reset times behind them,
+which are this machine's usage data. `src/share.mjs` `mayUseCards` and
+`mayUseMachine` are the only place a role is turned into permission.
+
+### TLS
+
+Off unless a certificate pair is configured. Leg never issues one: a
+self-signed pair teaches everyone on the board to click through a warning,
+which is worse than plaintext on a network that is already private. On
+Tailscale, `tailscale cert <machine>.<tailnet>.ts.net` issues a pair browsers
+already trust.
+
+| variable | meaning | read in |
+|----------|---------|---------|
+| `LEG_TLS_CERT` | path to the certificate; wins over `share.json`'s `tls.cert` | `src/share.mjs` `readTls` |
+| `LEG_TLS_KEY` | path to the private key; wins over `share.json`'s `tls.key` | `src/share.mjs` `readTls` |
+
+`leg share on --tls-cert <file> --tls-key <file>` writes the pair into
+`share.json` and reads it once, so a bad pair fails there rather than at the
+next board start. With a pair configured the shared address serves https and
+every link `leg share` prints says `https://`. The companion listener on
+`127.0.0.1` — the one that lets this machine's own browser in without a token
+— stays plain http, because the certificate is for the shared name and
+loopback traffic never leaves the machine. Half a pair, a missing file, an
+unreadable file or an empty one stops the board with exit `3` rather than
+falling back to plaintext. A renewed pair is picked up by `leg down && leg up`.
+
+### The audit trail
+
+`GET /api/audit` (owner only) and Settings → **Audit trail** on the board: one
+list across every terminal and every card, newest first, of the actions a
+person or an agent took — hand-offs, landings, approvals, reassignments,
+kills. It reads the events already on disk and stores nothing new. Query
+parameters: `limit` (default 200, max 1000), `since` (an ISO timestamp), `who`
+(a name), `kind` (`human`, `agent` or `leg`). Every answer carries `scanned`
+— how many terminals, cards and events it read — so an empty trail cannot be
+mistaken for a quiet week.
+
 ## Card-level options
 
 These configure one card, not the whole install (set with `card add` flags

package/docs/faq.md

@@ -57,9 +57,25 @@ same summary). The short version: owning two paid subscriptions is not named
 as prohibited by Anthropic or OpenAI, but rotating to a second account of the
 same vendor because the first is rate-limited sits close to OpenAI's
 "circumvent any rate limits" wording and Anthropic's "circumvent product
-guardrails". Leg's default chain switches vendors (claude, codex, agy),
-which is plainly fine. Same-vendor rotation only happens after you run
-`leg accounts add`.
+guardrails". Leg's default fallback ladder switches vendors (claude, codex,
+agy) only after it has already tried claude's own weaker models (fable, opus,
+sonnet), which is plainly fine. Same-vendor rotation only happens after you
+run `leg accounts add`; switching models on one login, claude/fable to
+claude/opus, is not a second account at all and none of this applies to it.
+
+**Can I switch models mid-session, or does a hand-off always mean a different CLI?**
+Yes. `handoff_ladder` in `preferences.json` names an agent, account and model
+per rung (`src/preferences.mjs`), and a fresh install tries claude/fable, then
+claude/opus, then claude/sonnet before it ever leaves the claude login, then
+the other agents. A downshift to a weaker claude model with a known session id
+runs `claude --resume <id> --model <alias>` and keeps the conversation; every
+other rung takes the bundle as today. `may_spend` (default `false`) keeps an
+automatic hand-off off any rung whose live cost is `credits` or `metered`; a
+hand-off you press yourself can still take it. `climb_back` decides whether
+Leg returns to the top rung at the next hand-off (`next-handoff`, the default)
+or waits for you to press **Back to fable** (`never`). Edit the ladder with
+`leg ladder` or in Settings; see
+[configuration.md](configuration.md#the-hand-off-ladder).
 
 **What does `leg uninstall` remove?**
 `~/.leg` and nothing else: sessions, usage files, the extra account
@@ -74,7 +90,7 @@ package gone too.
 Yes. A parent Claude Code session exports `CLAUDECODE` and `CLAUDE_CODE_*`
 markers that make a nested Claude refuse to start; `sanitizeEnv`
 (`src/env.mjs`) strips them along with the API-key variables, so the child
-starts normally. It becomes its own session with its own card on the board,
+starts normally. It becomes its own session with its own row on the board,
 unrelated to the parent's.
 
 **Why are `--dangerously-skip-permissions` and similar flags never
@@ -118,7 +134,7 @@ and nothing a terminal has said, read or written: no prompt, no file names, no
 paths, no bundle, no events, no logs, and none of the pipeline side. The
 limit line keeps only the reason and the reset time, never the raw limit
 text. The one thing they can do on your terminal is ask for a hand-off, which
-you approve or dismiss on the card. `leg share off` ends it and every link
+you approve or dismiss on the row. `leg share off` ends it and every link
 stops working. There is no TLS, so keep it on Tailscale or a network you trust.
 
 **What if the CLI I want isn't installed?**

package/docs/getting-started.md

@@ -62,10 +62,12 @@ Claude print session. The subscription login is always what runs. Nothing in
 
 ## 4. What you get while it runs
 
-- A card on the board for this terminal: agent, account, repo@branch, the first
-  prompt, turns, the files being touched, 5h and 7d usage.
-- A warning at 85 % of either window (`LEG_WARN_PCT`): amber card, an event,
-  one terminal bell.
+- A row on the board for this terminal: status, repo@branch, dirty/ahead
+  counts, agent/model, the first prompt, turns, the files being touched, and
+  the capacity phrase for whichever bucket actually binds (a percentage, or a
+  forecast like `about 2h 40m of fable left` once there are enough readings).
+- A warning at 85 % of either window (`LEG_WARN_PCT`): the row goes amber, an
+  event, one terminal bell.
 - For Codex, the board and active attach poll the read-only app-server
   `account/rateLimits/read` response every 60 seconds. Leg maps the returned
   300- and 10080-minute durations to 5h and 7d, shows `<n>% used`, and labels
@@ -77,13 +79,15 @@ Claude print session. The subscription login is always what runs. Nothing in
   section before the raw bundle dump.
 - At the limit: the bundle is saved, the agent is stopped, and the next option
   starts in the same terminal from `.leg/RESUME-<session-id>.md`, copied to
-  `.leg/RESUME.md`. Order is other logins of
-  the same agent first, then the remaining agents (claude, codex, agy). When
-  every option is out, Leg prints each reset time, soonest first, waits with
-  a countdown, and starts the first one back from the bundle. Ctrl-C quits.
+  `.leg/RESUME.md`. The order is a ladder of rungs, each an agent, account and
+  model: a fresh install goes claude/fable, then claude/opus, then
+  claude/sonnet before it ever leaves the claude login, then the remaining
+  agents (codex, agy). `leg ladder` (or Settings) edits it. When every option
+  is out, Leg prints each reset time, soonest first, waits with a countdown,
+  and starts the first one back from the bundle. Ctrl-C quits.
 
-Force a hand-off at any time with the **Hand off now** button on the card, or
-`leg sessions handoff <id>`.
+Force a hand-off at any time with the **Hand off now** button on the row, or
+`leg sessions handoff <id> [--to <agent>[/<account>[/<model>]]]`.
 
 ## Is the resume file still true?
 
@@ -95,7 +99,7 @@ leg resume              # the same verdict, then the pointer itself
 Leg stamps every resume file with the commit, the working tree and the
 terminals it was written against, and recomputes freshness from git when you
 read it. A commit landing, the tree moving, or the terminal it described going
-away all make it stale; the terminal card's drawer shows the same verdict under
+away all make it stale; the terminal's expansion shows the same verdict under
 "What happens next". A session ending rewrites `RESUME.md` to say nothing is in
 flight, and the board does the same at start for a terminal that crashed, so
 nothing is left describing work that has moved on.