@robmclarty/volley 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## v0.8.0 — 2026-10-19
+
+### Added
+- **`volley acp` runs volley from Zed.** It serves volley over stdio as an Agent Client Protocol agent, so Zed's agent panel, or any ACP client, can drive it. Each prompt is a fresh volley run on the open project. The builder's work streams in as the reply under a **Round N** line, the check runs as a command card, the critic's verdict shows as a thought, and the turn ends with a summary. Edits and commands go through the editor's permission prompts. Outside volley's sandbox container, every builder command and every check asks first, Auto mode isn't offered, and neither the commands nor the check can read `OPENROUTER_API_KEY` or `ANTHROPIC_API_KEY`. Run state goes under `$XDG_STATE_HOME/volley`, never the repo. It requires the four seat flags and refuses `--worktree`, `--git`, `--json`, and a `claude_cli` builder (exit 5). The README covers the Zed setup and a check to run by hand.
+- **Either seat can run on OpenRouter.** `--builder-provider openrouter` and `--critic-provider openrouter` reach a hosted model with one `OPENROUTER_API_KEY`, from the plain CLI as well as `volley acp`, and `VOLLEY_OPENROUTER_URL` overrides the endpoint. An OpenRouter builder runs volley's own tool loop under the same containment gate as a local one, and an OpenRouter critic gets the local critic's retry and fallback. OpenRouter reports its own charge, so `--max-cost-usd` trips on it. An unset key is a configuration error (exit 5).
+- **`--state-dir <root>` keeps run state out of the workspace.** Each run's state goes to `<root>/<run_id>/`, and `state_dir` in a config file does the same. `volley resume <id> --state-dir <root>` finds a run there. Without the flag, state stays in `.volley/` as before.
+- **`run_volley` takes per-seat tools, a builder approval handler, and a trajectory sink.** All three are optional, and a run without them is exactly what it was.
+
+### Changed
+- **`ResolvedConfig` has `state_dir`.** It's required (`string | null`), so SDK code that builds a `ResolvedConfig` by hand instead of through `resolve_config` needs it. Null keeps the run's state in `.volley/`.
+
+### Fixed
+- **A local critic that runs out of steps falls back instead of failing the run.** Since fascicle 0.10.1, a critic that spent its step budget reading files threw straight past the retry and the fallback, so the run exited 6, and `--dry-run`'s canary exited 5. It now goes straight to judging without tools. A fallback verdict now says why: `degrade_cause` (`stream_error` or `step_exhaustion`) on the critic record, `critic_degrade_causes` in the summary's comparison block, and `deg:stream` or `deg:steps` in the matrix flags.
+- **Stopping a run mid-check now stops the whole check.** A stop killed only the check's shell, which left a test runner's workers, or a server the check started in the background, still running. The check now runs in a process group of its own, and a stop kills all of it.
+
+### Internal
+- **Built on fascicle 0.16.3 and @agentclientprotocol/sdk 1.8.0.**
+- **The tests drive a whole volley turn through an in-process ACP client**, against a stub model server. The live check in Zed is scripted in the README and was run by hand. Its one miss, the check's card losing its command look while it asks, waits on robmclarty/fascicle#16.
+- **The flow diagram's critic retry and fallback rows name every provider but `claude_cli`.**
+
+## v0.7.0 — 2026-10-16
+
+### Added
+- **Each seat can use its own model server.** `--builder-url` and `--critic-url` (`builder_url` and `critic_url` in a config file) point the builder and the critic at different machines even when both run on the same provider, such as two Ollama servers. A seat without a URL of its own uses the provider's env var (`VOLLEY_OLLAMA_URL` or `VOLLEY_LMSTUDIO_URL`), then the default, never the other seat's. Everything a seat sends goes to its URL: its model calls, the Ollama prewarm and context check, and the `--dry-run` probe and critic canary. Inside the sandbox, a loopback seat URL crosses to `VOLLEY_MODEL_HOST` on its own port. Both URLs carry over to `volley resume` and to every `volley matrix` pairing. A URL on a `claude_cli` seat, or one that isn't plain http(s), is a configuration error (exit 5).
+
+### Changed
+- **Ollama seats need ai-sdk-ollama 4.3.0 or later.** Before 4.3.0 it streams a thinking model's reasoning only when a request sets `think`, which volley never does, so the reasoning vanished from the terminal and the trajectory and the phase's throughput read high. volley now declares the floor as an optional peer: pnpm warns about an older copy, npm refuses it with ERESOLVE, and an install without ai-sdk-ollama is unaffected.
+- **`--dry-run` probes the critic's model endpoint too.** Each local seat's endpoint is probed, once for a server both seats share, so a `claude_cli` builder with a local critic now gets a reachability check before the canary, and an unreachable endpoint is named with its seat.
+- **`ResolvedConfig` has `builder_url` and `critic_url`.** Both are required (`string | null`), so SDK code that builds a `ResolvedConfig` by hand instead of through `resolve_config` needs them. A run saved by an earlier version resumes with both null.
+- **An empty `VOLLEY_OLLAMA_URL` or `VOLLEY_LMSTUDIO_URL` means the default.** It used to fail the run with a configuration error.
+
+### Fixed
+- **An IPv6 loopback model URL reaches the host from inside the sandbox.** `http://[::1]:…` was never crossed to `VOLLEY_MODEL_HOST`, because `URL` keeps the brackets in the hostname.
+
+### Internal
+- **Built on fascicle 0.14.0, TypeScript 7, and tsdown.** tsdown replaces tsup, whose declaration build needed a compiler API TypeScript 7 no longer exports. The published files keep their names and exports, and the bundles now keep their source comments. The dev toolchain moves to checkride 0.14.0, fallow 3.33.1, oxlint 1.88.0, vitest 5.0.4, and @ast-grep/cli 0.50.0, alongside ai 7.0.140, undici 8.12.1, and cac 7.1.0, and `pnpm audit` is clean.
+- **The throughput docs mark the gap that remains on Ollama.** A turn whose only output is a tool call still reports a rate far too high until fascicle times those turns another way (robmclarty/fascicle#12).
+- **An integration test holds each seat to its own server.** It runs real engines against two stand-in Ollama servers, and the local-provider tests no longer reach a developer's own Ollama.
+
 ## v0.6.1 — 2026-10-14
 
 ### Fixed

package/README.md

@@ -55,7 +55,8 @@ The cap is enforced in the loop guard after each phase. Sessions are never
 killed mid-flight for cost (a builder killed mid-edit leaves the workspace
 undefined), so set the cap below your true ceiling by roughly one iteration's
 expected cost. Per-run totals land in `.volley/summary.json` and the final
-terminal summary.
+terminal summary. An [OpenRouter](#openrouter) seat's cost is the charge
+OpenRouter reports for each call, so the cap trips on one as on any other.
 
 ## How it works
 
@@ -94,7 +95,7 @@ Under the hood the loop is one [fascicle](https://www.npmjs.com/package/fascicle
 composition in [`src/flow.ts`](./src/flow.ts), and fascicle's `describe.diagram`
 draws it straight from the code. It shows what the sketch above leaves out: the
 branch that skips verification once the builder alone crosses the cost cap, the
-critic's retry-then-tool-less fallback for local models whose streams die, and
+critic's retry-then-tool-less fallback on every provider but `claude_cli`, and
 the guard that decides when the loop stops.
 
 <!-- flow diagram: pnpm diagram -->
@@ -108,8 +109,8 @@ volley                                loop: one round per iteration, up to max_i
 │  │  └─ else  sequence
 │  │     ├─ check                     the deterministic gate: checkride, a command, or none
 │  │     └─ critique                  the read-only critic's verdict and feedback
-│  │        └─ critic                 fallback: judge without tools if a local critic's stream keeps dying
-│  │           ├─ retry               one more try after a stream death, local providers only
+│  │        └─ critic                 fallback: judge without tools if a critic on any provider but claude_cli keeps dying or runs out of steps
+│  │           ├─ retry               one more try after a stream death, on any provider but claude_cli
 │  │           │  └─ critic_tools     model call with read-only workspace tools
 │  │           └─ pipe                mark the verdict degraded
 │  │              └─ critic_toolless  model call judging from the check output and a file list
@@ -122,8 +123,10 @@ the one in the `src/flow.ts` header to what the code builds, so neither drifts.
 
 ## Install
 
-Requires Node ≥ 24, pnpm, and the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
-installed and authenticated.
+Requires Node ≥ 24 and pnpm. The default seats run on the
+[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code), installed and
+authenticated; seats on [OpenRouter](#openrouter) or a
+[local model server](#local-critic) don't need it.
 
 From a checkout:
 
@@ -147,6 +150,8 @@ volley [options]
 volley --config <path>
 volley resume <run-id>
 volley matrix --builders <models> --critics <models> --config <path>
+volley acp --builder-provider <name> --builder-model <model> \
+  --critic-provider <name> --critic-model <model> [options]
 ```
 
 | Flag | Default | Description |
@@ -156,11 +161,13 @@ volley matrix --builders <models> --critics <models> --config <path>
 | `--criteria` | (required) | Acceptance criteria. Literal string or `@path`. |
 | `--check` | `auto` | `auto` (checkride if detected, else none), `none`, or a shell command. |
 | `--builder-model` | `opus` | `opus`/`sonnet`/`haiku` or a full model id. |
-| `--builder-provider` | `claude_cli` | `claude_cli`, `ollama`, or `lmstudio` (see [Local builder](#local-builder)). |
-| `--builder-max-steps` | `50` | Local builder tool-loop step cap per iteration. Ignored for `claude_cli`. |
-| `--allow-unsandboxed-builder` | off | Permit a local builder to run without a sandbox (see [Local builder](#local-builder)). |
+| `--builder-provider` | `claude_cli` | `claude_cli`, `ollama`, `lmstudio`, or `openrouter` (see [Local builder](#local-builder) and [OpenRouter](#openrouter)). |
+| `--builder-url` | the provider's env var | The builder's model server base URL, for `ollama`, `lmstudio`, or `openrouter` only. Lets the builder and critic run on different machines with the same provider (see [Seats on different machines](#seats-on-different-machines)). |
+| `--builder-max-steps` | `50` | Tool-loop builder step cap per iteration. Ignored for `claude_cli`. |
+| `--allow-unsandboxed-builder` | off | Permit a builder other than `claude_cli` to run without a sandbox (see [Local builder](#local-builder)). |
 | `--critic-model` | `opus` | Model for the critic. |
-| `--critic-provider` | `claude_cli` | `claude_cli`, `ollama`, or `lmstudio` (see [Local critic](#local-critic)). |
+| `--critic-provider` | `claude_cli` | `claude_cli`, `ollama`, `lmstudio`, or `openrouter` (see [Local critic](#local-critic) and [OpenRouter](#openrouter)). |
+| `--critic-url` | the provider's env var | The critic's model server base URL, for `ollama`, `lmstudio`, or `openrouter` only. |
 | `--builder-permission-mode` | `acceptEdits` | Or `bypassPermissions` for fully trusted workspaces. |
 | `--critic` | `reviewer` | `reviewer`, `optimizer`, `researcher`, or a prompt file path. |
 | `--max-iterations` | `10` | Hard iteration cap. |
@@ -171,8 +178,9 @@ volley matrix --builders <models> --critics <models> --config <path>
 | `--gate-paths` | (built-in list) | Comma-separated globs naming the gate — tests, fixtures, check config. Replaces the defaults; see [What the builder changed](#what-the-builder-changed). |
 | `--fail-on-gate-edit` | off | Halt the run (exit 8) if the builder edits a gate path, instead of reporting it. |
 | `--sandbox-image` | `volley-sandbox:latest` | Container image for the local-builder sandbox. Or `VOLLEY_SANDBOX_IMAGE`. |
-| `--run-id` | a fresh UUID | The run's id, naming its `.volley/` state and its `volley/<id>` branch, so a harness that owns the id finds it in both. Letters, digits, `-`, and `_`, starting with a letter or digit. |
-| `--dry-run` | off | Validate config, run `checkride doctor` and (for a local critic) the critic-seat canary, then exit. |
+| `--state-dir` | the workspace's `.volley/` | Keep each run's state under `<path>/<run id>/` instead, and none in the workspace (see [Run artifacts](#run-artifacts)). Or `state_dir` in a config file. |
+| `--run-id` | a fresh UUID | The run's id, naming its run state and its `volley/<id>` branch, so a harness that owns the id finds it in both. Letters, digits, `-`, and `_`, starting with a letter or digit. |
+| `--dry-run` | off | Validate config, run `checkride doctor`, probe each tool-loop seat's model endpoint (local or OpenRouter), run the critic-seat canary (for a local critic), then exit. |
 | `--config` | — | TypeScript config file (`VolleyConfig` default export). CLI flags override. |
 | `--json` | off | Machine mode: one summary JSON document on stdout. |
 | `--verbose` | off | Full tool inputs/outputs (truncated at 4000 chars). |
@@ -223,8 +231,13 @@ export default config;
 ```sh
 volley resume <run-id>            # in the workspace directory
 volley resume <run-id> --workspace ./my-project
+volley resume <run-id> --state-dir ~/volley-runs   # a run started with --state-dir
 ```
 
+Given the root a run was started under, `resume` finds it at
+`<root>/<run-id>/` from any directory, since the run's recorded config names its
+workspace.
+
 Continues from the last completed iteration with the saved feedback and cost
 totals. An iteration interrupted mid-phase is discarded and re-run.
 
@@ -244,7 +257,7 @@ volley matrix \
 
 | Matrix flag | Description |
 |---|---|
-| `--config` | Base `VolleyConfig` (TS/JS): the task, workspace, providers, and caps held fixed. Required. |
+| `--config` | Base `VolleyConfig` (TS/JS): the task, workspace, providers, seat URLs, and caps held fixed. Required. |
 | `--builders` | Comma-separated builder models to sweep. |
 | `--critics` | Comma-separated critic models to sweep. |
 | `--repeat` | Attempts per seat (default 1). A pass *rate* needs more than one. |
@@ -264,11 +277,11 @@ repository**. Every attempt's run state is written to
 `.volley-matrix/matrix.json`, and one aggregate table goes to stderr:
 
 ```
-builder         critic         pass  iters  wall     cost   salvage  flags  why
-──────────────  ─────────────  ────  ─────  ───────  ─────  ───────  ─────  ──────────────────
-qwen3.6:latest  qwen3:8b       3/3   1.0    403.4s   $0.00  0%       —      —
-qwen3.6:latest  gemma4:12b     2/3   1.5    512.0s   $0.00  0%       —      unmet: 2 criteria
-qwen3.6:latest  glm-4.7-flash  0/3   —      184.0s   $0.00  12%      deg    check: types, test
+builder         critic         pass  iters  wall    cost   salvage  flags       why
+──────────────  ─────────────  ────  ─────  ──────  ─────  ───────  ──────────  ──────────────────
+qwen3.6:latest  qwen3:8b       3/3   1.0    403.4s  $0.00  0%       —           —
+qwen3.6:latest  gemma4:12b     2/3   1.5    512.0s  $0.00  0%       —           unmet: 2 criteria
+qwen3.6:latest  glm-4.7-flash  0/3   —      184.0s  $0.00  12%      deg:stream  check: types, test
 ```
 
 **Why `--repeat`.** One run answers "did this pairing converge that time", and
@@ -286,7 +299,9 @@ totals rather than a mean of ratios.
 failing check slots, the criteria the critic still judged unmet, a cost cap, a
 gate edit, or the error that broke the run. `flags` carries what qualifies a
 pass rather than explaining a failure: `deg` for a degraded critic verdict,
-`gate` for a builder that edited the gate. Every attempt's full detail —
+named for what degraded it (`deg:stream` when the critic's stream kept dying,
+`deg:steps` when it ran out of steps), and `gate` for a builder that edited the
+gate. Every attempt's full detail —
 statuses, verdicts, failing slots, unmet criteria, gate edits — is in the
 `--json` aggregate and in `matrix.json`.
 
@@ -296,8 +311,8 @@ produced none at all (`status: broke`).
 
 ## Local critic
 
-The builder always runs on the Claude Code CLI, but the critic is read-only
-and schema-constrained — a good fit for a cheaper local model. Point it at a
+The critic is read-only and schema-constrained, which makes it a good fit for
+a cheaper local model even when the builder stays on Claude. Point it at a
 local provider with `--critic-provider`:
 
 ```sh
@@ -317,19 +332,29 @@ Providers and their setup:
 
 | `--critic-provider` | Server | Base-URL env (default) | Required peer dependency |
 |---|---|---|---|
-| `ollama` | [Ollama](https://ollama.com) | `VOLLEY_OLLAMA_URL` (`http://localhost:11434`) | `ai-sdk-ollama@^4` |
+| `ollama` | [Ollama](https://ollama.com) | `VOLLEY_OLLAMA_URL` (`http://localhost:11434`) | `ai-sdk-ollama@^4.3.0` |
 | `lmstudio` | [LM Studio](https://lmstudio.ai) | `VOLLEY_LMSTUDIO_URL` (`http://localhost:1234/v1`) | `@ai-sdk/openai-compatible` |
 
 Install the peer for your provider in the project running volley (e.g.
-`pnpm add ai-sdk-ollama@^4`); fascicle loads it lazily only when the local
-critic actually runs. The major matters: it must satisfy fascicle's declared
-peer range (`^4` for fascicle 0.12.13, which tracks the AI SDK v7 line; a bare
-`pnpm add ai-sdk-ollama` installs v4, which is exactly what this major wants).
+`pnpm add ai-sdk-ollama@^4.3.0`); fascicle loads it lazily only when the local
+critic actually runs. The version matters. The major must satisfy fascicle's
+declared peer range (`^4` for fascicle 0.16.3, which tracks the AI SDK v7
+line), and volley declares 4.3.0 as its floor (an optional peer, so your
+package manager flags an older copy at install time). Before 4.3.0,
+ai-sdk-ollama streams a thinking model's reasoning only when the request sets
+`think`, which volley never does: the reasoning disappears from the terminal
+and the trajectory, and the phase's throughput reads high. A bare
+`pnpm add ai-sdk-ollama` installs the latest 4.x, which clears the floor.
 The Ollama base URL is the **server root** — `ai-sdk-ollama` adds the `/api`
 prefix itself (volley strips a trailing `/api` from `VOLLEY_OLLAMA_URL` for
 compatibility). Local providers are free, so the critic's cost is reported as
 `$0.000` and the run total reflects builder spend only.
 
+The env var sets a provider's URL for both seats. To give the critic a server
+of its own, pass `--critic-url` (`critic_url` in a config file). A seat uses its
+own URL, then the provider's env var, then the default, and never the other
+seat's URL; see [Seats on different machines](#seats-on-different-machines).
+
 Keeping the builder on Claude while the critic goes local is the low-risk split:
 the recurring per-iteration critic cost drops to zero and the critic is
 read-only, so a weaker local model can only mis-judge, never mis-edit. A local
@@ -344,7 +369,14 @@ the *same* model drives the builder tool loop fine, so the defect is specific to
 the constrained-verdict path. volley no longer lets that kill a run: the critic
 phase degrades (a bounded retry, then a tool-less fallback that keeps the
 schema), marks the verdict `critic_degraded: true`, and `--dry-run` predicts the
-doomed combo up front with a critic-seat canary. Even so, prefer a critic whose
+doomed combo up front with a critic-seat canary. A critic that runs out of steps
+before its verdict (its 10-step budget spent, or its last turn a tool call) skips
+the retry, since another identical tool loop would only run out again, and goes
+straight to the tool-less pass. The record's `degrade_cause` says which happened:
+`stream_error` or `step_exhaustion`. A verdict cut off by the token limit or
+blocked by a content filter isn't degraded: it fails the critic phase (exit 6)
+with the finish reason in the message, because taking the tools away fixes
+neither. Even so, prefer a critic whose
 tool-call encoding Ollama parses cleanly — `qwen3:8b`, `gemma4:12b`, and
 `glm-4.7-flash` all pass. The full model-vs-transport write-up is in
 [`research/v3-comparison-finding.md`](./research/v3-comparison-finding.md).
@@ -408,7 +440,8 @@ is discarded wholesale in all three modes: an abandoned phase leaves nothing
 behind.
 
 Provider setup is the same as the [local critic](#local-critic) table
-(`VOLLEY_OLLAMA_URL` / `VOLLEY_LMSTUDIO_URL`, same peer dependencies). At
+(`VOLLEY_OLLAMA_URL` / `VOLLEY_LMSTUDIO_URL`, or `--builder-url` for the builder
+alone; same peer dependencies). At
 builder start (and before a local critic's first verdict) volley pre-loads an
 Ollama model with a load-only `/api/generate` call, so a cold multi-GB model
 load doesn't eat the first real request's time-to-first-byte budget — without
@@ -443,6 +476,264 @@ weak local model to drive a tool loop reliably has three sharp edges:
 Local providers are free, so a local builder's cost is reported as `$0.000` and
 never trips `--max-cost-usd`.
 
+### Seats on different machines
+
+Each seat can reach its own model server, so the builder and the critic can run
+on different machines even when they use the same provider. Give each seat a
+URL with `--builder-url` and `--critic-url`, or in a config file:
+
+```ts
+const config: VolleyConfig = {
+  // ...the task...
+  builder_provider: 'ollama',
+  builder_model: 'qwen3-coder:30b',
+  builder_url: 'http://localhost:11434', // this machine
+  critic_provider: 'ollama',
+  critic_model: 'qwen3:8b',
+  critic_url: 'http://localhost:11522', // a second machine, forwarded here
+};
+```
+
+- **Fallback.** A seat without a URL of its own uses the provider's env var,
+  then the default, never the other seat's URL.
+- **Same rules as the env var.** Ollama's trailing `/api` is dropped. The URL
+  must be plain `http(s)`, with no credentials, query, or fragment. Include the
+  port: a URL without one goes to 80 or 443, not the provider's default.
+- **`claude_cli` takes no URL.** Setting one on a `claude_cli` seat is a
+  configuration error (exit 5).
+- **Everything a seat sends goes to its own URL.** That covers the model calls,
+  the Ollama prewarm and context check, and the `--dry-run` endpoint probe and
+  critic canary. `volley matrix` holds both URLs fixed across every pairing.
+
+Inside the sandbox container, a loopback seat URL crosses to the host at
+`VOLLEY_MODEL_HOST` the way the env var does, keeping its port. So the two seats
+can be two forwarded ports on the host (`localhost:11522`, `localhost:11523`).
+With the allowlist's host rules in place the container reaches only the host
+gateway, so it can reach a seat on another machine only through a port forward
+on the host, for example `ssh -N -L 11522:localhost:11434 gpu-box`. On a Linux
+host, `host-gateway` is the Docker bridge's address, so the forward, like Ollama
+itself, has to listen there rather than on `127.0.0.1` alone.
+
+## OpenRouter
+
+`--builder-provider openrouter` and `--critic-provider openrouter` put a seat on
+[OpenRouter](https://openrouter.ai), so one API key runs both seats, Claude
+included, with no Claude Code CLI and no local model server:
+
+```sh
+OPENROUTER_API_KEY=sk-or-v1-... volley \
+  --prompt "@task.md" --workspace ./my-project --criteria "@criteria.md" \
+  --builder-provider openrouter --builder-model anthropic/claude-sonnet-5.5 \
+  --critic-provider openrouter --critic-model anthropic/claude-haiku-5.5 \
+  --allow-unsandboxed-builder --max-iterations 3
+```
+
+- **The key.** `OPENROUTER_API_KEY` is required whenever either seat is on
+  `openrouter`. Unset, volley exits 5 naming it, before any work. It goes out
+  as a Bearer token, with `X-Title: volley` so OpenRouter attributes the
+  traffic.
+- **The URL.** `VOLLEY_OPENROUTER_URL` (default `https://openrouter.ai/api/v1`)
+  points both seats at a proxy or another OpenAI-compatible gateway, and
+  `--builder-url` / `--critic-url` give one seat a URL of its own, under the
+  rules in [Seats on different machines](#seats-on-different-machines).
+  OpenRouter runs on fascicle's native transport, so there's no peer to
+  install, and the run summary records the transport as `native`.
+- **The seats.** An OpenRouter seat runs volley's tool loop, the same as a
+  local one. The builder gets volley's tools, `bash` included, so it's refused
+  uncontained unless you opt out, exactly like a
+  [local builder](#local-builder). The critic gets the read-only tools and the
+  same retry-and-degrade ladder as a [local critic](#local-critic).
+  `--dry-run` probes each OpenRouter seat's endpoint but runs no critic canary,
+  which would cost money here.
+- **Cost and reasoning.** OpenRouter reports what each call cost, and that
+  charge is the seat's cost, recorded as `provider_reported`, so
+  `--max-cost-usd` trips on an OpenRouter seat as on any other. A model that
+  reasons streams its reasoning, which the terminal shows dimmed unless
+  `--no-thinking` hides it, and which Zed shows as a thought.
+- **In the sandbox.** The container's allowlist reaches only the host gateway,
+  so a contained OpenRouter seat needs `openrouter.ai` let through your
+  `DOCKER-USER` rules. volley doesn't install that rule for you.
+
+## Run volley from Zed
+
+`volley acp` serves volley to an editor over the
+[Agent Client Protocol](https://agentclientprotocol.com), through fascicle's
+`serve_acp`, so a prompt in [Zed](https://zed.dev)'s agent panel starts a volley
+run on the folder Zed has open. The builder's work streams in as the reply, each
+round opens with a **Round N** line, the check shows as a command card, the
+critic's verdict arrives as a thought, and the turn ends with a summary.
+
+```sh
+volley acp \
+  --builder-provider openrouter --builder-model anthropic/claude-sonnet-5.5 \
+  --critic-provider openrouter --critic-model anthropic/claude-haiku-5.5 \
+  --check "pnpm test"
+```
+
+It reads the protocol on stdin and writes nothing but the protocol to stdout,
+with its own progress on stderr, which Zed shows in its agent log. Zed starts it
+for you ([below](#zed-setup)).
+
+### Each prompt is a run
+
+- **Fresh, in place.** Each prompt is a new volley run on the open folder, with
+  no worktree. Its task and its acceptance criteria are both the conversation so
+  far, then the new prompt. An earlier reply keeps only its last 2,000
+  characters, where its summary sits. An earlier prompt's attached files shrink
+  to a line naming each, since they're still on disk. A turn you stopped is
+  marked as stopped.
+- **Three rounds.** `--max-iterations` defaults to 3 per prompt, not 10, since
+  a prompt is one short exchange, and `--max-cost-usd` caps what it spends.
+  Follow a run that didn't converge with "keep going": the summary it ended
+  with lists what the critic still found missing.
+- **The tools.** The builder gets fascicle's workspace tools (`read_file`,
+  `list_files`, `search`, `write_file`, `edit_file`, `run_command`) plus
+  volley's `finish`. The critic gets the three reads. Both stay inside the open
+  folder, and neither gets `fetch`. volley doesn't offer the editor additional
+  directories, so in a workspace with several folders Zed opens the session on
+  the first, and a client that sends more anyway has its session refused.
+- **The summary.** The turn's last message says whether the run converged, in
+  how many rounds, and with what last verdict. When it didn't converge, it
+  lists the unmet criteria, and it names any gate edits and any verdict the
+  critic reached without its tools. A run that fails ends with a summary saying
+  in which round and phase, and why, so "try again" has a request to retry.
+- **Stop.** Pressing stop ends the turn as cancelled, and kills a running
+  command or check along with its whole process group.
+
+### Flags and refusals
+
+`volley acp` takes the run command's seat flags, and requires four of them:
+`--builder-provider`, `--builder-model`, `--critic-provider`, and
+`--critic-model`. A missing one is refused with every missing flag named. The
+rest are optional: `--builder-url`, `--critic-url`, `--builder-max-steps`,
+`--allow-unsandboxed-builder`, `--critic`, `--check`, `--max-iterations`,
+`--max-cost-usd`, and `--state-dir`.
+
+It refuses these before serving, each with exit 5:
+
+| Refused | Why |
+|---|---|
+| `--worktree` | A sibling worktree sits outside the project the editor has open. |
+| `--git` | It commits to the open repo after every phase, which no permission prompt covers. |
+| `--json` | Stdout carries the protocol alone. |
+| a `claude_cli` builder | The Claude CLI runs its own tools under its own permission model, so its edits would never reach the editor's prompts. |
+
+A `claude_cli` critic is allowed: it only reads, and it runs on the host, where
+its login works. The whole config resolves once at startup, so a bad flag or an
+unset `OPENROUTER_API_KEY` exits 5 there, where Zed's agent log shows it, rather
+than failing every prompt.
+
+### Modes and approvals
+
+Each session starts in Manual. Zed's mode picker switches it, and a switch holds
+from the next call on, mid-turn included. Zed also saves the mode you pick as the
+entry's `default_config_options`, and starts the entry's later threads in it.
+
+| Mode | Asks before an edit | Asks before a command |
+|---|---|---|
+| Manual | yes | yes |
+| Accept edits | no | yes |
+| Auto | no | no; offered only contained or opted out (below) |
+
+An edit asks with its diff, and offers "Allow all edits this session", which
+switches the session to Accept edits. A command offers "Always allow" for that
+exact command line: allowing `pnpm test` doesn't cover `pnpm test --watch=false`,
+which asks again. It never offers one for a command with shell control syntax
+such as `;` or `|`. A call you reject reaches the builder as
+`tool_approval_denied`, and its prompt tells it not to reach the same result
+another way.
+
+- **Uncontained, Auto isn't offered.** Outside volley's
+  [sandbox container](#local-builder) (`VOLLEY_CONTAINED`), a person approving
+  each command takes the container's place, so the mode picker lists Manual and
+  Accept edits alone, and the builder's `run_command` asks in both. No client
+  can switch the session to Auto, mid-turn included. A Zed entry left on Auto
+  (`"default_config_options": { "mode": "auto" }`, from a time it was offered)
+  falls back to Manual, with a warning in Zed's log.
+  `--allow-unsandboxed-builder` or `VOLLEY_ALLOW_UNSANDBOXED_BUILDER=1` opts
+  out, and Auto is offered again. So unlike the run command, `volley acp` never
+  refuses an uncontained builder.
+- **The check asks whenever a command would.** In Accept edits and Auto the
+  builder can rewrite a test without asking, and the check runs it next. So the
+  check asks on its own card exactly when a builder command would ask, offering
+  only Allow and Reject, since an "always" for checkride's `pnpm exec` would
+  cover the builder's commands too. A rejected check counts as a failed one, so
+  a round can't converge on work nobody checked.
+- **No keys in commands.** The builder's commands and the check run with the
+  agent's environment minus `OPENROUTER_API_KEY` and `ANTHROPIC_API_KEY`,
+  `PATH` kept, so nothing the builder writes can read the key a seat runs on.
+
+### Where its state goes
+
+Nothing of volley's own lands in the repo. Each prompt's run state goes to
+`<root>/<run id>/`, where the root is `--state-dir`, else
+`$XDG_STATE_HOME/volley`, else `~/.local/state/volley`. Nothing prunes old runs.
+The whole root is safe to delete whenever no prompt is running. A run's
+`trajectory.jsonl` there replays in `fascicle-viewer` like a CLI run's
+([Run artifacts](#run-artifacts)).
+
+### Zed setup
+
+Run `pnpm build` first: Zed runs `dist/cli.js`, and nothing else rebuilds it.
+Then add volley as a custom agent server in Zed's `settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Volley": {
+      "type": "custom",
+      "command": "node",
+      "args": [
+        "/abs/path/to/volley/dist/cli.js", "acp",
+        "--builder-provider", "openrouter", "--builder-model", "anthropic/claude-sonnet-5.5",
+        "--critic-provider", "openrouter", "--critic-model", "anthropic/claude-haiku-5.5",
+        "--check", "pnpm test"
+      ],
+      "env": {
+        "OPENROUTER_API_KEY": "sk-or-v1-...",
+        "PATH": "/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+`PATH` is there for the builder's commands and the check. Each runs with
+`/bin/sh -c`, which reads no shell profile, so a `node` or `pnpm` from nvm, fnm,
+volta, or asdf can come back as `command not found` unless it's on this `PATH`.
+Put the directories that `dirname "$(command -v node)"` and
+`dirname "$(command -v pnpm)"` print at its front.
+
+### Check it in Zed
+
+Run this by hand against a scratch repository with a test command (a
+`package.json` whose `test` script runs `node --test` is enough), using the
+snippet above. Start a thread with "Volley", and check that the mode picker
+shows Manual: Zed starts a thread in the last mode you picked, so an earlier run
+of step 8 leaves it on Accept edits. Stay in Manual unless a step says
+otherwise:
+
+1. Ask for a small change. The builder's work should stream in as the reply,
+   under a **Round 1** line.
+2. When it edits a file, a permission request should show the diff. Allow it,
+   and the card should keep the diff.
+3. When it runs a command, a permission request should show the command before
+   it runs, and once allowed, the card should show the output.
+4. Once the builder finishes, the check should ask, then run as a command card
+   titled `pnpm test`, with its output.
+5. The critic's verdict should show as a thought.
+6. The turn should end with the summary: whether it converged, in how many
+   rounds, and the last verdict.
+7. Ask it to run `sleep 60`, allow it, and press stop. The turn should end as
+   cancelled, and `pgrep -fl 'sleep 60'` should find nothing.
+8. Open the mode picker. It should list Manual and Accept edits, and no Auto,
+   since volley runs uncontained. Switch to Accept edits and ask for another
+   change. The edits shouldn't ask, but a command still should.
+
+Two more round it out. Ask it to run `echo "key=$OPENROUTER_API_KEY"`, and the
+output should be `key=` with nothing after it. And the repository should hold no
+`.volley`.
+
 ## What the builder changed
 
 A check that exits 0 proves the check passed. It does not prove the builder did
@@ -486,7 +777,7 @@ that `--fail-on-gate-edit` cannot fire there.
 
 ## Run artifacts
 
-Everything volley knows lives in the workspace:
+By default, everything volley knows lives in the workspace:
 
 ```
 .volley/
@@ -500,18 +791,30 @@ Everything volley knows lives in the workspace:
 
 A stale `.volley/` from a previous run is rotated to `.volley.bak.<timestamp>/`.
 
+With `--state-dir <root>` (or `state_dir` in a config file), each run writes the
+same files to `<root>/<run id>/` instead, and nothing to the workspace. A
+directory per run never needs rotating, and `config.json` records the root.
+`volley acp` always works this way, under a root of its own
+([Where its state goes](#where-its-state-goes)). `volley matrix` still writes
+its sweep to `.volley-matrix/` in the workspace, and a base config's
+`state_dir` moves only each seat's run state.
+
 The trajectory replays in fascicle's bundled viewer — the `fascicle-viewer` bin
 ships inside the `fascicle` package; there is no separate viewer package:
 
 ```sh
 pnpm dlx --package=fascicle fascicle-viewer .volley/trajectory.jsonl
+pnpm dlx --package=fascicle fascicle-viewer <root>/<run id>/trajectory.jsonl   # under --state-dir
 ```
 
 ## Environment variables
 
 See [.env.example](./.env.example): `VOLLEY_CLAUDE_BIN`, `VOLLEY_AUTH_MODE`,
-`VOLLEY_LOG_LEVEL`, `VOLLEY_NO_COLOR`, `VOLLEY_PRICING_PATH`, and the
-`ANTHROPIC_API_KEY` billing-meter warning.
+`VOLLEY_LOG_LEVEL`, `VOLLEY_NO_COLOR`, `VOLLEY_PRICING_PATH`, the
+`ANTHROPIC_API_KEY` billing-meter warning, each seat's base URL
+(`VOLLEY_OLLAMA_URL`, `VOLLEY_LMSTUDIO_URL`, `VOLLEY_OPENROUTER_URL`), and
+`OPENROUTER_API_KEY` for [OpenRouter](#openrouter) seats. `volley acp` also
+reads `XDG_STATE_HOME` for its state root.
 
 ## Development
 
@@ -520,7 +823,7 @@ pnpm install
 pnpm test          # vitest
 pnpm typecheck     # tsc --noEmit
 pnpm check         # checkride — volley dogfoods its own definition of done
-pnpm build         # tsup → dist/
+pnpm build         # tsdown → dist/
 pnpm diagram       # draw the flow from src/flow.ts with describe.diagram
 ```