@ucsandman/legcli 0.8.0 → 0.10.0

package/docs/harness.md

@@ -0,0 +1,319 @@
+# The portable harness
+
+Off by default. When you turn it on, a hand-off carries two things instead of
+one: the task (the context handoff bundle Leg has always written) and the
+agent's **working environment**: the global working agreement, identity,
+hooks, skills, subagents, slash commands, MCP servers and permissions of the
+client you actually use, rendered into the native configuration of the client
+the hand-off lands on. The promise is not byte-for-byte equivalence. It is:
+
+> Preserve as much of the source agent's operating environment as the
+> destination client can faithfully support, and say exactly what could not be
+> carried over.
+
+```
+leg harness enable        # detect clients, capture, show the plan, apply after you say yes
+leg harness status        # what is on, the source, when it was captured, each client's state
+leg harness sync          # re-capture and write whatever is out of date
+leg harness check         # the same, writing nothing; exit 1 when something is stale
+leg harness explain       # every item a client could not receive, and why
+leg harness disable       # stop; nothing already written is removed
+```
+
+## What moves, and what does not
+
+| component | carried as | what a destination may drop |
+|---|---|---|
+| rules | the source's global rules file with its `@imports` inlined, written as the destination's global rules file (`AGENTS.md`, `GEMINI.md`, or `leg-rules.md` imported from `CLAUDE.md`) | nothing; the whole agreement travels |
+| identity | `SOUL.md` or the identity section, inlined or written to the client's own file | nothing |
+| hooks | the same hook scripts, pointed at (never copied), in the destination's dialect; non-Codex clients run them through a shim that translates the payload | an event the client does not have (`MessageDisplay`, agy's missing `SessionStart`), a matcher whose tools have no counterpart |
+| skills | a directory link per skill into the client's skills directory, so an edit at the source is live everywhere | a name that already exists as a real directory there, a skill the client reads natively from a shared directory |
+| agents | one subagent file per agent in the client's format (`.md` or `.toml`), with the model tier mapped through the client's ladder | a client with no subagent surface (Gemini CLI) |
+| commands | one prompt file per slash command (`prompts/`, `commands/`, `.toml` for Gemini) | a name that already exists and Leg did not write |
+| MCP servers | each server in the client's own MCP file or config table, with every credential replaced by an environment reference | a transport the client lacks (Codex has no SSE), a server the user already configured there |
+| permissions | `settings.json` allow/deny/ask for Claude Code; Codex prefix rules for `Bash(...)` patterns | anything but a `Bash(...)` pattern on Codex; clients with no machine-readable permission surface |
+
+What never moves:
+
+- **Credentials.** OAuth tokens, `.credentials.json`, `auth.json`, API keys in an
+  MCP `env` or `headers` block, and a token anywhere else the capture reads.
+  An `env` or `headers` value that looks like a credential becomes `${NAME}`
+  in the bundle and Leg tells you which variable to export for each client.
+  A token inside free text (the rules, the identity, an agent or command
+  body) is replaced by `[REDACTED]`; a hook whose command line carries one,
+  and an MCP server whose argument or URL carries one (a password in a
+  connection string, a secret query value, a token in the path), are not
+  carried at all, each with a warning naming it. The scan is fail-closed:
+  every field of the bundle is validated at save time and a bundle that
+  still carries a credential is refused. Tests plant tokens in every one of
+  those places, and in the places a capture must not read, and assert they
+  appear in no bundle file and no destination file.
+- **Which login runs.** Accounts are Leg's account layer
+  (`leg accounts`, `src/accounts.mjs`); the harness describes behaviour and
+  capabilities, never who is signed in. A same-agent hand-off to a second
+  login carries no harness at all: the second login shares the first one's
+  home through the junctions the account layer made.
+- **Project-local instructions.** A repository's `CLAUDE.md`, `AGENTS.md` or
+  `GEMINI.md` is read natively by each client from the checkout. The harness
+  carries the *global* working agreement only.
+- **The source client itself.** The client the harness is captured from is
+  never written to.
+
+## Precedence
+
+When a destination starts after a hand-off, four layers of instruction are in
+play. From most to least specific:
+
+1. **The resume prompt and bundle** (`.leg/RESUME-<session>.md`): the task,
+   the last messages, the diff, why the previous agent stopped. Always
+   present, harness or not.
+2. **The repository's own instruction files**: `CLAUDE.md`, `AGENTS.md`,
+   `GEMINI.md` in the checkout. Never touched by Leg; each client reads them
+   itself.
+3. **The ported global working agreement**: the destination's global rules
+   file, written by the harness. This is where the source's `~/.claude/CLAUDE.md`
+   (with its imports) lands.
+4. The client's own defaults.
+
+Leg does not merge layers 2 and 3. A repository file that repeats a global rule
+repeats it; a repository file that contradicts one wins, because that is how
+every client already resolves project-level instructions over global ones.
+`test/harness-policy.test.mjs` runs a sync from inside a checkout that has its
+own `CLAUDE.md` and `AGENTS.md` and asserts both are byte-identical afterwards:
+a sync writes under the client homes only.
+
+## Turning it on: the first run
+
+`leg harness enable` is the one explicit consent. It:
+
+1. Detects which sources exist on this machine (`~/.claude/CLAUDE.md`,
+   `~/.codex/AGENTS.md`) and picks the first, or the one you name with
+   `--source`. It never guesses destructively: with two sources it says which
+   it chose and how to choose the other.
+2. Captures the source into the neutral bundle under `~/.leg/harness/bundle/`,
+   scans it for credentials, and prints every warning.
+3. Runs a check against every installed client and prints the table: per
+   client, per component, `✓ synced`, `✗ stale`, `- unsupported`, and the
+   count carried (`skills 2/3`), then every item that will not be carried with
+   its reason.
+4. Asks before writing. In a terminal it prompts; without one (a script, CI)
+   it prints the plan, writes nothing, and exits 3 unless you passed `--yes`.
+5. Applies, records ownership of every file and region it wrote, and saves the
+   consent: `preferences.json` gains `"harness": { "enabled": true, "policy":
+   "sync", "source": "claude" }`.
+
+After that, unattended hand-offs use the saved policy and never prompt.
+`leg harness sync` writes only on an install that gave this consent; before
+`enable` it exits 3 and points at it, while `check`, `diff` and `explain`
+report without writing. The board can turn the feature off or narrow the
+policy, never turn it on or widen it: that stays a terminal command.
+
+## Policies
+
+`leg harness policy <warn|sync|strict>`, or `--policy` on `enable`. The
+default when you enable is `sync`; an install that never enabled the feature
+is `off` and behaves exactly as before.
+
+| policy | at a hand-off, before the next agent starts |
+|---|---|
+| `off` | nothing is captured, checked, written or recorded |
+| `warn` | the source is re-captured if it changed, the destination is checked, the result is recorded on the session and printed; nothing is written to any client |
+| `sync` | as `warn`, and a stale destination is synced: managed files and regions are written, backups taken, hand-edited files skipped and reported. The hand-off proceeds whatever the outcome. |
+| `strict` | as `sync`, and a destination that ends `attention`, `error` or `unsupported` is refused: Leg records `harness_blocked`, prints why, tries the next option in your hand-off order, and if none is left stops the terminal with exit 5 rather than launching an agent without its environment. Strict applies to hand-offs only; the agent you start yourself is never refused. |
+
+There is no interactive prompt on this path under any policy. A limit usually
+lands when nobody is at the keyboard, and a prompt would wedge the terminal
+until morning.
+
+## States
+
+One word per destination, the same word on the CLI, the session timeline, the
+terminal card and the drawer:
+
+| state | meaning |
+|---|---|
+| `synced` | everything the destination supports is current and nothing was dropped |
+| `partial` | current, but some items could not be carried (each has a reason under **Dropped**) |
+| `stale` | the destination is behind the source; `warn` policy, or a `check` |
+| `attention` | a managed file was hand-edited since Leg wrote it (backed up, left alone), a component errored (a malformed config file, for instance), or a `deny` or `ask` permission the destination cannot express was dropped, leaving it less restricted than the source; needs you |
+| `unsupported` | the destination has no harness adapter (Grok) or is not installed |
+| `blocked` | the strict policy refused this destination |
+| `source` | the destination is the source client; nothing to carry |
+| `same-client` | a hand-off to another login of the same client; the harness is shared already |
+| `error` | the preparation itself failed; the reason is recorded |
+
+## Ownership, backups, hand edits
+
+Every file the harness writes carries `GENERATED by Leg harness` in its first
+lines. Inside a file you also own (`config.toml`, `settings.json`,
+`.claude.json`, agy's `hooks.json`) it writes a marked region:
+
+```
+# >>> leg harness hooks start (generated, do not edit)
+...
+# <<< leg harness hooks end
+```
+
+or, for JSON, exactly the groups or keys it inserted last time, recorded in
+`~/.leg/harness/harness-state.json`. Everything outside is preserved byte for
+byte; a re-run only ever removes what the harness itself added; a skill link is
+never made over a real directory; a file Leg did not create is never
+overwritten. Before any overwrite the previous content goes to
+`~/.leg/harness/backups/<client>-<file>-<timestamp>.bak`. A generated file
+that is pruned because its source went away (a subagent or command deleted at
+the source, a permissions file that became empty) is backed up the same way
+before it is removed.
+
+A file you edit by hand after Leg wrote it (the ownership line removed, or
+the content changed) is detected by hash, backed up once, and **skipped**. The
+sync reports `attention` with the path and the remedy: edit the source client
+instead, or `leg harness sync --force` to replace it (the backup stays).
+
+## Performance
+
+A hand-off must stay fast. Before capturing, Leg fingerprints the source's
+surfaces from file metadata alone (the rules file and its imports,
+`settings.json`, the MCP file, the agents, commands and skills directories):
+a few dozen `stat` calls. An unchanged fingerprint reuses the bundle on disk.
+The destination is then checked by reading its managed files, and written
+only when something differs. `test/harness-perf.test.mjs` holds a warm
+hand-off decision (unchanged source, synced destination) under 400 ms median
+and a cached capture under 40 ms; on the development machine they measure
+about 19 ms and 7 ms.
+
+## Failure model
+
+| failure | what happens |
+|---|---|
+| no source configured or detected | `error`; hand-off proceeds under `warn`/`sync`, refused under `strict`; `leg harness source` names one |
+| destination not installed | `unsupported`; the chooser never picks a missing CLI anyway |
+| destination config is not valid JSON/TOML | that component is `error`, nothing is written to that file, the hand-off proceeds under `warn`/`sync` |
+| a managed file was hand-edited | `attention`; backed up, skipped, named |
+| a skill name is a real directory at the destination | dropped with a reason; the directory is untouched |
+| an MCP value references a variable the destination does not expand | the component note names the variable to export |
+| a hook event or matcher the destination lacks | dropped with a reason |
+| a `deny` or `ask` permission the destination cannot express | `attention`: the destination would be less restricted than the source; strict refuses it, sync proceeds and names it |
+| a credential in the rules, an agent, a command, a hook command line, an MCP argument or URL | free text is redacted to `[REDACTED]`; the hook or server is not carried; each with a warning |
+| a subagent, command or skill with an unsafe name | not carried, with a warning; the rest of the bundle still travels |
+| a skill path with a shell metacharacter on Windows when the junction fallback is needed | the link is refused and reported; nothing is passed to a shell |
+| two Leg processes hand off at once | one takes `~/.leg/harness/.lock` (up to 30 s); the other fails its own step rather than tearing the ownership record |
+| a model tier the destination cannot map | passed through as a raw id and noted |
+| the captured bundle is corrupt on disk | re-captured from the source, never trusted |
+| an interrupted previous apply | the next sync re-derives everything from ownership records; a region is rebuilt, never appended twice |
+| the engine itself throws | `error` on the session; the session is never corrupted; the hand-off proceeds under `warn`/`sync` |
+
+Nothing here rolls back a user file: every overwrite is preceded by a backup,
+and a refusal leaves the file as it was.
+
+## Observability
+
+Every operation leaves evidence:
+
+- `~/.leg/harness/history.jsonl`: one line per capture, apply and hand-off
+  decision, with the source, target, bundle fingerprint, timestamps,
+  per-component states, dropped items, attention items, the files touched and
+  the backups made. `leg harness history` prints it.
+- The session record (`session.json` → `harness`) carries the outcome for the
+  leg now running: source, fingerprint, capture and sync times, components,
+  dropped, attention, whether the hand-off proceeded.
+- Session events `harness` and `harness_blocked`; card ledger events of the
+  same names on the background-task path.
+- The board: a chip on the terminal row (`harness synced`, `harness partial`,
+  `harness attention`, `harness refused`) and a **Harness** section in the
+  drawer with the source, capture and sync times, the component table,
+  **Needs you**, **Dropped**, and the last eight trail entries.
+
+No secret is ever logged: the bundle holds references, the trail holds paths
+and states.
+
+## Files
+
+```
+~/.leg/harness/
+  bundle/               the neutral bundle: manifest.json, rules.md, identity.md,
+                        hooks.json, mcp.json, skills.json, permissions.json, agents/, commands/
+  capture.json          source, fingerprint, the surfaces hash the capture was taken at
+  harness-state.json    ownership: every file and region written, per client
+  harness-report.json   the last apply or check, per client, per component
+  backups/              every file before Leg overwrote it
+  history.jsonl         the evidence trail
+  policy.json           optional: what is deliberately not carried (below)
+```
+
+`leg uninstall --yes` removes `~/.leg` and with it all of the above. It does
+not remove what the harness wrote into other clients: run `leg harness
+disable`, then delete the files carrying `GENERATED by Leg harness` and the
+`leg harness` regions if you want them gone.
+
+## The port policy
+
+`~/.leg/harness/policy.json`, optional, merged over the defaults:
+
+```jsonc
+{
+  "rules":  { "dropSectionsForTargets": ["Delegation and Model Routing"] },
+  "hooks":  { "exclude": [{ "match": "capability-graph-guard", "reason": "polices Claude Code's model ladder" }] },
+  "skills": { "exclude": { "review-browser": "the destination has no browser tool" } },
+  "mcp":    { "exclude": { "xapi": "one OAuth grant per client; copy nothing" } },
+  "agents": { "modelLadder": { "codex": { "opus": ["gpt-5.6-sol", "high"] } } }
+}
+```
+
+An excluded item shows in `explain` and on the board as **excluded by policy**
+with your reason, and does not make a destination `partial`. The defaults
+exclude nothing; the shipped Codex model ladder maps the four Claude tiers
+(`fable`, `opus`, `sonnet`, `haiku`) onto Codex models and can be overridden.
+
+## Which clients
+
+| client | source | destination | notes |
+|---|---|---|---|
+| Claude Code | yes | yes | the bundle's own dialect; hooks and matchers need no translation |
+| Codex CLI | yes | yes | hooks pre-trusted with Codex's own trust hash (self-tested against a value Codex wrote); SSE servers dropped |
+| Antigravity CLI (`agy`) | no | yes | hooks under one owned key in `hooks.json`; shares `GEMINI.md` with Gemini CLI; no permission surface |
+| Gemini CLI | no | yes | kept coherent with agy; no subagent surface |
+| Grok CLI | no | no | no adapter yet; reported `unsupported`, never guessed |
+
+Paths honour `CLAUDE_CONFIG_DIR`, `CODEX_HOME` and `GEMINI_CONFIG_DIR`, the
+same variables the trust and account layers honour.
+
+## Leg and Agnostic AI
+
+The capture → neutral bundle → apply engine is the
+[Agnostic AI](https://github.com/ucsandman/Agnostic-AI) port engine (MIT).
+Leg embeds it as a library, byte for byte, under
+`src/harness/vendor/agnostic-ai/`, and owns everything around it: consent,
+policy, the client registry, where state lives, the fingerprint, the evidence
+trail and the hand-off decision (`src/harness/*.mjs`).
+
+Drift between the two is refused, not managed:
+
+- `src/harness/vendor/agnostic-ai/UPSTREAM.json` records the upstream commit
+  and the sha256 of every vendored file. `npm test` runs
+  `scripts/sync-harness-engine.mjs --check`, which fails on any local edit
+  under `vendor/`.
+- A fix to the engine lands upstream first, then
+  `node scripts/sync-harness-engine.mjs <path-to-agnostic-ai>` copies it in
+  and re-records the hashes. `--diff <path>` lists what a sync would change.
+- Upstream exposes the library through `engine/harness/index.cjs` with
+  everything a host may own as an option (`configure({ brand, secretPatterns,
+  shimPath, importRoots })`, an injected registry and policy), and its own
+  regression suite proves that boundary. Node's ESM loader imports that
+  CommonJS entry directly, so there is no build step and no dependency.
+
+Attribution is in `NOTICE`; the vendored copy keeps its MIT licence text and
+is not relicensed.
+
+## Limits
+
+- Grok has no adapter.
+- Cursor, Windsurf and the other clients upstream supports are not in Leg's
+  registry, because Leg does not launch them.
+- The Claude Code target imports the ported rules from `~/.claude/CLAUDE.md`
+  with one `@` line; a source that is itself Codex therefore lands as
+  `~/.claude/leg-rules.md`, not inline.
+- A repository-level harness (project skills, project MCP) is not carried;
+  only the global one is.
+- Persistent configuration is the only mechanism: none of the four clients
+  offers a per-session overlay for rules, hooks, skills and MCP together, so
+  the managed-region and ownership discipline above is what keeps writes safe.

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.

package/docs/runtime-tap.md

@@ -0,0 +1,156 @@
+# Runtime tap: turn boundaries, usage and a safe place to hand off
+
+`src/taps/mod.mjs` is Leg's seam for an agent runtime that publishes structured
+events about itself while it runs. It is optional, it is off until one line
+wires it in, and nothing in Leg depends on it existing.
+
+## The gap it closes
+
+Leg's per-agent taps read whatever each CLI leaves behind: an OAuth usage
+endpoint every 60 s, a rollout file, a transcript tail. None of those says when
+a turn ends. So when a limit lands, `killTree()` fires at an arbitrary instant:
+mid-tool, mid-answer, with a subagent still running. The handoff bundle then
+describes a moment nobody chose.
+
+A runtime that publishes events closes that gap. The tap folds the stream into
+one small record of signals, and the one Leg never had is `cleanBoundary`: the
+turn is closed, no tool call is in flight, no subagent is still running.
+
+| Field | What Leg gains |
+| --- | --- |
+| `turnOpen`, `lastTurnCompletedAt` | where a turn starts and ends, to the millisecond |
+| `inFlightTools` | tool calls requested with no completion yet |
+| `subagentsLive` | subagents still running under this session |
+| `cleanBoundary` | all three at rest: a handoff here loses no work and no answer |
+| `usage.contextPercent`, `contextTokens`, `contextWindow` | how full the window is, which degrades an agent long before a rate limit stops it |
+| `usage.fiveHourPercent`, `sevenDayPercent` (+ their reset times) | the same two windows Leg already stores, without the 60 s poll |
+| `usage.costUsd` | what the session has spent |
+| `model`, `lastError` | which model is answering, and the last tool failure or denial |
+
+## Why the runtime side stays optional
+
+The events come from a plugin installed in the agent's own harness, not from
+anything Leg installs or launches. Leg's launcher needs no new flag, no
+`--plugin-dir`, and no change to any adapter's argv: the plugin is already
+installed, or it is not.
+
+`findEventsFile()` returns `null` when the session has no events file, and that
+is the ordinary case, never an error:
+
+- the runtime has no such plugin installed
+- the plugin is installed but this session has not flushed yet
+- the agent is not the one that writes these events at all (codex, agy, grok)
+
+In every one of those cases the tap does nothing, calls back never, and Leg
+behaves exactly as it does today. That is the acceptance condition for this
+seam: with the events file absent, no Leg behaviour changes.
+
+## Where the events come from
+
+One file per runtime session, JSON per line, appended and flushed on a timer
+and at the end of every main-loop turn:
+
+```
+<config dir>/mods/state/events/<sessionId>.jsonl
+```
+
+`<sessionId>` is the runtime's own session id, which Leg stores as
+`agent_session_id` once its transcript names it (not Leg's `sid`).
+`<config dir>` is the config directory that session ran under, which for Leg is
+`spec.env.CLAUDE_CONFIG_DIR` (each account gets its own). `eventsDirFor()`
+builds that path; `LEG_RUNTIME_EVENTS_DIR` overrides it outright, which is what
+the tests use.
+
+The runtime's own event names live in exactly one place in Leg: the `KIND`
+table at the top of `src/taps/mod.mjs`. `deriveSignals()` and `toLegEvents()`
+read that table, and every shape the tap exports is Leg's own, so a second
+runtime with a different vocabulary is a second table and nothing else.
+
+## Wiring it in (one line)
+
+Two lines total, both in `src/attach.mjs`, neither of which changes any
+existing behaviour.
+
+The import, with the other tap imports (after the `./taps/claude-usage.mjs`
+line):
+
+```js
+import { pollRuntimeTap, eventsDirFor } from './taps/mod.mjs'
+```
+
+The wiring itself, inside `if (agent === 'claude') {`, on the line straight
+after `usageTimer.unref?.()`:
+
+```js
+const runtimeStop = pollRuntimeTap({ sessionId: () => readSession(sid)?.agent_session_id, dir: eventsDirFor(spec.env.CLAUDE_CONFIG_DIR || LAYOUT.claude.home()), onSignals: (signals, { legEvents, advice }) => { for (const ev of legEvents) appendEvent(sid, ev); updateSession(sid, { runtime: { ...signals, advice } }) } })
+```
+
+`readSession`, `updateSession`, `appendEvent` and `LAYOUT` are already imported
+there. `sessionId` is a getter on purpose: neither the id nor the file exists
+when a leg starts, so the tap keeps looking until both do and the caller needs
+no lazy bookkeeping in the poll loop.
+
+Teardown is optional. The interval is `unref`'d, so it never holds the process
+open, and a finished session's file simply stops growing (one `stat` every
+2 s until the leg exits). To stop it exactly, declare `let runtimeStop = null`
+beside `let usageTimer = null`, drop the `const` above, and add
+`runtimeStop?.()` next to `if (usageTimer) clearInterval(usageTimer)`.
+
+What the line buys, immediately: turn-level board events (`turn_done`, the
+prompt, subagents, tool failures) instead of a poll-shaped guess, and a
+`session.runtime` record the board can render.
+
+Two follow-ups this seam makes possible, both deliberately not wired here:
+
+- feed the percentages to the chooser through the door every other tap uses:
+  `recordUsage('claude', account, toLegUsage(signals), 'runtime events')`
+  (`recordUsage` is already imported in `attach.mjs`)
+- hand off at a boundary Leg chose, by acting on `advice.shouldHandoff` in the
+  same place the limit handoff already fires
+
+## Handing off on purpose
+
+`handoffAdvice(signals, thresholds)` answers with `{ shouldHandoff, reason }`.
+Defaults:
+
+| Threshold | Default | Why |
+| --- | --- | --- |
+| `contextPercent` | 80 | a full window degrades an agent long before a limit stops it |
+| `fiveHourPercent` | 90 | just under the wall Leg already hands off at |
+| `sevenDayPercent` | 95 | a last resort; the 7-day window rarely moves first |
+
+Being over a threshold is not enough. Over a threshold but mid-turn returns
+`shouldHandoff: false` with a reason that says what it is waiting for
+("context at 84% of the window, waiting for a clean boundary (a turn is
+open)"), so the board can show the wait rather than a silent stall. A
+percentage the runtime has not published yet never triggers a handoff.
+
+## The API
+
+| Function | Answers |
+| --- | --- |
+| `findEventsFile(sessionId, { dir })` | the path, or `null` when this session publishes nothing |
+| `readRuntimeEvents(path, cursor)` | `{ events, cursor }` from a byte offset; a half-written last line is left for the next read, a truncated file restarts at 0, a corrupt line is skipped |
+| `deriveSignals(events, prev)` | the signals record above; pure, and folding in batches equals folding at once |
+| `toLegEvents(events)` | `{ type, summary }` board events, as `appendEvent(sid, ev)` takes them |
+| `toLegUsage(signals)` | `{ five_hour: { pct, resets_at }, seven_day: ... }`, the window shape `recordUsage()` already stores |
+| `handoffAdvice(signals, thresholds)` | `{ shouldHandoff, reason }` |
+| `pollRuntimeTap({ sessionId, dir, intervalMs, thresholds, onSignals })` | the whole tap on a timer; returns `stop()` |
+
+`emptySignals()` is the zero state, and it is what `deriveSignals([])` returns:
+nothing seen, nothing in flight, every percentage `null`.
+
+## Tests
+
+`test/taps-mod.test.mjs`, 11 tests, run by `node --test`. The fixture
+`fixtures/runtime-events.jsonl` is one real captured session (29 events, one
+turn, four tool calls, the usage frame last) with the local user name scrubbed
+out of the paths and nothing else changed. Subagent, denial and error cases are
+built in the test, because that capture has none.
+
+Covered: incremental reads across a torn line, truncation and a corrupt line;
+`cleanBoundary` shut by an open turn and by a tool with no completion, and
+released by the turn that closes; a live subagent, a denied one, and a tool
+call inside a subagent's own loop; usage extraction and its mapping to Leg's
+window shape; advice at 80% context only at a clean boundary; and the no-file
+fallback, where every entry point answers and nothing throws.

package/fixtures/verified.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "The single source of truth for every dated, numbered claim Baton makes in public. scripts/check-claims.mjs asserts that each surface listed here states exactly these values, and --strict additionally compares the pinned CLI versions against what those CLIs currently publish. Re-verify on a real machine, then edit this file and every surface in the same commit.",
+  "_comment": "The single source of truth for every dated, numbered claim Leg makes in public. scripts/check-claims.mjs asserts that each surface listed here states exactly these values, and --strict additionally compares the pinned CLI versions against what those CLIs currently publish. Re-verify on a real machine, then edit this file and every surface in the same commit.",
   "verifiedOn": "2026-09-11",
   "verifiedOnLong": "11 September 2026",
   "tests": 473,