@gethmy/harness 1.6.0 → 1.7.0

package/src/oracle.ts

@@ -64,7 +64,8 @@
  * Failing the gate rather than writing is the point.
  */
 import type { ChildProcess } from "node:child_process";
-import { lstatSync, readFileSync, statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import {
   chmod,
   lstat,
@@ -77,9 +78,18 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
-import { DEFAULT_METRIC_TIMEOUT_MS } from "./exec-types.js";
+import {
+  DEFAULT_METRIC_TIMEOUT_MS,
+  SANDBOX_STARTUP_GRACE_MS,
+} from "./exec-types.js";
 import { log } from "./log.js";
 import { reapGroup, spawnInGroup, terminateGroup } from "./process-group.js";
+import {
+  removeSandboxContainer,
+  sandboxAvailable,
+  sandboxRunArgs,
+} from "./repair-sandbox.js";
+import { heldTestEnvKeysToStrip } from "./run-containment.js";
 
 const TAG = "oracle";
 
@@ -96,8 +106,67 @@ export interface HeldOracle {
   runnerHint: string | null;
 }
 
+/**
+ * The container the held test runs in, or `undefined` for the host (#1021).
+ *
+ * Same shape and same config value as `VerificationSandbox` — one
+ * `verification.sandboxImage` covers every command the gate machinery runs
+ * against a worktree, because they all need exactly the same thing from the
+ * image: the repo's toolchain and nothing else. A second knob would let an
+ * operator contain the build and leave the held test on the host, which is the
+ * combination with the worst reasoning behind it.
+ *
+ * A distinct type rather than an import of `VerificationSandbox` would be two
+ * names for one thing; a shared one is used instead.
+ */
+export type HeldOracleSandbox = { image: string };
+
+/**
+ * The held test could not be RUN AS CONFIGURED — the container runtime is not
+ * answering, or the image cannot start / does not carry the runner (#1021).
+ *
+ * A distinct class because the collector has to mark it (#823 rule 1): this is
+ * static operator configuration, so re-running the stage cannot change the
+ * answer, and an unmarked `blocked` spends the card's whole attempt budget
+ * rediscovering it — which is exactly the failure #823 exists to prevent, and
+ * which containment would otherwise have introduced a fresh instance of.
+ *
+ * "Docker is not running" is static in the only sense that matters here: no
+ * number of retries fixes it, a person does.
+ */
+export class OracleSandboxConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OracleSandboxConfigError";
+  }
+}
+
+/** Options for {@link runHeldOracle}. */
+export interface RunHeldOracleOptions {
+  /** Wall-clock cap. Defaults to {@link DEFAULT_METRIC_TIMEOUT_MS}. */
+  timeoutMs?: number;
+  /**
+   * Run the held test in this container instead of in the motor's own process
+   * tree (#1021). `undefined` ⇒ the host, which is the default.
+   */
+  sandbox?: HeldOracleSandbox;
+}
+
 export interface OracleDeps {
   repoPath: string;
+  /**
+   * The container the held test runs in (#1021), threaded from the driver's
+   * `--sandbox-image`. Absent ⇒ the host path, which is what a person running
+   * the CLI against their own checkout gets.
+   *
+   * It lives on the DEPS rather than being bound into `run` at the call site,
+   * because a bound closure is a wiring that only a source scan can check. Here
+   * the collector reads `this.deps.sandbox` and passes it, so a test that
+   * injects a fake `run` sees whether the image actually arrived — the
+   * distinction between a parameter existing and a parameter being passed,
+   * which this repo has already shipped wrong once (#1036).
+   */
+  sandbox?: HeldOracleSandbox;
   /**
    * The card's ACTIVE agent session id — see the module doc comment above for
    * why this lives here rather than on `GateEvidenceContext`. Threaded straight
@@ -139,6 +208,7 @@ export interface OracleDeps {
   run(
     repoPath: string,
     oracle: HeldOracle,
+    options?: RunHeldOracleOptions,
   ): Promise<{
     exitCode: number;
     /** stdout + stderr merged, for the operator's log. Never the verdict. */
@@ -429,27 +499,69 @@ const ORACLE_RUNNERS: Record<string, OracleRunnerSpec> = {
  *     `reproduced` red gate AND a passing green gate from one file.
  *
  * {@link assertUntampered} refuses that one shape, because both ways of making
- * it stick change a mode the motor set. It does NOT close the class, and the
- * cheapest bypass needs no mode change and no race at all: the held test
- * pre-writes the report and then stops the runner from writing its own.
- * `process.exit(0)` in the test body is enough — measured, 3 runs of 3 under
- * bun, giving `{ total: 1, failed: 1 }` with exit 0, which is `reproduced` from
- * the red gate AND a pass from the green one. Under vitest the same trick yields
- * the same forged counts. `oracle-run.test.ts` pins that this is still open, so
- * the description cannot quietly drift back to "closed".
- *
- * Two other reasons not to read the check as a boundary: `statSync` follows
- * symlinks, so REPLACING the directory (rmdir + mkdir 0700, or a symlink) leaves
- * every mode the motor set intact; and a mode change is restorable by a
- * grandchild that waits for the runner to exit and chmods back.
- *
- * So the accurate summary, and what the docs say: this gate is evidence against
- * a CARELESS author, not against a hostile one, and the mode check raises the
- * cost of one attack rather than establishing a property. Anything short of not
- * running the held test as the motor's own user is a mitigation — the sandbox
- * `repair-sandbox.ts` (#1015) already uses for untrusted code, with the report
- * read from outside it, is the actual fix. Tracked at card #1021; see
- * `docs/agent-daemon.md`.
+ * it stick change a mode the motor set. It does NOT close the class, and it is
+ * not a boundary: `statSync` follows symlinks, so REPLACING the directory
+ * (rmdir + mkdir 0700, or a symlink) leaves every mode the motor set intact, and
+ * a mode change is restorable by a grandchild that waits for the runner to exit
+ * and chmods back.
+ *
+ * ---
+ *
+ * WHAT #1021 CHANGED, and it is two separate things because the two attacks are
+ * not one attack.
+ *
+ * **1. A report the exit code contradicts is refused** ({@link
+ * assertConsistentWithExit}). Measured against both allow-listed runners: a run
+ * in which the runner reports a failing test exits NON-ZERO. So `failed > 0`
+ * from a process that exited 0 is a state neither runner produces, whoever wrote
+ * the file and whenever they wrote it — which kills the `process.exit(0)`
+ * pre-write and the sprayer with one rule, on the host as well as in the
+ * container, needing no configuration at all. `oracle-run.test.ts` runs both as
+ * real hostile held tests.
+ *
+ * This is a CLAIM check and deliberately not an authentication check, because
+ * authentication is unavailable here in principle: the held test executes INSIDE
+ * the runner's process, so any secret the motor handed the runner to sign its
+ * report with would be readable by the held test — a hash, an HMAC or a nonce
+ * buys nothing.
+ *
+ * What it costs the attacker, exactly: it does NOT make the report authentic. A
+ * held test can still pre-write `failed = 1` and exit non-zero, which is
+ * self-consistent. What it removes is the FREE version — one file satisfying the
+ * red gate (`reproduced`) and the green gate (exit 0) out of a single run. After
+ * it, a held test that wants both polarities must exit differently before and
+ * after the fix, i.e. be sensitive to the tree, which is the whole content of
+ * the red-green contract.
+ *
+ * **2. The run can be moved off the motor's host** (`spawnHeldOracle`, opt-in
+ * behind `verification.sandboxImage`). Both polarities then run inside
+ * `repair-sandbox.ts`'s container: the worktree and the report directory are the
+ * only mounts, and there is no network, no host home, no credential file and no
+ * Docker socket. #988 could not use that container for the agent spawn because
+ * an agent needs the model API and the first flag is `--network=none`; the held
+ * test needs no network, which is exactly what makes it fit here. It also ends
+ * the straggler class by construction: a `setsid` grandchild escapes the motor's
+ * process group on the host and can rewrite the report at any later moment,
+ * while inside the container it is killed with the PID namespace before
+ * `docker run` returns.
+ *
+ * The container does NOT make the report file unforgeable, and nothing here
+ * should be read as saying so — the held test holds every capability the runner
+ * holds inside it too. Containment relocates the shared channel; it does not
+ * unshare it. That is what (1) is for.
+ *
+ * MEASURED COST, macOS / Docker Desktop 29.7.2, warm `oven/bun:1`, the real
+ * worktree bind-mounted: a trivial held test 0.01 s on the host and 0.14–0.18 s
+ * contained (~0.14 s added); one that resolves a dependency with the repo's real
+ * `node_modules` mounted, 0.05–0.08 s against 1.37–1.89 s (~1.4 s added). Two
+ * gate evaluations per card, so ~0.3 s to ~3 s per card, scaling with what the
+ * held test's imports touch over the virtualized filesystem.
+ *
+ * So the accurate summary, and what the docs say: the gate now claims "the
+ * authored test ran, and the runner's own report said it failed, on a run whose
+ * exit code agrees". A test that fakes tree-sensitivity by reading the diff
+ * rather than the behaviour is a bad test, and no gate mechanism grades test
+ * quality. See `docs/agent-daemon.md`.
  */
 
 /**
@@ -769,20 +881,38 @@ function argvPath(path: string): string {
  *      `reapGroup` when the promise settles — clean exit included.
  *   3. **Non-blocking.** Nothing here occupies the event loop.
  *
- * `timeoutMs` defaults to the motor's existing {@link DEFAULT_METRIC_TIMEOUT_MS}
- * rather than a second convention; the parameter exists so a test can use a
- * short cap.
+ * `options.timeoutMs` defaults to the motor's existing
+ * {@link DEFAULT_METRIC_TIMEOUT_MS} rather than a second convention; the option
+ * exists so a test can use a short cap. `options.sandbox` moves the whole run
+ * into a container (#1021) — see {@link spawnHeldOracle}.
  */
 export async function runHeldOracle(
   repoPath: string,
   oracle: HeldOracle,
-  timeoutMs: number = DEFAULT_METRIC_TIMEOUT_MS,
+  options: RunHeldOracleOptions = {},
 ): Promise<{
   exitCode: number;
   output: string;
   verdict: string;
   report: OracleRunSummary | null;
 }> {
+  const heldTestTimeoutMs = options.timeoutMs ?? DEFAULT_METRIC_TIMEOUT_MS;
+  // Refuse BEFORE the temp directory, for the same reason the runner is
+  // resolved first: an operator who configured an image asked for the held test
+  // to run without their credentials in scope, and running it on the host
+  // because Docker happened to be down would hand back exactly the exposure the
+  // image was set to remove — invisibly. `execStep` (verification.ts) refuses
+  // the same way and says so in the same words; the two must not diverge.
+  //
+  // A rejection is `blocked` at the collector, never `failed`: the branch is
+  // not at fault for the operator's container runtime.
+  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",
+    );
+  }
   // Resolve the runner BEFORE creating anything: an unknown hint must reject
   // without leaving a temp directory behind (and without spawning, which the
   // "rejects an unknown hint before it spawns anything" test pins).
@@ -795,16 +925,34 @@ export async function runHeldOracle(
   // all.
   //
   // `mkdtemp` randomizes the SUFFIX and creates the directory 0700. Neither
-  // hides the path from the held test: the prefix is a fixed string and
-  // `readdirSync(tmpdir())` enumerates the directory in one call, 0700 included
-  // (the held test runs as the motor's own user, who owns it). This was measured,
-  // not assumed. So the randomness is not a secret and nothing here should be
-  // read as one — see `assertUntampered` for what actually defends the file, and
-  // the comment above `OracleRunnerSpec` for what remains open.
+  // hides the path from the held test, on the host or in the container: on the
+  // host the prefix is a fixed string and `readdirSync(tmpdir())` enumerates the
+  // directory in one call, 0700 included (the held test runs as the motor's own
+  // user, who owns it); in the container the path is a fixed mount point AND is
+  // spelled out in the runner's own argv, which the held test can simply read.
+  // This was measured, not assumed. So the randomness is not a secret and
+  // nothing here should be read as one — see `assertConsistentWithExit` for what
+  // actually defends the VERDICT, and the comment above `OracleRunnerSpec` for
+  // what remains open.
   const reportDir = await mkdtemp(join(tmpdir(), reportDirPrefix()));
   const reportPath = join(reportDir, spec.report.file);
   try {
-    return await spawnHeldOracle(spec, repoPath, oracle, reportPath, timeoutMs);
+    return await spawnHeldOracle({
+      spec,
+      repoPath,
+      oracle,
+      reportPath,
+      // The HELD TEST'S own cap, plus what the container costs to start — the
+      // same shape `execStep` uses, and for the same reason: the cap an
+      // operator (or a test) chose governs the test, and turning containment on
+      // must not silently redefine it. Measured at ~5.4 s of start-up on macOS
+      // / Docker Desktop with a warm image; the grace is that with an order of
+      // magnitude of head-room, not a budget.
+      timeoutMs: sandbox
+        ? heldTestTimeoutMs + SANDBOX_STARTUP_GRACE_MS
+        : heldTestTimeoutMs,
+      sandbox,
+    });
   } finally {
     await removeReportDir(reportDir);
   }
@@ -844,16 +992,18 @@ function reportDirPrefix(): string {
  *     `process.exit(0)` in the held test skips the reporter's write entirely and
  *     leaves the forgery as the only file on disk, at ordinary modes inside a
  *     still-0700 directory. Measured under both runners. This is CHEAPER than
- *     the attack above, so the check below is one shape of an open class.
+ *     the attack above, and it is what {@link assertConsistentWithExit} closes
+ *     (#1021) — by reading the report's CLAIM against the exit code rather than
+ *     by looking at the file at all.
  *   - **Replacing the directory.** `statSync` follows symlinks, so an rmdir +
  *     mkdir 0700, or a symlink to the attacker's own directory, changes no mode
  *     the motor set.
  *   - **Restoring the mode.** A grandchild that waits for the runner to exit and
  *     chmods back defeats the file-mode arm.
  *
- * Mode checks raise the cost of one attack; they are not a boundary. The only
- * boundary is not running the held test as the motor's user at all — see the
- * comment above `OracleRunnerSpec` and card #1021.
+ * Mode checks raise the cost of one attack; they are not a boundary. See the
+ * comment above `OracleRunnerSpec` for what is, and for why the container this
+ * can now run in does not make the FILE unforgeable either.
  *
  * The exact-0700 requirement is deliberate but is a false-positive risk worth
  * knowing about: `mkdtemp` asks for 0700 through `mkdir`, so an exotic umask
@@ -862,6 +1012,13 @@ function reportDirPrefix(): string {
  * runners were measured writing the report 0644 inside a 0700 directory under a
  * normal umask. `captureReport` logs the refusal reason so that case is
  * diagnosable rather than silent.
+ *
+ * One more caveat since #1021: on the CONTAINER path the report directory is a
+ * bind mount, and a `chmod` from inside the container is not guaranteed to
+ * reach the host inode on a virtualized filesystem (Docker Desktop's). So this
+ * check may simply see nothing there. That is a reason not to lean on it, not a
+ * regression — `assertConsistentWithExit` is the one that does not depend on
+ * how the filesystem is plumbed.
  */
 function assertUntampered(reportPath: string): void {
   const dir = statSync(dirname(reportPath));
@@ -884,6 +1041,66 @@ function assertUntampered(reportPath: string): void {
   }
 }
 
+/**
+ * Refuse a report whose CLAIM the run's own exit code contradicts (#1021).
+ *
+ * ## Why a claim check and not an authentication check
+ *
+ * The held test executes INSIDE the runner's process — `bun test` and `vitest`
+ * both load the file into themselves — so it holds every capability the runner
+ * holds: the same uid, the same open files, the same argv, the same memory.
+ * There is therefore no secret the motor can hand the runner that the held test
+ * cannot read back, which is why a hash, an HMAC or a nonce over the report
+ * file buys nothing here: whatever would sign the real report signs a forged one
+ * just as happily. A container does not change that either — it relocates the
+ * shared channel, it does not unshare it.
+ *
+ * What the motor CAN check is agreement between two things the held test
+ * controls but cannot make agree in its own favour:
+ *
+ *   - the report's claim that N tests failed, and
+ *   - the exit code the process actually left with, which the OS reports and
+ *     nothing in the run gets to rewrite afterwards.
+ *
+ * Measured against both allow-listed runners: a run in which the runner
+ * reports a failing test exits NON-ZERO. So `failed > 0` from a process that
+ * exited 0 is a state neither runner produces, and the only way to reach it is
+ * for something other than the runner to have written the file. The cheap
+ * forgery — pre-write the report, then `process.exit(0)` so the reporter never
+ * runs — lands exactly there, and so does the sprayer that overwrites the real
+ * report of a green run.
+ *
+ * ## What it costs the attacker, stated exactly
+ *
+ * It does NOT make the report authentic. A held test can still pre-write
+ * `failed = 1` and exit NON-ZERO, and that pair is self-consistent. What it
+ * loses is the free version: one file that satisfies the red gate (`reproduced`)
+ * and the green gate (exit 0) out of a single run. After this, a held test that
+ * wants both polarities must exit differently before and after the fix — i.e.
+ * it must be sensitive to the tree, which is the whole content of the red-green
+ * contract. A test that fakes that sensitivity (by reading the diff rather than
+ * the behaviour) is a bad test, and no gate mechanism can grade test quality.
+ *
+ * ## Why the safe direction is a refusal
+ *
+ * `null` ⇒ `no_verdict` ⇒ `blocked`, which can never satisfy a gate. If a
+ * future runner ever legitimately exits 0 with a failing test in its report
+ * (none does today), this refuses a run it should have graded — a cost, never
+ * an over-grant. `oracle_passed` reads the exit code alone and is unaffected.
+ */
+function assertConsistentWithExit(
+  summary: OracleRunSummary | null,
+  exitCode: number | null,
+): void {
+  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",
+    );
+  }
+}
+
 /**
  * Delete the report directory. Attempted on EVERY path — completion, rejection,
  * timeout — because the report is secret-bearing for one of the two runners:
@@ -914,24 +1131,149 @@ async function removeReportDir(reportDir: string): Promise<void> {
   }
 }
 
+/**
+ * Where the report directory is mounted inside the sandbox (#1021).
+ *
+ * A fixed path, and deliberately not under `/tmp`: the container's `HOME` is
+ * `/tmp` (see `sandboxRunArgs`), and a report living under a directory the
+ * runner's own toolchain writes into is one more thing that can collide.
+ *
+ * It is NOT a secret, and nothing here should be read as treating it as one —
+ * the path is spelled out in the runner's argv, which the held test can read
+ * from `process.argv` without looking at the filesystem at all.
+ */
+const ORACLE_REPORT_MOUNT = "/harmony-oracle-report";
+
+/**
+ * `docker run`'s own failure codes, as opposed to the command's.
+ *
+ * 125 is docker refusing to start a container (unknown image, bad flag); 126
+ * and 127 are the container starting and the ENTRYPOINT being unusable or
+ * absent — which for us means the image does not carry `bun` / `npx`. All three
+ * are the operator's container setup, not the branch's code, so they REJECT
+ * (⇒ `blocked`) rather than returning an exit code the green gate would read as
+ * `failed` and charge to the implementer.
+ *
+ * A held test can reach these codes deliberately with `process.exit(125)`, and
+ * that is fine: it converts its own run into `blocked`, which can never satisfy
+ * either gate. Trading a `failed` for a `blocked` is the safe direction.
+ */
+const DOCKER_SELF_FAILURE_CODES = new Set([125, 126, 127]);
+
+/**
+ * The `docker run` argv for a held-test run, as a PURE function so the two
+ * things a test has to be able to see are visible without a container:
+ *
+ *   1. the report directory is mounted, and
+ *   2. the runner is told to write to the MOUNT POINT, not to the host path,
+ *      which does not exist inside the container and would silently produce
+ *      "the runner wrote no report" ⇒ a permanently blocked gate.
+ *
+ * The flag set itself is `sandboxRunArgs`' and is tested there — this adds a
+ * mount and nothing else. Paths must already be realpath'd by the caller: on
+ * macOS `os.tmpdir()` is reached through a symlink, and Docker resolves mount
+ * sources rather than following them.
+ */
+export function heldOracleSandboxArgv(args: {
+  image: string;
+  /** Realpath'd worktree. */
+  worktree: string;
+  /** Realpath'd host directory holding the report. */
+  reportDir: string;
+  /** The report's file name inside that directory. */
+  reportFile: string;
+  /** The runner's own command and args, WITHOUT the report flags. */
+  runner: OracleRunnerArgv;
+  /** Extra argv the runner needs to write its report, given a path. */
+  reportFlags: (reportPath: string) => string[];
+  containerName?: string;
+}): { command: string; args: string[]; reportPathInContainer: string } {
+  const reportPathInContainer = join(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,
+  };
+}
+
 /**
  * The supervised spawn half of {@link runHeldOracle}, split out so the report
  * directory's lifetime is a plain `try`/`finally` in one place rather than a
  * cleanup duplicated down every settle path.
+ *
+ * ## The container (#1021), and what it is and is not for
+ *
+ * With `sandbox` set, the argv becomes `docker run …` around the same runner
+ * argv, built by `repair-sandbox.ts`'s `sandboxRunArgs` so the flag set is the
+ * one that module documents and tests — `--network=none`, `--cap-drop=ALL`,
+ * `--security-opt=no-new-privileges`, memory and pid caps, no Docker socket, no
+ * host home. #988 could not use that container for the agent spawn because the
+ * agent needs the model API and the first flag is `--network=none`. The held
+ * test needs no network at all, which is exactly what makes the same container
+ * fit here.
+ *
+ * Everything else about this function is unchanged, and that is the point of
+ * doing it this way rather than through `runInSandbox`: the group leadership,
+ * the timeout escalation, the drain window, the per-runner stream split and the
+ * at-exit report read all still apply, because only `command` and `args`
+ * differ. `runInSandbox` returns `{ passed, output }`, which drops the exit code
+ * the green gate grades and merges the two streams the operator's log keeps
+ * apart.
+ *
+ * What the container buys, stated exactly so it is not read as more:
+ *
+ *   - The held test can no longer reach the MOTOR. No credential file, no other
+ *     worktree, no `~/.ssh`, no daemon process — the mounts are the worktree and
+ *     the report directory, and nothing else exists.
+ *   - No straggler survives it. A detached grandchild `setsid`s out of the
+ *     motor's process group on the host and can rewrite the report at any later
+ *     moment; inside the container it is in a PID namespace that the kernel
+ *     tears down when PID 1 exits, and `docker run` does not return until that
+ *     has happened. The spray window closes by construction rather than by
+ *     timing.
+ *   - It does NOT make the report file unforgeable. The held test runs inside
+ *     the runner process, so it can write the report in the container exactly as
+ *     it could on the host. {@link assertConsistentWithExit} is what answers
+ *     that, on both paths.
+ *
+ * TWO MOUNTS, both read-write, and both earn it: the worktree because a runner
+ * writes caches and the held test lives there, and the report directory because
+ * the runner writes the report and the motor reads it from outside. The
+ * container's report path is the mount point; the motor's is the host directory,
+ * and the two are kept apart in the signature below rather than by convention.
  */
-async function spawnHeldOracle(
-  spec: OracleRunnerSpec,
-  repoPath: string,
-  oracle: HeldOracle,
-  reportPath: string,
-  timeoutMs: number,
-): Promise<{
+async function spawnHeldOracle(args_: {
+  spec: OracleRunnerSpec;
+  repoPath: string;
+  oracle: HeldOracle;
+  /** The report's path ON THE HOST — what the motor stats, reads and cleans up. */
+  reportPath: string;
+  timeoutMs: number;
+  sandbox: HeldOracleSandbox | undefined;
+}): Promise<{
   exitCode: number;
   output: string;
   verdict: string;
   report: OracleRunSummary | null;
 }> {
-  const { command, args: baseArgs } = spec.argv(argvPath(oracle.path));
+  const { spec, repoPath, oracle, reportPath, timeoutMs, sandbox } = args_;
+  const runner = spec.argv(argvPath(oracle.path));
+
+  // Named so a timed-out container can be torn down: the timeout kills the
+  // `docker` CLI, and `--rm` only cleans up a container that EXITS. Without the
+  // name there is no handle left on a container still running with the
+  // operator's worktree mounted.
+  const containerName = sandbox ? `harmony-oracle-${randomUUID()}` : null;
+
   // The report flags ride on BOTH gate polarities, not just the red one. #921
   // kept the two polarities on one argv on purpose, so the security-reviewed
   // allow-list stays a single shape per runner; making the report conditional
@@ -944,7 +1286,27 @@ async function spawnHeldOracle(
   // problem with the motor's temp dir rather than with the diff. That has not
   // been seen outside a deliberately broken temp dir, and the alternative (two
   // argv shapes) was judged worse, but it is the trade being made.
-  const args = [...baseArgs, ...spec.report.flags(reportPath)];
+  //
+  // `realpathSync` on the mount sources: on macOS `os.tmpdir()` sits under
+  // `/var/folders/...`, reached through the `/var` -> `/private/var` symlink,
+  // and Docker's file sharing resolves mount sources rather than following
+  // them. A symlinked source is the difference between a working mount and an
+  // empty directory in the container, which would read as "the runner wrote no
+  // report" — safe, but a mystery to debug.
+  const { command, args } = sandbox
+    ? heldOracleSandboxArgv({
+        image: sandbox.image,
+        worktree: realpathSync(repoPath),
+        reportDir: realpathSync(dirname(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<{
     exitCode: number;
@@ -957,6 +1319,19 @@ async function spawnHeldOracle(
       child = spawnInGroup(command, args, {
         cwd: repoPath,
         stdio: ["ignore", "pipe", "pipe"],
+        // The held test is arbitrary code from an untrusted author, and this
+        // spawn used to pass no `env` at all — so it inherited the daemon's
+        // whole environment (#1021).
+        //
+        // `stripEnvKeys`, NOT a narrowed `env`: `spawnInGroup` merges
+        // `process.env` back on top of whatever `env` it is handed, so an `env`
+        // built by removing keys is INERT there. That is not hypothetical —
+        // `review-worker.ts` shipped exactly that spelling, and its dev server
+        // carried the daemon's credentials for as long as it did.
+        //
+        // On the container path this governs the DOCKER CLI's environment; the
+        // container itself gets only `HOME=/tmp`, per `sandboxRunArgs`.
+        stripEnvKeys: heldTestEnvKeysToStrip(),
       });
     } catch (err) {
       // A synchronous spawn throw (unusable cwd, bad argv) — no group exists.
@@ -1022,14 +1397,23 @@ async function spawnHeldOracle(
      * Every failure is `null`, which `gradeOracleRed` maps to `no_verdict` ⇒
      * `blocked`: the runner never wrote a report (measured — bun writes none at
      * all for an unmatched path or a file with no tests), the content is
-     * malformed, the parser does not recognize the shape, or the file shows
-     * signs of tampering. Never a pass.
+     * malformed, the parser does not recognize the shape, the file shows signs
+     * of tampering, or its CLAIM contradicts the exit code the run left with
+     * (#1021). Never a pass.
+     *
+     * The exit code is the reason this takes a parameter. It is the one channel
+     * the held test cannot rewrite after the fact, so it is what the report is
+     * checked against — see {@link assertConsistentWithExit}.
      */
     let report: OracleRunSummary | null = null;
-    const captureReport = (): void => {
+    const captureReport = (exitCode: number | null): void => {
       try {
         assertUntampered(reportPath);
-        report = spec.report.parse(readFileSync(reportPath, "utf8"));
+        const parsed = spec.report.parse(readFileSync(reportPath, "utf8"));
+        // BEFORE the assignment, so a refused report leaves `report` null
+        // rather than briefly holding forged counts.
+        assertConsistentWithExit(parsed, exitCode);
+        report = parsed;
       } catch (err) {
         report = null;
         // Never silent. This is the module's only tamper DETECTOR, and a
@@ -1138,6 +1522,22 @@ async function spawnHeldOracle(
         settle(new Error(`the held test was terminated by signal ${signal}`));
         return;
       }
+      if (sandbox && DOCKER_SELF_FAILURE_CODES.has(code)) {
+        // The container never ran the runner: no image, an unusable flag, or an
+        // image with no `bun` / `npx` on it. That is the operator's setup and
+        // not the branch's code, so it must not reach the green gate as an exit
+        // code — `oracle_passed` reads exit codes alone and would report
+        // `failed`, blaming the implementer and spending an attempt. A
+        // rejection is `blocked` instead, which holds. Same distinction
+        // `runInSandbox`'s `sandboxError` draws for the repair path.
+        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(),
@@ -1154,7 +1554,7 @@ async function spawnHeldOracle(
       // FIRST, before anything that yields: the runner has written its report
       // and exited, so this is the moment the file is both complete and not yet
       // reachable by a straggler. See `captureReport`.
-      captureReport();
+      captureReport(code);
       // The timeout governs the RUN, which is over. Disarm it so a slow pipe
       // drain cannot turn a finished run into a reported timeout.
       if (timer) clearTimeout(timer);
@@ -1179,7 +1579,18 @@ async function spawnHeldOracle(
           // terminateGroup swallows its own signal errors; guard anyway so a
           // rejection can never strand the promise unsettled.
         })
-        .then(() => {
+        .then(async () => {
+          // On the container path what just died is the `docker` CLI, not the
+          // container it launched — `--rm` only reclaims one that EXITS. Left
+          // alone, a timed-out held test keeps running with the operator's
+          // worktree mounted, once per gate evaluation, and the gate retries.
+          // `repair-sandbox.ts` documents the same failure for the repair path;
+          // the teardown is shared rather than re-implemented.
+          //
+          // Awaited before the settle so the removal is not racing the caller's
+          // own cleanup of the report directory, which the container still has
+          // mounted.
+          if (containerName) await removeSandboxContainer(containerName);
           settle(
             new Error(`the held test did not finish within ${timeoutMs}ms`),
           );