gaslamp 2.2.2 → 3.0.0

package/README.md

@@ -6,175 +6,143 @@
 [![node](https://img.shields.io/node/v/gaslamp)](https://www.npmjs.com/package/gaslamp)
 [![license](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue)](LICENSE)
 
-Let Claude Code and Codex consult each other from the shell — and reach Gemini
-and Grok as read-only consult targets.
+Let coding agents consult each other from the shell: Claude, Codex, Gemini and
+Grok.
 
 ```sh
-gaslamp codex  "review this diff for races: …"     # Claude asks Codex
-gaslamp claude "verify this proof sketch: …"       # Codex asks Claude
-git diff | gaslamp codex "review for races:"       # piped stdin rides as evidence
-gaslamp codex - < notes/design-spar.md             # or: the whole prompt from a file
-gaslamp claude --thread api-spar "counterpoint: …" # named session, continued
-gaslamp gemini "is this migration reversible? …"   # Gemini via Antigravity CLI
-gaslamp grok "what does this stack trace mean? …"  # Grok via Grok Build
+gaslamp codex  "review this diff for races: …"         # Claude asks Codex
+gaslamp claude "verify this proof sketch: …"           # Codex asks Claude
+git diff | gaslamp codex "review for races:"           # piped stdin rides along as evidence
+gaslamp gemini "what changed in the v5 API? cite URLs" # Gemini, through Antigravity CLI
+gaslamp grok --thread launch "how did people react?"   # Grok, through Grok Build
 ```
 
-Each call blocks until the reply, then prints it plus a greppable trailer:
+Each call blocks until the reply, then prints it and one line:
 
 ```
 lamplight
-[gaslamp] job: cx-20260612-142457-744e · session: 019ebdb9-… · resume: gaslamp codex --resume 019ebdb9-… · tok: 32k→60
+[gaslamp] job cx-20261026-142457-744e · continue: gaslamp codex --resume cx-20261026-142457-744e
 ```
 
-The agent backgrounds the call with its own facility (Claude Code:
-`run_in_background`; Codex: its background terminal), keeps working, and gets
-the reply when it lands — so several consults run in parallel and replies
-trickle in. No MCP servers, no daemon: asynchrony is the harness's job, and
-gaslamp stays a thin wrapper around `claude -p` / `codex exec`.
-
-> 1.x was a pair of MCP servers. 2.0 replaced them with this CLI: MCP tool
-> calls are blocking and serial, Codex's MCP client enforced a per-call
-> timeout that killed long consults, and its per-directory trust gate could
-> stall calls invisibly. All three problems are structural to MCP and absent
-> from a shell call.
+The calling agent runs the command in the background (`run_in_background` in
+Claude Code, a background terminal in Codex), keeps working, and gets the reply
+when it lands, so several consults run at once. No MCP servers, no daemon:
+asynchrony is the harness's job, and gaslamp stays a thin wrapper around each
+agent's headless mode.
 
 ## Requirements
 
-Both CLIs installed and logged in: [Claude Code](https://code.claude.com/docs)
-and [Codex](https://developers.openai.com/codex). Node ≥ 18. For the other two
-targets, [Antigravity CLI](https://antigravity.google/docs/cli/headless/)
-(`agy`, signed in once interactively) and/or
-[Grok Build](https://docs.x.ai/build/overview) (`grok login`).
+Node ≥ 18, and whichever agents you want to reach, installed and signed in:
+[Claude Code](https://code.claude.com/docs), [Codex](https://developers.openai.com/codex),
+[Antigravity CLI](https://antigravity.google/docs/cli/headless/) (`agy`, signed
+in once interactively), [Grok Build](https://docs.x.ai/build/overview) (`grok login`).
+Fenced Claude consults on Linux need `bubblewrap` and `socat`, which Claude
+Code's sandbox runs on.
 
 ## Install
 
 ```sh
 npm install -g gaslamp
-gaslamp setup           # allowlist the command in ~/.claude/settings.json
-gaslamp setup --skill   # …and install the gaslamp skill for BOTH agents
+gaslamp setup
 ```
 
-`setup` allowlists the command so a consult doesn't stall on a permission
-prompt. It does **not** touch your agent instructions: a CLI can't
-self-advertise the way MCP tools did, so each agent needs to learn gaslamp
-exists from somewhere. The clean way is `--skill`: both CLIs speak the same
-SKILL.md standard, so one flag installs a direction-aware skill on each side
-(`~/.claude/skills/gaslamp/` teaching Claude to consult Codex,
-`$CODEX_HOME/skills/gaslamp/` teaching Codex to consult Claude). The manual
-alternative is a short note pasted into each agent's instruction file.
-
-**`~/.claude/CLAUDE.md`** — so Claude consults Codex:
-
-> Hand work to Codex for a second pair of eyes — verify a fix, spar on a design,
-> review a diff, diagnose with fresh context. Send raw evidence (errors, diffs,
-> commands), not just your framing.
->
-> ```
-> gaslamp codex [--thread <name>] [--model <m>] [--sandbox <mode>] "<prompt>"
-> git diff | gaslamp codex "…"      # piped stdin rides as an evidence block
-> gaslamp codex --json --schema '<json-schema>' "…"   # typed reply in .data
-> gaslamp fleet codex -n N "…"      # fan out N takes in one command
-> ```
->
-> Run it as a background shell task (`run_in_background`) and keep working — the
-> reply lands when it's done; several can run in parallel. A consult is one hop
-> (the consulted agent can't consult back), so own the synthesis. `gaslamp jobs`
-> lists records, `gaslamp poll <job|--last>` fetches one (exit 10 = running),
-> `gaslamp threads` lists named sessions.
-
-**`~/.codex/AGENTS.md`** — so Codex consults Claude: the same block with
-`claude`/`Claude` in place of `codex`/`Codex`, and "run it in your background
-terminal, check back between steps" in place of the `run_in_background` line.
-
-### From source
+`setup` links gaslamp's skill into `~/.claude/skills/` and
+`$CODEX_HOME/skills/`, which is how both agents learn the command exists, and
+allowlists `Bash(gaslamp *)` in `~/.claude/settings.json` so a consult doesn't
+stall on a permission prompt. It is idempotent and never touches an agent's
+instruction files. The skill is a link into the installed package, so it
+always matches the binary.
 
-```sh
-git clone https://github.com/a9lim/gaslamp
-cd gaslamp
-./setup.sh              # === gaslamp setup --local (pins this checkout's path)
-```
+From source: clone, `npm link`, `gaslamp setup`.
 
 ## CLI
 
 ```
-gaslamp claude [opts] <prompt|->   Consult Claude (blocks until the reply).
-gaslamp codex  [opts] <prompt|->   Consult Codex  (blocks until the reply).
-gaslamp gemini [opts] <prompt|->   Consult Gemini through Antigravity CLI (agy).
-gaslamp grok   [opts] <prompt|->   Consult Grok through Grok Build.
-gaslamp fleet <backend> [opts]     Fan out a fleet of consults in one command.
-gaslamp fleet --resume <fleet-id>  Finish an interrupted fleet.
-gaslamp jobs [-n N] [--json]       List consult records, newest first.
-gaslamp threads                    List named threads, latest activity first.
-gaslamp poll <job|fleet|--last> [--json]   One record's reply/status (exit 10 = running).
-gaslamp tail <job|--last>          Follow one consult's events as one-liners.
-gaslamp setup [--local] [--skill]  Allowlist the command; --skill installs the
-                                   gaslamp skill for both agents.
-
-Consult options:
-  --resume <session|job>   Continue a session (a prior job id works too).
-  --thread <name>          Named session: continue if bound, else start + bind.
-  --model <m>              An exact model id, or a tier word: claude's own
-                           aliases (fable, opus, sonnet, haiku); codex tiers
-                           (astra, sol, luna) and gemini tiers (argon, flash)
-                           resolve to the newest id in that harness's catalog.
-  --effort <level>         Reasoning effort (native on every backend).
-  --schema <file|json>     JSON Schema for the reply; --json gains data.
-  --label <s>              Tag the job record (shows in gaslamp jobs).
-  --sandbox <mode>         claude: read-only | danger-full-access
-                           codex:  read-only | workspace-write | danger-full-access
-                           gemini: read-only | danger-full-access
-                           grok:   read-only | workspace-write | danger-full-access
-  --raw                    Skip the consult preamble.
-  --cwd <dir>              Working directory for the consult.
-  --json                   {backend, jobId, sessionId, status, exitCode,
-                            content, label?, usage?, data?}
-
-Fleet options (plus the consult options above, applied to every consult):
-  -n, --count N            Replicate the prompt across N fresh sessions.
-  -j, --concurrency N      Max consults in flight (default 4).
-  --stream                 Print replies as they complete (--json: JSONL).
-  - < tasks.jsonl          One task per line: {"prompt", model?, sandbox?,
-                           effort?, cwd?, resume?, thread?, label?, schema?,
-                           raw?} or a bare prompt.
+gaslamp <claude|codex|gemini|grok> [opts] <prompt|->   Consult one; blocks until the reply.
+gaslamp jobs [-n N] [--json]                          Recent consults, newest first.
+gaslamp poll <job|--last> [--json]                    One consult's reply (exit 10 = running).
+gaslamp threads                                       Named conversations, latest first.
+gaslamp setup                                         Link the skill, allowlist the command.
+
+  --thread <name>          Name the conversation: start it, or continue it.
+  --resume <job-id>        Continue an unnamed consult's conversation.
+  --model <m>              An exact id or a tier: claude fable|opus|sonnet|haiku,
+                           codex astra|sol|luna, gemini argon|flash.
+  --effort <level>         low|medium|high|xhigh|max.
+  --sandbox <mode>         read-only | workspace-write | danger-full-access.
+  --cwd <dir>              Where the consult runs.
+  --schema <file|json>     JSON Schema for the reply (with --json: parsed into data).
+  --json                   {backend, jobId, status, thread, content, error?, data?}
 ```
 
-## Evidence on stdin
+Tier words resolve against each harness's own model catalog, so a new
+generation is picked up without a gaslamp release. A gemini consult always
+pins a Gemini model (argon unless you say otherwise): Antigravity also serves
+Claude and GPT models under the same account.
 
-A prompt argument plus piped stdin composes them: the prompt frames, stdin is
-the evidence, appended as a `<stdin>` block (codex's own convention for the
-case, applied to both backends):
+## Conversations
+
+`--thread <name>` names a conversation. The first consult with a name starts
+it and every later one continues it, so you never handle session ids:
 
 ```sh
-git diff | gaslamp codex "review this diff for races:"
-cargo test 2>&1 | gaslamp claude "why is this failing?"
+gaslamp codex --thread api-spar "opening take: …"
+gaslamp codex --thread api-spar "counterpoint: …"    # same conversation
+gaslamp threads
 ```
 
-Send raw evidence — errors, diffs, failing output — not just your framing of
-it; the fresh-context advantage works on facts. A bare `-` (or piping with no
-prompt argument) still reads the whole prompt from stdin.
+A reused name carries the earlier context along, so name a conversation for
+its subject, and use a new name for an independent second opinion. A thread
+belongs to the directory it started in. From anywhere else, gaslamp refuses
+(continue it with `--cwd`, or pick another name), so a common name can't pull
+one repository's conversation into another. One consult runs per conversation
+at a time; a second gets exit 5. Without `--thread`, a consult is a one-off,
+and the trailer's `--resume <job-id>` still continues it.
+
+## Sandboxes
+
+| | omitted | read-only | workspace-write | danger-full-access |
+|---|---|---|---|---|
+| claude | its own config | Claude Code's sandbox, no writes | Claude Code's sandbox, cwd only | no checks |
+| codex | its own config | codex's sandbox | codex's sandbox | no checks |
+| gemini | read-only | Seatbelt, no writes (macOS) | Seatbelt, cwd only (macOS) | no checks |
+| grok | read-only | grok's sandbox | grok's sandbox | no checks |
+
+The fenced modes are enforced by the OS, and a fence that can't start refuses
+the consult instead of running it unfenced. "No writes" means nothing outside
+the harness's own state and temp dirs. The fences cover the filesystem, not
+the network: a read-only consultee can still search and fetch. Claude Code's
+sandbox wraps Bash commands only, so gaslamp also turns off Claude's file-edit
+tools in read-only. A fenced Claude consult loads none of your Claude settings
+files (only managed settings), because their sandbox exceptions would merge
+into the fence: it runs without your hooks, env and permission rules.
+Managed (organization) Claude settings still apply, and any sandbox exceptions
+they grant apply inside the fence too. Grok's
+and Gemini's own permission layers are skipped; their fence is the kernel's. Gemini's fence is Seatbelt (`sandbox-exec`) with agy's own
+permission layer skipped. Seatbelt doesn't exist on Linux and doesn't nest
+inside another sandbox, so in those environments a fenced gemini consult is
+refused (exit 4).
+
+Inside a sandboxed Codex with network off, no consult can reach its provider;
+gaslamp detects `CODEX_SANDBOX_NETWORK_DISABLED=1` and refuses (exit 4)
+instead of timing out.
 
-## Threads
+## Evidence on stdin
 
-`--thread <name>` is a named session: continue it if the name is bound, start
-and bind it if not — idempotent, no fishing session UUIDs out of old trailers.
+A prompt argument plus piped stdin composes them: the prompt frames, and
+stdin is appended as a `<stdin>` block. A bare `-`, or piping with no prompt
+argument, reads the whole prompt from stdin.
 
 ```sh
-gaslamp codex --thread api-spar "opening take: …"
-gaslamp codex --thread api-spar "counterpoint: …"    # same conversation
-gaslamp threads                                      # list them
+cargo test 2>&1 | gaslamp claude "why is this failing?"
+gaslamp codex - < notes/design-spar.md
 ```
 
-A thread is one pointer file under `~/.gaslamp/threads/`, re-pointed on every
-consult. This matters doubly for claude, where each resume forks a *new*
-session id — the pointer chases it automatically, which manual `--resume`
-juggling cannot.
-
 ## Typed replies
 
-`--schema <file|inline-json>` plumbs a JSON Schema to each backend's native
-structured output (`claude --json-schema` / `codex exec --output-schema`); the
-`--json` envelope then carries `data`, the parsed object. A reply that fails to
-parse marks the consult **failed** — trust the exit code.
+`--schema` plumbs a JSON Schema to each backend's native structured output.
+With `--json` the parsed object lands in `data`, and a reply that doesn't
+parse fails the consult.
 
 ```sh
 gaslamp codex --json --schema '{"type":"object","properties":{"verdict":
@@ -182,170 +150,60 @@ gaslamp codex --json --schema '{"type":"object","properties":{"verdict":
   "is this fix correct? …" | jq .data.verdict
 ```
 
-One backend asymmetry, papered over: OpenAI's endpoint only accepts *strict*
-schemas (every object needs `additionalProperties:false` and all properties
-required), so gaslamp strictifies schemas on the way to codex — spell optional
-fields nullable (`{"type":["string","null"]}`) rather than leaving them out of
-`required`. Claude takes the schema as written.
-
-## The consult preamble
-
-A consulted agent gets a few fixed lines of framing (claude via
-`--append-system-prompt`, codex prepended as a `<gaslamp_consult>` block): it
-is a one-hop consult, its final message returns verbatim to the calling agent,
-deliver the deliverable. Without this, consulted agents reply conversationally
-or promise work instead of doing it. `--raw` drops it. It is fixed and tiny by
-design — not a context-injection hook.
-
-## Fleets
-
-`gaslamp fleet` fires a whole batch of consults from one command and blocks
-until every reply is in — `-n N "<prompt>"` runs one prompt across N fresh
-sessions (voting, diverse sampling), or a JSONL manifest on stdin runs one
-`{prompt, model?, sandbox?, cwd?, resume?, label?}` task per line:
-
-```sh
-gaslamp fleet codex -n 5 "spot the worst bug in this diff: …"   # 5 takes, vote
-gaslamp fleet claude - < tasks.jsonl                            # one task/line
-gaslamp fleet codex -n 8 --json "…" | jq '.results[].content'   # structured
-gaslamp fleet codex -n 4 --stream --json "…"                    # JSONL as they land
-gaslamp fleet --resume fl-20260702-…                            # finish an interrupted one
-```
-
-Each task is a normal consult — its own job record and resumable session — so a
-killed fleet costs in-flight turns, not sessions. Two safety defaults at N:
-fleets run `--sandbox read-only` unless you opt into writes (N agents writing one
-directory race), and a manifest that resumes the same session or thread twice is
-refused (they'd deadlock on the session lock). `gaslamp poll <fleet-id>` regroups
-a fleet's replies later. It's the same move as backgrounding one consult, one
-layer up — and it's the only one-command fan-out Codex has, since (unlike Claude
-Code) it has no built-in agent-workflow tool.
+OpenAI only accepts *strict* schemas (every object closed, every property
+required), so gaslamp strictifies them on the way to codex. Spell an optional
+field nullable (`{"type":["string","null"]}`) rather than leaving it out of
+`required`.
 
-`--stream` prints each reply the moment it completes (completion order) so the
-caller can peek partial output mid-run; with `--json` it becomes explicit JSONL —
-one result line per reply, then a `fleet.done` line — leaving the collected
-single-object `--json` contract untouched.
-
-`fleet --resume <fleet-id>` finishes an interrupted fleet from its stored
-manifest: done children replay their recorded replies, a killed child whose
-session was captured is resumed with a fixed finish-and-deliver nudge (the
-session already holds the prompt and partial work), and everything else reruns
-fresh. The new fleet record points back via `resumedFrom`.
-
-## Job records
+## Records
 
 Every consult writes through to `~/.gaslamp/jobs/<id>/` as it runs: the
-prompt, the raw backend event stream, the reply, stderr, and a `meta.json`
-whose session id is recorded the moment the backend reports it. If the
-harness kills a consult mid-flight, the whole child process group dies with
-it (no orphans silently burning API quota) — but the session survives on the
-backend's side, so recovery is `--resume <session>`, not a lost half hour.
-
-Token usage lands in the record too (claude's result usage + cost; codex's
-per-turn usage, summed) and shows in the trailer — fleets are quota-shaped,
-so quota is visible. `gaslamp jobs --json` and `gaslamp poll <id> --json`
-make the records scriptable; `gaslamp tail <job|--last>` follows a running
-consult's events as uniform one-liners across every backend's schema.
-
-Each record also carries **provenance**, because a vendor can change the model
-or the system prompt behind a stable product name: the provider and harness
-version, the model the backend reported answering with (`unknown` where it
-reports none — codex), the tier word and the id actually passed, the
-permission mode and effective sandbox, a hash of the vendor system prompt where
-the harness exposes one (grok) or `known: false`, the web/X retrieval tools the
-consultee had and the ones it used, and the gaslamp version and git revision.
-
-Two concurrent consults into the same session would race, so gaslamp refuses
-the second (exit 5) until the first finishes.
-
-## Permissions
-
-A claude or codex consult with no `--sandbox` runs with the consulted agent's
-own config — exactly as that agent would behave if you drove it yourself.
-(Gemini and Grok consults default to read-only instead; see below.) Overrides:
-`read-only` forces an advisory, no-edit reviewer on either backend;
-`danger-full-access` forces full read/write. Claude has no filesystem
-sandbox, so `workspace-write` there is a usage error rather than a silent
-lie (Codex supports all three).
-
-Note for sandboxed Codex setups: the gaslamp CLI runs *inside* Codex's
-per-command sandbox (1.x's MCP server ran outside it). Under the default
-`workspace-write` sandbox, network is disabled and a consulted agent could
-reach neither Anthropic nor OpenAI — gaslamp detects this
-(`CODEX_SANDBOX_NETWORK_DISABLED=1`) and refuses with instructions instead of
-timing out. Grant the call escalated permissions, or set
-`network_access = true` / `danger-full-access` in `~/.codex/config.toml`.
-
-## Gemini and Grok
-
-`gaslamp gemini` drives Google's Antigravity CLI (`agy`) in print mode, the
-prompt on stdin as one streaming-input event; `gaslamp grok` drives xAI's Grok
-Build headless, prompt on stdin, `--output-format streaming-messages-json`.
-Same contract as the other two — blocking call, trailer, job records,
-threads, `--schema`, fleets — with these differences:
-
-- **Read-only by default, enforced by the harness.** Grok runs under its
-  kernel sandbox (`--sandbox read-only`: Seatbelt on macOS, Landlock on Linux;
-  writes only to `~/.grok` and temp dirs). Grok's permission layer is not a
-  substitute: headless `--permission-mode default` denied its write tool but
-  ran an arbitrary shell `touch`. On macOS, a read-only gemini consult runs
-  agy under Seatbelt (`sandbox-exec`): it can write its own state directory
-  (`~/.gemini/antigravity-cli`, minus the files that configure it) and temp
-  dirs, nothing else, whatever Antigravity's permission settings say — so a
-  user can keep `always-proceed` / `agentMode: auto` for interactive work, and
-  search and read-only commands still run. Elsewhere (Linux, or inside a
-  Codex sandbox, where Seatbelt does not nest) the guarantee is Antigravity's
-  `request-review` preset: the consult refuses to start when its permission
-  files grant more than reads, read-only git and the end_session off-ramp, or
-  set a lax `toolPermission` or `agentMode: auto` (which approves writes and
-  commands under any preset, unreported), and fails if init doesn't confirm
-  the preset. That path is read-capable rather than airtight: an allowed
-  `git diff` still accepts git's own `--output=<file>`.
-  Antigravity has no headless `workspace-write` (`--mode accept-edits` did
-  not enable writes in print mode), so that is a usage error there.
-- **A denied tool call can end the turn empty.** Both harnesses report success
-  for it; gaslamp marks an empty reply failed and surfaces the harness's
-  stderr. Pipe evidence in rather than asking the consultee to fetch it.
-- **Gemini is pinned.** Antigravity also serves Claude and GPT-OSS models under
-  the same account; without `--model`, a gemini consult runs the newest
-  `argon` tier, never the account default.
-- **The caller's harness stays home.** Their spawns drop `CLAUDE*`,
-  `ANTHROPIC_*`, `CODEX_*` and `OPENAI_*` variables (session ids, a messaging
-  token, account details), and Grok's vendor-compat imports are switched off
-  for the consult: by default Grok loads `~/.claude/CLAUDE.md` as its own
-  instructions and runs Claude's skills, MCP servers and hooks. (It also reads
-  `~/.claude/settings.json` permissions with no switch; gaslamp's explicit
-  `--permission-mode` overrides that file's `defaultMode`.)
-- **Unsigned `agy` hangs.** Without a cached sign-in, print mode prints a
-  sign-in URL and waits forever; gaslamp stops it and says to run `agy` once.
-- **Sessions.** `agy --conversation <id>` resumes in place (same id); so does
-  `grok --resume <id>`. Usage comes from Antigravity's per-step events, since
-  its result event counts the whole conversation.
+prompt, the backend's raw event stream, its stderr, the reply, and a small
+`meta.json` (status, error, session, thread, directory, timing). The session is
+recorded the moment the backend reports it. If the calling harness kills a
+consult, the whole child process group dies with it (no orphans quietly
+burning quota), but the conversation survives on the backend's side, so you
+continue it instead of starting over. Failure reasons, gaslamp's own included,
+land in `error` and in the trailer.
+
+The consultee gets a few fixed lines of framing: it is a one-hop consult, its
+final message returns verbatim to the caller, so deliver the deliverable.
 
 ## Recursion
 
-A consult is **one hop**: agents gaslamp spawns carry `GASLAMP_NESTED=1`
-(forced into Codex's shell env via config override, since a strict
-`shell_environment_policy` would strip it) and the consult verbs refuse under
-it. This is loop prevention, not a security boundary. Set
-`GASLAMP_ALLOW_RECURSION=1` to restore unbounded handoffs.
+A consult is one hop: agents gaslamp spawns carry `GASLAMP_NESTED=1` (forced
+into Codex's shell env through a config override, since a strict
+`shell_environment_policy` would strip it), and the consult verbs refuse under
+it. This is loop prevention, not a security boundary.
+`GASLAMP_ALLOW_RECURSION=1` lifts it.
 
-## Env knobs
+## Exit codes and environment
+
+`0` ok · `1` failed or killed · `2` usage · `3` nested · `4` can't run here (no
+network, or no OS sandbox for the mode) · `5` conversation busy · `poll`: `10`
+still running.
 
 | var | default | meaning |
 |-----|---------|---------|
-| `GASLAMP_HOME` | `~/.gaslamp` | state dir (jobs + locks + threads) |
-| `GASLAMP_ALLOWED_TOOLS` | `Read,Grep,Glob,WebFetch,WebSearch` + read-only git (`Bash(git diff:*)` etc) | tools the claude `read-only` override permits, comma-separated |
-| `GASLAMP_ALLOW_RECURSION` | unset | allow consulted agents to consult back |
-| `GASLAMP_DEBUG` | unset | verbose stderr (spawn argv) |
+| `GASLAMP_HOME` | `~/.gaslamp` | state dir (jobs, locks, threads) |
+| `GASLAMP_ALLOW_RECURSION` | unset | let consulted agents consult back |
+| `GASLAMP_DEBUG` | unset | print the spawn argv |
 | `CLAUDE_BIN` / `CODEX_BIN` / `AGY_BIN` / `GROK_BIN` | autodetected | backend binaries |
-| `GROK_HOME` | `~/.grok` | where grok keeps sessions (the system prompt hash is read from there) |
-| `GASLAMP_GEMINI_SEATBELT` | on (macOS) | `0` runs read-only gemini consults on Antigravity's preset check instead of Seatbelt |
-| `CODEX_HOME` | `~/.codex` | where `setup --skill` puts Codex's copy |
-
-Exit codes: `0` ok · `1` consult failed/killed · `2` usage · `3` nested
-refusal · `4` network-disabled sandbox · `5` session busy · `poll`: `10`
-still running.
+| `CODEX_HOME` | `~/.codex` | where `setup` links Codex's skill |
+
+## Upgrading from 2.x
+
+- `fleet` and `tail` are gone. Background several consults instead, or use your
+  harness's own fan-out.
+- `--label` folded into `--thread`, `--raw` is gone, and `--resume` takes job
+  ids only.
+- `meta.json` keeps only what gaslamp reads back. Provenance, usage and cost are
+  gone from records and output; the raw event stream still has what each
+  harness reported.
+- Claude and Gemini gained `workspace-write`, and Claude's `read-only` is now
+  OS-enforced. Gemini's fenced modes need macOS.
+- `setup` always installs the skill (as a link), and `--local`, `--skill`,
+  `GASLAMP_ALLOWED_TOOLS` and `GASLAMP_GEMINI_SEATBELT` are gone.
 
 ## Development