@robmclarty/volley 0.10.0 → 0.11.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { cac } from "cac";
 import { serve_acp, to_session_updates, workspace_tools } from "fascicle/acp";
@@ -101,6 +101,438 @@ function step_countdown(max_steps, check) {
 	};
 }
 //#endregion
+//#region src/builder/prepare_step.ts
+/** One hook that runs `hooks` in order, each on the request the one before it
+* made, and reports no change when none of them made one. */
+function compose_prepare_steps(hooks) {
+	return async ({ step_index, messages }) => {
+		let request = messages;
+		let changed = false;
+		for (const hook of hooks) {
+			const prepared = await hook({
+				step_index,
+				messages: request
+			});
+			if (prepared?.messages !== void 0) {
+				request = prepared.messages;
+				changed = true;
+			}
+		}
+		return changed ? { messages: request } : void 0;
+	};
+}
+//#endregion
+//#region src/builder/trim.ts
+/**
+* Trimming a long tool-loop session's history (#7). Every turn resends the
+* whole session, every earlier `read_file` result included, even for files the
+* builder has rewritten since, so a long local session's requests grow
+* linearly and each turn's latency grows with them: volley-41806476's input
+* went from 2.6k to 57k tokens over 50 steps, and its turns from 3 s to as
+* much as 120 s.
+*
+* Above a size the operator sets (`--builder-trim-history`), each turn's
+* request replaces the older tool results with one-line stubs: a read of a
+* file a later call wrote, edited, or read whole says so, and any other result
+* names its call and size. The last `TRIM_KEEP_TURNS` turns, every assistant
+* and user message, every failed call's result, and anything short stay as
+* they are. It goes in through fascicle's `prepare_step`, which reshapes only
+* what one turn sends, so the transcript stays as the model wrote it.
+*
+* A local runtime reuses the KV cache for the prefix a request shares with
+* the last one, and rewriting an earlier message breaks that prefix, so the
+* window is prefilled again. So the trim moves in coarse steps: it stubs
+* everything before a turn boundary, boundaries fall every
+* `TRIM_STRIDE_TURNS` turns, and the boundary moves on only when the trimmed
+* request has grown past the size again. Between moves each request starts
+* with the same bytes as the last, since a stub depends only on what came
+* before its boundary and never on the step. The trim keeps no state:
+* `trim_cutoff` works the boundary out again from the transcript each turn.
+*/
+/** A rough token count per character: the hook sees no token counts, so a
+* request's size is estimated from its text. */
+const CHARS_PER_TOKEN = 4;
+/** What a message costs beyond its text: its role and framing. */
+const MESSAGE_OVERHEAD_TOKENS = 8;
+/** The calls that change a file, whose success makes an earlier read of it
+* stale. Both volley's tools and fascicle's ACP tools use these names and a
+* `path` input. */
+const FILE_WRITERS = /* @__PURE__ */ new Set(["write_file", "edit_file"]);
+const COMMAND_TOOLS = /* @__PURE__ */ new Set(["bash", "run_command"]);
+function message_chars(message) {
+	if (typeof message.content === "string") return message.content.length;
+	let chars = 0;
+	for (const part of message.content) if (part.type === "text" || part.type === "reasoning") chars += part.text.length;
+	else if (part.type === "tool_call") chars += part.name.length + (JSON.stringify(part.input) ?? "").length;
+	return chars;
+}
+/** A request's size in tokens, estimated from its characters. */
+function estimate_tokens(messages) {
+	let tokens = 0;
+	for (const message of messages) tokens += Math.ceil(message_chars(message) / CHARS_PER_TOKEN) + MESSAGE_OVERHEAD_TOKENS;
+	return tokens;
+}
+function call_input(input) {
+	if (typeof input !== "object" || input === null) return {
+		path: null,
+		whole: true
+	};
+	const fields = input;
+	return {
+		path: typeof fields["path"] === "string" ? posix.normalize(fields["path"]) : null,
+		whole: fields["offset"] === void 0 && fields["limit"] === void 0
+	};
+}
+/** Each tool call's input, by call id, from the assistant messages in
+* `messages`. */
+function call_inputs(messages) {
+	const inputs = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		if (message.role !== "assistant" || typeof message.content === "string") continue;
+		for (const part of message.content) if (part.type === "tool_call") inputs.set(part.id, call_input(part.input));
+	}
+	return inputs;
+}
+/** Whether this result is one whose call changed its file or read it whole. */
+function supersession_of(message, input) {
+	if (input === void 0 || input.path === null || message.is_error === true) return null;
+	if (FILE_WRITERS.has(message.name)) return message.content.startsWith("error:") ? null : {
+		tool: message.name,
+		changed: true
+	};
+	if (message.name === "read_file" && input.whole) return {
+		tool: "read_file",
+		changed: false
+	};
+	return null;
+}
+function exit_code_of(content) {
+	try {
+		const parsed = JSON.parse(content);
+		if (typeof parsed === "object" && parsed !== null) {
+			const code = parsed["exit_code"];
+			if (typeof code === "number") return code;
+		}
+	} catch {}
+	return null;
+}
+function stub(message, input, later) {
+	const size = `${String(message.content.length)} chars`;
+	if (later !== void 0 && input !== void 0 && input.path !== null) return later.changed ? `[volley] read_file ${input.path} (${size}) elided: a later ${later.tool} changed this file. Read it again for its current content.` : `[volley] read_file ${input.path} (${size}) elided: it was read again later in this session.`;
+	const exit_code = COMMAND_TOOLS.has(message.name) ? exit_code_of(message.content) : null;
+	const detail = exit_code === null ? size : `${size}, exit ${String(exit_code)}`;
+	return `[volley] ${message.name} output (${detail}) elided from an earlier turn. Run it again if you need it.`;
+}
+/**
+* The request with every tool result before `cutoff` that is long enough to
+* matter and didn't fail replaced by a stub. Every message keeps its place,
+* role, id, and name. A stub reads only what comes before `cutoff`, so the
+* same transcript prefix always gives the same bytes.
+*/
+function trim_view(messages, cutoff) {
+	const window = messages.slice(0, cutoff);
+	const inputs = call_inputs(window);
+	const next_on_path = /* @__PURE__ */ new Map();
+	const later_for = /* @__PURE__ */ new Map();
+	for (let i = window.length - 1; i >= 0; i -= 1) {
+		const message = window[i];
+		if (message?.role !== "tool") continue;
+		const input = inputs.get(message.tool_call_id);
+		const path = input?.path ?? null;
+		if (path === null) continue;
+		if (message.name === "read_file") {
+			const later = next_on_path.get(path);
+			if (later !== void 0) later_for.set(i, later);
+		}
+		const supersedes = supersession_of(message, input);
+		if (supersedes !== null) next_on_path.set(path, supersedes);
+	}
+	return messages.map((message, i) => {
+		if (i >= cutoff || message.role !== "tool" || message.is_error === true) return message;
+		if (message.content.length <= 200) return message;
+		return {
+			...message,
+			content: stub(message, inputs.get(message.tool_call_id), later_for.get(i))
+		};
+	});
+}
+/**
+* Where to cut this turn's request, as a message index, or null to send it
+* whole. Boundaries are the starts of turns `TRIM_STRIDE_TURNS`,
+* `2 * TRIM_STRIDE_TURNS`, and so on, short of the last `TRIM_KEEP_TURNS`.
+* The cut moves to the next boundary only while the request, trimmed at the
+* last one, is still over `threshold`. A trimmed request only grows as the
+* session goes on, so a boundary once taken is kept.
+*/
+function trim_cutoff(messages, threshold) {
+	const turn_starts = messages.flatMap((message, i) => message.role === "assistant" ? [i] : []);
+	let cutoff = null;
+	for (let turn = 8; turn <= turn_starts.length - 6; turn += 8) {
+		if (estimate_tokens(cutoff === null ? messages : trim_view(messages, cutoff)) <= threshold) break;
+		cutoff = turn_starts[turn] ?? null;
+	}
+	return cutoff;
+}
+/** The `prepare_step` hook that trims a request estimated above `threshold`
+* tokens. */
+function step_trim(threshold) {
+	return ({ messages }) => {
+		const cutoff = trim_cutoff(messages, threshold);
+		return cutoff === null ? void 0 : { messages: trim_view(messages, cutoff) };
+	};
+}
+//#endregion
+//#region src/types.ts
+function config_error(message) {
+	return Object.assign(new Error(message), { kind: "config_error" });
+}
+function check_error(message) {
+	return Object.assign(new Error(message), { kind: "check_error" });
+}
+/** Wraps a provider/schema failure with the phase and iteration it hit. */
+function phase_error(phase, iteration, cause) {
+	const detail = cause instanceof Error ? cause.message : String(cause);
+	return Object.assign(/* @__PURE__ */ new Error(`${phase} failed on iteration ${iteration}: ${detail}`), {
+		kind: "phase_error",
+		phase,
+		iteration,
+		cause
+	});
+}
+function error_kind(err) {
+	if (typeof err === "object" && err !== null && "kind" in err) {
+		const kind = err.kind;
+		return typeof kind === "string" ? kind : null;
+	}
+	return null;
+}
+//#endregion
+//#region src/engine.ts
+/**
+* The ONLY module that calls fascicle's `create_engine`. Every
+* other module receives an `Engine`-shaped value, which keeps the engine
+* mockable in tests and confines provider knowledge to one seam.
+*/
+/** LM Studio's OpenAI-compatible server and Ollama's server-root defaults.
+* The Ollama URL is the server root, NOT `…/api`: `ai-sdk-ollama` appends
+* `/api/...` itself, so a base URL ending in `/api` requests `/api/api/chat`
+* 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";
+/** Every variable a seat reads a credential from. Every process volley starts
+* runs without them (the check, the builder's commands, and volley's own git
+* and checkride calls, which run hooks and filters the builder can write), so
+* nothing the builder writes can read the keys its seats spend. */
+const SEAT_CREDENTIAL_VARS = [OPENROUTER_KEY_VAR, ANTHROPIC_KEY_VAR];
+/** The environment every process volley starts runs with: `env`, `PATH`
+* included, less every variable a seat reads a credential from. */
+function command_env(env) {
+	const stripped = new Set(SEAT_CREDENTIAL_VARS);
+	return Object.fromEntries(Object.entries(env).filter((entry) => entry[1] !== void 0 && !stripped.has(entry[0])));
+}
+/** 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
+* except across the boundary at `VOLLEY_MODEL_HOST`. `URL.hostname` keeps an
+* IPv6 literal's brackets, so the IPv6 loopback is spelled `[::1]`. */
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]",
+	"0.0.0.0"
+]);
+/** Cross a loopback base URL to the host LLM endpoint. When volley
+* runs inside its sandbox container the local model daemon is on the *host*, so
+* the example's `docker run` injects `VOLLEY_MODEL_HOST=host.docker.internal`
+* (the host-gateway allowlist target; see `sandbox_invocation` in
+* `src/sandbox.ts`). This normalizer *consumes that override* and swaps a
+* loopback host for the gateway, so an unchanged `http://localhost:11434` still
+* reaches the host from in-container. A non-loopback URL (a real remote daemon)
+* is left untouched, and an unset `VOLLEY_MODEL_HOST` (the host / unsandboxed
+* path) is a no-op — so the default and all-Claude paths are unaffected. */
+function cross_to_host_gateway(base_url, env) {
+	const host = env["VOLLEY_MODEL_HOST"];
+	if (host === void 0 || host === "") return base_url;
+	let parsed;
+	try {
+		parsed = new URL(base_url);
+	} catch {
+		return base_url;
+	}
+	if (!LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase())) return base_url;
+	parsed.hostname = host;
+	return parsed.toString().replace(/\/$/, "");
+}
+function strip_trailing_slashes(url) {
+	return url.replace(/\/+$/, "");
+}
+const SEAT_URL_SOURCES = {
+	ollama: {
+		env: "VOLLEY_OLLAMA_URL",
+		default_url: DEFAULT_OLLAMA_URL,
+		normalize: (url) => strip_trailing_slashes(url).replace(/\/api$/, "")
+	},
+	lmstudio: {
+		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`), 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. */
+function takes_seat_url(provider) {
+	return SEAT_URL_PROVIDERS.includes(provider);
+}
+/** An absent, empty, or all-whitespace value counts as unset. */
+function present(value) {
+	const trimmed = value?.trim() ?? "";
+	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` /
+* `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 {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		throw config_error(`VOLLEY_PRICING_PATH is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/** A seat's provider entry, with the base URL resolved for that seat. The ai-sdk
+* 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, 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.
+*
+* 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.
+*
+* 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);
+	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
+* by the builder or critic role is wired in alongside it, at that seat's URL,
+* so one engine drives both roles. An engine holds one URL per provider, so on
+* a provider both seats share it carries the builder's; `create_seat_engines`
+* gives the critic its own engine when its URL differs. Binary, auth mode,
+* fallback provider URLs, and pricing come from the environment. */
+function create_volley_engine(options) {
+	const env = options.env ?? process.env;
+	const auth_mode = env["VOLLEY_AUTH_MODE"] ?? "auto";
+	if (auth_mode !== "auto" && auth_mode !== "oauth" && auth_mode !== "api_key") throw config_error(`VOLLEY_AUTH_MODE must be auto, oauth, or api_key; got: ${auth_mode}`);
+	const binary = env["VOLLEY_CLAUDE_BIN"];
+	const pricing_path = env["VOLLEY_PRICING_PATH"];
+	const providers = { claude_cli: {
+		default_cwd: options.workspace,
+		setting_sources: ["project", "local"],
+		auth_mode,
+		omit_env: SEAT_CREDENTIAL_VARS,
+		...binary !== void 0 && binary.length > 0 ? { binary } : {},
+		...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));
+	return create_engine({
+		providers,
+		...pricing_path !== void 0 && pricing_path.length > 0 ? { pricing: load_pricing_overrides(pricing_path) } : {}
+	});
+}
+/** One engine per seat, shared unless it can't be. fascicle fixes one base URL
+* per provider when it builds an engine, so two seats on the same provider at
+* different URLs need two engines: the critic's is derived from the builder's
+* with `with_providers`, which keeps claude_cli, auth, and pricing and
+* overrides only the shared provider's entry. Every other pairing, including a
+* run that sets no seat URL at all, gets the one engine a run has always had. */
+async function create_seat_engines(options) {
+	const env = options.env ?? process.env;
+	const builder = create_volley_engine(options);
+	const provider = options.critic_provider;
+	if (provider !== options.builder_provider || !takes_seat_url(provider) || seat_base_url(provider, options.builder_url ?? null, env) === seat_base_url(provider, options.critic_url ?? null, env)) return {
+		builder,
+		critic: builder
+	};
+	try {
+		return {
+			builder,
+			critic: builder.with_providers(seat_provider_config(provider, options.critic_url ?? null, env))
+		};
+	} catch (err) {
+		await builder.dispose();
+		throw err;
+	}
+}
+/** Dispose each distinct seat engine once. Both disposals start together, so
+* one that fails doesn't keep the other from running. */
+async function dispose_seat_engines(engines) {
+	const distinct = engines.critic === engines.builder ? [engines.builder] : [engines.builder, engines.critic];
+	await Promise.all(distinct.map((engine) => engine.dispose()));
+}
+//#endregion
 //#region src/workspace_tools.ts
 /**
 * Shared workspace tools: `contain()` path confinement plus the read-only
@@ -564,14 +996,17 @@ async function run_fetch(raw, ctx, config) {
 * containment this runs *inside* volley's hardened container against the
 * bind-mounted worktree — the container is the isolation boundary, no
 * `docker exec` hop — and it is likewise the executor on the
-* `--allow-unsandboxed-builder` host escape hatch. `status` is null
-* when a signal (the timeout SIGKILL) killed the process.
+* `--allow-unsandboxed-builder` host escape hatch. A command runs with
+* volley's environment less the seats' keys, so nothing the builder runs can
+* read the key its seat spends. `status` is null when a signal (the timeout
+* SIGKILL) killed the process.
 */
 function host_bash_executor(cwd) {
 	return (command, options) => {
 		const result = spawnSync(command, {
 			shell: true,
 			cwd,
+			env: command_env(process.env),
 			encoding: "utf8",
 			timeout: options.timeout_ms,
 			killSignal: "SIGKILL",
@@ -673,31 +1108,6 @@ function finish_tool() {
 	};
 }
 //#endregion
-//#region src/types.ts
-function config_error(message) {
-	return Object.assign(new Error(message), { kind: "config_error" });
-}
-function check_error(message) {
-	return Object.assign(new Error(message), { kind: "check_error" });
-}
-/** Wraps a provider/schema failure with the phase and iteration it hit. */
-function phase_error(phase, iteration, cause) {
-	const detail = cause instanceof Error ? cause.message : String(cause);
-	return Object.assign(/* @__PURE__ */ new Error(`${phase} failed on iteration ${iteration}: ${detail}`), {
-		kind: "phase_error",
-		phase,
-		iteration,
-		cause
-	});
-}
-function error_kind(err) {
-	if (typeof err === "object" && err !== null && "kind" in err) {
-		const kind = err.kind;
-		return typeof kind === "string" ? kind : null;
-	}
-	return null;
-}
-//#endregion
 //#region src/check/checkride.ts
 /**
 * checkride runner: spawn `pnpm exec checkride --json --digest`, gate on the
@@ -734,7 +1144,7 @@ function spawn_capture(cmd, args, options) {
 	return new Promise((resolve_promise, reject) => {
 		const proc = spawn(cmd, args, {
 			cwd: options.cwd,
-			...options.env !== void 0 ? { env: options.env } : {},
+			env: options.env ?? command_env(process.env),
 			detached: process.platform !== "win32",
 			stdio: [
 				"ignore",
@@ -940,6 +1350,60 @@ function rejected_check(runner) {
 	};
 }
 //#endregion
+//#region src/claude_cli_permissions.ts
+/** Whether a seat this run drives runs on the Claude CLI. A critique has no
+* builder, whatever its provider resolved to. */
+function uses_claude_cli(config) {
+	return config.mode !== "critique" && config.builder_provider === "claude_cli" || config.critic_provider === "claude_cli";
+}
+const BUILDER_ALLOWED_TOOLS = [
+	"Read(/**)",
+	"Edit(/**)",
+	"Bash",
+	"WebFetch"
+];
+const CRITIC_ALLOWED_TOOLS = ["Read(/**)"];
+const CRITIC_DISALLOWED_TOOLS = "Write,Edit,MultiEdit,NotebookEdit,Bash";
+const PERMISSION_BLOCKS = { permissions: {
+	blockWritesOutsideWorkingDirectories: true,
+	blockReadsOutsideWorkingDirectories: true
+} };
+/** The CLI flags that turn on `PERMISSION_BLOCKS`. */
+function settings_args() {
+	return ["--settings", JSON.stringify(PERMISSION_BLOCKS)];
+}
+const MIN_CLAUDE_WRITE_BLOCK = [
+	2,
+	1,
+	314
+];
+const MIN_CLAUDE_READ_BLOCK = [
+	2,
+	1,
+	257
+];
+/** The version `claude --version` printed (`2.1.316 (Claude Code)`), or null
+* when it printed something else. */
+function parse_claude_version(stdout) {
+	const match = /^\s*(\d+)\.(\d+)\.(\d+)\b/.exec(stdout);
+	if (match === null) return null;
+	return [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+}
+function version_below(version, min) {
+	const [major, minor, patch] = version;
+	const [min_major, min_minor, min_patch] = min;
+	if (major !== min_major) return major < min_major;
+	if (minor !== min_minor) return minor < min_minor;
+	return patch < min_patch;
+}
+function format_version(version) {
+	return version.join(".");
+}
+//#endregion
 //#region src/cost.ts
 /**
 * Cost and usage accumulation. All pricing knowledge lives in
@@ -995,14 +1459,77 @@ function phase_record(result, model, duration_ms = result.timing?.duration_ms ??
 		...rate !== void 0 ? { throughput: rate } : {}
 	};
 }
+const NS_PER_MS = 1e6;
+function ns_field(payload, name) {
+	const value = payload[name];
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+/** A turn's prefill and decode times: Ollama's own durations when it reported
+* them (in ns), else the time to the first streamed chunk, else none. */
+function step_split(step) {
+	const reported = step.provider_reported?.["ollama"];
+	if (typeof reported === "object" && reported !== null) {
+		const ollama = reported;
+		const evaluated = ns_field(ollama, "eval_duration");
+		const prompt = ns_field(ollama, "prompt_eval_duration");
+		if (evaluated !== void 0 && prompt !== void 0) return {
+			prefill_ms: Math.round(prompt / NS_PER_MS),
+			decode_ms: Math.round(evaluated / NS_PER_MS),
+			timing_basis: "ollama_reported"
+		};
+		const total = ns_field(ollama, "total_duration");
+		const load = ns_field(ollama, "load_duration");
+		if (evaluated !== void 0 && total !== void 0 && load !== void 0 && total >= load + evaluated) return {
+			prefill_ms: Math.round((total - load - evaluated) / NS_PER_MS),
+			decode_ms: Math.round(evaluated / NS_PER_MS),
+			timing_basis: "ollama_derived"
+		};
+	}
+	const timing = step.timing;
+	if (timing?.first_chunk_ms !== void 0 && timing.whole_tool_call !== true) return {
+		prefill_ms: timing.first_chunk_ms,
+		decode_ms: Math.max(0, timing.duration_ms - timing.first_chunk_ms),
+		timing_basis: "first_chunk"
+	};
+	return { timing_basis: "none" };
+}
+/** How much a tool call's result put into the transcript: its output as the
+* loop serializes it, or the error text it fed back. */
+function output_chars(call) {
+	if (call.output === void 0) return call.error?.message.length ?? 0;
+	return typeof call.output === "string" ? call.output.length : (JSON.stringify(call.output) ?? "").length;
+}
+/** Each turn of a session as the archive records it, or undefined when the
+* result has none. */
+function step_records(result) {
+	if (result.steps.length === 0) return void 0;
+	return result.steps.map((step) => ({
+		index: step.index,
+		input_tokens: step.usage.input_tokens,
+		output_tokens: step.usage.output_tokens,
+		duration_ms: step.timing?.duration_ms ?? 0,
+		...step_split(step),
+		finish_reason: step.finish_reason,
+		...step.truncated === true ? { truncated: true } : {},
+		tool_calls: step.tool_calls.map((call) => ({
+			name: call.name,
+			output_chars: output_chars(call)
+		}))
+	}));
+}
 /** Fold one phase's result into the loop state. Unknown cost records `null`
-* for the phase and warns once per run — a run never fails over pricing. */
+* for the phase and warns once per run — a run never fails over pricing. The
+* builder's record also carries its session's turns. */
 function accumulate(state, role, result, model, duration_ms) {
 	const record = phase_record(result, model, duration_ms);
+	const steps = role === "builder" ? step_records(result) : void 0;
 	const cost = record.cost_usd ?? 0;
 	return {
 		...state,
-		[role]: record,
+		[role]: steps !== void 0 ? {
+			...record,
+			steps
+		} : record,
 		total_usage: add_usage(state.total_usage, result.usage),
 		total_cost_usd: state.total_cost_usd + cost,
 		iteration_cost_usd: state.iteration_cost_usd + cost,
@@ -1015,224 +1542,6 @@ function cost_cap_hit(config, state) {
 	return config.max_cost_usd !== null && state.total_cost_usd >= config.max_cost_usd;
 }
 //#endregion
-//#region src/engine.ts
-/**
-* The ONLY module that calls fascicle's `create_engine`. Every
-* other module receives an `Engine`-shaped value, which keeps the engine
-* mockable in tests and confines provider knowledge to one seam.
-*/
-/** LM Studio's OpenAI-compatible server and Ollama's server-root defaults.
-* The Ollama URL is the server root, NOT `…/api`: `ai-sdk-ollama` appends
-* `/api/...` itself, so a base URL ending in `/api` requests `/api/api/chat`
-* 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";
-/** Every variable a seat reads a credential from. Under acp, the builder's
-* commands and the check run without them, so nothing the builder writes can
-* read the keys its seats spend. */
-const SEAT_CREDENTIAL_VARS = [OPENROUTER_KEY_VAR, ANTHROPIC_KEY_VAR];
-/** 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
-* except across the boundary at `VOLLEY_MODEL_HOST`. `URL.hostname` keeps an
-* IPv6 literal's brackets, so the IPv6 loopback is spelled `[::1]`. */
-const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
-	"localhost",
-	"127.0.0.1",
-	"[::1]",
-	"0.0.0.0"
-]);
-/** Cross a loopback base URL to the host LLM endpoint. When volley
-* runs inside its sandbox container the local model daemon is on the *host*, so
-* the example's `docker run` injects `VOLLEY_MODEL_HOST=host.docker.internal`
-* (the host-gateway allowlist target; see `sandbox_invocation` in
-* `src/sandbox.ts`). This normalizer *consumes that override* and swaps a
-* loopback host for the gateway, so an unchanged `http://localhost:11434` still
-* reaches the host from in-container. A non-loopback URL (a real remote daemon)
-* is left untouched, and an unset `VOLLEY_MODEL_HOST` (the host / unsandboxed
-* path) is a no-op — so the default and all-Claude paths are unaffected. */
-function cross_to_host_gateway(base_url, env) {
-	const host = env["VOLLEY_MODEL_HOST"];
-	if (host === void 0 || host === "") return base_url;
-	let parsed;
-	try {
-		parsed = new URL(base_url);
-	} catch {
-		return base_url;
-	}
-	if (!LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase())) return base_url;
-	parsed.hostname = host;
-	return parsed.toString().replace(/\/$/, "");
-}
-function strip_trailing_slashes(url) {
-	return url.replace(/\/+$/, "");
-}
-const SEAT_URL_SOURCES = {
-	ollama: {
-		env: "VOLLEY_OLLAMA_URL",
-		default_url: DEFAULT_OLLAMA_URL,
-		normalize: (url) => strip_trailing_slashes(url).replace(/\/api$/, "")
-	},
-	lmstudio: {
-		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`), 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. */
-function takes_seat_url(provider) {
-	return SEAT_URL_PROVIDERS.includes(provider);
-}
-/** An absent, empty, or all-whitespace value counts as unset. */
-function present(value) {
-	const trimmed = value?.trim() ?? "";
-	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` /
-* `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 {
-		return JSON.parse(readFileSync(path, "utf8"));
-	} catch (err) {
-		throw config_error(`VOLLEY_PRICING_PATH is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
-	}
-}
-/** A seat's provider entry, with the base URL resolved for that seat. The ai-sdk
-* 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, 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.
-*
-* 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.
-*
-* 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);
-	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
-* by the builder or critic role is wired in alongside it, at that seat's URL,
-* so one engine drives both roles. An engine holds one URL per provider, so on
-* a provider both seats share it carries the builder's; `create_seat_engines`
-* gives the critic its own engine when its URL differs. Binary, auth mode,
-* fallback provider URLs, and pricing come from the environment. */
-function create_volley_engine(options) {
-	const env = options.env ?? process.env;
-	const auth_mode = env["VOLLEY_AUTH_MODE"] ?? "auto";
-	if (auth_mode !== "auto" && auth_mode !== "oauth" && auth_mode !== "api_key") throw config_error(`VOLLEY_AUTH_MODE must be auto, oauth, or api_key; got: ${auth_mode}`);
-	const binary = env["VOLLEY_CLAUDE_BIN"];
-	const pricing_path = env["VOLLEY_PRICING_PATH"];
-	const providers = { claude_cli: {
-		default_cwd: options.workspace,
-		setting_sources: ["project", "local"],
-		auth_mode,
-		...binary !== void 0 && binary.length > 0 ? { binary } : {},
-		...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));
-	return create_engine({
-		providers,
-		...pricing_path !== void 0 && pricing_path.length > 0 ? { pricing: load_pricing_overrides(pricing_path) } : {}
-	});
-}
-/** One engine per seat, shared unless it can't be. fascicle fixes one base URL
-* per provider when it builds an engine, so two seats on the same provider at
-* different URLs need two engines: the critic's is derived from the builder's
-* with `with_providers`, which keeps claude_cli, auth, and pricing and
-* overrides only the shared provider's entry. Every other pairing, including a
-* run that sets no seat URL at all, gets the one engine a run has always had. */
-async function create_seat_engines(options) {
-	const env = options.env ?? process.env;
-	const builder = create_volley_engine(options);
-	const provider = options.critic_provider;
-	if (provider !== options.builder_provider || !takes_seat_url(provider) || seat_base_url(provider, options.builder_url ?? null, env) === seat_base_url(provider, options.critic_url ?? null, env)) return {
-		builder,
-		critic: builder
-	};
-	try {
-		return {
-			builder,
-			critic: builder.with_providers(seat_provider_config(provider, options.critic_url ?? null, env))
-		};
-	} catch (err) {
-		await builder.dispose();
-		throw err;
-	}
-}
-/** Dispose each distinct seat engine once. Both disposals start together, so
-* one that fails doesn't keep the other from running. */
-async function dispose_seat_engines(engines) {
-	const distinct = engines.critic === engines.builder ? [engines.builder] : [engines.builder, engines.critic];
-	await Promise.all(distinct.map((engine) => engine.dispose()));
-}
-//#endregion
 //#region src/prewarm.ts
 /**
 * Best-effort Ollama model pre-load. A cold multi-GB model can spend minutes
@@ -1468,6 +1777,7 @@ function write_resolved_config(config, env = process.env) {
 		builder_max_steps: config.builder_max_steps,
 		builder_max_tool_calls: config.builder_max_tool_calls,
 		builder_max_output_tokens: config.builder_max_output_tokens,
+		builder_trim_history: config.builder_trim_history,
 		critic_model: config.critic_model,
 		critic_provider: config.critic_provider,
 		critic_url: config.critic_url,
@@ -1513,6 +1823,7 @@ function commit_identity(cwd) {
 			key
 		], {
 			cwd,
+			env: command_env(process.env),
 			encoding: "utf8"
 		});
 		return set.status === 0 && set.stdout.trim() !== "" ? [] : ["-c", `${key}=${value}`];
@@ -1540,7 +1851,10 @@ function git_checkpoint(root, message, excluded_dir = null) {
 		"add",
 		"-A",
 		...pathspec
-	], { cwd: root });
+	], {
+		cwd: root,
+		env: command_env(process.env)
+	});
 	if (add.error !== void 0 || add.status !== 0) throw check_error(`git add failed: ${add.stderr?.toString() ?? String(add.error)}`);
 	const commit = spawnSync("git", [
 		...commit_identity(root),
@@ -1548,7 +1862,10 @@ function git_checkpoint(root, message, excluded_dir = null) {
 		"-m",
 		message,
 		"--no-verify"
-	], { cwd: root });
+	], {
+		cwd: root,
+		env: command_env(process.env)
+	});
 	if (commit.error !== void 0) throw check_error(`git commit failed to start: ${String(commit.error)}`);
 	const out = `${commit.stdout?.toString() ?? ""}${commit.stderr?.toString() ?? ""}`;
 	if (commit.status !== 0 && !/nothing (?:added )?to commit/.test(out)) throw check_error(`git commit failed: ${out.trim()}`);
@@ -1572,6 +1889,7 @@ function integrate_worktree(workspace, branch, message) {
 		branch
 	], {
 		cwd: workspace,
+		env: command_env(process.env),
 		encoding: "utf8"
 	});
 	if (squash.error !== void 0) throw check_error(`git merge --squash failed to start: ${String(squash.error)}`);
@@ -1584,6 +1902,7 @@ function integrate_worktree(workspace, branch, message) {
 		"--no-verify"
 	], {
 		cwd: workspace,
+		env: command_env(process.env),
 		encoding: "utf8"
 	});
 	if (commit.error !== void 0) throw check_error(`git commit failed to start: ${String(commit.error)}`);
@@ -1693,6 +2012,7 @@ function report_worktree_fate(config, sink) {
 function git$1(cwd, args) {
 	const result = spawnSync("git", args, {
 		cwd,
+		env: command_env(process.env),
 		encoding: "utf8"
 	});
 	if (result.error !== void 0) throw config_error(`git is required for --worktree but could not run: ${String(result.error)}`);
@@ -1719,6 +2039,7 @@ function git_quiet(cwd, args) {
 	try {
 		const result = spawnSync("git", args, {
 			cwd,
+			env: command_env(process.env),
 			encoding: "utf8"
 		});
 		return {
@@ -1930,16 +2251,6 @@ async function with_worktree(options, body) {
 * complete agentic session in the workspace — Claude Code under `claude_cli`,
 * or a model driving volley's tools on any other provider, local or hosted.
 */
-const BUILDER_ALLOWED_TOOLS = [
-	"Read",
-	"Write",
-	"Edit",
-	"MultiEdit",
-	"Bash",
-	"Grep",
-	"Glob",
-	"WebFetch"
-];
 function compose_builder_system() {
 	return [
 		"You are the builder inside the volley harness: an autonomous agent",
@@ -2001,6 +2312,14 @@ function check_hint(config) {
 	if (config.check_resolved === "command") return `the check (\`${config.check}\`)`;
 	return "the project's tests";
 }
+/** The builder's `prepare_step`: the countdown, after the history trim when
+* `--builder-trim-history` turns it on, so the countdown's note still goes
+* last. */
+function builder_prepare_step(config) {
+	const countdown = step_countdown(config.builder_max_steps, check_hint(config));
+	if (config.builder_trim_history === null) return countdown;
+	return compose_prepare_steps([step_trim(config.builder_trim_history), countdown]);
+}
 /** 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
@@ -2008,7 +2327,8 @@ function check_hint(config) {
 * 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), the per-call loop knobs, the step
-* countdown (`./builder/countdown.ts`), the output cap when one is set, and
+* countdown (`./builder/countdown.ts`) and the history trim when it's on
+* (`./builder/trim.ts`), the output cap when one is set, and
 * **no** schema (it produces a workspace, not a verdict); per-call values win
 * over engine defaults. */
 function builder_tool_options(deps) {
@@ -2016,7 +2336,11 @@ function builder_tool_options(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]
+		extra_args: [
+			"--permission-mode",
+			config.builder_permission_mode,
+			...settings_args()
+		]
 	} } };
 	return {
 		tools: deps.tools === void 0 ? builder_tools(build_root(config.workspace, config.worktree), bash_executor !== null ? { bash_executor } : {}) : [...deps.tools],
@@ -2025,7 +2349,7 @@ function builder_tool_options(deps) {
 		tool_error_policy: "feed_back",
 		tool_call_repair_attempts: BUILDER_TOOL_CALL_REPAIR_ATTEMPTS,
 		max_tool_calls_per_step: config.builder_max_tool_calls,
-		prepare_step: step_countdown(config.builder_max_steps, check_hint(config)),
+		prepare_step: builder_prepare_step(config),
 		...config.builder_max_output_tokens !== null ? {
 			max_tokens: config.builder_max_output_tokens,
 			truncated_turn_policy: "continue"
@@ -2231,6 +2555,7 @@ function git(root, args) {
 	try {
 		const result = spawnSync("git", args, {
 			cwd: root,
+			env: command_env(process.env),
 			encoding: "utf8",
 			maxBuffer: 33554432
 		});
@@ -2551,12 +2876,6 @@ function compose_critic_prompt(input) {
 * structured verdict. The
 * harness — not the critic — writes the run's `feedback.md` and `verdict`.
 */
-const CRITIC_ALLOWED_TOOLS = [
-	"Read",
-	"Grep",
-	"Glob"
-];
-const CRITIC_DISALLOWED_TOOLS = "Write,Edit,MultiEdit,NotebookEdit,Bash";
 /** A critic that holds tools isn't constrain-decoded, so nothing stops it
 * answering null for the feedback or the unmet list, as GLM did on approving.
 * Both fields allow null and read it as empty, so that answer is a verdict
@@ -2569,7 +2888,8 @@ const verdict_schema = z.object({
 	unmet_criteria: z.array(z.string()).nullable().transform((unmet) => unmet ?? []).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); every other critic,
+* the CLI permission layer (allowlist + explicit disallow, and the settings
+* blocks that keep its reads in the build root); 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.
 *
@@ -2591,7 +2911,11 @@ const verdict_schema = z.object({
 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]
+		extra_args: [
+			"--disallowedTools",
+			CRITIC_DISALLOWED_TOOLS,
+			...settings_args()
+		]
 	} } };
 	return {
 		tools: tools === void 0 ? read_only_tools(build_root(config.workspace, config.worktree)) : [...tools],
@@ -2957,7 +3281,8 @@ function phase_summary(record) {
 		...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 } : {}
+		...record.throughput !== void 0 ? { throughput: record.throughput } : {},
+		...record.steps !== void 0 ? { steps: record.steps } : {}
 	};
 }
 /** Archive one completed iteration: verdict files, check artifacts, and the
@@ -3214,6 +3539,7 @@ function load_resume_state(workspace, run_id, state_dir = null, options = {}) {
 		...recorded["builder_max_steps"] === void 0 ? {} : { builder_max_steps: Number(recorded["builder_max_steps"]) },
 		...recorded["builder_max_tool_calls"] === void 0 ? {} : { builder_max_tool_calls: Number(recorded["builder_max_tool_calls"]) },
 		...typeof recorded["builder_max_output_tokens"] === "number" ? { builder_max_output_tokens: recorded["builder_max_output_tokens"] } : {},
+		...typeof recorded["builder_trim_history"] === "number" ? { builder_trim_history: recorded["builder_trim_history"] } : {},
 		critic_model: String(recorded["critic_model"]),
 		critic_provider: recorded["critic_provider"] ?? "claude_cli",
 		...typeof recorded["critic_url"] === "string" ? { critic_url: recorded["critic_url"] } : {},
@@ -3441,13 +3767,14 @@ function report_changes(config, renderer, changes) {
 	renderer.warn(`gate edit: ${who} ${String(changes.gate_edits.length)} file(s) that decide ${whose} — ${listed}${hidden > 0 ? ` (+${String(hidden)} more)` : ""}. A green check proves less when ${edits} 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)." : ""));
 }
 /** Run the configured check, checkride or a command, with the environment
-* the caller set for it, else volley's own. */
+* the caller set for it, else volley's own less the seats' keys, since the
+* check runs code the builder wrote. */
 async function execute_check(deps, abort) {
 	const { config } = deps;
 	const root = build_root(config.workspace, config.worktree);
 	const options = {
 		abort,
-		...deps.check?.env !== void 0 ? { env: deps.check.env } : {}
+		env: deps.check?.env ?? command_env(process.env)
 	};
 	return config.check_resolved === "checkride" ? run_checkride({
 		...options,
@@ -3987,13 +4314,6 @@ const CRITIC_READS = /* @__PURE__ */ new Set([
 	"list_files",
 	"search"
 ]);
-/** The environment the builder's commands and the check run with under acp:
-* the agent's own, `PATH` included, less every variable a seat reads a
-* credential from. */
-function acp_command_env(env) {
-	const stripped = new Set(SEAT_CREDENTIAL_VARS);
-	return Object.fromEntries(Object.entries(env).filter((entry) => entry[1] !== void 0 && !stripped.has(entry[0])));
-}
 /** Whether `tool` asks before a call with `input`. A set without the tool
 * asks, so a check never runs unasked by mistake. */
 async function asks_before(tool, input) {
@@ -4008,10 +4328,10 @@ async function asks_before(tool, input) {
 * the session exactly when the builder's `run_command` would ask before
 * running the same command. */
 function acp_seat_tools(session, options = {}) {
-	const command_env = acp_command_env(options.env ?? process.env);
+	const env = command_env(options.env ?? process.env);
 	const tools = workspace_tools(session, {
 		ignore: [...IGNORED_DIRS],
-		command_env
+		command_env: env
 	});
 	const run_command = tools.find((tool) => tool.name === "run_command");
 	return {
@@ -4025,7 +4345,7 @@ function acp_seat_tools(session, options = {}) {
 			tool_set: "acp"
 		},
 		check: {
-			env: command_env,
+			env,
 			on_approval: async (request) => await asks_before(run_command, request.input) ? session.approve(request) : true
 		}
 	};
@@ -4149,6 +4469,7 @@ const CRITIQUE_REFUSED = [
 	["builder_max_steps", "--builder-max-steps"],
 	["builder_max_tool_calls", "--builder-max-tool-calls"],
 	["builder_max_output_tokens", "--builder-max-output-tokens"],
+	["builder_trim_history", "--builder-trim-history"],
 	["builder_permission_mode", "--builder-permission-mode"],
 	["allow_unsandboxed_builder", "--allow-unsandboxed-builder"],
 	["sandbox_image", "--sandbox-image"],
@@ -4188,6 +4509,12 @@ function builder_max_output_tokens_count(provider) {
 		fallback: CAPPED_BY_DEFAULT.includes(provider) ? DEFAULT_BUILDER_MAX_OUTPUT_TOKENS : null
 	};
 }
+/** The history trim's size: off unless something sets it. */
+const BUILDER_TRIM_HISTORY = {
+	flag: "--builder-trim-history",
+	env_var: "VOLLEY_BUILDER_TRIM_HISTORY",
+	fallback: null
+};
 /** A builder count's flag or config value wins over its env var, which wins
 * over the default, and either must be a positive integer. Local builder
 * only; ignored by the `claude_cli` arm. */
@@ -4322,6 +4649,7 @@ function resolve_config(raw, options = {}) {
 	const builder_max_steps = resolve_builder_count(raw.builder_max_steps, builder_env, BUILDER_MAX_STEPS);
 	const builder_max_tool_calls = resolve_builder_count(raw.builder_max_tool_calls, builder_env, BUILDER_MAX_TOOL_CALLS);
 	const builder_max_output_tokens = resolve_builder_count(raw.builder_max_output_tokens, builder_env, builder_max_output_tokens_count(builder_provider));
+	const builder_trim_history = resolve_builder_count(raw.builder_trim_history, builder_env, BUILDER_TRIM_HISTORY);
 	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);
@@ -4360,6 +4688,7 @@ function resolve_config(raw, options = {}) {
 		builder_max_steps,
 		builder_max_tool_calls,
 		builder_max_output_tokens,
+		builder_trim_history,
 		allow_unsandboxed_builder,
 		critic_model: raw.critic_model ?? DEFAULT_CRITIC_MODEL,
 		critic_provider,
@@ -5455,6 +5784,10 @@ function render_matrix_table(rows) {
 * never requires Docker or a model server — so they never contribute an exit 5
 * on that path.
 *
+* A `claude_cli` seat gets one read of `claude --version`, which only ever
+* warns: below the version that enforces the settings blocks keeping the seat's
+* file tools in the build root, the dry run says what goes unenforced.
+*
 * A *local critic* additionally gets the critic-seat canary: one tiny $0
 * generate through the real critic tool wiring, run
 * whatever the builder provider is. A degradable failure warns and predicts
@@ -5476,6 +5809,7 @@ const REQUIRED_TOOLCHAIN = [
 /** A short cap on the endpoint probe so a wrong/unreachable host fails fast
 * rather than hanging the preflight before the loop even starts. */
 const ENDPOINT_PROBE_TIMEOUT_MS = 3e3;
+const CLAUDE_VERSION_TIMEOUT_MS = 1e4;
 /** Builders that drive their model through volley's own tool loop, local or
 * hosted, so the containment preflight applies. `claude_cli` never does. */
 function is_tool_loop_builder(provider) {
@@ -5522,7 +5856,10 @@ async function probe_seat_endpoints(config, renderer, env, reachable) {
 /** Which required executables are not runnable on the current PATH. */
 function toolchain_missing(tools = REQUIRED_TOOLCHAIN) {
 	return tools.filter((tool) => {
-		const result = spawnSync(tool, ["--version"], { stdio: "ignore" });
+		const result = spawnSync(tool, ["--version"], {
+			env: command_env(process.env),
+			stdio: "ignore"
+		});
 		return result.error !== void 0 || result.status !== 0;
 	});
 }
@@ -5531,7 +5868,10 @@ function toolchain_missing(tools = REQUIRED_TOOLCHAIN) {
 * run's job — worktree.ts). */
 function worktree_creatable(workspace) {
 	const repo = resolve(workspace);
-	const version = spawnSync("git", ["--version"], { stdio: "ignore" });
+	const version = spawnSync("git", ["--version"], {
+		env: command_env(process.env),
+		stdio: "ignore"
+	});
 	if (version.error !== void 0 || version.status !== 0) return {
 		ok: false,
 		detail: "git is not available"
@@ -5545,7 +5885,10 @@ function worktree_creatable(workspace) {
 		repo,
 		"rev-parse",
 		"--is-inside-work-tree"
-	], { encoding: "utf8" });
+	], {
+		env: command_env(process.env),
+		encoding: "utf8"
+	});
 	if (inside.status !== 0 || (inside.stdout ?? "").trim() !== "true") return {
 		ok: false,
 		detail: `${repo} is not a git work tree`
@@ -5555,6 +5898,33 @@ function worktree_creatable(workspace) {
 		detail: repo
 	};
 }
+/** What `claude --version` printed, from the binary the run will spawn, or
+* null when it didn't run. */
+function claude_version(env) {
+	const binary = env["VOLLEY_CLAUDE_BIN"];
+	const result = spawnSync(binary !== void 0 && binary.length > 0 ? binary : "claude", ["--version"], {
+		env: command_env(process.env),
+		encoding: "utf8",
+		timeout: CLAUDE_VERSION_TIMEOUT_MS
+	});
+	if (result.error !== void 0 || result.status !== 0) return null;
+	return result.stdout;
+}
+/** Name the Claude Code version a `claude_cli` seat runs on, and warn when it
+* is too old to enforce the blocks that keep the seat's file tools in the
+* build root. Never fails the dry run. */
+function report_claude_cli(config, renderer, env, probe) {
+	if (!uses_claude_cli(config)) return;
+	const printed = probe(env);
+	const version = printed === null ? null : parse_claude_version(printed);
+	if (version === null) {
+		renderer.warn("claude: could not read the Claude Code version (`claude --version`), so whether it keeps a claude_cli seat's file tools in the build root is unknown");
+		return;
+	}
+	renderer.info(`claude: ${format_version(version)}`);
+	if (version_below(version, MIN_CLAUDE_WRITE_BLOCK)) renderer.warn(`claude: Claude Code ${format_version(version)} ignores the block on writes outside the build root (needs ${format_version(MIN_CLAUDE_WRITE_BLOCK)}). Edit(/**) still keeps a builder's edits there under acceptEdits, but not under bypassPermissions.`);
+	if (version_below(version, MIN_CLAUDE_READ_BLOCK)) renderer.warn(`claude: Claude Code ${format_version(version)} ignores the block on reads outside the build root (needs ${format_version(MIN_CLAUDE_READ_BLOCK)}).`);
+}
 /** Reachability probe: any HTTP response (even a 404) proves the TCP connect
 * landed; a thrown error (connection refused, DNS failure, timeout) means the
 * endpoint is unreachable. */
@@ -5618,6 +5988,7 @@ function run_checkride_doctor(workspace) {
 		"doctor"
 	], {
 		cwd: workspace,
+		env: command_env(process.env),
 		stdio: [
 			"ignore",
 			"ignore",
@@ -5643,6 +6014,7 @@ async function preflight(config, renderer, env, probes = {}) {
 		renderer.info(`builder max steps: ${config.builder_max_steps}`);
 		renderer.info(`builder tool calls per turn: ${config.builder_max_tool_calls}`);
 		renderer.info(`builder output tokens per turn: ${config.builder_max_output_tokens ?? "the provider's limit"}`);
+		renderer.info(`builder history trim: ${config.builder_trim_history === null ? "off" : `above ${String(config.builder_trim_history)} estimated tokens`}`);
 	}
 	if (tool_loop_builder) {
 		const contained = detect_containment(env);
@@ -5653,6 +6025,7 @@ async function preflight(config, renderer, env, probes = {}) {
 	renderer.info(seat_line("critic", config.critic_model, config.critic_provider, config.critic_url, env));
 	report_worktree_fate(config, renderer);
 	report_gate_posture(config, renderer);
+	report_claude_cli(config, renderer, env, probes.claude_version ?? claude_version);
 	if (config.check_resolved === "checkride") {
 		if (!(probes.checkride_doctor ?? run_checkride_doctor)(config.workspace)) {
 			renderer.error("checkride doctor failed; fix the workspace check pipeline before running");
@@ -5750,8 +6123,19 @@ function make_renderer(config, run_id = config.run_id) {
 		}, "trajectory.jsonl")
 	});
 }
-function warn_api_key_meter(renderer) {
-	if (process.env["ANTHROPIC_API_KEY"] !== void 0) renderer.warn("ANTHROPIC_API_KEY is set: the claude CLI will bill this run against the API key, not a subscription. Know which meter you are on.");
+/** Only `VOLLEY_AUTH_MODE=api_key` hands the claude CLI a key: under `auto`
+* and `oauth` it gets none and stays on its own login, whatever is set. */
+function warn_api_key_meter(config, renderer, env = process.env) {
+	if (uses_claude_cli(config) && env["VOLLEY_AUTH_MODE"] === "api_key") renderer.warn("VOLLEY_AUTH_MODE=api_key: the claude CLI bills this run to ANTHROPIC_API_KEY at API rates, not to a subscription. Know which meter you are on.");
+}
+/** What to try when a `claude_cli` seat on the subscription login can't
+* authenticate, which is how every such seat fails once `claude -p` runs bare by
+* default (volley#9). Null for any other error. */
+function claude_login_hint(err, env = process.env) {
+	const auth_failure = [err, err?.cause].some((e) => error_kind(e) === "provider_auth_error" && e.provider === "claude_cli");
+	const auth_mode = env["VOLLEY_AUTH_MODE"] ?? "auto";
+	if (!auth_failure || auth_mode === "api_key") return null;
+	return `a claude_cli seat on the subscription login (VOLLEY_AUTH_MODE=${auth_mode}) could not authenticate. If \`claude auth login\` does not fix it, a Claude Code release that runs \`claude -p\` bare by default would explain it (volley#9): set VOLLEY_AUTH_MODE=api_key with ANTHROPIC_API_KEY to run on the API key meanwhile.`;
 }
 /** One loud warning when a tool-loop builder is about to run *uncontained* on
 * the host via the opt-out. Config resolution has already refused this
@@ -5774,7 +6158,7 @@ function with_critic_options(command, required = false) {
 function with_seat_options(command, required = false) {
 	const model_note = required ? " (required)" : "";
 	const provider_note = required ? "required" : "default: claude_cli";
-	return with_critic_options(command.option("--builder-model <model>", `Builder model${model_note}`).option("--builder-provider <name>", `claude_cli | ollama | lmstudio | openrouter (${provider_note})`).option("--builder-url <url>", "Builder's model server base URL, ollama, lmstudio, or openrouter only (default: VOLLEY_OLLAMA_URL / VOLLEY_LMSTUDIO_URL / VOLLEY_OPENROUTER_URL)").option("--builder-max-steps <n>", "Tool-loop builder step cap per iteration, any provider but claude_cli (default: 50)").option("--builder-max-tool-calls <n>", "Tool calls a tool-loop builder may make per turn, reads aside, any provider but claude_cli (default: 1)").option("--builder-max-output-tokens <n>", "Output tokens a tool-loop builder may generate per turn, reasoning included, any provider but claude_cli (default: 16384 on ollama and lmstudio, the provider's on openrouter)").option("--allow-unsandboxed-builder", "Permit a builder other than claude_cli to run without a sandbox (real host bash + write)"), required);
+	return with_critic_options(command.option("--builder-model <model>", `Builder model${model_note}`).option("--builder-provider <name>", `claude_cli | ollama | lmstudio | openrouter (${provider_note})`).option("--builder-url <url>", "Builder's model server base URL, ollama, lmstudio, or openrouter only (default: VOLLEY_OLLAMA_URL / VOLLEY_LMSTUDIO_URL / VOLLEY_OPENROUTER_URL)").option("--builder-max-steps <n>", "Tool-loop builder step cap per iteration, any provider but claude_cli (default: 50)").option("--builder-max-tool-calls <n>", "Tool calls a tool-loop builder may make per turn, reads aside, any provider but claude_cli (default: 1)").option("--builder-max-output-tokens <n>", "Output tokens a tool-loop builder may generate per turn, reasoning included, any provider but claude_cli (default: 16384 on ollama and lmstudio, the provider's on openrouter)").option("--builder-trim-history <tokens>", "Experimental: above this estimated request size, a tool-loop builder's turns send older tool results as one-line stubs, any provider but claude_cli (default: off)").option("--allow-unsandboxed-builder", "Permit a builder other than claude_cli to run without a sandbox (real host bash + write)"), required);
 }
 /** What a critique declares only so that it can refuse each by name, with
 * exit 5: cac would answer an undeclared one with a bare "Unknown option".
@@ -5786,6 +6170,7 @@ const CRITIQUE_REFUSED_OPTIONS = [
 	"--builder-max-steps <n>",
 	"--builder-max-tool-calls <n>",
 	"--builder-max-output-tokens <n>",
+	"--builder-trim-history <tokens>",
 	"--builder-permission-mode <mode>",
 	"--allow-unsandboxed-builder",
 	"--sandbox-image <tag>",
@@ -5810,6 +6195,7 @@ function merge_flags(base, flags) {
 		...flags.builderMaxSteps !== void 0 ? { builder_max_steps: Number(flags.builderMaxSteps) } : {},
 		...flags.builderMaxToolCalls !== void 0 ? { builder_max_tool_calls: Number(flags.builderMaxToolCalls) } : {},
 		...flags.builderMaxOutputTokens !== void 0 ? { builder_max_output_tokens: Number(flags.builderMaxOutputTokens) } : {},
+		...flags.builderTrimHistory !== void 0 ? { builder_trim_history: Number(flags.builderTrimHistory) } : {},
 		...flags.allowUnsandboxedBuilder === true ? { allow_unsandboxed_builder: true } : {},
 		...flags.criticModel !== void 0 ? { critic_model: flags.criticModel } : {},
 		...flags.criticProvider !== void 0 ? { critic_provider: flags.criticProvider } : {},
@@ -5858,6 +6244,8 @@ function report_error(err) {
 		const cause = err.cause;
 		if (cause instanceof Error && cause.message !== message) process.stderr.write(`  cause: ${cause.message}\n`);
 	}
+	const hint = claude_login_hint(err);
+	if (hint !== null) process.stderr.write(`  hint: ${hint}\n`);
 	return exit_code_for_error(err);
 }
 async function main(argv) {
@@ -5868,7 +6256,7 @@ async function main(argv) {
 		const run_id = not_a_bare_number("--run-id", flags.runId);
 		const config = resolve_config(merged, run_id !== void 0 ? { run_id } : {});
 		const renderer = make_renderer(config);
-		warn_api_key_meter(renderer);
+		warn_api_key_meter(config, renderer);
 		warn_unsandboxed_builder(config, renderer);
 		if (merged.dry_run === true) {
 			exit_code = await preflight(config, renderer, process.env);
@@ -5887,7 +6275,7 @@ async function main(argv) {
 		});
 		if (resume.iterations_completed >= config.max_iterations) throw config_error(`run already completed ${String(resume.iterations_completed)} of ${String(config.max_iterations)} iterations`);
 		const renderer = make_renderer(config);
-		warn_api_key_meter(renderer);
+		warn_api_key_meter(config, renderer);
 		warn_unsandboxed_builder(config, renderer);
 		if (resume.config_signed === false) warn_trusted_config(config, renderer);
 		renderer.info(`resuming run ${run_id} at iteration ${String(resume.iterations_completed + 1)}`);
@@ -5906,7 +6294,7 @@ async function main(argv) {
 			...run_id !== void 0 ? { run_id } : {}
 		});
 		const renderer = make_renderer(config);
-		warn_api_key_meter(renderer);
+		warn_api_key_meter(config, renderer);
 		if (merged.dry_run === true) {
 			const sha = resolve_baseline(config.workspace, baseline);
 			renderer.info(`baseline: ${sha ?? "none (not a git repository, or no commit yet)"}`);
@@ -5935,7 +6323,7 @@ async function main(argv) {
 			discard_worktree: true
 		});
 		const renderer = make_renderer(base_config, "<run id>");
-		warn_api_key_meter(renderer);
+		warn_api_key_meter(base_config, renderer);
 		warn_unsandboxed_builder(base_config, renderer);
 		const outcome = await run_matrix({
 			base: merged,
@@ -5967,6 +6355,6 @@ if (import.meta.main) {
 	process.exitCode = code;
 }
 //#endregion
-export { package_version, warn_unsandboxed_builder };
+export { claude_login_hint, package_version, warn_api_key_meter, warn_unsandboxed_builder };
 
 //# sourceMappingURL=cli.js.map