@gethmy/harness 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/harness",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Execution motor for Harmony playbook stages. Runs exactly one stage per invocation: worktree, role-separated subagents, held oracle, gate evidence. It never routes, never judges, never pushes.",
   "type": "module",
   "main": "dist/index.js",

package/src/exec-types.ts

@@ -95,9 +95,73 @@ export interface VerificationConfig {
      * report a timeout as a test failure.
      */
     testTimeout: number;
+    /**
+     * Container image for the verification steps (#1036). Empty — the default —
+     * runs them in the daemon process as before.
+     *
+     * `runBuild` / `runTests` / `runFormatFix` / `runLint` execute
+     * `bun run <script>` out of the WORKTREE'S OWN `package.json`, which a
+     * contained implement run is allowed to rewrite (the worktree is inside
+     * `sandbox.filesystem.allowWrite` by design). #988 gave those spawns
+     * `containedEnv()`, which removes the secret-shaped variables and was
+     * stated there as a reduction and not a fix: the command still ran as the
+     * operator and could read `~/.ssh` and `~/.harmony-mcp/config.json` off
+     * disk. Setting this moves them into `repair-sandbox.ts`'s container, where
+     * the only mount is the worktree and there is no network.
+     *
+     * **Opt-in on purpose, unlike #988's own containment.** That one could ship
+     * on by default because the SDK sandbox is inside the CLI. This one needs a
+     * reachable Docker AND an image carrying the repo's toolchain, so a default
+     * would stop verification dead on every host that has neither. There is
+     * deliberately no guessed image, for the reason `types.ts` already records
+     * for the repair path: a container that cannot build anything reports every
+     * run as unverified.
+     *
+     * The image must carry the toolchain — the container has no network, so
+     * nothing installs at verification time. Dependencies are already present:
+     * `worktree.ts` installs them at worktree creation with `--ignore-scripts`.
+     * Point this at whatever your CI uses.
+     *
+     * Does NOT cover the two `dev` servers (`runDeepReview` and the review
+     * worker's). Those are probed over HTTP from the daemon, so a no-network
+     * container is unreachable by construction; they remain in
+     * `run-containment.ts`'s residual list.
+     */
+    sandboxImage: string;
   };
 }
 
+/**
+ * A configured verification container (#1036), or `undefined` for host
+ * execution. Resolved once by the caller from {@link VerificationConfig} so the
+ * four steps need no config import and stay unit-testable.
+ */
+export interface VerificationSandbox {
+  /** Image carrying the repo's toolchain. Empty means "not configured". */
+  image: string;
+}
+
+/**
+ * Head-room added to a step's own timeout when it runs in a container (#1036).
+ *
+ * There is deliberately NO separate sandbox timeout knob. Each step already
+ * carries the cap its operator chose — `verification.timeout` for build, lint
+ * and format, `verification.testTimeout` for the suite, and those two are
+ * separate precisely because a real suite outruns a build. A single
+ * container-wide cap would silently replace all four: with the values this repo
+ * ships, turning an image on would have taken build and lint from 2 minutes to
+ * 10, and would have ignored a `testTimeout` an operator had narrowed for a
+ * fast suite. Switching on containment must not change what any other setting
+ * means.
+ *
+ * So the step's own timeout wins, and this covers only what the container adds
+ * on top: image resolution and process start. Measured at ~5.1 s on macOS /
+ * Docker Desktop with a warm image; 60 s is that with an order of magnitude of
+ * head-room for a slower host or a cold layer, and it is not a budget for the
+ * command, which has already been capped by the time it is added.
+ */
+export const SANDBOX_STARTUP_GRACE_MS = 60_000;
+
 /** The slice of the daemon's config that the git helpers actually read. */
 export interface WorktreeConfig {
   worktree: VerificationConfig["worktree"];

package/src/gate-collectors.ts

@@ -46,6 +46,7 @@ import {
   CommandMetricCollector,
   type CommandMetricDeps,
 } from "./command-metric.js";
+import type { VerificationSandbox } from "./exec-types.js";
 import { log } from "./log.js";
 import type { OracleDeps } from "./oracle.js";
 import { OracleCollector, OracleRedCollector } from "./oracle-collector.js";
@@ -152,10 +153,25 @@ export interface BuildGreenDeps {
   worktreePath: string;
   buildTimeout: number;
   lintTimeout: number;
+  /**
+   * Verification container (#1036). Passed straight through to `runBuild` /
+   * `runLint`, so the gate's build runs wherever the daemon's own verification
+   * runs — a gate that ran the worktree's scripts in this process while
+   * `runVerification` contained them would be the hole under a different name.
+   */
+  sandbox?: VerificationSandbox;
   /** Inject for tests; defaults to verification.ts `runBuild`. Returns error lines. */
-  runBuild?: (worktreePath: string, timeout: number) => string[];
+  runBuild?: (
+    worktreePath: string,
+    timeout: number,
+    sandbox?: VerificationSandbox,
+  ) => string[] | Promise<string[]>;
   /** Inject for tests; defaults to verification.ts `runLint`. Returns warning lines. */
-  runLint?: (worktreePath: string, timeout: number) => string[];
+  runLint?: (
+    worktreePath: string,
+    timeout: number,
+    sandbox?: VerificationSandbox,
+  ) => string[] | Promise<string[]>;
 }
 
 /**
@@ -192,8 +208,18 @@ export class BuildGreenCollector implements GateEvidenceCollector {
   async collect(_context: GateEvidenceContext): Promise<GateEvidence> {
     const doBuild = this.deps.runBuild ?? runBuild;
     const doLint = this.deps.runLint ?? runLint;
-    const buildErrors = doBuild(this.deps.worktreePath, this.deps.buildTimeout);
-    const lintWarnings = doLint(this.deps.worktreePath, this.deps.lintTimeout);
+    // Awaited: both are async since #1036, and an injected test double may
+    // still be sync — `await` accepts either.
+    const buildErrors = await doBuild(
+      this.deps.worktreePath,
+      this.deps.buildTimeout,
+      this.deps.sandbox,
+    );
+    const lintWarnings = await doLint(
+      this.deps.worktreePath,
+      this.deps.lintTimeout,
+      this.deps.sandbox,
+    );
     const buildPassed = buildErrors.length === 0;
     const lintPassed = lintWarnings.length === 0;
     // Match verification.ts: only a failing BUILD makes the gate red. Lint

package/src/run-containment.ts

@@ -78,24 +78,44 @@
  * was found by a review round rather than by reading the code, and a residual
  * nobody wrote down is indistinguishable from one nobody saw.
  *
- *  - **Everything resolved through `spawnRunArgs` runs the run's own
- *    `package.json` scripts.** Six call sites, not four: `runBuild`,
- *    `runTests`, `runFormatFix` and `runLint` (`verification.ts`), plus the two
- *    `dev` servers — `runDeepReview` (`verification.ts`) and the review
- *    worker's own (`review-worker.ts`). Each executes `bun run <script>` from
- *    the worktree, which the run may rewrite, in the DAEMON process and outside
- *    the sandbox with network. All six now carry `containedEnv()`, so the
- *    secret-shaped variables are gone; the command itself is still the run's to
- *    choose. Closing that means running the repo's build somewhere the
- *    operator's credentials are not; that is `repair-sandbox.ts`'s problem shape
- *    and its own piece of work.
- *
- *    The count is in this bullet on purpose. The first version of this list
- *    named the four verification steps and stopped, and both dev servers then
- *    shipped with the daemon's whole environment while the changelog told users
- *    these commands run "without your credentials". `spawn-run-containment.test.ts`
- *    scans for the property instead of trusting this prose, because the residual
- *    is a completeness claim over CALL SITES and a hand-list has already lost it.
+ *  - **The two `dev` servers, plus the standalone harness CLI.** #1036 closed
+ *    the four verification steps AND the `build_green` gate collector, which
+ *    re-runs the same two scripts: `runBuild`, `runTests`, `runFormatFix` and `runLint`
+ *    now run inside `repair-sandbox.ts`'s container when
+ *    `verification.sandboxImage` is set — worktree the only mount, no network,
+ *    no host fallback. What is left of this bullet is `runDeepReview`'s dev
+ *    server and the review worker's own. Both are the same `spawnRunArgs`
+ *    shape, and both are **probed over HTTP from the daemon**, so
+ *    `--network=none` makes them unreachable by construction: containing them
+ *    needs a different answer, not the same one applied twice. They keep
+ *    `containedEnv()`, so the secret-shaped environment is gone; the command is
+ *    still the run's to choose and still executes in the daemon process.
+ *
+ *    The containment for the four is **opt-in**, so on a host with no
+ *    `sandboxImage` all six remain as described above. That is a deliberate
+ *    asymmetry with this module's own containment, which defaults on: the SDK
+ *    sandbox is inside the CLI, whereas a container needs a reachable Docker
+ *    and an image carrying the repo's toolchain.
+ *
+ *    `packages/harmony-harness/src/cli.ts` builds the same collector and passes
+ *    no image, because the motor holds no operator config of its own — there is
+ *    nothing for it to read. That path is driven by a person running the CLI
+ *    against their own checkout rather than by board text, so it is a different
+ *    threat model, but it is named here rather than left to be rediscovered.
+ *
+ *    The count is in this bullet on purpose, and it has now been wrong twice.
+ *    The first version named the four verification steps and stopped, and both
+ *    dev servers then shipped with the daemon's whole environment while the
+ *    changelog told users these commands run "without your credentials". The
+ *    second version — #1036's own — said "the two dev servers" while the
+ *    `build_green` gate ran the worktree's script on the host for any operator
+ *    who had set an image precisely to stop that. Both were caught by a reader,
+ *    not by a gate.
+ *    `spawn-run-containment.test.ts` scans for the environment property instead
+ *    of trusting this prose, and `verification-sandbox.test.ts` asserts that a
+ *    configured image takes the four out of this process entirely — because the
+ *    residual is a completeness claim over CALL SITES and a hand-list has
+ *    already lost it once.
  *  - **The MCP surface.** The sandbox governs commands. MCP stdio servers are
  *    hosted by the CLI and are not sandboxed, so `mcp__harmony__*` is bounded by
  *    the tool allow-list and the daemon-owned denials (#525/#576), not by this.

package/src/verification.ts

@@ -1,6 +1,10 @@
 import { type ChildProcess, execFileSync, spawn } from "node:child_process";
 import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
-import type { VerificationConfig } from "./exec-types.js";
+import {
+  SANDBOX_STARTUP_GRACE_MS,
+  type VerificationConfig,
+  type VerificationSandbox,
+} from "./exec-types.js";
 import { log } from "./log.js";
 import { spawnRunArgs } from "./pm.js";
 import {
@@ -10,6 +14,7 @@ import {
   supportsDevServer,
   testCommand,
 } from "./project-type.js";
+import { runInSandbox, sandboxAvailable } from "./repair-sandbox.js";
 import { findDeletedTestFiles } from "./revert-guard.js";
 import {
   containedEnv,
@@ -63,6 +68,11 @@ export async function runVerification(
     revertWarnings: [],
   };
 
+  // Resolved once (#1036). Undefined unless the operator configured an image,
+  // in which case the four script-resolved steps run in a container instead of
+  // in this process. The two dev servers below are deliberately not passed it.
+  const sandbox = verificationSandbox(config);
+
   if (config.verification.revertGuard) {
     log.info(TAG, `[worker:${workerId}] Checking for reverted merged work...`);
     const deletedTests = findDeletedTestFiles(
@@ -89,7 +99,11 @@ export async function runVerification(
 
   if (config.verification.build) {
     log.info(TAG, `[worker:${workerId}] Running build...`);
-    result.buildErrors = runBuild(worktreePath, config.verification.timeout);
+    result.buildErrors = await runBuild(
+      worktreePath,
+      config.verification.timeout,
+      sandbox,
+    );
     if (result.buildErrors.length > 0) {
       log.warn(
         TAG,
@@ -107,9 +121,10 @@ export async function runVerification(
   // still gates the branch.
   if (config.verification.test && result.buildErrors.length === 0) {
     log.info(TAG, `[worker:${workerId}] Running tests...`);
-    result.testFailures = runTests(
+    result.testFailures = await runTests(
       worktreePath,
       config.verification.testTimeout,
+      sandbox,
     );
     if (result.testFailures.length > 0) {
       log.warn(
@@ -125,7 +140,11 @@ export async function runVerification(
 
   if (config.verification.lint) {
     log.info(TAG, `[worker:${workerId}] Running lint...`);
-    result.lintWarnings = runLint(worktreePath, config.verification.timeout);
+    result.lintWarnings = await runLint(
+      worktreePath,
+      config.verification.timeout,
+      sandbox,
+    );
     if (result.lintWarnings.length > 0) {
       log.warn(
         TAG,
@@ -154,46 +173,151 @@ export async function runVerification(
 }
 
 /**
- * ## The verification steps run the RUN'S OWN scripts, and that is a known hole
+ * ## The verification steps run the RUN'S OWN scripts — contained since #1036
+ *
+ * `runBuild`, `runTests`, `runFormatFix` and `runLint` resolve their command
+ * through `spawnRunArgs` — `bun run <script>` out of the worktree's own
+ * `package.json`. The worktree is in `sandbox.filesystem.allowWrite` by design,
+ * so a contained implement run can rewrite `"build"` to anything it likes, and
+ * before #1036 the daemon then ran it **in its own process**, as the operator,
+ * with network. No failure was needed to trigger it; verification runs on every
+ * successful run.
  *
- * `runBuild`, `runTests`, `runFormatFix`, `runLint` and `runDeepReview`'s dev
- * server all resolve their command through `spawnRunArgs` — `bun run <script>`
- * out of the worktree's own `package.json` — and execute it **in the daemon
- * process**. (`review-worker.ts` spawns the sixth, its own `dev` server, for the
- * same reason and with the same exposure.)
- * The worktree is in `sandbox.filesystem.allowWrite` by design, so a contained
- * implement run can rewrite `"build"` to anything it likes and the daemon will
- * then run it, outside the sandbox, with full network. No failure is needed to
- * trigger this; verification runs on every successful run.
+ * `env: containedEnv()` (#988) removed the secret-shaped variables and was
+ * stated there as a reduction and NOT a fix — the command still read `~/.ssh`
+ * and `~/.harmony-mcp/config.json` off disk. **#1036 closes the rest, for these
+ * four, when `verification.sandboxImage` is set:** `execStep` routes them into
+ * `repair-sandbox.ts`'s container, whose only mount is the worktree and which
+ * has no network. There is no host fallback, because falling back would return
+ * exactly the exposure the image was configured to remove.
  *
- * `env: containedEnv()` (#988) is a real reduction and NOT a fix: it removes
- * the secret-shaped variables, so `HARMONY_API_KEY`, `GITHUB_PERSONAL_ACCESS_TOKEN`
- * and their neighbours are gone from the child. What remains is a command of
- * the run's choosing, executing as the operator, able to read `~/.ssh` and
- * reach the network.
+ * It is opt-in, and unlike #988 that is a COST decision as well as a capability
+ * one. #988 measured no penalty for its own containment. This one, measured on
+ * macOS / Docker Desktop 29.7.2 with a warm `node:22-alpine` and a ~0.35 s
+ * workload:
  *
- * Closing it properly means running the repo's own build and test somewhere the
- * operator's credentials are not — which is the problem `repair-sandbox.ts`
- * solved for the CI repair with a container, and it is a piece of work of its
- * own rather than a line in this one. Until then this is listed in
- * `run-containment.ts`'s "what this does not cover" and in `docs/agent-daemon.md`,
- * because a residual nobody wrote down is indistinguishable from one nobody saw.
+ *     uncontained   0.38 / 0.35 / 0.34 s
+ *     contained     5.53 / 5.42 / 5.41 s      -> ~5.1 s added per command
  *
- * That is not a figure of speech here. The first version of both lists named
- * the four verification steps only, and the two `dev` servers — which are the
- * same `spawnRunArgs` shape — then shipped with the daemon's full environment,
- * unlisted and unnoticed through every gate. `spawn-run-containment.test.ts`
- * now asserts the property over call sites rather than over a written list.
+ * The workload is 0.35 s, so that is essentially all container start-up rather
+ * than a slower command — which means it is a FIXED cost paid per step, about
+ * 20 s on a run that builds, tests, lints and formats. On a Linux daemon host
+ * with no VM in the path it should be well below this; nobody has measured that,
+ * and this comment is the only record either way. That is the second reason
+ * there is no default: a fixed ~20 s per run is not a cost to start spending on
+ * an operator's behalf, and the first is that a guessed image reports every run
+ * as unverified — the reason `types.ts` already records for the repair path.
+ *
+ * **The image must match the repo's DETECTED package manager, not merely carry
+ * "a toolchain".** `spawnRunArgs` resolves through `detectPackageManager`, so a
+ * repo that resolves to `npm` fails in an `oven/bun:1` image with a raw OCI
+ * error (`exec: "npm": executable file not found in $PATH`). That surfaces as a
+ * `sandboxError` — the step reports it did not run — which is the right
+ * outcome, but the message is Docker's and not a friendly one. Found while
+ * taking the measurement above.
+ *
+ * The `build_green` gate collector re-runs the same build and lint scripts and
+ * takes the same sandbox, wired at the worker's registry call site. One config
+ * value, both paths.
+ *
+ * ## Still uncontained: the two `dev` servers, and the standalone CLI
+ *
+ * `runDeepReview`'s and the review worker's. Both are the same `spawnRunArgs`
+ * shape, and both are **probed over HTTP from the daemon**, so a `--network=none`
+ * container is unreachable by construction. They keep `containedEnv()` and stay
+ * named in `run-containment.ts`'s residual list rather than being quietly
+ * counted as covered. `harmony-harness`'s own CLI builds the same gate
+ * collector and passes no image, because the motor holds no operator config —
+ * a person running it against their own checkout, not board text.
+ *
+ * That distinction is stated rather than left implied because the first version
+ * of both lists named the four verification steps only, and the two dev servers
+ * then shipped with the daemon's full environment, unlisted and unnoticed
+ * through every gate. `spawn-run-containment.test.ts` asserts the environment
+ * property over call sites, and `verification-sandbox.test.ts` asserts that a
+ * configured image takes the four out of the daemon entirely.
  */
-export function runBuild(worktreePath: string, timeout: number): string[] {
-  const command = buildCommand(worktreePath);
-  if (!command) {
-    log.warn(
-      TAG,
-      `No known build toolchain for ${worktreePath} — skipping build`,
-    );
-    return [];
+/**
+ * Resolve the sandbox for the verification steps out of the daemon's config
+ * (#1036). Returns `undefined` when no image is configured, which is the
+ * default and means host execution exactly as before.
+ *
+ * An empty string is "not configured", never an image literally named `""` —
+ * that is the same reading `ci-patch.ts` gives `sandboxImage` on the repair
+ * path, and the two must not diverge.
+ */
+export function verificationSandbox(
+  config: VerificationConfig,
+): VerificationSandbox | undefined {
+  const image = config.verification.sandboxImage?.trim();
+  if (!image) return undefined;
+  return { image };
+}
+
+/**
+ * One verification command, run in the container when one is configured and in
+ * the daemon process when it is not.
+ *
+ * ## Why the outcome has three shapes and not two
+ *
+ * `sandboxError` is not `ok: false`. "The command failed" and "the container
+ * never started" must not both read as a bad branch, because only the first is
+ * the branch's fault — the same distinction `repair-sandbox.ts` draws for the
+ * repair path, and for the same reason.
+ *
+ * ## Why there is no host fallback
+ *
+ * An operator who configured an image asked for these commands to run without
+ * their credentials in scope. Silently running them on the host when Docker is
+ * unreachable would hand back precisely the exposure the image was set to
+ * remove, and would do it invisibly. So an unavailable runtime is reported, not
+ * routed around. `repair-sandbox.ts`'s header states the general form: a
+ * half-sandbox on the host is the one option that trades the property for
+ * convenience, so it is not offered.
+ */
+async function execStep(
+  command: { cmd: string; args: string[] },
+  args: {
+    worktreePath: string;
+    timeout: number;
+    sandbox: VerificationSandbox | undefined;
+  },
+): Promise<{ ok: boolean; err?: unknown; sandboxError?: string }> {
+  const { worktreePath, timeout } = args;
+  // An empty image is "not configured", never an image named `""` — and the
+  // check is here as well as in `verificationSandbox` because these four are
+  // exported and a caller can hand-build the object. Docker reads `""` as a
+  // missing argument and would fail in a way that reads like a broken runtime.
+  const sandbox = args.sandbox?.image.trim() ? args.sandbox : undefined;
+
+  if (sandbox) {
+    if (!(await sandboxAvailable())) {
+      return {
+        ok: false,
+        sandboxError:
+          `verification.sandboxImage is set to "${sandbox.image}" but no container runtime answered — ` +
+          "start Docker or unset the image to verify on the host",
+      };
+    }
+    const result = await runInSandbox({
+      image: sandbox.image,
+      worktree: worktreePath,
+      command,
+      // The STEP's own cap, plus what the container costs to start. Not a
+      // separate sandbox-wide timeout: build/lint and the test suite carry
+      // different caps on purpose, and one shared knob would silently replace
+      // both the moment an image is configured.
+      timeoutMs: timeout + SANDBOX_STARTUP_GRACE_MS,
+    });
+    if (result.sandboxError) {
+      return { ok: false, sandboxError: result.sandboxError };
+    }
+    if (result.passed) return { ok: true };
+    // Re-shape into what the existing parsers read, so the container path and
+    // the host path produce identical diagnostics from identical output.
+    return { ok: false, err: { stdout: result.output, stderr: "" } };
   }
+
   try {
     execFileSync(command.cmd, command.args, {
       cwd: worktreePath,
@@ -202,18 +326,44 @@ export function runBuild(worktreePath: string, timeout: number): string[] {
       maxBuffer: MAX_OUTPUT_BUFFER,
       env: containedEnv(),
     });
-    return [];
+    return { ok: true };
   } catch (err: unknown) {
-    return parseErrorOutput(err);
+    return { ok: false, err };
   }
 }
 
+export async function runBuild(
+  worktreePath: string,
+  timeout: number,
+  sandbox?: VerificationSandbox,
+): Promise<string[]> {
+  const command = buildCommand(worktreePath);
+  if (!command) {
+    log.warn(
+      TAG,
+      `No known build toolchain for ${worktreePath} — skipping build`,
+    );
+    return [];
+  }
+  const outcome = await execStep(command, { worktreePath, timeout, sandbox });
+  if (outcome.ok) return [];
+  if (outcome.sandboxError) {
+    log.error(TAG, `Build not verified: ${outcome.sandboxError}`);
+    return [`Build did not run: ${outcome.sandboxError}`];
+  }
+  return parseErrorOutput(outcome.err);
+}
+
 /**
  * Run the repo's own test suite. Returns the failures (empty = passed, or no
  * suite to run). A non-zero exit ALWAYS yields at least one entry — an
  * unparsable failure must never read as a pass (#688).
  */
-export function runTests(worktreePath: string, timeout: number): string[] {
+export async function runTests(
+  worktreePath: string,
+  timeout: number,
+  sandbox?: VerificationSandbox,
+): Promise<string[]> {
   const command = testCommand(worktreePath);
   if (!command) {
     log.warn(
@@ -222,25 +372,23 @@ export function runTests(worktreePath: string, timeout: number): string[] {
     );
     return [];
   }
-  try {
-    execFileSync(command.cmd, command.args, {
-      cwd: worktreePath,
-      timeout,
-      stdio: "pipe",
-      maxBuffer: MAX_OUTPUT_BUFFER,
-      env: containedEnv(),
-    });
-    return [];
-  } catch (err: unknown) {
-    // The suite's own output is the diagnostic — put its tail in the run log,
-    // not only the parsed lines that become subtasks.
-    const output = combineOutput(err);
-    log.warn(
-      TAG,
-      `Test run failed:\n${output.slice(-4000) || "(no output captured)"}`,
-    );
-    return parseTestFailures(err, timeout);
+  const outcome = await execStep(command, { worktreePath, timeout, sandbox });
+  if (outcome.ok) return [];
+  if (outcome.sandboxError) {
+    // #688's rule — a non-pass must never yield [] — with the reason being the
+    // sandbox rather than a test that never ran. Reporting a phantom assertion
+    // here would send someone to read a suite that produced no output.
+    log.error(TAG, `Tests not verified: ${outcome.sandboxError}`);
+    return [`Test run did not happen: ${outcome.sandboxError}`];
   }
+  // The suite's own output is the diagnostic — put its tail in the run log,
+  // not only the parsed lines that become subtasks.
+  const output = combineOutput(outcome.err);
+  log.warn(
+    TAG,
+    `Test run failed:\n${output.slice(-4000) || "(no output captured)"}`,
+  );
+  return parseTestFailures(outcome.err, timeout);
 }
 
 /**
@@ -255,36 +403,42 @@ export function runTests(worktreePath: string, timeout: number): string[] {
  * rule) is logged, never thrown. This does NOT change the lint-warn-only
  * policy — the later `runLint` still reports whatever the fixer left behind.
  */
-export function runFormatFix(
+export async function runFormatFix(
   worktreePath: string,
   timeout: number,
   workerId: number,
-): void {
+  sandbox?: VerificationSandbox,
+): Promise<void> {
   const command = formatFixCommand(worktreePath);
   if (!command) return;
-  try {
-    execFileSync(command.cmd, command.args, {
-      cwd: worktreePath,
-      timeout,
-      stdio: "pipe",
-      maxBuffer: MAX_OUTPUT_BUFFER,
-      env: containedEnv(),
-    });
+  const outcome = await execStep(command, { worktreePath, timeout, sandbox });
+  if (outcome.ok) {
     log.info(
       TAG,
       `[worker:${workerId}] Auto-formatted worktree before commit/push`,
     );
-  } catch (err: unknown) {
-    log.warn(
-      TAG,
-      `[worker:${workerId}] Auto-format step exited non-zero (non-fatal): ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
+    return;
   }
+  // Best-effort by contract: this step is tied to the lint step and never
+  // blocks. A broken container is one more reason it did not run, reported at
+  // the same level as a fixer that exited non-zero — the later `runLint` still
+  // reports whatever was left behind.
+  const why = outcome.sandboxError
+    ? outcome.sandboxError
+    : outcome.err instanceof Error
+      ? outcome.err.message
+      : String(outcome.err);
+  log.warn(
+    TAG,
+    `[worker:${workerId}] Auto-format step did not complete (non-fatal): ${why}`,
+  );
 }
 
-export function runLint(worktreePath: string, timeout: number): string[] {
+export async function runLint(
+  worktreePath: string,
+  timeout: number,
+  sandbox?: VerificationSandbox,
+): Promise<string[]> {
   const command = lintCommand(worktreePath);
   if (!command) {
     log.info(
@@ -293,18 +447,16 @@ export function runLint(worktreePath: string, timeout: number): string[] {
     );
     return [];
   }
-  try {
-    execFileSync(command.cmd, command.args, {
-      cwd: worktreePath,
-      timeout,
-      stdio: "pipe",
-      maxBuffer: MAX_OUTPUT_BUFFER,
-      env: containedEnv(),
-    });
-    return [];
-  } catch (err: unknown) {
-    return parseErrorOutput(err);
+  const outcome = await execStep(command, { worktreePath, timeout, sandbox });
+  if (outcome.ok) return [];
+  if (outcome.sandboxError) {
+    // Lint is warn-only, so this is reported as a warning line rather than
+    // blocking — but it must still say the step did not run, because an empty
+    // lint result is indistinguishable from a clean one.
+    log.error(TAG, `Lint not verified: ${outcome.sandboxError}`);
+    return [`Lint did not run: ${outcome.sandboxError}`];
   }
+  return parseErrorOutput(outcome.err);
 }
 
 export async function runDeepReview(