@gethmy/harness 1.5.0 → 1.7.0

package/dist/cli.js

@@ -17,14 +17,13 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // ../harmony-shared/dist/agentStaleness.js
-var AGENT_HEARTBEAT_LIVENESS_MS, AGENT_MILESTONE_LIVENESS_MS, AGENT_SWEEP_DAEMON_MS, AGENT_SWEEP_INTERACTIVE_MS, AGENT_SWEEP_PAUSED_MS, SWEPT_SESSION_WRITE_GRACE_MS, ACTIVE_STATUSES;
+var AGENT_HEARTBEAT_LIVENESS_MS, AGENT_MILESTONE_LIVENESS_MS, AGENT_SWEEP_DAEMON_MS, AGENT_SWEEP_INTERACTIVE_MS, AGENT_SWEEP_PAUSED_MS, ACTIVE_STATUSES;
 var init_agentStaleness = __esm(() => {
   AGENT_HEARTBEAT_LIVENESS_MS = 5 * 60 * 1000;
   AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
   AGENT_SWEEP_DAEMON_MS = 30 * 60 * 1000;
   AGENT_SWEEP_INTERACTIVE_MS = 2 * 60 * 60 * 1000;
   AGENT_SWEEP_PAUSED_MS = 4 * 60 * 60 * 1000;
-  SWEPT_SESSION_WRITE_GRACE_MS = 60 * 60 * 1000;
   ACTIVE_STATUSES = new Set(["working", "blocked", "waiting"]);
 });
 // ../harmony-shared/dist/branchRef.js
@@ -612,13 +611,13 @@ var init_log = __esm(() => {
 
 // src/confine-to-repo.ts
 import { realpathSync } from "node:fs";
-import { dirname as dirname2, isAbsolute as isAbsolute2, parse, resolve as resolve2, sep as sep2 } from "node:path";
+import { dirname, isAbsolute, parse, resolve, sep } from "node:path";
 function isGitMetadata(repoRoot, candidate) {
   const rel = candidate.startsWith(repoRoot) ? candidate.slice(repoRoot.length) : candidate;
   return rel.split(/[\\/]/).some((segment) => segment.toLowerCase() === ".git");
 }
 function patternEscapes(pattern) {
-  if (isAbsolute2(pattern))
+  if (isAbsolute(pattern))
     return true;
   if (/[{}[\]~()!+@]/.test(pattern))
     return true;
@@ -628,17 +627,17 @@ function pathArgsFor(mode) {
   return mode === "write" ? { ...READ_PATH_ARGS, ...WRITE_PATH_ARGS } : READ_PATH_ARGS;
 }
 function realPathOrNearest(p) {
-  const abs = isAbsolute2(p) ? p : resolve2(p);
+  const abs = isAbsolute(p) ? p : resolve(p);
   const { root } = parse(abs);
   let real = root;
-  for (const part of abs.slice(root.length).split(sep2)) {
+  for (const part of abs.slice(root.length).split(sep)) {
     if (part === "" || part === ".")
       continue;
     if (part === "..") {
-      real = dirname2(real);
+      real = dirname(real);
       continue;
     }
-    const next = real.endsWith(sep2) ? real + part : real + sep2 + part;
+    const next = real.endsWith(sep) ? real + part : real + sep + part;
     try {
       real = realpathSync(next);
     } catch {
@@ -652,7 +651,7 @@ function isInsideTree(root, target) {
   const normalizedTarget = realPathOrNearest(target);
   if (normalizedTarget === normalizedRoot)
     return true;
-  return normalizedTarget.startsWith(normalizedRoot + sep2);
+  return normalizedTarget.startsWith(normalizedRoot + sep);
 }
 function decideConfinedTool(repoRoot, toolName, input, mode = "read") {
   const pathArgs = pathArgsFor(mode)[toolName];
@@ -678,7 +677,7 @@ function decideConfinedTool(repoRoot, toolName, input, mode = "read") {
     const value = input[key];
     if (typeof value !== "string" || value.length === 0)
       continue;
-    const candidate = isAbsolute2(value) ? value : `${repoRoot}${sep2}${value}`;
+    const candidate = isAbsolute(value) ? value : `${repoRoot}${sep}${value}`;
     if (isGitMetadata(repoRoot, candidate)) {
       return {
         behavior: "deny",
@@ -769,38 +768,38 @@ var init_runner = __esm(() => {
 });
 
 // src/run-containment.ts
-import { createHash as createHash2 } from "node:crypto";
-import { readFileSync as readFileSync2 } from "node:fs";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
-import { homedir, tmpdir as tmpdir2 } from "node:os";
-import { dirname as dirname3, isAbsolute as isAbsolute3, join as join2 } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join } from "node:path";
 import { getConfigDir as getConfigDir2 } from "@gethmy/mcp/src/config.js";
 function credentialDirectories() {
   const home = homedir();
   return [
     getConfigDir2(),
-    join2(home, ".claude"),
-    join2(home, ".claude.json"),
-    join2(home, ".ssh"),
-    join2(home, ".gnupg"),
-    join2(home, ".aws"),
-    join2(home, ".codex"),
-    join2(home, ".gemini"),
-    join2(home, ".config", "gh"),
-    join2(home, ".config", "gcloud"),
-    join2(home, ".config", "anthropic"),
-    join2(home, ".config", "op"),
-    join2(home, ".docker"),
-    join2(home, ".kube"),
-    join2(home, ".netrc"),
-    join2(home, ".npmrc"),
-    join2(home, ".git-credentials")
+    join(home, ".claude"),
+    join(home, ".claude.json"),
+    join(home, ".ssh"),
+    join(home, ".gnupg"),
+    join(home, ".aws"),
+    join(home, ".codex"),
+    join(home, ".gemini"),
+    join(home, ".config", "gh"),
+    join(home, ".config", "gcloud"),
+    join(home, ".config", "anthropic"),
+    join(home, ".config", "op"),
+    join(home, ".docker"),
+    join(home, ".kube"),
+    join(home, ".netrc"),
+    join(home, ".npmrc"),
+    join(home, ".git-credentials")
   ];
 }
 function writeOnlyDenyPaths() {
-  const paths = [join2(homedir(), ".gitconfig")];
+  const paths = [join(homedir(), ".gitconfig")];
   const xdg = process.env.XDG_CONFIG_HOME;
-  paths.push(xdg && isAbsolute3(xdg) ? join2(xdg, "git") : join2(homedir(), ".config", "git"));
+  paths.push(xdg && isAbsolute2(xdg) ? join(xdg, "git") : join(homedir(), ".config", "git"));
   return paths;
 }
 function credentialToolDeny() {
@@ -811,13 +810,13 @@ function credentialToolDeny() {
 }
 function toolchainCacheDirectories(worktree) {
   const home = homedir();
-  const scratch = `harmony-run-${createHash2("sha256").update(worktree).digest("hex").slice(0, 16)}`;
-  const candidate = process.env.TMPDIR ?? tmpdir2();
-  const tmpRoot = isAbsolute3(candidate) ? candidate : "/tmp";
+  const scratch = `harmony-run-${createHash("sha256").update(worktree).digest("hex").slice(0, 16)}`;
+  const candidate = process.env.TMPDIR ?? tmpdir();
+  const tmpRoot = isAbsolute2(candidate) ? candidate : "/tmp";
   return [
-    join2(home, ".bun", "install", "cache"),
-    join2(home, ".npm", "_cacache"),
-    join2(tmpRoot, scratch)
+    join(home, ".bun", "install", "cache"),
+    join(home, ".npm", "_cacache"),
+    join(tmpRoot, scratch)
   ];
 }
 function secretEnvKeysToStrip(parentEnv = process.env) {
@@ -832,10 +831,10 @@ function secretEnvKeysToStrip(parentEnv = process.env) {
 }
 function assertNoProjectSandboxOverride(worktree) {
   for (const name of ["settings.json", "settings.local.json"]) {
-    const path = join2(worktree, ".claude", name);
+    const path = join(worktree, ".claude", name);
     let raw;
     try {
-      raw = readFileSync2(path, "utf-8");
+      raw = readFileSync(path, "utf-8");
     } catch {
       continue;
     }
@@ -863,12 +862,17 @@ function containedEnv(parentEnv = process.env) {
   }
   return out;
 }
+function heldTestEnvKeysToStrip(parentEnv = process.env) {
+  return [
+    ...new Set([...secretEnvKeysToStrip(parentEnv), ...MODEL_CREDENTIAL_KEYS])
+  ];
+}
 function gitMetadataDenyPaths(worktree) {
   const paths = new Set;
-  const dotGit = join2(worktree, ".git");
+  const dotGit = join(worktree, ".git");
   const require2 = createRequire2(import.meta.url);
   const { execFileSync } = require2("node:child_process");
-  const { statSync: statSync2 } = require2("node:fs");
+  const { statSync } = require2("node:fs");
   const gitDirs = new Set;
   try {
     const out = execFileSync("git", [...GIT_NO_HOOKS, "rev-parse", "--git-dir", "--git-common-dir"], { cwd: worktree, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
@@ -877,17 +881,17 @@ function gitMetadataDenyPaths(worktree) {
       const trimmed = line.trim();
       if (!trimmed)
         continue;
-      gitDirs.add(isAbsolute3(trimmed) ? trimmed : join2(worktree, trimmed));
+      gitDirs.add(isAbsolute2(trimmed) ? trimmed : join(worktree, trimmed));
     }
   } catch {}
   gitDirs.add(dotGit);
   for (const dir of gitDirs) {
-    paths.add(join2(dir, "config"));
-    paths.add(join2(dir, "config.worktree"));
-    paths.add(join2(dir, "hooks"));
+    paths.add(join(dir, "config"));
+    paths.add(join(dir, "config.worktree"));
+    paths.add(join(dir, "hooks"));
   }
   try {
-    if (statSync2(dotGit).isFile())
+    if (statSync(dotGit).isFile())
       paths.add(dotGit);
   } catch {}
   return [...paths];
@@ -895,19 +899,19 @@ function gitMetadataDenyPaths(worktree) {
 function hostPersistencePaths() {
   const home = homedir();
   return [
-    join2(home, ".zshenv"),
-    join2(home, ".zprofile"),
-    join2(home, ".zshrc"),
-    join2(home, ".zlogin"),
-    join2(home, ".bashrc"),
-    join2(home, ".bash_profile"),
-    join2(home, ".bash_login"),
-    join2(home, ".profile"),
-    join2(home, ".config", "fish", "config.fish"),
-    join2(home, ".config", "fish", "conf.d"),
-    join2(home, "Library", "LaunchAgents"),
-    join2(home, ".config", "systemd", "user"),
-    join2(home, ".config", "autostart")
+    join(home, ".zshenv"),
+    join(home, ".zprofile"),
+    join(home, ".zshrc"),
+    join(home, ".zlogin"),
+    join(home, ".bashrc"),
+    join(home, ".bash_profile"),
+    join(home, ".bash_login"),
+    join(home, ".profile"),
+    join(home, ".config", "fish", "config.fish"),
+    join(home, ".config", "fish", "conf.d"),
+    join(home, "Library", "LaunchAgents"),
+    join(home, ".config", "systemd", "user"),
+    join(home, ".config", "autostart")
   ];
 }
 function credentialWriteToolDeny(worktree) {
@@ -939,7 +943,7 @@ function implementRunToolPolicy(args) {
         const value = input[key];
         if (typeof value !== "string" || value.length === 0)
           continue;
-        const target = isAbsolute3(value) ? value : join2(args.worktree, value);
+        const target = isAbsolute2(value) ? value : join(args.worktree, value);
         if (gitMeta.some((p) => isInsideTree(p, target) || p === target)) {
           return deny(`${toolName} may not touch git metadata. Refused: ${value}`);
         }
@@ -955,7 +959,7 @@ function implementRunToolPolicy(args) {
         const value = input[key];
         if (typeof value !== "string" || value.length === 0)
           continue;
-        const target = isAbsolute3(value) ? value : join2(args.worktree, value);
+        const target = isAbsolute2(value) ? value : join(args.worktree, value);
         if (secrets.some((dir) => isInsideTree(dir, target))) {
           return deny(`${toolName} may not read the credential directories. Refused: ${value}`);
         }
@@ -965,14 +969,20 @@ function implementRunToolPolicy(args) {
     return allow;
   };
 }
-function harmonyMcpServer() {
+function harmonyMcpServer(run) {
   const require2 = createRequire2(import.meta.url);
-  const cli = join2(dirname3(require2.resolve("@gethmy/mcp")), "cli.js");
+  const cli = join(dirname2(require2.resolve("@gethmy/mcp")), "cli.js");
   return {
     harmony: {
       type: "stdio",
       command: process.execPath,
-      args: [cli, "serve"]
+      args: [cli, "serve"],
+      ...run ? {
+        env: {
+          HARMONY_AGENT_CARD_ID: run.cardId,
+          HARMONY_AGENT_SESSION_ID: run.agentSessionId
+        }
+      } : {}
     }
   };
 }
@@ -1005,7 +1015,7 @@ function implementRunContainment(args) {
     canUseTool: implementRunToolPolicy(args),
     gateEveryToolCall: true,
     settingSources: args.readOnly === true ? [] : ["project"],
-    mcpServers: harmonyMcpServer(),
+    mcpServers: harmonyMcpServer(args.run),
     strictMcpConfig: true,
     stripEnvKeys: secretEnvKeysToStrip(),
     disallowedTools: [
@@ -1029,7 +1039,7 @@ function implementRunContainmentCliArgs(args) {
     containment.disallowedTools.join(",")
   ];
 }
-var SECRET_ENV_PATTERN, KEEP_ENV_KEYS, ProjectSandboxOverrideError, INERT_PROJECT_SETTING_KEYS, WRITE_TOOL_PATHS, READ_TOOL_PATHS, GIT_NO_HOOKS, IMPLEMENT_ALLOWED_DOMAINS;
+var SECRET_ENV_PATTERN, KEEP_ENV_KEYS, ProjectSandboxOverrideError, INERT_PROJECT_SETTING_KEYS, MODEL_CREDENTIAL_KEYS, WRITE_TOOL_PATHS, READ_TOOL_PATHS, GIT_NO_HOOKS, IMPLEMENT_ALLOWED_DOMAINS;
 var init_run_containment = __esm(() => {
   init_confine_to_repo();
   init_runner();
@@ -1066,6 +1076,11 @@ var init_run_containment = __esm(() => {
     "theme",
     "verbose"
   ]);
+  MODEL_CREDENTIAL_KEYS = [
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN"
+  ];
   WRITE_TOOL_PATHS = {
     Write: ["file_path"],
     Edit: ["file_path"],
@@ -1802,6 +1817,7 @@ init_dist();
 
 // src/exec-types.ts
 var DEFAULT_METRIC_TIMEOUT_MS = 300000;
+var SANDBOX_STARTUP_GRACE_MS = 60000;
 
 // src/gate-config-error.ts
 init_dist();
@@ -2061,11 +2077,12 @@ function truncate(value, max) {
 init_log();
 
 // src/oracle-collector.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 init_log();
 
 // src/oracle.ts
-import { lstatSync, readFileSync, statSync } from "node:fs";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { lstatSync, readFileSync as readFileSync2, realpathSync as realpathSync2, statSync } from "node:fs";
 import {
   chmod,
   lstat,
@@ -2075,26 +2092,159 @@ import {
   rm,
   writeFile
 } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+import { dirname as dirname3, isAbsolute as isAbsolute3, join as join2, resolve as resolve2, sep as sep2 } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 init_log();
-var TAG4 = "oracle";
+
+// src/repair-sandbox.ts
+init_log();
+import { randomUUID } from "node:crypto";
+import { promisify } from "node:util";
+var TAG4 = "repair-sandbox";
+async function dockerExec(argv, opts) {
+  const { execFile } = await import("node:child_process");
+  return promisify(execFile)("docker", argv, {
+    encoding: "utf-8",
+    ...opts
+  });
+}
+var MAX_OUTPUT_BUFFER2 = 20971520;
+var PROBE_TIMEOUT_MS = 1e4;
+var SANDBOX_MOUNT = "/repo";
+var SANDBOX_MEMORY = "4g";
+var SANDBOX_PIDS = "512";
+var dockerProbe = null;
+async function sandboxAvailable() {
+  if (dockerProbe === true)
+    return true;
+  try {
+    await dockerExec(["version", "--format", "{{.Server.Version}}"], {
+      timeout: PROBE_TIMEOUT_MS
+    });
+    dockerProbe = true;
+  } catch {
+    dockerProbe = false;
+  }
+  return dockerProbe;
+}
+function __resetSandboxProbe() {
+  dockerProbe = null;
+}
+async function removeSandboxContainer(name) {
+  try {
+    await dockerExec(["rm", "--force", name], { timeout: PROBE_TIMEOUT_MS });
+    log.info(TAG4, `removed sandbox container ${name}`);
+  } catch {}
+}
+function sandboxRunArgs(image, worktree, command, name, mounts = []) {
+  return [
+    "run",
+    "--rm",
+    ...name ? ["--name", name] : [],
+    "--network=none",
+    ...sandboxHardeningArgs(worktree, mounts),
+    "--entrypoint",
+    command.cmd,
+    image,
+    ...command.args
+  ];
+}
+function sandboxHardeningArgs(worktree, mounts = []) {
+  return [
+    "--cap-drop=ALL",
+    "--security-opt=no-new-privileges",
+    `--memory=${SANDBOX_MEMORY}`,
+    `--pids-limit=${SANDBOX_PIDS}`,
+    ...typeof process.getuid === "function" && typeof process.getgid === "function" ? ["--user", `${process.getuid()}:${process.getgid()}`] : [],
+    "--env",
+    "HOME=/tmp",
+    "--volume",
+    `${worktree}:${SANDBOX_MOUNT}`,
+    ...mounts.flatMap((m) => ["--volume", `${m.host}:${m.container}`]),
+    "--workdir",
+    SANDBOX_MOUNT
+  ];
+}
+var SANDBOX_DEV_SERVER_BIND = "0.0.0.0";
+function devServerContainerName(port) {
+  return `harmony-devserver-${port}`;
+}
+function devServerSandboxArgs(args) {
+  return [
+    "run",
+    "--rm",
+    "--quiet",
+    "--name",
+    args.name,
+    "--publish",
+    `127.0.0.1:${args.port}:${args.port}`,
+    ...sandboxHardeningArgs(args.worktree),
+    "--entrypoint",
+    args.command.cmd,
+    args.image,
+    ...args.command.args
+  ];
+}
+async function runInSandbox(args) {
+  const name = `harmony-repair-${randomUUID()}`;
+  const argv = sandboxRunArgs(args.image, args.worktree, args.command, name);
+  log.info(TAG4, `sandbox: ${args.command.cmd} ${args.command.args.join(" ")} (image ${args.image})`);
+  try {
+    const { stdout } = await dockerExec(argv, {
+      timeout: args.timeoutMs,
+      maxBuffer: MAX_OUTPUT_BUFFER2
+    });
+    return { passed: true, output: stdout ?? "" };
+  } catch (err) {
+    const e = err;
+    const output = `${e.stdout ?? ""}${e.stderr ?? ""}`;
+    if (typeof e.code !== "number") {
+      const timedOut = e.killed === true || e.signal != null;
+      if (timedOut)
+        await removeSandboxContainer(name);
+      return {
+        passed: false,
+        output,
+        sandboxError: timedOut ? `the sandbox timed out after ${args.timeoutMs}ms` : `the sandbox did not run: ${e.message ?? "unknown error"}`
+      };
+    }
+    if (e.code === 125) {
+      return {
+        passed: false,
+        output,
+        sandboxError: `the sandbox could not start (image "${args.image}" missing or unusable)`
+      };
+    }
+    return { passed: false, output };
+  }
+}
+
+// src/oracle.ts
+init_run_containment();
+var TAG5 = "oracle";
+
+class OracleSandboxConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OracleSandboxConfigError";
+  }
+}
 async function resolveContained(repoPath, relativePath) {
-  if (isAbsolute(relativePath)) {
+  if (isAbsolute3(relativePath)) {
     throw new Error(`refusing to place an oracle at an absolute path: ${relativePath}`);
   }
   if (relativePath === "" || relativePath === ".") {
     throw new Error(`refusing to place an oracle at the empty/self path: "${relativePath}"`);
   }
   const root = await realpath(repoPath);
-  const target = resolve(root, relativePath);
-  if (target !== root && !target.startsWith(root + sep)) {
+  const target = resolve2(root, relativePath);
+  if (target !== root && !target.startsWith(root + sep2)) {
     throw new Error(`refusing to place an oracle outside the worktree: ${relativePath}`);
   }
   let cursor = root;
   for (const segment of relativePath.split("/")) {
-    cursor = resolve(cursor, segment);
+    cursor = resolve2(cursor, segment);
     const stat = await lstat(cursor).catch(() => null);
     if (stat?.isSymbolicLink()) {
       throw new Error(`refusing an oracle path through a symlink component: ${relativePath}`);
@@ -2104,7 +2254,7 @@ async function resolveContained(repoPath, relativePath) {
 }
 async function place(repoPath, oracle) {
   const target = await resolveContained(repoPath, oracle.path);
-  await mkdir(dirname(target), { recursive: true });
+  await mkdir(dirname3(target), { recursive: true });
   await writeFile(target, oracle.content, "utf8");
 }
 async function remove(repoPath, oracle) {
@@ -2210,12 +2360,24 @@ function gradeOracleRed(summary, exitCode) {
 function argvPath(path) {
   return path.startsWith("./") ? path : `./${path}`;
 }
-async function runHeldOracle(repoPath, oracle, timeoutMs = DEFAULT_METRIC_TIMEOUT_MS) {
+async function runHeldOracle(repoPath, oracle, options = {}) {
+  const heldTestTimeoutMs = options.timeoutMs ?? DEFAULT_METRIC_TIMEOUT_MS;
+  const sandbox = options.sandbox?.image.trim() ? options.sandbox : undefined;
+  if (sandbox && !await sandboxAvailable()) {
+    throw new OracleSandboxConfigError(`the held test is configured to run in "${sandbox.image}" but no container runtime answered — ` + "start Docker or unset verification.sandboxImage to run it on the host");
+  }
   const spec = resolveOracleRunnerSpec(oracle);
-  const reportDir = await mkdtemp(join(tmpdir(), reportDirPrefix()));
-  const reportPath = join(reportDir, spec.report.file);
+  const reportDir = await mkdtemp(join2(tmpdir2(), reportDirPrefix()));
+  const reportPath = join2(reportDir, spec.report.file);
   try {
-    return await spawnHeldOracle(spec, repoPath, oracle, reportPath, timeoutMs);
+    return await spawnHeldOracle({
+      spec,
+      repoPath,
+      oracle,
+      reportPath,
+      timeoutMs: sandbox ? heldTestTimeoutMs + SANDBOX_STARTUP_GRACE_MS : heldTestTimeoutMs,
+      sandbox
+    });
   } finally {
     await removeReportDir(reportDir);
   }
@@ -2224,7 +2386,7 @@ function reportDirPrefix() {
   return "harmony-oracle-report-";
 }
 function assertUntampered(reportPath) {
-  const dir = statSync(dirname(reportPath));
+  const dir = statSync(dirname3(reportPath));
   if ((dir.mode & 511) !== 448) {
     throw new Error(`the oracle report directory's mode changed to ${(dir.mode & 511).toString(8)} — refusing the report`);
   }
@@ -2236,23 +2398,57 @@ function assertUntampered(reportPath) {
     throw new Error(`the oracle report is not owner-writable (mode ${(file.mode & 511).toString(8)}), so the runner could not have written it last — refusing it`);
   }
 }
+function assertConsistentWithExit(summary, exitCode) {
+  if (!summary)
+    return;
+  if (summary.failed > 0 && exitCode === 0) {
+    throw new Error(`the oracle report claims ${summary.failed} of ${summary.total} test(s) failed, but the runner exited 0 — ` + "neither allow-listed runner produces that pair, so the report is not the runner's; refusing it");
+  }
+}
 async function removeReportDir(reportDir) {
   try {
     await chmod(reportDir, 448).catch(() => {});
     await rm(reportDir, { recursive: true, force: true });
   } catch (err) {
-    log.warn(TAG4, `Could not remove the oracle report directory ${reportDir} (${err instanceof Error ? err.message : String(err)}) — it may still hold the runner's report, which carries assertion text for vitest. Remove it by hand.`);
+    log.warn(TAG5, `Could not remove the oracle report directory ${reportDir} (${err instanceof Error ? err.message : String(err)}) — it may still hold the runner's report, which carries assertion text for vitest. Remove it by hand.`);
   }
 }
-async function spawnHeldOracle(spec, repoPath, oracle, reportPath, timeoutMs) {
-  const { command, args: baseArgs } = spec.argv(argvPath(oracle.path));
-  const args = [...baseArgs, ...spec.report.flags(reportPath)];
+var ORACLE_REPORT_MOUNT = "/harmony-oracle-report";
+var DOCKER_SELF_FAILURE_CODES = new Set([125, 126, 127]);
+function heldOracleSandboxArgv(args) {
+  const reportPathInContainer = join2(ORACLE_REPORT_MOUNT, args.reportFile);
+  return {
+    command: "docker",
+    args: sandboxRunArgs(args.image, args.worktree, {
+      cmd: args.runner.command,
+      args: [...args.runner.args, ...args.reportFlags(reportPathInContainer)]
+    }, args.containerName, [{ host: args.reportDir, container: ORACLE_REPORT_MOUNT }]),
+    reportPathInContainer
+  };
+}
+async function spawnHeldOracle(args_) {
+  const { spec, repoPath, oracle, reportPath, timeoutMs, sandbox } = args_;
+  const runner = spec.argv(argvPath(oracle.path));
+  const containerName = sandbox ? `harmony-oracle-${randomUUID2()}` : null;
+  const { command, args } = sandbox ? heldOracleSandboxArgv({
+    image: sandbox.image,
+    worktree: realpathSync2(repoPath),
+    reportDir: realpathSync2(dirname3(reportPath)),
+    reportFile: spec.report.file,
+    runner,
+    reportFlags: spec.report.flags,
+    containerName: containerName ?? undefined
+  }) : {
+    command: runner.command,
+    args: [...runner.args, ...spec.report.flags(reportPath)]
+  };
   return await new Promise((settleOk, settleErr) => {
     let child;
     try {
       child = spawnInGroup(command, args, {
         cwd: repoPath,
-        stdio: ["ignore", "pipe", "pipe"]
+        stdio: ["ignore", "pipe", "pipe"],
+        stripEnvKeys: heldTestEnvKeysToStrip()
       });
     } catch (err) {
       settleErr(err);
@@ -2284,18 +2480,20 @@ ${output}` : output;
       return verdict;
     };
     let report = null;
-    const captureReport = () => {
+    const captureReport = (exitCode) => {
       try {
         assertUntampered(reportPath);
-        report = spec.report.parse(readFileSync(reportPath, "utf8"));
+        const parsed = spec.report.parse(readFileSync2(reportPath, "utf8"));
+        assertConsistentWithExit(parsed, exitCode);
+        report = parsed;
       } catch (err) {
         report = null;
         const message = err instanceof Error ? err.message : String(err);
         const absent = err instanceof Error && err.code === "ENOENT";
         if (absent) {
-          log.info(TAG4, `No oracle report at ${reportPath} — no verdict.`);
+          log.info(TAG5, `No oracle report at ${reportPath} — no verdict.`);
         } else {
-          log.warn(TAG4, `Refusing the oracle report at ${reportPath}: ${message} — the gate will report no verdict.`);
+          log.warn(TAG5, `Refusing the oracle report at ${reportPath}: ${message} — the gate will report no verdict.`);
         }
       }
     };
@@ -2341,6 +2539,10 @@ ${output}` : output;
         settle(new Error(`the held test was terminated by signal ${signal}`));
         return;
       }
+      if (sandbox && DOCKER_SELF_FAILURE_CODES.has(code)) {
+        settle(new OracleSandboxConfigError(`the held test's sandbox ("${sandbox.image}") exited ${code} without running the runner — ` + "the image is missing, unusable, or does not carry the runner; the motor's local log has docker's own message"));
+        return;
+      }
       settle(null, {
         exitCode: code,
         output: finalOutput(),
@@ -2351,7 +2553,7 @@ ${output}` : output;
     child.once("exit", (code, signal) => {
       if (killing)
         return;
-      captureReport();
+      captureReport(code);
       if (timer)
         clearTimeout(timer);
       reapGroup(pgid);
@@ -2365,7 +2567,9 @@ ${output}` : output;
       terminateGroup(child, {
         sigintTimeoutMs: ORACLE_SIGINT_GRACE_MS,
         sigtermTimeoutMs: ORACLE_SIGTERM_GRACE_MS
-      }).catch(() => {}).then(() => {
+      }).catch(() => {}).then(async () => {
+        if (containerName)
+          await removeSandboxContainer(containerName);
         settle(new Error(`the held test did not finish within ${timeoutMs}ms`));
       });
     }, timeoutMs);
@@ -2373,7 +2577,7 @@ ${output}` : output;
 }
 
 // src/oracle-collector.ts
-var TAG5 = "oracle-collector";
+var TAG6 = "oracle-collector";
 
 class HeldOracleCollector {
   deps;
@@ -2384,7 +2588,7 @@ class HeldOracleCollector {
     const stageId = this.oracleStageId(context);
     if (!stageId) {
       const reason = `No stage downstream of ${context.stageId} declares an \`oracle_passed\` gate, ` + "so there is no held test for this gate to grade. A red gate needs a later stage that runs the same test green.";
-      log.warn(TAG5, `${reason} — blocked (config)`);
+      log.warn(TAG6, `${reason} — blocked (config)`);
       return {
         result: "blocked",
         structured: { reason, ...GATE_CONFIG_ERROR_MARK }
@@ -2392,7 +2596,7 @@ class HeldOracleCollector {
     }
     const oracle = await this.deps.fetchOracle(context.cardId, stageId, this.deps.sessionId);
     if (!oracle) {
-      log.info(TAG5, `No oracle held for stage ${stageId} — blocked`);
+      log.info(TAG6, `No oracle held for stage ${stageId} — blocked`);
       return {
         result: "blocked",
         structured: {
@@ -2405,17 +2609,17 @@ class HeldOracleCollector {
   async runHeld(oracle) {
     const identity = {
       oracleId: oracle.id ?? null,
-      contentHash: createHash("sha256").update(oracle.content).digest("hex")
+      contentHash: createHash2("sha256").update(oracle.content).digest("hex")
     };
     await this.deps.place(this.deps.repoPath, oracle);
     try {
-      const { exitCode, output, report } = await this.deps.run(this.deps.repoPath, oracle);
+      const { exitCode, output, report } = await this.deps.run(this.deps.repoPath, oracle, { sandbox: this.deps.sandbox });
       const logLine = `Oracle run for ${oracle.path} exited ${exitCode}:
 ${output}`;
       if (exitCode === 0) {
-        log.info(TAG5, logLine);
+        log.info(TAG6, logLine);
       } else {
-        log.warn(TAG5, logLine);
+        log.warn(TAG6, logLine);
       }
       return this.verdict({
         oracle,
@@ -2426,12 +2630,14 @@ ${output}`;
       });
     } catch (err) {
       const message = errText(err);
-      log.warn(TAG5, `Oracle run threw: ${message} — blocked`);
+      const configError2 = err instanceof OracleSandboxConfigError;
+      log.warn(TAG6, `Oracle run threw: ${message} — blocked${configError2 ? " (config)" : ""}`);
       return {
         result: "blocked",
         structured: {
           oracle: { path: oracle.path, ...identity },
-          error: message
+          error: message,
+          ...configError2 ? { reason: message, ...GATE_CONFIG_ERROR_MARK } : {}
         }
       };
     } finally {
@@ -2443,13 +2649,13 @@ ${output}`;
       await this.deps.remove(this.deps.repoPath, oracle);
       return;
     } catch (err) {
-      log.warn(TAG5, `Removing the held test at ${oracle.path} failed (${errText(err)}) — retrying once`);
+      log.warn(TAG6, `Removing the held test at ${oracle.path} failed (${errText(err)}) — retrying once`);
     }
     try {
       await this.deps.remove(this.deps.repoPath, oracle);
-      log.info(TAG5, `Held test at ${oracle.path} removed on the second attempt`);
+      log.info(TAG6, `Held test at ${oracle.path} removed on the second attempt`);
     } catch (err) {
-      log.error(TAG5, `HELD TEST NOT REMOVED: ${oracle.path} is still in ${this.deps.repoPath} after two attempts (${errText(err)}). ` + "It will be auto-committed by the completion path if it is left there — delete it by hand and check whether it reached a commit.");
+      log.error(TAG6, `HELD TEST NOT REMOVED: ${oracle.path} is still in ${this.deps.repoPath} after two attempts (${errText(err)}). ` + "It will be auto-committed by the completion path if it is left there — delete it by hand and check whether it reached a commit.");
     }
   }
 }
@@ -2492,7 +2698,7 @@ class OracleRedCollector extends HeldOracleCollector {
     const graded = gradeOracleRed(report, exitCode);
     const base = { exitCode, path: oracle.path, ...identity };
     if (graded.outcome === "no_verdict") {
-      log.warn(TAG5, `Red gate for ${oracle.path}: ${graded.reason} — blocked`);
+      log.warn(TAG6, `Red gate for ${oracle.path}: ${graded.reason} — blocked`);
       return {
         result: "blocked",
         structured: { oracle: base, reason: graded.reason }
@@ -2516,15 +2722,15 @@ function errText(err) {
 }
 
 // src/verification.ts
-init_log();
 import { execFileSync as execFileSync4, spawn as spawn2 } from "node:child_process";
+init_log();
 
 // src/pm.ts
 init_log();
 init_run_containment();
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
-var TAG6 = "pm";
+var TAG7 = "pm";
 var cached = null;
 function detectPackageManager() {
   if (cached)
@@ -2546,7 +2752,7 @@ function detectPackageManager() {
   } else {
     cached = "npm";
   }
-  log.info(TAG6, `Detected package manager: ${cached}`);
+  log.info(TAG7, `Detected package manager: ${cached}`);
   return cached;
 }
 function installCommand(ignoreScripts = false) {
@@ -2575,7 +2781,7 @@ function spawnRunArgs(script, ...extra) {
 init_log();
 import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3 } from "node:fs";
-var TAG7 = "project-type";
+var TAG8 = "project-type";
 var _cache = new Map;
 function _resetCache() {
   _cache.clear();
@@ -2586,7 +2792,7 @@ function detect(dir) {
     return cached2;
   const result = detectUncached(dir);
   _cache.set(dir, result);
-  log.info(TAG7, `Detected project type in ${dir}: ${result.kind}`);
+  log.info(TAG8, `Detected project type in ${dir}: ${result.kind}`);
   return result;
 }
 function detectUncached(dir) {
@@ -2680,13 +2886,13 @@ function hasNodeTestScript(dir) {
     const pkg = JSON.parse(readFileSync3(`${dir}/package.json`, "utf-8"));
     script = pkg.scripts?.test;
   } catch (err) {
-    log.warn(TAG7, `Could not read package.json in ${dir}: ${err instanceof Error ? err.message : err}`);
+    log.warn(TAG8, `Could not read package.json in ${dir}: ${err instanceof Error ? err.message : err}`);
     return false;
   }
   if (typeof script !== "string" || script.trim().length === 0)
     return false;
   if (NPM_PLACEHOLDER_TEST.test(script)) {
-    log.info(TAG7, `package.json 'test' is the npm placeholder — skipping tests`);
+    log.info(TAG8, `package.json 'test' is the npm placeholder — skipping tests`);
     return false;
   }
   return true;
@@ -2697,7 +2903,7 @@ function firstNodeScript(dir, candidates) {
     const pkg = JSON.parse(readFileSync3(`${dir}/package.json`, "utf-8"));
     scripts = pkg.scripts ?? {};
   } catch (err) {
-    log.warn(TAG7, `Could not read package.json in ${dir}: ${err instanceof Error ? err.message : err}`);
+    log.warn(TAG8, `Could not read package.json in ${dir}: ${err instanceof Error ? err.message : err}`);
     return null;
   }
   for (const name of candidates) {
@@ -2716,7 +2922,7 @@ function xcodeBuildCommand(pt) {
     return null;
   const scheme = resolveXcodeScheme(pt);
   if (!scheme) {
-    log.warn(TAG7, "Could not resolve an Xcode scheme — skipping build (best-effort)");
+    log.warn(TAG8, "Could not resolve an Xcode scheme — skipping build (best-effort)");
     return null;
   }
   const containerFlag = pt.xcodeIsWorkspace ? "-workspace" : "-project";
@@ -2744,7 +2950,7 @@ function resolveXcodeScheme(pt) {
     const schemes = pt.xcodeIsWorkspace ? parsed.workspace?.schemes ?? [] : parsed.project?.schemes ?? [];
     return schemes[0] ?? null;
   } catch (err) {
-    log.warn(TAG7, `xcodebuild -list failed: ${err instanceof Error ? err.message : err}`);
+    log.warn(TAG8, `xcodebuild -list failed: ${err instanceof Error ? err.message : err}`);
     return null;
   }
 }
@@ -2753,7 +2959,7 @@ function resolveXcodeScheme(pt) {
 init_log();
 init_run_containment();
 import { execFileSync as execFileSync3 } from "node:child_process";
-var TAG8 = "revert-guard";
+var TAG9 = "revert-guard";
 var TEST_FILE = /(?:^|\/)__tests__\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
 function isTestFile(path) {
   return TEST_FILE.test(path);
@@ -2768,7 +2974,7 @@ function refetchBase(worktreePath, baseBranch) {
       stdio: "pipe"
     });
   } catch {
-    log.warn(TAG8, "Failed to re-fetch base for revert guard — using last fetch");
+    log.warn(TAG9, "Failed to re-fetch base for revert guard — using last fetch");
   }
 }
 function listDeletedFilesAgainstBase(worktreePath, baseBranch) {
@@ -2783,7 +2989,7 @@ function listDeletedFilesAgainstBase(worktreePath, baseBranch) {
     return out.split(`
 `).map((l) => l.trim()).filter((l) => l.length > 0);
   } catch (err) {
-    log.warn(TAG8, `Failed to list deleted files: ${err instanceof Error ? err.message : err}`);
+    log.warn(TAG9, `Failed to list deleted files: ${err instanceof Error ? err.message : err}`);
     return [];
   }
 }
@@ -2794,8 +3000,8 @@ function findDeletedTestFiles(worktreePath, baseBranch) {
 
 // src/verification.ts
 init_run_containment();
-var TAG9 = "verification";
-var MAX_OUTPUT_BUFFER2 = 64 * 1024 * 1024;
+var TAG10 = "verification";
+var MAX_OUTPUT_BUFFER3 = 64 * 1024 * 1024;
 async function runVerification(worktreePath, config, workerId) {
   const result = {
     passed: true,
@@ -2805,144 +3011,177 @@ async function runVerification(worktreePath, config, workerId) {
     reviewFindings: [],
     revertWarnings: []
   };
+  const sandbox = verificationSandbox(config);
   if (config.verification.revertGuard) {
-    log.info(TAG9, `[worker:${workerId}] Checking for reverted merged work...`);
+    log.info(TAG10, `[worker:${workerId}] Checking for reverted merged work...`);
     const deletedTests = findDeletedTestFiles(worktreePath, config.worktree.baseBranch);
     if (deletedTests.length > 0) {
       result.revertWarnings = deletedTests.map((f) => `Branch deletes test file '${f}' relative to current ${config.worktree.baseBranch} — ` + "likely an accidental revert of already-merged work. Restore the test or rebase on current main.");
-      log.warn(TAG9, `[worker:${workerId}] Revert guard tripped: ${deletedTests.length} deleted test file(s)`);
+      log.warn(TAG10, `[worker:${workerId}] Revert guard tripped: ${deletedTests.length} deleted test file(s)`);
       result.passed = false;
     } else {
-      log.info(TAG9, `[worker:${workerId}] Revert guard passed`);
+      log.info(TAG10, `[worker:${workerId}] Revert guard passed`);
     }
   }
   if (config.verification.build) {
-    log.info(TAG9, `[worker:${workerId}] Running build...`);
-    result.buildErrors = runBuild(worktreePath, config.verification.timeout);
+    log.info(TAG10, `[worker:${workerId}] Running build...`);
+    result.buildErrors = await runBuild(worktreePath, config.verification.timeout, sandbox);
     if (result.buildErrors.length > 0) {
-      log.warn(TAG9, `[worker:${workerId}] Build failed with ${result.buildErrors.length} error(s)`);
+      log.warn(TAG10, `[worker:${workerId}] Build failed with ${result.buildErrors.length} error(s)`);
       result.passed = false;
     } else {
-      log.info(TAG9, `[worker:${workerId}] Build passed`);
+      log.info(TAG10, `[worker:${workerId}] Build passed`);
     }
   }
   if (config.verification.test && result.buildErrors.length === 0) {
-    log.info(TAG9, `[worker:${workerId}] Running tests...`);
-    result.testFailures = runTests(worktreePath, config.verification.testTimeout);
+    log.info(TAG10, `[worker:${workerId}] Running tests...`);
+    result.testFailures = await runTests(worktreePath, config.verification.testTimeout, sandbox);
     if (result.testFailures.length > 0) {
-      log.warn(TAG9, `[worker:${workerId}] Tests failed with ${result.testFailures.length} failure(s)`);
+      log.warn(TAG10, `[worker:${workerId}] Tests failed with ${result.testFailures.length} failure(s)`);
       result.passed = false;
     } else {
-      log.info(TAG9, `[worker:${workerId}] Tests passed`);
+      log.info(TAG10, `[worker:${workerId}] Tests passed`);
     }
   }
   if (config.verification.lint) {
-    log.info(TAG9, `[worker:${workerId}] Running lint...`);
-    result.lintWarnings = runLint(worktreePath, config.verification.timeout);
+    log.info(TAG10, `[worker:${workerId}] Running lint...`);
+    result.lintWarnings = await runLint(worktreePath, config.verification.timeout, sandbox);
     if (result.lintWarnings.length > 0) {
-      log.warn(TAG9, `[worker:${workerId}] Lint found ${result.lintWarnings.length} issue(s)`);
+      log.warn(TAG10, `[worker:${workerId}] Lint found ${result.lintWarnings.length} issue(s)`);
     } else {
-      log.info(TAG9, `[worker:${workerId}] Lint passed`);
+      log.info(TAG10, `[worker:${workerId}] Lint passed`);
     }
   }
   if (config.verification.deepReview) {
-    log.info(TAG9, `[worker:${workerId}] Running deep review...`);
+    log.info(TAG10, `[worker:${workerId}] Running deep review...`);
     result.reviewFindings = await runDeepReview(worktreePath, config, workerId);
     if (result.reviewFindings.length > 0) {
-      log.warn(TAG9, `[worker:${workerId}] Deep review found ${result.reviewFindings.length} finding(s)`);
+      log.warn(TAG10, `[worker:${workerId}] Deep review found ${result.reviewFindings.length} finding(s)`);
     } else {
-      log.info(TAG9, `[worker:${workerId}] Deep review passed`);
+      log.info(TAG10, `[worker:${workerId}] Deep review passed`);
     }
   }
   return result;
 }
-function runBuild(worktreePath, timeout) {
-  const command = buildCommand(worktreePath);
-  if (!command) {
-    log.warn(TAG9, `No known build toolchain for ${worktreePath} — skipping build`);
-    return [];
+function verificationSandbox(config) {
+  const image = config.verification.sandboxImage?.trim();
+  if (!image)
+    return;
+  return { image };
+}
+async function execStep(command, args) {
+  const { worktreePath, timeout } = args;
+  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,
+      timeoutMs: timeout + SANDBOX_STARTUP_GRACE_MS
+    });
+    if (result.sandboxError) {
+      return { ok: false, sandboxError: result.sandboxError };
+    }
+    if (result.passed)
+      return { ok: true };
+    return { ok: false, err: { stdout: result.output, stderr: "" } };
   }
   try {
     execFileSync4(command.cmd, command.args, {
       cwd: worktreePath,
       timeout,
       stdio: "pipe",
-      maxBuffer: MAX_OUTPUT_BUFFER2,
+      maxBuffer: MAX_OUTPUT_BUFFER3,
       env: containedEnv()
     });
-    return [];
+    return { ok: true };
   } catch (err) {
-    return parseErrorOutput(err);
+    return { ok: false, err };
+  }
+}
+async function runBuild(worktreePath, timeout, sandbox) {
+  const command = buildCommand(worktreePath);
+  if (!command) {
+    log.warn(TAG10, `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(TAG10, `Build not verified: ${outcome.sandboxError}`);
+    return [`Build did not run: ${outcome.sandboxError}`];
+  }
+  return parseErrorOutput(outcome.err);
 }
-function runTests(worktreePath, timeout) {
+async function runTests(worktreePath, timeout, sandbox) {
   const command = testCommand(worktreePath);
   if (!command) {
-    log.warn(TAG9, `No test command for detected toolchain in ${worktreePath} — skipping tests`);
+    log.warn(TAG10, `No test command for detected toolchain in ${worktreePath} — skipping tests`);
     return [];
   }
-  try {
-    execFileSync4(command.cmd, command.args, {
-      cwd: worktreePath,
-      timeout,
-      stdio: "pipe",
-      maxBuffer: MAX_OUTPUT_BUFFER2,
-      env: containedEnv()
-    });
+  const outcome = await execStep(command, { worktreePath, timeout, sandbox });
+  if (outcome.ok)
     return [];
-  } catch (err) {
-    const output = combineOutput(err);
-    log.warn(TAG9, `Test run failed:
-${output.slice(-4000) || "(no output captured)"}`);
-    return parseTestFailures(err, timeout);
+  if (outcome.sandboxError) {
+    log.error(TAG10, `Tests not verified: ${outcome.sandboxError}`);
+    return [`Test run did not happen: ${outcome.sandboxError}`];
   }
+  const output = combineOutput(outcome.err);
+  log.warn(TAG10, `Test run failed:
+${output.slice(-4000) || "(no output captured)"}`);
+  return parseTestFailures(outcome.err, timeout);
 }
-function runFormatFix(worktreePath, timeout, workerId) {
+async function runFormatFix(worktreePath, timeout, workerId, sandbox) {
   const command = formatFixCommand(worktreePath);
   if (!command)
     return;
-  try {
-    execFileSync4(command.cmd, command.args, {
-      cwd: worktreePath,
-      timeout,
-      stdio: "pipe",
-      maxBuffer: MAX_OUTPUT_BUFFER2,
-      env: containedEnv()
-    });
-    log.info(TAG9, `[worker:${workerId}] Auto-formatted worktree before commit/push`);
-  } catch (err) {
-    log.warn(TAG9, `[worker:${workerId}] Auto-format step exited non-zero (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+  const outcome = await execStep(command, { worktreePath, timeout, sandbox });
+  if (outcome.ok) {
+    log.info(TAG10, `[worker:${workerId}] Auto-formatted worktree before commit/push`);
+    return;
   }
+  const why = outcome.sandboxError ? outcome.sandboxError : outcome.err instanceof Error ? outcome.err.message : String(outcome.err);
+  log.warn(TAG10, `[worker:${workerId}] Auto-format step did not complete (non-fatal): ${why}`);
 }
-function runLint(worktreePath, timeout) {
+async function runLint(worktreePath, timeout, sandbox) {
   const command = lintCommand(worktreePath);
   if (!command) {
-    log.info(TAG9, `No lint step for detected toolchain in ${worktreePath} — skipping lint`);
+    log.info(TAG10, `No lint step for detected toolchain in ${worktreePath} — skipping lint`);
     return [];
   }
-  try {
-    execFileSync4(command.cmd, command.args, {
-      cwd: worktreePath,
-      timeout,
-      stdio: "pipe",
-      maxBuffer: MAX_OUTPUT_BUFFER2,
-      env: containedEnv()
-    });
+  const outcome = await execStep(command, { worktreePath, timeout, sandbox });
+  if (outcome.ok)
     return [];
-  } catch (err) {
-    return parseErrorOutput(err);
+  if (outcome.sandboxError) {
+    log.error(TAG10, `Lint not verified: ${outcome.sandboxError}`);
+    return [`Lint did not run: ${outcome.sandboxError}`];
   }
+  return parseErrorOutput(outcome.err);
 }
 async function runDeepReview(worktreePath, config, workerId) {
   if (!supportsDevServer(worktreePath)) {
-    log.info(TAG9, `[worker:${workerId}] Detected non-web toolchain — skipping deep review`);
+    log.info(TAG10, `[worker:${workerId}] Detected non-web toolchain — skipping deep review`);
     return [];
   }
   const port = config.verification.devServerBasePort + workerId;
   let devServer = null;
+  const launch = devServerLaunch({
+    worktreePath,
+    port,
+    sandbox: verificationSandbox(config)
+  });
   try {
-    const [cmd, args] = spawnRunArgs("dev", "--port", String(port));
-    devServer = spawn2(cmd, args, {
+    if (launch.containerName) {
+      await removeSandboxContainer(launch.containerName);
+    }
+    devServer = spawn2(launch.cmd, launch.args, {
       cwd: worktreePath,
       stdio: ["ignore", "pipe", "pipe"],
       env: containedEnv()
@@ -2951,7 +3190,7 @@ async function runDeepReview(worktreePath, config, workerId) {
       await waitForDevServer(devServer, 30000);
       await probeDevServer(port);
     } catch (err) {
-      log.error(TAG9, `Dev server did not become ready: ${err instanceof Error ? err.message : err}`);
+      log.error(TAG10, `Dev server did not become ready: ${err instanceof Error ? err.message : err}`);
       return [];
     }
     let diff = "";
@@ -2960,7 +3199,7 @@ async function runDeepReview(worktreePath, config, workerId) {
         cwd: worktreePath,
         encoding: "utf-8",
         timeout: 30000,
-        maxBuffer: MAX_OUTPUT_BUFFER2
+        maxBuffer: MAX_OUTPUT_BUFFER3
       });
     } catch {
       diff = "(unable to retrieve diff)";
@@ -2994,17 +3233,20 @@ async function runDeepReview(worktreePath, config, workerId) {
       encoding: "utf-8",
       timeout: config.verification.timeout,
       stdio: "pipe",
-      maxBuffer: MAX_OUTPUT_BUFFER2,
+      maxBuffer: MAX_OUTPUT_BUFFER3,
       env: containedEnv()
     });
     return parseReviewFindings(output);
   } catch (err) {
-    log.error(TAG9, `Deep review failed: ${err instanceof Error ? err.message : err}`);
+    log.error(TAG10, `Deep review failed: ${err instanceof Error ? err.message : err}`);
     return [];
   } finally {
     if (devServer && !devServer.killed) {
       devServer.kill("SIGTERM");
     }
+    if (launch.containerName) {
+      await removeSandboxContainer(launch.containerName);
+    }
   }
 }
 function attemptAutoFix(worktreePath, config, errors) {
@@ -3037,12 +3279,12 @@ function attemptAutoFix(worktreePath, config, errors) {
     "--",
     fixPrompt
   ];
-  log.info(TAG9, "Spawning Claude for auto-fix...");
+  log.info(TAG10, "Spawning Claude for auto-fix...");
   execFileSync4("claude", args, {
     cwd: worktreePath,
     timeout: config.verification.timeout,
     stdio: "pipe",
-    maxBuffer: MAX_OUTPUT_BUFFER2,
+    maxBuffer: MAX_OUTPUT_BUFFER3,
     env: containedEnv()
   });
 }
@@ -3076,7 +3318,7 @@ async function reportFindings(client, cardId, result, recovery) {
     try {
       await client.createSubtask(cardId, title);
     } catch (err) {
-      log.error(TAG9, `Failed to create subtask: ${err instanceof Error ? err.message : err}`);
+      log.error(TAG10, `Failed to create subtask: ${err instanceof Error ? err.message : err}`);
     }
   }));
   if (overflow > 0) {
@@ -3084,7 +3326,7 @@ async function reportFindings(client, cardId, result, recovery) {
       await client.createSubtask(cardId, `...and ${overflow} more issues`);
     } catch {}
   }
-  log.info(TAG9, `Reported ${Math.min(items.length, maxSubtasks)} finding(s) as subtasks on card ${cardId}`);
+  log.info(TAG10, `Reported ${Math.min(items.length, maxSubtasks)} finding(s) as subtasks on card ${cardId}`);
 }
 function combineOutput(err) {
   const stderr = err?.stderr?.toString() ?? "";
@@ -3117,7 +3359,7 @@ function parseTestFailures(err, timeout) {
   }
   if (e?.code === "ENOBUFS") {
     return [
-      `Test output exceeded the ${MAX_OUTPUT_BUFFER2 / (1024 * 1024)}MB capture limit and the run was killed — ` + "the suite's real result is unknown. Quieten the reporter or raise the limit."
+      `Test output exceeded the ${MAX_OUTPUT_BUFFER3 / (1024 * 1024)}MB capture limit and the run was killed — ` + "the suite's real result is unknown. Quieten the reporter or raise the limit."
     ];
   }
   const combined = combineOutput(err);
@@ -3143,6 +3385,24 @@ class DevServerReadinessError extends Error {
     this.name = "DevServerReadinessError";
   }
 }
+function devServerLaunch(args) {
+  const [cmd, runArgs] = spawnRunArgs("dev", "--port", String(args.port), ...args.sandbox ? ["--host", SANDBOX_DEV_SERVER_BIND] : []);
+  if (!args.sandbox)
+    return { cmd, args: runArgs };
+  const containerName = devServerContainerName(args.port);
+  return {
+    cmd: "docker",
+    args: devServerSandboxArgs({
+      image: args.sandbox.image,
+      worktree: args.worktreePath,
+      command: { cmd, args: runArgs },
+      port: args.port,
+      name: containerName
+    }),
+    containerName
+  };
+}
+var DEV_SERVER_READY = /\bready\b/i;
 function waitForDevServer(proc, timeout) {
   return new Promise((resolve3, reject) => {
     let settled = false;
@@ -3172,7 +3432,7 @@ function waitForDevServer(proc, timeout) {
     }, timeout);
     const onData = (data) => {
       const text = data.toString();
-      if (text.includes("ready") || text.includes("localhost") || text.includes("Local:")) {
+      if (DEV_SERVER_READY.test(text) || text.includes("localhost") || text.includes("Local:")) {
         settleResolve();
       }
     };
@@ -3208,7 +3468,7 @@ async function probeDevServer(port, timeoutMs = 5000) {
 }
 
 // src/gate-collectors.ts
-var TAG10 = "gate-collectors";
+var TAG11 = "gate-collectors";
 async function resolveStageGate(client, card) {
   const currentStage = card.current_stage;
   const playbookId = card.playbook_id;
@@ -3226,7 +3486,7 @@ async function resolveStageGate(client, card) {
       return null;
     return { stage: resolution.stage, gate };
   } catch (err) {
-    log.warn(TAG10, `resolveStageGate failed for stage "${currentStage}": ${err instanceof Error ? err.message : err}`);
+    log.warn(TAG11, `resolveStageGate failed for stage "${currentStage}": ${err instanceof Error ? err.message : err}`);
     return null;
   }
 }
@@ -3261,8 +3521,8 @@ class BuildGreenCollector {
   async collect(_context) {
     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);
+    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;
     const result = buildPassed ? "passed" : "failed";
@@ -3358,7 +3618,7 @@ function buildGateCollectorRegistry(deps) {
 async function collectGateEvidence(registry, context) {
   const collector = registry[context.gate.kind];
   if (!collector) {
-    log.info(TAG10, `No collector for gate kind "${context.gate.kind}" — reporting blocked`);
+    log.info(TAG11, `No collector for gate kind "${context.gate.kind}" — reporting blocked`);
     return {
       result: "blocked",
       structured: {
@@ -3370,14 +3630,14 @@ async function collectGateEvidence(registry, context) {
     return await collector.collect(context);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    log.warn(TAG10, `Collector for "${context.gate.kind}" threw: ${msg} — reporting blocked`);
+    log.warn(TAG11, `Collector for "${context.gate.kind}" threw: ${msg} — reporting blocked`);
     return { result: "blocked", structured: { error: msg } };
   }
 }
 
 // src/harmony-client.ts
 init_log();
-var TAG11 = "harmony-client";
+var TAG12 = "harmony-client";
 function readClientConfig(env) {
   const apiUrl = env.HARMONY_API_URL?.trim();
   const apiKey = env.HARMONY_API_KEY?.trim();
@@ -3429,7 +3689,7 @@ class HarmonyClient {
       purpose: "gate_evaluation"
     });
     if (!response.ok) {
-      log.warn(TAG11, `Oracle fetch for stage ${stageId} returned ${response.status} — no oracle read, the gate will report blocked`);
+      log.warn(TAG12, `Oracle fetch for stage ${stageId} returned ${response.status} — no oracle read, the gate will report blocked`);
       return null;
     }
     const body = await response.json();
@@ -3513,7 +3773,7 @@ function relayAgentEvent(draft) {
 // src/stage-cli.ts
 init_dist();
 init_runner();
-var STAGE_RUN_USAGE = "usage: harmony-harness stage run --card <id> --stage <id> --workspace <id> --repo <path> --session <id> [--metrics <json-path>]";
+var STAGE_RUN_USAGE = "usage: harmony-harness stage run --card <id> --stage <id> --workspace <id> --repo <path> --session <id> [--metrics <json-path>] [--sandbox-image <image>]";
 function readFlag(argv, name) {
   const index = argv.indexOf(`--${name}`);
   if (index === -1)
@@ -3538,7 +3798,7 @@ function parseStageRunArgs(argv) {
     ["repoPath", "repo"],
     ["sessionId", "session"]
   ];
-  const args = { metricsPath: null };
+  const args = { metricsPath: null, sandboxImage: null };
   for (const [field, flag] of fields) {
     const value = readFlag(argv, flag);
     if (value === null) {
@@ -3553,6 +3813,16 @@ function parseStageRunArgs(argv) {
     }
     args.metricsPath = metricsPath;
   }
+  if (argv.includes("--sandbox-image")) {
+    const sandboxImage = readFlag(argv, "sandbox-image");
+    if (sandboxImage === null) {
+      return {
+        ok: false,
+        message: "missing value for --sandbox-image <image>"
+      };
+    }
+    args.sandboxImage = sandboxImage;
+  }
   return { ok: true, args };
 }
 function parseMetricsAllowlist(raw, sourcePath) {
@@ -3713,7 +3983,7 @@ async function runStage(request, deps) {
 }
 
 // src/cli.ts
-var TAG12 = "cli";
+var TAG13 = "cli";
 var GATE_VERIFICATION_TIMEOUT_MS = 600000;
 var SHUTDOWN_HARD_EXIT_MS = 15000;
 var activeRunner = null;
@@ -3744,12 +4014,12 @@ async function runRole(request, prompt, emit2) {
   });
   const runner = new SdkAgentRunner(launch.config);
   activeRunner = runner;
-  log.info(TAG12, `Running stage ${request.stageId} as role ${launch.role ?? "(none — fail-closed)"}`);
+  log.info(TAG13, `Running stage ${request.stageId} as role ${launch.role ?? "(none — fail-closed)"}`);
   const timeoutMs = stageTimeoutMs(process.env);
   let timedOut = false;
   const clock = timeoutMs > 0 ? setTimeout(() => {
     timedOut = true;
-    log.warn(TAG12, `stage ${request.stageId} exceeded ${timeoutMs}ms — stopping the subagent`);
+    log.warn(TAG13, `stage ${request.stageId} exceeded ${timeoutMs}ms — stopping the subagent`);
     runner.stop("timeout");
   }, timeoutMs) : null;
   clock?.unref?.();
@@ -3765,9 +4035,9 @@ async function runRole(request, prompt, emit2) {
       if (relayed)
         emit2(relayed);
       if (event.kind === "error") {
-        log.warn(TAG12, `subagent error: ${event.payload.message}`);
+        log.warn(TAG13, `subagent error: ${event.payload.message}`);
       } else {
-        log.event(TAG12, `subagent ${event.kind}`);
+        log.event(TAG13, `subagent ${event.kind}`);
       }
     }
   } finally {
@@ -3795,7 +4065,16 @@ ${STAGE_RUN_USAGE}
 `);
     process.exit(2);
   }
-  const { cardId, stageId, workspaceId, repoPath, sessionId, metricsPath } = parsed.args;
+  const {
+    cardId,
+    stageId,
+    workspaceId,
+    repoPath,
+    sessionId,
+    metricsPath,
+    sandboxImage
+  } = parsed.args;
+  const gateSandbox = sandboxImage?.trim() ? { image: sandboxImage.trim() } : undefined;
   let driverMetrics = {};
   if (metricsPath !== null) {
     const { readFileSync: readFileSync4 } = await import("node:fs");
@@ -3838,7 +4117,8 @@ ${STAGE_RUN_USAGE}
         build: {
           worktreePath: req.repoPath,
           buildTimeout: GATE_VERIFICATION_TIMEOUT_MS,
-          lintTimeout: GATE_VERIFICATION_TIMEOUT_MS
+          lintTimeout: GATE_VERIFICATION_TIMEOUT_MS,
+          sandbox: gateSandbox
         },
         command: {
           worktreePath: req.repoPath,
@@ -3847,6 +4127,7 @@ ${STAGE_RUN_USAGE}
         oracle: {
           repoPath: req.repoPath,
           sessionId: req.sessionId,
+          sandbox: gateSandbox,
           targetStageId: oracleTargetStageId,
           fetchOracle: (oracleCardId, oracleStageId, oracleSessionId) => client.fetchOracle(oracleCardId, oracleStageId, oracleSessionId),
           place,