@robmclarty/volley 0.5.3 → 0.6.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/config.ts
-import { accessSync, constants, existsSync, readFileSync, statSync } from "fs";
+import { accessSync, constants, existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "fs";
 import { isAbsolute, resolve } from "path";
 import { pathToFileURL } from "url";
 import { randomUUID } from "crypto";
@@ -133,6 +133,31 @@ function collect_changes(options) {
   };
 }
 
+// src/check/detect.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+function package_check_script_is_checkride(workspace) {
+  const path = join(workspace, "package.json");
+  if (!existsSync(path)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(path, "utf8"));
+    const script = pkg.scripts?.["check"];
+    return typeof script === "string" && /(^|\s)checkride(\s|$)/.test(script);
+  } catch {
+    return false;
+  }
+}
+function checkride_detected(workspace) {
+  return existsSync(join(workspace, "checkride.config.json")) || package_check_script_is_checkride(workspace) || existsSync(join(workspace, "node_modules", ".bin", "checkride"));
+}
+function resolve_check_runner(check, workspace) {
+  if (check === "none") return "none";
+  if (check === "auto") {
+    return checkride_detected(workspace) ? "checkride" : "none";
+  }
+  return /(^|\s)checkride(\s|$)/.test(check.trim()) ? "checkride" : "command";
+}
+
 // src/types.ts
 function config_error(message) {
   return Object.assign(new Error(message), { kind: "config_error" });
@@ -192,17 +217,17 @@ var PERMISSION_MODES = [
 function expand_at_file(value, cwd) {
   if (!value.startsWith("@")) return value;
   const path = resolve(cwd, value.slice(1));
-  if (!existsSync(path)) {
+  if (!existsSync2(path)) {
     throw config_error(`file not found: ${path} (from ${value})`);
   }
-  return readFileSync(path, "utf8");
+  return readFileSync2(path, "utf8");
 }
 function is_critic_preset(value) {
   return CRITIC_PRESETS.includes(value);
 }
 async function load_config_file(path) {
   const abs = resolve(path);
-  if (!existsSync(abs)) {
+  if (!existsSync2(abs)) {
     throw config_error(`config file not found: ${abs}`);
   }
   let loaded;
@@ -220,7 +245,7 @@ async function load_config_file(path) {
 }
 function validate_workspace(workspace) {
   const abs = isAbsolute(workspace) ? workspace : resolve(workspace);
-  if (!existsSync(abs)) {
+  if (!existsSync2(abs)) {
     throw config_error(`workspace not found: ${abs}`);
   }
   if (!statSync(abs).isDirectory()) {
@@ -238,7 +263,7 @@ function resolve_critic(critic, cwd) {
     return { critic_preset: critic, critic_prompt_path: null };
   }
   const path = resolve(cwd, critic);
-  if (!existsSync(path)) {
+  if (!existsSync2(path)) {
     throw config_error(
       `--critic must be one of ${CRITIC_PRESETS.join(", ")} or a path to a prompt file; got: ${critic}`
     );
@@ -282,6 +307,16 @@ function detect_containment(env) {
   const value = env["VOLLEY_CONTAINED"];
   return value === "1" || value === "true";
 }
+var RUN_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+function resolve_run_id(run_id) {
+  if (run_id === void 0) return randomUUID();
+  if (!RUN_ID_PATTERN.test(run_id)) {
+    throw config_error(
+      `--run-id must be letters, digits, '-', and '_', starting with a letter or digit; got: ${run_id}`
+    );
+  }
+  return run_id;
+}
 function resolve_config(raw, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const env = options.env ?? process.env;
@@ -347,11 +382,11 @@ function resolve_config(raw, options = {}) {
       );
     }
   }
-  if (raw.git_checkpoints === true && !existsSync(resolve(workspace, ".git"))) {
+  if (raw.git_checkpoints === true && !existsSync2(resolve(workspace, ".git"))) {
     throw config_error(`--git requires the workspace to be a git repository: ${workspace}`);
   }
   const worktree = raw.worktree ?? false;
-  if (worktree && !existsSync(resolve(workspace, ".git"))) {
+  if (worktree && !existsSync2(resolve(workspace, ".git"))) {
     throw config_error(`--worktree requires the workspace to be a git repository: ${workspace}`);
   }
   const discard_worktree = raw.discard_worktree ?? false;
@@ -365,14 +400,16 @@ function resolve_config(raw, options = {}) {
     throw config_error("gate_paths must be an array of glob strings");
   }
   const sandbox_image = resolve_sandbox_image(raw, env);
+  const run_id = resolve_run_id(options.run_id);
+  const check = raw.check ?? DEFAULT_CHECK;
   return {
     version: 2,
-    run_id: options.run_id ?? randomUUID(),
+    run_id,
     started_at: options.started_at ?? (/* @__PURE__ */ new Date()).toISOString(),
     prompt,
     criteria,
-    check: raw.check ?? DEFAULT_CHECK,
-    check_resolved: "none",
+    check,
+    check_resolved: resolve_check_runner(check, workspace),
     builder_model: raw.builder_model ?? DEFAULT_BUILDER_MODEL,
     builder_provider,
     builder_max_steps,
@@ -399,12 +436,12 @@ function resolve_config(raw, options = {}) {
 }
 
 // src/orchestrator.ts
-import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
 import { run } from "fascicle";
 import { filesystem_logger } from "fascicle/adapters";
 
 // src/engine.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { create_engine } from "fascicle";
 var DEFAULT_OLLAMA_URL = "http://localhost:11434";
 var DEFAULT_LMSTUDIO_URL = "http://localhost:1234/v1";
@@ -428,11 +465,11 @@ function resolve_ollama_base_url(env) {
   return cross_to_host_gateway(normalized, env);
 }
 function load_pricing_overrides(path) {
-  if (!existsSync2(path)) {
+  if (!existsSync3(path)) {
     throw config_error(`VOLLEY_PRICING_PATH not found: ${path}`);
   }
   try {
-    return JSON.parse(readFileSync2(path, "utf8"));
+    return JSON.parse(readFileSync3(path, "utf8"));
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);
     throw config_error(`VOLLEY_PRICING_PATH is not valid JSON: ${detail}`);
@@ -483,8 +520,8 @@ function create_volley_engine(options) {
 import { branch, fallback, loop, pipe, retry, sequence, step } from "fascicle";
 
 // src/builder.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname2, join as join4 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { dirname as dirname2, join as join5 } from "path";
 import { fileURLToPath } from "url";
 import { model_call } from "fascicle";
 
@@ -528,7 +565,7 @@ async function warn_small_local_context(provider, model, base_url, warn, abort)
 // src/builder/tools.ts
 import { spawnSync as spawnSync2 } from "child_process";
 import { lookup as dns_lookup } from "dns";
-import { mkdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
+import { mkdirSync, readFileSync as readFileSync5, writeFileSync } from "fs";
 import { dirname } from "path";
 import { Readability } from "@mozilla/readability";
 import ipaddr from "ipaddr.js";
@@ -538,8 +575,8 @@ import { Agent, buildConnector, interceptors, request } from "undici";
 import { z as z2 } from "zod";
 
 // src/workspace_tools.ts
-import { readFileSync as readFileSync3, readdirSync, statSync as statSync2 } from "fs";
-import { isAbsolute as isAbsolute2, join, relative, resolve as resolve2, sep } from "path";
+import { readFileSync as readFileSync4, readdirSync, statSync as statSync2 } from "fs";
+import { isAbsolute as isAbsolute2, join as join2, relative, resolve as resolve2, sep } from "path";
 import { z } from "zod";
 var READ_FILE_MAX_BYTES = 2e5;
 var SEARCH_MAX_MATCHES = 200;
@@ -573,7 +610,7 @@ function walk(root, start, limit) {
       continue;
     }
     for (const name of entries) {
-      const abs = join(dir, name);
+      const abs = join2(dir, name);
       let is_dir;
       try {
         is_dir = statSync2(abs).isDirectory();
@@ -618,7 +655,7 @@ function read_only_tools(workspace) {
     execute: (raw) => {
       const input = read_file_input.parse(raw);
       const abs = contain(workspace, input.path);
-      const content = readFileSync3(abs, "utf8");
+      const content = readFileSync4(abs, "utf8");
       return content.length > READ_FILE_MAX_BYTES ? `${content.slice(0, READ_FILE_MAX_BYTES)}
 \u2026 [truncated at ${String(READ_FILE_MAX_BYTES)} bytes]` : content;
     }
@@ -637,7 +674,7 @@ function read_only_tools(workspace) {
         if (hits.length >= SEARCH_MAX_MATCHES) break;
         let content;
         try {
-          content = readFileSync3(file.abs, "utf8");
+          content = readFileSync4(file.abs, "utf8");
         } catch {
           continue;
         }
@@ -745,9 +782,9 @@ function is_forbidden_address(address) {
 var default_resolver = (hostname, options, callback) => {
   dns_lookup(hostname, options, callback);
 };
-function guarded_lookup(is_forbidden, resolve4) {
+function guarded_lookup(is_forbidden, resolve5) {
   return (hostname, options, callback) => {
-    resolve4(hostname, options, (err, address, family) => {
+    resolve5(hostname, options, (err, address, family) => {
       if (err !== null) {
         callback(err, "", 0);
         return;
@@ -769,8 +806,8 @@ function ssrf_error(address, hostname) {
   err.code = "ERR_SSRF_BLOCKED";
   return err;
 }
-function create_ssrf_agent(is_forbidden, resolve4) {
-  const base = buildConnector({ lookup: guarded_lookup(is_forbidden, resolve4), timeout: FETCH_TIMEOUT_MS });
+function create_ssrf_agent(is_forbidden, resolve5) {
+  const base = buildConnector({ lookup: guarded_lookup(is_forbidden, resolve5), timeout: FETCH_TIMEOUT_MS });
   const connector = (options, callback) => {
     base(options, (err, socket) => {
       if (err !== null) {
@@ -980,7 +1017,7 @@ function builder_tools(workspace, options = {}) {
     execute: (raw) => {
       const input = edit_file_input.parse(raw);
       const abs = contain(workspace, input.path);
-      const content = readFileSync4(abs, "utf8");
+      const content = readFileSync5(abs, "utf8");
       const matches = count_occurrences(content, input.old_str);
       if (matches === 0) {
         return `error: old_str not found in ${input.path} (0 matches). No change made. Read the file and retry with an exact excerpt of its current content.`;
@@ -1120,16 +1157,16 @@ async function prewarm_ollama_model(base_url, model, abort) {
 }
 
 // src/worktree.ts
-import { existsSync as existsSync4, renameSync as renameSync2, rmSync, symlinkSync } from "fs";
-import { join as join3, resolve as resolve3 } from "path";
+import { existsSync as existsSync5, renameSync as renameSync2, rmSync, symlinkSync } from "fs";
+import { join as join4, resolve as resolve3 } from "path";
 import { spawnSync as spawnSync4 } from "child_process";
 
 // src/workspace.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, renameSync, writeFileSync as writeFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, renameSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
 import { spawnSync as spawnSync3 } from "child_process";
 function volley_path(workspace, ...parts) {
-  return join2(workspace, ".volley", ...parts);
+  return join3(workspace, ".volley", ...parts);
 }
 function iteration_dir(workspace, iteration) {
   return volley_path(workspace, "iterations", String(iteration).padStart(3, "0"));
@@ -1139,8 +1176,8 @@ function backup_stamp(date = /* @__PURE__ */ new Date()) {
 }
 function initialize_workspace(workspace, options = {}) {
   const dir = volley_path(workspace);
-  if (existsSync3(dir) && options.preserve !== true) {
-    renameSync(dir, join2(workspace, `.volley.bak.${backup_stamp()}`));
+  if (existsSync4(dir) && options.preserve !== true) {
+    renameSync(dir, join3(workspace, `.volley.bak.${backup_stamp()}`));
   }
   mkdirSync2(volley_path(workspace, "iterations"), { recursive: true });
 }
@@ -1178,7 +1215,7 @@ function write_resolved_config(config) {
   );
 }
 function git_checkpoint(root, message) {
-  if (!existsSync3(join2(root, ".git"))) {
+  if (!existsSync4(join3(root, ".git"))) {
     throw config_error(`git checkpoints require a git repository: ${root}`);
   }
   const add = spawnSync3("git", ["add", "-A"], { cwd: root });
@@ -1197,7 +1234,7 @@ function git_checkpoint(root, message) {
   }
 }
 function integrate_worktree(workspace, branch2, message) {
-  if (!existsSync3(join2(workspace, ".git"))) {
+  if (!existsSync4(join3(workspace, ".git"))) {
     throw config_error(`--worktree integration requires a git repository: ${workspace}`);
   }
   const squash = spawnSync3("git", ["merge", "--squash", branch2], {
@@ -1299,14 +1336,14 @@ function branch_exists(repo, branch2) {
 }
 function create_worktree(options) {
   const repo = resolve3(options.workspace);
-  if (!existsSync4(join3(repo, ".git"))) {
+  if (!existsSync5(join4(repo, ".git"))) {
     throw config_error(`--worktree requires the workspace to be a git repository: ${repo}`);
   }
   const path = worktree_path(repo);
   const base = options.base ?? "HEAD";
   const log = options.log ?? (() => {
   });
-  if (existsSync4(path)) {
+  if (existsSync5(path)) {
     const backup = `${path}.bak.${backup_stamp()}`;
     renameSync2(path, backup);
     git2(repo, ["worktree", "prune"]);
@@ -1318,9 +1355,9 @@ function create_worktree(options) {
     log(`worktree: rotated existing branch ${options.branch} aside to ${backup_branch}`);
   }
   git_ok(repo, ["worktree", "add", "-b", options.branch, path, base]);
-  const modules = join3(repo, "node_modules");
-  if (existsSync4(modules) && !existsSync4(join3(path, "node_modules"))) {
-    symlinkSync(modules, join3(path, "node_modules"), "dir");
+  const modules = join4(repo, "node_modules");
+  if (existsSync5(modules) && !existsSync5(join4(path, "node_modules"))) {
+    symlinkSync(modules, join4(path, "node_modules"), "dir");
     log(`worktree: linked node_modules from ${repo}`);
   }
   return { path, branch: options.branch };
@@ -1335,7 +1372,7 @@ function teardown_worktree(options) {
     git_quiet(repo, ["branch", "-D", options.branch]);
   }
   git_quiet(repo, ["worktree", "prune"]);
-  if (existsSync4(path)) {
+  if (existsSync5(path)) {
     try {
       rmSync(path, { recursive: true, force: true });
     } catch {
@@ -1344,7 +1381,7 @@ function teardown_worktree(options) {
   return outcome;
 }
 function salvage_worktree(repo, path, branch2) {
-  if (existsSync4(path)) {
+  if (existsSync5(path)) {
     git_quiet(path, ["add", "-A"]);
     git_quiet(path, [
       "commit",
@@ -1417,8 +1454,8 @@ function compose_builder_system() {
 function presets_dir() {
   let dir = dirname2(fileURLToPath(import.meta.url));
   for (let depth = 0; depth < 6; depth += 1) {
-    const candidate = join4(dir, "src", "builder", "presets");
-    if (existsSync5(candidate)) return candidate;
+    const candidate = join5(dir, "src", "builder", "presets");
+    if (existsSync6(candidate)) return candidate;
     dir = dirname2(dir);
   }
   throw config_error("builder presets directory not found");
@@ -1429,7 +1466,7 @@ function compose_builder_system_local() {
     "iterating on a workspace until it satisfies a task and its acceptance",
     "criteria."
   ].join("\n");
-  const append = readFileSync5(join4(presets_dir(), "harness_append_local.md"), "utf8");
+  const append = readFileSync6(join5(presets_dir(), "harness_append_local.md"), "utf8");
   return `${identity}
 
 ${append.trimEnd()}`;
@@ -1506,6 +1543,7 @@ function make_builder_step(deps) {
   return model_call({
     engine: deps.engine,
     id: "builder",
+    description: "model call: one agentic session in the build root",
     provider: config.builder_provider,
     model: config.builder_model,
     system: resolve_builder_system(config),
@@ -1551,24 +1589,24 @@ import { z as z3 } from "zod";
 import { model_call as model_call2 } from "fascicle";
 
 // src/critic/prompt.ts
-import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
-import { dirname as dirname3, join as join5 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
+import { dirname as dirname3, join as join6 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function presets_dir2() {
   let dir = dirname3(fileURLToPath2(import.meta.url));
   for (let depth = 0; depth < 6; depth += 1) {
-    const candidate = join5(dir, "src", "critic", "presets");
-    if (existsSync6(candidate)) return candidate;
-    const local = join5(dir, "presets");
-    if (existsSync6(local)) return local;
+    const candidate = join6(dir, "src", "critic", "presets");
+    if (existsSync7(candidate)) return candidate;
+    const local = join6(dir, "presets");
+    if (existsSync7(local)) return local;
     dir = dirname3(dir);
   }
   throw config_error("critic presets directory not found");
 }
 function resolve_critic_prompt(config) {
-  const base = config.critic_prompt_path !== null ? readFileSync6(config.critic_prompt_path, "utf8") : readFileSync6(join5(presets_dir2(), `${config.critic_preset}.md`), "utf8");
+  const base = config.critic_prompt_path !== null ? readFileSync7(config.critic_prompt_path, "utf8") : readFileSync7(join6(presets_dir2(), `${config.critic_preset}.md`), "utf8");
   const append_file = config.critic_provider === "claude_cli" ? "harness_append.md" : "harness_append_local.md";
-  const append = readFileSync6(join5(presets_dir2(), append_file), "utf8");
+  const append = readFileSync7(join6(presets_dir2(), append_file), "utf8");
   return `${base.trimEnd()}
 
 ${append.trimEnd()}`;
@@ -1747,11 +1785,16 @@ function make_critic_tools_step(deps) {
   return model_call2({
     ...critic_call_config(deps),
     id: "critic_tools",
+    description: "model call with read-only workspace tools",
     ...critic_tool_options(deps.config)
   });
 }
 function make_critic_toolless_step(deps) {
-  return model_call2({ ...critic_call_config(deps), id: "critic_toolless" });
+  return model_call2({
+    ...critic_call_config(deps),
+    id: "critic_toolless",
+    description: "model call judging from the check output and a file list"
+  });
 }
 function critic_retryable(config) {
   return (err) => is_retryable_critic_error(config, err);
@@ -1863,8 +1906,8 @@ function status_of(value, converged) {
 }
 
 // src/check/checkride.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync8 } from "fs";
+import { join as join7 } from "path";
 import { spawn } from "child_process";
 import { aborted_error } from "fascicle";
 var CHECK_ARTIFACT_MAX_CHARS = 8e3;
@@ -1916,9 +1959,9 @@ function parse_summary_with_fallback(stdout, workspace) {
   try {
     return parse_checkride_summary(stdout);
   } catch (err) {
-    const file = join6(workspace, ".check", "summary.json");
-    if (!existsSync7(file)) throw err;
-    return parse_checkride_summary(readFileSync7(file, "utf8"));
+    const file = join7(workspace, ".check", "summary.json");
+    if (!existsSync8(file)) throw err;
+    return parse_checkride_summary(readFileSync8(file, "utf8"));
   }
 }
 function failing_checks(summary) {
@@ -1927,11 +1970,11 @@ function failing_checks(summary) {
 function read_failing_artifacts(workspace, failing) {
   return failing.map((check) => {
     const file = check.output_file ?? `${check.name}.stdout.txt`;
-    const path = join6(workspace, ".check", file);
-    if (!existsSync7(path)) {
+    const path = join7(workspace, ".check", file);
+    if (!existsSync8(path)) {
       return { slot: check.name, path: null, content: "(no artifact found)", truncated: false };
     }
-    const raw = readFileSync7(path, "utf8");
+    const raw = readFileSync8(path, "utf8");
     const truncated = raw.length > CHECK_ARTIFACT_MAX_CHARS;
     return {
       slot: check.name,
@@ -2003,14 +2046,14 @@ function skipped_check(reason) {
 
 // src/iteration.ts
 import {
-  existsSync as existsSync8,
+  existsSync as existsSync9,
   mkdirSync as mkdirSync3,
-  readFileSync as readFileSync8,
+  readFileSync as readFileSync9,
   readdirSync as readdirSync2,
   rmSync as rmSync2,
   writeFileSync as writeFileSync3
 } from "fs";
-import { basename, join as join7 } from "path";
+import { basename, join as join8 } from "path";
 function write_json(path, value) {
   writeFileSync3(path, `${JSON.stringify(value, null, 2)}
 `);
@@ -2054,32 +2097,32 @@ function phase_summary(record) {
 }
 function archive_iteration(config, state) {
   const dir = iteration_dir(config.workspace, state.iteration);
-  mkdirSync3(join7(dir, "check"), { recursive: true });
+  mkdirSync3(join8(dir, "check"), { recursive: true });
   if (state.verdict !== null && state.feedback !== null) {
     persist_verdict_files(config.workspace, state.feedback, state.verdict);
-    writeFileSync3(join7(dir, "feedback.md"), readFileSync8(volley_path(config.workspace, "feedback.md")));
-    writeFileSync3(join7(dir, "verdict"), `${state.verdict}
+    writeFileSync3(join8(dir, "feedback.md"), readFileSync9(volley_path(config.workspace, "feedback.md")));
+    writeFileSync3(join8(dir, "verdict"), `${state.verdict}
 `);
   }
   const check = state.check;
   if (check !== null && check.ran) {
     if (check.runner === "checkride") {
       if (check.summary !== void 0) {
-        write_json(join7(dir, "check", "summary.json"), check.summary);
+        write_json(join8(dir, "check", "summary.json"), check.summary);
       }
       for (const artifact of check.detail) {
-        if (artifact.path !== null && existsSync8(artifact.path)) {
-          writeFileSync3(join7(dir, "check", basename(artifact.path)), readFileSync8(artifact.path));
+        if (artifact.path !== null && existsSync9(artifact.path)) {
+          writeFileSync3(join8(dir, "check", basename(artifact.path)), readFileSync9(artifact.path));
         }
       }
     } else {
-      writeFileSync3(join7(dir, "check", "check.log"), check.log ?? "");
-      writeFileSync3(join7(dir, "check", "check.exit"), `${String(check.exit_code)}
+      writeFileSync3(join8(dir, "check", "check.log"), check.log ?? "");
+      writeFileSync3(join8(dir, "check", "check.exit"), `${String(check.exit_code)}
 `);
     }
   }
   const completed_at = (/* @__PURE__ */ new Date()).toISOString();
-  write_json(join7(dir, "summary.json"), {
+  write_json(join8(dir, "summary.json"), {
     iteration: state.iteration,
     started_at: state.iteration_started_at,
     completed_at,
@@ -2129,20 +2172,20 @@ function run_result_from_state(config, state, status, completed_at) {
 }
 
 // src/summary.ts
-import { existsSync as existsSync9, readFileSync as readFileSync9, readdirSync as readdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync10, readdirSync as readdirSync3, writeFileSync as writeFileSync4 } from "fs";
 function transport_of(provider) {
   return provider === "claude_cli" ? "claude_cli" : "ai_sdk";
 }
 function read_iteration_archives(workspace) {
   const root = volley_path(workspace, "iterations");
-  if (!existsSync9(root)) return [];
+  if (!existsSync10(root)) return [];
   const dirs = readdirSync3(root).filter((dir) => /^\d{3}$/.test(dir)).toSorted();
   const archives = [];
   for (const dir of dirs) {
     const path = volley_path(workspace, "iterations", dir, "summary.json");
-    if (!existsSync9(path)) continue;
+    if (!existsSync10(path)) continue;
     try {
-      archives.push(JSON.parse(readFileSync9(path, "utf8")));
+      archives.push(JSON.parse(readFileSync10(path, "utf8")));
     } catch {
     }
   }
@@ -2342,14 +2385,18 @@ 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",
       max_attempts: MAX_CRITIC_RETRIES + 1,
       backoff_ms: 0,
       when: retryable,
       project: with_retries
     }),
-    pipe(make_critic_toolless_step(deps), as_degraded),
+    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,
       handoff: (prompt) => toolless_critic_prompt(deps.config, prompt),
       project: with_fallback_cause
@@ -2365,13 +2412,27 @@ function build_flow(deps, resume_from) {
     bash_executor: deps.bash_executor
   });
   const critic = build_critic({ engine: deps.engine, config, on_chunk: renderer.critic_chunk });
-  const build = step("build", (s, ctx) => build_phase(deps, builder, s, ctx));
-  const skip_verify = step("skip_verify", (s) => skip_verify_phase(deps, s));
-  const check = step("check", (s, ctx) => check_phase(deps, s, ctx));
-  const critique = step("critique", (s, ctx) => critique_phase(deps, critic, s, ctx));
-  const record = step("record", (s) => record_phase(deps, s));
+  const build = step("build", (s, ctx) => build_phase(deps, builder, s, ctx), {
+    description: "open the iteration, run the builder, measure the change",
+    arm: builder
+  });
+  const skip_verify = step("skip_verify", (s) => skip_verify_phase(deps, s), {
+    description: "record the check as skipped and call no critic"
+  });
+  const check = step("check", (s, ctx) => check_phase(deps, s, ctx), {
+    description: "the deterministic gate: checkride, a command, or none"
+  });
+  const critique = step(
+    "critique",
+    (s, ctx) => critique_phase(deps, critic, s, ctx),
+    { description: "the read-only critic's verdict and feedback", arm: critic }
+  );
+  const record = step("record", (s) => record_phase(deps, s), {
+    description: "archive the iteration and rewrite the run summary"
+  });
   const verify = branch({
     name: "verify",
+    description: "did the build alone cross the cost cap?",
     when: (s) => cost_cap_hit(config, s),
     // fascicle names this arm `then`. It holds a Step object, never a function,
     // so nothing can mistake the config for a thenable.
@@ -2384,9 +2445,12 @@ function build_flow(deps, resume_from) {
   });
   return loop({
     name: "volley",
+    description: "one round per iteration, up to max_iterations",
     init: (input) => input.resume_from ?? initial_state(),
     body: iteration,
-    guard: step("gate", (s) => gate(config, s)),
+    guard: step("gate", (s) => gate(config, s), {
+      description: "stop on approval over a green check, the cost cap, or a gate edit"
+    }),
     finish: (s, { converged }) => ({ value: s, converged }),
     max_rounds: remaining_iterations(config, resume_from)
   });
@@ -2474,7 +2538,7 @@ function finalize_failed_run(config, err) {
   const status = kind === "aborted_error" || cause === "aborted_error" ? "interrupted" : "error";
   try {
     const summary_path = volley_path(config.workspace, "summary.json");
-    const prior = existsSync10(summary_path) ? JSON.parse(readFileSync10(summary_path, "utf8")) : run_result_from_state(config, initial_state(), status, null);
+    const prior = existsSync11(summary_path) ? JSON.parse(readFileSync11(summary_path, "utf8")) : run_result_from_state(config, initial_state(), status, null);
     write_run_summary(config, {
       ...prior,
       status,
@@ -2652,6 +2716,82 @@ function summarize_output(output) {
   }
 }
 
+// src/sandbox.ts
+import { resolve as resolve4 } from "path";
+var SANDBOX_WORKDIR = "/workspace";
+var SANDBOX_HOME = "/home/node";
+var HOST_GATEWAY_HOST = "host.docker.internal";
+var SANDBOX_NETWORK_NAME = "volley-sandbox-net";
+var SANDBOX_NETWORK_SUBNET = "172.31.99.0/24";
+function network_run_args(network, network_name) {
+  if (network === "none") return ["--network", "none"];
+  return ["--network", network_name, "--add-host", `${HOST_GATEWAY_HOST}:host-gateway`];
+}
+function sandbox_run_args(options) {
+  if (options.uid === 0) {
+    throw config_error("refusing to start the builder sandbox as root (uid 0)");
+  }
+  const user = options.uid !== null && options.gid !== null ? ["--user", `${String(options.uid)}:${String(options.gid)}`] : [];
+  const name = options.name !== void 0 && options.name !== null ? ["--name", options.name] : [];
+  const entrypoint = options.entrypoint !== void 0 && options.entrypoint !== null ? ["--entrypoint", options.entrypoint] : [];
+  const env = (options.env ?? []).flatMap(([key, value]) => ["-e", `${key}=${value}`]);
+  const labels = (options.labels ?? []).flatMap(([key, value]) => ["--label", `${key}=${value}`]);
+  const store = options.store_volume !== void 0 && options.store_volume !== null ? ["-v", `${options.store_volume}:${SANDBOX_HOME}/.local/share/pnpm/store`] : [];
+  return [
+    "run",
+    // One-shot, foreground container: the whole run *is* this container, so
+    // remove it when volley exits.
+    "--rm",
+    ...name,
+    ...labels,
+    ...user,
+    // Network policy: default-deny egress. `'none'` gives the container
+    // no interface; `'allowlist'` puts it on the user-defined bridge and collapses
+    // the allowlist targets onto the host gateway.
+    ...network_run_args(options.network, options.network_name),
+    // Resource caps: contain a runaway / fork-bomb / OOM without starving
+    // pnpm/tsc (pids 1024, not 100; nofile high enough for esbuild/watchers).
+    "--memory=4g",
+    "--memory-swap=4g",
+    "--memory-swappiness=0",
+    "--cpus=2",
+    "--pids-limit=1024",
+    "--ulimit",
+    "nofile=8192:16384",
+    "--ulimit",
+    "core=0",
+    // Privilege caps: drop every capability, forbid privilege
+    // escalation, keep the default seccomp profile, and run tini (PID 1) to reap
+    // zombies. Never `--privileged`.
+    "--cap-drop=ALL",
+    "--security-opt",
+    "no-new-privileges",
+    "--init",
+    // Read-only rootfs with tmpfs for the few writable paths the toolchain
+    // needs; a pnpm store, when mounted, persists on a named volume.
+    "--read-only",
+    "--tmpfs",
+    "/tmp",
+    "--tmpfs",
+    "/run",
+    "--tmpfs",
+    `${SANDBOX_HOME}/.cache`,
+    "-e",
+    `HOME=${SANDBOX_HOME}`,
+    ...env,
+    // The bind-mounted worktree (writable — a bind mount is exempt from
+    // `--read-only`) and, when one is named, the persistent pnpm store.
+    "-v",
+    `${resolve4(options.build_root)}:${SANDBOX_WORKDIR}`,
+    ...store,
+    "-w",
+    SANDBOX_WORKDIR,
+    ...entrypoint,
+    options.image,
+    ...options.command ?? []
+  ];
+}
+
 // src/exit_codes.ts
 var EXIT_SUCCESS = 0;
 var EXIT_BUDGET_EXHAUSTED = 2;
@@ -2718,6 +2858,8 @@ export {
   EXIT_CRITIC_ERROR,
   EXIT_INTERRUPTED,
   EXIT_SUCCESS,
+  SANDBOX_NETWORK_NAME,
+  SANDBOX_NETWORK_SUBNET,
   create_renderer,
   exit_code_for_error,
   exit_code_for_status,
@@ -2725,8 +2867,10 @@ export {
   gate,
   initial_state,
   load_config_file,
+  network_run_args,
   resolve_config,
   run_volley,
+  sandbox_run_args,
   status_of,
   verdict_schema
 };