@ucsandman/legcli 0.9.0 → 0.11.0

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/limits/grok/grok-balance-exhausted.json

@@ -0,0 +1,11 @@
+{
+  "id": "grok-balance-exhausted",
+  "adapter": "grok",
+  "source": "observed-live",
+  "produced_by": "grok 1.0.34 -p --output-format json on an account with no balance left, 2026-09-17: stdout {\"type\":\"error\",\"message\":\"Internal error: {\n  \\\"message\\\": \\\"API error (status 402 Payment Required): Grok Build usage balance exhausted\\\",\n  \\\"http_status\\\": 402\n}\"}, exit 1",
+  "where": "any",
+  "text": "API error (status 402 Payment Required): Grok Build usage balance exhausted",
+  "pattern": "usage balance exhausted|status 402 Payment Required",
+  "exit_code": null,
+  "classification": "limit"
+}

package/fixtures/live/grok/cmd.txt

@@ -1 +1 @@
-~\.grok\bin\grok.exe -p "Create a file named hello-grok.txt in the current directory containing exactly the word hi. Then create the directory .baton if it is missing and write the file .baton/DONE containing the single line: done. Do nothing else. Do not ask questions.\n" --output-format json --permission-mode acceptEdits
+~\.grok\bin\grok.exe --prompt-file ~\.baton\cards\card-20260917-1748-probe-grok\runs\1\prompt.txt --output-format json --permission-mode acceptEdits --cwd ~\AppData\Local\Temp\claude\C--Projects-leg\9c2d72c5-4654-46ea-a183-81767ec30af5\scratchpad\probe-repo3

package/fixtures/live/grok/parsed.json

@@ -1,5 +1,8 @@
 {
-  "session_id": "01a08de5-c64c-7a31-ac58-1c11c2dd7332",
-  "last_message": null,
-  "stop_reason": null
+  "session_id": null,
+  "last_message": "Internal error: {\n  \"message\": \"API error (status 402 Payment Required): Grok Build usage balance exhausted\",\n  \"http_status\": 402\n}",
+  "stop_reason": "error",
+  "subtype": null,
+  "is_error": true,
+  "num_turns": null
 }

package/fixtures/live/grok/run.json

@@ -1,18 +1,30 @@
 {
-  "card_id": "card-20260911-0036-probe-grok",
+  "card_id": "card-20260917-1748-probe-grok",
   "run": 1,
   "adapter": "grok",
   "mode": "acceptEdits",
   "max_turns": null,
+  "model": null,
   "resume": null,
-  "cwd": "~\\AppData\\Local\\Temp\\claude\\C--Projects\\49952fac-5ff4-486c-8395-9973cebdfdcb\\scratchpad\\toy-probe",
+  "cwd": "~\\AppData\\Local\\Temp\\claude\\C--Projects-leg\\9c2d72c5-4654-46ea-a183-81767ec30af5\\scratchpad\\probe-repo3",
   "status": "exited",
-  "supervisor_pid": 70732,
-  "agent_pid": 12580,
-  "started_at": "2026-09-11T00:36:48.183Z",
-  "outcome": null,
-  "updated_at": "2026-09-11T00:37:45.845Z",
-  "exit_code": 0,
-  "session_id": "01a08de5-c64c-7a31-ac58-1c11c2dd7332",
-  "ended_at": "2026-09-11T00:37:45.380Z"
+  "supervisor_pid": 47116,
+  "agent_pid": 48864,
+  "driver_pid": null,
+  "started_at": "2026-09-17T17:48:07.055Z",
+  "outcome": "limit",
+  "updated_at": "2026-09-17T17:48:18.619Z",
+  "exit_code": 1,
+  "session_id": null,
+  "ended_at": "2026-09-17T17:48:18.538Z",
+  "signal": "grok-balance-exhausted",
+  "handoff": true,
+  "reason": "observed-live limit signal: grok-balance-exhausted",
+  "done_marker": false,
+  "diff": {
+    "changed": true,
+    "files": 1,
+    "head_at_start": "f8d264942a080ca398751d0d481d612f73ef3d62",
+    "head": "f8d264942a080ca398751d0d481d612f73ef3d62"
+  }
 }

package/fixtures/verified.json

@@ -2,7 +2,7 @@
   "_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,
+  "tests": 674,
   "clis": {
     "claude": {
       "label": "Claude Code",
@@ -22,6 +22,13 @@
       "npm": null,
       "probe": "agy --version",
       "note": "Antigravity CLI is a closed Go binary with no npm package, so drift is only visible from a machine that has it installed."
+    },
+    "grok": {
+      "label": "grok",
+      "version": "1.0.34",
+      "npm": null,
+      "probe": "grok --version",
+      "note": "Grok Build ships as a downloaded binary, not an npm package. Probed on 2026-09-17, separately from the 2026-09-11 sweep above: the flags came from grok --help and the headless envelope from the shipped exe, and scripts/probe.mjs reached the account and returned a real 402 wall. The success path of a grok leg is still unprobed for want of balance on the account."
     }
   },
   "surfaces": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ucsandman/legcli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Usage-limit monitor and automatic handoff for Claude Code, Codex, agy and Grok. Type leg claude|codex|agy|grok and get the same interactive agent with a board alongside, auto-approve on by default, usage tracking per agent and account, a live context handoff bundle, and at the limit the next agent continuing in the same terminal. $79 once, 30-day money-back guarantee.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/scripts/build-docs-site.mjs

@@ -65,19 +65,26 @@ const PAGES = [
     title: 'The portable harness: carry rules, hooks, skills and MCP servers between agents',
     description: 'How Leg carries the source agent\'s working environment to the agent a handoff lands on, what moves and what does not, the policies, ownership and backups, and how secrets are handled.',
   },
+  {
+    slug: 'history',
+    nav: 'History',
+    source: 'docs/history.md',
+    title: 'Every conversation on this machine: leg history and leg worktrees',
+    description: 'One read-only index over the conversations Claude Code, Codex, Grok, Antigravity and Copilot CLI keep in their own stores, plus the sessions Leg started itself, and every checkout: the support matrix, what is read, what is written, and how to continue one.',
+  },
   {
     slug: 'cli-contracts',
     nav: 'What it reads',
     source: 'docs/cli-contracts.md',
-    title: 'What Leg reads from Claude Code, Codex and agy',
-    description: 'The exact usage endpoints, hooks, log lines and limit strings Leg reads from Claude Code, Codex and agy, each cited to its source.',
+    title: 'What Leg reads from Claude Code, Codex, agy and Grok',
+    description: 'The exact usage endpoints, hooks, log lines and limit strings Leg reads from Claude Code, Codex, agy and Grok, each cited to its source.',
   },
   {
     slug: 'adapters',
     nav: 'Adapters',
     source: 'docs/adapters.md',
-    title: 'Leg agent adapters for Claude Code, Codex and agy',
-    description: 'How each agent adapter spawns its CLI, what it strips from the environment, and how to tell whether a tap is live or docs-only.',
+    title: 'Leg agent adapters for Claude Code, Codex, agy and Grok',
+    description: 'How each agent adapter spawns its CLI, what it strips from the environment, how to tell whether a tap is live or docs-only, and how to add any other CLI from a JSON spec.',
   },
   {
     slug: 'faq',

package/scripts/probe.mjs

@@ -79,7 +79,8 @@ mkdirSync(out, { recursive: true })
 for (const f of ['out.log', 'err.log', 'run.json', 'supervisor.log', 'last.md']) {
   if (existsSync(join(runDir, f))) writeFileSync(join(out, f), scrubPaths(readFileSync(join(runDir, f), 'utf8')))
 }
-const spec = adapter.argv({ mode, cwd: repo, prompt: PROMPT, runDir, killMs: 5400000 })
+// the same opts the runner passed, so cmd.txt is the command that really ran
+const spec = adapter.argv({ mode, cwd: repo, prompt: PROMPT, promptFile: join(runDir, 'prompt.txt'), runDir, killMs: 5400000 })
 writeFileSync(join(out, 'cmd.txt'), scrubPaths([spec.bin, ...spec.args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')) + '\n')
 const textOf = (f) => (existsSync(join(runDir, f)) ? readFileSync(join(runDir, f), 'utf8') : '')
 const authSource = /another auth source/i.test(textOf('err.log') + textOf('out.log'))

package/src/accounts.mjs

@@ -43,12 +43,15 @@ export const LAYOUT = {
 export function accountsFile() { return join(home(), 'accounts.json') }
 export function accountDir(agent, name) { return join(home(), 'accounts', agent, name) }
 
+const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,29}$/i
+
 export function readAccounts() {
   const base = { claude: ['default'], codex: ['default'], agy: ['default'], grok: ['default'] }
   if (!existsSync(accountsFile())) return base
   try {
     const j = JSON.parse(readFileSync(accountsFile(), 'utf8'))
-    for (const k of Object.keys(base)) if (Array.isArray(j[k])) base[k] = ['default', ...j[k].filter((n) => n !== 'default')]
+    // the same shape addAccount accepts: a name is a directory segment, never a path
+    for (const k of Object.keys(base)) if (Array.isArray(j[k])) base[k] = ['default', ...j[k].filter((n) => typeof n === 'string' && n !== 'default' && NAME_RE.test(n))]
   } catch {}
   return base
 }
@@ -74,7 +77,7 @@ function junction(target, link) {
 
 // Create the account dir, junction the shared harness in, copy the settings.
 export function addAccount(agent, name) {
-  if (!/^[a-z0-9][a-z0-9_-]{0,29}$/i.test(name) || name === 'default') throw new Error(`invalid account name "${name}" (letters, digits, - and _; not "default")`)
+  if (!NAME_RE.test(name) || name === 'default') throw new Error(`invalid account name "${name}" (letters, digits, - and _; not "default")`)
   const l = LAYOUT[agent]
   if (!l) throw new Error(`unknown agent "${agent}" (claude|codex|agy|grok)`)
   if (!l.env) throw new Error(`${agent} has no config-dir override in the installed version; extra accounts are not possible`)

package/src/adapters/cli.mjs

@@ -0,0 +1,130 @@
+// `leg adapter …` — the custom-adapter surface. A spec is a JSON file in
+// $LEG_HOME/adapters/<name>.json; these verbs write, validate and explain it
+// so a bad spec is caught here rather than when a card tries to spawn.
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { writeJsonAtomic } from '../fsx.mjs'
+import { BUILTIN_NAMES, customSpecs, get as getAdapter } from './index.mjs'
+import { adaptersDir, specPath, validateSpec, makeAdapter, SpecError, TEMPLATE, PLACEHOLDERS } from './custom.mjs'
+
+const USAGE = `usage:
+  leg adapter list                       every adapter this machine has, built-in and custom
+  leg adapter show <name>                the spec, as JSON
+  leg adapter check <name>               validate it and print the command line a leg would run
+  leg adapter add <file.json> [--name n] validate a spec and install it
+  leg adapter rm <name>                  remove a custom spec
+  leg adapter template [--name n]        print a starter spec to fill in`
+
+function quote(a) { return /\s/.test(a) ? JSON.stringify(a) : a }
+
+export async function adapterCommand(verb, args, { out, die }) {
+  const first = args._?.[0]
+
+  if (!verb || verb === 'help' || verb === '--help') { out(USAGE); return 0 }
+
+  if (verb === 'list') {
+    const specs = customSpecs()
+    if (args.json) {
+      out(JSON.stringify({
+        builtin: BUILTIN_NAMES,
+        custom: specs.map((s) => ({ name: s.name, file: s.file, ok: Boolean(s.adapter), error: s.error, bin: s.spec?.bin ?? null })),
+      }, null, 2))
+      return specs.some((s) => s.error) ? 1 : 0
+    }
+    out('built-in:')
+    for (const n of BUILTIN_NAMES) out(`  ${n}`)
+    out(`custom (${adaptersDir()}):`)
+    if (!specs.length) out('  none yet — leg adapter template > my-agent.json, then leg adapter add my-agent.json')
+    for (const s of specs) {
+      out(s.adapter ? `  ${s.name.padEnd(20)} ${s.spec.bin}` : `  ${s.name.padEnd(20)} BROKEN: ${s.error}`)
+    }
+    return specs.some((s) => s.error) ? 1 : 0
+  }
+
+  if (verb === 'template') {
+    const spec = { ...TEMPLATE }
+    // the common case is that the command is called what the adapter is called
+    if (typeof args.name === 'string') { spec.name = args.name; spec.bin = args.name }
+    out(JSON.stringify(spec, null, 2))
+    return 0
+  }
+
+  if (verb === 'show') {
+    if (!first) return die(2, 'usage: leg adapter show <name>')
+    const hit = customSpecs().find((s) => s.name === first)
+    if (!hit) {
+      if (BUILTIN_NAMES.includes(first)) return die(2, `${first} is a built-in adapter, not a spec on disk (src/adapters/${first}.mjs)`)
+      return die(3, `no custom adapter called "${first}" in ${adaptersDir()}`)
+    }
+    if (hit.error) return die(1, `${first}: ${hit.error}`)
+    out(JSON.stringify(hit.spec, null, 2))
+    return 0
+  }
+
+  if (verb === 'check') {
+    if (!first) return die(2, 'usage: leg adapter check <name>')
+    let adapter
+    try { adapter = await getAdapter(first) } catch (err) { return die(3, err.message) }
+    const cwd = typeof args.cwd === 'string' ? args.cwd : process.cwd()
+    let spec
+    try {
+      spec = adapter.argv({
+        prompt: 'THE TASK PROMPT',
+        promptFile: typeof args['prompt-file'] === 'string' ? args['prompt-file'] : null,
+        cwd,
+        mode: typeof args.mode === 'string' ? args.mode : undefined,
+        model: typeof args.model === 'string' ? args.model : null,
+        runDir: null,
+        killMs: 5400000,
+      })
+    } catch (err) { return die(1, `${first}: ${err.message}`) }
+    out(`${first}: ${adapter.custom ? 'custom spec' : 'built in'}`)
+    out(`  stdin        ${adapter.stdin}`)
+    out(`  modes        ${adapter.modes.allowed.join(', ')} (default ${adapter.modes.default})`)
+    out(`  would run    ${[spec.bin, ...spec.args].map(quote).join(' ')}`)
+    // A spec that names a binary nothing can find spawns once and fails once;
+    // saying so here is the difference between a typo and a mystery.
+    const bin = spec.bin
+    const found = existsSync(bin) || !/[\\/]/.test(bin)
+    out(`  binary       ${bin}${existsSync(bin) ? ' (found)' : found ? ' (looked up on PATH at spawn time)' : ' — NOT FOUND at that path'}`)
+    return existsSync(bin) || found ? 0 : 1
+  }
+
+  if (verb === 'add') {
+    if (!first) return die(2, 'usage: leg adapter add <file.json> [--name <name>]')
+    const file = resolve(first)
+    if (!existsSync(file)) return die(2, `no such file: ${file}`)
+    let raw
+    try { raw = JSON.parse(readFileSync(file, 'utf8')) } catch (err) { return die(2, `${file} is not JSON: ${err.message}`) }
+    if (raw && typeof raw === 'object' && typeof args.name === 'string') raw.name = args.name
+    let spec
+    try { spec = validateSpec(raw, { reserved: BUILTIN_NAMES }) } catch (err) {
+      if (err instanceof SpecError) return die(2, err.message)
+      throw err
+    }
+    const dest = specPath(spec.name)
+    const replacing = existsSync(dest)
+    mkdirSync(adaptersDir(), { recursive: true })
+    writeJsonAtomic(dest, spec)
+    const adapter = makeAdapter(spec)
+    // the runner always writes a prompt file, so the preview shows one too
+    const line = adapter.argv({ prompt: 'THE TASK PROMPT', promptFile: '<run>/prompt.txt', cwd: process.cwd() })
+    out(`${replacing ? 'replaced' : 'added'} ${spec.name} → ${dest}`)
+    out(`  would run  ${[line.bin, ...line.args].map(quote).join(' ')}`)
+    out(`  use it     leg card add --repo <path> --task "<t>" --chain ${spec.name},claude --queue`)
+    return 0
+  }
+
+  if (verb === 'rm' || verb === 'remove') {
+    if (!first) return die(2, 'usage: leg adapter rm <name>')
+    if (BUILTIN_NAMES.includes(first)) return die(2, `${first} is built in; there is no spec file to remove`)
+    const dest = specPath(first)
+    if (!existsSync(dest)) return die(3, `no custom adapter called "${first}" in ${adaptersDir()}`)
+    rmSync(dest, { force: true })
+    out(`removed ${first} (${dest})`)
+    out('cards that already name it keep their chain; they will fail to launch until it is added again')
+    return 0
+  }
+
+  return die(2, `unknown: leg adapter ${verb}\n\n${USAGE}\n\nplaceholders: ${PLACEHOLDERS.map((p) => `{{${p}}}`).join(' ')}`)
+}