@ucsandman/legcli 0.8.0 → 0.10.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,8 @@ 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'
+import { historyCommand, worktreesCommand } from '../src/history/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 +88,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 +140,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 +148,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 +194,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 +302,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 +324,27 @@ 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 === '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`
+    // starts a normal supervised leg on one of them. `leg history --json` is
+    // `leg history ls --json`: a leading flag names no verb.
+    const isHelp = cmd === '--help' || cmd === '-h' || cmd === 'help' || args.help || args.h
+    const bare = typeof cmd === 'string' && cmd.startsWith('--')
+    const verb = isHelp ? 'help' : (bare ? 'ls' : cmd)
+    const a = bare ? parseArgs([cmd, ...rest]) : args
+    // `continue <id> [agent args...]`: what follows the id goes to the agent
+    // untouched, the way `leg claude [args...]` passes its argv straight through
+    const raw = bare ? [cmd, ...rest] : rest
+    const code = group === 'history' ? await historyCommand(verb, a, { out, die, raw }) : worktreesCommand(verb, a, { 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 +373,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 +383,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,17 +470,25 @@ 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|history|worktrees|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
                                 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>
+  history [ls] [--provider p] [--repo r] [--search q] [--json]
+                                every conversation on this machine: Leg's own, and the ones Claude Code, Codex,
+                                Grok, Antigravity and Copilot keep in their own stores (read only, nothing moved)
+  history show|continue <id> | refresh | providers
+                                one conversation, or start leg <agent> on it where the agent can resume by id
+  worktrees [--repo r] [--json]  every checkout Leg can see: git's, its own, the ones conversations worked in
   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,157 @@
 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: 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
+`canLand`), `src/attach.mjs` (a taken port is a board; always open it) and
+`src/board/{board,sessions}.js` (one render per push, hold an open confirm row).
+Regression tests: `test/board-responsiveness.test.mjs`.**
+
+Reported as four bugs: `leg claude` took a long time to start, the board never
+opened by itself, the board was slow to load and to react, and Remove under
+Terminals did nothing. All four were one cause. The board server had burned
+17,080 seconds of CPU — it answered `/api/health` in 7 to 14 seconds and a
+40 KB stylesheet in 14. A live agent rewrites its session record every six
+seconds or so and takes a control lock about once a second; the recursive
+watcher over the sessions directory answered every one of those — including
+`.control.lock`, `.session.lock` and the `session.json.*.tmp` files atomic
+writes leave behind — with a full rebuild of the terminals view, which costs
+about two seconds (1.1 s of it `canLand` shelling out to git across twenty
+worktrees). 105 filesystem events in 30 seconds against a 300 ms debounce and a
+2,000 ms rebuild: the queue could never drain.
+
+What that one stall produced:
+
+- **Slow start.** `ensureBoard`'s health probe times out at 2 s, so a merely
+  busy board read as no board. `leg` spawned a second server, which died of
+  `EADDRINUSE` (the evidence was already in `~/.baton/board.log`), then polled
+  the dead child every 200 ms for the full 15 s.
+- **The board never opened.** `openBoard(url)` sat only on the branch that
+  successfully started a server. With one already running, or on the 15 s
+  give-up path, nothing was ever opened.
+- **Slow to react.** `board.js` dispatched `leg:sessions` and `baton:sessions`
+  per push, parsing the quarter-megabyte payload twice, with the second
+  dispatch outside the `state.es === es` staleness guard (missing braces on a
+  one-line `if`). `sessions.js` was registered on `leg:sessions` twice and on
+  the alias once. One push rebuilt the whole grid three times.
+- **Slow to react, part two.** `renderSessions` starts with
+  `grid.textContent = ''`, so with three rebuilds per push every button was
+  destroyed and recreated several times a second.
+
+**Remove was a second, independent bug, and fixing the first did not fix it.**
+Reported again as "it's still not removing them" after all of the above
+shipped. `confirmRow` does `pendingConfirm = null; onYes(yes)`, and the call
+site passed `(btn) => act(s.session_id, pendingConfirm.action, btn)` — a
+closure over the module variable, not over its value. Every Yes on the
+Terminals panel threw `TypeError: Cannot read properties of null (reading
+'action')` before reaching `act()`, so Remove, Remove record, End and Land had
+never worked from the confirm row; the exception went to the console and
+nowhere the reader would see it. Fixed by snapshotting
+`const pending = pendingConfirm` before building the row. Caught by driving the
+real page: the click produced zero network requests, which pointed at the
+handler rather than at anything server-side. The instrument that found it was
+five lines — wrap `window.fetch`, listen for `window.onerror`, click, read
+both.
+
+Three lessons. First, a name filter is not enough to classify a filesystem event:
+taking a lock inside a directory changes that directory's own mtime, and the
+event arrives naming only the directory. The watcher now treats an event as a
+hint and compares a stat fingerprint of the files the view is really built from
+— sub-millisecond, against a 2 s rebuild. Second, the CPU counter on a
+long-lived process names a stall in one command, before any code is read.
+
+Third, and the one that cost a round trip: several symptoms reported together
+are not thereby one bug. Three of these four were, and finding that cause made
+the fourth *look* explained — the render churn is a real way to drop a click,
+so "Remove doesn't work" fit the story. It was a different bug in a different
+file, and it was still there after the fix shipped. A symptom is only closed
+once it has been driven and watched, not once a plausible cause for it has been
+found and fixed. Clicking Remove in the real page would have taken two minutes
+and would have shown zero network requests and a `TypeError` in the console.
+
+Verified by running the new tests against `da453b7`: 7 of 8 fail there, 8 of 8
+pass after, and the busy-board test takes 21 s before versus 4 s after. On the
+live board, same 66 sessions: `/api/health` 14.19 s → 2.4 ms, `/board.css`
+14.24 s → 1.5 ms, `/api/sessions` 15.64 s → 109 ms, view rebuild 2,049 ms →
+115 ms, renders per push 3 → 1.
+
+Also found while verifying: `npm run lint` reported "ESLint: No issues found"
+with `node_modules/.bin` empty and eslint not installed — a wrapper was printing
+it. Run `npm install` first and check that ESLint really ran; a lint result from
+a tool that is not on disk is not a lint result.
+
+## 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`.**
@@ -324,3 +475,57 @@ it), and check whether a board was listening on 4747 at the time.
   module that reads the environment at import time cannot be imported from a
   helper that runs before the environment is set, no matter how small the thing
   you wanted from it.
+
+## A 3,000-line feature landed with red CI on Windows and no docs page (2026-09-16)
+
+- **Symptom.** Commit `c7f24a0` (the history index, committed by the agy
+  session that took over after a Claude usage limit) went green on Ubuntu and
+  macOS and red on Windows in two `history.test.mjs` cases, and the `docs` job
+  failed with "site/ is out of date". `/docs/history` did not exist and every
+  link to `history.md` pointed at the npm package page.
+- **Root cause, tests.** GitHub's Windows runner hands out an 8.3 short TEMP
+  path (`RUNNER~1`) while git reports the long form (`runneradmin`). The two
+  assertions compared a `mkdtemp` path with a path that had been through git.
+  The repo already had the seam for this (`canonPath` in `src/fsx.mjs`,
+  used the same way in `handoff-order.test.mjs`); the new tests did not use it.
+  It cannot be seen on a developer machine with 8.3 names disabled.
+- **Root cause, docs.** `scripts/build-docs-site.mjs` builds from a hard-coded
+  `PAGES` list. A new `docs/*.md` that is not in it gets no page, and
+  `rewriteHref` sends its links to the npm URL by design. Nobody ran
+  `npm run docs` before pushing, so the docs job was the first to notice.
+- **Fix.** `ebda794`: both sides of the four path assertions through
+  `canonPath`; reproduced locally by pointing `TEMP` at a case-altered path
+  (seen failing, then 16/16); `history` registered in `PAGES`; site rebuilt.
+- **The lesson that generalises.** A test that compares two filesystem paths
+  on Windows compares two spellings of the same folder unless both go through
+  `canonPath`. And a new `docs/*.md` is two edits, the file and the `PAGES`
+  entry, then `npm run docs`; the docs job exists because the second and third
+  get forgotten.
+
+## The review that was in flight when the limit hit never ran; the feature shipped with 38 defects (2026-09-17)
+
+- **Symptom.** `c7f24a0` (history discovery) was committed and pushed by the
+  agent that took over after a Claude usage limit. The nine-lens adversarial
+  review the Claude session had launched died with that session. Re-run the
+  next day it confirmed 38 findings, 3 high: the board's Conversations cell
+  could never page past 150 rows (the total was counted after the cursor
+  slice), an unreachable UNC cwd blocked a refresh for seconds per record,
+  and an Antigravity retitle was invisible to every incremental refresh
+  (the directory's mtime was the cache key; an in-place rewrite never moves
+  it).
+- **Root cause.** The hand-off bundle carried "what was established" and
+  "next moves" but not "what was in flight": a background workflow is not a
+  file, so the next agent saw a clean-looking task and shipped it. Nothing
+  in the ship path asks whether the change was reviewed.
+- **Fix.** `582dfe5`: 20 findings closed, each with a test that fails on the
+  previous source (proved on a detached worktree of HEAD before the fix).
+- **Left open, by choice.** Coverage-only findings (live markers, the
+  write-scope guard, the flag surfaces, extra accounts), a low-severity
+  dedup edge (a conversation split over two Claude transcript files when Leg
+  recorded only the older path), the `sessions ls` row format, and the
+  pretty-printed index file.
+- **The lesson that generalises.** A review is part of the change, not a
+  step after it: launch it before the feature is committable and record it
+  in the hand-off as in flight, or the next agent ships without it. And a
+  cache keyed on a directory's mtime sees files added and removed, never a
+  file rewritten in place.

package/docs/README.md

@@ -6,6 +6,8 @@
 - [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.
+- [history.md](history.md): `leg history` and `leg worktrees`, one read-only index over every agent's own conversation store and every checkout, the support matrix per provider, dedup against Leg's own sessions, privacy, and how to add a provider.
 - [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,8 +24,10 @@
 | 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) |
+| history | `src/history/index.mjs` (the index, dedup, resume), `src/history/providers/*.mjs` (one per agent store, read only), `src/history/worktrees.mjs` (the unified checkout view), `src/history/cli.mjs` (`leg history`, `leg worktrees`) |
+| board | `src/server.mjs`, `src/board/sessions.js` (Terminals lane), `src/board/history.js` (Conversations), `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` |
 
 ## History

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

@@ -47,10 +47,13 @@ Source: the `appendEvent`/`updateSession` call sites in `src/attach.mjs`,
 | `handoff` | the switch happened: from, to, reason, bundle id |
 | `all_out` | every option is walled; the resets are printed and the terminal waits for the first one (`ended` with "quit while waiting" if Ctrl-C or End cuts the wait short, exit 3) |
 | `agent_exit` | the agent process exited, with its code |
+| `continued` | the session was started by `leg history continue` on a conversation the agent's own store holds; `session.json` carries `continued_from: { id, provider, native_id }` |
 | `ended` | the session ended |
 | `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 +61,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 +186,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
@@ -304,7 +317,7 @@ before saving.
 
 ## The ledger
 
-Below the terminals, three counts sitting on the ground with no panel, because a
+Below the terminals, four counts sitting on the ground with no panel, because a
 raised surface here would compete with the terminals that are live. Each is a
 heading, a line of detail and a button that opens the detail below the row.
 
@@ -321,6 +334,25 @@ heading, a line of detail and a button that opens the detail below the row.
   visual weight as the live terminals, so the loudest thing on the page was a
   commit from eleven days ago. With nothing landed it reads `Nothing landed yet`
   and explains what Land does.
+- **N conversations**, every coding-agent conversation on this machine, `799
+  claude, 198 codex, 92 agy, 14 grok, 5 copilot; looked 2m ago`: the sessions
+  Leg started and the ones the agents keep in their own stores, read from
+  there and never moved ([history.md](history.md)). **Browse N** opens a
+  drawer with filters (agent, search, repository, only what Leg started), a
+  page of fifty rows newest first and **Show 50 more**. A row is the title as a
+  button, then the agent chip, `leg` or `external` (`, live` when a process is
+  still on it), `repo on branch`, the prompt count and the short id. The title
+  opens the conversation in place: agent, who started it, folder, repository,
+  worktree, times, prompts, transcript path, id, the `leg history continue
+  <id>` command with **Copy the continue command** where the agent can resume
+  by id (or the reason it cannot), **Copy folder path**, and the last eight
+  messages newest first, each redacted the way the terminal drawer's are. Below
+  the rows, **Checkouts**: every worktree Leg can see with its repo and branch,
+  owner (the checkout itself, a Leg session, a Leg card, or not Leg's), how
+  many conversations point at it, and `missing`, `orphaned`, `stale`, `clean`
+  or `N uncommitted`. Nothing here is pushed over the live stream; the count
+  re-reads itself once a minute while the drawer is closed. On a shared board
+  a guest sees `The owner of this machine sees them.` and nothing else.
 - **N background tasks**, the card runtime below, as a count with **View N
   cards**, plus **New card**. With none it reads `Nothing is queued. Leg starts
   the next login only when a terminal hands off.`