@phi-code-admin/phi-code 0.88.0 → 0.90.0

package/extensions/phi/providers/build-loop.ts

@@ -0,0 +1,89 @@
+/**
+ * /build outer loop — the pure decision core that composes the two oracles
+ * (docs/design/plan-debug-build.md): an acceptance RUN and an executable
+ * red-team. It never runs anything itself; given this round's reports it decides
+ * SUCCESS, CONTINUE (hand these real failures to /debug), or PARTIAL (budget
+ * spent — report what still fails honestly, never a confident-wrong PASS).
+ */
+
+import type { AcceptanceReport, CriterionResult } from "./acceptance.js";
+import type { FailingState } from "./debug-contract.js";
+import { type BreakingCase, breakingCasesToFailingStates } from "./redteam.js";
+
+export type BuildStatus = "success" | "continue" | "partial";
+
+export interface BuildDecision {
+	status: BuildStatus;
+	/** Real failures to route to /debug (continue) or to report (partial). */
+	failures: FailingState[];
+	/** Manual criteria that could not be executed — surfaced, never counted green. */
+	unverified: string[];
+	reason: string;
+}
+
+export interface BuildRoundInput {
+	round: number;
+	maxRounds: number;
+	acceptance: AcceptanceReport;
+	breakingCases: BreakingCase[];
+	cwd?: string;
+}
+
+/** A failed acceptance criterion becomes a failing state /debug can reproduce. */
+export function criterionToFailingState(r: CriterionResult, cwd?: string): FailingState {
+	return {
+		reproCommand: r.criterion.check,
+		expected: r.criterion.description,
+		trace: r.result ? `${r.result.command} exited ${r.result.exitCode}` : undefined,
+		cwd,
+	};
+}
+
+/**
+ * Decide one round of the build loop. SUCCESS requires: at least one criterion
+ * was actually checked, none failed, and the red-team found no break. Manual
+ * criteria never count toward success — they are reported as `unverified`.
+ */
+export function decideBuildRound(input: BuildRoundInput): BuildDecision {
+	const failedStates = input.acceptance.failed.map((r) => criterionToFailingState(r, input.cwd));
+	const breakStates = breakingCasesToFailingStates(input.breakingCases, input.cwd);
+	const failures = [...failedStates, ...breakStates];
+	const unverified = input.acceptance.manual.map((r) => r.criterion.description);
+
+	if (failures.length === 0) {
+		if (!input.acceptance.allCheckablePassed) {
+			// Nothing failed, but nothing was executably verified either.
+			return {
+				status: "partial",
+				failures: [],
+				unverified,
+				reason: "no criterion could be executed — nothing verified; add checkable acceptance criteria",
+			};
+		}
+		const note = unverified.length ? ` (${unverified.length} manual criteria still unverified)` : "";
+		return {
+			status: "success",
+			failures: [],
+			unverified,
+			reason: `all checkable acceptance criteria passed and the red-team found no break${note}`,
+		};
+	}
+
+	if (input.round >= input.maxRounds) {
+		return {
+			status: "partial",
+			failures,
+			unverified,
+			reason: `budget exhausted after ${input.maxRounds} round(s); ${failures.length} failure(s) still open`,
+		};
+	}
+
+	return {
+		status: "continue",
+		failures,
+		unverified,
+		reason: `${failures.length} real failure(s) this round → route to /debug (round ${input.round}/${input.maxRounds})`,
+	};
+}
+
+export const DEFAULT_MAX_ROUNDS = 4;

package/extensions/phi/providers/candidate-select.ts

@@ -0,0 +1,112 @@
+/**
+ * Minimality guard — pick the best of several candidate fixes.
+ *
+ * Lesson from the SWE-bench-lite head-to-head: /plan's extra deliberation made
+ * it produce a MORE elaborate (and wrong) fix than a single shot on the missed
+ * instance, while its diff was better-formed (it applied; the baseline's did
+ * not). The winning move is to generate more than one candidate and keep the
+ * SIMPLEST one that actually passes an executable acceptance repro — combining
+ * /plan's well-formed diffs with single-shot's tendency to stay minimal.
+ *
+ * This module is the pure decision core (no I/O): the caller runs each
+ * candidate against the same acceptance repro and reports `passedRepro`; this
+ * picks the winner. "Simplest" = fewest changed source lines in the unified
+ * diff (a robust, language-agnostic proxy for over-engineering).
+ */
+
+export interface FixCandidate {
+	/** Where it came from, for diagnostics: "single-shot", "plan", "plan-fix", ... */
+	source: string;
+	/** Unified diff. */
+	patch: string;
+	/**
+	 * Did this candidate pass the model's own falsify-first acceptance repro
+	 * (the repro that FAILS on the pre-fix code and must PASS after)? Undefined
+	 * when no repro was available to gate on.
+	 */
+	passedRepro?: boolean;
+}
+
+export interface CandidateSelection {
+	chosen: FixCandidate | null;
+	/** Human-readable rationale (surfaced to the user and asserted in tests). */
+	reason: string;
+	/** Changed-source-line count of the chosen patch (0 when none). */
+	chosenSize: number;
+}
+
+/**
+ * Count changed source lines in a unified diff: added/removed lines, excluding
+ * diff/hunk headers (---, +++, @@, diff --git, index) so the number reflects
+ * real edits, not file boilerplate.
+ */
+export function diffChangedLines(patch: string): number {
+	if (!patch) return 0;
+	let n = 0;
+	for (const line of patch.split("\n")) {
+		if (line.startsWith("+++") || line.startsWith("---")) continue;
+		if ((line.startsWith("+") || line.startsWith("-")) && line.length > 0) n++;
+	}
+	return n;
+}
+
+const hasPatch = (c: FixCandidate) => c.patch.trim().length > 0;
+
+/**
+ * Select the best candidate:
+ *  1. Among candidates that PASSED the acceptance repro, pick the smallest diff
+ *     (ties → the earliest in the list, so callers can order by preference).
+ *  2. If none is known to pass but some were never gated (passedRepro undefined),
+ *     pick the smallest non-empty patch among those (best effort).
+ *  3. If a repro existed and every candidate FAILED it, choose nothing — the
+ *     honest outcome is "no candidate is verified", not "ship the least-bad".
+ *  4. No non-empty patches → nothing.
+ */
+export function selectMinimalPassingCandidate(candidates: FixCandidate[]): CandidateSelection {
+	const nonEmpty = candidates.filter(hasPatch);
+	if (nonEmpty.length === 0) {
+		return { chosen: null, reason: "no candidate produced a non-empty patch", chosenSize: 0 };
+	}
+
+	const passed = nonEmpty.filter((c) => c.passedRepro === true);
+	if (passed.length > 0) {
+		const chosen = smallest(passed);
+		const others = passed.filter((c) => c !== chosen);
+		const note = others.length
+			? ` (over ${others.map((c) => `${c.source}:${diffChangedLines(c.patch)}`).join(", ")})`
+			: "";
+		return {
+			chosen,
+			reason: `smallest patch that passes the acceptance repro: ${chosen.source} (${diffChangedLines(chosen.patch)} changed lines)${note}`,
+			chosenSize: diffChangedLines(chosen.patch),
+		};
+	}
+
+	const anyGated = nonEmpty.some((c) => c.passedRepro === true || c.passedRepro === false);
+	if (anyGated) {
+		// A repro existed and nothing passed it — do not pretend a candidate is verified.
+		return { chosen: null, reason: "an acceptance repro existed but no candidate passed it", chosenSize: 0 };
+	}
+
+	// No repro to gate on: fall back to the smallest non-empty patch (best effort).
+	const chosen = smallest(nonEmpty);
+	return {
+		chosen,
+		reason: `no acceptance repro to gate on; smallest non-empty patch: ${chosen.source} (${diffChangedLines(chosen.patch)} changed lines)`,
+		chosenSize: diffChangedLines(chosen.patch),
+	};
+}
+
+/** Smallest by changed-line count; ties keep list order (stable). */
+function smallest(cs: FixCandidate[]): FixCandidate {
+	let best = cs[0];
+	let bestSize = diffChangedLines(best.patch);
+	for (let i = 1; i < cs.length; i++) {
+		const s = diffChangedLines(cs[i].patch);
+		if (s < bestSize) {
+			best = cs[i];
+			bestSize = s;
+		}
+	}
+	return best;
+}

package/extensions/phi/providers/debug-build-commands.ts

@@ -0,0 +1,132 @@
+/**
+ * Instruction builders for the /debug and /build phase pipelines.
+ *
+ * These are PURE text builders (no fs, no Pi) so the exact protocol each phase
+ * agent receives is unit-testable. They encode the contracts from
+ * docs/design/plan-debug-build.md: /debug turns a REAL failure green through
+ * REPRODUCE → LOCALIZE → FIX → VERIFY with execution as the only oracle; /build
+ * adds an execution-grounded verify (run recipe + acceptance + executable
+ * red-team) that routes real failures back to the /debug protocol.
+ */
+
+import type { FailingState } from "./debug-contract.js";
+
+/** Render a failing state as a compact, unambiguous block for an instruction. */
+export function formatFailingState(state: FailingState): string {
+	const lines: string[] = [];
+	if (state.failingTest?.trim()) lines.push(`- Failing test: \`${state.failingTest.trim()}\``);
+	if (state.reproCommand?.trim()) lines.push(`- Repro command: \`${state.reproCommand.trim()}\``);
+	if (state.expected?.trim()) lines.push(`- Expected behaviour: ${state.expected.trim()}`);
+	if (state.trace?.trim()) lines.push(`- Trace / error:\n\`\`\`\n${state.trace.trim()}\n\`\`\``);
+	if (state.cwd?.trim()) lines.push(`- Working directory: \`${state.cwd.trim()}\``);
+	return lines.length ? lines.join("\n") : "- (no structured failing state supplied)";
+}
+
+export interface DebugInstructions {
+	reproduce: string;
+	localize: string;
+	fix: string;
+	verify: string;
+}
+
+const DEBUG_RULES = `
+---
+## /debug operating rules (non-negotiable)
+- **Execution is the only oracle.** No verdict without a real run whose output you paste. Never write FIXED because the code "looks right".
+- **Use the \`sandbox_run\` tool for every oracle run** (reproduction, suite, acceptance). It runs in the project's guaranteed environment and returns the REAL exit code — a PASS means \`sandbox_run\` returned exit 0, nothing less.
+- **No fabricated PASS.** If \`sandbox_run\` reports \`SANDBOX UNAVAILABLE\` (or you otherwise cannot run the reproduction), emit \`BLOCKED: no executable environment\` — do NOT reconstruct a mock and grade your own reconstruction.
+- **Minimal fix wins.** Prefer the smallest change; every added guard/condition is a liability that can hide the bug (an over-clever guard is exactly how these fixes go wrong).
+- **Root cause, not workaround.** No skipped tests, no \`--no-verify\`, no mock that hides the failure.
+- The user does NOT answer during these phases. Act autonomously; do not end with a question.`;
+
+/** The four /debug phase instructions, specialised to the concrete failing state. */
+export function debugPhaseInstructions(state: FailingState): DebugInstructions {
+	const failing = formatFailingState(state);
+	const repro = state.failingTest?.trim() || state.reproCommand?.trim() || "(the reproduction command)";
+
+	return {
+		reproduce:
+			`You are the REPRODUCE agent (phase 1 of /debug). Your only job is to CONFIRM the failure is real.
+
+**The reported failing state:**
+${failing}
+
+**Do exactly this:**
+1. Run the reproduction on the CURRENT, unmodified code with the \`sandbox_run\` tool: \`sandbox_run ${repro}\`.
+2. Paste the exact command and its full output.
+3. Decide from what \`sandbox_run\` returned:
+   - If it FAILS as reported → capture the precise symptom (assertion, exception, exit code) and hand off to LOCALIZE.
+   - If it PASSES → STOP. Write \`BLOCKED: cannot reproduce — passes on current code\` with the run pasted. Do not invent a bug.
+   - If \`sandbox_run\` reports \`SANDBOX UNAVAILABLE\` → STOP. Write \`BLOCKED: no executable environment\`.
+4. Do NOT edit any source yet. This phase only observes.
+5. **Last action:** call \`phase_result\` — \`verdict: PASS\` if it reproduced (proceed to LOCALIZE), or \`verdict: BLOCKED\` with the reason if you stopped.` +
+			DEBUG_RULES,
+
+		localize: `You are the LOCALIZE agent (phase 2 of /debug). Drive from the REAL symptom the previous phase captured.
+
+**The failing state:**
+${failing}
+
+**Do exactly this:**
+1. Read the traceback / error from the reproduction. Follow it to the exact frame.
+2. Read the implicated source and the symbols it touches (grep the nearby/changed identifiers).
+3. Name the fault site precisely — file:line and the wrong assumption. Localization, not more review, is the lever here.
+4. Hand off a crisp fault description; do NOT fix yet.${DEBUG_RULES}`,
+
+		fix:
+			`You are the FIX agent (phase 3 of /debug). Produce the MINIMAL change that addresses the located root cause.
+
+**The failing state:**
+${failing}
+
+**Do exactly this:**
+1. Write the smallest patch that fixes the root cause at the fault site LOCALIZE named.
+2. If two approaches are plausible, prefer the one that adds the least surface (fewest new branches/guards).
+3. Do NOT run the suite to "confirm" here by eye — VERIFY re-runs everything. Just make the change and state precisely what you changed and why it addresses the cause.` +
+			DEBUG_RULES,
+
+		verify: `You are the VERIFY agent (phase 4 of /debug) — the oracle. A green verdict requires TWO real runs.
+
+**The failing state:**
+${failing}
+
+**Do exactly this, pasting every command's output:**
+1. Re-run the reproduction with \`sandbox_run ${repro}\`. It MUST now return exit 0.
+2. Run the existing test suite with \`sandbox_run <test command>\`. It MUST NOT regress.
+3. Verdict (from what \`sandbox_run\` returned, not from inspection):
+   - Both green → \`FIXED\`, and paste the before(fail)/after(pass) reproduction runs and the green suite as evidence.
+   - Reproduction still fails, or the suite regresses → \`BLOCKED\` with the closest diagnostic. Do NOT ship the least-bad patch; a wrong fix is worse than an honest BLOCKED.
+4. Write the final verdict block, then call \`phase_result\` with \`verdict: PASS\` (FIXED) or \`verdict: BLOCKED\`, plus a one-line handoff:
+\`\`\`
+VERDICT: FIXED | BLOCKED
+Evidence: reproBefore=fail reproAfter=pass suite=green|skipped
+Reason: <only when BLOCKED>
+\`\`\`${DEBUG_RULES}`,
+	};
+}
+
+/**
+ * The /build execution-grounded verify phase: run the recipe, check acceptance,
+ * red-team the boundary the change touched, and route real failures to /debug.
+ */
+export function buildVerifyInstruction(spec: string): string {
+	return `You are the BUILD-VERIFY agent — the execution oracle for /build. The code has been written; now PROVE it runs and meets the spec, or report honestly what still fails.
+
+**Original spec:** ${spec}
+
+**Every run below goes through the \`sandbox_run\` tool** (the project's guaranteed environment). If it reports \`SANDBOX UNAVAILABLE\`, do not fabricate results — mark the affected criteria ❔ and say the environment was unavailable.
+
+**Do exactly this, pasting every command's output:**
+1. **Run recipe.** From the brief's \`## Run Recipe\` (or package.json / Makefile / Dockerfile), build and start the app via \`sandbox_run\`. Distinguish a real failure from a stale launch recipe.
+2. **Acceptance.** For each acceptance criterion derived from the SPEC (not the code), \`sandbox_run\` a concrete check that exits 0 iff it holds. Mark each ✅ (sandbox_run returned 0), ❌ (non-zero), or ❔ (could not be executed — NEVER count ❔ as passing).
+3. **Executable red-team.** Attack the specific input regimes the change touched (empty, null, boundary, wrong-type, and buffered-vs-streaming / malformed / auth as relevant). Each attack must be a RUNNABLE test \`sandbox_run\` can execute and that goes RED if it breaks the code — an opinion is not a finding.
+4. **Route real failures.** For every ❌ criterion and every red-team break, treat it as a concrete failing state (failing test / repro command / expected) and fix it with the /debug protocol: REPRODUCE → LOCALIZE → minimal FIX → VERIFY (re-run the reproduction AND the suite).
+5. **Honest verdict.** When all checkable criteria pass and the red-team finds no break, write \`BUILD: SUCCESS\`. If rounds/budget run out with failures open, write \`BUILD: PARTIAL\` and LIST exactly which criteria still fail — never a confident-wrong SUCCESS. Then call \`phase_result\` with \`verdict: PASS\` (SUCCESS) or \`verdict: FAIL\`/\`BLOCKED\` and the handoff.
+\`\`\`
+VERDICT: PASS | FAIL | BLOCKED
+Handoff:
+State: <what runs and is proven by a real run>
+Open Risks: <criteria still ❔ unverified or ❌ failing>
+Next: <the single most important remaining action>
+\`\`\`${DEBUG_RULES}`;
+}

package/extensions/phi/providers/debug-contract.ts

@@ -0,0 +1,131 @@
+/**
+ * /debug contract — turn a REAL failing state green, or honestly say BLOCKED.
+ *
+ * The whole point (docs/design/plan-debug-build.md): /debug never guesses what
+ * is wrong. It is given a reproducible failure, confirms it fails on the current
+ * code, fixes it, and VERIFIES by re-running — repro passes AND the existing
+ * suite does not regress — selecting the minimal passing candidate. There is no
+ * path to FIXED without execution.
+ */
+
+import { type FixCandidate, selectMinimalPassingCandidate } from "./candidate-select.js";
+import { type CommandResult, passed } from "./execution.js";
+
+/** A concrete, reproducible failing state — /debug's input. */
+export interface FailingState {
+	/** A test command, e.g. "pytest tests/x.py::test_y". */
+	failingTest?: string;
+	/** A stack trace / error output pasted from a real run. */
+	trace?: string;
+	/** A command that exhibits the bug. */
+	reproCommand?: string;
+	/** What should happen instead (from the user/spec). */
+	expected?: string;
+	cwd?: string;
+}
+
+/** How to run the existing suite, to catch regressions. */
+export interface SuiteRecipe {
+	test?: string;
+}
+
+export type DebugVerdict = "FIXED" | "BLOCKED";
+
+export interface DebugOutcome {
+	verdict: DebugVerdict;
+	patch?: string;
+	evidence?: { reproBefore: "fail"; reproAfter: "pass"; suite: "green" | "skipped" };
+	reason?: string;
+}
+
+/** True when the input actually gives something runnable to reproduce. */
+export function hasReproducibleFailure(state: FailingState): boolean {
+	return Boolean(state.failingTest?.trim() || state.reproCommand?.trim());
+}
+
+/** The command that reproduces the failure (test preferred over generic repro). */
+export function reproCommand(state: FailingState): string | undefined {
+	return state.failingTest?.trim() || state.reproCommand?.trim() || undefined;
+}
+
+export type ReproduceDecision = { action: "proceed"; symptom: string } | { action: "blocked"; reason: string };
+
+/**
+ * REPRODUCE gate: the failing state must FAIL on the current code. If there is
+ * nothing runnable, or it already passes, /debug stops — it will not fabricate a
+ * bug or a repro from imagination.
+ */
+export function decideReproduce(state: FailingState, runOnCurrentCode: CommandResult | null): ReproduceDecision {
+	if (!hasReproducibleFailure(state)) {
+		return { action: "blocked", reason: "no reproducible failing state (need a failing test or a repro command)" };
+	}
+	if (runOnCurrentCode === null) {
+		return { action: "blocked", reason: "could not run the reproduction (no executable environment)" };
+	}
+	if (passed(runOnCurrentCode)) {
+		return { action: "blocked", reason: "the reported failure does not reproduce — it passes on the current code" };
+	}
+	return { action: "proceed", symptom: `${runOnCurrentCode.command} exited ${runOnCurrentCode.exitCode}` };
+}
+
+/** A fix candidate paired with its verification runs. */
+export interface VerifiedCandidate {
+	source: string;
+	patch: string;
+	/** The reproduction re-run WITH this candidate applied. */
+	reproAfter: CommandResult | null;
+	/** The existing suite re-run WITH this candidate applied (null = no suite). */
+	suite: CommandResult | null;
+}
+
+/**
+ * VERIFY: a candidate is accepted only if the repro now PASSES and the suite (if
+ * any) is green. Among accepted candidates, pick the minimal diff. If none is
+ * accepted, BLOCKED — never ship the least-bad.
+ */
+export function decideVerify(candidates: VerifiedCandidate[], hasSuite: boolean): DebugOutcome {
+	const fixCandidates: FixCandidate[] = candidates.map((c) => {
+		const reproOk = c.reproAfter !== null && passed(c.reproAfter);
+		const suiteOk = !hasSuite || (c.suite !== null && passed(c.suite));
+		return { source: c.source, patch: c.patch, passedRepro: reproOk && suiteOk };
+	});
+	const selection = selectMinimalPassingCandidate(fixCandidates);
+	if (!selection.chosen) {
+		return {
+			verdict: "BLOCKED",
+			reason: fixCandidates.some((c) => c.patch.trim())
+				? "no candidate makes the reproduction pass without regressing the suite"
+				: "no candidate produced a patch",
+		};
+	}
+	return {
+		verdict: "FIXED",
+		patch: selection.chosen.patch,
+		evidence: { reproBefore: "fail", reproAfter: "pass", suite: hasSuite ? "green" : "skipped" },
+		reason: selection.reason,
+	};
+}
+
+/** Parse a /debug argument string / structured input into a FailingState. */
+export function parseFailingState(arg: string, structured?: Partial<FailingState>): FailingState {
+	const a = arg.trim();
+	const state: FailingState = { ...structured };
+	// Heuristic: a bare test-runner invocation is a failing test; anything else
+	// with a command shape is a repro command; free prose is `expected`.
+	if (!state.failingTest && !state.reproCommand && a) {
+		// Test-runner invocations → a failing test. Bare `node x.js` / `python x.py`
+		// / `./x` are script runs → a repro command. Free prose → expected.
+		if (
+			/^(pytest|jest|vitest|mocha|go test|cargo test|npm (run )?test|npx (vitest|jest|mocha|playwright)|python -m pytest)\b/.test(
+				a,
+			)
+		) {
+			state.failingTest = a;
+		} else if (/^(node|python|python3|\.\/|bash|sh|deno|bun|ruby|php)\b|[|&;><]/.test(a)) {
+			state.reproCommand = a;
+		} else {
+			state.expected = state.expected || a;
+		}
+	}
+	return state;
+}

package/extensions/phi/providers/execution.ts

@@ -0,0 +1,107 @@
+/**
+ * Execution oracle — run real commands and report objective results.
+ *
+ * This is the ground truth the /plan → /debug → /build design turns on: an
+ * accept/reject decision must come from RUNNING code, not from a model reviewing
+ * its own output (see docs/design/plan-debug-build.md). Everything here is thin
+ * and deterministic so the result interpretation can be unit-tested; the spawn
+ * itself is exercised with trivial real commands.
+ */
+
+import { spawnSync } from "node:child_process";
+
+const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
+
+export interface CommandResult {
+	command: string;
+	exitCode: number | null;
+	stdout: string;
+	stderr: string;
+	durationMs: number;
+	timedOut: boolean;
+}
+
+/** A command passed iff it exited 0 and did not time out. */
+export function passed(result: CommandResult): boolean {
+	return result.exitCode === 0 && !result.timedOut;
+}
+
+/** One-line summary for a phase report / handoff. */
+export function summarize(result: CommandResult): string {
+	if (result.timedOut) return `\`${result.command}\` → TIMED OUT after ${Math.round(result.durationMs / 1000)}s`;
+	return `\`${result.command}\` → exit ${result.exitCode ?? "?"} (${Math.round(result.durationMs / 1000)}s)`;
+}
+
+/** Last N lines of the combined output — what a model needs to see to react. */
+export function tail(result: CommandResult, lines = 40): string {
+	const combined = `${result.stdout}\n${result.stderr}`.trimEnd();
+	const all = combined.split("\n");
+	return all.slice(Math.max(0, all.length - lines)).join("\n");
+}
+
+export interface RunOptions {
+	cwd?: string;
+	timeoutMs?: number;
+	env?: NodeJS.ProcessEnv;
+}
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Run a shell command and capture its result. Never throws — a non-zero exit,
+ * a spawn error, or a timeout all come back as a CommandResult so callers make
+ * decisions from data, not exceptions.
+ */
+export function runCommand(command: string, options: RunOptions = {}): CommandResult {
+	const start = Date.now();
+	const res = spawnSync(command, {
+		cwd: options.cwd,
+		timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		env: options.env ?? process.env,
+		shell: true,
+		encoding: "utf-8",
+		maxBuffer: DEFAULT_MAX_BUFFER,
+	});
+	const durationMs = Date.now() - start;
+	// spawnSync sets error with code "ETIMEDOUT" on timeout, and signal SIGTERM.
+	const timedOut = res.error !== undefined && (res.error as NodeJS.ErrnoException).code === "ETIMEDOUT";
+	const spawnFailed = res.error !== undefined && !timedOut;
+	return {
+		command,
+		exitCode: spawnFailed ? null : (res.status ?? (timedOut ? null : null)),
+		stdout: res.stdout ?? "",
+		stderr: spawnFailed ? `${(res.error as Error).message}\n${res.stderr ?? ""}` : (res.stderr ?? ""),
+		durationMs,
+		timedOut,
+	};
+}
+
+/**
+ * Run a program by ARGV with NO shell. This is what the Docker sandbox uses:
+ * passing `docker` + its arguments directly avoids shell quoting and — on
+ * Windows Git Bash — the MSYS path mangling that corrupts `-v C:\x:/work` and
+ * `//var/run/docker.sock`. `label` is the human-readable command echoed back in
+ * the result (the argv itself is not a shell string). Never throws.
+ */
+export function runArgv(file: string, args: string[], options: RunOptions & { label?: string } = {}): CommandResult {
+	const start = Date.now();
+	const res = spawnSync(file, args, {
+		cwd: options.cwd,
+		timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		env: options.env ?? process.env,
+		shell: false,
+		encoding: "utf-8",
+		maxBuffer: DEFAULT_MAX_BUFFER,
+	});
+	const durationMs = Date.now() - start;
+	const timedOut = res.error !== undefined && (res.error as NodeJS.ErrnoException).code === "ETIMEDOUT";
+	const spawnFailed = res.error !== undefined && !timedOut;
+	return {
+		command: options.label ?? `${file} ${args.join(" ")}`.trim(),
+		exitCode: spawnFailed ? null : (res.status ?? null),
+		stdout: res.stdout ?? "",
+		stderr: spawnFailed ? `${(res.error as Error).message}\n${res.stderr ?? ""}` : (res.stderr ?? ""),
+		durationMs,
+		timedOut,
+	};
+}