@ucsandman/legcli 0.7.0 → 0.9.0

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

@@ -20,13 +20,16 @@ variables yourself in that case.
 
 ## Interactive sessions
 
-These apply to `leg claude|codex|agy`.
+These apply to `leg claude|codex|agy|grok`.
 
 | variable | default | meaning | read in |
 |----------|---------|---------|---------|
 | `LEG_ACCOUNT` | `default` | start the session on a named login instead of the CLI's own home | `src/attach.mjs` |
+| `LEG_AUTO_APPROVE` | `1` | launch interactive agents in auto-approve mode (set to `0`, `false`, or `off` to disable) | `src/preferences.mjs` |
+| `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` |
@@ -45,6 +48,23 @@ record under `$LEG_HOME/sessions/`.
 `CLAUDE_CONFIG_DIR` and `CODEX_HOME` are set for the child when the session
 runs on a named account; see [Accounts](#accounts) below.
 
+### Auto-approve launch mode
+
+By default, Leg starts interactive sessions (`leg claude`, `leg codex`, `leg agy`, and `leg grok`) in permissive auto-approve mode so you never sit through repetitive tool permission prompts:
+
+- Claude: `--dangerously-skip-permissions`
+- Codex: `--ask-for-approval never`
+- agy: `--dangerously-skip-permissions`
+- Grok: `--always-approve`
+
+These flags are injected at spawn time and only affect sessions launched through Leg. Your global CLI configurations (`~/.claude.json`, `~/.codex/config.toml`, `~/.gemini/settings.json`) remain untouched.
+
+To opt out and keep standard approval prompts:
+
+1. CLI flag: pass `--no-auto-approve` when starting a session (e.g. `leg claude --no-auto-approve`).
+2. Environment variable: set `LEG_AUTO_APPROVE=0` or `LEG_NO_AUTO_APPROVE=1` (or legacy `BATON_AUTO_APPROVE=0` / `BATON_NO_AUTO_APPROVE=1`).
+3. Persistent preference: set `"auto_approve": false` in `~/.leg/preferences.json`.
+
 ## Core
 
 | variable | default | meaning | read in |
@@ -80,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 |
 |----------|---------|---------|
@@ -152,6 +172,26 @@ junctions as links, never following them, then deletes the directory. Nothing
 under your real home is written at any point. Start a session on a named
 account with `LEG_ACCOUNT=<name>`, or let a limit hand off to it.
 
+## The portable harness
+
+Off until `leg harness enable`. Its settings live in `~/.leg/preferences.json`
+beside the hand-off order:
+
+```json
+{ "harness": { "enabled": true, "policy": "sync", "source": "claude" } }
+```
+
+| key | values | meaning |
+|-----|--------|---------|
+| `enabled` | `true`, `false` (default) | the consent `leg harness enable` records; `leg harness disable` clears it and removes nothing |
+| `policy` | `warn`, `sync` (default on enable), `strict` | what an unattended hand-off may do: report only; write managed state when safe; refuse a destination that cannot be made safe |
+| `source` | `claude`, `codex` | the client whose harness is carried; auto-detected from `~/.claude/CLAUDE.md` then `~/.codex/AGENTS.md` when unset |
+
+`~/.leg/harness/policy.json` (optional) names what is deliberately not
+carried: sections to drop, hooks, skills and MCP servers to exclude, each with
+a reason, and the Codex model ladder. State, backups and the evidence trail
+live under `~/.leg/harness/`. Every detail: [harness.md](harness.md).
+
 ## Test and development seams
 
 Not meant for normal use; documented for completeness.

package/docs/faq.md

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