@ucsandman/legcli 0.10.0 → 0.11.0

package/docs/cli-contracts.md

@@ -25,7 +25,7 @@ questions."
 | claude | 2.1.268 | exit 0, file yes, DONE yes, 20 s | `src/adapters/claude.mjs` |
 | codex | codex-cli 0.153.4 | exit 0, file yes, DONE yes, 28 s | `src/adapters/codex.mjs` |
 | agy | 1.2.0 | attempt 1 exit 0 but wrote to its scratch workspace; attempt 2 (`--add-dir`) exit 0, file yes, DONE yes, 41 s | `src/adapters/agy.mjs` |
-| grok | 0.2.51 | exit 0, `stopReason: Cancelled`, no file: not logged in (device-code prompt) | `src/adapters/grok.mjs` exists, NOT registered |
+| grok | 1.0.34 | exit 1, no file, no DONE: the account answered `402 Payment Required: Grok Build usage balance exhausted`, classified `limit` (re-probed 2026-09-17; the 2026-09-11 run on 0.2.51 was not logged in) | `src/adapters/grok.mjs` |
 
 The auth-source check: the build shell carried `ANTHROPIC_API_KEY` and
 `OPENAI_API_KEY` (injected by the shell profile). Every adapter's `env()` deletes
@@ -165,29 +165,48 @@ stderr are 0 bytes, and codex's is the one stdin notice. observed-live.
 
 ## grok
 
-- Version grok 0.2.51 (f4f85a649) [stable] (source: `grok --version`).
+- Version grok 1.0.34 (3736acbc8658) [stable] (source: `grok --version`,
+  2026-09-17). The 2026-09-11 sweep saw 0.2.51 on a machine with no login; every
+  line below was re-read on 1.0.34.
 - Binary: `~/.grok/bin/grok.exe` (native; also an npm shim on PATH);
   `LEG_GROK_BIN` overrides (source: `where grok`).
-- Headless argv (from cmd.txt): `grok.exe -p "<prompt>" --output-format json --permission-mode acceptEdits`; stdin `ignore`.
-  `--prompt-file <path>` also exists (source: `grok --help`).
-- Output: one JSON object `{text, stopReason, sessionId, requestId, thought}`
-  (observed-live, fixtures/live/grok/out.log).
+- Headless argv (from cmd.txt): `grok.exe --prompt-file <run>/prompt.txt
+  --output-format json --permission-mode acceptEdits --cwd <worktree>`; stdin
+  `ignore`. The file form is used whenever the runner has written a prompt file,
+  because a hand-off prompt carries the whole bundle summary and Windows caps a
+  command line near 32k; with none, the adapter falls back to `-p "<prompt>"`
+  (source: `grok --help`, `-p, --single <PROMPT>` and `--prompt-file <PATH>`).
+  `--cwd <CWD>` is passed explicitly rather than trusting the spawn's working
+  directory, because grok can run against a shared leader process
+  (`~/.grok/leader.sock`) and a leg must edit its own worktree.
+- Output: the Claude Code result envelope. `"type":"result"`, `subtype`,
+  `is_error`, `session_id`, `result`, `num_turns`, `stop_reason`, `total_cost`,
+  read out of the shipped `grok.exe` on 2026-09-17 alongside the streaming
+  types (`assistant`, `system`, `text`, `usage`, `end`, `error`). An error is
+  the other envelope, `{"type":"error","message":…}` (observed-live,
+  `fixtures/live/grok/out.log`).
 - Exit codes:
 
   | exit | meaning | source |
   |------|---------|--------|
-  | 0 | printed JSON with `stopReason:"Cancelled"` and did no work: the CLI was not logged in, printed a device-code prompt on stderr (`https://accounts.x.ai/oauth2/device?user_code=…`, "Waiting for authorization...") and gave up after ~58 s | observed-live, fixtures/live/grok/err.log |
-
-  A zero exit with no DONE marker and no diff is exactly the `no_progress` class
-  the completion contract exists for.
-- Permission modes: `default`, `acceptEdits`, `auto`, `dontAsk`,
-  `bypassPermissions`, `plan` (source: `grok --help`). Leg: default
-  `acceptEdits`; forbidden `bypassPermissions`, `--always-approve`.
+  | 1 | printed `{"type":"error","message":"Internal error: … API error (status 402 Payment Required): Grok Build usage balance exhausted"}` and did no work: the account had no balance left | observed-live 2026-09-17, fixtures/live/grok/out.log |
+  | 0 | printed JSON with `stopReason:"Cancelled"` and did no work: the CLI was not logged in, printed a device-code prompt on stderr and gave up after ~58 s | observed-live 2026-09-11 on 0.2.51 |
+
+  The 402 is a wall, not a failure: `fixtures/limits/grok/grok-balance-exhausted.json`
+  classifies it `limit`, so the card hands off instead of stopping. None of the
+  rate-limit strings the tap watched for appear in a 402, which is why an
+  exhausted grok terminal used to sit there; `src/taps/grok.mjs` reads it too now.
+- Permission modes: `default`, `acceptEdits`, `auto`, `dontAsk`, `plan`, and a
+  bypass mode Leg never passes (source: `grok --help`). Leg: default
+  `acceptEdits`; forbidden the bypass mode and `--always-approve`.
 - Login: `grok login` (source: `grok --help` Commands).
-- **Verdict: not verified, no adapter registered.** `src/adapters/grok.mjs` is
-  built from `--help` and unit-tested for shape and forbidden flags, but stays
-  out of `src/adapters/index.mjs` until `grok login` has been completed on the
-  machine and `node scripts/probe.mjs --adapter grok --repo <toy>` passes.
+- **Verdict: registered, wall path verified, success path not.** The probe
+  reached the account through the real runner, so the binary resolution, the
+  argv, the auth and the limit classification are all observed-live. A leg that
+  completes its task has not been seen, because that needs balance on the
+  account; until it is, a grok leg whose envelope does not parse is judged by
+  its `.leg/DONE` marker and its diff, as every adapter is. Re-run
+  `node scripts/probe.mjs --adapter grok --repo <toy>` with balance to close it.
 
 ## `leg harness` (the portable harness)
 

package/docs/configuration.md

@@ -126,7 +126,8 @@ resolves to by default.
 | `LEG_CLAUDE_BIN` | claude | `src/adapters/claude.mjs` |
 | `LEG_CODEX_BIN` | codex | `src/adapters/codex.mjs` |
 | `LEG_AGY_BIN` | agy | `src/adapters/agy.mjs` |
-| `LEG_GROK_BIN` | grok (not registered by default) | `src/adapters/grok.mjs` |
+| `LEG_GROK_BIN` | grok | `src/adapters/grok.mjs` |
+| `LEG_<NAME>_BIN` | a custom adapter called `<name>` (dashes become underscores, so `my-agent` reads `LEG_MY_AGENT_BIN`) | `src/adapters/custom.mjs` |
 | `LEG_GH_BIN` | the `pr` land-mode stub | `src/stations/pr.mjs`; unset, `land_mode: pr` returns an error rather than running a real `gh` |
 | `LEG_CHB_BIN` | `context-handoff-bundle` | `src/handoff.mjs`; unset, Leg tries `context-handoff-bundle` on PATH, then `python -m context_handoff_bundle` |
 
@@ -210,9 +211,10 @@ other address without also setting `LEG_TOKEN` makes the server refuse to
 start, exit code `3` (`src/auth.mjs` `checkBind`/`BindRefused`). With a
 token set, every `/api/*` request needs an `Authorization: Bearer <token>`
 header; the event stream (`EventSource`, which cannot set headers) accepts
-the same token as a `?token=` query parameter instead. There is no TLS; keep
-`LEG_BIND` on loopback unless you are using `leg share`, which gives
-each human their own token (see [Share](#share-more-than-one-human)).
+the same token as a `?token=` query parameter instead. Keep `LEG_BIND` on
+loopback unless you are using `leg share`, which gives each human their own
+token (see [Share](#share-more-than-one-human)) and can serve the board over
+TLS.
 
 ## Share (more than one human)
 
@@ -224,7 +226,8 @@ switch and the roster; the env variables below only tune the limits.
 | `on` | share is on (it also needs a `bind` and at least one person) |
 | `bind`, `bind_kind`, `port` | where the board listens: the Tailscale address by default, `lan`, or one you named |
 | `owner` | the name a terminal belongs to when nothing else says (`LEG_PERSON`), and the name a loopback browser is treated as |
-| `people[]` | `{ name, role: owner\|guest, token_sha256, created_at }`; the token itself is printed once and never stored |
+| `people[]` | `{ name, role: owner\|operator\|guest, token_sha256, created_at }`; the token itself is printed once and never stored |
+| `tls` | `{ cert, key }`, the paths to a certificate pair; absent means plain http |
 | `loopback_owner` | default `true`: a browser on this machine is the owner without a token. Set it to `false` to ask for a link even here |
 
 | variable | default | meaning | read in |
@@ -234,6 +237,53 @@ switch and the roster; the env variables below only tune the limits.
 
 `LEG_TOKEN` is the single-token mode and is ignored while share is on.
 
+### Roles
+
+| role | terminals | cards | this machine |
+|------|-----------|-------|--------------|
+| `owner` | every one | every one | settings, harness policy, the trunk's repo paths, the history index, the worktree map, the audit trail |
+| `operator` | their own; someone else's is read-only and redacted | adds, runs, approves, reassigns, kills | nothing: `/api/settings`, `/api/history`, `/api/worktrees`, `/api/trunk` and `/api/audit` all answer 403, and `/api/health` omits the home path |
+| `guest` | their own; someone else's is read-only and redacted, with **Request handoff** as the only button | nothing: 403 | nothing |
+
+A guest and an operator both see their own terminal's hand-off destinations,
+so they can use the picker on it — but never the reset times behind them,
+which are this machine's usage data. `src/share.mjs` `mayUseCards` and
+`mayUseMachine` are the only place a role is turned into permission.
+
+### TLS
+
+Off unless a certificate pair is configured. Leg never issues one: a
+self-signed pair teaches everyone on the board to click through a warning,
+which is worse than plaintext on a network that is already private. On
+Tailscale, `tailscale cert <machine>.<tailnet>.ts.net` issues a pair browsers
+already trust.
+
+| variable | meaning | read in |
+|----------|---------|---------|
+| `LEG_TLS_CERT` | path to the certificate; wins over `share.json`'s `tls.cert` | `src/share.mjs` `readTls` |
+| `LEG_TLS_KEY` | path to the private key; wins over `share.json`'s `tls.key` | `src/share.mjs` `readTls` |
+
+`leg share on --tls-cert <file> --tls-key <file>` writes the pair into
+`share.json` and reads it once, so a bad pair fails there rather than at the
+next board start. With a pair configured the shared address serves https and
+every link `leg share` prints says `https://`. The companion listener on
+`127.0.0.1` — the one that lets this machine's own browser in without a token
+— stays plain http, because the certificate is for the shared name and
+loopback traffic never leaves the machine. Half a pair, a missing file, an
+unreadable file or an empty one stops the board with exit `3` rather than
+falling back to plaintext. A renewed pair is picked up by `leg down && leg up`.
+
+### The audit trail
+
+`GET /api/audit` (owner only) and Settings → **Audit trail** on the board: one
+list across every terminal and every card, newest first, of the actions a
+person or an agent took — hand-offs, landings, approvals, reassignments,
+kills. It reads the events already on disk and stores nothing new. Query
+parameters: `limit` (default 200, max 1000), `since` (an ISO timestamp), `who`
+(a name), `kind` (`human`, `agent` or `leg`). Every answer carries `scanned`
+— how many terminals, cards and events it read — so an empty trail cannot be
+mistaken for a quiet week.
+
 ## Card-level options
 
 These configure one card, not the whole install (set with `card add` flags

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.10.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

@@ -76,15 +76,15 @@ const PAGES = [
     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/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(' ')}`)
+}