@ucsandman/legcli 0.9.0 → 0.11.0

package/docs/ERRORS.md

@@ -3,6 +3,139 @@
 What broke, why, and what fixed it. One entry per failure, newest first. A first
 occurrence has to be written down or a repeat is never countable.
 
+## 2026-09-17: a new field on the session view leaked the owner's reset times to a guest, through the guest's own terminal
+
+**Fixed in `src/server.mjs` (`sessionsView` decides `guest` before the map and
+blanks `handoff_targets[].resets_at` for one). Caught by
+`test/share-security.test.mjs`, which was already asserting it.**
+
+The hand-off picker needed each destination's availability, so `handoff_targets`
+went onto every session in `sessionsView` carrying `resets_at`. The obvious
+mental model was "a guest gets `redactSession`, which lists its fields
+explicitly, so a new field is invisible to them". That is only true of someone
+else's terminal. `mine(s)` is true for a guest's **own** terminal, and that path
+spreads the whole object. So a guest's own card carried the exact reset
+timestamp of every account on the machine, including the owner's, which is
+precisely the usage data the share design keeps off a guest's board.
+
+The lesson is about where redaction lives, not about this field. There are two
+paths out of `sessionsView`: `redactSession` (allow-list, safe by default) and
+the `mine(s)` spread (deny-list, unsafe by default). **Any field added to a
+session object is visible to whoever owns that session, and a guest owns one.**
+A field that carries machine-level data has to be blanked where it is built, not
+left to a redactor that never sees it.
+
+What made this cheap: the security suite already asserted the whole guest
+response text contains no reset time, so the leak failed a test in the same run
+that introduced it. The test was written against the property ("a guest board
+carries no reset time"), not against the fields that existed when it was
+written, which is why it still caught a field invented months later.
+
+Two smaller ones from the same change, both worth the line:
+
+- Registering `grok` broke three tests that asserted `unknown adapter "grok"`.
+  A test that encodes "not supported yet" as an assertion becomes a tripwire on
+  the day support lands. Assert the refusal with a name nothing will ever
+  provide (`no-such-agent`), so the test outlives the gap it was describing.
+- `names()` started reading `$LEG_HOME/adapters` from disk, and `/api/health`
+  calls it once for the list and once per adapter. That put a readdir, a read
+  and a JSON parse per spec on the same event loop the terminals lane is pushed
+  from, and `/api/health` went over its 1 s budget in
+  `test/board-responsiveness.test.mjs`. Cached against the directory's entry
+  list with a one-second floor. The board's hot path is `/api/health` plus the
+  sessions view; anything new they call has to be counted, not assumed cheap.
+  (This is the same event-loop failure as the entry below, from the other end.)
+- `test/board-responsiveness.test.mjs` failed the ship twice at 1055 ms and
+  1140 ms against a hard `< 1000 ms`, and passed three times out of three when
+  run alone. An absolute millisecond budget on a four-way-concurrent runner
+  measures the machine, not the code. It now takes an idle baseline in the same
+  process and asserts the busy request is not 20x it, with a 3 s ceiling for the
+  symptom the test is named for. **It was only trusted after being made to
+  fail**: putting the original shape back (no floor, no fingerprint, a 1.2 s
+  blocking view on every watcher event) made it report 4,810 ms and fail both
+  assertions, which is the "four to fourteen seconds" the entry below describes.
+  A perf test that has never been watched failing is a number, not a guard.
+
+## 2026-09-17: one running terminal saturated the board's event loop, and four separate symptoms came out of it
+
+**Fixed in `src/server.mjs` (watcher filter, stat fingerprint, push floor, cached
+`canLand`), `src/attach.mjs` (a taken port is a board; always open it) and
+`src/board/{board,sessions}.js` (one render per push, hold an open confirm row).
+Regression tests: `test/board-responsiveness.test.mjs`.**
+
+Reported as four bugs: `leg claude` took a long time to start, the board never
+opened by itself, the board was slow to load and to react, and Remove under
+Terminals did nothing. All four were one cause. The board server had burned
+17,080 seconds of CPU — it answered `/api/health` in 7 to 14 seconds and a
+40 KB stylesheet in 14. A live agent rewrites its session record every six
+seconds or so and takes a control lock about once a second; the recursive
+watcher over the sessions directory answered every one of those — including
+`.control.lock`, `.session.lock` and the `session.json.*.tmp` files atomic
+writes leave behind — with a full rebuild of the terminals view, which costs
+about two seconds (1.1 s of it `canLand` shelling out to git across twenty
+worktrees). 105 filesystem events in 30 seconds against a 300 ms debounce and a
+2,000 ms rebuild: the queue could never drain.
+
+What that one stall produced:
+
+- **Slow start.** `ensureBoard`'s health probe times out at 2 s, so a merely
+  busy board read as no board. `leg` spawned a second server, which died of
+  `EADDRINUSE` (the evidence was already in `~/.baton/board.log`), then polled
+  the dead child every 200 ms for the full 15 s.
+- **The board never opened.** `openBoard(url)` sat only on the branch that
+  successfully started a server. With one already running, or on the 15 s
+  give-up path, nothing was ever opened.
+- **Slow to react.** `board.js` dispatched `leg:sessions` and `baton:sessions`
+  per push, parsing the quarter-megabyte payload twice, with the second
+  dispatch outside the `state.es === es` staleness guard (missing braces on a
+  one-line `if`). `sessions.js` was registered on `leg:sessions` twice and on
+  the alias once. One push rebuilt the whole grid three times.
+- **Slow to react, part two.** `renderSessions` starts with
+  `grid.textContent = ''`, so with three rebuilds per push every button was
+  destroyed and recreated several times a second.
+
+**Remove was a second, independent bug, and fixing the first did not fix it.**
+Reported again as "it's still not removing them" after all of the above
+shipped. `confirmRow` does `pendingConfirm = null; onYes(yes)`, and the call
+site passed `(btn) => act(s.session_id, pendingConfirm.action, btn)` — a
+closure over the module variable, not over its value. Every Yes on the
+Terminals panel threw `TypeError: Cannot read properties of null (reading
+'action')` before reaching `act()`, so Remove, Remove record, End and Land had
+never worked from the confirm row; the exception went to the console and
+nowhere the reader would see it. Fixed by snapshotting
+`const pending = pendingConfirm` before building the row. Caught by driving the
+real page: the click produced zero network requests, which pointed at the
+handler rather than at anything server-side. The instrument that found it was
+five lines — wrap `window.fetch`, listen for `window.onerror`, click, read
+both.
+
+Three lessons. First, a name filter is not enough to classify a filesystem event:
+taking a lock inside a directory changes that directory's own mtime, and the
+event arrives naming only the directory. The watcher now treats an event as a
+hint and compares a stat fingerprint of the files the view is really built from
+— sub-millisecond, against a 2 s rebuild. Second, the CPU counter on a
+long-lived process names a stall in one command, before any code is read.
+
+Third, and the one that cost a round trip: several symptoms reported together
+are not thereby one bug. Three of these four were, and finding that cause made
+the fourth *look* explained — the render churn is a real way to drop a click,
+so "Remove doesn't work" fit the story. It was a different bug in a different
+file, and it was still there after the fix shipped. A symptom is only closed
+once it has been driven and watched, not once a plausible cause for it has been
+found and fixed. Clicking Remove in the real page would have taken two minutes
+and would have shown zero network requests and a `TypeError` in the console.
+
+Verified by running the new tests against `da453b7`: 7 of 8 fail there, 8 of 8
+pass after, and the busy-board test takes 21 s before versus 4 s after. On the
+live board, same 66 sessions: `/api/health` 14.19 s → 2.4 ms, `/board.css`
+14.24 s → 1.5 ms, `/api/sessions` 15.64 s → 109 ms, view rebuild 2,049 ms →
+115 ms, renders per push 3 → 1.
+
+Also found while verifying: `npm run lint` reported "ESLint: No issues found"
+with `node_modules/.bin` empty and eslint not installed — a wrapper was printing
+it. Run `npm install` first and check that ESLint really ran; a lint result from
+a tool that is not on disk is not a lint result.
+
 ## 2026-09-16: a hand-edited `package.json` version left `package-lock.json` behind, and the publish gate refused 0.9.0
 
 **Fixed by bumping the lockfile root version; the gate is `scripts/npm-publish-gate.mjs`.**
@@ -395,3 +528,57 @@ it), and check whether a board was listening on 4747 at the time.
   module that reads the environment at import time cannot be imported from a
   helper that runs before the environment is set, no matter how small the thing
   you wanted from it.
+
+## A 3,000-line feature landed with red CI on Windows and no docs page (2026-09-16)
+
+- **Symptom.** Commit `c7f24a0` (the history index, committed by the agy
+  session that took over after a Claude usage limit) went green on Ubuntu and
+  macOS and red on Windows in two `history.test.mjs` cases, and the `docs` job
+  failed with "site/ is out of date". `/docs/history` did not exist and every
+  link to `history.md` pointed at the npm package page.
+- **Root cause, tests.** GitHub's Windows runner hands out an 8.3 short TEMP
+  path (`RUNNER~1`) while git reports the long form (`runneradmin`). The two
+  assertions compared a `mkdtemp` path with a path that had been through git.
+  The repo already had the seam for this (`canonPath` in `src/fsx.mjs`,
+  used the same way in `handoff-order.test.mjs`); the new tests did not use it.
+  It cannot be seen on a developer machine with 8.3 names disabled.
+- **Root cause, docs.** `scripts/build-docs-site.mjs` builds from a hard-coded
+  `PAGES` list. A new `docs/*.md` that is not in it gets no page, and
+  `rewriteHref` sends its links to the npm URL by design. Nobody ran
+  `npm run docs` before pushing, so the docs job was the first to notice.
+- **Fix.** `ebda794`: both sides of the four path assertions through
+  `canonPath`; reproduced locally by pointing `TEMP` at a case-altered path
+  (seen failing, then 16/16); `history` registered in `PAGES`; site rebuilt.
+- **The lesson that generalises.** A test that compares two filesystem paths
+  on Windows compares two spellings of the same folder unless both go through
+  `canonPath`. And a new `docs/*.md` is two edits, the file and the `PAGES`
+  entry, then `npm run docs`; the docs job exists because the second and third
+  get forgotten.
+
+## The review that was in flight when the limit hit never ran; the feature shipped with 38 defects (2026-09-17)
+
+- **Symptom.** `c7f24a0` (history discovery) was committed and pushed by the
+  agent that took over after a Claude usage limit. The nine-lens adversarial
+  review the Claude session had launched died with that session. Re-run the
+  next day it confirmed 38 findings, 3 high: the board's Conversations cell
+  could never page past 150 rows (the total was counted after the cursor
+  slice), an unreachable UNC cwd blocked a refresh for seconds per record,
+  and an Antigravity retitle was invisible to every incremental refresh
+  (the directory's mtime was the cache key; an in-place rewrite never moves
+  it).
+- **Root cause.** The hand-off bundle carried "what was established" and
+  "next moves" but not "what was in flight": a background workflow is not a
+  file, so the next agent saw a clean-looking task and shipped it. Nothing
+  in the ship path asks whether the change was reviewed.
+- **Fix.** `582dfe5`: 20 findings closed, each with a test that fails on the
+  previous source (proved on a detached worktree of HEAD before the fix).
+- **Left open, by choice.** Coverage-only findings (live markers, the
+  write-scope guard, the flag surfaces, extra accounts), a low-severity
+  dedup edge (a conversation split over two Claude transcript files when Leg
+  recorded only the older path), the `sessions ls` row format, and the
+  pretty-printed index file.
+- **The lesson that generalises.** A review is part of the change, not a
+  step after it: launch it before the feature is committable and record it
+  in the hand-off as in flight, or the next agent ships without it. And a
+  cache keyed on a directory's mtime sees files added and removed, never a
+  file rewritten in place.

package/docs/README.md

@@ -7,6 +7,7 @@
 - [board-guide.md](board-guide.md): the instrument head (a row per login, two window rails each, the 85 percent post), the Terminals panels, overlap flags, Landed on main, Background tasks, Settings, and the floor view.
 - [configuration.md](configuration.md): every environment variable, the accounts layout, `.env`, network exposure, card-level options.
 - [harness.md](harness.md): the portable harness, off by default: what moves between agents and what does not, the first run, policies, ownership and backups, secrets, the evidence trail, and how Leg relates to the Agnostic AI engine it embeds.
+- [history.md](history.md): `leg history` and `leg worktrees`, one read-only index over every agent's own conversation store and every checkout, the support matrix per provider, dedup against Leg's own sessions, privacy, and how to add a provider.
 - [adapters.md](adapters.md): what Leg reads from each CLI in an interactive session, each adapter's headless argv, modes, forbidden flags, gotchas, and how to add a new one.
 - [faq.md](faq.md): short answers to real questions (the status line, codex's missing hook, agy's missing percentage, second accounts, uninstall, limits, secrets, Windows support).
 
@@ -25,7 +26,8 @@
 | interactive sessions | `src/attach.mjs` (the `leg <agent>` runner), `src/sessions.mjs` (the session store), `src/usage.mjs` (usage windows and the chooser), `src/accounts.mjs` (extra logins), `src/bundle.mjs` (the per-session bundle), `src/hook.mjs` (what Claude Code's hooks run) |
 | portable harness | `src/harness/index.mjs` (capture, compare, apply, status, the hand-off decision), `src/harness/registry.mjs` (which clients, where their files are), `src/harness/fingerprint.mjs`, `src/harness/cli.mjs` (`leg harness`), `src/harness/vendor/agnostic-ai/` (the engine, verbatim; `scripts/sync-harness-engine.mjs` is the only writer) |
 | taps | `src/taps/claude.mjs`, `src/taps/claude-usage.mjs`, `src/taps/codex.mjs`, `src/taps/agy.mjs` |
-| board | `src/server.mjs`, `src/board/sessions.js` (Terminals lane), `src/board/board.js` and `src/board/floor.js` (pipelines) |
+| history | `src/history/index.mjs` (the index, dedup, resume), `src/history/providers/*.mjs` (one per agent store, read only), `src/history/worktrees.mjs` (the unified checkout view), `src/history/cli.mjs` (`leg history`, `leg worktrees`) |
+| board | `src/server.mjs`, `src/board/sessions.js` (Terminals lane), `src/board/history.js` (Conversations), `src/board/board.js` and `src/board/floor.js` (pipelines) |
 | pipelines | `src/orchestrator.mjs`, `src/scheduler.mjs`, `src/chain.mjs`, `src/pipeline.mjs`, `src/runner.mjs`, `src/ledger.mjs`, `src/leases.mjs`, `src/mergequeue.mjs`, `src/adapters/*.mjs` |
 
 ## History

package/docs/ROADMAP-v2.md

@@ -1,5 +1,13 @@
 # Roadmap v2: the software factory
 
+**Unreleased (2026-09-17) opened the chain and finished the share story.** grok is
+a registered card adapter; any other CLI becomes one from a JSON spec
+(`leg adapter add`, no code); **Hand off now** can name its destination
+instead of taking the next in the order; `leg share` grew TLS from a
+certificate pair you supply, an `operator` role between owner and guest, and
+an audit trail of who did what across every terminal and every card. That
+closes items 1 and 4 below, and the "hand off now to \<adapter>" picker.
+
 **0.3.0 (2026-09-11) shipped item 1 and the first half of continuous landing.**
 A second live session in one checkout gets its own worktree and branch, and
 **Land** on its card sends that branch through the merge queue (rebase, tests,
@@ -33,23 +41,28 @@ event names its actor, a board that reads only the ledger, and an auth/bind seam
 
 ## Next
 
-1. **Multi-human network access**, shipped in 0.3.0 as `leg share` (a token
-   and a name per human, per-human actor ids on every event, rate limits, a
-   guest's read-only redacted board). What is left: TLS termination, token
-   scopes finer than owner and guest, and an audit view of who did what across
-   sessions.
+1. ~~**Multi-human network access**~~ — done. 0.3.0 shipped `leg share`; the
+   unreleased work of 2026-09-17 shipped the three that were left: TLS (`leg share on --tls-cert/--tls-key`,
+   or `LEG_TLS_CERT`/`LEG_TLS_KEY`, from a pair you supply — Leg issues none),
+   the `operator` role between owner and guest, and the audit trail
+   (`/api/audit`, Settings → Audit trail).
 2. **Review station with human reviewers**: a `human` station kind that shows
    the diff, the bundle and the test tail, with Approve / Request changes /
    Reassign as buttons; reviewer identity from the token.
 3. **`pr` land mode live**: `gh pr create` argv is built and stub-tested today;
    run it for real behind an explicit per-card opt-in and a remote allowlist.
-4. **More adapters**: grok (adapter written, unregistered until `grok login` and
-   a passing probe on the machine) and muse only if a real CLI is verified; a
-   generic "argv + JSON result" adapter for anything else.
+4. ~~**More adapters**~~ — done. grok is registered (2026-09-17: flags read
+   from `grok --help` on 1.0.34, envelope read from the shipped binary, probe
+   reached the account and returned a real 402 wall that classified `limit`;
+   the success path is still unprobed for want of balance). Anything else,
+   muse included, is a custom adapter: a JSON spec in
+   `$LEG_HOME/adapters/<name>.json`, `leg adapter add`, no code
+   ([adapters.md](adapters.md#custom-adapters)).
 5. **OpenClaw Workboard mirror** once the bundled plugin is allowed
    (`plugins.allow`): the verb table in `src/sync/workboard.mjs` is the only
    thing to check against `openclaw workboard --help`.
 
-Also on the list: per-station prompt templates editable from the board, a
-"hand off now to <adapter>" picker, lease suggestions from the diff of the
-previous leg, and a floor view that shows lease contention over time.
+Also on the list: per-station prompt templates editable from the board, lease
+suggestions from the diff of the previous leg, and a floor view that shows
+lease contention over time. (The "hand off now to \<adapter>" picker landed
+2026-09-17, unreleased: Details → **Hand off now to**, or `leg sessions handoff <id> --to`.)

package/docs/VOCABULARY.md

@@ -47,6 +47,7 @@ Source: the `appendEvent`/`updateSession` call sites in `src/attach.mjs`,
 | `handoff` | the switch happened: from, to, reason, bundle id |
 | `all_out` | every option is walled; the resets are printed and the terminal waits for the first one (`ended` with "quit while waiting" if Ctrl-C or End cuts the wait short, exit 3) |
 | `agent_exit` | the agent process exited, with its code |
+| `continued` | the session was started by `leg history continue` on a conversation the agent's own store holds; `session.json` carries `continued_from: { id, provider, native_id }` |
 | `ended` | the session ended |
 | `lost` | the runner pid is gone; the session was marked `lost` |
 | `error` | a spawn error, a tap error, a failed bundle checkpoint, or an error the agent reported |

package/docs/adapters.md

@@ -239,25 +239,107 @@ These are what a pipeline card's chain spawns. Unchanged since 0.2.0.
   `emulates` to that CLI's name, so the limit classifier applies that CLI's own
   fixtures to it and a demo chain reads like a real fallback.
 
-### grok (built, not registered)
+### grok (headless)
 
 - **Binary**: `LEG_GROK_BIN`, else `~/.grok/bin/grok.exe`, else `grok` on
   PATH.
-- **Argv**: `grok -p "<prompt>" --output-format json --permission-mode
-  <mode>`, plus `-m <model>`, `-r <session-id>`.
+- **Argv**: `grok --prompt-file <run>/prompt.txt --output-format json
+  --permission-mode <mode> --cwd <worktree>`, plus `--max-turns <n>`,
+  `-m <model>`, `-r <session-id>`. Every flag was read from `grok --help` on
+  grok 1.0.34 (`3736acbc8658`) on 2026-09-17. The prompt travels by file
+  rather than on argv because a hand-off prompt carries the whole bundle
+  summary and Windows caps one command line at about 32k; with no prompt file
+  the adapter falls back to `-p "<prompt>"`. `--cwd` is passed explicitly
+  rather than relying on the spawn's working directory: grok can run against a
+  shared leader process (`~/.grok/leader.sock`), and a leg must edit its own
+  worktree, not whatever directory the leader started in.
 - **Stdin**: `ignore`.
 - **Modes**: default `acceptEdits`; allowed `default`, `acceptEdits`,
   `auto`, `dontAsk`, `plan`.
 - **Forbidden flags**: `--always-approve`, `bypassPermissions`,
   `--permission-mode=bypassPermissions`.
-- **Status**: `src/adapters/grok.mjs` exists and is unit-tested, but is
-  **not** in `src/adapters/index.mjs`'s registry. The build machine had no
-  `grok` login: the probe printed a device-code prompt and exited
-  `Cancelled`. Register it (add an entry to `REGISTRY` in
-  `src/adapters/index.mjs`) once `grok login` has been completed and
-  `node scripts/probe.mjs --adapter grok --repo <toy-repo>` passes.
-
-## How to add an adapter
+- **Result**: grok's headless writer emits the Claude Code result envelope.
+  The field names (`"type":"result"`, `subtype`, `is_error`, `session_id`,
+  `result`, `num_turns`, `stop_reason`, `total_cost`) were read out of the
+  shipped `grok.exe` on 2026-09-17. An error is the other envelope,
+  `{"type":"error","message":…}`, observed live the same day.
+- **Status**: registered on 2026-09-17. The probe reached the account and came
+  back with a real wall — `API error (status 402 Payment Required): Grok Build
+  usage balance exhausted`, exit 1, classified `limit` and handed off — so the
+  spawn, the argv, the auth and the wall path are all verified live
+  (`fixtures/live/grok/`). The **success** path of a grok leg is still
+  unprobed: that needs balance on the account. Until it is, a grok leg whose
+  envelope does not parse falls back to the `.leg/DONE` marker and the diff,
+  which is what every adapter does when `parseResult` returns null. Re-run
+  `node scripts/probe.mjs --adapter grok --repo <toy-repo>` with balance to
+  close it.
+
+## Custom adapters
+
+Any other coding-agent CLI becomes a card adapter through a JSON spec in
+`$LEG_HOME/adapters/<name>.json`, with no code in this package. This is the
+open end of the chain: claude, codex, agy and grok ship with taps and a probe,
+and anything else joins as "argv in, JSON out".
+
+A custom adapter runs **cards**: headless, in a worktree, handing off like any
+other leg. It is not an interactive `leg <agent>` terminal, because that needs
+a usage tap and a wall signal, which only the four built-ins expose.
+
+```
+leg adapter template --name muse > muse.json   # a starter spec
+leg adapter add muse.json                      # validate and install it
+leg adapter check muse                         # the exact command a leg would run
+leg card add --repo <path> --task "<t>" --chain muse,claude --queue
+leg adapter list | show muse | rm muse
+```
+
+The spec:
+
+```json
+{
+  "name": "muse",
+  "bin": "muse",
+  "stdin": "ignore",
+  "args": ["run", "--json",
+           ["--dir", "{{cwd}}"],
+           ["--model", "{{model}}"],
+           "--prompt-file", "{{promptFile}}"],
+  "modes": { "default": "auto", "allowed": ["auto", "readonly"] },
+  "forbiddenFlags": ["--unsafe"],
+  "result": { "format": "json", "sessionId": "session_id",
+              "message": "result", "stopReason": "stop_reason" }
+}
+```
+
+- **`bin`** is argv[0]. It is spawned directly, never through a shell, so it
+  cannot contain `< > | & ;`. `LEG_<NAME>_BIN` overrides it. A `.mjs`, `.cjs`
+  or `.js` path runs under this Node.
+- **`args`** is a list of strings and groups. Placeholders: `{{prompt}}`,
+  `{{promptFile}}`, `{{cwd}}`, `{{mode}}`, `{{model}}`, `{{resume}}`,
+  `{{maxTurns}}`, `{{runDir}}`. A bare string is always kept; a **group** (a
+  nested array) is dropped whole when a placeholder inside it has no value, so
+  `["--model", "{{model}}"]` disappears rather than passing a bare `--model`.
+  Something has to carry the prompt: `{{prompt}}`, `{{promptFile}}`, or
+  `"stdin": "pipe"`.
+- **`modes`** is validated before anything spawns, the same way a built-in's
+  is: a chain entry naming a mode outside `allowed` throws `forbidden flag`.
+- **`forbiddenFlags`** is yours to add to. The flags that turn a supervised
+  agent into an unsupervised one are refused whatever the spec says, in `args`,
+  in `modes` and at argv time (`NEVER_ALLOWED`, `src/adapters/custom.mjs`).
+- **`result.format`** is `json` (the first parseable object in stdout),
+  `jsonl` (the last line carrying the message field) or `text` (no parsing).
+  `sessionId`, `message` and `stopReason` are dotted paths, so
+  `"sessionId": "thread.id"` reads `{"thread":{"id":…}}`. With `text`, or when
+  nothing parses, the leg is judged by its `.leg/DONE` marker and its diff,
+  which is what happens for any adapter whose `parseResult` returns null.
+
+A broken spec is reported, never thrown: `leg adapter list` names the file and
+the reason, and the board, the scheduler and `leg card add` carry on without
+it. A spec may not take a built-in's name. The directory is re-read whenever
+the list is asked for, keyed on its entries, so a spec added while the board is
+up appears in the New card form without a restart.
+
+## How to add a built-in adapter
 
 An adapter is a plain object (see `src/adapters/common.mjs` for the shared
 helpers, `src/adapters/fake.mjs` for the simplest full example):

package/docs/board-guide.md

@@ -317,7 +317,7 @@ before saving.
 
 ## The ledger
 
-Below the terminals, three counts sitting on the ground with no panel, because a
+Below the terminals, four counts sitting on the ground with no panel, because a
 raised surface here would compete with the terminals that are live. Each is a
 heading, a line of detail and a button that opens the detail below the row.
 
@@ -334,6 +334,25 @@ heading, a line of detail and a button that opens the detail below the row.
   visual weight as the live terminals, so the loudest thing on the page was a
   commit from eleven days ago. With nothing landed it reads `Nothing landed yet`
   and explains what Land does.
+- **N conversations**, every coding-agent conversation on this machine, `799
+  claude, 198 codex, 92 agy, 14 grok, 5 copilot; looked 2m ago`: the sessions
+  Leg started and the ones the agents keep in their own stores, read from
+  there and never moved ([history.md](history.md)). **Browse N** opens a
+  drawer with filters (agent, search, repository, only what Leg started), a
+  page of fifty rows newest first and **Show 50 more**. A row is the title as a
+  button, then the agent chip, `leg` or `external` (`, live` when a process is
+  still on it), `repo on branch`, the prompt count and the short id. The title
+  opens the conversation in place: agent, who started it, folder, repository,
+  worktree, times, prompts, transcript path, id, the `leg history continue
+  <id>` command with **Copy the continue command** where the agent can resume
+  by id (or the reason it cannot), **Copy folder path**, and the last eight
+  messages newest first, each redacted the way the terminal drawer's are. Below
+  the rows, **Checkouts**: every worktree Leg can see with its repo and branch,
+  owner (the checkout itself, a Leg session, a Leg card, or not Leg's), how
+  many conversations point at it, and `missing`, `orphaned`, `stale`, `clean`
+  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.`

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)
 
@@ -391,6 +410,20 @@ 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).
 
+### History index
+
+`<LEG_HOME>/history/index.json` is the one file `leg history` writes: per
+provider, per transcript, size, mtime and a small scrubbed record (source:
+src/history/index.mjs). What each provider reads from its CLI's own store,
+with the observed file and field names, is the header of each
+`src/history/providers/<name>.mjs`; the support matrix and the resume
+commands quoted from each CLI's `--help` (observed-live 2026-09-16: `claude
+--resume <id>`, `codex resume <id>`, `grok --resume <id>`, `agy --conversation
+<id>`; copilot has none Leg has verified) are in [history.md](history.md).
+Board routes, owner only: `GET /api/history`, `GET /api/history/:id`,
+`GET /api/history/providers`, `POST /api/history/refresh`,
+`GET /api/worktrees` (source: src/server.mjs, src/board/history.js).
+
 ## Limit signals
 
 Recorded in `fixtures/limits/<group>/<id>.json` and classified by

package/docs/configuration.md

@@ -126,7 +126,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` |
 
@@ -200,6 +201,7 @@ Not meant for normal use; documented for completeness.
 |----------|---------|---------|
 | `LEG_SKIP_KILL` | set to `1` to make the supervisor skip actually killing a leg's process (used by tests that need an "unkillable agent") | `src/runner.mjs` |
 | `LEG_SERVER_SCRIPT` | override the server script path the launcher spawns | `src/launcher.mjs` |
+| `COPILOT_HOME` | where `leg history` looks for the Copilot CLI store instead of `~/.copilot` (Claude, Codex and Grok use their own `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `GROK_HOME`; Antigravity has no variable and is found under the OS home) | `src/history/providers/copilot.mjs` |
 
 ## Network exposure
 
@@ -209,9 +211,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)
 
@@ -223,7 +226,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 |
@@ -233,6 +237,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