@gethmy/harness 1.6.0 → 1.7.0

package/src/run-containment.ts

@@ -78,44 +78,85 @@
  * was found by a review round rather than by reading the code, and a residual
  * nobody wrote down is indistinguishable from one nobody saw.
  *
- *  - **The two `dev` servers, plus the standalone harness CLI.** #1036 closed
- *    the four verification steps AND the `build_green` gate collector, which
- *    re-runs the same two scripts: `runBuild`, `runTests`, `runFormatFix` and `runLint`
- *    now run inside `repair-sandbox.ts`'s container when
- *    `verification.sandboxImage` is set — worktree the only mount, no network,
- *    no host fallback. What is left of this bullet is `runDeepReview`'s dev
- *    server and the review worker's own. Both are the same `spawnRunArgs`
- *    shape, and both are **probed over HTTP from the daemon**, so
- *    `--network=none` makes them unreachable by construction: containing them
- *    needs a different answer, not the same one applied twice. They keep
- *    `containedEnv()`, so the secret-shaped environment is gone; the command is
- *    still the run's to choose and still executes in the daemon process.
- *
- *    The containment for the four is **opt-in**, so on a host with no
- *    `sandboxImage` all six remain as described above. That is a deliberate
- *    asymmetry with this module's own containment, which defaults on: the SDK
- *    sandbox is inside the CLI, whereas a container needs a reachable Docker
- *    and an image carrying the repo's toolchain.
- *
- *    `packages/harmony-harness/src/cli.ts` builds the same collector and passes
- *    no image, because the motor holds no operator config of its own — there is
- *    nothing for it to read. That path is driven by a person running the CLI
- *    against their own checkout rather than by board text, so it is a different
- *    threat model, but it is named here rather than left to be rediscovered.
- *
- *    The count is in this bullet on purpose, and it has now been wrong twice.
- *    The first version named the four verification steps and stopped, and both
- *    dev servers then shipped with the daemon's whole environment while the
+ *  - **Egress from the two `dev` servers, plus the standalone harness CLI.**
+ *    #1036 closed the four verification steps AND the `build_green` gate
+ *    collector, which re-runs the same two scripts: `runBuild`, `runTests`,
+ *    `runFormatFix` and `runLint` run inside `repair-sandbox.ts`'s container
+ *    when `verification.sandboxImage` is set — worktree the only mount, no
+ *    network, no host fallback. #1037 took the same key and moved the two dev
+ *    servers in behind it: `runDeepReview`'s and the review worker's, both
+ *    through one `devServerLaunch`, so they can no longer be fixed one at a
+ *    time the way #988 fixed one and shipped the other.
+ *
+ *    **What is left of this bullet is egress, and only egress.** A dev server
+ *    exists to be connected to, so `--network=none` is not available to it: the
+ *    container publishes `127.0.0.1:<port>` on a default bridge, which gives it
+ *    a route out. That is a strictly weaker property than the four verification
+ *    steps get, and it is named here rather than left to be inferred from a
+ *    missing flag. Two shapes that would have kept both halves were measured on
+ *    the daemon's own platform and neither works — `--internal` drops the
+ *    published port along with the egress, and a bridge with
+ *    `enable_ip_masquerade=false` keeps the egress and additionally reaches the
+ *    operator's own host services. `devServerSandboxArgs` carries the numbers.
+ *
+ *    What the container still takes is the part that made the command worth
+ *    attacking: the run's `dev` script no longer executes in the daemon
+ *    process, no longer reads `~/.ssh` or `~/.harmony-mcp/config.json`, and no
+ *    longer holds a capability. What egress can still carry out is the
+ *    worktree, which is the run's own output.
+ *
+ *    The containment is **opt-in**, so on a host with no `sandboxImage` all six
+ *    commands still run in the daemon process, with `containedEnv()` as the
+ *    only bound. That is a deliberate asymmetry with this module's own
+ *    containment, which defaults on: the SDK sandbox is inside the CLI, whereas
+ *    a container needs a reachable Docker and an image carrying the repo's
+ *    toolchain.
+ *
+ *    One correction to the severity this was first written with. The dev
+ *    servers were called the rare path because `verification.deepReview`
+ *    defaults to false. That is true of `runDeepReview` and **false of the
+ *    review worker's**, which has no such gate and no toolchain check:
+ *    `review.enabled` defaults to true, so that server starts on every card
+ *    that reaches Review. Of the two, the one on the default path was the one
+ *    described as conditional.
+ *
+ *    `packages/harmony-harness/src/cli.ts` used to build the same collector and
+ *    pass no image, because the motor held no operator config of its own. #1021
+ *    gave it `--sandbox-image`, threaded from the daemon's same
+ *    `verification.sandboxImage`, so a daemon-driven stage now contains the
+ *    `build_green` gate and the HELD TEST alike. A person running the CLI by
+ *    hand against their own checkout still passes no image and still runs on
+ *    their host — a different threat model, and named here rather than left to
+ *    be rediscovered.
+ *
+ *    The count is in this bullet on purpose, and it has now been wrong three
+ *    times. The first version named the four verification steps and stopped, and
+ *    both dev servers then shipped with the daemon's whole environment while the
  *    changelog told users these commands run "without your credentials". The
  *    second version — #1036's own — said "the two dev servers" while the
  *    `build_green` gate ran the worktree's script on the host for any operator
- *    who had set an image precisely to stop that. Both were caught by a reader,
- *    not by a gate.
- *    `spawn-run-containment.test.ts` scans for the environment property instead
- *    of trusting this prose, and `verification-sandbox.test.ts` asserts that a
- *    configured image takes the four out of this process entirely — because the
- *    residual is a completeness claim over CALL SITES and a hand-list has
- *    already lost it once.
+ *    who had set an image precisely to stop that. The third omission was not a
+ *    missing NAME but a wrong SPELLING, which is worse: `review-worker.ts`'s dev
+ *    server carried `env: containedEnv()` on a `spawnInGroup` call, and
+ *    `spawnInGroup` merges `process.env` back over whatever `env` it is handed —
+ *    so that strip removed nothing for as long as it shipped, and the source
+ *    scan reported the property as held because the scan read the spelling.
+ *    Every one of the three was caught by a reader, not by a gate.
+ *
+ *    A fourth was caught by the gate, which is the point of having one. #1037
+ *    consolidated the two dev servers behind `devServerLaunch` — the right move,
+ *    and it instantly took `review-worker.ts` OUT of the scan, because the file
+ *    stopped containing the word `spawnRunArgs` and that list was how the walk
+ *    chose which files to open. The property assertion would have gone on
+ *    passing over the very file whose inert strip had just been fixed. The scan
+ *    now names both dev-server files explicitly, so a file leaving the walk
+ *    fails instead of quietly shrinking the count.
+ *
+ *    `spawn-run-containment.test.ts` is therefore spawn-function aware, covers
+ *    the held-test spawn, and checks its own coverage; and
+ *    `verification-sandbox.test.ts` asserts that a configured image takes the
+ *    four out of this process entirely — because the residual is a completeness
+ *    claim over CALL SITES and a hand-list has already lost it twice.
  *  - **The MCP surface.** The sandbox governs commands. MCP stdio servers are
  *    hosted by the CLI and are not sandboxed, so `mcp__harmony__*` is bounded by
  *    the tool allow-list and the daemon-owned denials (#525/#576), not by this.
@@ -598,6 +639,53 @@ export function containedEnv(
   return out;
 }
 
+/**
+ * The model credentials {@link containedEnv} deliberately KEEPS, named so a
+ * spawn that is not a model call can drop them.
+ *
+ * They are in {@link KEEP_ENV_KEYS} because an implement run IS the model call
+ * — stripping them stops the run existing rather than containing it. Nothing
+ * generalizes from that: it is a statement about one spawn.
+ */
+const MODEL_CREDENTIAL_KEYS: readonly string[] = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+];
+
+/**
+ * Environment keys the HELD-TEST run must not carry (#1021): everything
+ * {@link secretEnvKeysToStrip} names, plus the model credentials.
+ *
+ * A held test is arbitrary code an untrusted `author` subagent wrote, and
+ * before this the oracle spawn passed no `env` at all — so it inherited the
+ * daemon's entire environment, `HARMONY_API_KEY` and `ANTHROPIC_API_KEY`
+ * included. The first class is `secretEnvKeysToStrip`'s. The second is kept by
+ * `containedEnv` on purpose, which is right for the spawn that one was written
+ * for and wrong here: a test file has no model call to make, so a live billing
+ * credential in its environment is spend and reach it has no use for.
+ *
+ * **KEY NAMES, not an environment, and that is the whole point.** The oracle
+ * spawns through `spawnInGroup`, which MERGES `process.env` back on top of any
+ * `env` it is handed — so passing a narrowed object there strips nothing. The
+ * removal has to be a `stripEnvKeys` DELETE. `sdk-agent-runner.ts` records the
+ * same trap for the same reason; `review-worker.ts` shipped the inert spelling.
+ *
+ * This is a REDUCTION, not the boundary — the same thing #988 said about
+ * `containedEnv()` and for the same reason: the command still runs as the
+ * operator and can read `~/.ssh` and `~/.harmony-mcp/config.json` off disk. The
+ * boundary is the container, which `oracle.ts` uses when
+ * `verification.sandboxImage` is configured. This is what the DEFAULT path gets,
+ * and the default path is the one most operators are on.
+ */
+export function heldTestEnvKeysToStrip(
+  parentEnv: Record<string, string | undefined> = process.env,
+): string[] {
+  return [
+    ...new Set([...secretEnvKeysToStrip(parentEnv), ...MODEL_CREDENTIAL_KEYS]),
+  ];
+}
+
 /**
  * Git metadata the contained run may not write — the escape the worktree grant
  * would otherwise hand it.
@@ -1048,8 +1136,36 @@ export const IMPLEMENT_ALLOWED_DOMAINS: readonly string[] = [
  * lockstep with its own release, and a contained run reaching for `@latest`
  * would fetch a version this daemon was never tested against — over a network
  * the containment then has to allow the registry for.
+ *
+ * ## `run` — how the agent inside the run learns its own session (#1035)
+ *
+ * A daemon-run agent cannot call `harmony_start_agent_session`: the daemon owns
+ * the lifecycle and denies the tool (`STAGE_DAEMON_OWNED_TOOLS`). So the MCP
+ * process it talks to used to know nothing about the run it serves, and
+ * `harmony_add_comment` had to leave the attribution to the API — which could
+ * only ask "does this ACCOUNT have a session on this card?", true of every
+ * concurrent run of the same account. That is the borrowed attribution measured
+ * on card #1029.
+ *
+ * Passing `run` closes it at the source: the run's `card_agent_context` id
+ * reaches the MCP server as its own environment, so the comment names the
+ * session instead of the server inferring one.
+ *
+ * **The `env` field, not the spawn environment, and that is the point.** The
+ * CLI hosts a stdio MCP server with `{...its own env, ...this env}` — measured
+ * 2026-09-05 against `claude 2.1.261` with a probe server that dumped its
+ * environment: both halves arrive, and `PATH`/`HOME` survive. Putting the id
+ * here rather than on the run's own spawn keeps it out of the model's shell, so
+ * the agent cannot read it, echo it, or pass a different one.
+ *
+ * An OLDER `@gethmy/mcp` — one published before #1035 — simply ignores two
+ * unknown environment keys, so this is safe to ship ahead of the pin bump. A
+ * CLI FLAG would not be: `cli.js serve` parses with commander, which exits 1 on
+ * an unknown option, and the run would lose `mcp__harmony__*` entirely.
  */
-export function harmonyMcpServer(): Record<string, McpServerConfig> {
+export function harmonyMcpServer(
+  run?: HarmonyMcpRunBinding,
+): Record<string, McpServerConfig> {
   const require = createRequire(import.meta.url);
   // The package's `exports` map publishes "." → dist/index.js and no bin
   // subpath, so the CLI is named as its sibling rather than resolved directly.
@@ -1061,10 +1177,37 @@ export function harmonyMcpServer(): Record<string, McpServerConfig> {
       // and no chance of a different Node than the one that was tested.
       command: process.execPath,
       args: [cli, "serve"],
+      // Both keys or neither: the card id is what lets the MCP server tell
+      // "this comment is on the card I am running" from "this comment is on a
+      // neighbour", and without it the session id would be claimed on every
+      // card the run comments on.
+      ...(run
+        ? {
+            env: {
+              HARMONY_AGENT_CARD_ID: run.cardId,
+              HARMONY_AGENT_SESSION_ID: run.agentSessionId,
+            },
+          }
+        : {}),
     },
   };
 }
 
+/**
+ * The run whose `card_agent_context` session the MCP server may claim (#1035).
+ *
+ * Both fields are required together — see {@link harmonyMcpServer}. A caller
+ * that has no live session (a verification or review spawn that never opened
+ * one) passes nothing, and the MCP server then posts sessionless rather than
+ * borrowing.
+ */
+export interface HarmonyMcpRunBinding {
+  /** `cards.id` — the card this run holds its session on. */
+  cardId: string;
+  /** `card_agent_context.id` — the run's own session row. */
+  agentSessionId: string;
+}
+
 /** The fields {@link implementRunContainment} contributes to an `SdkRunnerConfig`. */
 export interface RunContainment {
   sandbox: SandboxSettings;
@@ -1107,6 +1250,12 @@ export function implementRunContainment(args: {
    * it says instead of being auto-approved because the run is sandboxed.
    */
   readOnly?: boolean;
+  /**
+   * The board session this spawn IS, so its agent can name it on a comment
+   * instead of the API inferring one (#1035). Omit when the spawn holds no
+   * session — the agent then comments sessionless, which is the honest answer.
+   */
+  run?: HarmonyMcpRunBinding;
 }): RunContainment {
   // Inside the builder rather than at the call sites, so a future spawn cannot
   // adopt the containment and skip the check that makes it hold. Throws — see
@@ -1229,7 +1378,7 @@ export function implementRunContainment(args: {
     // Handed back explicitly, because the line above took it away — see
     // `harmonyMcpServer`. Without this the run loses `mcp__harmony__*` and can
     // no longer report its own progress.
-    mcpServers: harmonyMcpServer(),
+    mcpServers: harmonyMcpServer(args.run),
     // Paired with the two above: the run sees only the server declared to it,
     // and no MCP config the operator happens to have registered for themselves.
     strictMcpConfig: true,
@@ -1288,6 +1437,11 @@ export function implementRunContainmentCliArgs(args: {
    * it says instead of being auto-approved because the run is sandboxed.
    */
   readOnly?: boolean;
+  /**
+   * The board session this spawn IS (#1035) — travels inside `--mcp-config`,
+   * the same way the SDK path travels it inside `mcpServers`.
+   */
+  run?: HarmonyMcpRunBinding;
 }): string[] {
   const containment = implementRunContainment(args);
   return [

package/src/stage-cli.ts

@@ -26,14 +26,19 @@ import { buildRoleLaunch, envKeysDroppedByLaunch } from "./runner.js";
 import type { SdkRunnerConfig } from "./sdk-agent-runner.js";
 
 export const STAGE_RUN_USAGE =
-  "usage: harmony-harness stage run --card <id> --stage <id> --workspace <id> --repo <path> --session <id> [--metrics <json-path>]";
+  "usage: harmony-harness stage run --card <id> --stage <id> --workspace <id> --repo <path> --session <id> [--metrics <json-path>] [--sandbox-image <image>]";
 
 /** The five identifiers one stage run needs. Every one is required.
- * `metricsPath` is the one optional input: a JSON file holding the DRIVER's
- * metric allowlist for `custom` gates (same shape as the daemon operator's
- * `agent.playbooks.metrics`). The motor itself stays config-free — without the
- * flag a `custom` gate reports "metric not declared" and blocks, exactly as
- * before. */
+ * `metricsPath` and `sandboxImage` are the optional inputs, and both carry the
+ * DRIVER's operator config into a motor that holds none of its own:
+ *  - `metricsPath` is a JSON file holding the metric allowlist for `custom`
+ *    gates (same shape as the daemon operator's `agent.playbooks.metrics`).
+ *    Without it a `custom` gate reports "metric not declared" and blocks,
+ *    exactly as before.
+ *  - `sandboxImage` is the daemon's `verification.sandboxImage` (#1021): the
+ *    container the held test and the gate's build/lint commands run in. Without
+ *    it both run in the motor's own process tree, which is what a person
+ *    running this CLI against their own checkout gets. */
 export interface StageRunArgs {
   cardId: string;
   stageId: string;
@@ -41,6 +46,7 @@ export interface StageRunArgs {
   repoPath: string;
   sessionId: string;
   metricsPath: string | null;
+  sandboxImage: string | null;
 }
 
 export type StageRunArgsResult =
@@ -78,14 +84,16 @@ export function parseStageRunArgs(argv: string[]): StageRunArgsResult {
     };
   }
 
-  const fields: Array<[Exclude<keyof StageRunArgs, "metricsPath">, string]> = [
+  const fields: Array<
+    [Exclude<keyof StageRunArgs, "metricsPath" | "sandboxImage">, string]
+  > = [
     ["cardId", "card"],
     ["stageId", "stage"],
     ["workspaceId", "workspace"],
     ["repoPath", "repo"],
     ["sessionId", "session"],
   ];
-  const args = { metricsPath: null } as StageRunArgs;
+  const args = { metricsPath: null, sandboxImage: null } as StageRunArgs;
   for (const [field, flag] of fields) {
     const value = readFlag(argv, flag);
     if (value === null) {
@@ -105,6 +113,22 @@ export function parseStageRunArgs(argv: string[]): StageRunArgsResult {
     }
     args.metricsPath = metricsPath;
   }
+
+  // Optional: --sandbox-image <image> (#1021). Same absent/valueless split as
+  // --metrics, and the refusal matters MORE here: a driver that passed the flag
+  // asked for the held test to run without its credentials in scope, and
+  // silently running it on the host would hand back exactly the exposure the
+  // flag exists to remove. There is no host fallback anywhere on this path.
+  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 };
 }
 

package/src/verification.ts

@@ -14,7 +14,14 @@ import {
   supportsDevServer,
   testCommand,
 } from "./project-type.js";
-import { runInSandbox, sandboxAvailable } from "./repair-sandbox.js";
+import {
+  devServerContainerName,
+  devServerSandboxArgs,
+  removeSandboxContainer,
+  runInSandbox,
+  SANDBOX_DEV_SERVER_BIND,
+  sandboxAvailable,
+} from "./repair-sandbox.js";
 import { findDeletedTestFiles } from "./revert-guard.js";
 import {
   containedEnv,
@@ -70,7 +77,9 @@ export async function runVerification(
 
   // Resolved once (#1036). Undefined unless the operator configured an image,
   // in which case the four script-resolved steps run in a container instead of
-  // in this process. The two dev servers below are deliberately not passed it.
+  // 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) {
@@ -220,22 +229,59 @@ export async function runVerification(
  * takes the same sandbox, wired at the worker's registry call site. One config
  * value, both paths.
  *
- * ## Still uncontained: the two `dev` servers, and the standalone CLI
+ * ## 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:
  *
- * `runDeepReview`'s and the review worker's. Both are the same `spawnRunArgs`
- * shape, and both are **probed over HTTP from the daemon**, so a `--network=none`
- * container is unreachable by construction. They keep `containedEnv()` and stay
- * named in `run-containment.ts`'s residual list rather than being quietly
- * counted as covered. `harmony-harness`'s own CLI builds the same gate
- * collector and passes no image, because the motor holds no operator config —
- * a person running it against their own checkout, not board text.
+ *     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 `verification-sandbox.test.ts` asserts that a
- * configured image takes the four out of the daemon entirely.
+ * 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.
  */
 /**
  * Resolve the sandbox for the verification steps out of the daemon's config
@@ -476,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(),
     });
 
@@ -584,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);
+    }
   }
 }
 
@@ -836,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.
  *
@@ -843,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,
@@ -882,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:")
       ) {