@robmclarty/volley 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 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
+- **A diagram of the loop, drawn from the code.** The README's new "The flow" section shows the real composition: the branch that skips verification once the builder alone crosses the cost cap, the critic's retry-then-tool-less fallback for local models, and the guard that stops the loop. fascicle's `describe.diagram` renders it from `src/flow.ts`, and `pnpm diagram` prints it from a checkout.
+
+### Changed
+- **The trajectory's flow structure includes the builder and the critic.** They now appear as children of `build` and `critique` in the tree a run records at its start, so the fascicle viewer draws both model calls, and the critic's retry and fallback, before the run reaches them. Live output, verdicts, and exit codes are unchanged.
+
+### Internal
+- Built on fascicle 0.12.13. A test holds the `src/flow.ts` header diagram and the README's copy to `describe.diagram`, so neither can drift from the code.
+
 ## v0.5.3 — 2026-09-24
 
 ### Fixed

package/README.md

@@ -88,6 +88,38 @@ workspace filesystem and the critic's feedback. Swap the critic to change what
 the loop optimizes for: `--critic reviewer` (default), `optimizer`,
 `researcher`, or a path to your own system prompt.
 
+### The flow
+
+Under the hood the loop is one [fascicle](https://www.npmjs.com/package/fascicle)
+composition in [`src/flow.ts`](./src/flow.ts), and fascicle's `describe.diagram`
+draws it straight from the code. It shows what the sketch above leaves out: the
+branch that skips verification once the builder alone crosses the cost cap, the
+critic's retry-then-tool-less fallback for local models whose streams die, and
+the guard that decides when the loop stops.
+
+<!-- flow diagram: pnpm diagram -->
+```text
+volley                                loop: one round per iteration, up to max_iterations
+├─ iteration                          sequence
+│  ├─ build                           open the iteration, run the builder, measure the change
+│  │  └─ builder                      model call: one agentic session in the build root
+│  ├─ verify                          branch: did the build alone cross the cost cap?
+│  │  ├─ then  skip_verify            record the check as skipped and call no critic
+│  │  └─ else  sequence
+│  │     ├─ check                     the deterministic gate: checkride, a command, or none
+│  │     └─ critique                  the read-only critic's verdict and feedback
+│  │        └─ critic                 fallback: judge without tools if a local critic's stream keeps dying
+│  │           ├─ retry               one more try after a stream death, local providers only
+│  │           │  └─ critic_tools     model call with read-only workspace tools
+│  │           └─ pipe                mark the verdict degraded
+│  │              └─ critic_toolless  model call judging from the check output and a file list
+│  └─ record                          archive the iteration and rewrite the run summary
+└─ guard  gate                        stop on approval over a green check, the cost cap, or a gate edit
+```
+
+`pnpm diagram` prints the same tree from a checkout. A test holds this copy and
+the one in the `src/flow.ts` header to what the code builds, so neither drifts.
+
 ## Install
 
 Requires Node ≥ 24, pnpm, and the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
@@ -139,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. |
@@ -290,7 +323,7 @@ Providers and their setup:
 Install the peer for your provider in the project running volley (e.g.
 `pnpm add ai-sdk-ollama@^4`); fascicle loads it lazily only when the local
 critic actually runs. The major matters: it must satisfy fascicle's declared
-peer range (`^4` for fascicle 0.12.10, which tracks the AI SDK v7 line; a bare
+peer range (`^4` for fascicle 0.12.13, which tracks the AI SDK v7 line; a bare
 `pnpm add ai-sdk-ollama` installs v4, which is exactly what this major wants).
 The Ollama base URL is the **server root** — `ai-sdk-ollama` adds the `/api`
 prefix itself (volley strips a trailing `/api` from `VOLLEY_OLLAMA_URL` for
@@ -342,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
@@ -485,6 +521,7 @@ pnpm test          # vitest
 pnpm typecheck     # tsc --noEmit
 pnpm check         # checkride — volley dogfoods its own definition of done
 pnpm build         # tsup → dist/
+pnpm diagram       # draw the flow from src/flow.ts with describe.diagram
 ```
 
 Live smoke tests against the real `claude` CLI and real checkride are opt-in:

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;
@@ -1804,6 +1816,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),
@@ -2045,11 +2058,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);
@@ -2546,14 +2564,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
@@ -2569,13 +2591,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.
@@ -2588,9 +2624,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)
   });
@@ -2717,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);
@@ -3381,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);
@@ -3411,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`