@robmclarty/volley 0.7.0 → 0.8.0

package/dist/index.js

@@ -4,7 +4,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import { aborted_error, branch, claude_cli_reported, create_engine, fallback, loop, model_call, pipe, retry, run, sequence, step, throughput } from "fascicle";
-import { filesystem_logger } from "fascicle/adapters";
+import { filesystem_logger, tee_logger } from "fascicle/adapters";
 import { lookup } from "node:dns";
 import { Readability } from "@mozilla/readability";
 import ipaddr from "ipaddr.js";
@@ -315,6 +315,13 @@ function error_kind(err) {
 * and 404s. */
 const DEFAULT_OLLAMA_URL = "http://localhost:11434";
 const DEFAULT_LMSTUDIO_URL = "http://localhost:1234/v1";
+/** OpenRouter's API root, the one fascicle's openrouter adapter defaults to. */
+const DEFAULT_OPENROUTER_URL = "https://openrouter.ai/api/v1";
+/** The variable an `openrouter` seat's API key is read from. */
+const OPENROUTER_KEY_VAR = "OPENROUTER_API_KEY";
+/** The variable a `claude_cli` seat's API key is read from, which the Claude
+* CLI also reads on its own. */
+const ANTHROPIC_KEY_VAR = "ANTHROPIC_API_KEY";
 /** Loopback authorities the container→host crossing rewrites. A base URL
 * pointing at one of these is local to wherever volley runs; contained, that is
 * *inside* the sandbox container, where the host LLM daemon is unreachable
@@ -361,9 +368,15 @@ const SEAT_URL_SOURCES = {
 		env: "VOLLEY_LMSTUDIO_URL",
 		default_url: DEFAULT_LMSTUDIO_URL,
 		normalize: strip_trailing_slashes
+	},
+	openrouter: {
+		env: "VOLLEY_OPENROUTER_URL",
+		default_url: DEFAULT_OPENROUTER_URL,
+		normalize: strip_trailing_slashes
 	}
 };
-/** The providers that take a seat URL (`--builder-url` / `--critic-url`). */
+/** The providers that take a seat URL (`--builder-url` / `--critic-url`), and
+* so get their endpoint probed by `--dry-run`. */
 const SEAT_URL_PROVIDERS = Object.keys(SEAT_URL_SOURCES);
 /** Whether a seat on `provider` reaches its model at a base URL volley
 * configures, and so takes a URL of its own. */
@@ -376,16 +389,25 @@ function present(value) {
 	return trimmed === "" ? null : trimmed;
 }
 /** The base URL a seat's model calls go to: the seat's own URL, else the
-* provider's env var (`VOLLEY_OLLAMA_URL` / `VOLLEY_LMSTUDIO_URL`), else its
-* default. A seat never falls back to the other seat's URL. The result is
-* normalized, then a loopback authority is crossed to the host LLM endpoint
-* when volley runs contained. Both seats can be loopback URLs on different
-* ports, and each crosses on its own port. */
+* provider's env var (`VOLLEY_OLLAMA_URL` / `VOLLEY_LMSTUDIO_URL` /
+* `VOLLEY_OPENROUTER_URL`), else its default. A seat never falls back to the
+* other seat's URL. The result is normalized, then a loopback authority is
+* crossed to the host LLM endpoint when volley runs contained. Both seats can
+* be loopback URLs on different ports, and each crosses on its own port. */
 function seat_base_url(provider, seat_url, env) {
 	const source = SEAT_URL_SOURCES[provider];
 	const raw = present(seat_url) ?? present(env[source.env]) ?? source.default_url;
 	return cross_to_host_gateway(source.normalize(raw), env);
 }
+/** The API key an `openrouter` seat sends, from `OPENROUTER_API_KEY`. An unset
+* or blank key is a config error naming the variable, which `resolve_config`
+* raises before any work, because fascicle's own "requires a non-empty
+* api_key" doesn't say where the key comes from. */
+function openrouter_api_key(env) {
+	const key = present(env[OPENROUTER_KEY_VAR]);
+	if (key === null) throw config_error(`${OPENROUTER_KEY_VAR} is not set: an openrouter seat sends it as its API key`);
+	return key;
+}
 function load_pricing_overrides(path) {
 	if (!existsSync(path)) throw config_error(`VOLLEY_PRICING_PATH not found: ${path}`);
 	try {
@@ -398,29 +420,44 @@ function load_pricing_overrides(path) {
 * peer (`ai-sdk-ollama` / `@ai-sdk/openai-compatible`) is loaded lazily by
 * fascicle only when the provider actually runs. The entry is complete, because
 * `Engine.with_providers` replaces a provider's whole entry: whatever this
-* returns is all a seat's derived engine knows about the provider.
+* returns is all a seat's derived engine knows about the provider, so an
+* `openrouter` entry carries its key and its transport along with its URL.
+*
+* `openrouter` runs on fascicle's native transport, its OpenAI-compatible core,
+* so no ai-sdk peer gets installed for it, and its `X-Title` attributes the
+* traffic to volley.
 *
-* Native transport is the deferred future bridge, not adopted here: volley stays
-* on the ai_sdk transport, which fascicle 0.14.0 already selects by default
-* (`transport?: 'ai_sdk' | 'native'` defaults to `'ai_sdk'`), so no field is
-* needed today. Flipping later is a one-line change — add `transport: 'native'`
-* to the ollama/lmstudio entry returned below, which both seats' engines then
-* share. No URL re-pointing is required: `seat_base_url` already yields the
-* daemon-root URL the native `/api/chat` transport wants (its adapter appends
-* `/api/chat` itself), which is exactly what the v0.3.1 base-URL fix produces.
+* For the local providers, native transport is the deferred future bridge, not
+* adopted here: they stay on the ai_sdk transport, which fascicle 0.14.0 already
+* selects by default (`transport?: 'ai_sdk' | 'native'` defaults to `'ai_sdk'`),
+* so no field is needed today. Flipping later is a one-line change — add
+* `transport: 'native'` to the ollama/lmstudio entry returned below, which both
+* seats' engines then share. No URL re-pointing is required: `seat_base_url`
+* already yields the daemon-root URL the native `/api/chat` transport wants
+* (its adapter appends `/api/chat` itself), which is exactly what the v0.3.1
+* base-URL fix produces.
 * Kept as a proven-once-then-reverted option so the transport stays a clean
 * second variable in the model-vs-transport comparison. Flipping it today would
 * also lose the reasoning: fascicle's native Ollama adapter drops
 * `message.thinking`, with `think` unset or true (robmclarty/fascicle#12), so a
 * thinking seat's reasoning would vanish from the terminal and the trajectory.
 *
-* Both providers' base URLs cross a loopback authority to `VOLLEY_MODEL_HOST` when
-* volley runs contained, so an in-container model client reaches the
+* Every provider's base URL crosses a loopback authority to `VOLLEY_MODEL_HOST`
+* when volley runs contained, so an in-container model client reaches the
 * host LLM endpoint at `host.docker.internal`; on the host / unsandboxed path the
 * override is unset and this is a no-op. */
 function seat_provider_config(provider, seat_url, env) {
 	const base_url = seat_base_url(provider, seat_url, env);
-	return provider === "ollama" ? { ollama: { base_url } } : { lmstudio: { base_url } };
+	switch (provider) {
+		case "ollama": return { ollama: { base_url } };
+		case "lmstudio": return { lmstudio: { base_url } };
+		case "openrouter": return { openrouter: {
+			api_key: openrouter_api_key(env),
+			base_url,
+			transport: "native",
+			x_title: "volley"
+		} };
+	}
 }
 /** Per-run engine. `claude_cli` is always configured with `options.workspace`
 * (the run's build root) as its session cwd; any URL-taking provider selected
@@ -440,7 +477,7 @@ function create_volley_engine(options) {
 		setting_sources: ["project", "local"],
 		auth_mode,
 		...binary !== void 0 && binary.length > 0 ? { binary } : {},
-		...auth_mode === "api_key" && env["ANTHROPIC_API_KEY"] !== void 0 ? { api_key: env["ANTHROPIC_API_KEY"] } : {}
+		...auth_mode === "api_key" && env[ANTHROPIC_KEY_VAR] !== void 0 ? { api_key: env[ANTHROPIC_KEY_VAR] } : {}
 	} };
 	if (takes_seat_url(options.critic_provider)) Object.assign(providers, seat_provider_config(options.critic_provider, options.critic_url ?? null, env));
 	if (takes_seat_url(options.builder_provider)) Object.assign(providers, seat_provider_config(options.builder_provider, options.builder_url ?? null, env));
@@ -490,18 +527,24 @@ const DEFAULT_SANDBOX_IMAGE = "volley-sandbox:latest";
 const BUILDER_PROVIDERS = [
 	"claude_cli",
 	"ollama",
-	"lmstudio"
+	"lmstudio",
+	"openrouter"
+];
+/** Builder providers that drive their model through volley's own tool loop —
+* a real `bash` (write + exec), wherever the model runs. Refused unless volley
+* is running inside a container (the correct blast-radius default) or the
+* operator explicitly opts out; `claude_cli` has its own permission model and
+* is exempt. */
+const TOOL_LOOP_BUILDER_PROVIDERS = [
+	"ollama",
+	"lmstudio",
+	"openrouter"
 ];
-/** Builder providers that run a local model through volley's own tool loop —
-* a real `bash` (write + exec). Refused unless volley is running
-* inside a container (the correct blast-radius default) or the operator
-* explicitly opts out; `claude_cli` has its own permission model and is
-* exempt. */
-const LOCAL_BUILDER_PROVIDERS = ["ollama", "lmstudio"];
 const CRITIC_PROVIDERS = [
 	"claude_cli",
 	"ollama",
-	"lmstudio"
+	"lmstudio",
+	"openrouter"
 ];
 const CRITIC_PRESETS = [
 	"reviewer",
@@ -580,7 +623,8 @@ function resolve_sandbox_image(raw, env) {
 }
 /** The `--allow-unsandboxed-builder` flag/config value wins; otherwise
 * `VOLLEY_ALLOW_UNSANDBOXED_BUILDER=1` (or `=true`) opts out. Any other value
-* (incl. `0`/`false`/unset) leaves the local builder refused unless contained. */
+* (incl. `0`/`false`/unset) leaves a tool-loop builder refused unless
+* contained. */
 function resolve_allow_unsandboxed_builder(raw, env) {
 	if (raw.allow_unsandboxed_builder === true) return true;
 	const env_value = env["VOLLEY_ALLOW_UNSANDBOXED_BUILDER"];
@@ -600,7 +644,7 @@ function resolve_seat_url(seat, value, provider) {
 	if (typeof value !== "string") throw config_error(`${setting} must be a URL string; got a ${typeof value}`);
 	const url = value.trim();
 	if (url === "") return null;
-	if (!takes_seat_url(provider)) throw config_error(`${setting} applies only to a ${seat} on ${SEAT_URL_PROVIDERS.join(" or ")}; ${seat}-provider is ${provider}`);
+	if (!takes_seat_url(provider)) throw config_error(`${setting} applies only to a ${seat} on ${new Intl.ListFormat("en", { type: "disjunction" }).format(SEAT_URL_PROVIDERS)}; ${seat}-provider is ${provider}`);
 	let parsed;
 	try {
 		parsed = new URL(url);
@@ -612,6 +656,16 @@ function resolve_seat_url(seat, value, provider) {
 	if (parsed.search !== "" || parsed.hash !== "") throw config_error(`${setting} must not carry a query or fragment; got: ${url}`);
 	return url;
 }
+/** `--state-dir` (`state_dir`): the root each run's state sits under at
+* `<root>/<run_id>/`, resolved against `cwd` so a resumed run finds the same
+* place, or null to keep `<workspace>/.volley/`. An empty value counts as unset,
+* as it does for a seat URL. */
+function resolve_state_dir(value, cwd) {
+	if (value === void 0 || value === null) return null;
+	if (typeof value !== "string") throw config_error(`--state-dir (state_dir) must be a path string; got a ${typeof value}`);
+	const path = value.trim();
+	return path === "" ? null : resolve(cwd, path);
+}
 /** volley *detects* it is running inside its sandbox container rather than
 * starting the container itself. The signal is the `VOLLEY_CONTAINED=1` marker
 * volley's own image bakes in (`Dockerfile` `ENV`), so a `docker run <hardened
@@ -624,6 +678,12 @@ function detect_containment(env) {
 	const value = env["VOLLEY_CONTAINED"];
 	return value === "1" || value === "true";
 }
+/** Whether a tool-loop builder's commands would reach the host with nothing in
+* between: volley isn't contained, and the operator hasn't opted out with
+* `--allow-unsandboxed-builder` or `VOLLEY_ALLOW_UNSANDBOXED_BUILDER`. */
+function unguarded_builder(raw, env) {
+	return !detect_containment(env) && !resolve_allow_unsandboxed_builder(raw, env);
+}
 /** A caller's run id names the run's `volley/<run id>` branch, so it is held to
 * what a branch name accepts without quoting: letters, digits, `-`, and `_`,
 * starting with a letter or digit so it never reads as an option. */
@@ -656,12 +716,13 @@ function resolve_config(raw, options = {}) {
 	if (!BUILDER_PROVIDERS.includes(builder_provider)) throw config_error(`--builder-provider must be one of ${BUILDER_PROVIDERS.join(", ")}; got: ${String(raw.builder_provider)}`);
 	const allow_unsandboxed_builder = resolve_allow_unsandboxed_builder(raw, env);
 	const contained = detect_containment(env);
-	if (LOCAL_BUILDER_PROVIDERS.includes(builder_provider) && !contained && !allow_unsandboxed_builder) throw config_error(`builder-provider '${builder_provider}' runs a local model with a real bash (write + exec) — refused unless contained. Launch volley inside its sandbox container (docker run <hardened flags> <image> volley run …, which sets VOLLEY_CONTAINED=1), or pass --allow-unsandboxed-builder (VOLLEY_ALLOW_UNSANDBOXED_BUILDER=1) to run uncontained on the host.`);
+	if (TOOL_LOOP_BUILDER_PROVIDERS.includes(builder_provider) && options.uncontained_builder !== "ask" && unguarded_builder(raw, env)) throw config_error(`builder-provider '${builder_provider}' runs volley's tool loop with a real bash (write + exec) — refused unless contained. Launch volley inside its sandbox container (docker run <hardened flags> <image> volley run …, which sets VOLLEY_CONTAINED=1), or pass --allow-unsandboxed-builder (VOLLEY_ALLOW_UNSANDBOXED_BUILDER=1) to run uncontained on the host.`);
 	const builder_max_steps = resolve_builder_max_steps(raw, env);
 	const critic_provider = raw.critic_provider ?? DEFAULT_CRITIC_PROVIDER;
 	if (!CRITIC_PROVIDERS.includes(critic_provider)) throw config_error(`--critic-provider must be one of ${CRITIC_PROVIDERS.join(", ")}; got: ${String(raw.critic_provider)}`);
 	const builder_url = resolve_seat_url("builder", raw.builder_url, builder_provider);
 	const critic_url = resolve_seat_url("critic", raw.critic_url, critic_provider);
+	if (builder_provider === "openrouter" || critic_provider === "openrouter") openrouter_api_key(env);
 	if (contained) {
 		const claude_roles = [builder_provider === "claude_cli" ? "builder" : null, critic_provider === "claude_cli" ? "critic" : null].filter((role) => role !== null);
 		const auth_mode = env["VOLLEY_AUTH_MODE"] ?? "auto";
@@ -675,6 +736,7 @@ function resolve_config(raw, options = {}) {
 	const gate_paths = raw.gate_paths ?? DEFAULT_GATE_PATTERNS;
 	if (!Array.isArray(gate_paths) || gate_paths.some((glob) => typeof glob !== "string")) throw config_error("gate_paths must be an array of glob strings");
 	const sandbox_image = resolve_sandbox_image(raw, env);
+	const state_dir = resolve_state_dir(raw.state_dir, cwd);
 	const run_id = resolve_run_id(options.run_id);
 	const check = raw.check ?? "auto";
 	return {
@@ -704,6 +766,7 @@ function resolve_config(raw, options = {}) {
 		gate_paths: [...gate_paths],
 		fail_on_gate_edit: raw.fail_on_gate_edit ?? false,
 		sandbox_image,
+		state_dir,
 		workspace,
 		verbose: raw.verbose ?? false,
 		quiet: raw.quiet ?? false,
@@ -782,8 +845,9 @@ async function warn_small_local_context(provider, model, base_url, warn, abort)
 */
 const READ_FILE_MAX_BYTES = 2e5;
 const LIST_MAX_ENTRIES = 2e3;
-/** Directories never worth handing a critic; they bury signal and blow the
-* traversal budget. */
+/** Directories never worth handing a seat; they bury signal and blow the
+* traversal budget. The acp seats' `list_files` and `search` skip the same
+* names (`./acp_tools.ts`), so a seat sees one tree under acp and on the CLI. */
 const IGNORED_DIRS = /* @__PURE__ */ new Set([
 	"node_modules",
 	".git",
@@ -1295,7 +1359,19 @@ function builder_tools(workspace, options = {}) {
 			max_bytes: options.fetch_max_bytes ?? FETCH_MAX_BYTES
 		})
 	};
-	const finish = {
+	return [
+		...read_only_tools(workspace),
+		write_file,
+		edit_file,
+		bash,
+		fetch,
+		finish_tool()
+	];
+}
+/** The terminal `finish` tool, on its own for a builder set that brings its
+* own file and command tools (`../acp_tools.ts`). */
+function finish_tool() {
+	return {
 		name: "finish",
 		description: "Declare the task complete. Calling this tool ends your turn — do not call it until the work is done and verified.",
 		input_schema: finish_input,
@@ -1304,14 +1380,6 @@ function builder_tools(workspace, options = {}) {
 			return `finished: ${finish_input.parse(raw).summary}`;
 		}
 	};
-	return [
-		...read_only_tools(workspace),
-		write_file,
-		edit_file,
-		bash,
-		fetch,
-		finish
-	];
 }
 //#endregion
 //#region src/cost.ts
@@ -1339,9 +1407,13 @@ function add_usage(a, b) {
 	}
 	return sum;
 }
+/** The providers whose calls carry the charge they report, which fascicle
+* records as the call's cost in place of a pricing table's estimate: the
+* Claude CLI's own total, and OpenRouter's per-response charge. */
+const REPORTING_PROVIDERS = /* @__PURE__ */ new Set(["claude_cli", "openrouter"]);
 function cost_source_of(result) {
 	if (result.cost === void 0) return "unknown";
-	return result.model_resolved.provider === "claude_cli" ? "provider_reported" : "engine_derived";
+	return REPORTING_PROVIDERS.has(result.model_resolved.provider) ? "provider_reported" : "engine_derived";
 }
 /** One phase's record from its generate result. The duration is fascicle's
 * call-level wall clock (`GenerateResult.timing`: every turn and the tools
@@ -1430,27 +1502,36 @@ async function prewarm_ollama_model(base_url, model, abort) {
 //#endregion
 //#region src/workspace.ts
 /**
-* Workspace lifecycle: `.volley/` initialization, stale-run
+* Workspace lifecycle: run-state initialization, stale-run
 * backup rotation, path helpers, and optional git checkpoints.
 */
-function volley_path(workspace, ...parts) {
-	return join(workspace, ".volley", ...parts);
+/** Where a run keeps its config, summary, trajectory, feedback, verdict, and
+* iterations: `<state_dir>/<run_id>/` under a state root, else
+* `<workspace>/.volley/`. */
+function run_state_dir(run) {
+	return run.state_dir === null ? join(run.workspace, ".volley") : join(run.state_dir, run.run_id);
+}
+function state_path(run, ...parts) {
+	return join(run_state_dir(run), ...parts);
 }
-function iteration_dir(workspace, iteration) {
-	return volley_path(workspace, "iterations", String(iteration).padStart(3, "0"));
+function iteration_dir(run, iteration) {
+	return state_path(run, "iterations", String(iteration).padStart(3, "0"));
 }
 /** Filesystem-safe timestamp for `.bak.<stamp>` rotation names. Shared by the
-* `.volley/` rotation here and the worktree rotation so both preserve
+* run-state rotation here and the worktree rotation so both preserve
 * prior state under the same never-destroy naming. */
 function backup_stamp(date = /* @__PURE__ */ new Date()) {
 	return date.toISOString().replace(/[:.]/g, "-");
 }
-/** Fresh-run initialization: rotate a stale `.volley/` aside, then create the
-* directory tree. Resume runs skip rotation (`preserve: true`). */
-function initialize_workspace(workspace, options = {}) {
-	const dir = volley_path(workspace);
-	if (existsSync(dir) && options.preserve !== true) renameSync(dir, join(workspace, `.volley.bak.${backup_stamp()}`));
-	mkdirSync(volley_path(workspace, "iterations"), { recursive: true });
+/** Fresh-run initialization: rotate a stale state directory aside (a prior
+* `.volley/` becomes `.volley.bak.<stamp>`), then create the directory tree.
+* Under a state root each run has a directory of its own, so only a reused
+* `--run-id` ever finds one to rotate. Resume runs skip rotation
+* (`preserve: true`). */
+function initialize_run_state(run, options = {}) {
+	const dir = run_state_dir(run);
+	if (existsSync(dir) && options.preserve !== true) renameSync(dir, `${dir}.bak.${backup_stamp()}`);
+	mkdirSync(join(dir, "iterations"), { recursive: true });
 }
 function write_resolved_config(config) {
 	const record = {
@@ -1479,9 +1560,10 @@ function write_resolved_config(config) {
 		gate_paths: config.gate_paths,
 		fail_on_gate_edit: config.fail_on_gate_edit,
 		sandbox_image: config.sandbox_image,
+		state_dir: config.state_dir,
 		workspace: config.workspace
 	};
-	writeFileSync(volley_path(config.workspace, "config.json"), `${JSON.stringify(record, null, 2)}\n`);
+	writeFileSync(state_path(config, "config.json"), `${JSON.stringify(record, null, 2)}\n`);
 }
 /**
 * `--git`: commit everything under `root` after a phase (`git -C <root>`, run
@@ -1879,7 +1961,7 @@ async function with_worktree(options, body) {
 /**
 * Builder invocation: one call to the builder leaf per iteration is one
 * complete agentic session in the workspace — Claude Code under `claude_cli`,
-* or a local model driving volley's tools.
+* or a model driving volley's tools on any other provider, local or hosted.
 */
 const BUILDER_ALLOWED_TOOLS = [
 	"Read",
@@ -1901,7 +1983,7 @@ function compose_builder_system() {
 }
 /** Walk up from this module to the package root (works from src/ under tsx
 * and from dist/ in the published package, which ships src/builder/presets). */
-function presets_dir$1() {
+function builder_presets_dir() {
 	let dir = dirname(fileURLToPath(import.meta.url));
 	for (let depth = 0; depth < 6; depth += 1) {
 		const candidate = join(dir, "src", "builder", "presets");
@@ -1910,36 +1992,48 @@ function presets_dir$1() {
 	}
 	throw config_error("builder presets directory not found");
 }
-function compose_builder_system_local() {
+/** The harness append each tool set's builder reads: one naming volley's own
+* tools, or one naming fascicle's workspace tools under `volley acp` and
+* saying what a call the user refused means. */
+const HARNESS_APPENDS = {
+	volley: "harness_append_local.md",
+	acp: "harness_append_acp.md"
+};
+function compose_builder_system_local(tool_set = "volley") {
 	return `${[
 		"You are the builder inside the volley harness: an autonomous agent",
 		"iterating on a workspace until it satisfies a task and its acceptance",
 		"criteria."
-	].join("\n")}\n\n${readFileSync(join(presets_dir$1(), "harness_append_local.md"), "utf8").trimEnd()}`;
+	].join("\n")}\n\n${readFileSync(join(builder_presets_dir(), HARNESS_APPENDS[tool_set]), "utf8").trimEnd()}`;
 }
 /** The builder system prompt for the active provider: the `claude_cli`
 * prompt (implicit built-in tools, "the current working directory") for the
-* CLI builder, or the local prompt (volley's tool set, workspace-is-cwd, and
-* the harness-enforced `finish` stop) for a local model. Mirrors the critic's
-* `resolve_critic_prompt`. */
-function resolve_builder_system(config) {
-	return config.builder_provider === "claude_cli" ? compose_builder_system() : compose_builder_system_local();
+* CLI builder, which never takes an injected set, or the local prompt naming
+* the seat's tool set for every provider that runs volley's tool loop,
+* `openrouter` included. Mirrors the critic's `resolve_critic_prompt`. */
+function resolve_builder_system(config, tool_set) {
+	return config.builder_provider === "claude_cli" ? compose_builder_system() : compose_builder_system_local(tool_set);
 }
 const BUILDER_TOOL_CALL_REPAIR_ATTEMPTS = 3;
 /** Per-provider tool wiring for the builder, mirroring `critic_tool_options`.
 * The `claude_cli` builder is confined at the CLI permission layer (allowlist +
 * permission mode) and brings its own built-in tools — this arm is unchanged
-* from v2. A local builder brings none, so volley supplies its whole
-* workspace tool surface plus the five per-call loop knobs and **no**
-* schema (it produces a workspace, not a verdict); per-call values win over
-* engine defaults. */
-function builder_tool_options(config, bash_executor) {
+* from v2, and takes no injected tools or approval handler. Every other
+* builder, local or `openrouter`, brings none, so volley supplies its whole
+* workspace tool surface (or the set the caller injected in its place, with
+* the handler that answers its approvals) plus the five per-call loop knobs
+* and **no** schema (it produces a workspace, not a verdict); per-call values
+* win over engine defaults. */
+function builder_tool_options(deps) {
+	const { config } = deps;
+	const bash_executor = deps.bash_executor ?? null;
 	if (config.builder_provider === "claude_cli") return { provider_options: { claude_cli: {
 		allowed_tools: [...BUILDER_ALLOWED_TOOLS],
 		extra_args: ["--permission-mode", config.builder_permission_mode]
 	} } };
 	return {
-		tools: builder_tools(build_root(config.workspace, config.worktree), bash_executor !== null ? { bash_executor } : {}),
+		tools: deps.tools === void 0 ? builder_tools(build_root(config.workspace, config.worktree), bash_executor !== null ? { bash_executor } : {}) : [...deps.tools],
+		...deps.on_tool_approval !== void 0 ? { on_tool_approval: deps.on_tool_approval } : {},
 		max_steps: config.builder_max_steps,
 		tool_error_policy: "feed_back",
 		tool_call_repair_attempts: BUILDER_TOOL_CALL_REPAIR_ATTEMPTS,
@@ -1976,9 +2070,9 @@ function make_builder_step(deps) {
 		description: "model call: one agentic session in the build root",
 		provider: config.builder_provider,
 		model: config.builder_model,
-		system: resolve_builder_system(config),
+		system: resolve_builder_system(config, deps.tool_set),
 		on_chunk: deps.on_chunk,
-		...builder_tool_options(config, deps.bash_executor ?? null)
+		...builder_tool_options(deps)
 	});
 }
 async function run_builder(deps, state, ctx) {
@@ -2022,11 +2116,30 @@ function presets_dir() {
 	}
 	throw config_error("critic presets directory not found");
 }
-function resolve_critic_prompt(config) {
+/** The harness append that names the critic's reads. The CLI critic reads
+* via built-in Read/Grep/Glob and never takes an injected set; every other
+* critic, local or `openrouter`, reads via volley's read_file/search_files/
+* list_files, or under `volley acp` via fascicle's read_file/list_files/
+* search. */
+function harness_append_file(config, tool_set) {
+	if (config.critic_provider === "claude_cli") return "harness_append.md";
+	return tool_set === "acp" ? "harness_append_acp.md" : "harness_append_local.md";
+}
+function resolve_critic_prompt(config, tool_set = "volley") {
 	const base = config.critic_prompt_path !== null ? readFileSync(config.critic_prompt_path, "utf8") : readFileSync(join(presets_dir(), `${config.critic_preset}.md`), "utf8");
-	const append_file = config.critic_provider === "claude_cli" ? "harness_append.md" : "harness_append_local.md";
-	const append = readFileSync(join(presets_dir(), append_file), "utf8");
-	return `${base.trimEnd()}\n\n${append.trimEnd()}`;
+	const append = readFileSync(join(presets_dir(), harness_append_file(config, tool_set)), "utf8");
+	return `${base.trimEnd()}\n\n${place_iterations_dir(append, config).trimEnd()}`;
+}
+const ITERATIONS_DIR = "{{iterations_dir}}";
+/** Fill the harness append's line about prior iteration state with where the
+* run's `iterations/` sits, relative to the build root the critic reads from,
+* or drop the line when the run's state is outside that root: a confined
+* critic can't reach it, and naming it would only spend the critic's steps on
+* a path it can't open. */
+function place_iterations_dir(append, config) {
+	const path = relative(build_root(config.workspace, config.worktree), state_path(config, "iterations"));
+	const outside = path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path);
+	return append.split("\n").filter((line) => !(outside && line.includes(ITERATIONS_DIR))).join("\n").replaceAll(ITERATIONS_DIR, `${path}/`);
 }
 /** One-letter status column, so a hundred-path list stays readable. */
 const STATUS_MARKS = {
@@ -2106,8 +2219,9 @@ function compose_critic_prompt(input) {
 //#endregion
 //#region src/critic/run.ts
 /**
-* Critic invocation: a read-only session (`claude_cli`, or a local model with
-* volley's read tools) returning a schema-validated structured verdict. The
+* Critic invocation: a read-only session (`claude_cli`, or a local or
+* `openrouter` model with volley's read tools) returning a schema-validated
+* structured verdict. The
 * harness — not the critic — writes `.volley/feedback.md` and `.volley/verdict`.
 */
 const CRITIC_ALLOWED_TOOLS = [
@@ -2122,12 +2236,12 @@ const verdict_schema = z.object({
 	unmet_criteria: z.array(z.string()).describe("The specific acceptance criteria judged unmet, verbatim. Empty when approved.")
 });
 /** Read-only tool wiring per provider. The claude_cli critic is confined at
-* the CLI permission layer (allowlist + explicit disallow); a local-model
-* critic gets volley's own workspace-scoped read-only tools and no write
-* path at all.
+* the CLI permission layer (allowlist + explicit disallow); every other critic,
+* local or `openrouter`, gets volley's own workspace-scoped read-only tools (or
+* the set the caller injected in their place) and no write path at all.
 *
-* The two providers also enforce `verdict_schema` by two different paths, both
-* verified live. The claude_cli critic compiles the schema for
+* The providers also enforce `verdict_schema` by different paths, the first
+* two verified live. The claude_cli critic compiles the schema for
 * `claude --json-schema`; that only works because fascicle 0.14.0's
 * `compile_schema` strips the top-level `$schema`/`$id` that zod v4 stamps (the
 * CLI rejects them) — `live_smoke` asserts a structured verdict comes back, so a
@@ -2137,16 +2251,22 @@ const verdict_schema = z.object({
 * structurally guaranteed at decode time, with no prompt-parse-repair;
 * `live_local_builder` exercises that path. Unchanged in v3: on ai_sdk
 * constrained decode needs no wiring, and under the deferred native flip it
-* would move to `provider_options.ollama.format` (parked). */
-function critic_tool_options(config) {
+* would move to `provider_options.ollama.format` (parked). An `openrouter`
+* critic rides fascicle's native OpenAI-compatible core, which has no
+* constrained decode: the schema travels in the prompt, and the reply is parsed
+* and repaired. */
+function critic_tool_options(config, tools) {
 	if (config.critic_provider === "claude_cli") return { provider_options: { claude_cli: {
 		allowed_tools: [...CRITIC_ALLOWED_TOOLS],
 		extra_args: ["--disallowedTools", CRITIC_DISALLOWED_TOOLS]
 	} } };
-	return { tools: read_only_tools(build_root(config.workspace, config.worktree)) };
+	return {
+		tools: tools === void 0 ? read_only_tools(build_root(config.workspace, config.worktree)) : [...tools],
+		max_steps: 10
+	};
 }
-/** Is this critic failure the transient local-provider stream death the ladder
-* retries? Local providers only (the `claude_cli` path is proven and its
+/** Is this critic failure the transient provider stream death the ladder
+* retries? Every provider but `claude_cli` (that path is proven and its
 * retries cost real money), and fascicle's typed `provider_error` only (no
 * message string-matching). A user abort never gets here: `retry` and
 * `fallback` pass control-flow signals through untouched, and `retry` checks the
@@ -2155,6 +2275,23 @@ function is_retryable_critic_error(config, err) {
 	if (config.critic_provider === "claude_cli") return false;
 	return error_kind(err) === "provider_error";
 }
+/** Did a schema call end without a verdict because the tool loop ran out —
+* its step budget spent, or its last turn a tool call — rather than because
+* the response was cut off or blocked? fascicle throws
+* `incomplete_generation_error` for every such finish; only these two are
+* fixed by taking the tools away. Matched on `kind` and `finish_reason`. */
+function is_step_exhaustion(err) {
+	if (error_kind(err) !== "incomplete_generation_error") return false;
+	const finish = err.finish_reason;
+	return finish === "max_steps" || finish === "tool_calls";
+}
+/** Does this failure send a local critic to the tool-less rung? A stream death
+* the retry rung gave up on, or step exhaustion, which no retry would fix. A
+* `length` or `content_filter` finish is neither, and stays fatal. */
+function is_degradable_critic_error(config, err) {
+	if (config.critic_provider === "claude_cli") return false;
+	return error_kind(err) === "provider_error" || is_step_exhaustion(err);
+}
 /** fascicle's `provider_error.cause_kind` is `... | undefined`; fold the
 * missing case into `'unknown'` so a recorded retry always names a cause. */
 function retry_cause_kind_of(err) {
@@ -2173,7 +2310,8 @@ function finalize_critic(state, result, model, mark, duration_ms) {
 			...next.critic,
 			retries: mark.retries,
 			...mark.retry_cause_kind !== void 0 ? { retry_cause_kind: mark.retry_cause_kind } : {},
-			...mark.critic_degraded === true ? { critic_degraded: true } : {}
+			...mark.critic_degraded === true ? { critic_degraded: true } : {},
+			...mark.degrade_cause !== void 0 ? { degrade_cause: mark.degrade_cause } : {}
 		},
 		verdict: result.content.verdict,
 		feedback: result.content.feedback,
@@ -2203,7 +2341,7 @@ function critic_call_config(deps) {
 		engine: deps.engine,
 		provider: config.critic_provider,
 		model: config.critic_model,
-		system: resolve_critic_prompt(config),
+		system: resolve_critic_prompt(config, deps.tool_set),
 		schema: verdict_schema,
 		on_chunk: deps.on_chunk
 	};
@@ -2215,7 +2353,7 @@ function make_critic_tools_step(deps) {
 		...critic_call_config(deps),
 		id: "critic_tools",
 		description: "model call with read-only workspace tools",
-		...critic_tool_options(deps.config)
+		...critic_tool_options(deps.config, deps.tools)
 	});
 }
 /** Rung 2's leaf: the same critic with no tools at all, so nothing enters
@@ -2228,9 +2366,28 @@ function make_critic_toolless_step(deps) {
 		description: "model call judging from the check output and a file list"
 	});
 }
-/** The ladder's retry predicate for this run's critic provider. */
+const ladder_traces = /* @__PURE__ */ new WeakMap();
+/** The ladder's retry predicate for this run's critic provider: stream deaths
+* only. It also traces every failure it sees, so a degraded verdict can say how
+* many retries preceded it and why. A first attempt starts a fresh critique, so
+* it forgets the last one's retries. */
 function critic_retryable(config) {
-	return (err) => is_retryable_critic_error(config, err);
+	let retried_cause;
+	return (err, attempt) => {
+		if (attempt === 1) retried_cause = void 0;
+		if (typeof err === "object" && err !== null) ladder_traces.set(err, {
+			attempt,
+			retried_cause
+		});
+		const retryable = is_retryable_critic_error(config, err);
+		if (retryable) retried_cause = retry_cause_kind_of(err);
+		return retryable;
+	};
+}
+/** The ladder's fallback predicate: a stream death the retry rung gave up on,
+* or step exhaustion, which it never retries. */
+function critic_degradable(config) {
+	return (err) => is_degradable_critic_error(config, err);
 }
 /** Rung 1's projection: a verdict the tool-bearing critic produced, marked with
 * how many stream deaths it took and the last one's cause. */
@@ -2244,27 +2401,42 @@ function with_retries(outcome) {
 		}
 	};
 }
-/** Rung 2's answer: every retry was spent, and the verdict is marked degraded
-* so it never passes silently as a full critique. */
+/** Rung 2's answer, marked degraded so it never passes silently as a full
+* critique. Why it degraded, and the retries before it, are the ladder's to
+* stamp (`with_fallback_cause`), since the tool-less call can't see them. */
 function as_degraded(result) {
 	return {
 		result,
 		mark: {
-			retries: 1,
+			retries: 0,
 			retry_cause_kind: void 0,
 			critic_degraded: true
 		}
 	};
 }
 /** The ladder's projection: the tool-less backup cannot see why it ran, so the
-* cause comes from the last stream death the retry rung gave up on. */
+* mark comes from the error that sent it there.
+*
+* - A stream death the retry rung gave up on: every retry was spent, and the
+*   cause is that error's own.
+* - Step exhaustion, never retried: the retries are the stream deaths before
+*   it, usually none, and the cause is the last of those.
+*
+* An error the retry rung never traced reads as one that spent every retry. */
 function with_fallback_cause(outcome) {
 	if (outcome.source === "primary") return outcome.value;
+	const err = outcome.primary_error;
+	const trace = typeof err === "object" && err !== null ? ladder_traces.get(err) : void 0;
+	const retries = trace === void 0 ? 1 : trace.attempt - 1;
+	const exhausted = is_step_exhaustion(err);
+	const retry_cause_kind = exhausted ? trace?.retried_cause : retry_cause_kind_of(err);
 	return {
 		...outcome.value,
 		mark: {
 			...outcome.value.mark,
-			retry_cause_kind: retry_cause_kind_of(outcome.primary_error)
+			retries,
+			retry_cause_kind,
+			degrade_cause: exhausted ? "step_exhaustion" : "stream_error"
 		}
 	};
 }
@@ -2374,14 +2546,50 @@ function status_of(value, converged) {
 */
 const CHECK_ARTIFACT_MAX_CHARS = 8e3;
 const CHECKRIDE_SCHEMA_VERSION = 1;
+/** How long a check's output may stay open after its shell exits, while
+* something that escaped its process group still holds it, before the reads
+* stop so the check can finish. */
+const OUTPUT_GRACE_MS = 2e3;
+/** Kill a check's whole process group with SIGKILL. A test runner's workers,
+* and anything the check started in the background, sit in the shell's group,
+* so killing the shell alone would leave them running. Windows has no process
+* groups to signal, so there only the shell goes. */
+function kill_group(proc) {
+	if (proc.pid === void 0) return;
+	try {
+		if (process.platform === "win32") proc.kill("SIGKILL");
+		else process.kill(-proc.pid, "SIGKILL");
+	} catch {}
+}
+/** Run a check to its end in a process group of its own, capturing its
+* output. The abort kills the whole group and rejects with `aborted_error`,
+* and the shell's exit kills whatever it left behind, so a stopped run leaves
+* no test workers or servers running. */
 function spawn_capture(cmd, args, options) {
+	const { abort } = options;
+	if (abort?.aborted === true) return Promise.reject(new aborted_error("check aborted"));
 	return new Promise((resolve_promise, reject) => {
 		const proc = spawn(cmd, args, {
 			cwd: options.cwd,
-			...options.abort !== void 0 ? { signal: options.abort } : {}
+			...options.env !== void 0 ? { env: options.env } : {},
+			detached: process.platform !== "win32",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
 		});
 		let stdout = "";
 		let stderr = "";
+		let grace;
+		const on_abort = () => {
+			kill_group(proc);
+			reject(new aborted_error("check aborted"));
+		};
+		const finish = () => {
+			clearTimeout(grace);
+			abort?.removeEventListener("abort", on_abort);
+		};
 		proc.stdout.on("data", (chunk) => {
 			stdout += chunk.toString();
 		});
@@ -2389,19 +2597,25 @@ function spawn_capture(cmd, args, options) {
 			stderr += chunk.toString();
 		});
 		proc.on("error", (err) => {
-			if (err.name === "AbortError") {
-				reject(new aborted_error("check aborted"));
-				return;
-			}
+			finish();
 			reject(check_error(`check command failed to start: ${err.message}`));
 		});
+		proc.on("exit", () => {
+			kill_group(proc);
+			grace = setTimeout(() => {
+				proc.stdout.destroy();
+				proc.stderr.destroy();
+			}, OUTPUT_GRACE_MS);
+		});
 		proc.on("close", (code) => {
+			finish();
 			resolve_promise({
 				exit_code: code,
 				stdout,
 				stderr
 			});
 		});
+		abort?.addEventListener("abort", on_abort, { once: true });
 	});
 }
 /** Best-effort parse of the summary contract. `pnpm exec` talks over the
@@ -2465,13 +2679,14 @@ function read_failing_artifacts(workspace, failing) {
 	});
 }
 async function run_checkride(opts) {
+	const { workspace, ...spawn_options } = opts;
 	const proc = await spawn_capture("pnpm", [
 		"exec",
 		"checkride",
 		"--json"
 	], {
-		cwd: opts.workspace,
-		...opts.abort !== void 0 ? { abort: opts.abort } : {}
+		...spawn_options,
+		cwd: workspace
 	});
 	if (proc.exit_code === 2) throw check_error(`checkride harness error: ${proc.stderr.trim()}`);
 	const { summary } = parse_summary_with_fallback(proc.stdout, opts.workspace);
@@ -2495,12 +2710,13 @@ async function run_checkride(opts) {
 * (exit 4), not an iterable failure.
 */
 async function run_command_check(opts) {
+	const { command, workspace, ...spawn_options } = opts;
 	const started = Date.now();
-	const proc = await spawn_capture("sh", ["-c", opts.command], {
-		cwd: opts.workspace,
-		...opts.abort !== void 0 ? { abort: opts.abort } : {}
+	const proc = await spawn_capture("sh", ["-c", command], {
+		...spawn_options,
+		cwd: workspace
 	});
-	if (proc.exit_code === 127 || proc.exit_code === 126) throw check_error(`check command failed to start (exit ${String(proc.exit_code)}): ${opts.command}`);
+	if (proc.exit_code === 127 || proc.exit_code === 126) throw check_error(`check command failed to start (exit ${String(proc.exit_code)}): ${command}`);
 	const log = `${proc.stdout}${proc.stderr}`;
 	return {
 		ran: true,
@@ -2524,6 +2740,23 @@ function skipped_check(reason) {
 		detail: []
 	};
 }
+/** What a rejected check says in place of its output. */
+const CHECK_REJECTED = "the check was rejected when it asked to run, so it never ran";
+/** A check the user rejected when it asked to run: recorded as a failed
+* check, with the refusal as its output, so a round can't converge on work
+* nothing checked, and the critic hears why there's no result. */
+function rejected_check(runner) {
+	return {
+		ran: true,
+		runner,
+		ok: false,
+		exit_code: null,
+		duration_ms: 0,
+		failing_slots: [],
+		detail: [],
+		log: CHECK_REJECTED
+	};
+}
 //#endregion
 //#region src/iteration.ts
 /**
@@ -2534,9 +2767,9 @@ function skipped_check(reason) {
 function write_json(path, value) {
 	writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
 }
-function persist_verdict_files(workspace, feedback, verdict) {
-	writeFileSync(volley_path(workspace, "feedback.md"), feedback.endsWith("\n") ? feedback : `${feedback}\n`);
-	writeFileSync(volley_path(workspace, "verdict"), `${verdict}\n`);
+function persist_verdict_files(config, feedback, verdict) {
+	writeFileSync(state_path(config, "feedback.md"), feedback.endsWith("\n") ? feedback : `${feedback}\n`);
+	writeFileSync(state_path(config, "verdict"), `${verdict}\n`);
 }
 function phase_summary(record) {
 	if (record === null) return null;
@@ -2555,17 +2788,18 @@ function phase_summary(record) {
 		...record.retries !== void 0 ? { retries: record.retries } : {},
 		...record.retry_cause_kind !== void 0 ? { retry_cause_kind: record.retry_cause_kind } : {},
 		...record.critic_degraded === true ? { critic_degraded: true } : {},
+		...record.degrade_cause !== void 0 ? { degrade_cause: record.degrade_cause } : {},
 		...record.throughput !== void 0 ? { throughput: record.throughput } : {}
 	};
 }
 /** Archive one completed iteration: verdict files, check artifacts, and the
 * per-iteration summary. */
 function archive_iteration(config, state) {
-	const dir = iteration_dir(config.workspace, state.iteration);
+	const dir = iteration_dir(config, state.iteration);
 	mkdirSync(join(dir, "check"), { recursive: true });
 	if (state.verdict !== null && state.feedback !== null) {
-		persist_verdict_files(config.workspace, state.feedback, state.verdict);
-		writeFileSync(join(dir, "feedback.md"), readFileSync(volley_path(config.workspace, "feedback.md")));
+		persist_verdict_files(config, state.feedback, state.verdict);
+		writeFileSync(join(dir, "feedback.md"), readFileSync(state_path(config, "feedback.md")));
 		writeFileSync(join(dir, "verdict"), `${state.verdict}\n`);
 	}
 	const check = state.check;
@@ -2620,7 +2854,7 @@ function run_result_from_state(config, state, status, completed_at) {
 //#endregion
 //#region src/summary.ts
 /**
-* Enriched run summary (`.volley/summary.json`): the `RunResult` projection plus
+* Enriched run summary (the run's `summary.json`): the `RunResult` projection plus
 * a `comparison` block that makes the two blessed examples' runs diff-able.
 * The block gathers the seven comparison metrics — transport,
 * iterations-to-converge, wall-clock, cost, verdict, the deterministic check
@@ -2635,22 +2869,27 @@ function run_result_from_state(config, state, status, completed_at) {
 * surviving branch on `salvaged_branch`, which teardown only names after the
 * final status is known.
 * Each write recomputes the comparison from what is currently archived under
-* `.volley/iterations/`, so the trajectory grows as the run does.
+* the run's `iterations/`, so the trajectory grows as the run does.
 */
 function transport_of(provider) {
-	return provider === "claude_cli" ? "claude_cli" : "ai_sdk";
+	switch (provider) {
+		case "claude_cli": return "claude_cli";
+		case "openrouter": return "native";
+		case "ollama":
+		case "lmstudio": return "ai_sdk";
+	}
 }
 /** Read the archived per-iteration summaries in order. A missing archive root
 * (a run that failed before the first `record`) or an unreadable entry yields an
 * empty/short list — the run summary still writes, just without that trajectory
 * detail. */
-function read_iteration_archives(workspace) {
-	const root = volley_path(workspace, "iterations");
+function read_iteration_archives(config) {
+	const root = state_path(config, "iterations");
 	if (!existsSync(root)) return [];
 	const dirs = readdirSync(root).filter((dir) => /^\d{3}$/.test(dir)).toSorted();
 	const archives = [];
 	for (const dir of dirs) {
-		const path = volley_path(workspace, "iterations", dir, "summary.json");
+		const path = state_path(config, "iterations", dir, "summary.json");
 		if (!existsSync(path)) continue;
 		try {
 			archives.push(JSON.parse(readFileSync(path, "utf8")));
@@ -2672,6 +2911,13 @@ function check_trajectory(archives) {
 function any_critic_degraded(archives) {
 	return archives.some((archive) => archive.critic?.critic_degraded === true);
 }
+/** Each distinct reason an archived critic verdict degraded. An archive from
+* before the cause was recorded reads as a stream error, the only way a verdict
+* could degrade then. */
+function critic_degrade_causes(archives) {
+	const causes = archives.filter((archive) => archive.critic?.critic_degraded === true).map((archive) => archive.critic?.degrade_cause ?? "stream_error");
+	return [...new Set(causes)];
+}
 /** Every gate path the run's builder touched, across all iterations: an edit in
 * iteration 1 that a later iteration reverted still happened, so the run-level
 * answer is the union rather than the last iteration's list. */
@@ -2697,7 +2943,7 @@ function salvage_stats(archives) {
 * archive for the check trajectory and salvage aggregate. Pure over its inputs
 * plus the on-disk archive; `write_run_summary` persists the result. */
 function build_run_summary(config, result) {
-	const archives = read_iteration_archives(config.workspace);
+	const archives = read_iteration_archives(config);
 	const wall_clock_ms = result.completed_at === null ? null : Date.parse(result.completed_at) - Date.parse(result.started_at);
 	return {
 		...result,
@@ -2714,17 +2960,54 @@ function build_run_summary(config, result) {
 			gate_edits: all_gate_edits(archives),
 			unmet_criteria: archives.at(-1)?.unmet_criteria ?? [],
 			local_salvage: salvage_stats(archives),
-			critic_degraded: any_critic_degraded(archives)
+			critic_degraded: any_critic_degraded(archives),
+			critic_degrade_causes: critic_degrade_causes(archives)
 		}
 	};
 }
-/** Write the enriched summary to `.volley/summary.json` (the projection the
+/** Write the enriched summary to the run's `summary.json` (the projection the
 * examples' comparison is read from). */
 function write_run_summary(config, result) {
-	writeFileSync(volley_path(config.workspace, "summary.json"), `${JSON.stringify(build_run_summary(config, result), null, 2)}\n`);
+	writeFileSync(state_path(config, "summary.json"), `${JSON.stringify(build_run_summary(config, result), null, 2)}\n`);
 }
 //#endregion
 //#region src/phases.ts
+/**
+* The step bodies behind the nodes of `./flow.ts`, one function per node. Each
+* takes the loop's carry-state and returns the next one. The phase modules they
+* call (`./builder.ts`, `./check/`, `./critic/`) do the work; these bodies add
+* what surrounds it: the renderer lines an operator watches, change detection,
+* git checkpoints, the per-iteration archive, and the progress events a
+* trajectory reader follows the run by.
+*/
+/** The step id the check's card is recorded under: the check step's own, in
+* `./flow.ts`, so each round's check counts as a fresh run of it and opens a
+* card of its own. */
+const CHECK_STEP_ID = "check";
+/** The raw call id and tool name of the check's card. The name sits outside
+* the workspace tools, so nothing dresses the card as one of theirs. */
+const CHECK_CALL = {
+	id: "check",
+	name: "check"
+};
+function emit(ctx, event) {
+	ctx.emit(event);
+}
+/** Record one chunk of the check's card, the way `model_call` records a tool
+* call's, under a streamed run only, since nothing reads a card otherwise. */
+function record_check_chunk(ctx, chunk) {
+	if (ctx.streaming) ctx.trajectory.record({
+		kind: "model_chunk",
+		step_id: CHECK_STEP_ID,
+		chunk
+	});
+}
+/** The command line the check runs, or null when no check is configured. */
+function check_command(config) {
+	if (config.check_resolved === "checkride") return "pnpm exec checkride --json";
+	if (config.check_resolved === "command") return config.check;
+	return null;
+}
 /** How many gate edits a warning names before it summarises the rest. */
 const LISTED_GATE_EDITS = 5;
 /**
@@ -2742,18 +3025,42 @@ function report_changes(config, renderer, changes) {
 	const listed = changes.gate_edits.slice(0, LISTED_GATE_EDITS).join(", ");
 	renderer.warn(`gate edit: the builder changed ${String(changes.gate_edits.length)} file(s) that decide whether its work passes — ${listed}${hidden > 0 ? ` (+${String(hidden)} more)` : ""}. A green check proves less when the builder can edit the gate; the critic is told about this and the run summary records it.` + (config.fail_on_gate_edit ? " This run will end without success (--fail-on-gate-edit, exit 8)." : ""));
 }
-async function execute_check(config, abort) {
+/** Run the configured check, checkride or a command, with the environment
+* the caller set for it, else volley's own. */
+async function execute_check(deps, abort) {
+	const { config } = deps;
 	const root = build_root(config.workspace, config.worktree);
-	if (config.check_resolved === "checkride") return run_checkride({
-		workspace: root,
-		abort
-	});
-	if (config.check_resolved === "command") return run_command_check({
+	const options = {
+		abort,
+		...deps.check?.env !== void 0 ? { env: deps.check.env } : {}
+	};
+	return config.check_resolved === "checkride" ? run_checkride({
+		...options,
+		workspace: root
+	}) : run_command_check({
+		...options,
 		command: config.check,
-		workspace: root,
+		workspace: root
+	});
+}
+/** Whether the check may run `command`: yes, unless the caller set an
+* approval and it answers no. It asks on the check's card under the command
+* line as its tool name, which titles the prompt the way the card is titled,
+* and which names none of fascicle's gated tools, so the prompt offers Allow
+* and Reject alone, never an "always" that would cover the builder's commands
+* too. A stop while it asks ends the check as a stop, not a rejection. */
+async function check_allowed(deps, command, abort) {
+	const approve = deps.check?.on_approval;
+	if (approve === void 0) return true;
+	const allowed = await approve({
+		tool_name: command,
+		input: { command },
+		tool_call_id: CHECK_CALL.id,
+		step_index: 0,
 		abort
 	});
-	return skipped_check("none");
+	if (abort.aborted) throw new aborted_error("check aborted");
+	return allowed;
 }
 /** Open the next iteration: advance the counter and clear every per-iteration
 * field, so nothing from the last round leaks into this one. */
@@ -2775,6 +3082,10 @@ function next_iteration(s) {
 async function build_phase(deps, builder, s, ctx) {
 	const { config, renderer } = deps;
 	const next = next_iteration(s);
+	emit(ctx, {
+		volley: "round_start",
+		round: next.iteration
+	});
 	renderer.phase_start(next.iteration, "builder");
 	const built = await run_builder({
 		builder,
@@ -2806,20 +3117,79 @@ function skip_verify_phase(deps, s) {
 		check: skipped_check("cost_cap")
 	};
 }
-/** `check`: the deterministic gate over the tree the builder wrote. */
+/** Open the check's card on a streamed run: the call's start, then the
+* command as its input, the two chunks `model_call` records for a tool call
+* before it runs. */
+function open_check_card(ctx, command) {
+	record_check_chunk(ctx, {
+		kind: "tool_call_start",
+		...CHECK_CALL,
+		step_index: 0
+	});
+	record_check_chunk(ctx, {
+		kind: "tool_call_end",
+		id: CHECK_CALL.id,
+		input: { command },
+		step_index: 0
+	});
+}
+/** Close the check's card with its result, which the card's reader renders,
+* or with the error that stopped the check before it had one. */
+function close_check_card(ctx, outcome) {
+	record_check_chunk(ctx, "result" in outcome ? {
+		kind: "tool_result",
+		id: CHECK_CALL.id,
+		output: outcome.result,
+		step_index: 0
+	} : {
+		kind: "tool_result",
+		id: CHECK_CALL.id,
+		error: { message: outcome.error instanceof Error ? outcome.error.message : String(outcome.error) },
+		step_index: 0
+	});
+}
+/** `check`: the deterministic gate over the tree the builder wrote. A check
+* that runs a command emits its start and end, and on a streamed run also
+* records its card as a tool call, so a reader of the stream shows it running
+* while it runs. When the caller set an approval, the check asks on that card
+* first, and a rejected check closes it failed and is recorded as failed. */
 async function check_phase(deps, s, ctx) {
 	const { config, renderer } = deps;
 	renderer.phase_start(s.iteration, "check");
+	const command = check_command(config);
+	if (command === null) {
+		renderer.info("no deterministic check configured; loop is critic-gated only");
+		return {
+			...s,
+			check: skipped_check("none")
+		};
+	}
+	emit(ctx, {
+		volley: "check_start",
+		round: s.iteration,
+		command
+	});
+	open_check_card(ctx, command);
 	try {
-		const result = await execute_check(config, ctx.abort);
-		if (result.ran) renderer.phase_end(s.iteration, "check", result.ok, result.failing_slots.length > 0 ? `failing: ${result.failing_slots.join(", ")}` : void 0);
-		else renderer.info("no deterministic check configured; loop is critic-gated only");
+		const allowed = await check_allowed(deps, command, ctx.abort);
+		const result = allowed ? await execute_check(deps, ctx.abort) : rejected_check(config.check_resolved);
+		close_check_card(ctx, allowed ? { result } : { error: CHECK_REJECTED });
+		emit(ctx, {
+			volley: "check_end",
+			round: s.iteration,
+			ok: result.ok,
+			exit_code: result.exit_code,
+			failing_slots: result.failing_slots,
+			duration_ms: result.duration_ms
+		});
+		renderer.phase_end(s.iteration, "check", result.ok, !allowed ? "rejected" : result.failing_slots.length > 0 ? `failing: ${result.failing_slots.join(", ")}` : void 0);
 		return {
 			...s,
 			check: result,
 			check_duration_ms: s.check_duration_ms + result.duration_ms
 		};
 	} catch (err) {
+		close_check_card(ctx, { error: err });
 		if (error_kind(err) === "check_error") throw err;
 		throw phase_error("check", s.iteration, err);
 	}
@@ -2832,6 +3202,14 @@ async function critique_phase(deps, critic, s, ctx) {
 		critic,
 		config: deps.config
 	}, s, ctx);
+	if (critiqued.verdict !== null) emit(ctx, {
+		volley: "verdict",
+		round: critiqued.iteration,
+		verdict: critiqued.verdict,
+		feedback: critiqued.feedback ?? "",
+		unmet_criteria: critiqued.unmet_criteria,
+		degraded: critiqued.critic?.critic_degraded === true
+	});
 	renderer.phase_end(critiqued.iteration, "critic", critiqued.verdict === "approved", critiqued.verdict ?? void 0);
 	renderer.cost_line(critiqued.iteration, "critic", critiqued.critic?.cost_usd ?? null, critiqued.total_cost_usd);
 	return critiqued;
@@ -2867,30 +3245,32 @@ function record_phase(deps, s) {
 *   │  │  └─ 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
 *   │  └─ record                          archive the iteration and rewrite the run summary
 *   └─ guard  gate                        stop on approval over a green check, the cost cap, or a gate edit
 */
-/** The critic arm: the degradation ladder. A local critic whose tool-bearing
-* stream dies is retried at once (the death is stochastic parser failure, not
-* load, so waiting buys nothing), then judged once without tools; anything the
-* ladder does not retry propagates from either rung untouched. */
+/** The critic arm: the degradation ladder. A critic on any provider but
+* `claude_cli` whose tool-bearing stream dies is retried at once (the death is
+* stochastic parser failure, not load, so waiting buys nothing), then judged
+* once without tools. One that runs out of steps skips the retry, since
+* another identical tool loop would only run out again, and goes straight to
+* the tool-less pass. Anything else propagates from either rung untouched. */
 function build_critic(deps) {
 	const retryable = critic_retryable(deps.config);
 	return fallback(retry(make_critic_tools_step(deps), {
-		description: "one more try after a stream death, local providers only",
+		description: "one more try after a stream death, on any provider but claude_cli",
 		max_attempts: 2,
 		backoff_ms: 0,
 		when: retryable,
 		project: with_retries
 	}), pipe(make_critic_toolless_step(deps), as_degraded, { description: "mark the verdict degraded" }), {
 		name: "critic",
-		description: "judge without tools if a local critic's stream keeps dying",
-		when: retryable,
+		description: "judge without tools if a critic on any provider but claude_cli keeps dying or runs out of steps",
+		when: critic_degradable(deps.config),
 		handoff: (prompt) => toolless_critic_prompt(deps.config, prompt),
 		project: with_fallback_cause
 	});
@@ -2898,13 +3278,13 @@ function build_critic(deps) {
 function build_flow(deps, resume_from) {
 	const { config, renderer } = deps;
 	const builder = make_builder_step({
-		engine: deps.engines.builder,
+		...deps.seats.builder,
 		config,
 		on_chunk: renderer.builder_chunk,
 		bash_executor: deps.bash_executor
 	});
 	const critic = build_critic({
-		engine: deps.engines.critic,
+		...deps.seats.critic,
 		config,
 		on_chunk: renderer.critic_chunk
 	});
@@ -2954,19 +3334,19 @@ function build_flow(deps, resume_from) {
 * substrate.
 *
 *   run_volley
-*   ├─ initialize the workspace (or preserve it, on resume)
+*   ├─ initialize the run's state (or preserve it, on resume)
 *   ├─ with_worktree                    off unless --worktree
 *   │  ├─ capture the change baseline
-*   │  ├─ run_loop                      run(build_flow(...)), then the final summary
+*   │  ├─ run_loop                      run the flow (streamed when a sink is given), then the final summary
 *   │  └─ integrate                     a successful --worktree --git run only
 *   └─ report a kept checkout, or a salvaged branch (re-stamping the summary)
 */
 async function run_volley(config, deps, resume_from = null) {
 	const { renderer } = deps;
 	if (resume_from === null) {
-		initialize_workspace(config.workspace);
+		initialize_run_state(config);
 		write_resolved_config(config);
-	} else initialize_workspace(config.workspace, { preserve: true });
+	} else initialize_run_state(config, { preserve: true });
 	report_worktree_fate(config, renderer);
 	const branch = worktree_branch(config.run_id);
 	const fate = worktree_fate(config);
@@ -3007,18 +3387,24 @@ async function run_loop(config, deps, resume_from, bash_executor, baseline) {
 		critic: deps.engine
 	};
 	const flow = build_flow({
-		engines,
+		seats: {
+			builder: {
+				...deps.seats?.builder,
+				engine: engines.builder
+			},
+			critic: {
+				...deps.seats?.critic,
+				engine: engines.critic
+			}
+		},
 		config,
 		renderer,
 		bash_executor,
-		baseline
+		baseline,
+		...deps.check !== void 0 ? { check: deps.check } : {}
 	}, resume_from);
 	try {
-		const { value, converged } = await run(flow, { resume_from }, {
-			trajectory: filesystem_logger({ output_path: volley_path(config.workspace, "trajectory.jsonl") }),
-			...deps.abort !== void 0 ? { abort: deps.abort } : {},
-			...deps.install_signal_handlers !== void 0 ? { install_signal_handlers: deps.install_signal_handlers } : {}
-		});
+		const { value, converged } = await execute_flow(config, deps, flow, { resume_from });
 		const result = run_result_from_state(config, value, status_of(value, converged), (/* @__PURE__ */ new Date()).toISOString());
 		write_run_summary(config, result);
 		return result;
@@ -3029,6 +3415,45 @@ async function run_loop(config, deps, resume_from, bash_executor, baseline) {
 		await dispose_seat_engines(engines);
 	}
 }
+/** Run the flow into its file trajectory and, when the caller passed one, its
+* own sink. Without a sink this is the one `run` it has always been. With one,
+* it goes through `run.stream`, because only a streamed run records each model
+* call's chunks as `model_chunk` events, which are what an outer consumer maps
+* to text, tool cards, and approval prompts. The sink is that consumer, so the
+* handle's own event stream is closed at once rather than left to buffer, and
+* the file skips the chunks, so it holds the same kinds of event either way.
+*
+* The file goes first in the tee because the first sink's span ids are the
+* ones the run hands out as parents, so the file's parent links stay whole.
+* The sink sees parent ids it never issued, which costs an ACP consumer
+* nothing: it counts a step's runs by the `id` on each `span_start`. */
+function execute_flow(config, deps, flow, input) {
+	const file = filesystem_logger({ output_path: state_path(config, "trajectory.jsonl") });
+	const options = {
+		...deps.abort !== void 0 ? { abort: deps.abort } : {},
+		...deps.install_signal_handlers !== void 0 ? { install_signal_handlers: deps.install_signal_handlers } : {}
+	};
+	if (deps.trajectory === void 0) return run(flow, input, {
+		...options,
+		trajectory: file
+	});
+	const handle = run.stream(flow, input, {
+		...options,
+		trajectory: tee_logger(without_model_chunks(file), deps.trajectory)
+	});
+	handle.events[Symbol.asyncIterator]().return?.();
+	return handle.result;
+}
+/** A logger that passes `inner` every event but a model call's streamed
+* chunks. */
+function without_model_chunks(inner) {
+	return {
+		...inner,
+		record: (event) => {
+			if (event.kind !== "model_chunk") inner.record(event);
+		}
+	};
+}
 /** Best-effort status stamp on the run summary when the loop threw; the
 * on-disk iteration state is already consistent (record runs per round). */
 function finalize_failed_run(config, err) {
@@ -3036,7 +3461,7 @@ function finalize_failed_run(config, err) {
 	const cause = kind === "phase_error" ? error_kind(err.cause) : null;
 	const status = kind === "aborted_error" || cause === "aborted_error" ? "interrupted" : "error";
 	try {
-		const summary_path = volley_path(config.workspace, "summary.json");
+		const summary_path = state_path(config, "summary.json");
 		write_run_summary(config, {
 			...existsSync(summary_path) ? JSON.parse(readFileSync(summary_path, "utf8")) : run_result_from_state(config, initial_state(), status, null),
 			status,
@@ -3089,6 +3514,7 @@ function summarize_value(value, max = 120) {
 function create_renderer(options) {
 	const write = options.write ?? ((text) => process.stderr.write(text));
 	const { mode, color } = options;
+	const see_trajectory = `see ${options.trajectory_path ?? ".volley/trajectory.jsonl"}`;
 	const silent = mode === "json";
 	const streaming = mode === "default" || mode === "verbose";
 	let mid_line = false;
@@ -3110,7 +3536,7 @@ function create_renderer(options) {
 				mid_line = !chunk.text.endsWith("\n");
 				return;
 			case "tool_call_end": {
-				const summary = mode === "verbose" ? truncate(JSON.stringify(chunk.input, null, 2) ?? "", VERBOSE_TRUNCATE_CHARS, "see .volley/trajectory.jsonl") : summarize_value(chunk.input);
+				const summary = mode === "verbose" ? truncate(JSON.stringify(chunk.input, null, 2) ?? "", VERBOSE_TRUNCATE_CHARS, see_trajectory) : summarize_value(chunk.input);
 				line(`${GLYPH_TOOL} ${paint(role, chunk.id, color)} ${summary}`);
 				return;
 			}
@@ -3118,7 +3544,7 @@ function create_renderer(options) {
 				const ok = chunk.error === void 0;
 				if (mode === "verbose") {
 					const body = ok ? summarize_output(chunk.output) : chunk.error?.message ?? "";
-					line(`${ok ? "✅" : "❌"} ${truncate(body, VERBOSE_TRUNCATE_CHARS, "see .volley/trajectory.jsonl")}`);
+					line(`${ok ? "✅" : "❌"} ${truncate(body, VERBOSE_TRUNCATE_CHARS, see_trajectory)}`);
 				} else line(`${ok ? "✅" : "❌"} ${ok ? "" : summarize_value(chunk.error?.message)}`);
 				return;
 			}