@ucsandman/legcli 0.7.0

package/docs/ROADMAP-v2.md

@@ -0,0 +1,55 @@
+# Roadmap v2: the software factory
+
+**0.3.0 (2026-09-11) shipped item 1 and the first half of continuous landing.**
+A second live session in one checkout gets its own worktree and branch, and
+**Land** on its card sends that branch through the merge queue (rebase, tests,
+fast-forward, or a bounce with the reason), with the landed-on-trunk list
+naming the terminal that landed each commit. `leg share` puts more than one
+human on the board, off by default: a token and a name per human, per-human
+actor ids on every event, another human's terminal read-only with everything it
+said or touched left out, a **Request handoff** the owner approves, and rate
+limits on the API. Still open from item 1: TLS (there is none, so the board
+belongs on Tailscale or a trusted LAN), token scopes finer than owner and
+guest, and an audit view.
+
+**0.2.0 (2026-09-11) shipped the terminal-first entry**: `leg claude|codex|agy`
+runs the real interactive agent with a board, usage tracking and a hand-off
+alongside it. Against the list below, it delivers the hand-off-on-demand half
+of the "hand off now to \<adapter>" item (a button on every terminal card,
+which takes the next option in the chain; the picker is still open), and it
+puts the machine's terminals on one board, which is the surface item 1's
+multi-human work was built on.
+
+v1 ships one wedge: a card runs a fallback chain of coding-agent CLIs, and when
+a leg hits its usage limit the next agent resumes from a handoff bundle in the
+same worktree. Where it is headed (Wes, 2026-09-10, after @mikehostetler's
+"massive multiplayer software factory"): many cards, many agents and several
+humans working one repo at once; stations handing work to each other
+continuously; trunk moving in small landed pieces all day; every human judgment
+a button on a shared floor. Not live co-editing of the same files: that is a
+conflict machine with agents. The v1 shapes already point there: stations not
+fixed columns, a scheduler with path leases, a merge queue, a ledger where every
+event names its actor, a board that reads only the ledger, and an auth/bind seam.
+
+## Next
+
+1. **Multi-human network access**, shipped in 0.3.0 as `leg share` (a token
+   and a name per human, per-human actor ids on every event, rate limits, a
+   guest's read-only redacted board). What is left: TLS termination, token
+   scopes finer than owner and guest, and an audit view of who did what across
+   sessions.
+2. **Review station with human reviewers**: a `human` station kind that shows
+   the diff, the bundle and the test tail, with Approve / Request changes /
+   Reassign as buttons; reviewer identity from the token.
+3. **`pr` land mode live**: `gh pr create` argv is built and stub-tested today;
+   run it for real behind an explicit per-card opt-in and a remote allowlist.
+4. **More adapters**: grok (adapter written, unregistered until `grok login` and
+   a passing probe on the machine) and muse only if a real CLI is verified; a
+   generic "argv + JSON result" adapter for anything else.
+5. **OpenClaw Workboard mirror** once the bundled plugin is allowed
+   (`plugins.allow`): the verb table in `src/sync/workboard.mjs` is the only
+   thing to check against `openclaw workboard --help`.
+
+Also on the list: per-station prompt templates editable from the board, a
+"hand off now to <adapter>" picker, lease suggestions from the diff of the
+previous leg, and a floor view that shows lease contention over time.

package/docs/VOCABULARY.md

@@ -0,0 +1,243 @@
+# Vocabulary
+
+One page of the words Leg uses for state, events and actions, pulled
+straight from the source (not invented). Each table lists the exact
+identifiers the code uses; UI copy is allowed to be more readable ("Hand off
+now" for `handoff_now`) but must not use a different word for the same thing.
+Regenerate this by re-running the greps in each section header if the source
+changes.
+
+## Session statuses
+
+One interactive terminal under `leg claude|codex|agy`. Source:
+`src/sessions.mjs` `SESSION_STATUSES`; board labels from `STATUS` in
+`src/board/sessions.js`.
+
+| status | board label | active? | meaning |
+|--------|-------------|---------|---------|
+| `starting` | starting | yes | the runner registered the session; the agent has not reported in yet |
+| `running` | running | yes | the agent is up and taking turns |
+| `warning` | near limit | yes | a usage window crossed `LEG_WARN_PCT` (default 85) |
+| `limit` | limit hit | yes | the agent reported its usage limit; the account is walled |
+| `handing_off` | handing off | yes | the bundle is being saved and the next option chosen |
+| `waiting` | waiting for reset | yes | every option is walled; the terminal counts down to the first reset (`session.waiting`) and then starts that agent from the bundle |
+| `handed_off` | handed off | no | this leg is done; the next agent owns the terminal |
+| `ended` | ended | no | the agent exited, or End was pressed |
+| `lost` | lost | no | the runner process that owned the terminal is gone; never shown as live |
+
+The six active statuses are what the board counts as a live session for
+overlap flags and for the accounts strip's live dot.
+
+## Session event types
+
+Source: the `appendEvent`/`updateSession` call sites in `src/attach.mjs`,
+`src/sessions.mjs`, `src/taps/claude.mjs` and `src/server.mjs`; written to
+`$LEG_HOME/sessions/<id>/events.jsonl`.
+
+| type | meaning |
+|------|---------|
+| `started` | the session was created: agent, account and directory |
+| `leg` | one agent is starting in this terminal, noting whether it starts from a handoff bundle |
+| `agent_ready` | the agent reported its own session id (claude's `SessionStart` hook, codex's rollout `session_meta`) |
+| `turn` | a human prompt was submitted; carries the turn number and the first 120 characters |
+| `turn_done` | the agent's reply for that turn, first 160 characters |
+| `warning` | a usage window crossed the warning threshold; names the window, the percentage and the next option |
+| `limit` | a usage limit was detected; carries the agent's own wording, `(simulated)` when `leg sessions simulate-limit` produced it |
+| `handoff_requested` | someone pressed Hand off now, ran `leg sessions handoff`, or (on a shared board) asked for or approved a hand-off; `by` names the human (a dismissed request logs as `status` instead) |
+| `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 |
+| `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 |
+| `status` | a note that does not fit another type |
+| `worktree` | another live session was in the checkout, so this one got its own worktree: path, branch, base |
+| `land_requested` | Land was pressed: the branch and its base |
+| `land_warning` | the landing ran without a test command |
+| `landed` | the base was fast-forwarded to the branch: sha range, files, who pressed Land |
+| `bounced` | the landing stopped with a [bounce reason](#bounce-reasons-land-station); the full detail is in `body` |
+| `land_noop` | Land found nothing on the branch beyond its base |
+
+## Land states (terminal cards)
+
+`$LEG_HOME/sessions/<id>/land.json`, written by the board server only
+(`src/land.mjs`); the runner never touches it.
+
+| state | card line | meaning |
+|-------|-----------|---------|
+| `landing` | landing `<branch>` onto `<base>`… | the merge queue has the branch |
+| `landed` | ✓ landed on `<base>` · `<sha>` | the base was fast-forwarded |
+| `noop` | nothing to land | the branch had nothing beyond its base |
+| `bounced` | ✗ bounced (`<reason>`) | a step failed and the base is untouched |
+| `interrupted` | the landing was cut off | the board restarted while it was landing; press Land again |
+
+## Share roles (more than one human)
+
+`$LEG_HOME/share.json`, written by `leg share` (`src/share.mjs`).
+
+| role | the terminals lane | the pipeline side | their own terminals |
+|------|--------------------|-------------------|---------------------|
+| `owner` | every card in full | everything | control, Land, Remove, approve or dismiss a request |
+| `guest` | their own cards in full; every other card read-only, with the prompt, paths, file names, limit text, bundle and events left out | 403 | control, Land and Remove their own; **Request handoff** on anyone else's |
+
+A request is `{ by, at, state: pending\|approved\|dismissed }` in the session's
+`requests.json`; approving it sends the runner `handoff` with
+`by: "<owner> for <guest>"`.
+
+## Card statuses
+
+Source: `src/chain.mjs` `TERMINAL` + `NON_TERMINAL`.
+
+| status | terminal? | meaning |
+|--------|-----------|---------|
+| `backlog` | no | card created, not yet queued |
+| `queued` | no | waiting for the scheduler to start a leg under its leases |
+| `running` | no | a leg (agent/test/land station) is executing |
+| `handing_off` | no | the leg ended (limit/incomplete/no_progress/stalled/failed) and Leg is writing the handoff bundle |
+| `waiting_human` | no | parked at a `human` station for a button press |
+| `needs_approval` | no | next chain entry has `approve: true`; parked for Approve |
+| `paused` | no | human paused it; child killed, bundle written |
+| `done` | yes | all pipeline stations complete |
+| `failed` | yes | chain exhausted, an environment fault, or land attempts exhausted |
+| `killed` | yes | killed from the board |
+
+## Leg outcomes
+
+Source: `src/limits.mjs` `OUTCOMES` (`classify()`'s return value).
+
+| outcome | meaning |
+|---------|---------|
+| `completed` | exit 0 and `.leg/DONE` present |
+| `incomplete` | exit 0 with changes but no DONE marker |
+| `no_progress` | exit 0, no DONE marker, no changes |
+| `limit` | an adapter-specific or generic usage-limit signal fired |
+| `stalled` | the kill timer fired before the leg finished |
+| `auth_failed` | an auth signal fired, or stderr says another auth source is set; not treated as a limit |
+| `launch_failed` | the CLI failed to spawn, or a launch signal fired |
+| `killed` | killed from the board |
+| `failed` | none of the above; non-zero exit with no recognized signal |
+
+`limit`, `incomplete`, `no_progress`, `stalled` and `failed` hand off to the
+next adapter in the chain (`HANDOFF_OUTCOMES`); `auth_failed` and
+`launch_failed` do not advance the chain: a human fixes the environment and
+clicks Rerun (`NO_ADVANCE_OUTCOMES`).
+
+## Station kinds
+
+Source: `src/pipeline.mjs` `KINDS`.
+
+| kind | meaning |
+|------|---------|
+| `agent` | runs the station's chain (one or more adapters) with that station's prompt |
+| `human` | parks the card for a button press; no automatic work |
+| `test` | runs the repo's test command; bounces the card on red |
+| `land` | merge queue: rebase, test, fast-forward trunk (see Bounce reasons below); at most one, must be last |
+
+## Event types
+
+Source: `src/ledger.mjs` `EVENT_TYPES`, written by `ledgerAppend`/`ev()` calls
+across `src/chain.mjs`, `src/orchestrator.mjs`, `src/scheduler.mjs`,
+`src/land.mjs` and `src/store.mjs`.
+
+| type | meaning |
+|------|---------|
+| `card_created` | a card was added |
+| `leg_started` | an adapter leg started running |
+| `leg_progress` | progress recorded mid-leg |
+| `leg_exited` | the adapter process exited |
+| `limit_detected` | a limit signal fired during a leg |
+| `handoff_written` | the handoff bundle was written for the next leg |
+| `leg_resumed` | a leg resumed from a bundle (pause/resume, or a bounce) |
+| `station_done` | a station finished and the card advanced |
+| `bounced` | a test or land failure sent the card back to `build` |
+| `landed` | the land station merged the card's work onto trunk |
+| `land_warning` | the land station landed without running tests (no test command found) |
+| `land_retry` | trunk moved during land; one fast-forward retry |
+| `blocked_by` | the scheduler could not start the card because a lease is held |
+| `scheduler_started` | the scheduler process started |
+| `scheduler_stopped` | the scheduler process stopped |
+| `approval_needed` | the card is parked for Approve (gated leg or a PR was opened) |
+| `approved` | a human clicked Approve |
+| `reassigned` | a human changed the current leg's adapter/mode |
+| `paused` | a human clicked Pause |
+| `resumed` | a human clicked Resume |
+| `killed` | a human clicked Kill |
+| `done` | the card finished all stations |
+| `failed` | the card failed (chain exhausted, land attempts exhausted, or an environment fault) |
+| `error` | an unexpected error (orchestrator crash, handoff bundle write failure, land station crash) |
+| `status` | a status note that doesn't fit another type (e.g. "rerun from build leg 0") |
+
+## Actor types
+
+Source: `src/ledger.mjs` (`parseActor`/`actorKey`).
+
+| type | meaning |
+|------|---------|
+| `agent` | an adapter CLI acting on a leg; carries `adapter` (and optionally `model`) |
+| `human` | a person acting through the board or CLI; carries `id` |
+| `leg` | Leg itself (scheduler, orchestrator) acting with no human or agent behind it |
+
+## Human actions and board buttons
+
+Source: `src/chain.mjs` `HUMAN_ACTIONS`; board labels from
+`ACTION_LABELS` in `src/board/board.js` (~line 17).
+
+| action | board button | what it does |
+|--------|--------------|--------------|
+| `pause` | Pause | stop after the current leg |
+| `resume` | Resume | pick up where it stopped |
+| `kill` | Kill | stop the running agent; card ends as `killed` |
+| `reassign` | Reassign | pick the next adapter/mode from a picker instead of the chain order |
+| `handoff_now` | Hand off now | end the current leg, write the bundle, start the next adapter |
+| `approve` | Approve | release a leg gated with `approve: true`, or clear a `waiting_human` station |
+| `rerun` | Rerun | start the station over from the last bundle |
+
+The board also shows a **Run** button for `enqueue` (queues a `backlog` card;
+API path `run`). `enqueue` moves a card via the station machine's
+`backlog`→`queued` transition and is not in `HUMAN_ACTIONS`, since it is
+reached through card creation/queueing rather than `humanAction()`.
+
+## Bounce reasons (land station)
+
+Source: `src/mergequeue.mjs` (`bounce()` call sites, documented in the
+file's own header comment).
+
+| reason | meaning |
+|--------|---------|
+| `dirty-trunk` | the repo root isn't on the trunk branch, or has uncommitted changes; root is left untouched. A terminal's Land allows local changes in the checkout and bounces this way only when the fast-forward would overwrite one, naming the files |
+| `rebase-conflict` | rebasing the card's branch onto trunk conflicted |
+| `rebase-failed` | git refused the rebase for a reason other than a conflict (a hook, an unusable upstream); the detail carries git's own words |
+| `tests-red` | the land station's own test run (no test command found → falls back per `land_warning`, otherwise `test_command`/`npm test`/`pytest`) failed |
+| `trunk-moved` | trunk moved while tests ran; one fast-forward retry also failed |
+
+Card-level `bounce_reason` is stored as `"<reason>: <detail>"`
+(`src/orchestrator.mjs`); the board's status chip shows the text up to the
+first colon or opening parenthesis, truncated to 24 characters. The separate
+pipeline `test`
+station (kind `test`, distinct from a `land` station's own internal test
+step) bounces with its own free-text reason ("test red (…): …"), not one of
+the four words above, it is a different failure path through the same
+`bounced` event type.
+
+## Cross-check against visible strings
+
+Checked against `src/board/board.js`, `src/board/floor.js`,
+`src/board/index.html`, `src/board/floor.html`, `bin/leg.mjs`'s usage text
+and `README.md`.
+
+- Board button labels (`ACTION_LABELS`, `WAIT_LABELS`) match README's "Board
+  buttons" table word for word (Run, Approve, Pause, Resume, Hand off now,
+  Reassign, Kill, Rerun).
+- Board status labels (`STATUS_LABELS`) and chain-rail glyphs
+  (`stateGlyph`: ✓ done, ↷ handed, ✗ failed, ● active, · pending) match the
+  README's drawer description.
+- Station kinds shown in the drawer (`${name} (${kind})`) and README's
+  "Station kinds" list both use `agent`/`human`/`test`/`land`.
+- CLI human-action verbs in `bin/leg.mjs` (`pause`, `resume`, `kill`,
+  `approve`, `handoff-now`, `rerun`, `reassign`) are the same 7 words as
+  `HUMAN_ACTIONS`, spelled with hyphens instead of underscores on the CLI
+  surface (`handoff-now` vs `handoff_now`), a deliberate, consistent
+  per-surface convention, not a mismatch.
+- One mismatch found: the bounce chip splits on the first colon **or**
+  opening parenthesis (`src/board/board.js:325`), which the Bounce reasons
+  note above now states. Nothing else needed changing in `src/board/*`.

package/docs/adapters.md

@@ -0,0 +1,300 @@
+# Adapters
+
+Two things per agent: what Leg reads from an interactive session
+(`leg claude|codex|agy`), and the headless argv the v0.1 pipeline spawns.
+Every fact here was written against `src/taps/*.mjs`, `src/attach.mjs` and
+`src/adapters/*.mjs`; the evidence trail, including which lines an artifact
+backs, is [cli-contracts.md](cli-contracts.md).
+
+An agent is never run through a shell. Interactive sessions are
+`spawn(bin, argv, { stdio: 'inherit' })` (`src/attach.mjs` `spawnSpec`);
+headless legs are `spawn(spec.bin, spec.args, …)` (`src/runner.mjs`). Both
+strip the API-key and base-URL variables and the Claude Code nested-session
+markers from the child environment (`src/env.mjs` `sanitizeEnv`).
+
+## What Leg reads from each agent
+
+Nothing is screen-scraped. Each tap was read from the CLI's own source or
+documentation, then checked on a real machine on 2026-09-11 (Claude Code
+2.1.268, codex-cli 0.153.4, agy 1.2.0). Lines that a live run or a fixture
+backs say observed-live; lines read only from a CLI's source or
+documentation say docs-only.
+
+### claude
+
+- **How Leg attaches**: one extra settings file per session, passed as
+  `claude <your args> --settings <~/.leg/sessions/<id>/claude-settings.json>`
+  (`src/taps/claude.mjs` `settingsFor`). Hooks from `--settings` merge with
+  yours rather than replacing them. Observed live: a Leg session ran with
+  every user hook still firing.
+- **Hooks wired**: `SessionStart`, `UserPromptSubmit`,
+  `PostToolUse` (matcher `Edit|Write|MultiEdit|NotebookEdit`), `Stop`,
+  `StopFailure`, `SessionEnd`, each running
+  `node src/hook.mjs claude-hook --session <id>`. Observed live.
+- **`autoContinueAtUsageLimit` is set to `false`** in that settings file,
+  because Leg owns what happens at the limit.
+- **Usage percentages**: `GET https://api.anthropic.com/api/oauth/usage`
+  (`LEG_CLAUDE_USAGE_URL` overrides), with the `accessToken` Claude Code
+  stored in `<CLAUDE_CONFIG_DIR>/.credentials.json` under `claudeAiOauth`, and
+  the header `anthropic-beta: oauth-2025-04-20`. The response carries
+  `five_hour` and `seven_day`, each `{ utilization, resets_at }`. Polled every
+  60 s (`LEG_USAGE_POLL_MS`). Observed live: real percentages come back
+  and land in `<LEG_HOME>/usage/claude--default.json` with
+  `source: claude usage endpoint`; a 7-day window at 93 % raised the amber
+  warning on 2026-09-11.
+- **The wall**: the `StopFailure` hook fires with `error: rate_limit`
+  ([docs](https://code.claude.com/docs/en/hooks#stopfailure)). Status:
+  **observed-live 2026-09-11** <!-- live:claude/rate_limit -->. A real
+  `StopFailure` arrived on 2026-09-11 at 07:46:37Z, a 429 `rate_limit_error`
+  from the API, and is kept, secrets scrubbed, as
+  `fixtures/live/claude/limit-rate_limit.json` (`src/live-capture.mjs`); a
+  payload `leg sessions simulate-limit <id>` produces is marked and never
+  kept (`src/live-capture.mjs` `isSimulated`). The path is also covered by
+  the hook contract test and can be driven end to end with
+  `leg sessions simulate-limit <id>`, which sends the same payload through
+  `src/hook.mjs`.
+- **Why not the status line.** Leg writes a `statusLine` entry into the same
+  settings file that would record `rate_limits.five_hour.used_percentage` and
+  `resets_at`, and chains your own `statusLine` command first. Claude Code
+  2.1.268 did not run it when it was tried on this machine: an `echo` command
+  passed through `--settings` and again through a project
+  `.claude/settings.local.json` left the built-in status line in place, while
+  hooks from the same `--settings` file fired. No artifact of that check was
+  kept; the note lives in the `src/taps/claude-usage.mjs` header. The endpoint
+  poll is therefore the live source; the status-line route becomes a fallback
+  the moment a build honours it.
+- **Token handling**: the stored token is read by the polling process only,
+  sent only to `api.anthropic.com`, and written nowhere. The ledger scrubs
+  bearer tokens from every line regardless (`src/redact.mjs`).
+
+### codex
+
+- **How Leg attaches**: nothing is injected. `leg codex` runs `codex` with
+  your arguments, then finds and tails that session's rollout file. A hook
+  would have to be trusted by codex on first use, which is why this tap
+  reads instead.
+- **Which file**: `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
+  (`CODEX_HOME` when an extra account is in use), picked by
+  `session_meta.payload.cwd` equal to the session's directory and a birth
+  time or mtime at or after the spawn, with five seconds of slack
+  (`src/taps/codex.mjs` `findRollout`). Observed live: the tap found the
+  right rollout for a real hand-off. On Windows the file's mtime lags its
+  contents, across six rollouts from 2026-09-11 the mtime was 7 s to 9 min
+  behind the last line's timestamp, so `findRollout` matches on cwd and
+  accepts a birth time or mtime at or after the spawn rather than relying on
+  the two agreeing.
+- **Usage percentages**: the read-only app-server `account/rateLimits/read`
+  response. Leg identifies the returned windows by duration rather than by
+  field name: 300 minutes is 5h and 10080 minutes is 7d. The board and active
+  attach poll it every 60 seconds; neither sends a model turn nor assumes a
+  quota. Only an explicit available response clears a prior wall.
+- **The wall**: `event_msg.task_complete.error` with
+  `codex_error_info: "usage_limit_exceeded"` and the message "You've hit your
+  usage limit … try again at \<date>". The wording comes from
+  `codex-rs/protocol/src/error.rs` (`UsageLimitReachedError`); the event shape
+  was read from local rollouts. The error itself:
+  **observed-live 2026-09-15** <!-- live:codex/usage_limit_exceeded -->, a
+  real `task_complete.error` with `codex_error_info: usage_limit_exceeded`
+  walled a codex leg at 07:56:24Z and handed the session to agy. No payload
+  was kept: the capture call in `src/attach.mjs` was added while that
+  session's runner was already running, so
+  `fixtures/live/codex/limit-usage_limit_exceeded.json` is still the slot
+  for the next one.
+- **Transcript**: user prompts from `response_item.message` with `role: user`
+  and `content[].type: input_text`; assistant text from `output_text` and from
+  `task_complete.last_agent_message`. Observed live.
+- **Edited files**: parsed from `apply_patch` payloads, the
+  `*** Add File:` / `*** Update File:` / `*** Delete File:` lines. Observed
+  live.
+
+### agy
+
+- **How Leg attaches**: `agy <your args> --log-file
+  <~/.leg/sessions/<id>/agy.log>`. agy 1.2.0 is a closed Go binary with no
+  hook surface.
+- **Usage percentages**: none. agy exposes no percentage anywhere on disk; its
+  own status line fetches a quota summary from the backend and writes it
+  nowhere. When agy is not walled the board shows a "no % from agy" chip
+  instead of empty bars (`src/board/sessions.js`); when it is walled the
+  chip shows the wall and its reset.
+- **The wall**: `RESOURCE_EXHAUSTED`, "it resets in %s" and "out of quota" in
+  the log. Those strings are present in `agy.exe`, and `scanLog()` also reads a
+  relative reset out of "resets in \<n>\<s|m|h|d>". Status:
+  **docs-only** <!-- live:agy/agy-resource-exhausted --> —
+  `RESOURCE_EXHAUSTED (code 429): Individual quota reached … Resets in
+  71h19m42s.` appeared in a session's `agy.log` at 08:02:42Z and walled the
+  agent. No payload was kept: the capture call in `src/attach.mjs` was added
+  while that session's runner was already running, so
+  `fixtures/live/agy/limit-agy-resource-exhausted.json` is still the slot
+  for the next one.
+- **Prompts and conversation id**: `~/.gemini/antigravity-cli/history.jsonl`,
+  one `{ display, timestamp, workspace, conversationId }` per prompt. Observed
+  live.
+- **One account only**: agy 1.2.0 has no config-directory override, so
+  `leg accounts add agy …` is refused.
+
+### Resume prompt per agent
+
+After a hand-off the next agent starts in the same terminal with the pointer
+prompt as its first positional argument: `claude "<prompt>"`,
+`codex "<prompt>"`, `agy -i "<prompt>"` (`src/attach.mjs` `spawnSpec`).
+
+## Headless adapters (the v0.1 pipeline)
+
+These are what a pipeline card's chain spawns. Unchanged since 0.2.0.
+
+### claude (headless)
+
+- **Binary**: `LEG_CLAUDE_BIN`, else `~/.local/bin/claude.exe` (Windows)
+  or `~/.local/bin/claude`, else `claude` on PATH.
+- **Argv**: `claude -p --output-format json --permission-mode <mode>`, plus
+  `--max-turns <n>`, `--resume <session-id>`, `--model <name>`,
+  `--allowedTools <a,b>` when set.
+- **Stdin**: `pipe`: the prompt is written to stdin, not argv.
+- **Modes**: default `acceptEdits`; allowed `acceptEdits`, `auto`, `plan`,
+  `manual`, `dontAsk`.
+- **Forbidden flags**: `--dangerously-skip-permissions`,
+  `--allow-dangerously-skip-permissions`,
+  `--permission-mode=bypassPermissions`, `bypassPermissions`.
+- **Gotchas**: prints nothing on stdout until the session ends (poll
+  `run.json`, never a stdout timeout). Stderr saying "another auth source is
+  set" is an `auth_failed` leg, not a limit: it means an
+  `ANTHROPIC_API_KEY` or similar is shadowing the subscription login.
+
+### codex (headless)
+
+- **Binary**: `LEG_CODEX_BIN`, else the `@openai/codex` npm package's
+  native platform exe (resolved under `%APPDATA%\npm\node_modules\@openai\codex\...`
+  on Windows), else `node <bin/codex.js>` via `resolveNpmCliEntry`, else
+  `codex` on PATH.
+- **Argv**: `codex exec --json -s <mode> -C <cwd> -c
+  sandbox_workspace_write.network_access=<true|false>`, plus `-m <model>`,
+  `-o <runDir>/last.md`, `resume <session-id>` and the prompt as the last
+  positional argument.
+- **Stdin**: `ignore`, deliberately. `codex exec` reads stdin whenever it
+  is not a TTY and hangs on an open pipe ("Reading additional input from
+  stdin..."); a plan-time probe with a pipe hung until it was killed at
+  170 s; the same task with stdin closed finished normally (the kept probe
+  run took 28 s).
+- **Modes**: default `workspace-write`; allowed `read-only`,
+  `workspace-write`.
+- **Forbidden flags**: `danger-full-access`,
+  `--dangerously-bypass-approvals-and-sandbox`,
+  `--dangerously-bypass-hook-trust`, `--full-auto`, `--approve-for-me`.
+- **Gotchas**: network access is off unless the chain entry sets
+  `network: true`. If you run `codex exec` by hand outside Leg, always
+  pass the prompt as an argument, never on a pipe.
+
+### agy (headless)
+
+- **Binary**: `LEG_AGY_BIN`, else `%LOCALAPPDATA%\agy\bin\agy.exe`, else
+  `agy` on PATH.
+- **Argv**: `agy -p "<working-directory preamble>\n\n<prompt>"
+  --output-format json --mode <mode> --add-dir <cwd> --print-timeout
+  <duration>`, plus `--model <model>`, `--conversation <session-id>`. The
+  duration is the card's kill timer converted to Go syntax, for example `90m`.
+- **Stdin**: `ignore`.
+- **Modes**: default `accept-edits`; allowed `accept-edits`, `plan`.
+- **Forbidden flags**: `--dangerously-skip-permissions`.
+- **Gotchas**: agy does not act in the process cwd by default: with no
+  `--add-dir` it writes into its own scratch workspace
+  (`~/.gemini/antigravity-cli/scratch/`, observed live). Leg always passes
+  `--add-dir <worktree>` and prefixes the prompt with "Working directory:
+  `<worktree>`" so the agent writes where the card expects. `--print-timeout`
+  defaults to 5 minutes in the CLI itself; Leg always sets it explicitly
+  from the leg's kill timer so the supervisor, not agy, decides what a
+  runaway is.
+
+### fake (and fake-claude / fake-codex / fake-agy / fake-nostdin)
+
+- **Binary**: always `node bin/fake-agent.mjs` (`process.execPath` +
+  the script path); nothing to install.
+- **Argv**: `fake-agent.mjs [--mode <m>] [--max-turns <n>] [--resume <id>]`.
+- **Stdin**: `pipe` for `fake`, `ignore` for the `fake-*` named variants
+  (`fake-nostdin` is the same agent with stdin ignored), useful for
+  exercising both stdin conventions without a real CLI.
+- **Modes**: default `acceptEdits`; allowed `acceptEdits`, `plan`,
+  `workspace-write`, `read-only`, `accept-edits`, `auto_edit` (a superset
+  covering every real adapter's vocabulary, so a chain can mix fakes and
+  real adapters without a mode conflict).
+- **Forbidden flags**: `--dangerously-skip-permissions`, `--yolo`.
+- **What it does**: driven entirely by the `FAKE_MODE` environment
+  variable, set per chain entry with `--fake-mode <adapter>=<mode>` (see
+  [getting-started.md](getting-started.md#try-a-pipeline-with-no-real-agent)
+  for the full list of modes). `fake-claude` / `fake-codex` / `fake-agy` set
+  `emulates` to that CLI's name, so the limit classifier applies that CLI's own
+  fixtures to it and a demo chain reads like a real fallback.
+
+### grok (built, not registered)
+
+- **Binary**: `LEG_GROK_BIN`, else `~/.grok/bin/grok.exe`, else `grok` on
+  PATH.
+- **Argv**: `grok -p "<prompt>" --output-format json --permission-mode
+  <mode>`, plus `-m <model>`, `-r <session-id>`.
+- **Stdin**: `ignore`.
+- **Modes**: default `acceptEdits`; allowed `default`, `acceptEdits`,
+  `auto`, `dontAsk`, `plan`.
+- **Forbidden flags**: `--always-approve`, `bypassPermissions`,
+  `--permission-mode=bypassPermissions`.
+- **Status**: `src/adapters/grok.mjs` exists and is unit-tested, but is
+  **not** in `src/adapters/index.mjs`'s registry. The build machine had no
+  `grok` login: the probe printed a device-code prompt and exited
+  `Cancelled`. Register it (add an entry to `REGISTRY` in
+  `src/adapters/index.mjs`) once `grok login` has been completed and
+  `node scripts/probe.mjs --adapter grok --repo <toy-repo>` passes.
+
+## How to add an adapter
+
+An adapter is a plain object (see `src/adapters/common.mjs` for the shared
+helpers, `src/adapters/fake.mjs` for the simplest full example):
+
+```js
+{
+  name: 'mycli',
+  stdin: 'pipe' | 'ignore',
+  modes: { default: 'acceptEdits', allowed: ['acceptEdits', 'plan'] },
+  forbiddenFlags: ['--any-bypass-flag'],
+  emulates: null,             // optional: another registered adapter's name
+  resolve() { return { bin, viaNode, entry } },
+  argv(opts) { return { bin, args } },   // opts: mode, maxTurns, resume, cwd, prompt, model, ...
+  env(base) { return sanitizeEnv(base) },   // from src/env.mjs, always
+  parseResult(text) { return { session_id, last_message, stop_reason, raw } | null },
+}
+```
+
+1. Write `src/adapters/<name>.mjs` exporting that shape as `default`.
+   `argv()` must call `assertAllowed(adapter, opts)` (from
+   `src/adapters/common.mjs`) first, so a forbidden mode or flag throws
+   before anything spawns.
+2. Add an entry to `REGISTRY` in `src/adapters/index.mjs`:
+   `<name>: { path: './<name>.mjs' }`.
+3. Add its limit/auth/launch signal fixtures under `fixtures/limits/` (see
+   the existing ones for the JSON shape `src/limits.mjs` expects: `id`,
+   `adapter`, `source`, `produced_by`, `where`, `text`, `classification`).
+4. Run the probe script against a real login before trusting it:
+
+   ```
+   node scripts/probe.mjs --adapter <name> --repo <existing-git-repo> [--mode <m>] [--timeout-s 300]
+   ```
+
+   It runs one real tiny task (write a file, write `.leg/DONE`) through
+   the same runner a card uses, and prints `probe <name>: exit=<code>
+   file=<yes|no> done=<yes|no> auth_source=<yes|no> seconds=<n>`. Keep the
+   evidence it produces under `fixtures/live/<name>/` and cite it in
+   [cli-contracts.md](cli-contracts.md), the way every existing adapter's
+   section does.
+
+An interactive tap is a separate, larger job: a new agent needs a
+`src/taps/<name>.mjs` that answers three questions (what are the usage
+percentages, what does the wall look like, what are the prompts and edited
+files) and a branch in `src/attach.mjs` `spawnSpec`.
+
+## See also
+
+- [cli-contracts.md](cli-contracts.md): the full evidence trail, exit
+  codes, the interactive tap sources, and every limit-signal fixture, tagged
+  observed-live or docs-only.
+- [configuration.md](configuration.md): the `LEG_<ADAPTER>_BIN`
+  overrides and the accounts layout.
+- [concepts.md](concepts.md): sessions, usage windows, the interactive
+  hand-off, and how a headless leg's outcome is classified.