@robmclarty/volley 0.5.4 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## v0.6.1 — 2026-10-14
+
+### Fixed
+- **`--worktree` now isolates a Claude builder.** The `claude` session started in the workspace instead of the worktree, so under `--worktree` a `claude_cli` builder edited your checkout while the check, the checkpoints, and the change report the critic reads all looked at the untouched worktree. Claude sessions now start in the worktree; `.volley/` run state stays in the workspace as before, and local-model builders, whose tools were already rooted in the worktree, are unaffected.
+
+### Internal
+- An integration test runs the real engine against a stand-in `claude` binary and checks that the builder's write lands on the run branch, not in the workspace.
+
+## v0.6.0 — 2026-09-27
+
+### Added
+- **The container spec is exported from the package root.** `sandbox_run_args`, `network_run_args`, `SANDBOX_NETWORK_NAME`, `SANDBOX_NETWORK_SUBNET`, and the `SandboxNetwork` type are now public, so a harness that launches volley's container renders volley's own hardened `docker run` flags instead of a copy that drifts from them. `sandbox_run_args` gains `labels` (one `--label KEY=VALUE` each, so a caller can find and reap its containers), and `store_volume` is now optional: leave it out and no pnpm store is mounted.
+- **`--run-id <id>` names a run.** The id names the run's `.volley/` state and its `volley/<id>` branch in place of a fresh UUID, so a harness that owns the id finds the run in both. Ids are limited to letters, digits, `-`, and `_`, starting with a letter or digit; anything else is a config error before any spend, and the CLI refuses a bare-number id rather than silently dropping its leading zeros.
+
+### Fixed
+- **Runs started from the SDK run their check.** `resolve_config` now resolves the check the way the CLI always did. It used to return `'none'` for every config, so an embedded run ran no check even with `check: 'auto'` in a checkride workspace or with a command check.
+
+### Internal
+- The version skill bumps `package.json` after writing the changelog, so pnpm's clean-tree check no longer blocks it.
+
 ## v0.5.4 — 2026-09-25
 
 ### Added

package/README.md

@@ -171,6 +171,7 @@ volley matrix --builders <models> --critics <models> --config <path>
 | `--gate-paths` | (built-in list) | Comma-separated globs naming the gate — tests, fixtures, check config. Replaces the defaults; see [What the builder changed](#what-the-builder-changed). |
 | `--fail-on-gate-edit` | off | Halt the run (exit 8) if the builder edits a gate path, instead of reporting it. |
 | `--sandbox-image` | `volley-sandbox:latest` | Container image for the local-builder sandbox. Or `VOLLEY_SANDBOX_IMAGE`. |
+| `--run-id` | a fresh UUID | The run's id, naming its `.volley/` state and its `volley/<id>` branch, so a harness that owns the id finds it in both. Letters, digits, `-`, and `_`, starting with a letter or digit. |
 | `--dry-run` | off | Validate config, run `checkride doctor` and (for a local critic) the critic-seat canary, then exit. |
 | `--config` | — | TypeScript config file (`VolleyConfig` default export). CLI flags override. |
 | `--json` | off | Machine mode: one summary JSON document on stdout. |
@@ -374,7 +375,10 @@ operator launches volley there with `docker run <hardened flags>
 volley-sandbox:latest volley …`, which sets `VOLLEY_CONTAINED=1` (baked into the
 image; volley detects containment, it does not start the container itself). The
 container gives default-deny network egress with a host-gateway allowlist; the
-hardened `docker run` spec lives in `src/sandbox.ts`, and `--sandbox-image` /
+hardened `docker run` spec lives in `src/sandbox.ts` and is exported
+(`sandbox_run_args`, `network_run_args`, and the bridge's
+`SANDBOX_NETWORK_NAME` and `SANDBOX_NETWORK_SUBNET`) so a harness that launches
+the container renders the same flags rather than a copy, and `--sandbox-image` /
 `VOLLEY_SANDBOX_IMAGE` overrides the default `volley-sandbox:latest`. Inside the
 container, `claude_cli`'s subscription/OAuth token does not survive — it is
 mangled crossing the boundary — so a *contained* Claude role must drive by API

package/dist/cli.js

@@ -7,7 +7,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 import { cac } from "cac";
 
 // 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";
@@ -141,6 +141,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" });
@@ -200,17 +225,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;
@@ -228,7 +253,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()) {
@@ -246,7 +271,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}`
     );
@@ -290,6 +315,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;
@@ -355,11 +390,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;
@@ -373,14 +408,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,
@@ -406,31 +443,6 @@ function resolve_config(raw, options = {}) {
   };
 }
 
-// src/check/detect.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join } from "path";
-function package_check_script_is_checkride(workspace) {
-  const path = join(workspace, "package.json");
-  if (!existsSync2(path)) return false;
-  try {
-    const pkg = JSON.parse(readFileSync2(path, "utf8"));
-    const script = pkg.scripts?.["check"];
-    return typeof script === "string" && /(^|\s)checkride(\s|$)/.test(script);
-  } catch {
-    return false;
-  }
-}
-function checkride_detected(workspace) {
-  return existsSync2(join(workspace, "checkride.config.json")) || package_check_script_is_checkride(workspace) || existsSync2(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/exit_codes.ts
 var EXIT_SUCCESS = 0;
 var EXIT_BUDGET_EXHAUSTED = 2;
@@ -2671,7 +2683,7 @@ async function run_volley(config, deps, resume_from = null) {
 async function run_loop(config, deps, resume_from, bash_executor, baseline) {
   const { renderer } = deps;
   const engine = deps.engine ?? create_volley_engine({
-    workspace: config.workspace,
+    workspace: build_root(config.workspace, config.worktree),
     builder_provider: config.builder_provider,
     critic_provider: config.critic_provider
   });
@@ -2744,7 +2756,6 @@ function combo_config(base, combo) {
 }
 var default_run_combo = async (base, combo, renderer) => {
   const config = resolve_config(combo_config(base, combo));
-  config.check_resolved = resolve_check_runner(config.check, config.workspace);
   try {
     const result = await run_volley(config, { renderer });
     return build_run_summary(config, result);
@@ -3408,11 +3419,16 @@ function report_error(err) {
 async function main(argv) {
   const cli = cac("volley");
   let exit_code = EXIT_SUCCESS;
-  cli.command("", "Run the builder/critic loop").option("--prompt <prompt>", "Task prompt (string or @file)").option("--workspace <path>", "Workspace directory (must exist and be writable)").option("--criteria <criteria>", "Acceptance criteria (string or @file)").option("--check <check>", `auto | none | shell command (default: ${DEFAULT_CHECK})`).option("--builder-model <model>", "Builder model").option("--builder-provider <name>", "claude_cli | ollama | lmstudio (default: claude_cli)").option("--builder-max-steps <n>", "Local builder tool-loop step cap per iteration (default: 50)").option("--allow-unsandboxed-builder", "Permit a local builder to run without a sandbox (real host bash + write)").option("--critic-model <model>", "Critic model").option("--critic-provider <name>", "claude_cli | ollama | lmstudio (default: claude_cli)").option("--builder-permission-mode <mode>", "acceptEdits | bypassPermissions").option("--critic <critic>", "reviewer | optimizer | researcher | path to prompt file").option("--max-iterations <n>", "Iteration cap").option("--max-cost-usd <usd>", "Hard USD ceiling, enforced in the loop guard").option("--git", "Auto-commit after each phase (workspace must be a git repo)").option("--worktree", "Isolate the builder run in a per-run git worktree (workspace must be a git repo)").option("--discard-worktree", "Throw a --worktree run's effects away at teardown instead of keeping them on the run branch").option("--gate-paths <globs>", "Comma-separated globs naming the gate (tests, fixtures, check config); replaces the defaults").option("--fail-on-gate-edit", "Halt the run if the builder edits a gate path (exit 8) instead of reporting it").option("--sandbox-image <tag>", `Container image for the local-builder sandbox (default: ${DEFAULT_SANDBOX_IMAGE})`).option("--dry-run", "Validate config (and checkride doctor) without running").option("--config <path>", "TypeScript config file exporting a VolleyConfig").option("--json", "Machine mode: final summary JSON on stdout, no streaming").option("--verbose", "Show full tool inputs/outputs (truncated at 4000 chars)").option("--quiet", "Only phase transitions, cost updates, and the final summary").option("--no-thinking", "Hide reasoning chunks (still recorded in the trajectory)").action(async (flags) => {
+  cli.command("", "Run the builder/critic loop").option("--prompt <prompt>", "Task prompt (string or @file)").option("--workspace <path>", "Workspace directory (must exist and be writable)").option("--criteria <criteria>", "Acceptance criteria (string or @file)").option("--check <check>", `auto | none | shell command (default: ${DEFAULT_CHECK})`).option("--builder-model <model>", "Builder model").option("--builder-provider <name>", "claude_cli | ollama | lmstudio (default: claude_cli)").option("--builder-max-steps <n>", "Local builder tool-loop step cap per iteration (default: 50)").option("--allow-unsandboxed-builder", "Permit a local builder to run without a sandbox (real host bash + write)").option("--critic-model <model>", "Critic model").option("--critic-provider <name>", "claude_cli | ollama | lmstudio (default: claude_cli)").option("--builder-permission-mode <mode>", "acceptEdits | bypassPermissions").option("--critic <critic>", "reviewer | optimizer | researcher | path to prompt file").option("--max-iterations <n>", "Iteration cap").option("--max-cost-usd <usd>", "Hard USD ceiling, enforced in the loop guard").option("--git", "Auto-commit after each phase (workspace must be a git repo)").option("--worktree", "Isolate the builder run in a per-run git worktree (workspace must be a git repo)").option("--discard-worktree", "Throw a --worktree run's effects away at teardown instead of keeping them on the run branch").option("--gate-paths <globs>", "Comma-separated globs naming the gate (tests, fixtures, check config); replaces the defaults").option("--fail-on-gate-edit", "Halt the run if the builder edits a gate path (exit 8) instead of reporting it").option("--sandbox-image <tag>", `Container image for the local-builder sandbox (default: ${DEFAULT_SANDBOX_IMAGE})`).option("--run-id <id>", "The run's id, naming its volley/<id> branch (default: a fresh UUID)").option("--dry-run", "Validate config (and checkride doctor) without running").option("--config <path>", "TypeScript config file exporting a VolleyConfig").option("--json", "Machine mode: final summary JSON on stdout, no streaming").option("--verbose", "Show full tool inputs/outputs (truncated at 4000 chars)").option("--quiet", "Only phase transitions, cost updates, and the final summary").option("--no-thinking", "Hide reasoning chunks (still recorded in the trajectory)").action(async (flags) => {
     const base = flags.config !== void 0 ? await load_config_file(flags.config) : {};
     const merged = merge_flags(base, flags);
-    const config = resolve_config(merged);
-    config.check_resolved = resolve_check_runner(config.check, config.workspace);
+    if (typeof flags.runId === "number") {
+      throw config_error(`--run-id must not be a bare number (read as ${String(flags.runId)})`);
+    }
+    const config = resolve_config(
+      merged,
+      flags.runId !== void 0 ? { run_id: flags.runId } : {}
+    );
     const renderer = make_renderer(config);
     warn_api_key_meter(renderer);
     warn_unsandboxed_builder(config, renderer);
@@ -3438,7 +3454,6 @@ async function main(argv) {
       run_id: resume.run_id,
       started_at: resume.started_at
     });
-    config.check_resolved = resolve_check_runner(config.check, config.workspace);
     if (resume.iterations_completed >= config.max_iterations) {
       throw config_error(
         `run already completed ${String(resume.iterations_completed)} of ${String(config.max_iterations)} iterations`