@ucsandman/legcli 0.7.0

package/docs/ERRORS.md

@@ -0,0 +1,326 @@
+# Errors
+
+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-15: macOS `/var` symlink broke two e2e tests
+
+**Fixed in `test/helpers.mjs`.**
+
+`initRepo` and `makeHome` returned the path from `mkdtempSync(join(tmpdir(),
+...))` verbatim. On macOS, `tmpdir()` returns `/var/folders/…` but `/var` is a
+symlink to `/private/var`. Leg stores paths through `canonPath` (which calls
+`realpathSync`), so `s.cwd` was `/private/var/…` while the test's `repo` was
+`/var/…`. Two `attach-e2e` assertions failed: `assert.equal(codex.cwd, repo)`
+and the `.find(s => s.cwd === repo)` that guards the "End from board" test.
+
+The fix wraps both helpers in `realpathSync` so the returned path matches what
+baton stores. This is a test-infrastructure bug, not a production-code bug:
+`canonPath` was already doing the right thing.
+
+The lesson: any path created from `os.tmpdir()` that will be compared against a
+path stored by production code must be resolved first, because macOS `tmpdir()`
+returns the unresolved symlink form.
+
+## 2026-09-15: Land could not run the tests on macOS
+
+**Fixed in `src/adapters/resolve.mjs`.**
+
+The first CI run with `macos-latest` in the matrix failed where Linux and
+Windows passed: `cannot resolve npm's JS entry` from `resolveCommand`
+(`src/commands.mjs:22`), taking down `runTests` and with it `landNow` and the
+merge queue. On a Mac, Land could never have run a repo whose test command
+starts with `npm` or `npx`.
+
+`resolveNpmCliEntry` looked in three places: `%APPDATA%\npm\node_modules`,
+`/usr/local/lib/node_modules` and `/usr/lib/node_modules`. All three are
+guesses at where someone else put node. The GitHub macOS runner keeps it in
+`~/hostedtoolcache`, so none of them existed and the lookup returned null.
+Linux passed only because `/usr/local/lib/node_modules` happens to exist
+there, the same latent bug, hidden by a coincidence of layout. Homebrew,
+nvm and asdf would all have failed the same way on a real machine.
+
+The fix derives the prefix from the running binary instead of guessing:
+POSIX installs put node at `<prefix>/bin/node` and global packages at
+`<prefix>/lib/node_modules`, so `dirname(process.execPath)/../lib/node_modules`
+finds it wherever node actually lives. `execPath` is now an injectable option
+so the layout can be tested without one.
+
+The lesson is about the class, not the path: a hardcoded absolute path is a
+guess about someone else's machine, and a test matrix that omits a platform
+does not tell you the code works there, it tells you nothing about it. This
+was latent for as long as the matrix was two platforms wide.
+
+Covered by `npm-entry-from-execpath` in `test/lessons.test.mjs`, checked in
+both directions: it fails with the fix reverted and passes with it.
+
+## 2026-09-15: share-security failed once in the full suite and has not repeated
+
+**Not fixed. Recorded so a second occurrence is countable.**
+
+One full-suite run reported `test\share-security.test.mjs` failing at `:1:1`
+after 1496 ms, with no individual test named. The file passed 19 of 19 in
+isolation in 6.5 s, and passed inside two later full runs of the whole suite.
+No root cause found.
+
+What the evidence rules out: parallel contention, because `npm test` runs
+`--test-concurrency=1`. What it points at: the file failed at the top level
+rather than in a named test, and far faster than its healthy 6.5 s, so it died
+during setup, not in an assertion. The file binds several loopback boards on
+ephemeral ports and exercises a rate-limit lockout, and a Leg board was live
+on 4747 for 161 minutes when the failing run started.
+
+The cost of the bad reading was real even though the test was fine: the suite
+totalled 454 tests that run instead of 472, because a file that dies at the top
+level never registers its subtests, and 454 was briefly written into
+`fixtures/verified.json` and onto two public pages as the published test count.
+A total from a run with a failure in it is not the suite's size.
+
+If it happens again: capture the file's stderr before anything else
+(`node --test --test-reporter=spec` writes it; the default reporter swallowed
+it), and check whether a board was listening on 4747 at the time.
+
+## 2026-09-15: a 3-second rebuild made the board impossible to scroll
+
+- **Symptom.** Reported by the operator as "I'm not able to scroll down or up or
+  really interact with the new UI layout, and it keeps reverting to where I was
+  before scrolling." Intermittent-looking, which is what made it hard to believe.
+- **Root cause.** `src/board/sessions.js`, in `putFocus()`. Every region on the
+  board is wiped and rebuilt on a timer, so focus is captured before the wipe and
+  restored after it, or a tabbed control is lost every three seconds. The restore
+  called `target.focus()`. `focus()` scrolls its element into view unless it is
+  passed `{ preventScroll: true }`, so the moment the reader clicked any button,
+  every poll dragged the viewport back to that button, forever.
+- **Why it looked random.** With nothing focused, `takeFocus()` returns null and
+  the page behaves. The bug only appears after the reader interacts, which is
+  exactly when they stop suspecting the page and start suspecting themselves.
+- **Fix.** `target.focus({ preventScroll: true })` on the rebuild path only. A
+  focus move the reader asked for (Cancel in a confirm row, the close control of
+  the detail region) still scrolls, because there it is the right behaviour.
+- **Measured before and after.** Before: scroll to 1200, click Details, and the
+  next seven samples read 106, 106, 106… After: four scenarios held for 20
+  seconds each across both the 3s poll and the 15s re-sort, 0px drift on all
+  four. `test/board-drawer.test.mjs` now pins both halves of the rule.
+- **The lesson that generalises.** Screenshots and a green suite cannot see "the
+  page fights you three seconds later". A live surface needs a hold test: put the
+  viewport somewhere, wait through every timer the page owns, and assert it did
+  not move. The same applies to focus, scroll position, an open disclosure and a
+  text selection.
+
+## 2026-09-15: Leg silently reversed a user's refusal to trust a folder
+
+- **Symptom.** None visible. That is the point: it wrote to a file the user owns
+  and printed a line that read like a first-time record.
+- **Root cause.** `src/trust.mjs` treated "not `true`" as "not asked yet". A
+  `hasTrustDialogAccepted: false` in `~/.claude.json`, which is what clicking
+  "No, exit" records, was flipped to `true` on every run in that repo. The agy
+  writer had the same shape: any value other than `TRUST_FOLDER`, including a
+  deliberate `DO_NOT_TRUST`, fell through to a write. The codex writer was the
+  only one of the three that got it right, because it happened to test for
+  presence rather than for truth.
+- **Fix.** Only an absent key is an unanswered question. An answer already on
+  file is the user's, including "no", and is left alone with a stated reason.
+  The imports question is separate: `WarningShown: true` with `Approved: false`
+  is a recorded refusal and is not re-approved.
+- **The lesson that generalises.** When code writes a file a human owns, absent
+  and negative are different states and must be distinguished in the code, not
+  in a comment. `!== true` is not "unset".
+
+## 2026-09-15: the trust record was written under a key Claude Code never reads
+
+- **Symptom.** Would have been: the flag is on file, the prompt still appears,
+  and nothing says why. Caught before shipping by diffing against a copy of a
+  real `~/.claude.json` rather than a synthetic one.
+- **Root cause.** The project key was written in Windows-native form,
+  `C:\Projects\foo`. Claude Code stores it as `C:/Projects/foo`: 100 of the 104
+  entries in a real config are forward-slash with an upper-case drive letter and
+  no trailing separator, and the four that are not are older duplicates of
+  projects that also appear in the new form. The wrong spelling creates a second
+  entry that is simply ignored.
+- **Fix.** `claudeProjectKey()` normalises to that form. An older spelling
+  already present is updated in place, never created, so a stale entry is
+  corrected without littering the config.
+- **The lesson that generalises.** When writing into someone else's data file,
+  derive the key format from that file's own contents on a real machine. A
+  synthetic fixture agrees with whatever the code does and proves nothing.
+
+## 2026-09-15: a walled usage bar was drawn full, then drawn red, before it was drawn at all
+
+- **Symptom.** The account at its limit showed a full calm-blue bar beside the
+  words `no reading`: the most urgent row on the page looked like the safest.
+- **Root cause.** `board.css` draws a walled account's fill at 100%, but the
+  colour stops were computed from the percentage, which is 0 when there is no
+  reading, and `fillStops(0)` puts every stop at 100% so the whole bar paints
+  calm.
+- **The wrong first fix, and why.** Computing the stops from 100 when walled made
+  the bar danger-red. That is the same fabricated number, louder. An independent
+  review caught it. The right answer is that a window with no reading paints no
+  fill at all, and the wall is carried by the words beside it.
+- **The lesson that generalises.** When a display and its own label disagree,
+  fix the display's right to exist, not its colour.
+
+## 2026-09-15: the OG card advertised a commercial product as MIT
+
+- **Symptom.** `site/og.html` printed `Claude Code · Codex · agy · local · MIT`
+  on the card every shared link renders. Leg ships under the Leg License
+  Agreement, all rights reserved; the only MIT in the repo is in `NOTICE`, about
+  a borrowed component explicitly re-licensed.
+- **Fix.** The tag line names the price instead. The first correction was longer
+  than the string it replaced and pushed `.cmd` into wrapping, so `.cmd` is now
+  `flex: none; white-space: nowrap` and the footer measures 0px past its gutter
+  with a 15px gap, checked with `getBoundingClientRect` rather than by eye.
+- **The lesson that generalises.** A generated image is code with no test. Any
+  copy change inside one needs the render measured afterwards, and legal or
+  pricing strings in marketing assets need checking against `LICENSE` and
+  `package.json`, which are the only sources that are actually true.
+
+## 2026-09-15: a redesign measured on a board of healthy terminals
+
+- **Symptom.** Compact row styling was reported as producing 40px terminal rows.
+  Wes's actual screen showed 400px rows and he rejected the result.
+- **Root cause.** The styling was scoped to `.panel.is-running` and measured
+  against a board of live, healthy terminals. A real board after a day's work is
+  mostly `lost` and `ended` terminals with long absolute temp paths, and none of
+  them matched the selector, so the measurement was taken on the minority of rows
+  the change actually touched.
+- **Fix.** `scratchpad/seed-wes.mjs` seeds a board with the real shape, 4 live,
+  3 lost, 2 ended, long temp paths, an image tag in a prompt, served on an
+  isolated port with a throwaway `LEG_HOME`. Run against it, the *pre-change*
+  board reproduced the defect exactly: 3,302px page and 180-277px rows at 1280,
+  6,530px and 307-585px at 400. That is the check being observed failing before
+  it was trusted.
+- **The lesson that generalises.** A UI measurement is only worth what its
+  fixture is worth. Before trusting a number about a redesign, seed the state the
+  operator actually has and confirm the instrument reproduces the complaint.
+  Never 4747 for that board: that port is the live one with real sessions on it.
+
+## 2026-09-15: a CSS rewrite silently broke the page that shares the stylesheet
+
+- **Symptom.** `/floor` rendered unstyled account rows and threw
+  `ReferenceError: narrowQuery is not defined` after the board redesign.
+- **Root cause.** `floor.html` and `floor.js` share `board.css` and carry a
+  ported copy of the board's head block. Rewriting `board.css` removed the
+  classes that copy emits (`.acct`, `.rail`, `.track`, `.fill`, `.num`, `.tier`),
+  and removing helpers from `sessions.js` left the copy in `floor.js` referencing
+  names that no longer existed on its own page.
+- **Fix.** The head block is now extracted from `sessions.js` mechanically rather
+  than transcribed, so the "character for character" claim in its comment stays
+  true; `floor.html` moved onto the new shell; the floor's table styles were
+  added to the new system.
+- **The lesson that generalises.** Before rewriting a shared stylesheet, list
+  every page that links it and open each one. A grep for the class names would
+  also have caught this; rendering the page is what actually did.
+
+## 2026-09-15: two pre-existing CI failures, one hiding behind the other
+
+- **Symptom.** Three trust tests failed on the ubuntu job; the windows job showed
+  `cancelled`. Fixing ubuntu revealed three *different* failures on windows, in
+  resume, that had been there for two commits.
+- **Root cause.** A failing matrix leg cancels its siblings, so windows had not
+  run to completion since `1f61414` introduced `test/resume.test.mjs`. Every run
+  after that reported `win=cancelled`, which reads like "not the problem" and is
+  actually "not measured". Both underlying bugs were the same shape: a function
+  describing a path asked the *host* to resolve it. On ubuntu, `resolve()` on
+  `C:\cfg` prepended the runner's cwd; on windows, `realPath()` expanded the 8.3
+  short name in `tmpdir()`, so `C:\Users\RUNNER~1\...` came back as
+  `C:\Users\runneradmin\...` and no longer matched the path the caller passed in.
+- **Fix.** `src/trust.mjs` treats a drive-letter path as already absolute and
+  recognises the older Windows spelling by its spelling rather than by asking the
+  host to resolve it. `src/resume.mjs` walks with `resolve()` instead of
+  `realPath()` and returns the root in the caller's own spelling; two spellings
+  of one checkout are reconciled by `canonPath()` where they are compared.
+- **The lesson that generalises.** `cancelled` on a CI matrix leg is not a pass
+  and not a failure, it is no information, and it stays that way for as long as
+  a sibling keeps failing. Read the per-job conclusions, not the run's, and treat
+  a leg that has not completed since a feature landed as unmeasured. Locally,
+  `npm test` does not run `npm run lint` here: both are needed before a push.
+
+## 2026-09-15: the site did not deploy, and the repo said it had
+
+- **Symptom.** `main` was fast-forwarded with the board and site redesign, every
+  check was green, and `legcli.com` still served the old blue page.
+  GitHub showed `Vercel, Canceled by Ignored Build Step` with a green tick,
+  which reads like a pass.
+- **Root cause.** `site/vercel.json` carried
+  `ignoreCommand: git diff --quiet HEAD^ HEAD .`, and with Root Directory `site`
+  that asks one question: did the SINGLE most recent commit touch `site/`? The
+  push was five commits; `site/` changed in the first of them and the tip was a
+  test fix, so the answer was no and the build was skipped. A push is not a
+  commit, and `HEAD^ HEAD` cannot see past the tip.
+- **Fix.** `ignoreCommand` removed, so every push to `main` deploys. Vercel's
+  built-in "Skip deployments when there are no changes to the root directory"
+  is the safe form of the same idea because it compares against the last
+  deployment, not against `HEAD^`.
+- **The lesson that generalises.** A skipped step reports as a green tick.
+  "Canceled by Ignored Build Step" and a cancelled CI matrix leg are the same
+  trap in different clothes: an absence of failure that is not a success. After
+  a deploy, load the page and confirm the change is on it, the deploy
+  platform's own tick is not evidence that anything shipped.
+
+## 2026-09-15: the new OG card was live and every share still showed the old one
+
+- **Symptom.** The site had deployed the dark OG card, and a link shared in a
+  messaging app still previewed the blue one, with a tag line naming MIT, which
+  had been corrected days earlier.
+- **Root cause.** Nothing was wrong with the deploy: fetching
+  `/og.png` returned the new image. Link-preview caches (Telegram, Slack,
+  iMessage, X) key on the image URL and most never re-fetch a URL they already
+  hold. `og.png` never changed, so every client that had ever crawled the page
+  kept its first copy indefinitely.
+- **Fix.** `og:image` and `twitter:image` carry `?v=`, bumped in the same commit
+  that changes `og.png`. Already-cached previews need the platform's own
+  refresh (Telegram: send the URL to `@WebpageBot`).
+- **The lesson that generalises.** "Deployed" and "what people see" are
+  different questions for anything a third party caches by URL. An asset that
+  will ever be revised needs a version in its URL from the first ship, not after
+  someone notices the old one is still going out.
+
+## The card row was never ported, and nothing noticed for four days (2026-09-15)
+
+- **Symptom.** Retaking `docs/screenshots/` showed the Background tasks rows
+  rendering as unstyled markup: the card title unreadable, chips welded to the
+  text beside them, the four-column layout stacked into blocks. The rest of the
+  board had been redesigned on 2026-09-15 and looked right.
+- **Root cause.** `.r1` `.r2` `.r3` `.r4`, the card row's whole layout, had no
+  rule in `board.css`. `.row-title` had a rule, but it set only `font-size` and
+  `color`, never resetting the native button, so the browser's own
+  `rgb(240,240,240)` fill sat under the board's near-white text. Two separate
+  misses in the same region, neither of which fails a test, a lint, or a build.
+- **Fix.** Both rules written against `.term-row`, the terminal row they are
+  supposed to mirror. `test/board-a11y.test.mjs` now fails if any class that
+  reaches the DOM from `board.js`, `sessions.js`, `floor.js`, `index.html` or
+  `floor.html` has no rule in `board.css`, with a named exception list for the
+  ones queried as selectors only. Verified by deleting the `.r1` rules and
+  watching the test name `.r1`.
+- **The lesson that generalises.** A redesign that lands region by region has no
+  natural signal for the region nobody opened. CSS has no undefined-variable
+  error: an unstyled class renders, it just renders wrong, and it renders wrong
+  only where someone looks. The check that would have caught it is cheap and
+  mechanical, every class the code emits must resolve to a rule, and it should
+  exist before the redesign starts, not after the screenshots expose it.
+
+## Removing the trial turned the test suite red in three unrelated files (2026-09-15)
+
+- **Symptom.** After deleting the 14-day trial from `src/license.mjs`,
+  `share.test.mjs`, `cards.test.mjs` and `launcher.test.mjs` failed with
+  licensing errors, none of which mention licensing in their test names.
+- **Root cause.** The trial opened every gate for free, so ~470 tests had been
+  passing the licence check without ever declaring they needed to. Removing it
+  made the suite's dependence on it visible all at once.
+- **Fix.** `testEnv()` writes a Team key into each throwaway home, signed by a
+  pair generated per run, with `LEG_PUBLIC_KEY_B64` pointing the spawned CLI
+  at its public half. `LEG_UNLICENSED=1` opts a test back into the refusal.
+- **A second bug inside the fix.** The first version imported `src/license.mjs`
+  from `test/helpers.mjs` to reuse `signLicense`. That pulls in `store.mjs`,
+  which reads `LEG_HOME` once at import time, and `helpers.mjs` is imported by
+  every test file *before* it sets `LEG_HOME`, so the ledger was pinned to
+  whatever home happened to be set, which on a developer machine is the real
+  `~/.leg`. Caught because `server.test.mjs` started failing on a card it had
+  just written. The key format is now reproduced in `helpers.mjs` instead.
+  Checked `~/.leg` afterwards: no test cards, no `license.json`, nothing
+  written.
+- **The lesson that generalises.** A permissive default in test setup is load
+  bearing and invisible; you find out how much only when you remove it. And a
+  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.

package/docs/README.md

@@ -0,0 +1,40 @@
+# Docs index
+
+## Start here
+
+- [getting-started.md](getting-started.md): install, run `leg claude`, what you get while it runs, where files live, and the v0.1 pipeline flow as an extra.
+- [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.
+- [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).
+
+## Reference
+
+- [VOCABULARY.md](VOCABULARY.md): the exact identifiers Leg uses for session statuses and session events, and for card statuses, outcomes, event types, actor types, human actions and bounce reasons.
+- [cli-contracts.md](cli-contracts.md): what Leg knows about each coding-agent CLI, the interactive taps and their sources, and the limit-signal table, every fact tagged observed-live or docs-only.
+- [DEMO.md](DEMO.md): a fake-adapter walkthrough of a usage-limit handoff, with screenshots.
+- [real-run.md](real-run.md): one real pipeline run, claude handing off to codex with no fakes involved.
+- [ROADMAP-v2](ROADMAP-v2.md): where the factory-floor shape is headed after v1.
+
+## The code behind the docs
+
+| 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) |
+| 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` |
+
+## History
+
+- [REUSE.md](REUSE.md): what Leg ports from the private team tooling it started from, and what it drops.
+- [ERRORS.md](ERRORS.md): what broke, the root cause and the fix, so a repeat is countable.
+- [DEVIATIONS.md](DEVIATIONS.md): every place Leg's shape differs from that ported source or from the plan, one row per change.
+
+## Also see
+
+- [../README.md](../README.md): the top-level overview.
+- [../CHANGELOG.md](../CHANGELOG.md): what changed in each release.
+- [../CONTRIBUTING.md](../CONTRIBUTING.md): dev setup, tests, lint, the privacy hook, PR checklist.
+- [../SECURITY.md](../SECURITY.md): how to report a vulnerability.

package/docs/REUSE.md

@@ -0,0 +1,289 @@
+# REUSE, what Leg ports from the private team tooling, and what it drops
+
+Source: a private ucsandman repository (team tooling for a two-agent protocol
+with a detached Claude Code launcher, a JSONL task ledger, a git snapshot tool,
+and a governed capability runner). Read in full on 2026-09-10 before any Leg
+code was designed. Every ported shape change is one row in `DEVIATIONS.md`.
+NOTICE carries the attribution. No path, id, or chat identifier from the source
+appears anywhere in this tree; `scripts/privacy-check.mjs` enforces that.
+
+Legend: **Ported** = kept, with its new home. **Dropped** = removed, with the
+reason. **Why** = the judgment.
+
+## lead-handoff.mjs
+
+**Ported** (→ `src/runner.mjs`, subcommands `launch | supervise | sweep`):
+- `launch`: detached supervisor spawn (`detached: true, windowsHide: true`,
+  `child.unref()`), the `handoff_already_running` refusal (exit 11) when the
+  recorded supervisor pid is alive, archiving a stale record to `*.prev.json`
+  and relaunching when it is dead, one-line JSON on stdout.
+- `supervise`: spawn the agent with stdout/stderr redirected to files, write
+  the run record on every transition, notify timer (30 min) and kill timer
+  (90 min) with the kill-verify retry (30 s) and the UNKILLABLE path (exit 12),
+  session-id capture from the result file, ledger writes through the ledger CLI
+  via `ledgerSafe` (a ledger failure never crashes the supervisor), stderr tail
+  scrubbed of secrets before it is logged (`SECRET_RES`, `scrub`, `errTail`).
+- `killTree`: `taskkill /PID <pid> /T /F` on Windows, process-group SIGKILL
+  elsewhere; the `HANDOFF_SKIP_KILL` test seam becomes `LEG_SKIP_KILL`.
+- `sweep`: orphan detection (record says running, supervisor pid dead →
+  `orphaned` + ledger error + ORPHANED line naming the child pid).
+- `pidAlive`, `parseArgs`, `need`, `die`, exit codes 0 / 2 / 3 / 11 / 12 / 13.
+- `resolveOpenclawEntry` → `src/adapters/resolve.mjs` `resolveNpmCliEntry(pkg, bin)`:
+  resolves an npm package's real JS entry so the runner can `spawn(node, [entry])`
+  without a shell (the `.cmd` shim needs one). Codex and the optional
+  OpenClaw sync need exactly this.
+- Child environment sanitization before spawn (the "drill launched from inside
+  a Claude Code session leaks a session key" lesson) → one exported
+  `sanitizeEnv(env)` that every adapter calls; the deleted-key set grows (see
+  DEVIATIONS).
+- The timer seam (`HANDOFF_TIMERS_MS` → `LEG_TIMERS_MS`, same
+  `notify,kill,kill-verify` shape and defaults).
+
+**Dropped:**
+- `telegramTarget`, `sendTelegram`, `.env.handoff`, every `notify(...)` message
+  string, and the sweep's delivery canary, Telegram delivery and chat ids
+  (privacy rule). The notify timer becomes a ledger `status` event only.
+- `LEAD_ALLOWED_TOOLS`, a hard-coded allowlist naming the team bin scripts and
+  two MCPs. Leg passes only the permission mode the chain entry names and
+  never disallows the Agent tool.
+- `findReportEvent`, decided "completed" by scanning the lead's ledger for a
+  `done` event. Leg uses one CLI-agnostic completion contract (`.leg/DONE`
+  in the worktree), phase 5.
+- `--model` / `--effort` / `--safe-mode` argv and the `origin` lookup, model
+  and effort move into the chain entry; there is no origin surface.
+- `WORKDIR = ROOT/../..` (the lead ran in the private repo's root), Leg runs
+  every leg in the card's worktree.
+
+**Why:** the supervise/kill/sweep logic is paid-for behaviour with tests that
+caught real incidents (split-brain relaunch, unkillable lead, orphaned
+supervisor after reboot). Everything dropped is either transport (Telegram),
+identity (allowlist, private paths), or a completion rule that only worked for
+one CLI.
+
+## lead-handoff.test.mjs
+
+**Ported** (→ `test/runner.test.mjs`, stub agents → `src/adapters/fake.mjs` +
+`bin/fake-agent.mjs` selected by `FAKE_MODE`):
+- launch writes the run record + prompt file and prints ok JSON
+- launch refuses unknown card (exit 3) and missing prompt file (exit 2)
+- launch exits 11 when the supervisor pid is alive
+- launch archives a stale record (dead pid) and relaunches
+- supervise: fast finish stores the session id, exit code, never fires timers
+- supervise: agent exits without finishing → `failed`-shaped record, exit 13,
+  ledger error with a **scrubbed** stderr tail (the `sk-…` assertion stays)
+- supervise: runaway agent → notify event then killed, exit 12
+- supervise: unkillable agent → retry, UNKILLABLE ledger error, exit 12
+- supervise: child environment is sanitized (extended to all seven keys plus
+  the `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` assertion)
+- sweep: dead supervisor → orphaned + ORPHANED line + ledger error
+- sweep: healthy running record left alone
+- sweep: no records → quiet OK line, exit 0
+
+**Dropped** (named here so the count is auditable):
+- "supervise: lead logs done -> completed, session id stored, HANDOFF_DONE sent"
+  (the completed half is replaced by phase 5's DONE-marker test; the Telegram
+  half is gone)
+- "supervise: claude-code origin -> no telegram send at all"
+- "supervise: no TEAM_TELEGRAM_TO configured -> send skipped, still completes"
+- "sweep: no handoffs at all -> ... dry-run-only canary" (canary half)
+- "sweep: broken delivery path -> DELIVERY-CHECK FAILED line"
+- "sweep: no TEAM_TELEGRAM_TO -> DELIVERY-CHECK FAILED line"
+
+**Why:** the stub-agent approach (a per-test `.mjs` that plays the CLI) is the
+right seam for a runner that must never touch a real CLI under test; it becomes
+Leg's fake adapter, which phase 4 extends with limit / stall / auth-failure
+modes.
+
+## team-ledger.mjs
+
+**Ported** (→ `src/ledger.mjs`, subcommands `create | append | update | sync`):
+- The rule that this file is the ONLY writer of ledger files; per-writer
+  append-only JSONL; `ACTIVE.md` regenerated on every create/update with
+  corrupt records skipped and warned, never bricking the list.
+- `assertNoSecrets` with `SECRET_PATTERNS` (refuses to log, exit 2).
+- `parseArgs` / `need(args, key, allowed)` validation with the exact
+  `invalid --type "gossip" (allowed: …)` error shape.
+- The DashClaw sync: `loadDashclawConfig` (process variables win, then a
+  dotenv file), `dashclawRequest` on native `http`/`https` with a 5 s timeout
+  and the 409-on-create-is-success rule, `bufferUnsynced` → `unsynced.jsonl`,
+  `flushUnsynced` via `sync [--card]` exiting 1 while anything remains.
+- Exit codes 2 (bad args / secret / corrupt record) and 3 (not found).
+
+**Dropped:**
+- `AGENTS = ['claude', 'openclaw']`, `RECIPIENTS`, and the `from`/`to` pair -
+  replaced by a validated `actor` object plus `card_id`, `station`, `leg`
+  (amendment 2 §4).
+- `ORIGINS`, `lead`, `stop_condition`, `max_exchanges`,
+  `openclaw_session_key`, two-agent protocol fields with no Leg meaning.
+- The `team-` id prefix and `tasks/` directory (→ `card-`, `cards/`).
+- The DashClaw endpoint paths `/api/team-tasks…`, phase 9 wires the real
+  target through config; the transport code stays.
+
+**Why:** an append-only, secret-refusing, per-writer ledger with a buffered
+best-effort sync is exactly the multiplayer-ready event store amendment 2 asks
+for. Only the vocabulary changes.
+
+## team-ledger.test.mjs
+
+**Ported** (→ `test/ledger.test.mjs`, renamed to card/actor vocabulary):
+- create writes `card.json`, the `card_created` event, and `ACTIVE.md`
+- append adds one line to the writer's own file only
+- update patches status and session id and regenerates `ACTIVE.md`
+- append with an invalid type exits 2 and names the bad value
+- append to a missing card exits 3
+- create rejects a slug that will not produce a valid id
+- create syncs to DashClaw with `x-api-key` (fake server on 127.0.0.1)
+- sync failure buffers to `unsynced.jsonl` and still exits 0
+- `sync` flushes the buffer
+- append refuses secret-looking values with exit 2 and writes nothing
+- update dies cleanly (exit 2) on a corrupt record
+- unknown subcommand exits 2
+- a corrupt record is skipped with a warning and does not brick `ACTIVE.md`
+
+**Added in the port:** append without a valid `--actor` exits 2;
+`readEvents(cardId)` merges writer files sorted by `ts`.
+
+**Dropped:** none. Assertions on `from`/`to`/`origin`/`lead` become assertions
+on `actor`/`card_id`/`station`/`leg`.
+
+**Why:** all thirteen encode behaviour Leg keeps.
+
+## git-snapshot.mjs
+
+**Ported** (→ `src/git-snapshot.mjs`, byte-identical apart from the two removals):
+read-only snapshot JSON (`branch`, `head`, `head_subject`, `dirty` counts and
+files with `--max-files` truncation, `submodules_dirty`, `recommendation`) and
+`--diff-since <ref>` (commits, changed files, insertions, deletions). Phase 5
+uses `--diff-since` to classify a leg that exited 0 with no DONE marker and no
+diff as `no_progress`; phase 7 uses the snapshot before landing.
+
+**Dropped:** the hard-coded private-path constant and its `dirty-check`
+recommendation branch. Recommendation is `branch` when clean, `worktree` when
+dirty.
+
+**Why:** the tool already does what the land station and the no-progress
+check need, and it never mutates the repo.
+
+## git-snapshot.test.mjs
+
+**Ported** (→ `test/git-snapshot.test.mjs`): clean repo → `branch`; dirty
+repo → `worktree` with exact counts; `--diff-since` across two commits; non-repo
+dir exits 2; 25 untracked files truncate at 20.
+
+**Dropped:** "private-path override … yields recommendation dirty-check", it
+asserts on a machine path that must not exist in this tree.
+
+**Why:** five of six tests are portable as-is.
+
+## invoke-capability.mjs
+
+**Ported** (as patterns, not code → `src/sync/dashclaw.mjs` in phase 9):
+- The argv-builder shape: a registry entry owns an `argv(input)` function that
+  returns a plain array, and `--dry-run` prints the exact command without
+  touching anything. Leg's `pr` land mode (`gh pr create` argv, stub-tested
+  only) and the DashClaw action recorder use this shape.
+- Fail-closed: no config → do nothing and say so; a 4xx/5xx or a timeout never
+  turns into "executed". Leg's optional syncs are off by default and a sync
+  failure never changes a card's state.
+
+**Dropped:** the capability registry (`post-to-x`, `send-email`), the
+approval-polling loop, agent identities, `REPO_ROOT`-relative wrapper paths,
+and the global `fetch` client (LESSONS 07-12: Node 24 on Windows can crash at
+exit after global fetch; the ledger already uses native `http`/`https`).
+
+**Why:** exactly the verdict the plan expected: nothing to port but the two
+shapes. Leg records actions; it does not gate external capabilities.
+
+## LESSONS.md
+
+Each applicable line becomes a named test in `test/lessons.test.mjs` (phase 4).
+Lines that only concern X/OAuth, the OpenClaw gateway, Vercel, or the weekly
+drill do not apply and are omitted.
+
+| lesson | Leg test name |
+|--------|-----------------|
+| 07-09 MSYS mangles leading-slash args | `lessons: every git spawn carries MSYS_NO_PATHCONV=1 and never a shell` |
+| 07-10 `claude -p --output-format json` prints nothing until the end | `lessons: stall detector reads out/err file mtime, never waits on stdout` |
+| 07-10 acceptEdits silently denies tools outside `--allowedTools` | `lessons: claude argv carries no --allowedTools and never disallows Agent` |
+| 07-11 `bash` under some PATHs is the WSL shim and drops variables | `lessons: no adapter spawn sets shell:true; argv[0] is node or a native exe` |
+| 07-11 every ledger write from your OWN identity only | `lessons: an event always lands in its own actor's events file` |
+| 07-11 a detached session cannot answer permission prompts | `lessons: CONTRACT.md tells the agent no interactive prompt will be answered` |
+| 07-12 Node 24 + global fetch crashes at exit | `lessons: src/ has no global fetch call` |
+| 07-13 codex exec may start read-only despite the flag | `lessons: codex argv carries -s workspace-write and -C <worktree>; phase 3 records the effective sandbox` |
+| 07-13 `node --test <dir>` fails on Node 24/Windows | `lessons: package.json test script is bare node --test` |
+| 07-13 `[hidden]` loses to an author `display:` rule | `lessons: board CSS ships [hidden]{display:none!important}` |
+| 08-10 enumerate the interface from source before building | `lessons: cli-contracts.md carries a producing command for every CLI section` |
+| 08-10 relative doc paths silently no-op | `lessons: README links resolve to files in the tree` |
+| 08-11 two checkouts, wrong path built against | `lessons: card repo is resolved to its git toplevel before a worktree is created` |
+
+Thirteen tests. Phase 4 may add more if the port surfaces another line.
+
+## PROTOCOL.md
+
+**Ported** (as rules in `docs/cli-contracts.md`, the adapters, and the land
+station):
+- Codex sandbox ladder: `read-only` for review, `workspace-write` only when
+  edits are the deliverable, `danger-full-access` and
+  `--dangerously-bypass-approvals-and-sandbox` never (a chain entry naming one
+  refuses to launch). Blast radius: `-C <narrowest dir>` = the card's worktree.
+  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
+  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
+  on; slow, dead, or runaway legs are the supervisor's job (30 m notify, 90 m
+  kill); no secrets in any ledger field.
+- Model routing: a `claude -p` call that omits `--model` inherits the
+  interactive default. Leg lets the chain entry name the model and passes it
+  when present; the default is documented per CLI in `cli-contracts.md` rather
+  than hard-coded.
+
+**Dropped:** the two-agent classifier, lead/specialist roles, envelopes, the
+exchange cap, Telegram transport, DashClaw tiers and approvals (Leg's
+approvals are buttons on the board; DashClaw is an optional recorder), the
+`openclaw agent` transport.
+
+**Why:** the containment rules for Codex and the snapshot-then-diff workflow
+were written after real incidents and transfer unchanged. The protocol's
+coordination layer is what Leg replaces with a board.
+
+## context-handoff-bundle (the handoff format)
+
+**Reused as-is** (argv subprocess, never re-implemented): `save --title --slug
+--notes <file> --tag --repo-local [--update]`, `load [query] [--json]`,
+`validate <dir>`, `list`, `show`. The `--notes` file is the input Leg
+writes; its parser reads `## Scope`, `## Projects mentioned`, `## Findings`,
+`## Opportunities`, `## Open questions`, `## Evidence anchors` (bullets under
+each). Leg's mapping: Scope = the task and the leg that stopped; Findings =
+what was done (from `.leg/PROGRESS.md` and the diff); Open questions = why
+the leg stopped and what is unverified (a failing test lands here on a
+bounce); Evidence anchors = the changed files, so drift checks flag them.
+Bundles are saved `--repo-local` inside the worktree so the next agent finds
+them in its cwd. Storage: `.context-handoffs/index.json` in the worktree.
+`checkpoint` / `rescue` (hook-driven passive checkpoints) are not used.
+
+0.2.0's interactive sessions reuse the same seam rather than adding a second
+one: `src/bundle.mjs` imports `chb()` and `ensureExcluded()` from
+`src/handoff.mjs`, so the CLI stays the only writer of bundle files. The
+difference is one bundle per session, refreshed with `save --update <slug>`
+instead of one bundle per handoff.
+
+**Machine state (verified live 2026-09-10):** the CLI on PATH was 0.1.0 from
+the Store Python; PyPI and the source checkout are 0.4.0 (`--notes`,
+`--repo-local`, `--update`, drift). Phase 5 installed 0.4.0 from PyPI, then
+the local checkout in editable mode because 0.4.0 has no `--version` flag:
+the checkout gained `--version` and `tests/test_version.py` (76 upstream
+tests green, not pushed). `src/handoff.mjs` reads the version through
+`importlib.metadata` when the flag is absent, so a plain `pip install -U
+context-handoff-bundle` still works. Live-verified in phase 5: `save
+--repo-local --notes`, `validate`, `load`, `list --repo-only`, `show`.
+
+## project-launch-button-policy
+
+Adopted whole as phase 8's spec: `npm start` = `leg up`; boots, health-checks,
+opens the board, prefixed unified logs, Ctrl+C teardown, `--dry` and `down`
+modes, argv subprocesses only, secret redaction on stdout, refuses dangerous
+misconfiguration (a YOLO flag in a chain entry, a bind address off loopback
+without a token).