@ucsandman/legcli 0.10.0 → 0.12.0

package/docs/VOCABULARY.md

@@ -45,6 +45,7 @@ Source: the `appendEvent`/`updateSession` call sites in `src/attach.mjs`,
 | `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 |
+| `waiting` | a claude `Notification` said a human is being waited on: the type (`permission_prompt`, `idle_prompt`, `agent_needs_input`) and the question verbatim; the next prompt or the end of the turn clears it |
 | `all_out` | every option is walled; the resets are printed and the terminal waits for the first one (`ended` with "quit while waiting" if Ctrl-C or End cuts the wait short, exit 3) |
 | `agent_exit` | the agent process exited, with its code |
 | `continued` | the session was started by `leg history continue` on a conversation the agent's own store holds; `session.json` carries `continued_from: { id, provider, native_id }` |
@@ -61,6 +62,32 @@ Source: the `appendEvent`/`updateSession` call sites in `src/attach.mjs`,
 | `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 |
 
+## Routing and capacity words
+
+The words the ladder, the usage record and the board top use. Source:
+`src/preferences.mjs` (`RUNG_COSTS`, `WHEN_RE`, `defaultLadder`),
+`src/usage.mjs` (`binding`, `burn`, `emptyRecord`), `src/buckets.mjs`
+(`bucketFromWall`) and `src/board/sessions.js`.
+
+| word | meaning |
+|------|---------|
+| rung | one destination on the ladder: `{agent, account, model, when, cost}`. `leg ladder` writes `claude/default/opus`; a rung with `model: null` means "whatever that CLI's default is", never a guess |
+| ladder | the ordered list of rungs a terminal falls down, `preferences.handoff_ladder`. `handoff_order` is its older, narrower form and is derived from it, so both stay true |
+| `when` | when a rung may be taken: `always`, `below:N` (only while that login's binding percent is under N), or `walled-only` (only when every rung above it is walled, never when they are merely slow) |
+| `cost` | what a rung spends: `free`, `plan`, `credits` or `metered`. Computed at the moment of choosing, never trusted from disk, because `credits` depends on whether the login has extra usage enabled right now |
+| `may_spend` | off by default. While it is off, an automatic hand-off skips any `credits` or `metered` rung and says so in the ledger. A hand-off a human presses is not automatic and is not gated |
+| `reserve` | a per-login floor, `{agent: percent}`. An automatic hand-off skips a rung past the floor so a background card cannot eat what you kept for yourself; a human pick still takes it and the picker says `past your N% reserve` |
+| `climb_back` | `next-handoff` (the default: the ladder is walked from rung 1 every time, so a reset model is picked up at the next hand-off) or `never` (stay put until **Back to fable**). Leg never interrupts a running turn to climb |
+| bucket | one measured window in a usage record's `buckets[]`: `kind` (`session`, `weekly_all`, `weekly_scoped`), `model` (set only on `weekly_scoped`), `percent`, `resets_at`, `is_active`. A percentage, always measured, never inferred from wording |
+| binding bucket | the bucket that will stop this login first, what `binding(u, model)` returns. The strip, the verdict and the row all print this one rather than whichever window happened to be stored |
+| wall scope | how far a wall reaches, from `bucketFromWall`. `model` walls one model family and writes `walls[model]`, leaving the login open; `account` walls the whole login through `limited_until`. Wording Leg cannot parse is `account`, and the row prints the evidence it failed on |
+| capacity | the phrase a row prints for its own binding bucket: `63% of the fable week`, or nothing when there is no reading. Computed per request, never persisted |
+| forecast | a time figure from `burn()`, and only ever with its sample count: `about 2h 40m of Fable left, from 9 samples over 4h`. Under three samples spanning ten minutes, or on a flat or falling line, or across a reset, it prints nothing at all |
+| waiting on you | a row's status word when `session.waiting` is set by a claude `Notification` hook. It sorts the row first, counts in the Terminals head and puts `(N) Leg` with a dotted favicon in the browser tab. Only claude publishes this signal; other agents say `quiet Nm` and never claim to be waiting |
+| Background | the panel of live cards directly under Terminals. Liveness decides the surface, not kind: `backlog`, `queued`, `running`, `handing_off`, `needs_approval`, `waiting_human` and `paused` are rows here, and `done`, `failed` and `killed` collapse into one ledger line |
+| end as a card | the second verb on a terminal's End confirm row (`POST /api/sessions/:id/end-as-card`): writes the bundle, hands the terminal's own worktree to a card starting at the terminal's current rung, and records the terminal as its `lineage.from` |
+| take over | the reverse, in a card's expansion (`POST /api/cards/:id/take-over`): pauses the card and prints `leg claude --resume-card <id>`, the one command a browser cannot run for you |
+
 ## Harness states (terminal cards, drawer, `leg harness`)
 
 Source: `STATES` in `src/harness/index.mjs`; recorded on `session.harness.state`.

package/docs/adapters.md

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