@robmclarty/volley 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## v0.10.0 — 2026-10-27
+
+### Added
+- **A builder sees what the last check said (#6).** When the previous iteration's check failed, the builder's prompt carries a `PREVIOUS CHECK RESULT` section: the exit code, the failing slots, and an excerpt capped at 6,000 characters, taken from checkride's digest (volley now runs `pnpm exec checkride --json --digest` and archives `check/digest.md`), else the start of each failing slot's raw output, else the end of a command's output. A resume rebuilds it from the archive, and a check the user rejected under `volley acp` reads as never having run, not as failed.
+- **A tool-loop builder's last steps count down (#6).** The last five steps of a session, or a tenth of a longer budget, end with a note of how many are left and the command that runs the check, and the last says that only `finish` runs on it. When a session hits its step limit, the next prompt says so and asks for the check first.
+- **`--builder-max-output-tokens <n>` caps a tool-loop builder's output per turn (#6).** Or `VOLLEY_BUILDER_MAX_OUTPUT_TOKENS`. Reasoning counts, and Ollama gets it as `num_predict`. An ollama or lmstudio builder is capped at 16,384 by default, an openrouter one only when you set a cap. A turn cut off before it calls a tool costs that step instead of ending the session, and each iteration's summary counts those turns as `builder.truncated_turns`.
+- **`builder_max_steps_hits` counts the builder sessions that ran out of steps (#6).** It's on `RunResult`, so `--json` and `summary.json` carry it, since the warning each one prints goes to stderr, which `--json` silences.
+
+### Changed
+- **Reads don't count against `--builder-max-tool-calls` (#6).** `read_file`, `search_files`, and `list_files` are read-only, so a builder that batches them gets them all, and past the cap the next request names the calls that were dropped. Above a cap of one, step 2 of the builder's prompt no longer names the cap.
+- **The builder is asked to check as it goes (#6).** In a checkride workspace it's told to run `pnpm exec checkride --digest` after each batch of edits and to read `.check/digest.md` before any slot's raw output, and both harness prompts say to verify after each batch of edits, not only before finishing.
+- **`RunResult` has `builder_max_steps_hits` and `ResolvedConfig` has `builder_max_output_tokens`.** Both are required, so SDK code that builds either by hand needs them.
+
+### Fixed
+- **A contained `--worktree` run keeps its work.** The sandbox image has no git identity, so volley's own commits failed inside it: the salvage commit that keeps a converged run's work on `volley/<run id>`, the `--git` checkpoints, and the squash merge. They now fall back to `volley <volley@volley.invalid>` for whatever git lacks, and an identity you configured still wins.
+- **A failing slot's raw output is read only from inside the check directory.** Slot names and output files come from a summary the builder could have written, and a `../` in one could put a file from outside it in front of the critic or the next builder.
+
+### Internal
+- **Built on fascicle 0.17.1**, which names a turn's dropped tool calls to the model and can go on past a turn cut off at its output cap.
+- **The publish workflow keeps its OIDC identity out of the job that runs dependencies.** A `build` job verifies the tag, installs, runs the gate, builds, and packs with read-only permissions, and a separate `publish` job holds `id-token: write` behind the `npm-publish` approval and publishes that tarball with `--ignore-scripts`.
+- **The tests drive the step countdown, the per-turn cap's read-only reads, and the output cap through fascicle's real tool loop**, against a stand-in OpenAI server that now takes several calls a turn and can end one on `length`.
+
+## v0.9.0 — 2026-10-20
+
+### Added
+- **`volley critique` checks and critiques a change already made, once, with no builder (#3).** The change is everything that differs from `--baseline` (default HEAD), committed or not, untracked files included, and the critic sees what a run's critic sees, so critics can be compared on fixed, known-good and known-bad changes without paying for builder turns. It exits 0 on approval over a green check and 2 when the critic asks for changes or the check is red (status `rejected`). Every builder or loop flag, and `--config`, is refused by name (exit 5), and a `--baseline` that isn't a commit fails before any state is written. `run_critique` is exported for harnesses.
+- **`--builder-max-tool-calls <n>` lets a tool-loop builder make several tool calls a turn (#4).** Or `VOLLEY_BUILDER_MAX_TOOL_CALLS`; the default stays 1, since some model and runtime pairs return parallel calls badly. Above 1, the builder's prompt asks it to batch independent reads but make one change or command per turn. The cap is recorded with the run and kept on resume.
+- **Each run names its state directory.** `RunResult`, and so `--json` and `summary.json`, carry `run_state_dir`, and a run prints `state: <dir>` when it starts and in its final summary. `--dry-run` names the state root.
+- **`sandbox_run_args` mounts a contained run's own state directory.** Its `run_state` option binds the host's `<root>/<run id>/` at that run's directory under `SANDBOX_STATE_ROOT`, never the whole root, so the builder inside can't read or rewrite another run's state. `default_state_root` and `SANDBOX_STATE_ROOT` are exported.
+
+### Changed
+- **Run state leaves the workspace by default (#5).** Without `--state-dir`, a run's config, summary, trajectory, feedback, verdict, and iterations go to `<root>/<run id>/`, where the root is `$XDG_STATE_HOME/volley`, else `~/.local/state/volley`, as under `volley acp`. A check that reads every file, dot-directories included, no longer fails from the second iteration on over volley's own feedback. A harness that read `<workspace>/.volley/` reads `run_state_dir` instead. A run directory volley can't write is a configuration error (exit 5), and inside the sandbox the message names the mount. The critic's "prior iteration state" line now drops by default, since the iterations sit outside the tree it reads.
+- **`volley resume <id>` finds a run from any directory**, under `--state-dir` or the default root, and falls back to the workspace's `.volley/` for a run an older volley started. It refuses a run directory with a symbolic link in it, an id that isn't a run id, and a critique, which has nothing to resume.
+- **A resume on the host runs only a config this machine signed.** volley signs each run's `config.json` (as `config.sig`) under a key kept at `$XDG_CONFIG_HOME/volley/run-key`, else `~/.config/volley/run-key`, and signs nothing inside the sandbox, so a contained run's builder can't plant a check or seat for a host-side resume to run. A config without a valid signature (a contained run's, another machine's, an older volley's, or one edited by hand) resumes only with `--trust-config`, which first shows the check and seats it's about to run, escaped so a planted control sequence can't disguise them. Resume a contained run inside its container.
+- **`ResolvedConfig` has `mode` and `builder_max_tool_calls`, and `RunResult` has `mode` and `run_state_dir`.** All are required, so SDK code that builds either by hand needs them. `resolve_config` always sets `state_dir`, where null still means the workspace's `.volley/`. `RunStatus` gains `rejected`, and a critique's `comparison.builder_transport` is null.
+
+### Fixed
+- **`search_files` and `list_files` on a file path search or list that file.** They walked it as a directory and answered "no matches", which led a local critic to reject a sound change. A path that doesn't exist now says so.
+- **A critic verdict with null `feedback` or `unmet_criteria` reads as empty.** A critic that holds tools isn't constrain-decoded, and such an answer failed schema validation and exited 6.
+- **A `--state-dir` inside the workspace stays out of the builder's work.** Its files showed up in the change list the critic reads and were committed by `--git` checkpoints. A `--state-dir` that is the workspace itself is refused (exit 5).
+
+### Internal
+- **The tests keep run state and the signing key out of your home directory.** A setup file gives each test file its own `XDG_STATE_HOME` and `XDG_CONFIG_HOME`, and fails a file that leaves a test run in the real state root or makes the real key.
+
 ## v0.8.0 — 2026-10-19
 
 ### Added

package/README.md

@@ -54,8 +54,8 @@ volley \
 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. An [OpenRouter](#openrouter) seat's cost is the charge
+expected cost. Per-run totals land in the run's `summary.json` (see
+[Run artifacts](#run-artifacts)) and the final 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
@@ -73,19 +73,28 @@ prompt ──> builder (full agentic session in your workspace)
 ```
 
 - **Builder** gets the task, the acceptance criteria, and the previous
-  iteration's critic feedback. It has full tools (Read/Write/Edit/Bash) and
-  runs with `--permission-mode acceptEdits` by default.
+  iteration's critic feedback. When the previous iteration's check failed, it
+  also gets what the check said: checkride's digest of the failing slots, else
+  the start of each failing slot's raw output, else the end of a command's
+  output, capped at 6,000 characters. If the previous session hit its step
+  limit, the prompt says so and asks it to run the check first. In a
+  checkride workspace it's asked to run `pnpm exec checkride --digest` after
+  each batch of edits and to read `.check/digest.md` when that fails, one
+  capped file for every failing slot, before any slot's raw output. It has full tools
+  (Read/Write/Edit/Bash) and runs with `--permission-mode acceptEdits` by
+  default.
 - **Check** is auto-detected: if the workspace uses checkride, volley runs
-  `pnpm exec checkride --json` and gates on the summary. Any shell command
-  works too (`--check "npm test"`), or `--check none` for critic-only runs.
+  `pnpm exec checkride --json --digest` and gates on the summary. Any shell
+  command works too (`--check "npm test"`), or `--check none` for critic-only
+  runs.
 - **Critic** is read-only (`Read`, `Grep`, `Glob` — no write path at all) and
   returns a schema-validated `{ verdict, feedback, unmet_criteria }`. It is told
   which files the builder changed, so it reviews a change rather than a tree.
-  The harness writes `.volley/feedback.md` and `.volley/verdict`; the critic
+  The harness writes the run's `feedback.md` and `verdict`; the critic
   cannot get them wrong.
 
 Each iteration is a fresh session — no context carries over except through the
-workspace filesystem and the critic's feedback. Swap the critic to change what
+workspace filesystem, the critic's feedback, and a failed check's output. Swap the critic to change what
 the loop optimizes for: `--critic reviewer` (default), `optimizer`,
 `researcher`, or a path to your own system prompt.
 
@@ -150,6 +159,7 @@ volley [options]
 volley --config <path>
 volley resume <run-id>
 volley matrix --builders <models> --critics <models> --config <path>
+volley critique --criteria <criteria> [--baseline <rev>] [options]
 volley acp --builder-provider <name> --builder-model <model> \
   --critic-provider <name> --critic-model <model> [options]
 ```
@@ -163,7 +173,9 @@ volley acp --builder-provider <name> --builder-model <model> \
 | `--builder-model` | `opus` | `opus`/`sonnet`/`haiku` or a full model id. |
 | `--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`. |
+| `--builder-max-steps` | `50` | Tool-loop builder step cap per iteration. Or `VOLLEY_BUILDER_MAX_STEPS`. Ignored for `claude_cli`. `--json` and `summary.json` count the sessions that hit it as `builder_max_steps_hits`. |
+| `--builder-max-tool-calls` | `1` | Tool calls a tool-loop builder may make per turn, not counting reads (`read_file`, `search_files`, `list_files`); past it, fascicle runs the calls before the first one over, drops the rest, and tells the model which it dropped. Raise it for a model and runtime that return parallel calls well. Or `VOLLEY_BUILDER_MAX_TOOL_CALLS`. Ignored for `claude_cli`. |
+| `--builder-max-output-tokens` | `16384` (ollama, lmstudio), the provider's (openrouter) | Output tokens a tool-loop builder may generate per turn, reasoning included (`num_predict` on Ollama). A turn cut off at it before it calls a tool costs that step, not the session. Or `VOLLEY_BUILDER_MAX_OUTPUT_TOKENS`. 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`, `lmstudio`, or `openrouter` (see [Local critic](#local-critic) and [OpenRouter](#openrouter)). |
@@ -178,7 +190,7 @@ volley acp --builder-provider <name> --builder-model <model> \
 | `--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`. |
-| `--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. |
+| `--state-dir` | `$XDG_STATE_HOME/volley`, else `~/.local/state/volley` | The root each run keeps its state under, at `<path>/<run id>/`, never 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. |
@@ -196,7 +208,7 @@ checkride.
 | Code | Meaning |
 |---|---|
 | 0 | Check passed and verdict approved. |
-| 2 | Max iterations reached without success. |
+| 2 | Max iterations reached without success; for `volley critique`, the critic asked for changes or the check failed. |
 | 3 | Builder/provider error. |
 | 4 | Check pipeline error (broken pipeline, not failing checks). |
 | 5 | Configuration error. |
@@ -229,17 +241,37 @@ export default config;
 ### Resume
 
 ```sh
-volley resume <run-id>            # in the workspace directory
-volley resume <run-id> --workspace ./my-project
+volley resume <run-id>                             # from any directory
 volley resume <run-id> --state-dir ~/volley-runs   # a run started with --state-dir
+volley resume <run-id> --workspace ./my-project    # a run an older volley kept in .volley/
 ```
 
-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.
+`resume` finds the run at `<root>/<run-id>/` under `--state-dir`, else the
+default root, from any directory, since the run's recorded config names its
+workspace. A run an older volley started keeps its state in the workspace's
+`.volley/`, and resumes there: point `--workspace` at it, or run `resume` from
+inside it. A run directory with a symbolic link in it is refused, since volley
+never writes one. The resumed run's first builder gets what the last completed
+iteration left it, as it would have without the stop: the critic's feedback,
+the check's output if it failed, and the step-limit note.
+
+**A resume on the host runs only a config this machine signed.** A resume runs
+what the run's `config.json` says, its check command and its seats included.
+So volley on the host signs each config it writes, as `config.sig`, under a
+key that stays on the machine (`$XDG_CONFIG_HOME/volley/run-key`, else
+`~/.config/volley/run-key`), and a resume on the host refuses a config whose
+signature doesn't hold (exit 5). That covers:
+
+- **A contained run's config.** Nothing is signed inside the sandbox, and the
+  builder there can rewrite its own run's config, so resume it inside its
+  container, with the same mount. Inside the container, nothing is checked.
+- **Another machine's config, an older volley's, or one you edited.** Read it,
+  then pass `--trust-config`, and the resume says which check and seats it's
+  about to run before it runs them.
 
 Continues from the last completed iteration with the saved feedback and cost
-totals. An iteration interrupted mid-phase is discarded and re-run.
+totals. An iteration interrupted mid-phase is discarded and re-run. A
+[critique](#critique-a-fixed-change) has one round and nothing to resume.
 
 ### Matrix sweep
 
@@ -272,9 +304,10 @@ local providers share one GPU, so parallel combos would thrash the model loader.
 Each run forces `--worktree --discard-worktree` for a clean per-run reset — a
 sweep wants verdicts, so each seat's effects are isolated and then thrown away,
 leaving neither a branch nor a commit behind — so the **workspace must be a git
-repository**. Every attempt's run state is written to
-`.volley-matrix/<builder>__<critic>/run-NN/summary.json`, the whole sweep to
-`.volley-matrix/matrix.json`, and one aggregate table goes to stderr:
+repository**. Each attempt keeps its run state under the state root like any
+run, and its summary, which names that state as `run_state_dir`, is copied to
+`.volley-matrix/<builder>__<critic>/run-NN/summary.json`. The whole sweep goes
+to `.volley-matrix/matrix.json`, and one aggregate table goes to stderr:
 
 ```
 builder         critic         pass  iters  wall    cost   salvage  flags       why
@@ -309,6 +342,48 @@ A run that does not converge is a *result*, shown in the table; the sweep exits
 0 as long as every attempt produced a summary, and nonzero only when one
 produced none at all (`status: broke`).
 
+### Critique a fixed change
+
+`volley critique` runs the check and the critic once over a change already
+made, with no builder. It's how you choose a critic: replay the same
+known-good and known-bad changes through the critic seat, across models and
+prompts, and count how many of the bad ones each critic rejects. A matrix sweep
+can't tell a critic that reads from one that approves everything, since both
+pass whenever the builder happens to be right.
+
+```sh
+volley critique --workspace ./repo --baseline <rev> \
+  --criteria "@criteria.md" \
+  --critic-provider ollama --critic-model qwen3:8b --critic reviewer
+```
+
+- **The change** is everything that differs from `--baseline`, committed or
+  not, untracked files included: the set a run reports for its builder. Without
+  `--baseline` it's HEAD, so the uncommitted and untracked edits are the
+  change. A revision that isn't a commit is a configuration error (exit 5).
+- **The critic** sees what it sees in a run: the changed paths and gate edits,
+  the check's section, and the same preset or prompt file. `--prompt` is
+  optional and only recorded, since a critic judges against `--criteria`.
+- **The state** is a one-round run's, under the state root
+  ([Run artifacts](#run-artifacts)). The summary records `mode: "critique"`
+  and no builder: `builder` is null in the iteration's archive, and so is the
+  comparison block's `builder_transport`. The archived `critic.tool_calls` says
+  how much the critic read before it judged.
+- **Exit codes**: 0 when the critic approves over a green check, 2 when it asks
+  for changes or the check is red (`status: "rejected"`), and the usual codes
+  for provider, check-pipeline, configuration, and critic errors.
+- **Flags**: the critic's seat flags, `--check`, `--critic`, `--gate-paths`,
+  `--state-dir`, `--run-id`, `--dry-run` (with the critic-seat canary),
+  `--json`, and the output flags work as they do for a run. Every flag only a
+  builder or its loop uses, from `--builder-model` and `--max-iterations` to
+  `--worktree`, `--git`, and `--fail-on-gate-edit`, is refused by name (exit
+  5), and so is `--config`, since a run's config file sets a builder.
+
+With no builder, a local critic needs no sandbox opt-in. The check still runs
+whatever the repository's check runs, though, so review an untrusted change
+with `volley critique` inside the container, its run directory mounted as a
+run's would be ([Local builder](#local-builder)).
+
 ## Local critic
 
 The critic is read-only and schema-constrained, which makes it a good fit for
@@ -338,7 +413,7 @@ Providers and their setup:
 Install the peer for your provider in the project running volley (e.g.
 `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
+declared peer range (`^4` for fascicle 0.17.1, 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
@@ -389,7 +464,40 @@ surface itself — `read_file`, `search_files`, `list_files`, `write_file`,
 `edit_file`, `bash`, `fetch`, and an explicit `finish` — and runs one bounded
 tool loop per iteration (capped by `--builder-max-steps`, default 50; hitting
 the cap is treated as partial work, not an error). The produced workspace goes
-to check + critic exactly like a `claude_cli` build.
+to check + critic exactly like a `claude_cli` build. Each hit prints a warning,
+and `--json`, which silences warnings, and `summary.json` count them as
+`builder_max_steps_hits`.
+
+So that a model that explores first still verifies, the last few steps of each
+session count down: five, or a tenth of a longer budget. Each of those turns
+ends with a note of how many steps are left and the command that runs the
+check, and the last says that only `finish` runs on it, as fascicle refuses
+any other call there. The note is added to what that one turn sends, never to
+the transcript, so it never piles up and a local runtime's cached prefix holds.
+
+A local builder makes one tool call per turn by default, since some model and
+runtime pairs return parallel calls badly. Reads don't count: `read_file`,
+`search_files`, and `list_files` are read-only, so a model that batches them,
+as qwen3.8 on Ollama's MLX runner does, gets them all. A turn's calls run in
+order, so a read can't race an edit. Past the cap, fascicle drops the
+remaining calls and the next request names them, so the model can make them
+again. For a pair that handles parallel calls, `--builder-max-tool-calls <n>`
+lets each turn make up to `n` changes or commands, and the builder's prompt
+then asks it to batch independent reads but make one change or command per
+turn.
+
+A thinking model can spend one turn reasoning for a long time: on Ollama's MLX
+runner, with nothing capping a turn, one qwen3.8 turn ran to 30,847 tokens and
+19 minutes before a single `read_file`, since the runner lets an unset
+`num_predict` run to the model's trained context less the prompt. So a local
+builder's turns are capped at 16,384 output tokens, reasoning included, and
+`--builder-max-output-tokens <n>` sets another cap. A turn cut off there
+before it makes a tool call costs that one step: fascicle tells the model it
+hit the limit and the session goes on. Each iteration's `summary.json` counts
+those turns as `builder.truncated_turns`. An OpenRouter builder is capped only
+when you set one, since a hosted model has its own output limit and can refuse
+a request for more; uncapped, a turn cut off at the provider's limit still ends
+the session.
 
 ```sh
 volley \
@@ -417,6 +525,26 @@ mangled crossing the boundary — so a *contained* Claude role must drive by API
 key (`VOLLEY_AUTH_MODE=api_key` with `ANTHROPIC_API_KEY`); the all-Claude
 subscription path stays on the host, Docker-free.
 
+**A contained run's state needs a mount of its own.** The container's root
+filesystem is read-only, so volley inside has nowhere to keep the run's state
+until you mount the run's own host directory where it looks:
+
+1. Create `<root>/<run id>/` on the host first, empty. On Linux, Docker creates
+   a missing one owned by root, and the container's user can't write it.
+2. Mount it at `/home/node/.local/state/volley/<run id>`. That's
+   `SANDBOX_STATE_ROOT`, and `run_state` on `sandbox_run_args` renders the
+   flag.
+3. Pass volley the same `--run-id`.
+
+Without the mount, the run stops before any spend (exit 5) and says what to
+mount. Mount that one directory, never the whole root: the builder runs
+arbitrary commands, and with the root mounted it could read every other run's
+trajectory or plant a check in another run's config. Its own run's config is
+still the builder's to rewrite, so a resume on the host refuses it, since
+volley signs only the configs it writes outside the sandbox
+([Resume](#resume)). Resume a contained run inside the container, with the same
+mount.
+
 To run a local builder uncontained on the host anyway, opt out with
 `--allow-unsandboxed-builder` (or `VOLLEY_ALLOW_UNSANDBOXED_BUILDER=1`), which
 prints a one-time warning — only point it at a workspace you are willing to let a
@@ -435,6 +563,10 @@ surprise at teardown:
 | `--worktree` | Committed onto `volley/<run id>` and left there. Recover it with `git switch volley/<run id>` or `git cherry-pick`; the branch is named in the final summary and in `--json` as `salvaged_branch`. |
 | `--worktree --discard-worktree` | Thrown away with the branch — verdicts only, nothing kept. |
 
+volley's own commits (`--git` checkpoints, the squash merge, and the salvage
+commit) use your git identity. Where git has none, as in the sandbox image,
+they fall back to `volley <volley@volley.invalid>` rather than fail.
+
 Any run that does *not* converge (cost cap, budget exhausted, interrupt, error)
 is discarded wholesale in all three modes: an abandoned phase leaves nothing
 behind.
@@ -606,7 +738,7 @@ for you ([below](#zed-setup)).
 `--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`,
+`--builder-max-tool-calls`, `--builder-max-output-tokens`, `--allow-unsandboxed-builder`, `--critic`, `--check`, `--max-iterations`,
 `--max-cost-usd`, and `--state-dir`.
 
 It refuses these before serving, each with exit 5:
@@ -665,12 +797,13 @@ another way.
 
 ### Where its state goes
 
-Nothing of volley's own lands in the repo. Each prompt's run state goes to
+Nothing of volley's own lands in the repo. Each prompt's run state goes under
+the same state root as any run's ([Run artifacts](#run-artifacts)):
 `<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)).
+`$XDG_STATE_HOME/volley`, else `~/.local/state/volley`. An unwritable root
+stops `volley acp` at startup, so it shows once in the agent log. 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.
 
 ### Zed setup
 
@@ -748,7 +881,7 @@ iteration and reports what moved:
   which ones moved.
 - Changed paths matching the **gate** — the tests, fixtures, and check
   configuration that decide whether the work passes — are called out separately
-  in the prompt, listed in `.volley/summary.json` as `comparison.gate_edits`,
+  in the prompt, listed in the run's `summary.json` as `comparison.gate_edits`,
   and warned about on stderr as they happen.
 
 A gate edit is not misconduct: plenty of tasks are *about* the tests. It is the
@@ -777,34 +910,49 @@ that `--fail-on-gate-edit` cannot fire there.
 
 ## Run artifacts
 
-By default, everything volley knows lives in the workspace:
+Everything volley knows about a run lives in a directory of its own, outside
+the workspace: `<root>/<run id>/`, where the root is `--state-dir` (or
+`state_dir` in a config file), else `$XDG_STATE_HOME/volley`, else
+`~/.local/state/volley`.
 
 ```
-.volley/
+<root>/<run id>/
   config.json          # resolved run config (immutable per run)
+  config.sig           # this machine's signature over config.json (none from inside the sandbox)
   summary.json         # run-level usage, cost, status
   trajectory.jsonl     # every fascicle trajectory event (replayable, below)
   feedback.md          # current critic feedback (harness-written)
   verdict              # approved | changes_requested (harness-written)
-  iterations/NNN/      # per-iteration archive: feedback, verdict, check artifacts, summary
+  iterations/NNN/      # per-iteration archive: feedback, verdict, check artifacts and digest, summary
 ```
 
-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.
+- **Why outside.** Some checks read every file in the tree, dot-directories
+  included, as markdownlint-cli2 and checkride's links walk do. Kept in the
+  workspace, the run's own `feedback.md` would fail them from the second
+  iteration on, a failure the builder can't fix. Kept out, the workspace holds
+  only the builder's work, and `--git` checkpoints never commit volley's files.
+- **Finding a run.** A run prints `state: <dir>` when it starts and again in its
+  final summary, and `--json` and `summary.json` carry it as `run_state_dir`.
+  `--dry-run` names the root, and `--run-id` names the directory.
+- **Unwritable.** A run directory volley can't write is a configuration error
+  (exit 5) before any spend. In the sandbox container, mount the run's own
+  directory ([Local builder](#local-builder)).
+- **Pruning.** Nothing prunes old runs. A root volley creates is yours alone
+  (0700), since trajectories hold prompts and tool output. A reused `--run-id`
+  rotates the earlier run aside to `<run id>.bak.<timestamp>/`.
+- **Older runs.** An older volley kept the same files in the workspace's
+  `.volley/`. `volley resume` still finds such a run there, and resumes it in
+  place once you pass `--trust-config`, since an older volley signed nothing
+  ([Resume](#resume)).
+
+`volley matrix` writes its sweep to `.volley-matrix/` in the workspace, and a
+base config's `state_dir` moves each seat's run state as it would any run's.
 
 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
+pnpm dlx --package=fascicle fascicle-viewer ~/.local/state/volley/<run id>/trajectory.jsonl
 ```
 
 ## Environment variables
@@ -813,8 +961,9 @@ See [.env.example](./.env.example): `VOLLEY_CLAUDE_BIN`, `VOLLEY_AUTH_MODE`,
 `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.
+`OPENROUTER_API_KEY` for [OpenRouter](#openrouter) seats. Every run reads
+`XDG_STATE_HOME` for its default state root, and `XDG_CONFIG_HOME` for where
+it keeps the key it signs run configs with.
 
 ## Development