@ucsandman/legcli 0.7.0

package/docs/faq.md

@@ -0,0 +1,206 @@
+# FAQ
+
+Real questions, short answers, sourced from the code and the other docs in
+this directory.
+
+**Why subscription CLIs only, never a per-token API?**
+Leg spawns each CLI's own logged-in session (`claude`, `codex`, `agy`).
+Every child process has `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`,
+`ANTHROPIC_BASE_URL`, `ANTHROPIC_CUSTOM_HEADERS`, `OPENAI_API_KEY`,
+`OPENAI_BASE_URL`, `OPENAI_API_BASE`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`,
+`GOOGLE_GEMINI_BASE_URL`, `GOOGLE_GENAI_USE_VERTEXAI`,
+`GOOGLE_GENAI_USE_ENTERPRISE`, `GOOGLE_CLOUD_PROJECT`,
+`GOOGLE_CLOUD_LOCATION`, `GOOGLE_APPLICATION_CREDENTIALS`, `CLAUDECODE`,
+`CLAUDE_CODE_*`, `CLAUDE_EFFORT`, and `CLAUDE_PLUGIN_DATA` stripped out
+(`src/env.mjs`), then gets `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` for a
+detached Claude print session. A stray API key in your shell cannot silently
+take over billing or shadow the subscription login. If stderr ever says
+"another auth source is set", that leg is classified `auth_failed`, a failed
+launch, and does not count as a usage limit.
+
+**Why does Leg poll an endpoint for claude's usage instead of reading the
+status line?**
+Because Claude Code 2.1.268 did not run a custom status line from a settings
+file Leg controls when this was tried on 2026-09-11 (recorded in
+[DEVIATIONS.md](DEVIATIONS.md)); hooks from the same `--settings` file did
+fire. So the numbers come from
+`GET api.anthropic.com/api/oauth/usage` with the login Claude Code already
+stored, which is the same data `/usage` shows. Leg still writes the
+`statusLine` entry, so the endpoint poll becomes a fallback the moment a build
+honours it, and your own status-line command is chained first either way. See
+[adapters.md](adapters.md#claude) and `src/taps/claude-usage.mjs`.
+
+**Why does codex get no hook when claude does?**
+Because injecting one would put a prompt in your way. codex asks you to review
+new hooks before it runs them, so a hook per Leg session would mean a
+review prompt per Leg session. It is not needed: an interactive codex writes
+the whole thread to a rollout file under `~/.codex/sessions/YYYY/MM/DD/`, and
+flushes it per event. Leg finds the rollout whose `session_meta` cwd is the
+session's directory and tails it for the rate limits, the prompts and the
+edited files.
+
+**Why does agy show no percentage?**
+Because agy exposes none. agy 1.2.0 is a closed Go binary; its own status line
+fetches a quota summary from the backend and writes it nowhere on disk. The
+board shows "no % from agy" rather than an empty bar. The wall itself is still
+caught: Leg passes `--log-file` per session and watches for
+`RESOURCE_EXHAUSTED`, "it resets in …" and "out of quota". Those strings are
+present in `agy.exe`. A real `RESOURCE_EXHAUSTED` wall was caught live on
+2026-09-11 and handed the session off; the fixture in `fixtures/limits/agy/`
+is still tagged docs-only in [cli-contracts.md](cli-contracts.md#agy-tap)
+because the payload itself was never captured to `fixtures/live/agy/`.
+
+**Am I allowed to add a second account?**
+That is your call, and the terms are quoted in full in the README under
+"Second accounts, and what the terms say" (`leg accounts terms` prints the
+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`.
+
+**What does `leg uninstall` remove?**
+`~/.leg` and nothing else: sessions, usage files, the extra account
+directories with their junctions, the v0.1 cards and runs, and the board
+pidfile. It removes the junctions as links, never following them into your
+real `~/.claude` or `~/.codex`. It does not touch any file of yours, any repo,
+or the agent CLIs themselves. Run `leg uninstall` with no flag to print what
+would go, `--yes` to do it; then `npm rm -g legcli` if you want the
+package gone too.
+
+**Can I run `leg claude` inside a Claude Code shell?**
+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,
+unrelated to the parent's.
+
+**Why are `--dangerously-skip-permissions` and similar flags never
+available?**
+Each adapter's `argv()` calls `assertAllowed()`
+(`src/adapters/common.mjs`), which checks the requested mode against that
+adapter's `allowed` list and rejects any flag on its `forbiddenFlags` list,
+before anything spawns. Requesting `bypassPermissions`, `--yolo`,
+`--full-auto`, `danger-full-access`, or similar throws immediately; nothing
+ever runs with permission checks off.
+
+**What actually happens when a pipeline leg hits a usage limit?**
+(For an interactive session, see [concepts.md](concepts.md#handoff-interactive).)
+`src/limits.mjs` classifies the leg's exit code, output and diff evidence as
+`limit`. Leg writes a handoff bundle in the same worktree (task, done so
+far, the diff, open findings) via `context-handoff-bundle`, then starts the
+next adapter in that station's chain from the bundle's resume text. If the
+chain has no next adapter, the card fails. See
+[concepts.md](concepts.md#outcomes-and-the-classifier).
+
+**Can two agents edit the same files at the same time?**
+Not inside one card: a station runs one chain leg at a time. Across cards,
+the scheduler only starts a queued card when its declared leases (path
+globs) do not overlap any running card's leases (`src/leases.mjs`); the
+default lease is `**` (the whole repo), so two cards with no leases set
+always serialize. The overlap check is a deliberate approximation biased
+toward false positives: an unnecessary serialization costs minutes, a
+wrongly parallel card can corrupt a merge.
+
+For terminals: a second `leg <agent>` in a checkout that already has a live
+session gets its own worktree and branch, so the two never write over each
+other's files. Whoever presses Land first fast-forwards trunk; the second one
+rebases onto it, or bounces with the conflicting files named on the card.
+`--no-worktree` shares the checkout when that is what you want.
+
+**Can someone else watch my board?**
+Only if you run `leg share on`, which is off by default. It binds your
+Tailscale or LAN address and prints one link per human (`leg share add
+<name>`), each with its own token. A guest sees the terminals lane read-only
+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
+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?**
+`node bin/leg.mjs up --dry` prints a preflight table with `ok`/`missing`
+per adapter. A missing adapter only matters if a card's chain names it: that
+leg fails to launch (`launch_failed`), which does not advance the chain,
+install and log in, then press Rerun. A chain only needs the adapters it
+names; leave a missing one out.
+
+**How do I resume after a reboot or a crash?**
+Every run's `run.json` under `$LEG_HOME/cards/<id>/runs/<n>/` is the
+source of truth, not process memory. `leg down` kills active agents but
+each run's supervisor still writes its final verdict; the next `leg up`
+(or the scheduler) finds any unsettled run with no live driver and
+re-attaches to apply that verdict, logging a `re-attached to run N` event.
+Nothing manual to do beyond starting Leg again.
+
+**Does Leg push to GitHub, or open pull requests?**
+No. The default `land_mode: ff` only rebases and fast-forwards the local
+trunk branch inside the repo you gave it; there is no remote write anywhere
+in `src/worktree.mjs` or `src/mergequeue.mjs`. `land_mode: pr` builds a real
+`gh pr create` argv but is stub-only: it refuses to run unless
+`LEG_GH_BIN` points at a real `gh` (or a test stub), and even then it
+never pushes or creates a remote for you, that is out of scope for this
+build.
+
+**Is there a hosted version of Leg?**
+No. Leg is local-first: the board binds `127.0.0.1` by default, every
+card's state lives in files under `LEG_HOME`, and there is no service to
+sign into. See [configuration.md](configuration.md#network-exposure) for
+what changes if you deliberately bind it to a shared address.
+
+**How are secrets handled?**
+`src/redact.mjs` holds one pattern list (API keys, bearer tokens, GitHub and
+AWS tokens, `key=value` secrets); `scrub()` rewrites matches to
+`[REDACTED]` in every log line the launcher prints and in handoff bundle
+text, and the ledger's own writer refuses to record an event whose summary
+or body matches a secret pattern at all. Every adapter's `env()` strips the
+API-key/base-URL variables from the child process. `npm test` and the
+pre-commit hook both run `scripts/privacy-check.mjs`, which additionally
+scans the whole tree for a short list of strings specific to the private
+codebase Leg's runner/ledger were ported from.
+
+**What happens if I close the terminal instead of Ctrl-C?**
+The board server and any running agents keep running as detached processes.
+Run `node bin/leg.mjs down` (or `npm run stop`) from another terminal to
+stop them cleanly, or just start `leg up` again later: it re-attaches to
+any run left in progress rather than launching a duplicate.
+
+**Can I run a card without the board?**
+Yes: `node bin/leg.mjs card run <card-id>` drives one card through the
+orchestrator directly and exits when it reaches a waiting or terminal
+state, printing the final status. `node bin/leg.mjs card show <id>` and
+`card events <id>` work without the server running too, since they read the
+same on-disk ledger the board reads.
+
+**What does `LEG_NO_SCHEDULER=1` do, and why would I set it?**
+It boots the board server without its embedded scheduler, so no queued card
+starts automatically, useful when you want to drive every card by hand
+with `card run` (for example, inside a test) while still watching it on the
+board.
+
+**Is there a limit to how long a chain can be, or how many legs a card can
+take?**
+No fixed limit; the chain array can be as long as you like. A card fails
+only when a leg's outcome needs to hand off and the chain has no next entry
+left, or (separately) after `LEG_MAX_LAND_ATTEMPTS` test/land bounces.
+
+**Windows vs macOS/Linux: what's actually verified?**
+Built and tested on Windows (every worktree, git and taskkill path in the
+source has Windows-specific handling: `MSYS_NO_PATHCONV=1`, `taskkill /T
+/F`, native `.exe` resolution). CI (`.github/workflows/ci.yml`) runs the
+full test suite on both `ubuntu-latest` and `windows-latest` on every push
+and pull request.
+
+**How do I report a bug?**
+Open a GitHub issue using the bug report template
+(`.github/ISSUE_TEMPLATE/bug_report.md`). For a security vulnerability, do
+not open a public issue, see [SECURITY.md](../SECURITY.md) instead.
+
+**Where do I find the exact word Leg uses for a given status, event, or
+button?**
+[VOCABULARY.md](VOCABULARY.md): one table per category (statuses, outcomes,
+station kinds, event types, actor types, human actions, bounce reasons),
+pulled straight from the source identifiers.

package/docs/getting-started.md

@@ -0,0 +1,251 @@
+# Getting started
+
+For a developer setting up Leg for the first time on their own machine. The
+first four sections get an interactive agent running with the board alongside
+it. The v0.1 pipeline flow is section 7 onward.
+
+## 1. Prerequisites
+
+- Node 22 or newer (`package.json` sets `"engines": {"node": ">=22"}`).
+- git.
+- Python 3 with pip, for the `context-handoff-bundle` CLI. This is what writes
+  and reads the handoff bundles.
+- At least one coding-agent CLI, logged in: `claude`, `codex` or `agy`. You do
+  not need all three. With one installed you get the board and the usage
+  tracking; with two or more you also get the hand-off.
+
+## 2. Install
+
+```
+npm install -g @ucsandman/legcli
+pip install -U context-handoff-bundle
+```
+
+The source repository is private, so there is no clone to install from. The
+source you run ships in the package: `$(npm root -g)/legcli/src`, plain
+`.mjs`, nothing bundled. Read it before you trust it.
+
+## 3. Run an agent
+
+```
+cd <any repo>
+leg claude
+```
+
+That is the whole setup. `leg claude` runs the real Claude Code in this
+terminal with your own settings, hooks and skills. Anything after the agent
+name passes straight through:
+
+```
+leg claude --model haiku
+leg codex -m gpt-5.3-codex-spark
+leg agy
+```
+
+The first `leg <agent>` starts the board on http://127.0.0.1:4747 and opens
+it once in your browser. Later sessions reuse the same board. Set
+`LEG_NO_OPEN=1` to skip the browser.
+
+Leg strips `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`,
+`ANTHROPIC_BASE_URL`, `ANTHROPIC_CUSTOM_HEADERS`, `OPENAI_API_KEY`,
+`OPENAI_BASE_URL`, `OPENAI_API_BASE`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`,
+`GOOGLE_GEMINI_BASE_URL`, `GOOGLE_GENAI_USE_VERTEXAI`,
+`GOOGLE_GENAI_USE_ENTERPRISE`, `GOOGLE_CLOUD_PROJECT`,
+`GOOGLE_CLOUD_LOCATION`, `GOOGLE_APPLICATION_CREDENTIALS`, `CLAUDECODE`,
+`CLAUDE_CODE_*`, `CLAUDE_EFFORT`, and `CLAUDE_PLUGIN_DATA` from the agent's
+environment, then sets `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` for a detached
+Claude print session. The subscription login is always what runs. Nothing in
+`~/.claude`, `~/.codex` or agy's home is edited.
+
+## 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.
+- 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
+  old readings stale. Only an explicit backend available answer clears a prior
+  wall; no model turn or hardcoded quota is used.
+- A `context-handoff-bundle` for this session, refreshed every two minutes and
+  at every warning, limit and hand-off.
+- 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.
+
+Force a hand-off at any time with the **Hand off now** button on the card, or
+`leg sessions handoff <id>`.
+
+## Is the resume file still true?
+
+```powershell
+leg resume --check      # exit 0 current, 1 stale or unstamped, 3 none here
+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
+"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.
+
+## 5. Watching and steering from the CLI
+
+```
+leg sessions ls            every session and its usage
+leg sessions show <id>
+leg sessions events <id>
+leg sessions handoff <id>  same as the board button
+leg sessions end <id>
+leg sessions rm <id>       forget an ended session
+leg sessions simulate-limit <id>   drive the real limit path without a real wall (claude, agy)
+leg accounts ls            logins and their 5h/7d usage
+leg open | down | status   the board
+```
+
+On the board, **Remove** safely prunes an ended session only when its worktree
+is clean and its branch is already merged into the base. For a session that
+needs to be removed from the board while preserving its work, use the visible
+**Remove record** button, read its confirmation, and keep the worktree, branch,
+unmerged commits, and dirty files intact.
+
+## 6. Where files live
+
+Everything Leg writes goes under `LEG_HOME` (default `~/.leg`):
+
+```
+~/.leg/
+  sessions/<session-id>/
+    session.json           the live record the board renders
+    events.jsonl           the timeline
+    control.json           board to runner requests
+    hook.log               what Claude Code's hooks sent
+    claude-settings.json   the per-session --settings file
+    agy.log                agy's --log-file, agy sessions only
+  usage/<agent>--<account>.json
+  accounts/<agent>/<name>/ extra logins (see configuration.md)
+  landings.jsonl           every Land, for the landed-on-trunk list
+  board.log                the board server's output
+```
+
+In the repo you run in, Leg writes `.leg/` (session notes, `RESUME.md` and
+one `RESUME-<session-id>.md` per hand-off) and `.context-handoffs/` (the
+bundles). Both are added to `.git/info/exclude`, so they never show up in
+`git status`.
+
+`leg uninstall --yes` removes `~/.leg` and nothing else.
+
+## 7. Pipelines (extras)
+
+Version 0.1 worked the other way round: you dropped a task card on the board
+and Leg ran the agents headless in a git worktree, one per card, with a
+fallback chain, path leases, a scheduler and a merge queue. All of that still
+works and lives below the Terminals lane. It is no longer the way in.
+
+### Preflight
+
+```
+leg up --dry
+```
+
+One row per dependency (node, git, `context-handoff-bundle`, each registered
+adapter) with `ok` or `missing`, then exit without spawning anything. A
+`missing` adapter only matters if a card's chain names it.
+
+### Start the board with the scheduler
+
+```
+npm start
+```
+
+`npm start` runs the same preflight, boots the board server on
+`http://127.0.0.1:4747`, opens it, and streams prefixed, redacted logs. Ctrl-C
+stops the server and any agent it started. From another terminal: `npm run
+stop` (which runs `leg down`).
+
+### A card from the board
+
+Click **New card**. The form asks for:
+
+- **Repo path**: an absolute path to a local git repository (at least one
+  commit).
+- **Task**: the text prompt every agent leg gets.
+- **Pipeline**: `factory`, `build`, `build-land`, or `custom JSON`.
+- **Chain**: one row per adapter, in fallback order.
+- **Leases** (comma separated path globs), **Trunk branch** (default `main`),
+  **Land mode** (`ff` or `pr`), **Test command**, **Title**.
+- **Queue immediately**: leave it checked to start the card right away.
+
+### A card from the CLI
+
+```
+leg card add --repo <path-to-a-git-repo> --task "Add a LICENSE file" --chain claude --queue
+```
+
+Other flags `card add` accepts: `--pipeline <preset|file>`, `--mode
+<adapter>=<mode>`, `--max-turns <adapter>=<n>`, `--leases <glob,glob>`,
+`--trunk <branch>`, `--land-mode ff|pr`, `--test-command "<cmd>"`, `--title
+"<text>"`, `--slug <id>`, `--approve <adapter,...>`.
+
+The command prints the new card id. Show it, or run it directly:
+
+```
+leg card show <card-id>
+leg card run <card-id>
+leg card events <card-id>
+```
+
+### Try a pipeline with no real agent
+
+The `fake` adapter drives `bin/fake-agent.mjs`, a stand-in CLI, so you can see
+a full run without a subscription login:
+
+```
+leg card add --repo <path-to-a-git-repo> --task "demo" --chain fake --fake-mode fake=limit --queue
+```
+
+`FAKE_MODE` (set per adapter with `--fake-mode <adapter>=<mode>`) picks its
+behaviour: `success`, `incomplete`, `limit`, `stall`, `auth`, `crash`,
+`no_progress`, and the land-demo modes `break-test` / `fix-test` /
+`resolve-rebase`. A chain of two fake adapters (`--chain
+fake-claude,fake-codex --fake-mode "fake-claude=limit,fake-codex=success"`)
+shows a full handoff; see [DEMO.md](DEMO.md) for the walkthrough with
+screenshots.
+
+### Where a card's files live
+
+```
+~/.leg/
+  cards/<card-id>/
+    card.json                    the card's current state
+    events-<actor-key>.jsonl     one append-only file per writer
+    driver.lock                  the process driving the card, only while it runs
+    unsynced.jsonl               DashClaw records to retry (`ledger sync`), if any
+    runs/<n>/
+      run.json                   this run's status, outcome, exit code
+      prompt.txt                 the exact prompt sent to the adapter
+      out.log                    the adapter's stdout
+      err.log                    the adapter's stderr
+      supervisor.log             the runner's own log for this run
+  locks/land-<hash>.json         the merge queue's turn, one per repo root, while a land runs
+  ACTIVE.md                      generated summary of open cards
+  leg.pid                        written by `leg up`, removed on stop
+  scheduler.pid                  written by `leg scheduler start`
+```
+
+A card's own git worktree lives in the repo it targets, not under
+`LEG_HOME`: `<repo>/.leg-worktrees/<card-id>` on branch `leg/<card-id>`.
+
+## Next
+
+- [concepts.md](concepts.md): sessions, accounts, usage windows, the
+  interactive hand-off, then cards, stations, chains, leases and the land
+  station.
+- [board-guide.md](board-guide.md): every element of the board.
+- [configuration.md](configuration.md): every environment variable.

package/docs/real-run.md

@@ -0,0 +1,80 @@
+# Real run: claude → codex, no fakes
+
+One task, two real logged-in CLIs, the real handoff path. Run on 2026-09-10 on
+a scratch repo (`toy-real`: README, package.json with `"test": "node --test"`,
+one commit). Evidence: `fixtures/real-run/` (run records, logs, bundle `show`,
+events; home paths scrubbed to `~`).
+
+## Command
+
+```
+node bin/leg.mjs card add --repo <toy-real> --chain claude,codex --max-turns claude=2 --mode codex=workspace-write --pipeline build --title "calc module (real run)" --task "Create src/calc.mjs exporting add, sub, mul and div (div throws on division by zero). Create test/calc.test.mjs using node:test covering all four functions including the divide-by-zero case. Run node --test and fix until green. Then write .leg/DONE."
+node bin/leg.mjs card run card-20260911-0232-real-calc
+```
+
+`--max-turns claude=2` is the handoff trigger: the task needs more than two
+turns, so the first leg ends before the DONE marker.
+
+## Timeline (UTC, from `fixtures/real-run/events.jsonl`)
+
+| time | event | detail |
+|------|-------|--------|
+| 02:32:50 | card_created | actor human:local, chain claude > codex |
+| 02:32:51 | leg_started | adapter `claude`, run 1, `mode=default`, `--max-turns 2` |
+| 02:33:23 | leg_exited | **outcome `failed`**, exit 1, signal `claude-max-turns` (32 s) |
+| 02:33:24 | handoff_written | bundle `20260911-023324-baton-card-20260911-0232-real-calc-build-leg0`, quality **strong (0.65)** |
+| 02:33:25 | leg_started | adapter `codex`, run 2, `-s workspace-write` |
+| 02:35:39 | leg_exited | **outcome `completed`**, exit 0 (2 m 14 s) |
+| 02:35:40 | station_done, done | |
+
+Wall time: 2 m 50 s. `grep -c fake fixtures/real-run/events.jsonl` = 0.
+
+## Leg 1 (claude)
+
+The result JSON on stdout (`fixtures/real-run/leg1/out.log`) is the signal that
+was docs-only until this run and is now observed-live:
+
+```
+{"type":"result","subtype":"error_max_turns","is_error":true,"stop_reason":"tool_use","terminal_reason":"max_turns","num_turns":3, …}
+```
+
+Exit code 1, empty stderr, no `.leg/DONE`; the diff evidence saw one changed
+path (`.dashclaw-local/`, written by the machine's Claude Code hooks, not the
+task). Classification: `budget` signal `claude-max-turns` + non-zero exit →
+`failed`, handoff. (A budget cap is Leg's own setting, not a usage limit; it
+still hands off.)
+
+## The bundle
+
+`fixtures/real-run/bundle-show.txt`: Findings carry "Done so far", "Diff since
+leg start", the touched path; Open questions carry the outcome and exit code.
+Leg 2 picked the handoff up: its first message is "Proceeding from the last
+agent state" and its second tool call reads `.leg/CONTRACT.md` and the
+handoff file (`fixtures/real-run/leg2/out.excerpt.log`, items 1-3).
+
+## Leg 2 (codex)
+
+`fixtures/real-run/leg2/out.excerpt.log` (JSONL): codex read the resume,
+wrote `src/calc.mjs` and `test/calc.test.mjs`, ran the tests itself (its
+sandbox allowed `node --test` here; LESSONS 07-13 recorded a policy block on a
+different machine setup), wrote `.leg/PROGRESS.md` and `.leg/DONE`, and
+printed a summary. Verified inside leg 2
+(`fixtures/real-run/leg2/out.excerpt.log`, item 20), which ran the repo's
+`npm test` -> `node --test` in the worktree:
+
+```
+tests 5  pass 5  fail 0
+```
+
+The worktree holds `src/calc.mjs`, `test/calc.test.mjs` and
+`.leg/{CONTRACT.md, DONE, PROGRESS.md, handoff-build-leg0.md}`.
+
+## What this proves
+
+- The subscription logins were used: neither leg's stderr carries an
+  "another auth source" warning (`leg1/err.log` is empty, `leg2/err.log` is
+  one stdin notice), and `sanitizeEnv` strips ANTHROPIC_API_KEY and
+  OPENAI_API_KEY before any adapter starts (test/redact.test.mjs).
+- The handoff is CLI-agnostic: the bundle written after a Claude leg was
+  consumed by a Codex leg through the same `load` + contract prompt.
+- The DONE-marker contract classified both legs without parsing prose.

package/docs/review-2026-09-14.md

@@ -0,0 +1,72 @@
+# Review notes, 2026-09-14
+
+This is a requested thorough-review deliverable. It records confirmed fixes
+and the local evidence captured before publication. Current release outcomes
+are tracked on npm; release contents are in the packaged `CHANGELOG.md`.
+
+## Confirmed fixes
+
+| area | confirmed behavior | source and regression references |
+|---|---|---|
+| Codex quota | The board and an active Codex attach make a read-only app-server `account/rateLimits/read` request every 60 seconds. Durations identify windows: 300 minutes is 5h and 10080 minutes is 7d. An explicit available response, rather than a percentage, clears an old wall. | `src/server.mjs` `refreshCodexAccounts`, `src/attach.mjs` `refreshCodexUsage`, `src/taps/codex.mjs` `readCodexUsage`, `src/usage.mjs` `recordUsage`; `test/attach-core.test.mjs`, `test/server.test.mjs` |
+| quota display | Account bars read `<n>% used`; readings older than five minutes are stale. No model turn and no hardcoded quota supply the reading. | `src/board/sessions.js`, `src/usage.mjs`; `test/server.test.mjs` |
+| session removal | Normal removal is a safe prune. **Remove record** is a separate confirmed board action that preserves the worktree, branch, unmerged commits, and dirty files after its confirmation. | `src/board/sessions.js`, `src/server.mjs`, `src/worktree.mjs`; `test/server.test.mjs` |
+| concurrent terminal control | End and Hand off write through the session file lock, preventing competing control-file updates. | `src/sessions.mjs` `requestControl`, `src/server.mjs`; `test/attach-core.test.mjs`, `test/attach-e2e.test.mjs` |
+| landing | Landing rejects a wrong base branch, proves a branch is merged before safe pruning, and reruns tests after a retry rebase when trunk moves. | `src/land.mjs` `landSession` and `pruneSessionWorktree`, `src/mergequeue.mjs` `land`, `src/worktree.mjs`; `test/land.test.mjs`, `test/mergequeue.test.mjs`, `test/worktree.test.mjs` |
+| card recovery | An orphaned run can recover a card left in `handing_off` instead of occupying the scheduler indefinitely. | `src/orchestrator.mjs` `orphanedRun`, `src/scheduler.mjs`, `src/runner.mjs`; `test/runner.test.mjs`, `test/scheduler.test.mjs` |
+| board freshness | Guest-to-owner token changes restore pipeline controls; valid guest changes retain the terminal stream. Older card-list, drawer, log, Floor, and retired SSE responses cannot overwrite newer state. | `src/board/board.js`, `src/board/floor.js`; `test/board-updates.test.mjs` |
+| loopback authorization | Tokenless owner access requires a loopback peer and a loopback hostname. An attacker-controlled hostname that resolves or rebinds to `127.0.0.1` is refused on reads and writes even when its `Origin` matches its `Host`. | `src/auth.mjs` `isLoopbackRequest`, `src/server.mjs`; `test/dns-rebinding.test.mjs` |
+| Team refresh | A signed Team key is required for refresh. An expired signed key can refresh when its subscription remains active; this is subscription-level behavior, not individual-seat revocation. | `site/api/key.js`, `site/api/_lib.js`; `test/site-api.test.mjs`, `test/license.test.mjs` |
+| webhook delivery | Stripe webhook verification accepts multiple rotated `v1` signatures. Resend is given a stable event-and-delivery idempotency key; Resend retains that key for 24 hours, so this is not a claim of permanent deduplication. | `site/api/webhook.js`, `site/api/_lib.js`; `test/site-api.test.mjs` |
+
+## Evidence already observed
+
+- The final independent `npm test` run exited 0: 391 tests, 390 passed, none
+  failed or cancelled, and one POSIX-permission test was skipped on Windows.
+  The privacy check reported 0 findings across 256 files. Final lint and
+  `git diff --check` both exited 0.
+- The board-focused suite added deferred behavioral cases for guest/owner token
+  changes and stale card, drawer, log, and Floor responses. It reported 26
+  passing tests before this documentation change.
+- A live Codex app-server probe returned a weekly-only window as `primary`,
+  confirming that positional primary-to-5h mapping was wrong. The check did
+  not start a model turn; account-specific readings are omitted here.
+  The same weekly-only fixture failed against an archived `HEAD` copy because
+  the old parser put the 10080-minute object in `five_hour`; it passes now with
+  `five_hour=null` and the object in `seven_day`.
+- The DNS-rebinding regression failed against `HEAD` with `200 !== 401`, then
+  passed with the fix for both a read and a state-changing request. The focused
+  auth/share suite reported 35 passing tests.
+- After a board-only restart, `/api/health` returned 200. Frontend verification
+  passed `/` and `/floor` with no console errors or failed requests; the live
+  Codex pill rendered the weekly percentage from the app-server source and no
+  5h value. The New card form opened and Escape dismissed it without creating
+  data.
+- An independent security review passed the loopback authorization fix for the
+  normal API, SSE reauthorization, and the companion listener. Custom-host
+  bearer and share tokens remained valid while the attacker Host returned 401.
+
+## Review conclusions and rejected findings
+
+- Account labels expose intentional shared metadata, not an additional account
+  privacy defect.
+- Removing a landing session after the landing operation completes is not a
+  concurrent-removal bug if the final verifier confirms the operation boundary.
+- Resend retains an idempotency key for 24 hours while Stripe can retry live
+  webhooks for longer. A delayed retry can therefore resend the same license
+  email; it cannot create a duplicate charge or entitlement. Durable delivery
+  storage was not added because it would introduce new production state and
+  infrastructure beyond this local audit.
+
+## Retro
+
+Green baseline checks did not expose every race or operator-facing safety gap.
+Inspecting actual records and running deferred behavioral reproductions did.
+The permanent behavioral cases now cover the observed guest/owner and stale
+response failures so they do not rely on a future review to be rediscovered.
+
+## Deviation log
+
+The approved test update required a small refresh-auth protocol change so a
+valid guest token reconnects the sessions stream while pipeline controls remain
+hidden.