@ucsandman/legcli 0.7.0 → 0.9.0

package/bin/fake-agent.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // fake-agent — stands in for a coding-agent CLI in tests and the demo. It acts
 // in the process cwd (the card's worktree). FAKE_MODE selects behaviour:
-//   success      write the target file and .baton/DONE, print a result JSON, exit 0
+//   success      write the target file and .leg/DONE, print a result JSON, exit 0
 //   incomplete   write the target file but no DONE marker, exit 0
 //   limit        print the recorded limit text (FAKE_LIMIT_FIXTURE, default
 //                claude-session-limit) to the fixture's stream, exit with its code
@@ -58,8 +58,8 @@ function writeTarget() {
 }
 
 function writeDone(line) {
-  mkdirSync(join(cwd, '.baton'), { recursive: true })
-  writeFileSync(join(cwd, '.baton', 'DONE'), line + '\n')
+  mkdirSync(join(cwd, '.leg'), { recursive: true })
+  writeFileSync(join(cwd, '.leg', 'DONE'), line + '\n')
 }
 
 const prompt = process.stdin.isTTY ? '' : await readStdin()
@@ -68,7 +68,7 @@ if (delay > 0) await sleep(delay)
 if (mode === 'success') {
   writeTarget()
   writeDone(`wrote ${target}`)
-  out({ session_id: 'sess-fake', result: `wrote ${target} and .baton/DONE`, prompt_chars: prompt.length, argv: process.argv.slice(2) })
+  out({ session_id: 'sess-fake', result: `wrote ${target} and .leg/DONE`, prompt_chars: prompt.length, argv: process.argv.slice(2) })
   process.exit(0)
 } else if (mode === 'break-test') {
   // land demo: ship the change together with a failing test

package/bin/leg.mjs

@@ -20,12 +20,13 @@ 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 { AGENTS, listSessions, readSession, readEvents as readSessionEvents, requestControl, removeSession, isActive, readLand, sessionDir, appendEvent } from '../src/sessions.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 { 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'
 
 const SRC = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'src')
 // one source of truth for the version, so the help text cannot drift from the package
@@ -86,9 +87,14 @@ function simulateLimit(s) {
   if (s.agent === 'agy') {
     appendFileSync(join(sessionDir(s.session_id), 'agy.log'), '\nrpc error: code = ResourceExhausted desc = RESOURCE_EXHAUSTED quota (simulated by leg sessions simulate-limit)\n')
     appendEvent(s.session_id, { type: 'status', summary: 'simulated RESOURCE_EXHAUSTED appended to the session log' })
-    return out(`simulated: RESOURCE_EXHAUSTED appended to ${join(sessionDir(s.session_id), 'agy.log')}; the runner reads it within ${process.env.BATON_ATTACH_POLL_MS || 2000} ms and hands off to ${s.chain?.[0]?.agent ?? 'nothing'}`)
+    return out(`simulated: RESOURCE_EXHAUSTED appended to ${join(sessionDir(s.session_id), 'agy.log')}; the runner reads it within ${(process.env.LEG_ATTACH_POLL_MS || process.env.BATON_ATTACH_POLL_MS) || 2000} ms and hands off to ${s.chain?.[0]?.agent ?? 'nothing'}`)
   }
-  die(2, `simulate-limit drives the claude hook path (and the agy log); codex's wall comes from its own rollout file, which Baton never writes. Use "leg sessions handoff ${s.session_id}" to force the switch.`)
+  if (s.agent === 'grok') {
+    appendFileSync(join(sessionDir(s.session_id), 'grok.log'), "\nRate limited (429): You've hit the rate limit for your plan. Try again later. (simulated by leg sessions simulate-limit)\n")
+    appendEvent(s.session_id, { type: 'status', summary: 'simulated rate limit appended to the grok log' })
+    return out(`simulated: rate limit appended to ${join(sessionDir(s.session_id), 'grok.log')}; the runner reads it within ${(process.env.LEG_ATTACH_POLL_MS || process.env.BATON_ATTACH_POLL_MS) || 2000} ms and hands off to ${s.chain?.[0]?.agent ?? 'nothing'}`)
+  }
+  die(2, `simulate-limit drives the claude hook path (and the agy/grok log); codex's wall comes from its own rollout file, which Leg never writes. Use "leg sessions handoff ${s.session_id}" to force the switch.`)
 }
 
 function fmtCard(c) {
@@ -97,36 +103,51 @@ function fmtCard(c) {
   return `${c.card_id}  [${c.status}]  ${c.station}${leg}  leases=${(c.leases?.length ? c.leases : ['**']).join(',')}  ${String(c.title ?? c.task).slice(0, 60)}`
 }
 
-const TERMS = `Terms check (fetched 2026-09-11): Anthropic Consumer Terms forbid sharing account credentials and "bypassing any of our systems or protective measures"; the Anthropic Usage Policy forbids coordinating across multiple accounts to circumvent product guardrails; OpenAI's Terms of Use forbid sharing credentials and "circumvent any rate limits or restrictions". Two paid logins you own are not banned by name, but rotating to a second account of the same vendor because the first is rate-limited is close to that wording. Leg's default chain switches vendors (claude -> codex -> agy); a second account of one vendor is your call.`
+const TERMS = `Terms check (fetched 2026-09-11): Anthropic Consumer Terms forbid sharing account credentials and "bypassing any of our systems or protective measures"; the Anthropic Usage Policy forbids coordinating across multiple accounts to circumvent product guardrails; OpenAI's Terms of Use forbid sharing credentials and "circumvent any rate limits or restrictions". Two paid logins you own are not banned by name, but rotating to a second account of the same vendor because the first is rate-limited is close to that wording. Leg's default chain switches vendors (claude -> codex -> agy -> grok); a second account of one vendor is your call.`
 
 async function main() {
   const [group, cmd, ...rest] = process.argv.slice(2)
   const args = parseArgs(rest)
   if (group === '--version' || group === '-v') return out(VERSION)
   if (group === '🦿' || group === 'prosthetic' || group === 'easter-egg') {
-    out(' 🦿 LegCli — The mechanical relay runner for coding agents.')
-    out(`
-.--------.
-|  ____  |
-| |    | |
-| |____| |
-'--------'
-    ||
- .--||--.
- |  ||  |   knee servo
- '--||--'
-    ||
-    ||
- ___||___
-|________|
-`)
-    out('   Passing the leg to the next runner when limits hit.')
+    const ORANGE = '\x1b[38;5;208m'
+    const RESET = '\x1b[0m'
+    const LEG_ART = [
+      '         ███████',
+      '           ███████',
+      '             ███████',
+      '               ███████',
+      '                 ███████',
+      '                   ███████',
+      '                     ███████',
+      '                       ███████',
+      '                         ███████',
+      '                           ███████',
+      '                              ███████',
+      '                            ███████████',
+      '                           █████████████',
+      `                           ██████(${ORANGE}00${RESET})███  ← knee servo`,
+      '                           █████████████',
+      '                            ███████████',
+      '                              ███████',
+      '                             █████',
+      '                           █████',
+      '                         █████',
+      '                       █████',
+      '                     █████',
+      '                    █████',
+      '            ██████████████████████████',
+      '            ████ ████ ████ ████ ████ ████',
+    ].join('\n')
+    out('🦿 Leg: the mechanical relay runner for coding agents.\n')
+    out(LEG_ART)
+    out('\nPassing the leg to the next runner when limits hit.')
     return
   }
-  if (AGENTS.includes(group)) {
-    // leg claude|codex|agy [agent args...]: everything after the agent name
+  if (SUPERVISED_AGENTS.includes(group)) {
+    // leg claude|codex|agy|grok [agent args...]: everything after the agent name
     // goes straight through.
-    const code = await attach(group, [cmd, ...rest].filter((x) => x !== undefined), { open: process.env.BATON_NO_OPEN !== '1' })
+    const code = await attach(group, [cmd, ...rest].filter((x) => x !== undefined), { open: (process.env.LEG_NO_OPEN || process.env.BATON_NO_OPEN) !== '1' })
     process.exit(code)
   }
   if (group === 'sessions') {
@@ -172,15 +193,15 @@ async function main() {
     const v = resumeVerdict(where)
     if (a.json) { out(JSON.stringify(v, null, 2)); process.exit(v.exit_code) }
     if (v.state === 'missing') {
-      out(`no resume pointer in this checkout (looked for .baton/RESUME.md from ${where} upward).`)
-      out('Baton writes one when a terminal hands off; `baton claude` in this directory starts one.')
+      out(`no resume pointer in this checkout (looked for .leg/RESUME.md from ${where} upward).`)
+      out('Leg writes one when a terminal hands off; `leg claude` in this directory starts one.')
       process.exit(v.exit_code)
     }
     const head = v.head?.now ? `${v.head.now.slice(0, 7)}${v.head.branch ? ` on ${v.head.branch}` : ''}` : 'no commit'
     const line = v.state === 'fresh'
       ? `${v.file} is current: written ${v.written_at ? ago(v.age_ms) : 'at an unrecorded time'}, and the repository is still at ${head}.`
       : v.state === 'unstamped'
-        ? `${v.file} is UNSTAMPED: ${v.reasons[0]}. Baton did not write it, or an older Baton did.`
+        ? `${v.file} is UNSTAMPED: ${v.reasons[0]}. Leg did not write it, or an older version did.`
         : `${v.file} is STALE: ${v.reasons.join('; ')}.`
     if (a.check) {
       out(line)
@@ -280,7 +301,7 @@ async function main() {
         out('')
         out('Log in once (paste in PowerShell):')
         out(`  ${r.login}`)
-        out(`Then: $env:BATON_ACCOUNT='${name}'; baton ${agent}   (or let a limit hand off to it)`)
+        out(`Then: $env:LEG_ACCOUNT='${name}'; leg ${agent}   (or let a limit hand off to it)`)
       } catch (err) { die(2, err.message) }
       return
     }
@@ -302,6 +323,12 @@ async function main() {
     if (cmd === 'terms') return out(TERMS)
     die(2, `unknown accounts command "${cmd}" (ls|add|rm|terms)`)
   }
+  if (group === 'harness') {
+    // The portable harness: the working environment a hand-off carries with
+    // the task. Off until `leg harness enable` (src/harness/index.mjs).
+    const code = await harnessCommand(cmd, args, { out, die })
+    process.exit(code)
+  }
   if (group === 'license') {
     // The paid gate. Keys verify offline against the public key in
     // src/license.mjs; nothing here talks to the network except refresh.
@@ -330,7 +357,7 @@ async function main() {
   }
   if (group === 'uninstall') {
     // Leg never edits ~/.claude or ~/.codex; everything it added lives under
-    // $BATON_HOME (sessions, usage, extra-account dirs, cards).
+    // $LEG_HOME (sessions, usage, extra-account dirs, cards).
     const dir = home()
     if (!args.yes) {
       out(`leg uninstall removes ${dir} (sessions, usage, extra-account dirs, cards, board pidfile) and nothing else.`)
@@ -340,7 +367,7 @@ async function main() {
     for (const r of listAccountRows()) if (r.name !== 'default') removeAccount(r.agent, r.name)
     await down()
     rmSync(dir, { recursive: true, force: true })
-    return out(`removed ${dir}; now: npm rm -g legcli`)
+    return out(`removed ${dir}; now: npm rm -g @ucsandman/legcli`)
   }
   if (group === 'card') {
     if (cmd === 'add') return cardAdd(args)
@@ -427,16 +454,19 @@ async function main() {
     out(openBoard(url) ? `opened ${url}` : `could not open a browser; visit ${url}`)
     return
   }
-  if (group && group !== '--help' && group !== 'help') die(2, `unknown command "${group}" (claude|codex|agy|sessions|resume|accounts|license|share|up|down|status|open|card|scheduler|uninstall)`)
+  if (group && group !== '--help' && group !== 'help') die(2, `unknown command "${group}" (claude|codex|agy|grok|sessions|resume|accounts|harness|license|share|up|down|status|open|card|scheduler|uninstall)`)
   out(`leg ${VERSION}, your coding agents, with a board alongside and a handoff when one hits its limit
-  claude|codex|agy [args...]   the normal interactive agent in this terminal; args pass straight through
-                               the board opens once, the session shows as a card, usage is tracked, a limit hands off
-                               a second live session in one checkout gets its own worktree (--no-worktree to share)
+  claude|codex|agy|grok [args...]   the normal interactive agent in this terminal; args pass straight through
+                                the board opens once, the session shows as a card, usage is tracked, a limit hands off
+                                a second live session in one checkout gets its own worktree (--no-worktree to share)
+                                auto-approve mode (--no-auto-approve to opt out)
   sessions ls|show|events|handoff|end|rm|simulate-limit <id>
   resume [--check] [--json] [--path <dir>]      the hand-off waiting in this checkout, and whether it is still true
                                freshness is recomputed from git at read time; --check prints only the verdict
                                exit 0 current, 1 stale or unstamped, 3 no pointer here
   accounts ls|add <agent> <name>|rm|terms        optional second login for claude or codex
+  harness status|enable|sync|check|explain|...   carry the source agent's rules, hooks, skills, agents, commands and MCP
+                                servers to the agent a hand-off lands on; off until enabled (leg harness help)
   license [status|activate <key>|deactivate|refresh]
                                 personal or team license status and management
   share status|on|add <name>|rotate <name>|rm <name>|off

package/docs/DECISIONS.md

@@ -2,6 +2,24 @@
 
 Durable product and design decisions that the code does not explain on its own. One entry per decision, newest first.
 
+## 2026-09-16: the portable harness is an opt-in subsystem over a vendored, hash-pinned engine
+
+- **What.** `leg harness` carries the source agent's working environment (rules, identity, hooks, skills, subagents, commands, MCP servers, permissions) to the agent a hand-off lands on. The capture, neutral bundle and apply engine is the Agnostic AI port engine (MIT), embedded byte for byte under `src/harness/vendor/agnostic-ai/` and driven through its library entry; Leg owns consent, policy, the client registry, state, the fingerprint, the trail and the hand-off decision (`src/harness/*.mjs`).
+- **Why vendor, and why verbatim.** Leg ships with zero runtime dependencies and no build step, and Agnostic AI is a private-by-default template repo, so a package dependency was not on the table. A copy that is edited locally drifts forever; a copy that is verified against recorded hashes cannot. `scripts/sync-harness-engine.mjs --check` runs in `npm test` and fails on any local edit; a fix lands upstream, then the sync copies it in. Upstream was made embeddable first (`configure({ brand, secretPatterns, shimPath, importRoots })`, injected registry and policy, a library entry), with its own regression proving the boundary, so the vendored files need no patching.
+- **Why CommonJS stays.** Node's ESM loader imports the CommonJS entry directly. Converting upstream to ESM would have rewritten working machinery for style and broken its dynamic adapter loading; keeping the boundary keeps the copy verbatim.
+- **Why off by default, and why a policy.** Leg's promise that it leaves your settings files alone stands for every install that never runs `leg harness enable`. The first run shows what will be written and asks. After that a hand-off lands when nobody is at the keyboard, so the saved policy decides, never a prompt: `warn` reports, `sync` writes what is safe, `strict` refuses what is not and tries the next option, ending the terminal with exit 5 only when none is left. The strict refusal applies to hand-offs, not to the agent the human started.
+- **What a write may do.** Only owned files (`GENERATED by Leg harness` in the head) and marked regions or owned keys inside files the user also owns; a backup before every overwrite; a hand-edited file skipped and named; the source client never written; credentials replaced by `${NAME}` and a bundle that still carries one refused. The same discipline as the folder-trust record, extended.
+- **What stays separate.** Accounts. The harness describes behaviour; the account layer decides which login runs, and a same-agent hand-off to a second login carries no harness.
+- **Registry.** Only the clients Leg launches, plus Gemini CLI because it shares `GEMINI.md` with agy. Grok is reported `unsupported`, never guessed. Upstream's other fifteen targets are not exposed.
+
+## 2026-09-16: @ucsandman/legcli and leg-agents stay on the same version
+
+- **What.** The unscoped `leg-agents` package is an alias installer for `@ucsandman/legcli`. It lives in `packages/leg-agents`, always carries the root version, and pins `@ucsandman/legcli` to that exact version. CI publishes both from `.github/workflows/ci.yml` after the same registry gate.
+- **Why.** `npm i -g leg-agents` is the name agents and muscle memory will type. A hand-kept alias is how the two versions drift, and a drifted alias installs yesterday's CLI.
+- **How drift is refused.** `scripts/sync-leg-agents.mjs --check` is part of `npm test`. The publish gate refuses to ship if the two package.json versions differ, or if the alias pin is not the root version. `npm version` / `npm run sync-alias` writes the alias in the same step as the root bump. The alias tarball is not included in the scoped package (`files` does not list `packages/`).
+- **Windows.** The alias wrapper loads `bin/leg.mjs` through `pathToFileURL`. A bare `import(join(absPath))` is a `c:` URL scheme on Windows and throws `ERR_UNSUPPORTED_ESM_URL_SCHEME`.
+- **First publish.** `leg-agents` is a new npm name. Bind a trusted publisher on npmjs.com for `leg-agents` to `ucsandman/legcli` + `ci.yml` (same as the scoped package) before the first CI publish, or publish the first version once with OTP.
+
 ## 2026-09-15: the board is dark cobalt, and there is no light mode
 
 - **What.** The board ground is a saturated deep cobalt at hue 258, the same hue the marketing site is drenched in, taken to its dark end. Not a neutral near-black: measured in OKLab, `--e0` sits 0.0507 from `#0f1115` at 5.7 times its chroma, so the anti-reference colour `PRODUCT.md` bans is not reachable from this palette.
@@ -22,7 +40,7 @@ Durable product and design decisions that the code does not explain on its own.
 
 ## 2026-09-15: Leg records the folder-trust answer, and never overrides one already given
 
-- **What.** Before starting an agent, Leg writes the folder-trust answer for the repository the user chose by typing `baton <agent>` in it: `hasTrustDialogAccepted` in `~/.claude.json`, `trust_level` in `~/.codex/config.toml`, an entry in `~/.gemini/trustedFolders.json`. `LEG_TRUST=never` turns it off.
+- **What.** Before starting an agent, Leg writes the folder-trust answer for the repository the user chose by typing `leg <agent>` in it: `hasTrustDialogAccepted` in `~/.claude.json`, `trust_level` in `~/.codex/config.toml`, `trustedWorkspaces` in `~/.gemini/antigravity-cli/settings.json` (and `default-cli-project.json` for Gemini project resources). For worktrees, both the repo root and the worktree directory are recorded because Antigravity CLI does an exact string match against `Store.workspacePath`. `LEG_TRUST=never` turns it off.
 - **Why.** The handoff is the product, and it fires when the limit hits, which is usually when nobody is watching. An agent that had never run in that folder stopped on its first-run trust prompt and waited for a keypress that was not coming, so the bundle was written and the terminal sat idle until morning.
 - **Why writing those files is allowed at all.** `stdio: 'inherit'` in `src/attach.mjs` hands the real terminal to the agent, so Leg cannot watch for the prompt and answer it. Pre-seeding is the only mechanism that does not change Leg's architecture. For Claude Code it is also the documented remedy: its permissions guide prescribes exactly this edit.
 - **The three rules that bound it.** Never create a config file that is not already there. Never rewrite a file to say what it already says. Never override an answer already on file: only an absent key is an unanswered question, so a recorded refusal stays a refusal.
@@ -41,7 +59,7 @@ Durable product and design decisions that the code does not explain on its own.
 - **What.** One static HTML page (`site/index.html`, `style.css`, `site.js`), self-hosted fonts, deployed to Vercel from the `site/` directory with `vercel.json` headers. No framework, no build step. PRODUCT.md and DESIGN.md at the repo root carry the brief and the tokens so later edits inherit them.
 - **How it was chosen.** A four-concept tournament (light restrained, drenched racing green, committed cobalt, product-led dark terminal) judged against a written rubric. Committed cobalt won and borrowed the DOM-recreated board from the light concept and the typed full-bleed terminal from the product-led one. The scores and disqualifications are recorded in the session notes; the design tokens are in DESIGN.md.
 - **Why cobalt and not the board's own dark palette.** The operator board and the sibling site declick.dev are both near-black; a third near-black surface from the same author would read as one family and as the generic dark AI-tool page. The site's warmth comes only from the agent colors inside product visuals.
-- **What the page promises.** Every number, path, version and date on it is copied from the README as verified on 2026-09-11. The terminal transcript is a labeled sample session whose `[baton]` lines are the strings `src/attach.mjs` prints and whose pointer prompt is the one `src/bundle.mjs` sends. The two-session cards are from the live run the README documents.
+- **What the page promises.** Every number, path, version and date on it is copied from the README as verified on 2026-09-11. The terminal transcript is a labeled sample session whose `[leg]` lines are the strings `src/attach.mjs` prints and whose pointer prompt is the one `src/bundle.mjs` sends. The two-session cards are from the live run the README documents.
 - **Analytics and search.** Vercel Web Analytics is the only script besides `site.js`; nothing on the page depends on it. Search Console and Bing registration state is recorded below this entry when done.
 
 ### Registration state, 2026-09-11

package/docs/ERRORS.md

@@ -3,6 +3,77 @@
 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-16: a hand-edited `package.json` version left `package-lock.json` behind, and the publish gate refused 0.9.0
+
+**Fixed by bumping the lockfile root version; the gate is `scripts/npm-publish-gate.mjs`.**
+
+The version went from 0.8.1 to 0.9.0 by editing `package.json` directly, so
+the lockfile's two root `version` fields still said 0.8.1 and CI's
+`publish-npm` job stopped at "package.json and package-lock.json root metadata
+do not match". The run before it had failed the same way, which is why npm
+still served 0.8.0. Tests, lint and the docs job were green; only the publish
+was refused, which is the gate doing its job. Lesson: bump with `npm version`
+(it writes the lockfile and runs the alias sync) and run the gate locally
+before pushing a release; a green test matrix says nothing about the publish.
+
+## 2026-09-16: the vendored engine's secret scan covered two fields; the review found the other five
+
+**Fixed upstream (Agnostic AI 7e35b51) and re-vendored; regression in `test/harness-engine.test.mjs`.**
+
+`docs/harness.md` promised "a bundle that still carries a credential is refused
+at save time". The engine's `validate()` scanned `mcp.<n>.env` and
+`mcp.<n>.headers` only; the rules text, identity, hook command lines, MCP
+arguments, URLs and agent bodies were copied verbatim, and the four canary
+tests planted tokens exactly where the scan already looked. The read-only
+security review planted one everywhere else and got one problem back. Root
+cause: a scan written for two map keys, and a test fixture shaped to it. Fix:
+whole-bundle scanning with redaction of free text and drops of unsafe
+handlers or servers, plus `PLANTED` tokens in every place the scan must reach.
+Lesson: a canary proves the place it sits in, nothing else; a fixture written
+by the same hands as the scan finds nothing the scan missed.
+
+## 2026-09-16: `CLAUDE_CONFIG_DIR` outside the OS home was captured from `~/.claude` instead
+
+**Fixed upstream in `sources/claude.cjs` (`pick()`), regression in `test/harness-engine.test.mjs`.**
+
+The engine kept a registry path only when it sat inside the OS home and fell
+back to `~/.claude` otherwise, while Leg's registry, detection and fingerprint
+honoured the override. A per-account config dir under a `LEG_HOME` on another
+drive would have ported the dormant profile and never noticed edits to the
+active one. Fix: the registry path is trusted as given. Lesson: three code
+paths agreeing on a directory is a property to test, not to assume.
+
+## 2026-09-16: `leg harness sync` wrote before `leg harness enable`; the board could widen the policy
+
+**Fixed in `src/harness/cli.mjs` and `src/server.mjs`, regressions in `test/harness-cli.test.mjs` and `test/harness-policy.test.mjs`.**
+
+The consent gate lived in `enable` only, so `sync` on an install that never
+enabled the feature wrote managed files while `status` said off; the settings
+route accepted any policy value, so a board POST could take `warn` to
+`strict`. Both were one-line fixes the review caught. Lesson: a consent rule
+has to be checked at every writer, not at the one verb that grants it.
+
+## 2026-09-16: the backup count was always zero
+
+**Fixed in `src/harness/index.mjs`.**
+
+The engine's writer returns the backup path, but every adapter keeps only the
+action, so counting `f.backup` counted nothing. The count now comes from the
+backups directory before and after an apply. Lesson: a number that never moves
+in a demo is a number nobody is computing.
+
+## 2026-09-16: alias `import(join(windowsPath))` is a `c:` URL scheme
+
+**Fixed in `packages/leg-agents/bin/leg.mjs`.**
+
+The first `leg-agents` wrapper did `await import(join(pkgRoot, 'bin', 'leg.mjs'))`.
+On Windows that string is `C:\…\bin\leg.mjs`, which Node's ESM loader treats as a
+URL with protocol `c:` and throws `ERR_UNSUPPORTED_ESM_URL_SCHEME`. `npm install`
+of the tarball succeeded; `leg --version` died before printing `0.8.0`.
+
+The fix is `await import(pathToFileURL(join(pkgRoot, 'bin', 'leg.mjs')).href)`.
+`require.resolve` returning a path is not a valid ESM specifier on Windows.
+
 ## 2026-09-15: macOS `/var` symlink broke two e2e tests
 
 **Fixed in `test/helpers.mjs`.**

package/docs/README.md

@@ -6,6 +6,7 @@
 - [concepts.md](concepts.md): sessions, accounts, usage windows and the interactive handoff, then cards, stations, chains, outcomes, leases, the land station and the card status state diagram.
 - [board-guide.md](board-guide.md): the instrument head (a row per login, two window rails each, the 85 percent post), the Terminals panels, overlap flags, Landed on main, Background tasks, Settings, and the floor view.
 - [configuration.md](configuration.md): every environment variable, the accounts layout, `.env`, network exposure, card-level options.
+- [harness.md](harness.md): the portable harness, off by default: what moves between agents and what does not, the first run, policies, ownership and backups, secrets, the evidence trail, and how Leg relates to the Agnostic AI engine it embeds.
 - [adapters.md](adapters.md): what Leg reads from each CLI in an interactive session, each adapter's headless argv, modes, forbidden flags, gotchas, and how to add a new one.
 - [faq.md](faq.md): short answers to real questions (the status line, codex's missing hook, agy's missing percentage, second accounts, uninstall, limits, secrets, Windows support).
 
@@ -22,6 +23,7 @@
 | area | modules |
 |------|---------|
 | interactive sessions | `src/attach.mjs` (the `leg <agent>` runner), `src/sessions.mjs` (the session store), `src/usage.mjs` (usage windows and the chooser), `src/accounts.mjs` (extra logins), `src/bundle.mjs` (the per-session bundle), `src/hook.mjs` (what Claude Code's hooks run) |
+| portable harness | `src/harness/index.mjs` (capture, compare, apply, status, the hand-off decision), `src/harness/registry.mjs` (which clients, where their files are), `src/harness/fingerprint.mjs`, `src/harness/cli.mjs` (`leg harness`), `src/harness/vendor/agnostic-ai/` (the engine, verbatim; `scripts/sync-harness-engine.mjs` is the only writer) |
 | taps | `src/taps/claude.mjs`, `src/taps/claude-usage.mjs`, `src/taps/codex.mjs`, `src/taps/agy.mjs` |
 | board | `src/server.mjs`, `src/board/sessions.js` (Terminals lane), `src/board/board.js` and `src/board/floor.js` (pipelines) |
 | pipelines | `src/orchestrator.mjs`, `src/scheduler.mjs`, `src/chain.mjs`, `src/pipeline.mjs`, `src/runner.mjs`, `src/ledger.mjs`, `src/leases.mjs`, `src/mergequeue.mjs`, `src/adapters/*.mjs` |

package/docs/REUSE.md

@@ -229,7 +229,7 @@ station):
   Network off by default: `-c sandbox_workspace_write.network_access=false`.
 - Git workflow: snapshot before a leg, snapshot `--diff-since` after; the
   `worktree` recommendation is Leg's only mode (one worktree per card,
-  branch `baton/<card-id>`); the diff, never prose, is what review and landing
+  branch `leg/<card-id>`); the diff, never prose, is what review and landing
   trust.
 - Failure rules that carry over: exit 11 means a supervisor is already running,
   never relaunch over it; a failed launch is retried once then the chain moves

package/docs/VOCABULARY.md

@@ -51,6 +51,8 @@ Source: the `appendEvent`/`updateSession` call sites in `src/attach.mjs`,
 | `lost` | the runner pid is gone; the session was marked `lost` |
 | `error` | a spawn error, a tap error, a failed bundle checkpoint, or an error the agent reported |
 | `status` | a note that does not fit another type |
+| `harness` | the portable harness was prepared for the leg starting now: the destination's state (`synced`, `partial`, `stale`, `attention`, `unsupported`, `source`, `error`) with what was dropped in the body |
+| `harness_blocked` | the strict harness policy refused the chosen destination; the next option is tried |
 | `worktree` | another live session was in the checkout, so this one got its own worktree: path, branch, base |
 | `land_requested` | Land was pressed: the branch and its base |
 | `land_warning` | the landing ran without a test command |
@@ -58,6 +60,23 @@ Source: the `appendEvent`/`updateSession` call sites in `src/attach.mjs`,
 | `bounced` | the landing stopped with a [bounce reason](#bounce-reasons-land-station); the full detail is in `body` |
 | `land_noop` | Land found nothing on the branch beyond its base |
 
+## Harness states (terminal cards, drawer, `leg harness`)
+
+Source: `STATES` in `src/harness/index.mjs`; recorded on `session.harness.state`.
+
+| state | meaning |
+|-------|---------|
+| `off` | the portable harness is not enabled; nothing recorded |
+| `same-client` | a hand-off to another login of the same client; the harness is shared already |
+| `source` | the destination is the source client; never written |
+| `synced` | every component the destination supports is current, nothing dropped |
+| `partial` | current, some items could not be carried (each with a reason) |
+| `stale` | the destination is behind the source (`warn` policy, or a check) |
+| `attention` | a managed file was hand-edited (backed up, skipped) or a component errored |
+| `unsupported` | no adapter for the destination (Grok), or it is not installed |
+| `blocked` | the strict policy refused the destination |
+| `error` | the preparation failed; the reason is recorded |
+
 ## Land states (terminal cards)
 
 `$LEG_HOME/sessions/<id>/land.json`, written by the board server only
@@ -166,6 +185,8 @@ across `src/chain.mjs`, `src/orchestrator.mjs`, `src/scheduler.mjs`,
 | `failed` | the card failed (chain exhausted, land attempts exhausted, or an environment fault) |
 | `error` | an unexpected error (orchestrator crash, handoff bundle write failure, land station crash) |
 | `status` | a status note that doesn't fit another type (e.g. "rerun from build leg 0") |
+| `harness` | the portable harness was prepared for the adapter about to run; the summary names the state, the body what was dropped |
+| `harness_blocked` | the strict harness policy refused the adapter; the leg fails as `launch_failed` and does not advance |
 
 ## Actor types
 

package/docs/adapters.md

@@ -1,7 +1,7 @@
 # Adapters
 
 Two things per agent: what Leg reads from an interactive session
-(`leg claude|codex|agy`), and the headless argv the v0.1 pipeline spawns.
+(`leg claude|codex|agy|grok`), and the headless argv the v0.1 pipeline spawns.
 Every fact here was written against `src/taps/*.mjs`, `src/attach.mjs` and
 `src/adapters/*.mjs`; the evidence trail, including which lines an artifact
 backs, is [cli-contracts.md](cli-contracts.md).
@@ -120,7 +120,7 @@ documentation say docs-only.
 - **The wall**: `RESOURCE_EXHAUSTED`, "it resets in %s" and "out of quota" in
   the log. Those strings are present in `agy.exe`, and `scanLog()` also reads a
   relative reset out of "resets in \<n>\<s|m|h|d>". Status:
-  **docs-only** <!-- live:agy/agy-resource-exhausted --> —
+  **observed-live 2026-09-16** <!-- live:agy/agy-resource-exhausted --> —
   `RESOURCE_EXHAUSTED (code 429): Individual quota reached … Resets in
   71h19m42s.` appeared in a session's `agy.log` at 08:02:42Z and walled the
   agent. No payload was kept: the capture call in `src/attach.mjs` was added
@@ -133,11 +133,25 @@ documentation say docs-only.
 - **One account only**: agy 1.2.0 has no config-directory override, so
   `leg accounts add agy …` is refused.
 
+### grok
+
+- **How Leg attaches**: `grok <your args>` with `--debug-file <~/.leg/sessions/<id>/grok.log>` passed by Leg (`src/attach.mjs` `spawnSpec`).
+- **Usage percentages**: `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits` and `GET https://cli-chat-proxy.grok.com/v1/user?include=subscription` (`LEG_GROK_BILLING_URL` and `LEG_GROK_USER_URL` override), reading the OAuth token stored in `~/.grok/auth.json`. The billing endpoint reports `creditUsagePercent` and `currentPeriod` (with weekly resets). Polled every 60 s (`LEG_USAGE_POLL_MS`). If the token expires or returns 401, usage is marked unknown without crashing, and re-reads `auth.json` on the next poll.
+- **The wall**: rate limit signals cited directly from `xai-org/grok-build`:
+  - `SamplingError::Api { status: StatusCode::TOO_MANY_REQUESTS }` (`crates/codegen/xai-grok-sampling-types/src/error.rs:304`)
+  - `RATE_LIMITED_ERROR_CODE = -32003` and user messages `RATE_LIMITED_USER_MESSAGE_OAUTH` ("You've hit the rate limit for your plan. Try again later.") and `RATE_LIMITED_USER_MESSAGE_API_KEY` ("You've hit the rate limit for your API key. Try again later.") (`crates/codegen/xai-grok-shell/src/sampling/error.rs:15, 18-21`)
+  - Headline "Rate limited (429)" and "You've hit the rate limit for your plan" (`crates/codegen/xai-grok-pager/src/app/error_display.rs:263-267`)
+  - `StopFailureKind::RateLimit` ("rate_limit") (`crates/codegen/xai-grok-hooks/src/event.rs:306-315`)
+  - Free usage exhausted: `FREE_USAGE_USER_MESSAGE` and `FREE_USAGE_EXHAUSTED_ERROR_CODE` ("subscription:free-usage-exhausted") (`crates/codegen/xai-grok-shell/src/sampling/error.rs:30, 33`)
+  `src/taps/grok.mjs` scans `grok.log` for these exact signals and extracts reset durations when available.
+- **Prompts and session id**: `~/.grok/sessions/<url-encoded-cwd>/prompt_history.jsonl`, recorded per prompt with timestamp, `session_id`, and `prompt`.
+- **Accounts**: Supports `GROK_HOME` override. `leg accounts add grok <name>` creates junctioned directories copying `config.toml`.
+
 ### Resume prompt per agent
 
 After a hand-off the next agent starts in the same terminal with the pointer
 prompt as its first positional argument: `claude "<prompt>"`,
-`codex "<prompt>"`, `agy -i "<prompt>"` (`src/attach.mjs` `spawnSpec`).
+`codex "<prompt>"`, `agy -i "<prompt>"`, `grok "<prompt>"` (`src/attach.mjs` `spawnSpec`).
 
 ## Headless adapters (the v0.1 pipeline)
 

package/docs/board-guide.md

@@ -184,6 +184,11 @@ is history, and after a day's work it is most of the list. It moves to the
 ledger (below) as part of a count that opens. A finished terminal that still
 needs you, or whose expansion you have open, stays in place.
 
+With the portable harness on, the register also carries one chip for the leg
+now running: `harness synced`, `harness partial`, `harness stale`, `harness
+attention` or `harness refused` (`harness.md`, "States"). Nothing shows when
+the feature is off.
+
 ### The one sentence
 
 `rankedNotes` in `src/board/sessions.js` is the single source of every sentence
@@ -289,6 +294,14 @@ from the right, and the page keeps one scroll container
    Hand off now. A normal exit ends this terminal.`, the **Change order**
    editor, the current bundle id, and whether `.leg/RESUME.md` still describes
    the repository (recomputed from git on every poll).
+8. **Harness** (only when the [portable harness](harness.md) is on): the
+   source client, when it was captured and synced, the policy, one line for
+   the leg now running (`codex harness partial · 8/8 components, 3 dropped ·
+   1 file(s) written`), a row per component with its state and `carried /
+   total`, **Needs you** for a hand-edited file or an unreadable config,
+   **Dropped** with a reason per item (`excluded by policy` when the drop was
+   yours), and the last eight entries of the harness trail. Every word comes
+   from what the session recorded when the leg started, never from a guess.
 
 It refetches every 3 seconds while it is open, and stops on **Pause updates**,
 when the tab is in the background, or when it is closed. The rest of the page

package/docs/cli-contracts.md

@@ -189,9 +189,30 @@ stderr are 0 bytes, and codex's is the one stdin notice. observed-live.
   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.
 
+## `leg harness` (the portable harness)
+
+What the command reads and writes per client, each fact from the engine's
+adapter source (`src/harness/vendor/agnostic-ai/engine/harness/{sources,targets}/*.cjs`,
+byte for byte the Agnostic AI engine) and verified by
+`test/harness-*.test.mjs` against fixture homes on 2026-09-16.
+
+| client | read as a source | written as a destination | shim |
+|---|---|---|---|
+| Claude Code | `~/.claude/CLAUDE.md` (+ `@imports` inside the home), `SOUL.md`, the hooks and permissions of its settings file, the `mcpServers` of `~/.claude.json` and `~/.claude/.mcp.json` (the oauth block is never read), `agents/*.md`, `commands/*.md`, `skills/*/SKILL.md` | `~/.claude/leg-rules.md` + one `@` line appended to `CLAUDE.md`; owned hook groups and permission entries in its settings file; owned servers in `~/.claude.json`; `agents/`, `commands/`, skill links | none: the bundle is Claude's dialect |
+| Codex CLI | `~/.codex/AGENTS.md`, `config.toml` (`hooks.*`, `mcp_servers.*`), `agents/*.toml`, `prompts/*.md`, `skills/`, `rules/*.rules` (per-invocation absolute-path approvals skipped; `auth.json` never read) | `AGENTS.md` (whole file, owned), `config.toml` regions `hooks` (with `[hooks.state]` trust hashes, self-tested), `skills` (duplicate disables), `mcp`; `agents/*.toml`; `prompts/*.md`; skill links; `rules/leg-harness.rules` prefix rules | none |
+| Antigravity CLI | not a source | `~/.gemini/GEMINI.md` (owned), the `leg-harness` key in `~/.gemini/config/hooks.json`, `mcp_config.json` servers, `config/agents`, `config/commands`, `config/skills` links | the engine's hook shim, chained with `++` |
+| Gemini CLI | not a source | `GEMINI.md`, owned hook groups in its settings file, `commands/*.toml`, `mcpServers`, skill links | shim |
+| Grok CLI | no | no (reported `unsupported`) | |
+
+Exit codes: `0` fine; `1` stale or attention (`check`, `sync`) or a doctor
+failure; `2` usage; `3` not captured, no source, or consent declined
+(`enable` without `--yes` and without a terminal). `--json` on `status`,
+`inspect`, `sync`, `check`, `explain`, `history`, `doctor` prints the same
+record the board reads.
+
 ## Interactive taps
 
-What `leg claude|codex|agy` reads while the real interactive CLI runs. Same
+What `leg claude|codex|agy|grok` reads while the real interactive CLI runs. Same
 tagging rule: `observed-live 2026-09-11` means the build machine did it;
 `docs-only` means the CLI's own source or documentation says so and Leg has
 not seen it happen. Machine: Claude Code 2.1.268, codex-cli 0.153.4, agy 1.2.0.
@@ -295,7 +316,7 @@ variable and `LEG_SESSION` (source: src/attach.mjs, src/env.mjs).
   "quota exhausted/exceeded" in the log, plus a relative reset parsed out of
   "resets in \<n>\<s|m|h|d>" (source: strings present in `agy.exe`;
   src/taps/agy.mjs `scanLog`).
-  **docs-only** <!-- live:agy/agy-resource-exhausted -->:
+  **observed-live 2026-09-16** <!-- live:agy/agy-resource-exhausted -->:
   `RESOURCE_EXHAUSTED (code 429): Individual quota reached … Resets in
   71h19m42s.` appeared in a session's `agy.log` at 08:02:42Z, `scanLog` read
   the relative reset, and the agent was walled. No payload was kept, the
@@ -310,6 +331,38 @@ variable and `LEG_SESSION` (source: src/attach.mjs, src/env.mjs).
   `LAYOUT.agy.env` is `null` and `accounts add agy` is refused (source:
   src/accounts.mjs).
 
+### grok tap
+
+- Attach: `grok <args> --debug-file <LEG_HOME>/sessions/<id>/grok.log` (source:
+  src/attach.mjs `spawnSpec`).
+- Usage: `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits` and
+  `GET https://cli-chat-proxy.grok.com/v1/user?include=subscription` with
+  `Authorization: Bearer <token>` read from `~/.grok/auth.json` (per-scope
+  key map or direct object). The billing endpoint reports `creditUsagePercent`
+  and `currentPeriod` (with weekly reset timestamp `end`). Polled every 60 s
+  (`LEG_USAGE_POLL_MS`). Token expiry and HTTP 401 are handled gracefully
+  without throwing, marking usage unknown until re-authenticated.
+  (source: src/taps/grok.mjs; probe against xAI proxy).
+- The wall: exact rate-limit signals cited from `xai-org/grok-build` (Rust):
+  - `SamplingError::Api { status: StatusCode::TOO_MANY_REQUESTS }`
+    (`crates/codegen/xai-grok-sampling-types/src/error.rs:304`)
+  - `RATE_LIMITED_ERROR_CODE = -32003` and messages
+    `RATE_LIMITED_USER_MESSAGE_OAUTH` ("You've hit the rate limit for your plan. Try again later.")
+    and `RATE_LIMITED_USER_MESSAGE_API_KEY` ("You've hit the rate limit for your API key. Try again later.")
+    (`crates/codegen/xai-grok-shell/src/sampling/error.rs:15, 18-21`)
+  - Headline "Rate limited (429)" and "You've hit the rate limit for your plan"
+    (`crates/codegen/xai-grok-pager/src/app/error_display.rs:263-267`)
+  - `StopFailureKind::RateLimit` ("rate_limit")
+    (`crates/codegen/xai-grok-hooks/src/event.rs:306-315`)
+  - Free usage exhausted: `FREE_USAGE_USER_MESSAGE` and `FREE_USAGE_EXHAUSTED_ERROR_CODE`
+    ("subscription:free-usage-exhausted")
+    (`crates/codegen/xai-grok-shell/src/sampling/error.rs:30, 33`)
+  `src/taps/grok.mjs` scans `grok.log` for these patterns and parses reset duration.
+- Prompts and session id: `~/.grok/sessions/<url-encoded-cwd>/prompt_history.jsonl`,
+  one `{ timestamp, session_id, prompt }` per entry (source: src/taps/grok.mjs `promptsSince`).
+- Accounts: `GROK_HOME` override supported; `leg accounts add grok <name>` creates
+  junctioned directories with copied `config.toml` (source: src/accounts.mjs).
+
 ### Usage store and the chooser
 
 - `<LEG_HOME>/usage/<agent>--<account>.json`:
@@ -361,7 +414,7 @@ non-zero exit → `failed`. Every outcome except `completed`, `auth_failed` and
 `killed` asks the chain to hand off.
 
 <!-- limits-table:start -->
-Generated by `node scripts/limits-table.mjs` from 21 fixtures (4 observed-live, 17 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Leg itself; `info` must never classify as a limit.
+Generated by `node scripts/limits-table.mjs` from 22 fixtures (4 observed-live, 18 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Leg itself; `info` must never classify as a limit.
 
 | id | adapter | class | where | source | text (excerpt) | produced by |
 |----|---------|-------|-------|--------|----------------|-------------|
@@ -383,6 +436,7 @@ Generated by `node scripts/limits-table.mjs` from 21 fixtures (4 observed-live,
 | generic-resource-exhausted | * | limit | any | **docs-only** | RESOURCE_EXHAUSTED | generic matcher (gRPC RESOURCE_EXHAUSTED); lowest priority |
 | generic-usage-limit | * | limit | any | **docs-only** | usage limit | generic matcher; lowest priority |
 | grok-not-logged-in | grok | auth | stderr | **observed-live** | To sign in, open this URL in your browser:    https://accounts.x.ai/oauth2/device?user_cod | fixtures/live/grok/err.log from scripts/probe.mjs --adapter grok, 2026-09-10 (stdout JSON stopReason: Cancelled, exit 0) |
+| grok-rate-limit | grok | limit | any | **docs-only** | You've hit the rate limit for your plan. Try again later. | crates/codegen/xai-grok-shell/src/sampling/error.rs:18 (RATE_LIMITED_USER_MESSAGE_OAUTH: "You've hit the rate limit for your plan. Try again later.") |
 | auth-source-set | * | auth | stderr | **docs-only** | another auth source is set | project brief (Wes, 2026-09-10): stderr saying "another auth source is set" counts as a failed launch; wording not yet observed live |
 | compile-error | * | info | stderr | **docs-only** | SyntaxError: Unexpected token )     at compileSourceTextModule (node:internal/modules/esm/ | synthetic negative fixture (a crashed agent is not a limit) |
 | empty-stdout-exit-0 | * | info | stdout | **observed-live** |  | fixtures/live/grok (exit 0, no work): silence is not a limit |