@ucsandman/legcli 0.8.0 → 0.10.0

package/docs/cli-contracts.md

@@ -189,6 +189,27 @@ stderr are 0 bytes, and codex's is the one stdin notice. observed-live.
   out of `src/adapters/index.mjs` until `grok login` has been completed on the
   machine and `node scripts/probe.mjs --adapter grok --repo <toy>` passes.
 
+## `leg harness` (the portable harness)
+
+What the command reads and writes per client, each fact from the engine's
+adapter source (`src/harness/vendor/agnostic-ai/engine/harness/{sources,targets}/*.cjs`,
+byte for byte the Agnostic AI engine) and verified by
+`test/harness-*.test.mjs` against fixture homes on 2026-09-16.
+
+| client | read as a source | written as a destination | shim |
+|---|---|---|---|
+| Claude Code | `~/.claude/CLAUDE.md` (+ `@imports` inside the home), `SOUL.md`, the hooks and permissions of its settings file, the `mcpServers` of `~/.claude.json` and `~/.claude/.mcp.json` (the oauth block is never read), `agents/*.md`, `commands/*.md`, `skills/*/SKILL.md` | `~/.claude/leg-rules.md` + one `@` line appended to `CLAUDE.md`; owned hook groups and permission entries in its settings file; owned servers in `~/.claude.json`; `agents/`, `commands/`, skill links | none: the bundle is Claude's dialect |
+| Codex CLI | `~/.codex/AGENTS.md`, `config.toml` (`hooks.*`, `mcp_servers.*`), `agents/*.toml`, `prompts/*.md`, `skills/`, `rules/*.rules` (per-invocation absolute-path approvals skipped; `auth.json` never read) | `AGENTS.md` (whole file, owned), `config.toml` regions `hooks` (with `[hooks.state]` trust hashes, self-tested), `skills` (duplicate disables), `mcp`; `agents/*.toml`; `prompts/*.md`; skill links; `rules/leg-harness.rules` prefix rules | none |
+| Antigravity CLI | not a source | `~/.gemini/GEMINI.md` (owned), the `leg-harness` key in `~/.gemini/config/hooks.json`, `mcp_config.json` servers, `config/agents`, `config/commands`, `config/skills` links | the engine's hook shim, chained with `++` |
+| Gemini CLI | not a source | `GEMINI.md`, owned hook groups in its settings file, `commands/*.toml`, `mcpServers`, skill links | shim |
+| Grok CLI | no | no (reported `unsupported`) | |
+
+Exit codes: `0` fine; `1` stale or attention (`check`, `sync`) or a doctor
+failure; `2` usage; `3` not captured, no source, or consent declined
+(`enable` without `--yes` and without a terminal). `--json` on `status`,
+`inspect`, `sync`, `check`, `explain`, `history`, `doctor` prints the same
+record the board reads.
+
 ## Interactive taps
 
 What `leg claude|codex|agy|grok` reads while the real interactive CLI runs. Same
@@ -370,6 +391,20 @@ in [VOCABULARY.md](VOCABULARY.md). Board routes: `GET /api/sessions`,
 `POST /api/sessions/:id/end`, `DELETE /api/sessions/:id`, with the list pushed
 as the SSE `sessions` event (source: src/server.mjs, src/board/sessions.js).
 
+### History index
+
+`<LEG_HOME>/history/index.json` is the one file `leg history` writes: per
+provider, per transcript, size, mtime and a small scrubbed record (source:
+src/history/index.mjs). What each provider reads from its CLI's own store,
+with the observed file and field names, is the header of each
+`src/history/providers/<name>.mjs`; the support matrix and the resume
+commands quoted from each CLI's `--help` (observed-live 2026-09-16: `claude
+--resume <id>`, `codex resume <id>`, `grok --resume <id>`, `agy --conversation
+<id>`; copilot has none Leg has verified) are in [history.md](history.md).
+Board routes, owner only: `GET /api/history`, `GET /api/history/:id`,
+`GET /api/history/providers`, `POST /api/history/refresh`,
+`GET /api/worktrees` (source: src/server.mjs, src/board/history.js).
+
 ## Limit signals
 
 Recorded in `fixtures/limits/<group>/<id>.json` and classified by
@@ -393,7 +428,7 @@ non-zero exit → `failed`. Every outcome except `completed`, `auth_failed` and
 `killed` asks the chain to hand off.
 
 <!-- limits-table:start -->
-Generated by `node scripts/limits-table.mjs` from 22 fixtures (4 observed-live, 18 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Baton itself; `info` must never classify as a limit.
+Generated by `node scripts/limits-table.mjs` from 22 fixtures (4 observed-live, 18 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Leg itself; `info` must never classify as a limit.
 
 | id | adapter | class | where | source | text (excerpt) | produced by |
 |----|---------|-------|-------|--------|----------------|-------------|

package/docs/concepts.md

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

package/docs/configuration.md

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

package/docs/faq.md

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