@ucsandman/legcli 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.11.0 (2026-09-17)
+
+- **grok is a card adapter, not just a terminal.** `--chain grok` works. Its
+  flags were read from `grok --help` on grok 1.0.34 (`3736acbc8658`) and its
+  result envelope out of the shipped binary, both on 2026-09-17, replacing the
+  guessed field names the unregistered adapter carried. The prompt now travels
+  by `--prompt-file` (a hand-off prompt carries the whole bundle summary, and
+  Windows caps a command line near 32k) and `--cwd` is passed explicitly,
+  because grok can run against a shared leader process and a leg must edit its
+  own worktree. The probe reached the account and came back with a real wall.
+- **A grok terminal at the wall now hands off.** An exhausted Grok Build
+  account answers `402 Payment Required: Grok Build usage balance exhausted`,
+  and none of the rate-limit strings the tap looked for appear in it. The
+  terminal sat on a dead login instead of moving on. Both the tap
+  (`src/taps/grok.mjs`) and the leg classifier (a new observed-live fixture)
+  now read it as a limit. Found by running the probe against an exhausted
+  account on 2026-09-17.
+- **Any CLI can be a card agent, from a JSON spec and no code.** `leg adapter
+  template --name muse > muse.json`, `leg adapter add muse.json`, then
+  `--chain muse,claude`. `leg adapter check muse` prints the exact command line
+  a leg would run before one does; `leg adapter list|show|rm` are the rest.
+  Placeholders (`{{prompt}}`, `{{promptFile}}`, `{{cwd}}`, `{{mode}}`,
+  `{{model}}`, `{{resume}}`, `{{maxTurns}}`, `{{runDir}}`) fill the argv, and a
+  group in the args is dropped whole when a placeholder inside it is unset, so
+  an absent model never leaves a bare `--model`. The flags that turn a
+  supervised agent into an unsupervised one are refused whatever a spec says.
+  A broken spec is reported by name and reason, never thrown, so one typo
+  cannot stop the board. See [docs/adapters.md](docs/adapters.md#custom-adapters).
+- **Hand off now can name its destination.** The button still takes the next
+  option in the order; Details → **Hand off now to** lists every destination
+  with the reason a greyed one cannot be picked, and `leg sessions handoff
+  <id> --to codex` is the same choice from a terminal. A destination that is
+  not on the chain, not installed, or at its wall is refused at the click with
+  the reset time. If the one you picked walls between the click and the
+  hand-off, the work continues down the order and the terminal says which
+  agent took it instead, rather than going somewhere else in silence.
+- **TLS for a shared board.** `leg share on --tls-cert <file> --tls-key <file>`,
+  or `LEG_TLS_CERT` / `LEG_TLS_KEY`. Leg issues no certificate: a self-signed
+  pair teaches everyone to click through a warning, which is worse than
+  plaintext on a network that is already private, so it takes a pair you have
+  (`tailscale cert <machine>.<tailnet>.ts.net` is one command). Half a pair, a
+  missing file or an empty one stops the board with exit 3 rather than quietly
+  serving plaintext. The loopback companion stays http, because the certificate
+  is for the shared name and that traffic never leaves the machine.
+- **An `operator` role, between owner and guest.** An operator runs the
+  pipeline board — adds, runs, approves, reassigns and kills cards — and their
+  own terminals, and sees nothing that describes this machine: no settings, no
+  home path, no repository paths, no conversation index, no audit. `leg share
+  add dana --role operator`. What each role may reach is decided in one place
+  (`mayUseCards` / `mayUseMachine` in `src/share.mjs`) instead of per endpoint.
+- **An audit trail: who did what, across every terminal and every card.**
+  Settings → **Audit trail** on the board, `GET /api/audit` for a script, owner
+  only. Hand-offs, landings, approvals, reassignments and kills, newest first,
+  each with the person or agent that did it. It reads what the ledger already
+  recorded and stores nothing new, and every answer carries how much it read
+  (`14 terminals and 3 cards, 812 events read`) so an empty trail cannot be
+  mistaken for a quiet week.
+- **Fixed: a guest's own terminal leaked the owner's reset times.** The new
+  hand-off destination list carried the exact reset timestamp of every
+  account, and a guest owns their own terminal, so it reached them through it.
+  A guest and an operator now get the destinations and the coarse reason
+  (`at its usage limit`) without the timestamp. Caught by the share-security
+  suite in the same change.
+- **Fixed: the board slowed down as soon as a custom adapter existed.**
+  `/api/health` asks every adapter where its binary is, and reading the spec
+  directory on each of those calls put a readdir, a read and a JSON parse per
+  spec on the event loop the terminals lane is pushed from. The parsed list is
+  now cached against the directory's entries with a one-second floor, so a
+  spec added or removed is still seen at once.
+
 ## 0.10.0 (2026-09-17)
 
 - **The board is responsive again, `leg` starts straight away, and the board

package/README.md

@@ -275,12 +275,21 @@ token at all.
 
 ```
 leg share on              your own link, printed once
-leg share add sam         sam's link, printed once
+leg share add sam         sam's link, printed once (a guest)
+leg share add dana --role operator    dana runs cards, not this machine
 leg share                 who is on the board (never a token again)
 leg share rotate sam      sam's old link stops working
 leg share off             back to 127.0.0.1; every link stops working
 ```
 
+There are three roles. **owner** is everything: the machine's settings, the
+harness, every terminal, the cards, the history index and the audit trail.
+**operator** is the pipeline board and their own terminals: they add, run,
+approve, reassign and kill cards, and they never see this machine's settings,
+its home path, its repository paths, its conversation index or the audit.
+**guest** is the terminals lane, read-only and redacted, with **Request
+handoff** as their only button.
+
 A token is kept as a sha256 hash, so a lost link is re-issued, never re-read.
 The board takes the token out of the address bar and keeps it in the browser.
 Your own browser on this machine needs no token.
@@ -301,12 +310,42 @@ The security pass that goes with it: every `/api` route needs a token, the
 event stream included; twenty wrong tokens from one address and that address
 waits a minute; one identity gets 600 requests a minute; a guest gets 403 on
 everything that is not theirs; and the tests send a bad and a missing token to
-every route. There is still no TLS, so keep this on Tailscale or a network you
-trust. Verified live on 2026-09-11: two terminals on one machine, one wes's and
+every route. Verified live on 2026-09-11: two terminals on one machine, one wes's and
 one sam's; sam's board showed wes's card with the prompt hidden and only
 **Request handoff**, and sam's request reached wes's board (`~/.leg/board.log`:
 "hand-off requested … by sam").
 
+### TLS
+
+Off unless you hand it a certificate. Leg does not issue 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 the pair is
+one command:
+
+```
+tailscale cert <machine>.<tailnet>.ts.net
+leg share on --tls-cert <machine>.<tailnet>.ts.net.crt --tls-key <machine>.<tailnet>.ts.net.key
+```
+
+`LEG_TLS_CERT` and `LEG_TLS_KEY` do the same without writing the paths into
+`share.json`, and they win over it. With a pair configured the shared address
+serves https and every printed link says `https://`; the companion listener on
+`127.0.0.1`, which exists so this machine's own browser needs no token, stays
+plain http, because the certificate is for the shared name and loopback traffic
+never leaves the machine. A pair that is half-configured, missing, unreadable
+or empty stops the board with exit 3 rather than quietly serving plaintext.
+Renew the pair, then `leg down && leg up` to pick it up.
+
+### Who did what
+
+Settings → **Audit trail** is one list across every terminal and every card,
+newest first: hand-offs, landings, approvals, reassignments, kills, each with
+the person or agent that did it, the repo and the time. Filter by person or by
+kind. It reads what the ledger already recorded, so nothing new is stored, and
+it prints how much it read beside the answer (`14 terminals and 3 cards, 812
+events read`) so an empty trail cannot be mistaken for a quiet week. Owner
+only: the trail names repositories and people.
+
 ## The board
 
 `leg <agent>` opens it; `leg open` reopens it; `leg down` stops it.
@@ -337,6 +376,13 @@ one sam's; sam's board showed wes's card with the prompt hidden and only
 - **Buttons**, in a fixed order that never reflows: Land, Hand off now,
   Details, End. Once a session has ended, Remove and Remove record take End's
   place. Details opens an expansion in flow under the panel.
+  **Hand off now** takes the next option in the order. To name the destination
+  instead, open Details and use **Hand off now to**, which lists every
+  destination with the reason a greyed one cannot be picked (`at its usage
+  limit, back 11:40`, `not installed on this machine`). `leg sessions handoff
+  <id> --to codex` is the same choice from a terminal. If the destination you
+  picked walls between the click and the hand-off, the work still continues
+  down the order and the terminal says which one took it instead.
 - Below it, **Conversations**: every coding-agent conversation on this machine
   as a count that opens, the ones Leg started and the ones Claude Code, Codex,
   Grok, Antigravity and Copilot keep in their own stores. Filter by agent,
@@ -460,6 +506,7 @@ leg claude|codex|agy|grok [agent args…] the interactive agent, board alongside
 leg sessions ls [--json]             every session and its usage
 leg sessions show|events <id>
 leg sessions handoff|end <id>        same as the board buttons
+leg sessions handoff <id> --to <agent>[/<account>]   hand off to a destination you name
 leg sessions rm <id>                 forget an ended session
 leg sessions simulate-limit <id>     the real limit path without a real wall (claude, agy, grok)
 leg history [ls] [--provider p] [--repo r] [--search q] [--managed|--external] [--live] [--all] [--json]
@@ -474,9 +521,12 @@ leg harness sync [--to codex,agy] [--force] [--dry-run] | diff <client> | doctor
 leg harness capture [claude|codex] | source <client> | policy <mode> | disable
 leg license                          the license on this machine, or where to buy one
 leg license activate <key> | deactivate | refresh   (refresh renews a Team key)
+leg adapter list|show <n>|check <n>  every adapter, built-in and custom
+leg adapter template [--name n]      a starter spec to fill in
+leg adapter add <file.json> | rm <n> any CLI as a card agent, from JSON
 leg share                            who is on the board (off by default; Team plan)
-leg share on [--bind tailscale|lan|<addr>] [--port N] | off
-leg share add|rotate|rm <name>       one link per human, printed once
+leg share on [--bind tailscale|lan|<addr>] [--port N] [--tls-cert <f> --tls-key <f>] | off
+leg share add|rotate|rm <name> [--role owner|operator|guest]   one link per human, printed once
 leg open | down | status             the board
 leg uninstall [--yes]
 ```
@@ -488,8 +538,10 @@ open the browser), `LEG_USAGE_POLL_MS` (60000), `LEG_CLAUDE_ARGS` /
 `LEG_CODEX_ARGS` / `LEG_AGY_ARGS` / `LEG_GROK_ARGS` (extra args for a leg Leg starts after
 a hand-off, e.g. `-m gpt-5.3-codex-spark`), `LEG_CLAUDE_BIN`,
 `LEG_CODEX_BIN`, `LEG_AGY_BIN`, `LEG_GROK_BIN`, `LEG_CHB_BIN`, `LEG_PERSON` (whose
-terminal this is when the board is shared), `LEG_RATE_MAX` (600 requests a
-minute per human) and `LEG_RATE_MAX_FAILURES` (20 wrong tokens per address).
+terminal this is when the board is shared), `LEG_TLS_CERT` / `LEG_TLS_KEY`
+(serve the shared board over https; they win over `share.json`),
+`LEG_RATE_MAX` (600 requests a minute per human) and `LEG_RATE_MAX_FAILURES`
+(20 wrong tokens per address).
 
 ## Background tasks: the v0.1 extras
 
@@ -514,8 +566,17 @@ under Advanced options.
 - Adapters spawn the CLIs headless as argv, never through a shell, with their
   own permission modes and never a bypass flag: `claude -p --output-format json
   --permission-mode <m>`, `codex exec --json -s <m> -C <worktree>`,
-  `agy -p --output-format json --mode <m> --add-dir <worktree>`; `fake`,
-  `fake-claude`, `fake-codex`, `fake-agy` for tests and demos.
+  `agy -p --output-format json --mode <m> --add-dir <worktree>`,
+  `grok --prompt-file <f> --output-format json --permission-mode <m> --cwd
+  <worktree>`; `fake`, `fake-claude`, `fake-codex`, `fake-agy` for tests and
+  demos.
+- **Any other CLI** is a card adapter too, from a JSON spec and no code:
+  `leg adapter template --name muse > muse.json`, fill in the command and its
+  flags, `leg adapter add muse.json`, then `--chain muse,claude`. `leg adapter
+  check muse` prints the exact command line a leg would run before one does.
+  See [docs/adapters.md](docs/adapters.md#custom-adapters). A custom adapter
+  runs cards; it is not an interactive `leg <agent>` terminal, because that
+  needs a usage tap and a wall signal, which only the four above expose.
 - A leg that ends on a limit signal, a stall, a crash or exit 0 without
   `.leg/DONE` hands off with a bundle to the next adapter in the same
   worktree; a `land` station rebases, tests and fast-forwards trunk or bounces

package/bin/leg.mjs

@@ -19,14 +19,16 @@ import { createScheduler, schedulerStatus, pidfile, MAX_CONCURRENT } from '../sr
 import { availableActions } from '../src/chain.mjs'
 import { up, down, stopBoard, status, openBoard } from '../src/launcher.mjs'
 import { attach, ensureBoard } from '../src/attach.mjs'
-import { readShare, addPerson, removePerson, rotate as rotateToken, turnOn, turnOff, linkFor, personNamed } from '../src/share.mjs'
+import { readShare, addPerson, removePerson, rotate as rotateToken, turnOn, turnOff, linkFor, personNamed, scheme, tlsConfigured, ROLES } from '../src/share.mjs'
+import { normalizeHandoffOrder } from '../src/preferences.mjs'
 import { SUPERVISED_AGENTS, listSessions, readSession, readEvents as readSessionEvents, requestControl, removeSession, isActive, readLand, sessionDir, appendEvent } from '../src/sessions.mjs'
-import { addAccount, removeAccount, listAccountRows, LAYOUT } from '../src/accounts.mjs'
-import { listUsage, fmtReset } from '../src/usage.mjs'
+import { addAccount, removeAccount, listAccountRows, readAccounts, LAYOUT } from '../src/accounts.mjs'
+import { listUsage, fmtReset, readUsage, isAvailable, candidates } from '../src/usage.mjs'
 import { home } from '../src/store.mjs'
 import { entitlement, allows, describe as describeLicense, activate as activateLicense, deactivate as deactivateLicense, refresh as refreshLicense, licensePath, BUY_URL } from '../src/license.mjs'
 import { resumeVerdict, bodyOf, ago } from '../src/resume.mjs'
 import { harnessCommand } from '../src/harness/cli.mjs'
+import { adapterCommand } from '../src/adapters/cli.mjs'
 import { historyCommand, worktreesCommand } from '../src/history/cli.mjs'
 
 const SRC = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'src')
@@ -159,11 +161,32 @@ async function main() {
       for (const s of list) out(`${s.session_id}  [${s.status}]  ${s.agent}${s.account !== 'default' ? '/' + s.account : ''}  ${s.repo_name ?? s.cwd}${s.branch ? '@' + s.branch : ''}  turns=${s.turns}  ${s.limits ? `5h ${s.limits.five_hour?.pct ?? '-'}% 7d ${s.limits.seven_day?.pct ?? '-'}%` : ''}  ${String(s.task ?? '').slice(0, 50)}`)
       return
     }
-    const id = args._[0] || die(2, `usage: leg sessions ${cmd} <session-id>`)
+    const id = args._[0] || die(2, `usage: leg sessions ${cmd} <session-id>${cmd === 'handoff' ? ' [--to <agent>[/<account>]]' : ''}`)
     const s = readSession(id) || die(3, `session not found: ${id}`)
     if (cmd === 'show') return out(JSON.stringify({ session: s, events: readSessionEvents(id) }, null, 2))
     if (cmd === 'events') { for (const e of readSessionEvents(id)) out(`${e.ts}  ${String(e.type).padEnd(18)}  ${e.summary}`); return }
-    if (cmd === 'handoff') { if (!isActive(s)) die(3, `session ${id} is not active`); requestControl(id, { handoff: true }); return out(`handoff requested for ${id}`) }
+    if (cmd === 'handoff') {
+      if (!isActive(s)) die(3, `session ${id} is not active`)
+      // --to names the destination, the same choice the board's picker makes.
+      // Validated here for the same reason it is validated there: a pick that
+      // is not a destination, is not installed, or is at its wall must be
+      // refused now, not silently turn into "whatever is next".
+      if (typeof args.to === 'string') {
+        const [wantAgent, wantAccount = 'default'] = args.to.split('/')
+        const order = normalizeHandoffOrder(s.handoff_order)
+        const chain = candidates({ agent: s.agent, account: s.account, accounts: readAccounts(), order })
+        const hit = chain.find((c) => c.agent === wantAgent && c.account === wantAccount)
+        const label = `${wantAgent}${wantAccount !== 'default' ? '/' + wantAccount : ''}`
+        if (!hit) die(2, `${label} is not a destination for this terminal (${chain.map((c) => c.agent + (c.account !== 'default' ? '/' + c.account : '')).join(', ') || 'none'})`)
+        if (s.installed && s.installed[wantAgent] === false) die(3, `${label} is not installed on this machine`)
+        const u = readUsage(wantAgent, wantAccount)
+        if (!isAvailable(u)) die(3, `${label} is at its usage limit until ${fmtReset(u.limited_until)}; pick another, or drop --to to take the next option in the order`)
+        requestControl(id, { handoff: true, target: hit })
+        return out(`handoff to ${label} requested for ${id}`)
+      }
+      requestControl(id, { handoff: true })
+      return out(`handoff requested for ${id}`)
+    }
     if (cmd === 'end') { if (!isActive(s)) die(3, `session ${id} is not active`); requestControl(id, { end: true }); return out(`end requested for ${id}`) }
     if (cmd === 'rm') {
       if (isActive(s)) die(3, `session ${id} is still active; end it first`)
@@ -226,7 +249,9 @@ async function main() {
     const showLink = (person, token, s) => {
       out(`${person.name} is on the board (${person.role}). Their link, shown once:`)
       out(`  ${linkFor(s, token)}`)
-      out(person.role === 'owner' ? 'Open it on this machine, or any machine that can reach that address.' : 'They see the terminals lane read-only: no prompts, no file names, no logs, no bundles. They can ask for a hand-off; you approve it on the card.')
+      out(person.role === 'owner' ? 'Open it on this machine, or any machine that can reach that address.'
+        : person.role === 'operator' ? 'They get the pipeline board — cards, the floor, the adapters — and their own terminals. Not this machine’s settings, not its history index, not anyone else’s terminal.'
+        : 'They see the terminals lane read-only: no prompts, no file names, no logs, no bundles. They can ask for a hand-off; you approve it on the card.')
     }
     if (!cmd || cmd === 'ls' || cmd === 'status') {
       if (!share.on || !share.people.length) {
@@ -234,9 +259,12 @@ async function main() {
         out('Turn it on: leg share on            (the Tailscale address; --bind lan, or --bind <address>)')
         return
       }
-      out(`share is on: http://${share.bind}:${share.port} (${share.bind_kind})`)
-      for (const p of share.people) out(`  ${p.name.padEnd(16)} ${p.role.padEnd(6)} added ${String(p.created_at).slice(0, 10)}${p.last_seen ? `  last seen ${String(p.last_seen).slice(0, 16).replace('T', ' ')}` : ''}`)
+      out(`share is on: ${scheme(share)}://${share.bind}:${share.port} (${share.bind_kind})`)
+      for (const p of share.people) out(`  ${p.name.padEnd(16)} ${p.role.padEnd(9)} added ${String(p.created_at).slice(0, 10)}${p.last_seen ? `  last seen ${String(p.last_seen).slice(0, 16).replace('T', ' ')}` : ''}`)
       out('')
+      out(tlsConfigured(share)
+        ? `TLS: certificate ${share.tls?.cert ?? '(from the environment)'}. The board on 127.0.0.1 stays plain http for this machine's own browser.`
+        : 'No TLS: keep this on Tailscale or a network you trust. Add one with leg share on --tls-cert <file> --tls-key <file> (tailscale cert <machine>.<tailnet>.ts.net issues a trusted pair).')
       out('A token is shown once. Lost one? leg share rotate <name>. Everyone out: leg share off')
       return
     }
@@ -246,19 +274,26 @@ async function main() {
       const ent = entitlement()
       if (!allows(ent, 'share')) die(2, ent.ok ? `leg share is part of the Team plan (per seat); this machine has a ${ent.plan} license. ${BUY_URL}` : describeLicense(ent))
       try {
-        const r = await turnOn({ bind: a.bind ?? 'tailscale', port: a.port ? parseInt(a.port, 10) : undefined, owner: a.owner })
+        const r = await turnOn({
+          bind: a.bind ?? 'tailscale', port: a.port ? parseInt(a.port, 10) : undefined, owner: a.owner,
+          tlsCert: typeof a['tls-cert'] === 'string' ? a['tls-cert'] : null,
+          tlsKey: typeof a['tls-key'] === 'string' ? a['tls-key'] : null,
+        })
         await restartBoard()
-        out(`share is on: the board is at http://${r.share.bind}:${r.share.port} (${r.share.bind_kind})`)
+        out(`share is on: the board is at ${scheme(r.share)}://${r.share.bind}:${r.share.port} (${r.share.bind_kind})`)
         if (r.token) showLink(r.owner, r.token, r.share)
-        out('Add someone: leg share add <name>')
-        out('No TLS: keep this on Tailscale or a network you trust. Anyone with a link sees that your terminals exist and how much usage is left.')
+        out('Add someone: leg share add <name> [--role operator|guest]')
+        out(tlsConfigured(r.share)
+          ? `TLS is on, from ${r.share.tls?.cert ?? 'the environment'}. Renew the pair and run leg down && leg up to pick up a new one.`
+          : 'No TLS: keep this on Tailscale or a network you trust. Anyone with a link sees that your terminals exist and how much usage is left. leg share on --tls-cert <file> --tls-key <file> turns it on; tailscale cert <machine>.<tailnet>.ts.net issues a trusted pair.')
       } catch (err) { die(2, err.message) }
       return
     }
     if (cmd === 'add') {
-      const name = args._[0] || die(2, 'usage: leg share add <name> [--role owner|guest]')
+      const name = args._[0] || die(2, `usage: leg share add <name> [--role ${ROLES.join('|')}]`)
       try {
-        const r = addPerson(name, { role: args.role === 'owner' ? 'owner' : 'guest', share })
+        if (args.role !== undefined && !ROLES.includes(String(args.role))) die(2, `bad role "${args.role}" (${ROLES.join('|')})`)
+      const r = addPerson(name, { role: typeof args.role === 'string' ? args.role : 'guest', share })
         showLink(r.person, r.token, r.share)
         if (!r.share.on) out('share is still off: leg share on')
       } catch (err) { die(2, err.message) }
@@ -330,6 +365,12 @@ async function main() {
     const code = await harnessCommand(cmd, args, { out, die })
     process.exit(code)
   }
+  if (group === 'adapter' || group === 'adapters') {
+    // Custom adapters: any CLI as a card agent, from a JSON spec on disk
+    // (src/adapters/custom.mjs). The built-ins need none of this.
+    const code = await adapterCommand(cmd, args, { out, die })
+    process.exit(code)
+  }
   if (group === 'history' || group === 'worktrees') {
     // Every conversation on this machine, Leg's own and the ones the agents'
     // stores hold: a read-only index (src/history/index.mjs). `continue`

package/docs/ERRORS.md

@@ -3,6 +3,59 @@
 What broke, why, and what fixed it. One entry per failure, newest first. A first
 occurrence has to be written down or a repeat is never countable.
 
+## 2026-09-17: a new field on the session view leaked the owner's reset times to a guest, through the guest's own terminal
+
+**Fixed in `src/server.mjs` (`sessionsView` decides `guest` before the map and
+blanks `handoff_targets[].resets_at` for one). Caught by
+`test/share-security.test.mjs`, which was already asserting it.**
+
+The hand-off picker needed each destination's availability, so `handoff_targets`
+went onto every session in `sessionsView` carrying `resets_at`. The obvious
+mental model was "a guest gets `redactSession`, which lists its fields
+explicitly, so a new field is invisible to them". That is only true of someone
+else's terminal. `mine(s)` is true for a guest's **own** terminal, and that path
+spreads the whole object. So a guest's own card carried the exact reset
+timestamp of every account on the machine, including the owner's, which is
+precisely the usage data the share design keeps off a guest's board.
+
+The lesson is about where redaction lives, not about this field. There are two
+paths out of `sessionsView`: `redactSession` (allow-list, safe by default) and
+the `mine(s)` spread (deny-list, unsafe by default). **Any field added to a
+session object is visible to whoever owns that session, and a guest owns one.**
+A field that carries machine-level data has to be blanked where it is built, not
+left to a redactor that never sees it.
+
+What made this cheap: the security suite already asserted the whole guest
+response text contains no reset time, so the leak failed a test in the same run
+that introduced it. The test was written against the property ("a guest board
+carries no reset time"), not against the fields that existed when it was
+written, which is why it still caught a field invented months later.
+
+Two smaller ones from the same change, both worth the line:
+
+- Registering `grok` broke three tests that asserted `unknown adapter "grok"`.
+  A test that encodes "not supported yet" as an assertion becomes a tripwire on
+  the day support lands. Assert the refusal with a name nothing will ever
+  provide (`no-such-agent`), so the test outlives the gap it was describing.
+- `names()` started reading `$LEG_HOME/adapters` from disk, and `/api/health`
+  calls it once for the list and once per adapter. That put a readdir, a read
+  and a JSON parse per spec on the same event loop the terminals lane is pushed
+  from, and `/api/health` went over its 1 s budget in
+  `test/board-responsiveness.test.mjs`. Cached against the directory's entry
+  list with a one-second floor. The board's hot path is `/api/health` plus the
+  sessions view; anything new they call has to be counted, not assumed cheap.
+  (This is the same event-loop failure as the entry below, from the other end.)
+- `test/board-responsiveness.test.mjs` failed the ship twice at 1055 ms and
+  1140 ms against a hard `< 1000 ms`, and passed three times out of three when
+  run alone. An absolute millisecond budget on a four-way-concurrent runner
+  measures the machine, not the code. It now takes an idle baseline in the same
+  process and asserts the busy request is not 20x it, with a 3 s ceiling for the
+  symptom the test is named for. **It was only trusted after being made to
+  fail**: putting the original shape back (no floor, no fingerprint, a 1.2 s
+  blocking view on every watcher event) made it report 4,810 ms and fail both
+  assertions, which is the "four to fourteen seconds" the entry below describes.
+  A perf test that has never been watched failing is a number, not a guard.
+
 ## 2026-09-17: one running terminal saturated the board's event loop, and four separate symptoms came out of it
 
 **Fixed in `src/server.mjs` (watcher filter, stat fingerprint, push floor, cached

package/docs/ROADMAP-v2.md

@@ -1,5 +1,13 @@
 # Roadmap v2: the software factory
 
+**Unreleased (2026-09-17) opened the chain and finished the share story.** grok is
+a registered card adapter; any other CLI becomes one from a JSON spec
+(`leg adapter add`, no code); **Hand off now** can name its destination
+instead of taking the next in the order; `leg share` grew TLS from a
+certificate pair you supply, an `operator` role between owner and guest, and
+an audit trail of who did what across every terminal and every card. That
+closes items 1 and 4 below, and the "hand off now to \<adapter>" picker.
+
 **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,
@@ -33,23 +41,28 @@ 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.
+1. ~~**Multi-human network access**~~ — done. 0.3.0 shipped `leg share`; the
+   unreleased work of 2026-09-17 shipped the three that were left: TLS (`leg share on --tls-cert/--tls-key`,
+   or `LEG_TLS_CERT`/`LEG_TLS_KEY`, from a pair you supply — Leg issues none),
+   the `operator` role between owner and guest, and the audit trail
+   (`/api/audit`, Settings → Audit trail).
 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.
+4. ~~**More adapters**~~ — done. grok is registered (2026-09-17: flags read
+   from `grok --help` on 1.0.34, envelope read from the shipped binary, probe
+   reached the account and returned a real 402 wall that classified `limit`;
+   the success path is still unprobed for want of balance). Anything else,
+   muse included, is a custom adapter: a JSON spec in
+   `$LEG_HOME/adapters/<name>.json`, `leg adapter add`, no code
+   ([adapters.md](adapters.md#custom-adapters)).
 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.
+Also on the list: per-station prompt templates editable from the board, lease
+suggestions from the diff of the previous leg, and a floor view that shows
+lease contention over time. (The "hand off now to \<adapter>" picker landed
+2026-09-17, unreleased: Details → **Hand off now to**, or `leg sessions handoff <id> --to`.)

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):