@ucsandman/legcli 0.8.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

@@ -26,6 +26,7 @@ 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,14 +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'}`)
   }
   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.BATON_ATTACH_POLL_MS || 2000} ms and hands off to ${s.chain?.[0]?.agent ?? 'nothing'}`)
+    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 Baton never writes. Use "leg sessions handoff ${s.session_id}" to force the switch.`)
+  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) {
@@ -138,7 +139,7 @@ async function main() {
       '            ██████████████████████████',
       '            ████ ████ ████ ████ ████ ████',
     ].join('\n')
-    out('🦿 LegCli: the mechanical relay runner for coding agents.\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
@@ -146,7 +147,7 @@ async function main() {
   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') {
@@ -192,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)
@@ -300,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
     }
@@ -322,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.
@@ -350,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.`)
@@ -360,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)
@@ -447,7 +454,7 @@ 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|grok|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|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
@@ -458,6 +465,8 @@ async function main() {
                                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/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,6 +189,27 @@ 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|grok` reads while the real interactive CLI runs. Same
@@ -393,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 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 Baton 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 |
 |----|---------|-------|-------|--------|----------------|-------------|

package/docs/concepts.md

@@ -108,12 +108,14 @@ things in order (`src/attach.mjs`, `src/bundle.mjs`):
    it again at the transition and during all-out waiting. Machine Settings is
    copied only when a new terminal starts.
 3. **Switch.** The agent process is stopped and the terminal restored. The
-   bundle's `context-handoff-bundle load <id>` output is written to
+   bundle's `context-handoff-bundle load <id>` output (with the `## Synthesis`
+   section prepended if `.leg/SYNTHESIS-<session-id>.md` is present) is written to
    `.leg/RESUME-<session-id>.md` and copied to `.leg/RESUME.md`, and the next
    agent starts in the same terminal with a short pointer prompt as its first
    positional argument: `claude "<prompt>"`, `codex "<prompt>"`,
-   `agy -i "<prompt>"`. The prompt names the per-session file, and says to check
-   `git status` and `git diff`, continue, and not ask the human to restate the
+   `agy -i "<prompt>"`. The prompt names the per-session file, directs the agent
+   to read Synthesis first and treat ruled-out approaches as settled, and says to
+   check `git status` and `git diff`, continue, and not ask the human to restate the
    task.
 4. **All out.** If every option is walled, Leg prints each one with its reset
    time, soonest first, then waits in the terminal with a one-line countdown
@@ -123,6 +125,33 @@ things in order (`src/attach.mjs`, `src/bundle.mjs`):
    (`{ agent, account, resets_at, since }`) and shows status `waiting`. Ctrl-C
    in the terminal, or End on the card, quits with exit 3.
 
+## The portable harness
+
+Off by default. `leg harness enable` adds a step to the hand-off, between
+**Choose** and **Switch**: the destination's working environment is prepared
+before the destination starts. The source client (the one you actually
+configure: Claude Code or Codex) is captured into a client-neutral bundle
+under `~/.leg/harness/bundle/` (rules with their imports inlined, identity,
+hooks, skills, subagents, slash commands, MCP servers with every credential
+replaced by `${NAME}`, permissions), and that bundle is rendered into the
+destination client's own files: `AGENTS.md`, `config.toml` regions and hook
+trust entries for Codex; `GEMINI.md`, `hooks.json` and `mcp_config.json` for
+agy; `leg-rules.md` plus one import line, hook groups and MCP servers for
+Claude Code. Skills are linked, not copied. What a destination cannot
+represent is dropped with a reason, and the session records exactly what
+transferred (`session.harness`, the `harness` event, the **Harness** section
+of the drawer).
+
+The saved policy decides what an unattended hand-off may do: `warn` reports
+and writes nothing, `sync` writes managed state when that is safe, `strict`
+refuses a destination it cannot make safe and tries the next option. A
+fingerprint of the source's files makes an unchanged environment free to
+check. Everything Leg writes this way carries `GENERATED by Leg harness`, sits
+in a marked region or an owned key inside files you also own, is backed up
+before it is overwritten, and is skipped when you hand-edited it. The source
+client is never written; credentials never move; which login runs is still the
+account layer's decision. The whole contract is in [harness.md](harness.md).
+
 ## The resume pointer
 
 `.leg/RESUME.md` is the file humans and other agents open by habit, so Leg
@@ -303,6 +332,16 @@ notes carry six sections in the bundle's own vocabulary:
 The next leg's prompt starts with the bundle's `load` output (the resume
 text) followed by the same contract.
 
+### The synthesis layer
+
+Alongside raw state, Leg supports an agent-maintained judgment record in `.leg/SYNTHESIS-<session-id>.md`. At handoff time, Leg reads this file and inlines it verbatim into `.leg/RESUME-<session-id>.md` and `.leg/RESUME.md` as a `## Synthesis` section before the raw bundle dump.
+
+- **Schema v1**: A 2-line header (`synthesis_version: 1`, `session: <id>  updated: <ISO-8601 UTC>`) followed by up to four optional sections in fixed order: `## Ruled out`, `## Decisions`, `## Next steps`, `## Open questions` (max 5 bullets each, one line per bullet).
+- **Size cap**: 4 KB. Beyond that, Leg includes the first 4 KB plus a trailing `[synthesis truncated]` marker.
+- **Resilience**: If the header is malformed, Leg still inlines the body prefixed with `[synthesis header invalid, rendering body as-is]`. If the file is absent or empty, no `## Synthesis` section is emitted and handoff degrades to today's raw dump.
+- **Pointer prompt**: Directs the taking-over agent to read the Synthesis section first if present, treat ruled-out approaches as settled, and start from the top-ranked next step.
+- **Board indicator**: Shows a `synthesis` chip on the terminal card when the synthesis file exists and was modified within the last 3 checkpoints.
+
 ## Worktrees
 
 Every card runs in its own git worktree: `<repo>/.leg-worktrees/<card-id>`

package/docs/configuration.md

@@ -29,6 +29,7 @@ These apply to `leg claude|codex|agy|grok`.
 | `LEG_NO_AUTO_APPROVE` | (unset) | set to `1` to opt out of auto-approve mode | `src/preferences.mjs` |
 | `LEG_WARN_PCT` | `85` | the percentage of either usage window that turns the card amber, records a `warning` event and rings the terminal bell once | `src/usage.mjs` |
 | `LEG_NO_HANDOFF` | (unset, hand-off on) | set to `1` to warn and record but never switch agents | `src/attach.mjs` |
+| `LEG_HARNESS_HOME` | the OS home | where the portable harness reads and writes client configuration (`~/.claude`, `~/.codex`, `~/.gemini` under it); the test suite points it at a throwaway directory. `CLAUDE_CONFIG_DIR`, `CODEX_HOME` and `GEMINI_CONFIG_DIR` move one client each, as everywhere else in Leg | `src/harness/registry.mjs` |
 | `LEG_NO_OPEN` | (unset, opens once) | set to `1` to start the board without opening a browser | `bin/leg.mjs` |
 | `LEG_NO_BOARD` | (unset) | set to `1` to run a session with no board at all (the record under `$LEG_HOME/sessions/` is still kept; the test suite uses this) | `src/attach.mjs` |
 | `LEG_WAIT_TICK_MS` | `1000` | how often the all-out countdown redraws and re-checks Ctrl-C / End while waiting for the first reset | `src/attach.mjs` |
@@ -99,7 +100,7 @@ Off unless explicitly enabled; a sync failure never blocks or fails a card
 ## Seller and checkout site
 
 These are for the checkout/key-delivery site and its deployment helpers, not
-normal Leg CLI use.
+normal Leg use.
 
 | variable | meaning | read in |
 |----------|---------|---------|
@@ -171,6 +172,26 @@ junctions as links, never following them, then deletes the directory. Nothing
 under your real home is written at any point. Start a session on a named
 account with `LEG_ACCOUNT=<name>`, or let a limit hand off to it.
 
+## The portable harness
+
+Off until `leg harness enable`. Its settings live in `~/.leg/preferences.json`
+beside the hand-off order:
+
+```json
+{ "harness": { "enabled": true, "policy": "sync", "source": "claude" } }
+```
+
+| key | values | meaning |
+|-----|--------|---------|
+| `enabled` | `true`, `false` (default) | the consent `leg harness enable` records; `leg harness disable` clears it and removes nothing |
+| `policy` | `warn`, `sync` (default on enable), `strict` | what an unattended hand-off may do: report only; write managed state when safe; refuse a destination that cannot be made safe |
+| `source` | `claude`, `codex` | the client whose harness is carried; auto-detected from `~/.claude/CLAUDE.md` then `~/.codex/AGENTS.md` when unset |
+
+`~/.leg/harness/policy.json` (optional) names what is deliberately not
+carried: sections to drop, hooks, skills and MCP servers to exclude, each with
+a reason, and the Codex model ladder. State, backups and the evidence trail
+live under `~/.leg/harness/`. Every detail: [harness.md](harness.md).
+
 ## Test and development seams
 
 Not meant for normal use; documented for completeness.

package/docs/faq.md

@@ -162,6 +162,25 @@ pre-commit hook both run `scripts/privacy-check.mjs`, which additionally
 scans the whole tree for a short list of strings specific to the private
 codebase Leg's runner/ledger were ported from.
 
+**Does the next agent get my rules, hooks, skills and MCP servers, or just the task?**
+Just the task, unless you turn on the [portable harness](harness.md)
+(`leg harness enable`). Then a hand-off also renders the source client's
+global working agreement, identity, hooks, skills, subagents, slash commands,
+MCP servers and permissions into the destination's own files, as far as that
+client can represent them, and the terminal's details say what was dropped and
+why (Codex has no SSE transport; agy has no `SessionStart` hook; a skill that
+already exists as a real directory is left alone). Credentials never move: an
+MCP key becomes `${NAME}` and you export it for each client. Off by default,
+and `leg harness disable` turns it off without removing anything.
+
+**Will the portable harness overwrite a file I edited?**
+No. Every file it writes carries `GENERATED by Leg harness` in its first lines,
+and inside a file you also own it writes a marked `leg harness` region. A
+file whose content changed since Leg wrote it is backed up once under
+`~/.leg/harness/backups` and skipped; the sync reports `attention` with the
+path, and `leg harness sync --force` is the only way it gets replaced. The
+source client is never written at all.
+
 **What happens if I close the terminal instead of Ctrl-C?**
 The board server and any running agents keep running as detached processes.
 Run `node bin/leg.mjs down` (or `npm run stop`) from another terminal to