@gethmy/harness 1.5.0 → 1.7.0

package/src/repair-sandbox.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { SANDBOX_MOUNT, sandboxRunArgs } from "./repair-sandbox.js";
+import {
+  devServerContainerName,
+  devServerSandboxArgs,
+  SANDBOX_DEV_SERVER_BIND,
+  SANDBOX_MOUNT,
+  sandboxRunArgs,
+} from "./repair-sandbox.js";
 
 const IMAGE = "oven/bun:1";
 const WORKTREE = "/repo/.harmony-worktrees/review-agent-x";
@@ -39,6 +45,26 @@ describe("sandboxRunArgs", () => {
     expect(mounts).toEqual([`${WORKTREE}:${SANDBOX_MOUNT}`]);
   });
 
+  it("adds a caller's extra mount, and only where it was asked for", () => {
+    // #1021 needs the runner's report to reach the motor, so `mounts` exists.
+    // The default stays exactly one mount — every other case above reads the
+    // no-argument form, so a mount that leaked into the default would fail them
+    // rather than passing quietly here.
+    const withReport = sandboxRunArgs(IMAGE, WORKTREE, CMD, undefined, [
+      { host: "/private/var/folders/x/report", container: "/harmony-report" },
+    ]);
+    const mounts = withReport
+      .map((a, i) => (a === "--volume" ? withReport[i + 1] : null))
+      .filter((v): v is string => v !== null);
+    expect(mounts).toEqual([
+      `${WORKTREE}:${SANDBOX_MOUNT}`,
+      "/private/var/folders/x/report:/harmony-report",
+    ]);
+    // The extra mount is a HOLE, so it must not weaken anything else.
+    expect(withReport).toContain("--network=none");
+    expect(withReport).toContain("--cap-drop=ALL");
+  });
+
   it("never mounts the Docker socket", () => {
     // A container that can reach the daemon socket is root on the host, which
     // would invert the entire point of running the verification in one.
@@ -114,3 +140,142 @@ describe("sandboxRunArgs", () => {
     expect(argv()).toContain("--network=none");
   });
 });
+
+/**
+ * #1037 — the dev server's container, which is the SAME container as above with
+ * one bound removed.
+ *
+ * The cases below are written to make that sentence checkable rather than
+ * merely written down: the first asserts the difference is exactly the network
+ * flags, so a future edit that also drops, say, `--cap-drop=ALL` from the dev
+ * server fails here with a diff naming the capability it lost.
+ */
+describe("devServerSandboxArgs", () => {
+  const PORT = 4300;
+  const NAME = "harmony-devserver-4300-abc";
+  const devArgv = () =>
+    devServerSandboxArgs({
+      image: IMAGE,
+      worktree: WORKTREE,
+      command: { cmd: "bun", args: ["run", "dev", "--port", "4300"] },
+      port: PORT,
+      name: NAME,
+    });
+
+  it("differs from the verification container only in reachability and output", () => {
+    // The whole claim of #1037 in one assertion. Every SECURITY bound —
+    // capabilities, mounts, uid, env, memory, pids, workdir — is identical, and
+    // a drop on either side shows up here as an unexpected entry.
+    //
+    // Exactly two flags are allowed to differ, and both are subtracted by name
+    // rather than by a loose filter, so a third difference fails: the network
+    // (`--network=none` vs `--publish`) and `--quiet`, which this container
+    // needs because its output is parsed for readiness. Neither is a bound.
+    const named = sandboxRunArgs(IMAGE, WORKTREE, CMD, NAME);
+    const shared = (a: string[]) =>
+      a.filter(
+        (x, i) =>
+          x !== "--network=none" &&
+          x !== "--quiet" &&
+          x !== "--publish" &&
+          a[i - 1] !== "--publish" &&
+          // The command tail differs by construction (`test` vs `dev`).
+          i <= a.indexOf(IMAGE),
+      );
+    expect(shared(devArgv())).toEqual(shared(named));
+    // Non-vacuity: an over-eager filter that emptied both sides would make the
+    // line above pass while comparing nothing. The shared part is most of the
+    // argv, so it is checked to actually still carry the bounds it exists for.
+    expect(shared(devArgv())).toContain("--cap-drop=ALL");
+    expect(shared(devArgv())).toContain("--security-opt=no-new-privileges");
+    expect(shared(devArgv()).length).toBeGreaterThan(10);
+  });
+
+  it("cannot use --network=none, and does not pretend to", () => {
+    // Not an oversight: a namespace with no interfaces cannot be connected to,
+    // and the entire purpose of this container is that something outside it
+    // connects. The residual is egress, and it is documented at the source.
+    expect(devArgv()).not.toContain("--network=none");
+  });
+
+  it("publishes on the loopback interface and nowhere else", () => {
+    // The bare `-p 4300:4300` form binds 0.0.0.0 and offers the run's own dev
+    // script to the whole LAN. The host half is pinned so the only thing that
+    // can reach it is the daemon that asked for it.
+    const a = devArgv();
+    const published = a
+      .map((x, i) => (x === "--publish" ? a[i + 1] : null))
+      .filter((v): v is string => v !== null);
+    expect(published).toEqual([`127.0.0.1:${PORT}:${PORT}`]);
+    for (const p of published) expect(p.startsWith("127.0.0.1:")).toBe(true);
+  });
+
+  it("still mounts the worktree and nothing else", () => {
+    const a = devArgv();
+    const mounts = a
+      .map((x, i) => (x === "--volume" ? a[i + 1] : null))
+      .filter((v): v is string => v !== null);
+    expect(mounts).toEqual([`${WORKTREE}:${SANDBOX_MOUNT}`]);
+    const joined = a.join(" ");
+    expect(joined).not.toContain("docker.sock");
+    expect(joined).not.toContain("/var/run");
+    expect(joined).not.toContain(".ssh");
+    expect(joined).not.toContain(".harmony-mcp");
+  });
+
+  it("always names the container, because this one never exits on its own", () => {
+    // `--name` is optional for the one-shot and mandatory here: `--rm` collects
+    // a container that EXITS, and a dev server only ever ends by being killed.
+    // The name is the only handle that stops it.
+    const a = devArgv();
+    expect(a[a.indexOf("--name") + 1]).toBe(NAME);
+  });
+
+  it("derives the container name from the port, so a predecessor is findable", () => {
+    // NOT randomised, and that is the fix for a real race. A review worker's
+    // port is fixed for its whole life and reused for every card it picks up,
+    // and `killDevServer` is reached from a synchronous `cleanup()` that cannot
+    // await the removal it starts. With a random name the next run has no
+    // handle on the container still holding the published port; with this one
+    // it can simply remove that name first. It also collects a container
+    // orphaned by a killed daemon, which no in-process handle outlives.
+    expect(devServerContainerName(PORT)).toBe(devServerContainerName(PORT));
+    expect(devServerContainerName(PORT)).toContain(String(PORT));
+  });
+
+  it("still separates workers, because they are separated by port", () => {
+    // The thing a random suffix was protecting against. Two containers on one
+    // port cannot coexist whatever they are called — the port is the
+    // constraint — and every worker slot has its own.
+    expect(devServerContainerName(4300)).not.toBe(devServerContainerName(4301));
+  });
+
+  it("would actually notice a lost flag", () => {
+    // Mutation check: the comparison above must fail when a real bound is
+    // dropped from the dev-server side, not merely pass on identical inputs.
+    const stripped = devArgv().filter((x) => x !== "--cap-drop=ALL");
+    expect(stripped).not.toContain("--cap-drop=ALL");
+    expect(devArgv()).toContain("--cap-drop=ALL");
+  });
+
+  it("keeps docker's pull progress off the stream that is parsed", () => {
+    // `waitForDevServer` reads this stream for the server announcing itself,
+    // and containing the server put a SECOND writer on it. The word-boundary
+    // `DEV_SERVER_READY` is the primary defence (it is what makes docker's
+    // "Already exists" safe); this is the second, kept because the two fail
+    // differently — a regex bounds the strings we thought of, `--quiet` removes
+    // the writer. It hides progress only: a missing image still errors and
+    // still exits 125.
+    expect(devArgv()).toContain("--quiet");
+    // NOT on the one-shot: its output is captured and shown, never parsed, and
+    // there the pull progress is context a reader may want.
+    expect(sandboxRunArgs(IMAGE, WORKTREE, CMD)).not.toContain("--quiet");
+  });
+
+  it("binds a routable address inside the container", () => {
+    // Loopback inside the container is not the loopback the published port
+    // forwards to, so a server bound there is unreachable and the probe fails
+    // with a connection refused that names nothing.
+    expect(SANDBOX_DEV_SERVER_BIND).toBe("0.0.0.0");
+  });
+});

package/src/repair-sandbox.ts

@@ -91,6 +91,28 @@ export interface SandboxCommand {
   args: string[];
 }
 
+/**
+ * One extra bind mount beside the worktree.
+ *
+ * There is exactly one consumer (#1021's held-test run, which needs the
+ * runner's report file to reach the motor) and it is deliberately a
+ * parameter rather than a second argv builder: the flag set below is the
+ * boundary, and a copy of it that drifts is the failure this module exists to
+ * prevent. Every caller therefore gets `--network=none`, `--cap-drop=ALL` and
+ * the rest by construction, and only the mount list differs.
+ *
+ * A mount is a HOLE in the container, so adding one is never free. The
+ * held-test run's is a directory the motor created and owns, holding nothing
+ * but the report the runner writes — see `oracle.ts`, which also states why the
+ * held test being able to write it is not what the container is closing.
+ */
+export interface SandboxMount {
+  /** Absolute path on the host. Realpath it first — `/tmp` is a symlink on macOS. */
+  host: string;
+  /** Absolute path inside the container. */
+  container: string;
+}
+
 export interface SandboxResult {
   /** Did the command exit 0? */
   passed: boolean;
@@ -146,11 +168,31 @@ export function __resetSandboxProbe(): void {
  * still bind-mounted — once per repair attempt, and the repair loop retries.
  *
  * Best-effort and short: if the daemon is gone the container is too.
+ *
+ * EXPORTED for the held-test run (#1021), which supervises its own `docker`
+ * child through `spawnInGroup` rather than through {@link runInSandbox} — it
+ * needs the exit code and the two streams apart, which this module's
+ * `{ passed, output }` shape does not carry. Its timeout kills the same CLI and
+ * strands the same container, so it needs the same teardown, and a second copy
+ * of it would be one more thing to keep in step.
+ *
+ * **And for the dev servers (#1037), where it is not an edge path but the
+ * ORDINARY one.** A one-shot container exits on its own and `--rm` collects it;
+ * a dev server never exits, so every contained dev server is torn down by name,
+ * on the success path as much as the failure path — and the NEXT one removes
+ * its predecessor by name before starting, which is why the name is derived
+ * from the port rather than randomised. It never throws and never rejects, so a
+ * synchronous caller (the review worker's `killDevServer`) may leave the
+ * promise unawaited without risking an unhandled rejection.
  */
-async function removeContainer(name: string): Promise<void> {
+export async function removeSandboxContainer(name: string): Promise<void> {
   try {
     await dockerExec(["rm", "--force", name], { timeout: PROBE_TIMEOUT_MS });
-    log.warn(TAG, `removed the timed-out sandbox container ${name}`);
+    // Not "timed-out": since #1037 this is also the ordinary teardown for a
+    // dev server, which never exits on its own, and logging every one of those
+    // as a timeout would invent an incident once per review. `info`, for the
+    // same reason — the caller logs the timeout itself when there was one.
+    log.info(TAG, `removed sandbox container ${name}`);
   } catch {
     // Already gone, or the daemon is unreachable. Nothing further to do.
   }
@@ -172,8 +214,11 @@ async function removeContainer(name: string): Promise<void> {
  * - `--env` is passed ONLY as `HOME=/tmp`. Docker does not inherit the host
  *   environment, so this is belt-and-braces: it stops a toolchain resolving
  *   `$HOME` to `/root` and finding a mounted credential that is not there.
- * - `-v <worktree>:/repo` — the ONLY mount. Not the Docker socket, not the
- *   host home, not `/var/run`. A container with the socket is root on the host.
+ * - `-v <worktree>:/repo` — the only mount a caller gets for free. Not the
+ *   Docker socket, not the host home, not `/var/run`. A container with the
+ *   socket is root on the host. A caller may add `mounts` (#1021 needs the
+ *   runner's report to reach the motor), and each one is a hole it has to
+ *   justify at its own call site — see {@link SandboxMount}.
  * - `--workdir /repo` and `--entrypoint` — run the command as given, ignoring
  *   whatever entrypoint the image declares.
  *
@@ -186,12 +231,39 @@ export function sandboxRunArgs(
   worktree: string,
   command: SandboxCommand,
   name?: string,
+  mounts: readonly SandboxMount[] = [],
 ): string[] {
   return [
     "run",
     "--rm",
     ...(name ? ["--name", name] : []),
     "--network=none",
+    ...sandboxHardeningArgs(worktree, mounts),
+    "--entrypoint",
+    command.cmd,
+    image,
+    ...command.args,
+  ];
+}
+
+/**
+ * Everything both container shapes share — that is, every bound EXCEPT the
+ * network one, which is the only place they differ (#1037).
+ *
+ * Factored so the dev-server shape cannot quietly drift from the verification
+ * shape. Before this the flags were a literal list in one function; a second
+ * list beside it is how one of them ends up a capability short, and nothing
+ * would have failed.
+ *
+ * `mounts` is #1021's parameter, threaded rather than duplicated: a dev server
+ * has no use for one today, but a second mount mechanism beside it is exactly
+ * the drift this function exists to prevent.
+ */
+function sandboxHardeningArgs(
+  worktree: string,
+  mounts: readonly SandboxMount[] = [],
+): string[] {
+  return [
     "--cap-drop=ALL",
     "--security-opt=no-new-privileges",
     `--memory=${SANDBOX_MEMORY}`,
@@ -210,12 +282,135 @@ export function sandboxRunArgs(
     "HOME=/tmp",
     "--volume",
     `${worktree}:${SANDBOX_MOUNT}`,
+    ...mounts.flatMap((m) => ["--volume", `${m.host}:${m.container}`]),
     "--workdir",
     SANDBOX_MOUNT,
+  ];
+}
+
+/**
+ * The address a contained dev server must bind INSIDE the container.
+ *
+ * A dev server that binds loopback binds the CONTAINER's loopback, which the
+ * published port never reaches — the mapping forwards to the container's
+ * external interface. Vite, Next, Astro and webpack-dev-server all default to
+ * localhost, so without this the container starts, the server reports itself
+ * ready on its own stdout, and the probe then fails with a connection refused
+ * that names nothing. Measured: with `--host 0.0.0.0` the published port
+ * answered in ~0.25 s; without it, never.
+ */
+export const SANDBOX_DEV_SERVER_BIND = "0.0.0.0";
+
+/**
+ * The container name for a dev server on `port`, and the handle that kills it.
+ *
+ * **Derived from the port, deliberately, rather than randomised.** A review
+ * worker's port is fixed for the worker's whole life (`review.devServerPort +
+ * slot`) and reused for every card that worker ever picks up, so the container
+ * that has to be gone before the next one starts is always *the one on this
+ * port*. A random name cannot be used to find it, which leaves the next run
+ * racing a `docker rm` it has no handle on; a derived one turns the teardown
+ * into something the next start can simply wait for.
+ *
+ * It introduces no collision. Two containers on one port cannot coexist
+ * whatever they are called — the port is the constraint — and the review and
+ * verification pools occupy separate port ranges by config
+ * (`review.devServerPort` 4300, `verification.devServerBasePort` 4200), one
+ * slot each.
+ *
+ * It also picks up the case a random name loses entirely: a container orphaned
+ * by a daemon that was killed, which no in-process handle survives to remove.
+ */
+export function devServerContainerName(port: number): string {
+  return `harmony-devserver-${port}`;
+}
+
+/**
+ * The `docker run` argv for a LONG-LIVED dev server, published on the host's
+ * loopback (#1037).
+ *
+ * ## Why this is not `sandboxRunArgs` with a port added
+ *
+ * It is the same container in every respect but one, and that one cannot be
+ * fixed: **it has egress.** `--network=none` is not available to a dev server,
+ * because the whole point of the server is that something OUTSIDE the container
+ * connects to it — `probeDevServer` from the daemon, and then the reviewer that
+ * looks at the page. A namespace with no interfaces cannot be connected to.
+ *
+ * That is a strictly weaker property than the four verification steps get, and
+ * it is stated here rather than left for someone to infer from a missing flag.
+ *
+ * ## What was measured before settling for it
+ *
+ * Two shapes that would have kept both halves were tried on the daemon's own
+ * platform (macOS, Docker Desktop 29.7.2) and neither works:
+ *
+ *  - `docker network create --internal` — egress is gone, and so is the
+ *    published port: `curl 127.0.0.1:<port>` never answers. Internal networks
+ *    drop the published-port path along with the external one, so this trades
+ *    the server away to protect it.
+ *  - a user-defined bridge with `enable_ip_masquerade=false` — the port
+ *    publishes, but egress SURVIVES (`registry.npmjs.org` and a raw
+ *    `https://1.1.1.1` both answered). Docker Desktop routes through its own
+ *    VM gateway, so the flag does not bite the way it does on native Linux.
+ *    Worse, that network reached a service on the operator's own host
+ *    (`host.docker.internal`) which the DEFAULT bridge could not.
+ *
+ * So the default bridge is chosen deliberately, not by omission: of the two
+ * bridges that publish a port, it is the one that could not reach the
+ * operator's other local services.
+ *
+ * ## What the container still takes away
+ *
+ * Egress is what is left, and it is worth being precise about what egress is
+ * worth here. The command is the run's own `dev` script and it still runs, but
+ * it now runs with the worktree as its ONLY mount and `HOME=/tmp`: no
+ * `~/.ssh`, no `~/.harmony-mcp/config.json`, no `~/.claude.json`, no
+ * capabilities, and no route back to acquiring any. What it can still send is
+ * the worktree — which is the run's own output — and what it can still fetch is
+ * a second stage, which lands inside the same bounds. The valuable half of
+ * "network plus the operator's home directory" is the half this removes.
+ *
+ * `--publish 127.0.0.1:<port>:<port>` and not `<port>:<port>`: the bare form
+ * binds `0.0.0.0` and puts the run's dev server on every interface of the
+ * operator's machine, offering it to the whole LAN. The host half is pinned to
+ * loopback so the only thing that can reach it is the daemon that asked for it.
+ */
+export function devServerSandboxArgs(args: {
+  image: string;
+  worktree: string;
+  command: SandboxCommand;
+  port: number;
+  name: string;
+}): string[] {
+  return [
+    "run",
+    // Still a one-shot: nothing of the server outlives the review that wanted
+    // it. `--rm` collects it when it exits, and `removeSandboxContainer` is
+    // what collects it when it does not — which, for a dev server, is always.
+    "--rm",
+    // Suppress docker's own pull progress, because this container's output is
+    // PARSED, not merely logged: `waitForDevServer` reads it for the server
+    // announcing itself, and containing the server put a SECOND writer on that
+    // stream. `DEV_SERVER_READY` is the primary defence and it is what makes
+    // "Already exists" safe (`\bready\b` does not match inside "already"); this
+    // is the second, and it is worth having because the two fail differently —
+    // a regex bounds the strings we thought of, while `--quiet` removes the
+    // writer. Docker's vocabulary is not ours to pin.
+    //
+    // It hides progress only: a missing image still writes its error and still
+    // exits 125, which is what `runInSandbox` reads to tell "the sandbox could
+    // not start" from "the command failed". Measured both ways.
+    "--quiet",
+    "--name",
+    args.name,
+    "--publish",
+    `127.0.0.1:${args.port}:${args.port}`,
+    ...sandboxHardeningArgs(args.worktree),
     "--entrypoint",
-    command.cmd,
-    image,
-    ...command.args,
+    args.command.cmd,
+    args.image,
+    ...args.command.args,
   ];
 }
 
@@ -277,7 +472,7 @@ export async function runInSandbox(args: {
     // that launched it.
     if (typeof e.code !== "number") {
       const timedOut = e.killed === true || e.signal != null;
-      if (timedOut) await removeContainer(name);
+      if (timedOut) await removeSandboxContainer(name);
       return {
         passed: false,
         output,