@gethmy/harness 1.5.0 → 1.7.0

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,14 @@ import {
   supportsDevServer,
   testCommand,
 } from "./project-type.js";
+import {
+  devServerContainerName,
+  devServerSandboxArgs,
+  removeSandboxContainer,
+  runInSandbox,
+  SANDBOX_DEV_SERVER_BIND,
+  sandboxAvailable,
+} from "./repair-sandbox.js";
 import { findDeletedTestFiles } from "./revert-guard.js";
 import {
   containedEnv,
@@ -63,6 +75,13 @@ 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. `runDeepReview` resolves the same value for its dev server
+  // (#1037) rather than taking it from here, because it is also called directly
+  // by the review path — one key, six commands.
+  const sandbox = verificationSandbox(config);
+
   if (config.verification.revertGuard) {
     log.info(TAG, `[worker:${workerId}] Checking for reverted merged work...`);
     const deletedTests = findDeletedTestFiles(
@@ -89,7 +108,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 +130,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 +149,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 +182,188 @@ export async function runVerification(
 }
 
 /**
- * ## The verification steps run the RUN'S OWN scripts, and that is a known hole
- *
- * `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) 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.
- *
- * 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.
- *
- * 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 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.
+ *
+ * `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.
+ *
+ * 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:
+ *
+ *     uncontained   0.38 / 0.35 / 0.34 s
+ *     contained     5.53 / 5.42 / 5.41 s      -> ~5.1 s added per command
+ *
+ * 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.
+ *
+ * ## The two `dev` servers: contained too, on a weaker network (#1037)
+ *
+ * `runDeepReview`'s and the review worker's take the SAME `sandboxImage` and go
+ * through one `devServerLaunch`, so they can no longer be fixed one at a time —
+ * which is how #988 came to fix one of them and ship the other.
+ *
+ * **That is not a hypothetical, and #1037's card got it wrong.** The card says
+ * both dev servers already carried a working `containedEnv()`. The review
+ * worker's did not: it passed `env: containedEnv()` to `spawnInGroup`, which
+ * merges `process.env` back on top, so the strip removed NOTHING for as long as
+ * it shipped — and `spawn-run-containment.test.ts` reported the property as held
+ * because it read the spelling. #1021 fixed the call and made the scan
+ * spawn-function aware. So on that server the credential half closed one commit
+ * before this one, not in #988.
+ *
+ * Their container differs from the four steps' in exactly one flag, and it
+ * cannot be otherwise: a dev server exists to be connected to, so it publishes
+ * `127.0.0.1:<port>` instead of taking `--network=none`, and therefore has
+ * egress. Every other bound is identical — worktree the only mount, `HOME=/tmp`,
+ * no capabilities. `devServerSandboxArgs` records the two alternative network
+ * shapes that were measured and rejected.
+ *
+ * The cost lands very differently from the four steps', and this was measured
+ * rather than carried over. A verification step pays container start-up per
+ * COMMAND; a dev server pays it once and then lives for the whole review.
+ * Measured on macOS / Docker Desktop 29.7.2 with a warm `oven/bun:1`, as
+ * time-to-first-HTTP-response — what `probeDevServer` actually waits for:
+ *
+ *     host        0.11 / 0.11 / 0.25 s
+ *     contained   0.24 / 0.26 / 0.26 s     -> ~0.15 s added, once per run
+ *
+ * That is noise beside the 10–20 s a real dev server takes to boot, which is
+ * why this one is not a cost argument the way #1036's was. (Taking the
+ * measurement also failed to reproduce #1036's own ~5.1 s figure on this host:
+ * its one-shot shape measures 0.50 s contained against 0.37 s on the host, with
+ * or without the bind mount. Left as a note rather than an edit, because the
+ * conditions that produced 5.1 s cannot be reconstructed from here — but the
+ * number is load-bearing for "opt-in, not default" and is worth re-taking.)
+ *
+ * `harmony-harness`'s own CLI no longer passes no image: #1021 gave it
+ * `--sandbox-image`, threaded from this same config by the daemon's motor
+ * driver, so a daemon-driven stage contains the `build_green` gate and the held
+ * test alike. A person running the CLI by hand still passes none and still runs
+ * on their own host, which is a different threat model. The dev servers are not
+ * on that path at all — neither gate starts one.
+ *
+ * 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 that both dev-server files are still in its
+ * scan; `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,10 +372,32 @@ 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);
 }
 
 /**
@@ -213,7 +405,11 @@ export function runBuild(worktreePath: string, timeout: number): string[] {
  * 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 +418,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 +449,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 +493,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(
@@ -324,25 +522,44 @@ export async function runDeepReview(
 
   const port = config.verification.devServerBasePort + workerId;
   let devServer: ChildProcess | null = null;
+  // Resolved before the `try`, so the `finally` can tear the container down
+  // even if the spawn itself throws — `--rm` does not collect a server that
+  // never exits, and this one never does.
+  const launch = devServerLaunch({
+    worktreePath,
+    port,
+    sandbox: verificationSandbox(config),
+  });
 
   try {
+    // Clear a predecessor on this port BEFORE starting, and await it. The
+    // teardown below cannot be awaited everywhere it is reached, and a
+    // container still shutting down still holds the published port — so the
+    // next start would fail with "port is already allocated" through no fault
+    // of the branch. Also collects a container orphaned by a killed daemon,
+    // which no in-process handle survives to remove. No-op when nothing is
+    // there; `removeSandboxContainer` swallows "No such container".
+    if (launch.containerName) {
+      await removeSandboxContainer(launch.containerName);
+    }
+
     // Start dev server in background
-    const [cmd, args] = spawnRunArgs("dev", "--port", String(port));
-    devServer = spawn(cmd, args, {
+    devServer = spawn(launch.cmd, launch.args, {
       cwd: worktreePath,
       stdio: ["ignore", "pipe", "pipe"],
       // Contained (#988), and it was the one spawn in this file that was not.
-      // `spawnRunArgs("dev", …)` resolves the worktree's OWN `dev` script,
-      // which the contained implement run may rewrite, so this is the same
+      // `devServerLaunch` resolves the worktree's OWN `dev` script, which the
+      // contained implement run may rewrite, so this is the same
       // attacker-choosable command as `runBuild`/`runTests` — except it ran
       // with the daemon's full environment, `HARMONY_API_KEY` and
       // `GITHUB_PERSONAL_ACCESS_TOKEN` included, while `changelog.ts` told
       // users the verification commands run "without your credentials".
       //
-      // A reduction, not a fix: the command still executes outside the sandbox
-      // with network. That is why the dev server is now NAMED in the residual
-      // list in `run-containment.ts` and in `docs/agent-daemon.md`, instead of
-      // being left implied by a list of four other scripts.
+      // #988 removed the environment; #1037 removes the rest of the daemon
+      // process, when `verification.sandboxImage` is set. The env strip stays
+      // either way: it is what covers the host path, which is still the
+      // default, and it is what `docker` itself is spawned with on the
+      // contained one.
       env: containedEnv(),
     });
 
@@ -432,6 +649,14 @@ export async function runDeepReview(
     if (devServer && !devServer.killed) {
       devServer.kill("SIGTERM");
     }
+    // Killing the `docker run` CLI is not the same as stopping the container it
+    // launched — the trap `runInSandbox` already documents for its timeout
+    // path, except here it is every path, because a dev server only ever ends
+    // by being killed. Without this a deep review leaves a server running with
+    // the operator's worktree bind-mounted, once per run.
+    if (launch.containerName) {
+      await removeSandboxContainer(launch.containerName);
+    }
   }
 }
 
@@ -684,6 +909,104 @@ export class DevServerReadinessError extends Error {
   }
 }
 
+/** How a dev server is started, and what has to be torn down afterwards. */
+export interface DevServerLaunch {
+  /** Command for `spawn` / `spawnInGroup`. */
+  cmd: string;
+  args: string[];
+  /**
+   * The container to force-remove once the server is no longer wanted. Absent
+   * on the host path, where killing the process is the whole teardown.
+   */
+  containerName?: string;
+}
+
+/**
+ * Resolve how to start the worktree's `dev` server — in a container when one is
+ * configured, in the daemon process when one is not (#1037).
+ *
+ * ## Why both dev servers come through here
+ *
+ * There are two: `runDeepReview`'s, below, and the review worker's
+ * (`review-worker.ts`, in the daemon package). They are the same command with
+ * the same exposure, and they have already drifted apart once — #988 found the
+ * first, shipped the fix, and the second went out uncontained in the same
+ * release because nothing tied them together. A shared resolver is what makes
+ * "both dev servers" a fact about the code instead of a claim in a comment.
+ *
+ * `spawn-run-containment.test.ts` scans for this function by name alongside
+ * `spawnRunArgs`, so moving the resolution in here does not take the review
+ * worker's spawn out of that scan.
+ *
+ * ## What the container does and does not buy
+ *
+ * The `dev` script is resolved 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. So this is the same
+ * attacker-choosable command as `runBuild` and `runTests`, and until now it ran
+ * in the daemon process as the operator. Contained, it loses the operator's
+ * home directory, every capability, and the daemon's uid on anything outside
+ * the worktree. It does NOT lose egress: see `devServerSandboxArgs`, which
+ * records the two shapes that were measured and rejected.
+ *
+ * ## Opt-in, behind the SAME key as #1036
+ *
+ * `verification.sandboxImage`, and deliberately not a second key. The image
+ * requirement is identical — it has to carry the repo's own toolchain — and an
+ * operator who set one key but not the other would get a half-contained daemon,
+ * which is the failure this module keeps having to write down. The cost of
+ * being wrong is bounded and already designed for: a contained dev server that
+ * cannot start fails exactly as an unstartable host one does, and the review
+ * worker already treats that as infrastructure rather than as the branch's
+ * fault — it keeps the card in Review and labels it for a human.
+ *
+ * `--host` is appended only on the contained path, because only there does the
+ * bind address matter. See `SANDBOX_DEV_SERVER_BIND`.
+ */
+export function devServerLaunch(args: {
+  worktreePath: string;
+  port: number;
+  sandbox?: VerificationSandbox;
+}): DevServerLaunch {
+  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,
+  };
+}
+
+/**
+ * The word "ready", and NOT the tail of "already" (#1037).
+ *
+ * A substring test read `already` as a readiness signal, which stopped being
+ * academic the moment the server moved into a container: `docker run` refuses a
+ * duplicate with `Conflict. The container name "…" is **already** in use`, so a
+ * failed start announced itself as a successful one. Reproduced end to end — the
+ * probe that followed was answered by the PREVIOUS run's container, still up on
+ * that port, and the review would have graded the previous card's page believing
+ * it was looking at this one. A wrong answer, not a slow one.
+ *
+ * `\b` is what fixes it: `already` has a word character before `ready`, so it no
+ * longer matches, while `ready in 320 ms` and `Ready in 2.3s` both still do —
+ * the second only since this became case-insensitive, which is a small widening
+ * in the direction the check was always reaching for.
+ */
+const DEV_SERVER_READY = /\bready\b/i;
+
 /**
  * Wait for a dev server to signal readiness on stdout/stderr.
  *
@@ -691,6 +1014,14 @@ export class DevServerReadinessError extends Error {
  * need the server to be live for correctness (e.g. the review worker)
  * must not proceed without a confirmed signal. If the server dies before
  * becoming ready, we reject with the exit details.
+ *
+ * **A match here is not proof the server is up**, and the caller's
+ * `probeDevServer` is not redundant: this reads text the child chose to print.
+ * The container path adds a second writer to that stream — docker itself — and
+ * the two are indistinguishable once they are bytes. That is why the contained
+ * path both suppresses docker's progress output (`--quiet`) and removes the
+ * previous container before starting, so a stale server cannot be the thing
+ * that answers the probe.
  */
 export function waitForDevServer(
   proc: ChildProcess,
@@ -730,7 +1061,7 @@ export function waitForDevServer(
     const onData = (data: Buffer) => {
       const text = data.toString();
       if (
-        text.includes("ready") ||
+        DEV_SERVER_READY.test(text) ||
         text.includes("localhost") ||
         text.includes("Local:")
       ) {