@ucsandman/legcli 0.14.0 → 0.15.0

package/docs/DECISIONS.md

@@ -2,6 +2,14 @@
 
 Durable product and design decisions that the code does not explain on its own. One entry per decision, newest first.
 
+## 2026-09-18: a second claude login shares the conversation store, so an account switch keeps the conversation
+
+- **What.** `LAYOUT.claude.share` gains `projects`: `leg accounts add claude <name>` junctions Claude Code's conversation store into the account directory beside the harness directories, and `refreshAccount()` adds a missing junction to an account made before this before every launch. `keepsConversation()` in `src/usage.mjs` is the one rule that decides `--resume` over the bundle, for the terminal's switch and the board picker's `keeps_conversation` alike: a same-login downshift (as before), or another login of the same agent under which the transcript file exists. The history index skips a junctioned `projects` so a conversation is listed once.
+- **Why share rather than copy.** Wes runs two 20x logins and wants a Fable or weekly wall on one to continue on the other without re-explaining anything. Copying the one transcript at hand-off would have to write into `~/.claude/projects` on the way back, and that directory is on the README's "read, never written" list. A junction inside `$LEG_HOME/accounts/` keeps that promise: Claude Code writes its own store, Leg reads it. It also carries the auto-memory under `projects/<cwd>/memory/`, which is the same human's and should follow them.
+- **Why the rule checks the file.** A `--resume` into a login that cannot see the transcript opens an empty conversation and loses the bundle too. So the rule asks whether the file exists under the destination home at the moment of the switch, and says bundle when it does not. A false answer costs one bundle prime; a wrong true would cost the context.
+- **Why a cross-login upshift resumes when a same-login upshift does not.** The same-login rule stays as decided on 2026-09-17: the re-read at the stronger model's rate is paid on the login that is already low. Across logins the destination is a fresh window, which is the reason the human bought it.
+- **What this rules out.** codex across logins: `codex resume` under a second `CODEX_HOME` is unobserved, so codex rungs keep taking the bundle and claim nothing.
+
 ## 2026-09-18: usage is polled by the board, once per login; a rung's model is a catalog entry validated by shape
 
 - **What.** The board process runs one usage poller per login (`src/usage-poll.mjs`): 60s, doubling to ten minutes on any refusal, one status line when a login's reading fails and one when it is back. Terminals poll nothing and receive the windows on their session record. `GET /api/models` lists what each installed CLI can run, read from claude's aliases, codex's `models_cache.json` and `config.toml`, and the `models` commands of agy and grok, cached an hour under `<LEG_HOME>/models/`. A rung's `model` is validated by shape (lower-case id characters) for every provider and by membership for claude only.

package/docs/DEVIATIONS.md

@@ -181,3 +181,36 @@ tests. Rows for the shape changes a later reader would otherwise wonder about.
 | 2026-09-14 | src/resume.mjs idle pointer | a checkpoint bundle was described as "the last hand-off", and the per-session file was named unconditionally | `lineage.to` decides hand-off vs checkpoint, and the file is named only when it exists on disk | seen in the live pointer for this repo: it claimed a hand-off that never happened and pointed at a `RESUME-<id>.md` that was never written, which is the same class of lie the module exists to stop |
 | 2026-09-14 | src/board/sessions.js `renderDrawer()` | the whole panel is rebuilt every 3 s poll so relative timestamps stay honest | still rebuilt, but every scrollable box carries a stable `data-scroll-key` and its offset is carried across | the rebuild reset the task box, each message and the timeline to the top every three seconds, so a long message could not be read at all |
 | 2026-09-17 | src/board/sessions.js `verdictLines()` | spec A.5 lists "a model bucket came back and a terminal is still downshifted" below the two branches that print a standing percentage | the came-back branch is tested before them, right after the model-walled branch | as written it can never fire: "one login carries every live terminal" and "several logins carry work" both return for any login that has a figure at all, so the only state change worth telling a downshifted reader about was unreachable |
+
+## 2026-09-18: product, performance and architecture pass (0.15.0)
+
+Measured first (`scratchpad/prof/BASELINE.md`, reproduction commands in the
+CHANGELOG entry), then changed. Rows for the shape changes a later reader
+would otherwise wonder about; the designs not built are in
+`docs/review-2026-09-18.md`.
+
+| date | file | old shape | new shape | why |
+|------|------|-----------|-----------|-----|
+| 2026-09-18 | src/accounts.mjs, src/usage.mjs, src/attach.mjs, src/server.mjs | a hand-off to a second claude login always took the bundle; only a same-login downshift kept the conversation | the account junctions claude's `projects` store; one rule, `keepsConversation()`, decides for the terminal and the picker, and checks the transcript file is reachable under the destination home at the switch | a second 20x login should continue the conversation, not re-read it from a bundle; the junction keeps "~/.claude/projects: read, never written" true |
+| 2026-09-18 | src/history/providers/claude.mjs | every claude home was scanned, junction or not | a home whose `projects` is a link is skipped and reported `shared: true` | the same transcript listed twice from two logins |
+| 2026-09-18 | src/digest.mjs, bin/leg.mjs, src/server.mjs | nothing read the records back as an answer to a person; the audit trail was a flat list | `leg digest [--since]` and `GET /api/digest` (owner only): volume first, what needs you, per repository, walls standing now | the question after eight hours away had no reader; a window with nothing in it must print its counts, not a blank |
+| 2026-09-18 | bin/leg.mjs | 26 static imports; the agent dispatch first; `parseTarget` synchronous | one `await import()` per command group, inside its branch; the agent dispatch after every named group; `parseTarget` async and loads buckets/accounts only for a two-part target | `leg --version` loaded 68 modules for one readFileSync: 117 ms wall, 79 ms CPU, 254 fs calls; now 1 module, 52 ms, 4 fs calls |
+| 2026-09-18 | src/limits.mjs | `SIGNALS = loadSignals()` at import (24 fixture reads, one RegExp each) | a Proxy over the same array that loads on first property access | every command paid for the fixture tree; test/ and scripts/limits-table.mjs read `SIGNALS.length` at their own top level, so a loader function was not an option |
+| 2026-09-18 | src/scheduler-status.mjs (new), src/scheduler.mjs, src/launcher.mjs | `pidfile`, `schedulerStatus`, `MAX_CONCURRENT` lived in scheduler.mjs | a leaf module, re-exported from scheduler.mjs | the launcher pulled orchestrator, land, mergequeue, stations, chain, runner and limits to answer "is the scheduler running" |
+| 2026-09-18 | src/git.mjs (new), src/attach.mjs, src/bundle.mjs | six git processes per poll round (three `rev-parse`, `status --porcelain`, `@{upstream}`, `rev-list --count`), each wrapper private, no timeout, no maxBuffer | one `status --porcelain=v2 --branch` carries head, branch, upstream, ahead/behind and the dirty list; `aheadFromStatus` uses `# branch.ab` or a one-pair head cache; 20 s timeout, 8 MB buffer | an idle terminal spawned 59.5 git processes a minute and blocked its own loop 4.4 to 10.3 s/min; now 10.9/min and 2.1 s/min, CPU 1.7 to 0.1 s/min |
+| 2026-09-18 | src/git.mjs parseStatus | a rename printed the old and new names with the quotes half-stripped | the new name | the file on disk is the one a human recognises; pinned in test/git-status.test.mjs |
+| 2026-09-18 | src/attach.mjs ensureBoard | polled /api/health every 200 ms for up to 15 s before the agent got its first instruction | `wait: false` for a terminal: the agent starts at once, the wait runs behind it, `claimBoardBeforeExit` (2 s at most) still writes the pidfile before a sub-second session exits; `leg share on|off` keeps the blocking form | the one terminal of the day that starts the board waited ~790 ms doing nothing (to-agent 1,280 to 261 ms); a board without a pidfile is one `leg down` cannot stop |
+| 2026-09-18 | src/attach.mjs installedAgents | a `--version` subprocess per bare-name agent per launch, 8 s timeout each | `$LEG_HOME/installed.json`, one day per resolved bin; a `*_BIN` override is asked every time and never cached | a stub pointed at on purpose must be probed; a real CLI on PATH answers the same for a day |
+| 2026-09-18 | src/bundle.mjs, src/handoff.mjs, src/attach.mjs | the periodic checkpoint ran `chb save` synchronously inside the poll tick | `saveSessionBundleAsync` (execFile), one at a time through `checkpointGate`, awaited before the hand-off save; warning, limit and hand-off saves stay synchronous | a python subprocess with a 120 s timeout froze limit detection and every board button for its whole run |
+| 2026-09-18 | src/handoff.mjs | `scrub` imported from runner.mjs | from redact.mjs | the terminal path pulled the card runner's whole graph for one function |
+| 2026-09-18 | src/sessions.mjs updateSession | `withFileLock` defaults: past 1.2 s the read-modify-write ran unlocked | `retries: 250, staleMs: 10000`, run.json's budget | the most-written file in Leg (runner poll, claude hook, usage poller, board actions, every `leg` command); losing a patch is the race the lock exists for |
+| 2026-09-18 | src/sessions.mjs, src/attach.mjs | `rmSync(control.json)` at exit | `clearControl` under `.control.lock` | a bare unlink could delete a board request mid-write |
+| 2026-09-18 | src/attach.mjs | the 12-leg stop said "run leg again in this directory to continue from the bundle" | names the bundle path and `leg resume`; says a fresh `leg <agent>` does not load it | nothing reloads a bundle on a fresh launch; the line promised a hand-off that never happened |
+| 2026-09-18 | src/server.mjs health tick | `pushSessions()` unconditionally every 10 s per client | the stat fingerprint decides; a liveness pass (`reapLost`) runs on the tick because a dead runner moves no file; a card entering or leaving a human-waiting status forces one push | an idle board with 43 terminals did 7,294 fs calls, 8 git processes and 1.1 CPU s a minute for nothing; the first cut of this lost the dead-runner case, and the test that kills a real child now pins it |
+| 2026-09-18 | src/server.mjs sessionsView | `readUsage` per rung per terminal, again for `capacity`, again for the accounts payload (143 reads per answer) | one reader per view | a login is read at most once per answer, and every part of the answer comes from the same reading |
+| 2026-09-18 | src/synthesis.mjs | three `existsSync` per terminal per view | one `readdirSync` per checkout per view (`sessionFileIndex`) | 172 of 512 fs calls per answer, for files that mostly do not exist |
+| 2026-09-18 | src/server.mjs, src/history/worktrees.mjs | `/api/worktrees` ran up to 40 git processes synchronously on the board's loop (9 to 25 s cold) | `listWorktreesAsync` (execFile, four in flight), one refresh per query, the last list served while a refresh runs | the worst `/api/health` during a cold call fell from 11.8 s to 3.2 s; the rest is `listHistory` inside `gather()`, still synchronous |
+| 2026-09-18 | src/server.mjs /api/trunk | every card ledger read on every 2 s floor poll | a 15 s cache keyed by the window, cleared by any card change and by a landing | 27.5 to 0.5 ms p50, 113 to 15 fs calls per request |
+| 2026-09-18 | src/session-detail.mjs | one `git ls-files` per file the terminal touched, every 3 s the drawer is open | one `git ls-files -z -- <paths>` for the list | 7 to 2 processes per detail answer, 1,247 to 305 ms |
+| 2026-09-18 | src/server.mjs rows | every field of session.json on every push | `argv`, `runner_pid`, `head_at_start`, `checkpoints`, `agent_sessions`, `runtime_capabilities`, `files_touched` dropped from the row; `GET /api/sessions/<id>` still hands over the record | nothing under src/board/ read them; 8% off every push |
+| 2026-09-18 | src/history/worktrees.mjs | the git env built by a helper | `MSYS_NO_PATHCONV: '1'` spelled out at each spawn site | test/lessons.test.mjs checks every git spawn line in src/ for it, and the helper hid it from that check |

package/docs/ERRORS.md

@@ -21,7 +21,7 @@ and "CI green" after a push means the run, not the publish; `npm view
 **Fixed by deploying from the repo root with a root `.vercelignore` and
 `--archive=tgz`; the recipe is in DECISIONS.md under "the site deploys itself
 from git".** The `--yes` also auto-created an empty Vercel project named `leg`
-that still needs `vercel project rm leg`. The lesson: on a project with a Root
+that still needs `vercel project rm leg` (2026-09-18 later: `vercel project ls` no longer lists a `leg` project, so it is gone). The lesson: on a project with a Root
 Directory set, the CLI must run from the repo root, and `--yes` is a consent to
 create projects, not only to skip a confirmation.
 

package/docs/ROADMAP-v2.md

@@ -86,7 +86,18 @@ event names its actor, a board that reads only the ledger, and an auth/bind seam
    The same probe shape applies to naming the terminal tab: whether codex, agy
    and grok leave an OSC 2 title alone once the child starts drawing is
    assumed, not known, which is why the tab title is the browser's and not the
-   terminal's.
+   terminal's. 0.15.0 made the claude half of this real across logins too (a
+   second login shares the conversation store, so a login switch keeps the
+   conversation): the codex probe now also covers a second `CODEX_HOME` with
+   its `sessions` store shared the same way.
+7. **`stalled` and `repeating` on the row.** Two derived states from data the
+   record already holds: no turn, file write or commit for N minutes while not
+   waiting on a human; the same test red across two legs of one card. Printed
+   only, never acted on; a `looping` state waits for a false-positive study on
+   real transcripts. Design in `docs/review-2026-09-18.md`.
+8. **The digest on the board.** `leg digest` and `/api/digest` shipped in
+   0.15.0; the panel above Terminals on the first load of the day is the
+   human surface it still lacks. Same review doc.
 
 Also on the list: per-station prompt templates editable from the board, lease
 suggestions from the diff of the previous leg, and a floor view that shows

package/docs/concepts.md

@@ -19,7 +19,7 @@ Each session gets a directory under `$LEG_HOME/sessions/<id>/`
 
 | file | what it holds |
 |------|---------------|
-| `session.json` | the live record the board renders; the runner is its only writer, and every write is one atomic replace |
+| `session.json` | the live record the board renders. The runner owns it, and the board's usage poller, Claude Code's hooks and a board action patch fields on it too; every write is one atomic replace under `.session.lock` (`updateSession`), so no writer can lose another's field |
 | `events.jsonl` | the timeline (see [VOCABULARY.md](VOCABULARY.md#session-event-types)) |
 | `control.json` | requests from the board to the runner, for example `{ handoff: true }` |
 | `hook.log` | what Claude Code's hooks sent, claude sessions only |
@@ -70,12 +70,17 @@ override, so agy stays one account.
 Your harness is shared into an extra account, never copied into a fork that
 drifts: the directories are junctions back to the real home (claude: `hooks`,
 `skills`, `agents`, `commands`, `plugins`, `rules`, `scripts`,
-`output-styles`, `tools`; codex: `skills`, `prompts`, `rules`, `plugins`,
-`agents`, `hooks`, `memories`, `superpowers`), and the settings files are
-copied fresh before every launch (claude: `settings.json`,
+`output-styles`, `tools`, `projects`; codex: `skills`, `prompts`, `rules`,
+`plugins`, `agents`, `hooks`, `memories`, `superpowers`), and the settings
+files are copied fresh before every launch (claude: `settings.json`,
 `settings.local.json`, `CLAUDE.md`, `keybindings.json`, `statusline.ps1`,
 `statusline-combined.ps1`; codex: `config.toml`, `AGENTS.md`). Only the login
-itself lives in the account directory.
+itself lives in the account directory. claude's `projects` is its
+conversation store, shared so that a hand-off to the second login can
+`--resume` the transcript the first one was writing (see Handoff, step 3) and
+so the same human's auto-memory follows them; `refreshAccount()` adds a
+junction an older account is missing before every launch, and the history
+index skips a junctioned store so a conversation is listed once.
 
 `leg accounts add <claude|codex> <name>` creates one and prints the single
 line to paste to log in. `leg accounts rm` removes the junctions as links,
@@ -161,7 +166,10 @@ in that picker ("the next option in the order") is still a press of the button.
    `context-handoff-bundle save --repo-local --slug leg-<session id>`, with
    `--update <slug>` after the first time, so one bundle per session is updated
    in place. A checkpoint runs about every two minutes while the session has
-   turns, and at every warning, limit and hand-off.
+   turns, and at every warning, limit and hand-off. The periodic checkpoint runs
+   beside the terminal's poll rather than inside it, one at a time, so a slow
+   save never stops the terminal noticing a limit or a board button; a warning,
+   a limit and a hand-off save are still finished before the next leg starts.
 2. **Choose.** `candidates()` lists the other accounts of the same agent first,
    then walks the ladder, and after each rung, the other accounts of that
    rung's agent. `evaluateLadder()` walks that list top to bottom and takes the
@@ -191,14 +199,22 @@ in that picker ("the next option in the order") is still a press of the button.
    ladder for an active terminal; the wrapper reads 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. A
-   same-login move to a weaker claude model (a downshift, by the
-   `fable, opus, sonnet, haiku` order) with the agent's own session id on the
-   record keeps the conversation instead: Leg runs
-   `claude --resume <agent_session_id> --model <alias>`, no bundle is written
-   into a prompt, and the ledger says so. Every other rung, including an
-   upshift back to a stronger model, a different account, or a different
-   agent, takes the bundle: the `context-handoff-bundle load <id>` output
+3. **Switch.** The agent process is stopped and the terminal restored. Two
+   claude moves keep the conversation instead of taking the bundle, decided by
+   one rule both the terminal and the board's picker read
+   (`keepsConversation()` in `src/usage.mjs`): a same-login move to a weaker
+   model (a downshift, by the `fable, opus, sonnet, haiku` order), which runs
+   `claude --resume <agent_session_id> --model <alias>`; and a move to another
+   claude login whose home can see the transcript through its `projects`
+   junction, which runs `claude --resume <agent_session_id>` under that
+   login's `CLAUDE_CONFIG_DIR` (with `--model` only when the rung names one).
+   Both need the agent's own session id on the record; the second also needs
+   the transcript file to exist under the destination home, checked at the
+   switch, so a login made before the junction existed takes the bundle until
+   its next launch adds it. No bundle is written into a prompt, and the
+   ledger says `kept the conversation`. Every other rung, including a
+   same-login upshift back to a stronger model or a different agent, takes
+   the bundle: the `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
@@ -314,6 +330,28 @@ on:
 `leg share off` puts the board back on `127.0.0.1` and every link stops
 working; `leg share rotate <name>` replaces one.
 
+## The digest
+
+`leg digest [--since 8h|2d|<iso>] [--json]` and `GET /api/digest?since=`
+(owner only) answer the question a person asks after eight hours away
+(`src/digest.mjs`). It reads the session records, their `events.jsonl`, the
+cards' ledgers, `landings.jsonl` and the usage records, and writes nothing.
+The record is `{ since, until, volume, attention, repos, walls }`: `volume`
+is what was read (terminals, cards, landings and events in the window, and
+the sessions and cards on disk), printed on the first line so a quiet night
+and an empty home cannot read the same; `attention` is what needs a person,
+ranked (a live terminal waiting on a question, a card in `waiting_human`,
+`needs_approval` or `paused`, a card that failed in the window, a terminal
+that was lost in the window); `repos` groups every terminal that moved or is
+live, every card that moved or is live, and every landing, by repository;
+`walls` is every login and every model that is out right now, soonest reset
+first. A terminal counts when it moved in the window or is live now, and its
+entry carries the events worth a line (`limit`, `handoff`, `all_out`,
+`lost`, `ended`, `landed`, `bounced`, `continued`, `harness_blocked`), never
+the running commentary. The audit trail ([Share](#share-more-than-one-human))
+is the same data as a flat list of actors; the digest is the same data
+grouped by what to do about it.
+
 ## Cards, stations and pipelines
 
 A **card is a terminal you are not sitting at.** It has the same register

package/docs/configuration.md

@@ -35,7 +35,7 @@ These apply to `leg claude|codex|agy|grok`.
 | `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` |
 | `LEG_USAGE_POLL_MS` | `60000` | how often the board asks each login's usage source (one poller per login, not one per terminal); Claude uses its usage endpoint, Codex read-only app-server rate limits, Grok its billing proxy | `src/usage-poll.mjs` |
 | `LEG_USAGE_POLL_MAX_MS` | `600000` | the longest the board waits between readings for one login: a refusal (429, timeout, no login) doubles the wait up to this, and the first good reading puts it back to `LEG_USAGE_POLL_MS` | `src/usage-poll.mjs` |
-| `LEG_ATTACH_POLL_MS` | `2000` | how often the session loop re-reads the taps; git is re-read every third poll | `src/attach.mjs` |
+| `LEG_ATTACH_POLL_MS` | `2000` | how often the session loop re-reads the taps; git is re-read every third poll, as one `git status --porcelain=v2 --branch` (`src/git.mjs`) that carries the head, the branch, the dirty list and the upstream's own ahead count | `src/attach.mjs` |
 | `LEG_CLAUDE_USAGE_URL` | `https://api.anthropic.com/api/oauth/usage` | the usage endpoint, for a test double | `src/taps/claude-usage.mjs` |
 | `LEG_CLAUDE_ARGS`, `LEG_CODEX_ARGS`, `LEG_AGY_ARGS` | (none) | space-separated extra arguments for a leg Leg starts on its own after a hand-off (your own `leg <agent> …` args never apply to the next agent); e.g. `LEG_CODEX_ARGS="-m gpt-5.3-codex-spark"` keeps a test chain on cheap models | `src/attach.mjs` |
 | `LEG_LIVE_DIR` | `fixtures/live/` in a dev clone, else `~/.leg/live/` | where the first real limit payload per agent and signal is kept, secrets scrubbed (`src/live-capture.mjs`); a `leg sessions simulate-limit` payload is never kept | `src/live-capture.mjs`, `scripts/live-limits.mjs` |
@@ -133,7 +133,7 @@ permission, so it is always on.
 
 | variable | default | meaning | read in |
 |----------|---------|---------|---------|
-| `LEG_HOME` | `~/.leg` | where sessions, usage, accounts, cards, runs and the pidfiles live | `src/store.mjs`, `src/ledger.mjs`, `src/runner.mjs`, `src/worktree.mjs`, `src/cards.mjs`, `src/sessions.mjs`, `src/usage.mjs`, `src/accounts.mjs` |
+| `LEG_HOME` | `~/.leg` | where sessions, usage, accounts, cards, runs, the pidfiles and `installed.json` (which agent CLIs answered `--version`, remembered for a day per resolved bin) live | `src/store.mjs`, `src/ledger.mjs`, `src/runner.mjs`, `src/worktree.mjs`, `src/cards.mjs`, `src/sessions.mjs`, `src/usage.mjs`, `src/accounts.mjs` |
 | `LEG_PORT` | `4747` | board server port | `src/server.mjs`, `src/launcher.mjs`, `bin/leg.mjs` (`open`) |
 | `LEG_BIND` | `127.0.0.1` | board server bind address | `src/server.mjs`, `src/launcher.mjs` |
 | `LEG_TOKEN` | (none) | bearer token required for `/api/*` and the event stream once set | `src/server.mjs`, `src/auth.mjs` |
@@ -205,7 +205,9 @@ home. `src/accounts.mjs` `LAYOUT` is the whole definition.
   accounts.json                     the named accounts per agent
   accounts/claude/<name>/
     hooks/ skills/ agents/ commands/ plugins/ rules/ scripts/
-    output-styles/ tools/           junctions back to ~/.claude
+    output-styles/ tools/ projects/ junctions back to ~/.claude (projects is
+                                    the conversation store: a hand-off to this
+                                    login can --resume the same transcript)
     settings.json settings.local.json CLAUDE.md keybindings.json
     statusline.ps1 statusline-combined.ps1
                                     copies, refreshed before every launch

package/docs/review-2026-09-18.md

@@ -0,0 +1,172 @@
+# Review notes, 2026-09-18: product, performance and architecture pass
+
+A requested first-principles pass over Leg as a product and as a program.
+Working file, not published to the docs site. What shipped from it is in
+`CHANGELOG.md` (0.15.0); what did not is designed here so the next pass can
+pick it up without re-deriving it. Measurements are from
+`scratchpad/prof/BASELINE.md` (kept out of the repo) and are summarised in
+the CHANGELOG entry with their reproduction commands.
+
+## What Leg is, and what it should become
+
+Today Leg is a usage-wall relay: the same terminal keeps going when a login
+stops. Around that wedge a lot arrived in one week: rungs of (agent, login,
+model), a board, cards and pipelines, a machine-wide history index, a
+portable harness, a shared board with roles and an audit trail. The wedge is
+still the identity, and the reviews agree on the two things that make it
+more than a relay:
+
+1. **The terminal should never lose its conversation.** A same-login
+   downshift already kept it. 0.15.0 keeps it across logins too (the
+   `projects` junction plus one `keepsConversation` rule). The remaining gap
+   is codex across logins, unprobed.
+2. **Leg holds the record of everything every agent did on this machine**,
+   and until 0.15.0 nothing read it back as an answer to a person. `leg
+   digest` is the first reader. The audit trail was the second-last.
+
+Where it should go, in one sentence: from "a relay that keeps the terminal
+alive" to "the layer that knows what every agent is doing, what it cost, and
+what needs a person, and never loses the thread". Not an orchestrator that
+invents work; a control layer over work the human started.
+
+## Gaps found, ranked
+
+| gap | evidence | status |
+|---|---|---|
+| a second login of the same vendor lost the conversation | `isDownshift` required the same account | **shipped 0.15.0** |
+| nothing summarised what happened while you were away | audit trail is a flat list; ledger counts on the board | **shipped 0.15.0** (`leg digest`) |
+| an idle terminal spent ~60 git processes a minute | `gitInfo` + `aheadCount` every 6 s | **shipped 0.15.0** (one `status --porcelain=v2 --branch`) |
+| the board rebuilt its whole view every 10 s for nothing | health timer bypassed the fingerprint | **shipped 0.15.0** |
+| every command loaded 68 modules, `--version` included | eager imports in `bin/leg.mjs`, two gratuitous edges | **shipped 0.15.0** |
+| the checkpoint bundle froze limit detection for the length of a python spawn | sync `chb save` inside the poll interval | **shipped 0.15.0** |
+| `.leg/DONE` is self-reported; a card is `completed` on the agent's word | `classify()` rule 6 | designed below (verify the claim) |
+| a wedged agent looks like a thinking one; a loop burns the ladder | no stall/loop signal beyond `quiet Nm` | designed below |
+| every new session re-learns the repository | SYNTHESIS dies with its session | designed below (project brain) |
+| cards and terminals are two substrates for one idea | two stores, two status vocabularies, two hand-off loops | designed below (one leg primitive) |
+| every ledger write is a Node process (85–114 ms) | `execFileSync(node, ledger.mjs)` per event | designed below |
+| `codex resume <id> -m <model>` and a second `CODEX_HOME` unprobed | roadmap item 6 | still open |
+
+## Designs for what was not built
+
+### Verify the claim (cards)
+
+`classify()` rule 6 says exit 0 plus `.leg/DONE` is `completed`. Add a
+`verify` policy on the card (`test|none`, default `test` for pipelines with
+no `test` station, else `none` because the station already runs it): on
+`completed`, run `resolveTestCommand(repo)` in the worktree with the land
+timeout, record `{ verified: 'green'|'red'|'untested', command, tail, at }`
+on the run, and treat `red` as `incomplete` (hands off with the tail in the
+bundle's Open questions). A DONE with an empty diff stays `completed`: an
+analysis card legitimately changes nothing, so a zero diff is not evidence
+of a lie. Surface: the card row's sentence (`claimed done; tests red (3
+failures)`), `leg card show`. Tests: a fake adapter writing DONE with green,
+red and no test command. Not built now because the plain `build` preset is
+the one place it applies and the `build-land` preset already verifies.
+
+### Stalled, looping, repeating
+
+Three derived states, printed only from measured facts:
+
+- `stalled`: live, not waiting on a human, and no turn, no file write and no
+  commit for N minutes (N per agent, default 12). Data: `last_activity`,
+  `files_touched`, `head`. The row says `stalled 14m` where it says `quiet
+  14m` today; the head count includes it.
+- `looping`: the same (tool, path) or the same normalised error line three
+  times in the last 40 transcript-tail entries (`messagesFromLines` exists).
+  Row: `looping: Edit src/server.mjs 4x in 6m`. Never automatic action; a
+  Hand off now button already sits beside it.
+- `repeating`: the same test name red across two legs of one card
+  (`bounce_reason` history). Stops the chain instead of spending the next
+  rung, the way `LEG_MAX_LAND_ATTEMPTS` already caps landings.
+
+Not built now: `looping` needs a false-positive study on real transcripts
+before it can print anything ("print nothing rather than a wrong number").
+`stalled` and `repeating` are a day each and should come first.
+
+### The project brain
+
+`<repo>/.leg/BRAIN.md`, written by Leg's code and never by an agent turn:
+decisions (dated, with who decided), ruled-out approaches, invariants (from
+`CLAUDE.md`/`AGENTS.md`), hot files (from `files_touched` frequency) and open
+questions. At hand-off the session's SYNTHESIS delta merges into it; every
+first prompt of a leg and every card contract opens with its invariants and
+ruled-out list before the bundle dump. `leg brain` prints it, `leg brain
+--check` reports staleness like `leg resume --check`, `leg decide "<text>"`
+appends. It subsumes `.leg/SYNTHESIS-<id>.md` as the per-session delta. Not
+built now because it is a new file in the human's repository with a format
+that has to be right the first time; it deserves its own pass with the
+synthesis schema's authors.
+
+### One leg primitive
+
+The terminal loop (`src/attach.mjs`) and the card loop
+(`src/orchestrator.mjs` + `src/chain.mjs`) do the same four steps: bundle,
+choose next, switch, wait. What differs is real: the terminal chooses from
+live usage at hand-off time and keeps one TTY; the card walks a static chain
+and classifies post-mortem. The extractable pieces with no semantic change
+are `bundle → prompt` and `prepare harness → proceed?` as shared functions,
+and a per-agent tap table (`PER_AGENT[agent].poll(session, ctx) → patch`)
+so a fifth agent is a table row. Making a card's chain a ladder evaluated at
+hand-off time is the product decision that would unify the rest; it belongs
+in the roadmap, not in a refactor.
+
+### In-process ledger writes
+
+`src/store.mjs` spawns `node src/ledger.mjs` per event (85 ms append, 114 ms
+update; a scheduler tick that newly blocks six cards spends 487 ms in six of
+them). The single-writer rule is a file lock (`.card.lock`), not a process
+boundary, so the functions can be exported and called in-process. Three
+things make it a refactor: `die()` exits, `assertNoSecrets` exits on a
+secret-looking summary (in-process that must throw, never take the board
+down), and `syncNotify` is async. Also `writeActive()` rescans every
+`card.json` on every write and should be debounced. Not built now: medium
+risk on the card path, which is the v0.1 extra, and the terminal path never
+touches it.
+
+### One event schema
+
+Sessions have ~24 event types, cards 28 (`ledger.mjs EVENT_TYPES`), with
+different actor shapes. `audit.mjs` and `digest.mjs` both merge the two by
+hand. One `{ v, ts, subject:{kind,id}, actor, type, summary, measured }`
+line format would let the audit, the digest, a future `leg events --follow`
+and an outside subscriber read one stream. Do it when a third reader
+appears.
+
+## Rejected, with the reason
+
+- **Answering a permission prompt from the board.** `stdio: 'inherit'` is
+  the architecture; a PTY between the human and their agent breaks "the same
+  agent you always run".
+- **Routing by headroom instead of rung order.** "Rung 1 first, every time"
+  is the contract the ladder editor teaches; a sort by headroom makes the
+  next destination unpredictable. A `when: below:N` rung already expresses
+  the honest version.
+- **Inferred workflows and automatic undo.** A recipe guessed from three
+  observations is a wrong number with a button; undoing a leg destroys work
+  that may be the only copy.
+- **Marking a DONE with no diff as a false claim.** An analysis task changes
+  nothing and is still done.
+- **Pooling a team's logins as one capacity market.** The README's terms
+  section draws the same-vendor line at an explicit human act.
+
+## What Leg must never do without a human
+
+Spend credits (`may_spend` off); push or open a PR; write a settings file
+outside `leg harness enable`'s owned regions; move a credential; delete a
+worktree with uncommitted work or an unmerged branch; pick a second login of
+the same vendor the human did not add; read message bodies wholesale into an
+index; send anything off the machine; answer a permission prompt; print a
+number it does not have.
+
+## Next three moves
+
+1. **Probe codex across logins**: `codex resume <id> -m <model>` under a
+   second `CODEX_HOME` with the `sessions` store junctioned the way
+   `projects` now is for claude. One live run settles whether the second
+   `keepsConversation` case can include codex.
+2. **`stalled` and `repeating`** as above: two derived states from data
+   already on the record, each with a fixture-driven test, no automatic
+   action.
+3. **A digest panel on the board** above Terminals on the first load of the
+   day, dismissible, fed by `/api/digest`; the CLI and the route exist, the
+   board is the human surface.

package/fixtures/verified.json

@@ -2,7 +2,7 @@
   "_comment": "The single source of truth for every dated, numbered claim Leg makes in public. scripts/check-claims.mjs asserts that each surface listed here states exactly these values, and --strict additionally compares the pinned CLI versions against what those CLIs currently publish. Re-verify on a real machine, then edit this file and every surface in the same commit.",
   "verifiedOn": "2026-09-11",
   "verifiedOnLong": "11 September 2026",
-  "tests": 926,
+  "tests": 955,
   "clis": {
     "claude": {
       "label": "Claude Code",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ucsandman/legcli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Usage-limit monitor and automatic handoff for Claude Code, Codex, agy and Grok. Type leg claude|codex|agy|grok and get the same interactive agent with a board alongside, auto-approve on by default, usage tracking per agent and account, a live context handoff bundle, and at the limit the next agent continuing in the same terminal. 14-day free trial, then $79 once, 30-day money-back guarantee.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/src/accounts.mjs

@@ -6,8 +6,8 @@
 // back into it with directory junctions, and the settings file is refreshed
 // from the real home before every launch. Only the login lives in the
 // account dir. agy 1.2.0 has no config-dir override, so it stays one account.
-import { existsSync, mkdirSync, readFileSync, copyFileSync, readdirSync, lstatSync, symlinkSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
+import { existsSync, mkdirSync, readFileSync, copyFileSync, readdirSync, lstatSync, symlinkSync, rmSync, realpathSync } from 'node:fs'
+import { join, relative, dirname, basename, resolve, isAbsolute } from 'node:path'
 import { homedir } from 'node:os'
 import { home } from './store.mjs'
 import { writeJsonAtomic } from './fsx.mjs'
@@ -19,7 +19,12 @@ export const LAYOUT = {
   claude: {
     env: 'CLAUDE_CONFIG_DIR',
     home: () => process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'),
-    share: ['hooks', 'skills', 'agents', 'commands', 'plugins', 'rules', 'scripts', 'output-styles', 'tools'],
+    // `projects` is the conversation store (projects/<encoded cwd>/<id>.jsonl,
+    // and the auto-memory beside it). Shared, not copied, so a hand-off to the
+    // second login can run `claude --resume <id>` on the transcript the first
+    // login was writing, and the same human's memory follows them. Claude Code
+    // does the writing; Leg reads that directory and never writes it.
+    share: ['hooks', 'skills', 'agents', 'commands', 'plugins', 'rules', 'scripts', 'output-styles', 'tools', 'projects'],
     copy: ['settings.json', 'settings.local.json', 'CLAUDE.md', 'keybindings.json', 'statusline.ps1', 'statusline-combined.ps1'],
     login: (dir) => `$env:CLAUDE_CONFIG_DIR='${dir}'; claude auth login`,
   },
@@ -73,6 +78,45 @@ export function envFor(agent, account) {
   return { [l.env]: accountDir(agent, account) }
 }
 
+// The config directory a login runs from: the CLI's own home for `default`,
+// the account directory for anything else. Null for an agent Leg does not know.
+export function homeFor(agent, account = 'default') {
+  const l = LAYOUT[agent]
+  if (!l) return null
+  return account === 'default' ? l.home() : accountDir(agent, account)
+}
+
+// Whether the conversation file one login was writing is visible to another
+// login of the same agent: the transcript's path relative to the source home
+// must exist under the destination home. True through the `projects` junction
+// an account carries; false for an account made before that junction existed
+// (until its next launch adds it), for a transcript outside the source home,
+// and for an agent with no per-account home at all. A false answer means the
+// bundle, never a `--resume` that would open an empty conversation.
+export function transcriptReachable(agent, transcriptPath, { from = 'default', to = 'default' } = {}) {
+  if (!transcriptPath || from === to || !LAYOUT[agent]?.env) return false
+  const dst = homeFor(agent, to)
+  if (!dst) return false
+  const where = realDir(dirname(transcriptPath))
+  // the transcript's place inside whichever home really holds it: the source
+  // login's, the destination's, or the CLI's own. A path a CLI reported through
+  // an account's junction resolves to the real home, and a record that kept
+  // the first login's path while the terminal moved on is still one file.
+  for (const account of new Set([from, to, 'default'])) {
+    const h = homeFor(agent, account)
+    if (!h) continue
+    const rel = relative(realDir(h), where)
+    if (rel.startsWith('..') || isAbsolute(rel)) continue
+    return existsSync(join(dst, rel, basename(transcriptPath)))
+  }
+  return false
+}
+
+// A directory's real path, for comparing a transcript's location against a
+// home that may itself be reached through a junction; the path as given when
+// it does not exist.
+function realDir(p) { try { return realpathSync.native(p) } catch { return resolve(p) } }
+
 function junction(target, link) {
   if (existsSync(link)) return false
   if (!existsSync(target)) return false
@@ -80,6 +124,22 @@ function junction(target, link) {
   return true
 }
 
+// The shared directories, junctioned into the account dir when they are not
+// there yet. Runs at creation and before every launch, so an account made by
+// an older Leg picks up a directory added to `share` since (the `projects`
+// store, for one) the next time it starts.
+export function ensureShared(agent, name) {
+  if (name === 'default') return []
+  const l = LAYOUT[agent]
+  if (!l?.env) return []
+  const dir = accountDir(agent, name)
+  if (!existsSync(dir)) return []
+  const src = l.home()
+  const shared = []
+  for (const d of l.share) if (junction(join(src, d), join(dir, d))) shared.push(d)
+  return shared
+}
+
 // Create the account dir, junction the shared harness in, copy the settings.
 export function addAccount(agent, name) {
   if (!NAME_RE.test(name) || name === 'default') throw new Error(`invalid account name "${name}" (letters, digits, - and _; not "default")`)
@@ -88,9 +148,7 @@ export function addAccount(agent, name) {
   if (!l.env) throw new Error(`${agent} has no config-dir override in the installed version; extra accounts are not possible`)
   const dir = accountDir(agent, name)
   mkdirSync(dir, { recursive: true })
-  const src = l.home()
-  const shared = []
-  for (const d of l.share) if (junction(join(src, d), join(dir, d))) shared.push(d)
+  const shared = ensureShared(agent, name)
   refreshAccount(agent, name)
   const acc = readAccounts()
   if (!acc[agent]) acc[agent] = ['default']
@@ -98,11 +156,13 @@ export function addAccount(agent, name) {
   return { dir, shared, login: l.login(dir), env: l.env }
 }
 
-// Before each launch: bring the copied files up to date with the real home.
+// Before each launch: bring the copied files up to date with the real home,
+// and add any shared directory the account is still missing.
 export function refreshAccount(agent, name) {
   if (name === 'default') return []
   const l = LAYOUT[agent]
   const dir = accountDir(agent, name)
+  ensureShared(agent, name)
   const copied = []
   for (const f of l.copy) {
     const s = join(l.home(), f)