@ucsandman/legcli 0.10.0 → 0.12.0

package/fixtures/live/claude/usage-oauth.json

@@ -0,0 +1,87 @@
+{
+  "agent": "claude",
+  "signal": "usage",
+  "source": "observed-live",
+  "captured_at": "2026-09-17T20:16:00Z",
+  "endpoint": "GET https://api.anthropic.com/api/oauth/usage",
+  "status": 200,
+  "produced_by": "docs/redesign-2026-09-17.md \"What I verified myself before writing\" (2026-09-17 20:16Z, HTTP 200, 23 keys) and the tournament candidate transcript that printed the raw limits[] rows (kind, group, percent, severity, resets_at as ISO, scope{model{id,display_name},surface}, is_active), fetched through src/taps/claude-usage.mjs fetchClaudeUsage",
+  "scrubbed": "no ids, no tokens, no account identifiers: only the limit rows, the two legacy windows and the spend block Leg reads",
+  "verified": [
+    "limits[] holds session 29%, weekly_all 47% and weekly_scoped 63% with scope.model.display_name \"Fable\" and is_active true",
+    "seven_day_opus and seven_day_sonnet are null",
+    "extra_usage.is_enabled false, disabled_reason \"out_of_credits\", monthly_limit 12500 (minor units)",
+    "spend.can_toggle false, can_purchase_credits false",
+    "seven_day_breakdown: Claude Code 100, Chats 0, Cowork 0"
+  ],
+  "payload": {
+    "five_hour": {
+      "utilization": 29,
+      "resets_at": "2026-09-17T20:30:00Z"
+    },
+    "seven_day": {
+      "utilization": 47,
+      "resets_at": "2026-09-23T19:00:00Z"
+    },
+    "seven_day_opus": null,
+    "seven_day_sonnet": null,
+    "limits": [
+      {
+        "kind": "session",
+        "group": "session",
+        "percent": 29,
+        "severity": "normal",
+        "resets_at": "2026-09-17T20:30:00Z",
+        "scope": null,
+        "is_active": false
+      },
+      {
+        "kind": "weekly_all",
+        "group": "weekly",
+        "percent": 47,
+        "severity": "normal",
+        "resets_at": "2026-09-23T19:00:00Z",
+        "scope": null,
+        "is_active": false
+      },
+      {
+        "kind": "weekly_scoped",
+        "group": "weekly",
+        "percent": 63,
+        "severity": "normal",
+        "resets_at": "2026-09-23T19:00:00Z",
+        "scope": {
+          "model": {
+            "id": null,
+            "display_name": "Fable"
+          },
+          "surface": null
+        },
+        "is_active": true
+      }
+    ],
+    "seven_day_breakdown": [
+      {
+        "name": "Claude Code",
+        "percentage": 100
+      },
+      {
+        "name": "Chats",
+        "percentage": 0
+      },
+      {
+        "name": "Cowork",
+        "percentage": 0
+      }
+    ],
+    "extra_usage": {
+      "is_enabled": false,
+      "disabled_reason": "out_of_credits",
+      "monthly_limit": 12500
+    },
+    "spend": {
+      "can_toggle": false,
+      "can_purchase_credits": false
+    }
+  }
+}

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": 830,
   "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.12.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",
@@ -67,6 +67,7 @@
     "@eslint/js": "^9",
     "eslint": "^9",
     "globals": "^16",
-    "marked": "^18.0.13"
+    "marked": "^18.0.13",
+    "playwright": "^1.63.0"
   }
 }

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/scripts/seed-fake-cards.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 // seed-fake-cards — fills a LEG_HOME with N backlog cards (fake chain, build
 // pipeline) through the same path the CLI uses (src/cards.mjs createCard), for
-// perf tests and manual board load-testing.
-//   node scripts/seed-fake-cards.mjs --home <dir> --repo <git repo path> --count 50
+// perf tests and manual board load-testing. --finished and --live add a
+// realistic mix of finished and live cards, driven through humanAction
+// (src/orchestrator.mjs) rather than by hand-editing card.json.
+//   node scripts/seed-fake-cards.mjs --home <dir> --repo <git repo path> --count 50 --finished 10 --live 3
 import { resolve } from 'node:path'
 
 function parseArgs(argv) {
@@ -15,21 +17,72 @@ function parseArgs(argv) {
 }
 
 const args = parseArgs(process.argv.slice(2))
-if (!args.home) { process.stderr.write('usage: seed-fake-cards.mjs --home <dir> --repo <git repo path> [--count 50]\n'); process.exit(2) }
-if (!args.repo) { process.stderr.write('usage: seed-fake-cards.mjs --home <dir> --repo <git repo path> [--count 50]\n'); process.exit(2) }
+if (!args.home) { process.stderr.write('usage: seed-fake-cards.mjs --home <dir> --repo <git repo path> [--count 50] [--finished 0] [--live 0]\n'); process.exit(2) }
+if (!args.repo) { process.stderr.write('usage: seed-fake-cards.mjs --home <dir> --repo <git repo path> [--count 50] [--finished 0] [--live 0]\n'); process.exit(2) }
 const count = parseInt(args.count ?? '50', 10) || 50
+const finishedCount = parseInt(args.finished ?? '0', 10) || 0
+const liveCount = parseInt(args.live ?? '0', 10) || 0
 
 // LEG_HOME must be set before store.mjs (and the ledger.mjs it imports) load.
 process.env.LEG_HOME = resolve(args.home)
 process.env.BATON_HOME = process.env.LEG_HOME
 const { createCard } = await import('../src/cards.mjs')
+const { humanAction } = await import('../src/orchestrator.mjs')
 
 const TITLES = ['Add retry to fetch', 'Fix flaky lease test', 'Refactor log tail', 'Wire up SSE health', 'Trim README', 'Bump adapter timeout', 'Dedupe blocked events', 'Guard null station', 'Speed up card list', 'Polish error copy']
+const actor = { type: 'human', id: 'seed' }
 
 let created = 0
 for (let i = 0; i < count; i++) {
   const title = `${TITLES[i % TITLES.length]} #${i + 1}`
-  await createCard({ repo: args.repo, task: title, title, chain: 'fake' }, { type: 'human', id: 'seed' })
+  await createCard({ repo: args.repo, task: title, title, chain: 'fake' }, actor)
   created += 1
 }
-process.stdout.write(`seeded ${created} card(s) into ${process.env.BATON_HOME}\n`)
+
+// Finished cards: queue, start, then drive a leg_result straight to done or
+// failed. `chain: 'fake'` has no fallback, so a `failed` outcome exhausts the
+// chain immediately (src/chain.mjs leg_result) instead of handing off.
+let done = 0
+let failed = 0
+for (let i = 0; i < finishedCount; i++) {
+  const wantDone = i % 2 === 0
+  const title = `Seeded finished card #${i + 1}`
+  const card = await createCard({ repo: args.repo, task: title, title, chain: 'fake', queue: true }, actor)
+  humanAction(card.card_id, 'start', {}, actor)
+  humanAction(card.card_id, 'leg_result', { outcome: wantDone ? 'completed' : 'failed', adapter: 'fake' }, actor)
+  if (wantDone) done += 1
+  else failed += 1
+}
+
+// Live cards: cycle through queued, running, needs_approval and paused, each
+// reached through the same transitions a real run takes. `fake=sleep` keeps a
+// running (or queued, on a board that is actually driving its scheduler) card
+// from finishing out from under the board the moment it is looked at.
+const LIVE_KINDS = ['queued', 'running', 'needs_approval', 'paused']
+const liveSeeded = { queued: 0, running: 0, needs_approval: 0, paused: 0 }
+for (let i = 0; i < liveCount; i++) {
+  const kind = LIVE_KINDS[i % LIVE_KINDS.length]
+  const title = `Seeded live card #${i + 1}`
+  if (kind === 'needs_approval') {
+    // a second, approval-gated leg to hand off into
+    const card = await createCard({ repo: args.repo, task: title, title, chain: 'fake-claude,fake-codex', approve: 'fake-codex', queue: true }, actor)
+    humanAction(card.card_id, 'start', {}, actor)
+    humanAction(card.card_id, 'leg_result', { outcome: 'incomplete', adapter: 'fake-claude' }, actor)
+    humanAction(card.card_id, 'bundle_written', {}, actor)
+  } else {
+    const card = await createCard({ repo: args.repo, task: title, title, chain: 'fake', fake_mode: 'fake=sleep', queue: true }, actor)
+    if (kind === 'running' || kind === 'paused') humanAction(card.card_id, 'start', {}, actor)
+    if (kind === 'paused') humanAction(card.card_id, 'pause', {}, actor)
+  }
+  liveSeeded[kind] += 1
+}
+
+// test/perf.test.mjs matches "seeded N card(s)" as a substring, so the
+// original --count-only sentence stays intact; the finished/live counts are
+// appended rather than folded into it.
+const liveSummary = LIVE_KINDS.map((k) => `${liveSeeded[k]} ${k}`).join(', ')
+const extra = []
+if (finishedCount) extra.push(`${finishedCount} finished (${done} done, ${failed} failed)`)
+if (liveCount) extra.push(`${liveCount} live (${liveSummary})`)
+const suffix = extra.length ? `, ${extra.join(', ')}` : ''
+process.stdout.write(`seeded ${created} card(s)${suffix} into ${process.env.BATON_HOME}\n`)

package/scripts/seed-wes-board.mjs

@@ -17,7 +17,7 @@ import { tmpdir } from 'node:os'
 // a throwaway home under the OS temp dir, so nothing is written into the repo
 process.env.LEG_HOME ||= process.env.BATON_HOME || join(tmpdir(), 'leg-seed-board')
 process.env.BATON_HOME ||= process.env.LEG_HOME
-const { createSession, updateSession } = await import('../src/sessions.mjs')
+const { createSession, updateSession, HANDOFF_ORDER_CAPABILITY } = await import('../src/sessions.mjs')
 const { recordUsage, markLimited } = await import('../src/usage.mjs')
 const { spawn } = await import('node:child_process')
 const { writeFileSync } = await import('node:fs')
@@ -37,28 +37,40 @@ const min = 60_000, hour = 60 * min
 const ago = (ms) => new Date(Date.now() - ms).toISOString()
 const B = String.fromCharCode(92)          // one backslash, unmangled by any shell
 const w = (...parts) => parts.join(B)
-const P = (...rest) => w('C:', 'Projects', ...rest)
+// 'Projects-seed', not 'Projects': these rows print like real repos, but a
+// button on a seeded row (End as a card, Land) runs git against the path it
+// names. On 2026-09-17 a seeded End-as-card cut a worktree and wrote a bundle
+// into the real recruiting-tool repository on this machine. A path that
+// does not exist 409s instead.
+const P = (...rest) => w('C:', 'Projects-seed', ...rest)
 // the shape that matters is LENGTH: a real worktree path under a temp dir runs
 // past 90 characters, which is what buried the prompt in the rejected design
 const LONG = w('C:', 'Users', 'operator', 'AppData', 'Local', 'Temp', 'agent',
   'C--Projects-baton--baton-worktrees-s-20260915-000000-claude-0000',
   '00000000-0000-0000-0000-000000000000')
 
+// `model` is the alias the leg resolved to, `waiting` is the Notification shape
+// (a human is being waited on), `dirty` and `ahead` are what the git poll
+// writes. One live row carries a permission prompt and another an idle prompt,
+// because the board's whole attention story is those two rows; one live row
+// carries no model at all, so the register's agent-alone path is on screen too.
 const rows = [
   { id: 's-20260915-0049-claude-2fbf', agent: 'claude', status: 'warning', started: 4 * hour + 24 * min,
-    cwd: P('baton'), repo: P('baton'), branch: 'main',
+    cwd: P('baton'), repo: P('baton'), branch: 'main', model: 'fable', dirty: 3, ahead: 2,
+    waiting: { type: 'permission_prompt', message: 'Bash(git push origin HEAD)', since: ago(40_000) },
     task: 'ultracode run a tournament of ideas to drastically redesign and improve the UI for this project. I do not like the current setup.' },
-  { id: 's-20260915-0213-claude-95d3', agent: 'claude', status: 'running', started: 2 * hour + 46 * min,
-    cwd: w('C:', 'documents'), repo: null, branch: null, task: null },
+  { id: 's-20260915-0213-claude-95d3', agent: 'claude', status: 'running', started: 2 * hour + 46 * min, quiet: 4 * min,
+    cwd: w('C:', 'documents'), repo: null, branch: null, model: 'sonnet', task: null },
   { id: 's-20260915-0257-claude-88e8', agent: 'claude', status: 'warning', started: 2 * hour + 2 * min,
-    cwd: P('recruiting-tool'), repo: P('recruiting-tool'), branch: 'main',
+    cwd: P('recruiting-tool'), repo: P('recruiting-tool'), branch: 'main', model: 'opus', dirty: 1,
+    waiting: { type: 'idle_prompt', message: 'Claude is waiting for your input', since: ago(11 * min) },
     task: `<image name=screenshot.png path=${w('C:', 'Users', 'operator', 'Desktop', 'shot.png')}> [Image #1] sourcing candidates is a huge pain for my friend who recruits on LinkedIn, how can we help` },
   { id: 's-20260915-0455-claude-8e8a', agent: 'claude', status: 'running', started: 5 * min,
     cwd: w('C:', 'Projects'), repo: null, branch: null, task: '/handoff-load verifier-reach-contracts' },
   { id: 's-20260914-2211-claude-4c10', agent: 'claude', status: 'lost', started: 6 * hour, ended: 3 * hour,
-    cwd: w(LONG, 'discovery-loop'), repo: P('discovery-loop'), branch: 'main', task: 'run the nightly discovery loop' },
+    cwd: w(LONG, 'discovery-loop'), repo: P('discovery-loop'), branch: 'main', model: 'fable', task: 'run the nightly discovery loop' },
   { id: 's-20260914-2010-codex-7b31', agent: 'codex', status: 'lost', started: 7 * hour, ended: 4 * hour,
-    cwd: w(LONG, 'costclaw'), repo: P('costclaw'), branch: 'main', task: 'fix the per-model price table for Opus' },
+    cwd: w(LONG, 'costclaw'), repo: P('costclaw'), branch: 'main', model: 'gpt-5.6-sol', task: 'fix the per-model price table for Opus' },
   { id: 's-20260914-1802-agy-d9f2', agent: 'agy', status: 'lost', started: 9 * hour, ended: 6 * hour,
     cwd: w('C:', 'Projects'), repo: null, branch: null, task: 'summarise yesterday' },
   { id: 's-20260914-1533-claude-a04b', agent: 'claude', status: 'ended', started: 11 * hour, ended: 8 * hour,
@@ -67,22 +79,79 @@ const rows = [
     cwd: P('costclaw'), repo: P('costclaw'), branch: 'main', task: 'monthly rollup excludes refunded calls' },
 ]
 
+// distinct from files_touched below: the board prints basenames, and two
+// different paths ending in the same name read as one file listed twice
+const DIRTY = ['server.mjs', 'attach.mjs', 'usage.mjs']
+// The ladder a terminal started with (docs/redesign-2026-09-17.md B.3): the
+// claude models first, because a same-login switch keeps the conversation, then
+// the other CLIs. Written onto the record the way src/attach.mjs writes it, so
+// the picker, the per-terminal ladder editor and `Back to fable` all have the
+// shape they render from. `orderFromLadder` of this list is the default order,
+// which is what `ladderFor` insists on.
+const SEED_LADDER = [
+  { agent: 'claude', account: 'default', model: 'fable', when: 'always', cost: 'plan' },
+  { agent: 'claude', account: 'default', model: 'opus', when: 'always', cost: 'plan' },
+  { agent: 'claude', account: 'default', model: 'sonnet', when: 'always', cost: 'plan' },
+  { agent: 'codex', account: 'default', model: null, when: 'always', cost: 'plan' },
+  { agent: 'agy', account: 'default', model: null, when: 'walled-only', cost: 'free' },
+]
 for (const r of rows) {
-  createSession({ id: r.id, agent: r.agent, cwd: r.cwd, repo: r.repo, branch: r.branch, argv: [r.agent], runner_pid: r.ended ? 1 : livePid() })
+  createSession({
+    id: r.id, agent: r.agent, cwd: r.cwd, repo: r.repo, branch: r.branch, argv: [r.agent],
+    runner_pid: r.ended ? 1 : livePid(), model: r.model ?? null,
+    // what a terminal started by this Leg carries: without it the board offers
+    // the ladder editor read-only and the model rail stays text
+    runtimeCapabilities: r.ended ? [] : [HANDOFF_ORDER_CAPABILITY],
+    // which CLIs were on the PATH when this terminal started. Without it the
+    // server cannot say which rung is eligible and the row prints the caveat
+    // for an older record instead of a destination.
+    installed: r.ended ? null : { claude: true, codex: true, agy: true, grok: false },
+  })
   updateSession(r.id, {
+    ...(r.ended ? {} : { handoff_ladder: SEED_LADDER.map((x) => ({ ...x })) }),
+    // the claude conversation id: a downshift on the same login resumes it,
+    // which is the only reason a picker row can say it keeps the conversation
+    ...(r.ended || r.agent !== 'claude' ? {} : { agent_session_id: `conv-${r.id.slice(-4)}` }),
     status: r.status,
     started_at: ago(r.started),
-    last_activity: ago(r.ended ?? 0),
+    last_activity: ago(r.ended ?? r.quiet ?? 0),
     ended_at: r.ended ? ago(r.ended) : null,
     task: r.task,
     turns: r.task ? 12 : 0,
+    waiting: r.waiting ?? null,
+    // `ahead` is written by the git poll in src/attach.mjs; an older record has
+    // no such key, and the row prints the token only when it is there
+    ...(r.ahead ? { ahead: r.ahead } : {}),
+    files_dirty: r.dirty && r.repo ? DIRTY.slice(0, r.dirty).map((f) => w(r.cwd, 'src', f)) : [],
     files_touched: r.repo ? [w(r.cwd, 'src', 'board', 'board.css'), w(r.cwd, 'src', 'board', 'sessions.js')] : [],
   })
 }
 
+// The two windows are what an older Leg record carries; `buckets` is what the
+// live `limits[]` array carries, and the shape here is the one verified off
+// the endpoint on 2026-09-17: a session bucket, an account-wide weekly, and a
+// model-scoped weekly the endpoint itself marks active. The board prints the
+// active one, which is the whole point: 95% is the login, 63% is what will
+// actually stop the work.
+const fiveHourReset = Math.floor((Date.now() + 3 * hour) / 1000)
+const weekReset = Math.floor((Date.now() + 40 * hour) / 1000)
 recordUsage('claude', 'default',
-  { five_hour: { pct: 38, resets_at: Math.floor((Date.now() + 3 * hour) / 1000) },
-    seven_day: { pct: 95, resets_at: Math.floor((Date.now() + 40 * hour) / 1000) } },
+  { five_hour: { pct: 38, resets_at: fiveHourReset },
+    seven_day: { pct: 95, resets_at: weekReset },
+    buckets: [
+      { kind: 'session', group: 'session', model: null, percent: 38, resets_at: fiveHourReset, is_active: false, severity: 'normal' },
+      { kind: 'weekly_all', group: 'weekly', model: null, percent: 95, resets_at: weekReset, is_active: false, severity: 'normal' },
+      { kind: 'weekly_scoped', group: 'weekly', model: 'fable', percent: 63, resets_at: weekReset, is_active: true, severity: 'normal' },
+      // a second model family with a reading of its own. The live payload on
+      // 2026-09-17 had `seven_day_opus` null, so this is the shape the endpoint
+      // publishes once opus has been used, not a figure anyone measured; it is
+      // here because the model rail and the per-model capacity phrase have
+      // nothing to draw with one bucket.
+      { kind: 'weekly_scoped', group: 'weekly', model: 'opus', percent: 12, resets_at: weekReset, is_active: false, severity: 'normal' },
+    ],
+    // the live payload on 2026-09-17: credits are off and cannot be turned on
+    // from the API, which is what the ladder editor says under may_spend
+    extra_usage: { enabled: false, reason: 'out_of_credits', can_toggle: false, limit_minor: 12500, used_minor: 0 } },
   'statusline', { observed_at: ago(2 * hour + 13 * min) })
 markLimited('codex', 'default', { resets_at: Math.floor((Date.now() + 29 * hour) / 1000), reason: 'limit', source: 'hook' })
 // agy publishes no usage figure, ever. Left unwritten on purpose.

package/src/accounts.mjs

@@ -43,7 +43,12 @@ 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
+// A name is a directory segment, never a path: it is joined into the CLI's
+// config dir and into the usage record's file name. Exported so the one rule
+// has one owner (src/preferences.mjs validates a rung's account with it, and
+// src/usage.mjs refuses to write a record under anything else).
+export const ACCOUNT_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,29}$/i
+const NAME_RE = ACCOUNT_NAME_RE
 
 export function readAccounts() {
   const base = { claude: ['default'], codex: ['default'], agy: ['default'], grok: ['default'] }

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(' ')}`)
+}