@ucsandman/legcli 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## 0.10.0 (2026-09-17)
+
+- **The board is responsive again, `leg` starts straight away, and the board
+  opens every time.** One running terminal was enough to saturate the board
+  server: it rewrites its record every few seconds and takes a control lock
+  about once a second, and the watcher over the sessions directory rebuilt the
+  whole terminals view — over a second of `git` — for every one of those
+  touches, including the lock files and the temp files atomic writes leave
+  behind. The server spent all its time in that loop, so it answered a
+  stylesheet in fourteen seconds and `/api/health` in seven. Four consequences,
+  all fixed:
+  - The watcher now drops locks and temp files by name, and checks the rest
+    against a stat fingerprint of the files the view is actually built from,
+    because a lock taken inside a session directory changes that directory's
+    own mtime and arrives as an event naming nothing else. What survives is
+    floored to one rebuild per interval. `canLand` is cached per record
+    revision with staggered expiries, so twenty worktrees are never re-read in
+    one pass. The terminals view went from 2,000 ms to 115 ms; on a board with
+    66 sessions `/api/health` went from 14.2 s to 2.4 ms and `/board.css` from
+    14.2 s to 1.5 ms.
+  - `leg claude` treated a board too busy to answer a health probe as no board
+    at all, spawned a second server that could only die of `EADDRINUSE`, then
+    polled the dead child for fifteen seconds. A listener on the port is now a
+    board: `leg` attaches to it.
+  - The board is opened whether or not this terminal is the one that started
+    it. Previously the browser was only opened on the path that spawned the
+    server, so with a board already running nothing ever opened.
+  - One push rebuilt the terminals grid three times (two listeners registered
+    for `leg:sessions` and one for the legacy alias, with the payload parsed
+    twice per push and one dispatch outside the staleness guard). Every button
+    was destroyed and recreated several times a second. One push now rebuilds
+    once, and an open confirm row is left alone until it is answered.
+
+- **Remove, Remove record, End and Land work.** Confirming any of them did
+  nothing at all. `confirmRow` clears `pendingConfirm` and then calls its
+  callback, and the callback read `pendingConfirm.action` — off the variable it
+  had just cleared. Every Yes on the Terminals panel threw
+  `TypeError: Cannot read properties of null (reading 'action')` into the
+  console and never reached the request. The callback now closes over a
+  snapshot taken before the row is built.
+
+- **Every conversation on this machine (`leg history`, `leg worktrees`, the
+  board's Conversations cell).** One read-only index over the conversations
+  Claude Code, Codex, Grok, Antigravity and Copilot CLI keep in their own
+  stores, plus Leg's own sessions, deduplicated (a session Leg started and
+  the same conversation in the agent's store are one row, marked `leg`; the
+  rest are `external`). List, filter by agent, repository or text, open one
+  (its last messages, read from the tail of the transcript only when asked),
+  and `leg history continue <id>` to start a supervised leg on it where the
+  installed CLI documents resume-by-id (claude, codex, grok, agy; copilot
+  lists and reads but is not an agent Leg runs). Nothing in an agent's store
+  is moved or written; Leg writes only `~/.leg/history/index.json`, refreshed
+  incrementally by size and mtime, and never opens a SQLite file. Every
+  checkout Leg can see, git's and its own and the ones conversations ran in,
+  with owner, uncommitted count, orphaned, stale and missing verdicts, read
+  only. On a shared board the whole group is the owner's. Redaction learned
+  the shapes another agent's transcript carries (Stripe, Google, xAI, npm,
+  GitLab, Hugging Face keys, JWTs, private-key blocks, basic auth, URL
+  credentials, `password=`), and the board token joined the values it strips.
+  Support matrix and every file read: docs/history.md.
+- **History, after its review.** The board's Conversations cell pages past
+  150 rows (the total no longer shrank with each cursor page); the board
+  refreshes a stale index in a child process instead of its own event loop;
+  a cwd on an unreachable network share no longer stalls a refresh; an
+  Antigravity retitle or a touched presence lock is seen by an incremental
+  refresh, and only that conversation is re-read; an older Leg session id
+  still opens the conversation it was one leg of; `leg history` prints a
+  failed refresh whatever the last index still lists, `refresh` fails cleanly
+  when another Leg holds the lock, `--limit 0` is a usage error (`--all`),
+  `--offset` works, a Leg-only row's id prints whole; a malformed id on
+  `/api/history/<id>` is a 400; an account name that is a path is ignored;
+  titles are cut to 200 as documented and go through the held-value
+  redaction too; the Copilot chip has a colour. Redaction no longer eats
+  `Basic authentication/authorization`, `cache_key = ...` or
+  `refresh_token: string`, and a value never crosses a line break.
+
 ## 0.9.0 (2026-09-16)
 
 - **The portable harness (`leg harness`), off by default.** A hand-off can now

package/README.md

@@ -95,6 +95,7 @@ yourself.
 - [Two sessions in one repo](#two-sessions-in-one-repo)
 - [More than one human](#more-than-one-human)
 - [The board](#the-board)
+- [Every conversation on this machine](#every-conversation-on-this-machine)
 - [Second accounts, and what the terms say](#second-accounts-and-what-the-terms-say)
 - [What is and is not touched](#what-is-and-is-not-touched)
 - [CLI reference](#cli-reference)
@@ -336,12 +337,40 @@ one sam's; sam's board showed wes's card with the prompt hidden and only
 - **Buttons**, in a fixed order that never reflows: Land, Hand off now,
   Details, End. Once a session has ended, Remove and Remove record take End's
   place. Details opens an expansion in flow under the panel.
-- Below it, optional **Background tasks** an agent runs in a separate worktree
-  without joining the terminal conversation (see below), then **Settings**.
+- Below it, **Conversations**: every coding-agent conversation on this machine
+  as a count that opens, the ones Leg started and the ones Claude Code, Codex,
+  Grok, Antigravity and Copilot keep in their own stores. Filter by agent,
+  search, repository, or only what Leg started; a row opens its last messages
+  in place, with the `leg history continue` command to copy where the agent
+  can resume by id. The same drawer lists every checkout Leg can see. Then
+  optional **Background tasks** an agent runs in a separate worktree without
+  joining the terminal conversation (see below), then **Settings**.
 
 The board reads `~/.leg/sessions/*/session.json` over server-sent events; a
 session whose runner process is gone is marked `lost`, never shown as live.
 
+## Every conversation on this machine
+
+Claude Code, Codex, Grok, Antigravity and Copilot each keep their history in
+their own place. `leg history` is one list over all of them, whether or not
+Leg started the conversation, and `leg worktrees` is one list over every
+checkout: git's, Leg's own, and the ones those conversations ran in.
+
+```
+leg history                          newest first, every agent; --provider, --repo, --search, --json
+leg history show claude:0fc5         where it ran, its last messages, whether Leg can continue it
+leg history continue claude:0fc5     leg claude --resume <id> in that folder, supervised like any session
+leg worktrees                        path, repo, branch, exists, uncommitted, owner, conversations, stale
+```
+
+Nothing moves: each agent's store stays where it was, Leg writes only its own
+`~/.leg/history/index.json`, reads transcripts from their head and tail, and
+opens messages only when you open a conversation. A session Leg started and
+the same conversation in the agent's store are one row, marked `leg`; the rest
+are `external`. On a shared board the whole group is the owner's. The support
+matrix (which agents list, show messages, continue) and every file read are in
+[docs/history.md](docs/history.md).
+
 ## Second accounts, and what the terms say
 
 Optional. `leg accounts add claude work` creates
@@ -387,6 +416,10 @@ happens after you run `leg accounts add`; that is your call.
   `~/.codex/config.toml`, agy's files, your repo's settings. Claude Code gets
   hooks through a per-session `--settings` file under `~/.leg`; codex and
   agy get nothing injected.
+- **Read, never written**: each agent's own history (`~/.claude/projects`,
+  `~/.codex/sessions`, `~/.grok/sessions`, `~/.gemini/antigravity-cli`,
+  `~/.copilot/session-state`) for `leg history`; the index it builds lives
+  under `~/.leg/history/`, and no SQLite file is ever opened.
 - **Written only after `leg harness enable`** ([the portable harness](docs/harness.md),
   off by default): the destination client's global rules file
   (`~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.claude/leg-rules.md` plus
@@ -429,6 +462,10 @@ leg sessions show|events <id>
 leg sessions handoff|end <id>        same as the board buttons
 leg sessions rm <id>                 forget an ended session
 leg sessions simulate-limit <id>     the real limit path without a real wall (claude, agy, grok)
+leg history [ls] [--provider p] [--repo r] [--search q] [--managed|--external] [--live] [--all] [--json]
+                                     every conversation on this machine, Leg's own and the agents' own (read only)
+leg history show <id> [--messages n] [--json] | continue <id> [agent args…] | refresh [--full] | providers
+leg worktrees [--repo <path>] [--no-dirty] [--json]   every checkout: git's, Leg's, the conversations' (read only)
 leg accounts ls                      logins and their 5h/7d usage
 leg accounts add <claude|codex|grok> <name> | rm <agent> <name> | terms
 leg harness status|inspect|check|explain|history [--json]   the portable harness, read-only
@@ -534,6 +571,7 @@ More in [docs/faq.md](docs/faq.md).
 | [Board guide](docs/board-guide.md) | every word, number and button on the board explained |
 | [Configuration](docs/configuration.md) | environment variables and options |
 | [Portable harness](docs/harness.md) | carrying rules, hooks, skills, agents, commands and MCP servers to the agent a hand-off lands on: what moves, what does not, policies, ownership, secrets |
+| [History](docs/history.md) | `leg history` and `leg worktrees`: every conversation and checkout on this machine across agents, the support matrix, what is read and what is written |
 | [Adapters](docs/adapters.md) | what each CLI exposes and how Leg attaches to it |
 | [CLI contracts](docs/cli-contracts.md) | exact argv per CLI and the limit-signal table with sources |
 | [FAQ](docs/faq.md) | a question the others did not answer |

package/bin/leg.mjs

@@ -27,6 +27,7 @@ import { home } from '../src/store.mjs'
 import { entitlement, allows, describe as describeLicense, activate as activateLicense, deactivate as deactivateLicense, refresh as refreshLicense, licensePath, BUY_URL } from '../src/license.mjs'
 import { resumeVerdict, bodyOf, ago } from '../src/resume.mjs'
 import { harnessCommand } from '../src/harness/cli.mjs'
+import { historyCommand, worktreesCommand } from '../src/history/cli.mjs'
 
 const SRC = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'src')
 // one source of truth for the version, so the help text cannot drift from the package
@@ -329,6 +330,21 @@ async function main() {
     const code = await harnessCommand(cmd, args, { out, die })
     process.exit(code)
   }
+  if (group === 'history' || group === 'worktrees') {
+    // Every conversation on this machine, Leg's own and the ones the agents'
+    // stores hold: a read-only index (src/history/index.mjs). `continue`
+    // starts a normal supervised leg on one of them. `leg history --json` is
+    // `leg history ls --json`: a leading flag names no verb.
+    const isHelp = cmd === '--help' || cmd === '-h' || cmd === 'help' || args.help || args.h
+    const bare = typeof cmd === 'string' && cmd.startsWith('--')
+    const verb = isHelp ? 'help' : (bare ? 'ls' : cmd)
+    const a = bare ? parseArgs([cmd, ...rest]) : args
+    // `continue <id> [agent args...]`: what follows the id goes to the agent
+    // untouched, the way `leg claude [args...]` passes its argv straight through
+    const raw = bare ? [cmd, ...rest] : rest
+    const code = group === 'history' ? await historyCommand(verb, a, { out, die, raw }) : worktreesCommand(verb, a, { out, die })
+    process.exit(code)
+  }
   if (group === 'license') {
     // The paid gate. Keys verify offline against the public key in
     // src/license.mjs; nothing here talks to the network except refresh.
@@ -454,13 +470,19 @@ async function main() {
     out(openBoard(url) ? `opened ${url}` : `could not open a browser; visit ${url}`)
     return
   }
-  if (group && group !== '--help' && group !== 'help') die(2, `unknown command "${group}" (claude|codex|agy|grok|sessions|resume|accounts|harness|license|share|up|down|status|open|card|scheduler|uninstall)`)
+  if (group && group !== '--help' && group !== 'help') die(2, `unknown command "${group}" (claude|codex|agy|grok|sessions|history|worktrees|resume|accounts|harness|license|share|up|down|status|open|card|scheduler|uninstall)`)
   out(`leg ${VERSION}, your coding agents, with a board alongside and a handoff when one hits its limit
   claude|codex|agy|grok [args...]   the normal interactive agent in this terminal; args pass straight through
                                 the board opens once, the session shows as a card, usage is tracked, a limit hands off
                                 a second live session in one checkout gets its own worktree (--no-worktree to share)
                                 auto-approve mode (--no-auto-approve to opt out)
   sessions ls|show|events|handoff|end|rm|simulate-limit <id>
+  history [ls] [--provider p] [--repo r] [--search q] [--json]
+                                every conversation on this machine: Leg's own, and the ones Claude Code, Codex,
+                                Grok, Antigravity and Copilot keep in their own stores (read only, nothing moved)
+  history show|continue <id> | refresh | providers
+                                one conversation, or start leg <agent> on it where the agent can resume by id
+  worktrees [--repo r] [--json]  every checkout Leg can see: git's, its own, the ones conversations worked in
   resume [--check] [--json] [--path <dir>]      the hand-off waiting in this checkout, and whether it is still true
                                freshness is recomputed from git at read time; --check prints only the verdict
                                exit 0 current, 1 stale or unstamped, 3 no pointer here

package/docs/ERRORS.md

@@ -3,6 +3,86 @@
 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: 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 +475,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/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/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

@@ -391,6 +391,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

@@ -200,6 +200,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
 

package/docs/history.md

@@ -0,0 +1,172 @@
+# History: every conversation on this machine
+
+`leg history` lists the coding-agent conversations on this machine in one
+place: the sessions Leg started itself, and the ones Claude Code, Codex, Grok,
+Antigravity and GitHub Copilot CLI keep in their own stores, whether or not
+Leg was involved. `leg worktrees` does the same for checkouts. The board's
+fourth ledger cell, **Conversations**, is the same index with a search box.
+
+Nothing moves. Claude keeps Claude's history where it always was, Codex
+keeps Codex's, and so on. Leg reads those stores, writes one index file of
+its own, and points back.
+
+## What you get
+
+```
+leg history                          newest first, every agent, 50 rows
+leg history --provider codex,grok    one or more agents
+leg history --repo leg               a repository by name, or by path
+leg history --search "drainer"       title, repo, branch, folder or id
+leg history --managed | --external   only what Leg started, or only what it found
+leg history --live                   only conversations with a process still on them
+leg history --all --json             everything, as JSON
+leg history show <id>                one conversation: where, when, its last messages, whether it can continue
+leg history continue <id>            start leg <agent> on it, in its folder, supervised like any other session
+leg history refresh [--full]         re-stat every store now; --full drops the index and re-reads everything
+leg history providers                the support matrix below, from the code that implements it
+leg worktrees [--repo <path>] [--json] [--no-dirty]
+```
+
+An id is `<provider>:<the agent's own id>`, for example
+`claude:0fc54b51-6cfa-40cf-9823-a5a36d1ca3f3`. A unique prefix of the agent's
+id, four characters or more, is enough: `leg history show 0fc5`. A Leg session
+id (`s-2026…`) works too.
+
+A row says which agent, whether the conversation is **leg** (Leg started it,
+its session id follows) or **external** (found in the agent's store), whether
+it is **live** (a process is still on it, where the agent leaves a marker),
+the repository and branch, when it was last active, and its title.
+
+## Support matrix
+
+Verified against the stores on a real machine on 2026-09-16 (Claude Code
+2.1.273, codex-cli 0.154.0, Grok CLI with `chat_format_version` 1,
+Antigravity 1.2.0, Copilot CLI 1.0.80). Each provider's file header in
+`src/history/providers/` names the exact files and fields it reads.
+
+| provider | list | title | branch | live marker | transcript | continue | store read |
+|---|---|---|---|---|---|---|---|
+| Claude Code | yes | custom title, else the AI title, else the first prompt | yes | `sessions/<pid>.json`, pid checked | yes | `claude --resume <id>` | `~/.claude/projects/*/<id>.jsonl`, `history.jsonl`, `sessions/` |
+| Codex | yes | `session_index.jsonl`, else the first prompt | yes (the `git` block) | no | yes | `codex resume <id>` | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`, `session_index.jsonl`, `history.jsonl` |
+| Grok | yes | `generated_title`, else the summary, else the first prompt | yes | `active_sessions.json` | yes | `grok --resume <id>` | `~/.grok/sessions/<cwd>/<id>/summary.json`, `chat_history.jsonl`, `prompt_history.jsonl` |
+| Antigravity | yes | `annotations/<id>.pbtxt`, else the first prompt | no | no | **no** (SQLite) | `agy --conversation <id>` | `~/.gemini/antigravity-cli/history.jsonl`, `annotations/`, `presence/` |
+| Copilot CLI | yes | the session name | yes | no | yes | **no** | `~/.copilot/session-state/<id>/workspace.yaml`, `events.jsonl` |
+
+Extra logins made with `leg accounts add` are scanned too (their `CLAUDE_CONFIG_DIR`,
+`CODEX_HOME` or `GROK_HOME` directory); a row from one carries the account
+name.
+
+**Continue** is offered only where the installed CLI's own help documents
+resume-by-id, quoted in the provider file. Antigravity keeps its transcripts
+in SQLite, which Leg does not open, so it lists and continues but cannot show
+messages. Copilot is discoverable without being an agent Leg supervises, so it
+lists and shows messages but cannot be continued through Leg; that split (a
+provider Leg can *find* versus an agent Leg can *run*) is deliberate, and the
+registry in `src/history/index.mjs` is separate from `src/adapters/`.
+
+Looked at and left unsupported, each for one reason: Cursor (its chat lives
+in `state.vscdb`, SQLite), opencode (`opencode.db`, SQLite), Pi (documented
+under `~/.pi/agent/sessions/`, not present on the verification machine, the
+cwd encoding undocumented), Hermes, aider and Windsurf (no session store).
+
+## How discovery works
+
+- **One index file.** `$LEG_HOME/history/index.json` holds, per provider, per
+  transcript, the file's size and mtime and a small record: ids, cwd, repo,
+  branch, times, a scrubbed title cut to 200 characters. No message body is
+  ever cached. A refresh stats every file and re-reads only the ones whose
+  size or mtime changed; deleted files drop out.
+- **Bounded reads.** Metadata comes from the first 256 KB and the last 256 KB
+  of a transcript, never the whole file (a busy machine has gigabytes of
+  them). Messages are read only when a conversation is opened, from the last
+  4 MB, and every string is passed through the same redaction as the rest of
+  the board plus the values of the well-known key variables the process holds.
+- **Repository resolution without git.** A cwd is walked up to its `.git`; a
+  `.git` *file* names a linked worktree and its main repository, so a
+  conversation that ran in a worktree groups under the repository it belongs
+  to. When the folder is gone, what the agent itself recorded (Claude's
+  `worktree-state`, Grok's `git_root_dir`) is used instead.
+- **Dedup.** A Leg session records the agent's own id (`agent_session_id`)
+  and transcript path; a discovered record with the same id or path is the
+  same conversation and is shown once, marked managed, with the Leg session id
+  and status. A Leg session whose agent id Leg never learned still lists,
+  under `leg:<session id>`. `leg history continue` seeds the new session with
+  the id up front, so the continued conversation dedups from its first turn.
+- **Hidden by default.** Subagent threads (Codex `source.subagent`, Grok
+  `session_kind: subagent`, Claude sidechains and the `<id>/subagents/`
+  directory) and sessions Claude Code itself hides (`history-suppression`)
+  are left out unless `--subagents` (the API's `hidden=1`) asks for them.
+- **A provider failing is contained.** Each provider scans inside its own
+  try; a throw keeps that provider's last good entries, records the error on
+  its stats line, and the others still index.
+- **The listing refreshes itself** when the index is older than a minute;
+  `leg history refresh` forces it. The CLI refreshes inline; the board hands
+  the refresh to a child `leg history refresh` so its own event loop keeps
+  serving (a scan stats thousands of files and walks every cwd). A refresh
+  that fails or cannot take the index lock keeps the last index, and the
+  listing says so.
+- **A folder on a network share** (`\host\share\...`) is listed as the agent
+  recorded it and never probed: an unreachable host blocks every synchronous
+  file-system call for seconds, so no refresh touches one.
+- **Antigravity's titles and activity marks** live one small file per
+  conversation (`annotations/<id>.pbtxt`, `presence/<id>.lock`). Each is
+  stat'ed on every pass and read again only when its own mtime moved; a
+  retitle rewrites the file in place and does not change the directory, so
+  the directory is no signal.
+
+## Worktrees
+
+`leg worktrees` merges three sources into one list: what `git worktree list`
+says for every repository Leg knows (from its sessions, its cards and the
+discovered conversations), the worktrees Leg's sessions and cards recorded
+(even when git no longer lists them), and the worktrees discovered
+conversations ran in. Each row carries the repository, branch, whether the
+directory exists, how many files are uncommitted (git status, on up to 40
+checkouts per call; `null` past that or when `--no-dirty`), who owns it (the
+checkout itself, a Leg session, a Leg card, or nobody Leg knows), which
+conversations point at it and when the last one was active, **orphaned**
+(a `.leg-worktrees/` directory no session or card records), **stale**
+(exists, no live owner, nothing touched it in 14 days) and **missing** (git
+or a record names it, the directory is gone).
+
+It is a view. Removing a worktree is still `leg sessions rm`, `leg card rm`
+or the board's Remove, which keep their guards.
+
+## Privacy
+
+- The whole `/api/history` and `/api/worktrees` group is the owner's. On a
+  shared board a guest gets 403 from every route in it, the same gate as the
+  pipeline routes; nothing history knows is pushed over SSE.
+- The API takes an id, never a path. The transcript a record names is read
+  only when it sits inside a provider home, an extra account's directory or
+  Leg's own `sessions/`; an index edited by hand to point elsewhere reads
+  nothing.
+- Discovery writes only `$LEG_HOME/history/index.json`, its lock and its
+  temporary sibling, and refuses to write when `LEG_HOME` sits inside a
+  provider's store. No SQLite file is ever opened. Junctions and symlinks
+  under a store are not followed.
+- `leg history continue` validates the id against the provider's own shape
+  (a UUID) before it becomes an argument, and the folder before it becomes
+  the working directory: it must exist, be a directory, and not sit under
+  `LEG_HOME`. The continued session shares its checkout (no worktree is cut):
+  the conversation's files are where it left them.
+
+## Adding a provider
+
+One file in `src/history/providers/`, registered in `src/history/index.mjs`:
+
+- `name`, `label`, `transcript` (`'supported' | 'unsupported'`), `ID_RE`
+- `root(homes)`: the store's directory (from the CLI's own environment variable
+  when it has one; `homes` overrides it in tests)
+- `scan({ home, prev })`: `{ entries, aux, scanned, parsed }` where `entries`
+  maps a stable key (the transcript path) to `{ mtime, size, record }`, reusing
+  `prev.entries[key]` when the file is unchanged; `record` carries
+  `native_id, cwd, branch, title, started_at, updated_at, transcript_path,
+  size_bytes, turns, live, native`
+- `messages(record, limit)`: the last messages from a bounded tail, or `null`
+- `resume(record)`: `{ supported, agent, args }` or `{ supported: false, reason }`,
+  with the CLI's help text quoted beside it
+- optionally `liveIds(home)`
+
+`test/history-fixture.mjs` shows the shapes each existing provider expects;
+a new provider gets a builder there and a row in the matrix above.