@gethmy/harness 1.2.1 → 1.3.0

package/src/pm.ts

@@ -42,18 +42,28 @@ export function detectPackageManager(): PackageManager {
 
 /**
  * Return the install command string for the detected package manager.
+ *
+ * `ignoreScripts` adds `--ignore-scripts`, which every one of these supports.
+ * It exists for the red-CI repair (#1015): that checkout is of a branch whose
+ * head may ALREADY carry a machine-authored repair commit — `maxAttempts`
+ * defaults to 2 — so a `postinstall` there would run unreviewed code on the
+ * daemon's host, as the daemon user, with its credentials. The diff gate covers
+ * `package.json` itself, but not the file a script it already declares points
+ * at, and no path list can: which file an install script reaches is a property
+ * of the repo, not of this code. Not running them is the bound.
  */
-export function installCommand(): string {
+export function installCommand(ignoreScripts = false): string {
   const pm = detectPackageManager();
+  const skip = ignoreScripts ? " --ignore-scripts" : "";
   switch (pm) {
     case "bun":
-      return "bun install --frozen-lockfile";
+      return `bun install --frozen-lockfile${skip}`;
     case "pnpm":
-      return "pnpm install --frozen-lockfile";
+      return `pnpm install --frozen-lockfile${skip}`;
     case "yarn":
-      return "yarn install --frozen-lockfile";
+      return `yarn install --frozen-lockfile${skip}`;
     case "npm":
-      return "npm ci";
+      return `npm ci${skip}`;
   }
 }
 

package/src/repair-sandbox.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import { SANDBOX_MOUNT, sandboxRunArgs } from "./repair-sandbox.js";
+
+const IMAGE = "oven/bun:1";
+const WORKTREE = "/repo/.harmony-worktrees/review-agent-x";
+const CMD = { cmd: "bun", args: ["run", "test"] };
+
+const argv = () => sandboxRunArgs(IMAGE, WORKTREE, CMD);
+
+/**
+ * These are not style assertions. Each flag below is the only thing standing
+ * between "a container ran the repair's tests" and "the repair's tests ran with
+ * the daemon's credentials", so each gets its own named case — a dropped flag
+ * should fail a test that says what was lost, not a snapshot diff.
+ */
+describe("sandboxRunArgs", () => {
+  it("has no network", () => {
+    // Exfiltration does not need a shell. A test file the repair wrote is
+    // executed by the suite, and with egress it can post anything it read.
+    expect(argv()).toContain("--network=none");
+  });
+
+  it("drops every capability and cannot regain one", () => {
+    expect(argv()).toContain("--cap-drop=ALL");
+    expect(argv()).toContain("--security-opt=no-new-privileges");
+  });
+
+  it("caps memory and pids", () => {
+    // A repair that spins parks the card; it does not take down the host the
+    // daemon shares with its operator.
+    expect(argv().some((a) => a.startsWith("--memory="))).toBe(true);
+    expect(argv().some((a) => a.startsWith("--pids-limit="))).toBe(true);
+  });
+
+  it("mounts the worktree and NOTHING else", () => {
+    const mounts = argv()
+      .map((a, i) => (a === "--volume" ? argv()[i + 1] : null))
+      .filter((v): v is string => v !== null);
+    expect(mounts).toEqual([`${WORKTREE}:${SANDBOX_MOUNT}`]);
+  });
+
+  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.
+    const joined = argv().join(" ");
+    expect(joined).not.toContain("docker.sock");
+    expect(joined).not.toContain("/var/run");
+  });
+
+  it("never mounts a host home directory", () => {
+    const joined = argv().join(" ");
+    expect(joined).not.toContain("/Users/");
+    expect(joined).not.toContain("/home/");
+    expect(joined).not.toContain(".claude");
+    expect(joined).not.toContain(".harmony-mcp");
+    expect(joined).not.toContain(".ssh");
+  });
+
+  it("passes exactly one env var, and it is not a credential", () => {
+    const envs = argv()
+      .map((a, i) => (a === "--env" ? argv()[i + 1] : null))
+      .filter((v): v is string => v !== null);
+    expect(envs).toEqual(["HOME=/tmp"]);
+  });
+
+  it("is a one-shot", () => {
+    expect(argv()).toContain("--rm");
+  });
+
+  it("runs as the daemon's own uid, not the image's root", () => {
+    // Otherwise build output in the bind mount is root-owned on Linux, and the
+    // `git add` and the worktree cleanup that follow run as the daemon user.
+    const a = argv();
+    if (typeof process.getuid !== "function") return; // Windows: not a concept
+    expect(a).toContain("--user");
+    expect(a[a.indexOf("--user") + 1]).toBe(
+      `${process.getuid()}:${process.getgid?.()}`,
+    );
+  });
+
+  it("names the container, so a timed-out one can be torn down", () => {
+    // `--rm` cleans up a container that EXITS. A timeout kills the docker CLI,
+    // not the container it launched, so the name is the only handle left.
+    const a = sandboxRunArgs(IMAGE, WORKTREE, CMD, "harmony-repair-abc");
+    expect(a[a.indexOf("--name") + 1]).toBe("harmony-repair-abc");
+    // And it stays optional, so the flag pins above hold either way.
+    expect(argv()).not.toContain("--name");
+  });
+
+  it("runs the command as given, ignoring the image's own entrypoint", () => {
+    const a = argv();
+    expect(a).toContain("--entrypoint");
+    expect(a[a.indexOf("--entrypoint") + 1]).toBe("bun");
+    // The image name separates docker's flags from the command's arguments, so
+    // everything after it is argv for the command and nothing else.
+    expect(a.slice(a.indexOf(IMAGE) + 1)).toEqual(["run", "test"]);
+  });
+
+  it("works out of the mount point, not the host path", () => {
+    const a = argv();
+    expect(a[a.indexOf("--workdir") + 1]).toBe(SANDBOX_MOUNT);
+    // The host path appears ONLY as the source half of the bind mount.
+    expect(a.filter((x) => x.includes(WORKTREE))).toEqual([
+      `${WORKTREE}:${SANDBOX_MOUNT}`,
+    ]);
+  });
+
+  it("would actually notice a missing flag", () => {
+    // Mutation check for the cases above: they read a real argv, so a guard
+    // that could never fail is not a guard. Dropping a flag from the list must
+    // make the corresponding assertion false.
+    const withoutNetwork = argv().filter((a) => a !== "--network=none");
+    expect(withoutNetwork).not.toContain("--network=none");
+    expect(argv()).toContain("--network=none");
+  });
+});

package/src/repair-sandbox.ts

@@ -0,0 +1,303 @@
+/**
+ * Run a command against a worktree with none of the daemon's credentials in
+ * scope (#1015).
+ *
+ * ## Why this exists
+ *
+ * Verifying a repair means RUNNING code the repair wrote. That is not a path
+ * problem and no denylist fixes it: a test file the suite imports is executed
+ * too, and so is anything the build entrypoint reaches. Review of #981 found the
+ * cheap version of this — write a `pretest` script into the worktree's own
+ * `package.json` and wait for the verification step to run it, as the daemon
+ * user, on a host holding `gh` credentials and the Harmony API key. Removing
+ * `Bash` from the spawn did not help, because the spawn never needed a shell of
+ * its own; it needed the daemon to run one for it.
+ *
+ * So the bound is not "which files may it write" but "what does the thing that
+ * executes them have". Here: a container with no network, no host home
+ * directory, no environment, no capabilities, and no way to acquire more.
+ *
+ * ## Why absence is the fallback, not a weaker sandbox
+ *
+ * A daemon host without Docker gets no local verification at all rather than a
+ * best-effort one. `ciRepair.patch` then still repairs — it commits and pushes,
+ * and CI runs the branch on GitHub's runner instead. That keeps the same
+ * property by a different route: the code the repair wrote is executed
+ * somewhere the operator's credentials are not. A half-sandbox on the host
+ * would be the one option that trades the property for convenience, so it is
+ * not offered.
+ *
+ * What the push path needs INSTEAD of this module is `buildExecutedChanges`
+ * (`ci-patch.ts`), because a repair that rewrote `.github/workflows/*` would be
+ * executed by Actions with the repository's own secrets. The two guards cover
+ * two different executors and neither replaces the other.
+ *
+ * ## What this module is not
+ *
+ * It is not a general sandbox and does not try to be one. It runs one command,
+ * once, and reports whether it passed. It deliberately mounts nothing but the
+ * worktree, and in particular never the Docker socket — a container that can
+ * reach the daemon socket is root on the host, which would invert the whole
+ * point.
+ */
+import { randomUUID } from "node:crypto";
+import { promisify } from "node:util";
+import { log } from "./log.js";
+
+const TAG = "repair-sandbox";
+
+/**
+ * Run `docker` asynchronously, importing `execFile` LAZILY.
+ *
+ * The laziness is not incidental. A top-level `promisify(execFile)` puts
+ * `execFile` in this module's import bindings, and this module is re-exported
+ * from the package barrel — so every test anywhere that partially mocks
+ * `node:child_process` with only `execFileSync` then fails at LOAD time with
+ * "No execFile export is defined on the mock", in files that have nothing to do
+ * with sandboxes. It broke two pre-existing agent suites when it was written
+ * statically. `worktree.ts` → `git-pr.ts` hit exactly this and was fixed the
+ * same way; the module system caches the import, so the cost is one lookup.
+ */
+async function dockerExec(
+  argv: string[],
+  opts: { timeout: number; maxBuffer?: number },
+): Promise<{ stdout: string; stderr: string }> {
+  const { execFile } = await import("node:child_process");
+  return promisify(execFile)("docker", argv, {
+    encoding: "utf-8",
+    ...opts,
+  }) as unknown as Promise<{ stdout: string; stderr: string }>;
+}
+
+/** Output cap, matching `verification.ts` — a verbose suite clears 1 MB easily. */
+const MAX_OUTPUT_BUFFER = 20 * 1024 * 1024;
+
+/** How long `docker version` may take before the host counts as sandbox-less. */
+const PROBE_TIMEOUT_MS = 10_000;
+
+/** Where the worktree is mounted inside the container. */
+export const SANDBOX_MOUNT = "/repo";
+
+/**
+ * Hard resource caps. A repair that spins is a repair that parks, not one that
+ * takes the host down with it: the daemon is a long-lived process on a machine
+ * someone else is using.
+ */
+const SANDBOX_MEMORY = "4g";
+const SANDBOX_PIDS = "512";
+
+export interface SandboxCommand {
+  cmd: string;
+  args: string[];
+}
+
+export interface SandboxResult {
+  /** Did the command exit 0? */
+  passed: boolean;
+  /** Combined stdout+stderr, capped. Empty when the run never started. */
+  output: string;
+  /**
+   * Set when the sandbox itself failed rather than the command under it —
+   * no Docker, image missing, timeout. Distinct from `passed: false`, which
+   * means the repair genuinely did not verify.
+   */
+  sandboxError?: string;
+}
+
+let dockerProbe: boolean | null = null;
+
+/**
+ * Is a usable container runtime reachable?
+ *
+ * Cached for the daemon's lifetime. `docker version` (not `--version`) is the
+ * probe because it contacts the daemon: the CLI being on PATH says nothing
+ * about whether Docker Desktop is actually running, and the difference decides
+ * whether a repair verifies locally or leans on CI.
+ */
+export async function sandboxAvailable(): Promise<boolean> {
+  // Only a POSITIVE result is cached. A daemon that starts before Docker
+  // Desktop is up would otherwise treat "not available" as settled for its
+  // whole lifetime — pushing every later repair unverified, with one `info`
+  // line as the only trace. A negative costs one probe per repair attempt,
+  // which is bounded by `maxAttempts` and is the cheap direction to be wrong in.
+  if (dockerProbe === true) return true;
+  try {
+    await dockerExec(["version", "--format", "{{.Server.Version}}"], {
+      timeout: PROBE_TIMEOUT_MS,
+    });
+    dockerProbe = true;
+  } catch {
+    dockerProbe = false;
+  }
+  return dockerProbe;
+}
+
+/** Test seam. Not for production use — the probe is cached on purpose. */
+export function __resetSandboxProbe(): void {
+  dockerProbe = null;
+}
+
+/**
+ * Tear down a container the `docker` CLI was killed out from under.
+ *
+ * `--rm` cleans up a container that EXITS; it does nothing for one still
+ * running when its launching CLI was killed on a timeout. Without this a
+ * timed-out verification leaves a build running with the operator's worktree
+ * 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.
+ */
+async function removeContainer(name: string): Promise<void> {
+  try {
+    await dockerExec(["rm", "--force", name], { timeout: PROBE_TIMEOUT_MS });
+    log.warn(TAG, `removed the timed-out sandbox container ${name}`);
+  } catch {
+    // Already gone, or the daemon is unreachable. Nothing further to do.
+  }
+}
+
+/**
+ * The `docker run` argv, as a pure function so the flags are pinned by a test
+ * rather than by reading them.
+ *
+ * Every flag below is load-bearing, and a test names each one:
+ *
+ * - `--rm` — the container is a one-shot; nothing of it outlives the check.
+ * - `--network=none` — no egress. The repair cannot phone home with what it
+ *   read, and cannot fetch a second stage.
+ * - `--cap-drop=ALL` + `--security-opt=no-new-privileges` — no capabilities,
+ *   and no setuid path back to acquiring any.
+ * - `--memory` / `--pids-limit` — a fork bomb or a leak parks the card instead
+ *   of taking the daemon's host with it.
+ * - `--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.
+ * - `--workdir /repo` and `--entrypoint` — run the command as given, ignoring
+ *   whatever entrypoint the image declares.
+ *
+ * The worktree is mounted read-WRITE because a build writes: `dist/`, a test
+ * cache, coverage. That is the point of the container — those writes land in a
+ * throwaway checkout, and the process making them holds nothing.
+ */
+export function sandboxRunArgs(
+  image: string,
+  worktree: string,
+  command: SandboxCommand,
+  name?: string,
+): string[] {
+  return [
+    "run",
+    "--rm",
+    ...(name ? ["--name", name] : []),
+    "--network=none",
+    "--cap-drop=ALL",
+    "--security-opt=no-new-privileges",
+    `--memory=${SANDBOX_MEMORY}`,
+    `--pids-limit=${SANDBOX_PIDS}`,
+    // Run as the daemon's own uid/gid, so build output in the bind mount stays
+    // owned by the user who has to `git add` and delete it afterwards. Without
+    // this the container runs as the image's default user — root for most CI
+    // images — and on Linux leaves root-owned files behind in the operator's
+    // worktree. `process.getuid` is absent on Windows, where the concept does
+    // not apply and the flag is simply omitted.
+    ...(typeof process.getuid === "function" &&
+    typeof process.getgid === "function"
+      ? ["--user", `${process.getuid()}:${process.getgid()}`]
+      : []),
+    "--env",
+    "HOME=/tmp",
+    "--volume",
+    `${worktree}:${SANDBOX_MOUNT}`,
+    "--workdir",
+    SANDBOX_MOUNT,
+    "--entrypoint",
+    command.cmd,
+    image,
+    ...command.args,
+  ];
+}
+
+/**
+ * Run one command against `worktree` inside a container.
+ *
+ * **Async, and that is not a style choice.** The daemon is one event loop
+ * serving the realtime watcher, `/health`, the reconcile heartbeat and every
+ * pool worker. A synchronous `execFileSync` here would freeze all of them for
+ * up to `timeoutMs` — ten minutes by default. `command-metric.ts` had exactly
+ * this defect and #823 fixed it; repeating it would be the same outage under a
+ * different name.
+ *
+ * On a timeout the child that dies is the `docker` CLI, not the container it
+ * started, so the container is torn down BY NAME afterwards — otherwise a
+ * timed-out verification leaves a build running with the worktree still
+ * mounted, once per repair attempt.
+ *
+ * Never throws: a sandbox that failed to start reports `sandboxError` and the
+ * caller decides. That distinction matters — "the repair does not build" and
+ * "the image is missing" must not both read as a bad repair, because only the
+ * first is the repair's fault.
+ */
+export async function runInSandbox(args: {
+  image: string;
+  worktree: string;
+  command: SandboxCommand;
+  timeoutMs: number;
+}): Promise<SandboxResult> {
+  const name = `harmony-repair-${randomUUID()}`;
+  const argv = sandboxRunArgs(args.image, args.worktree, args.command, name);
+  log.info(
+    TAG,
+    `sandbox: ${args.command.cmd} ${args.command.args.join(" ")} (image ${args.image})`,
+  );
+  try {
+    const { stdout } = await dockerExec(argv, {
+      timeout: args.timeoutMs,
+      maxBuffer: MAX_OUTPUT_BUFFER,
+    });
+    return { passed: true, output: stdout ?? "" };
+  } catch (err) {
+    // `promisify(execFile)` reports the exit status as `code`, NOT `status` —
+    // the field `execFileSync` uses. A string `code` is a spawn-level errno
+    // (`ENOENT` when docker is not installed), never an exit status.
+    const e = err as {
+      code?: number | string | null;
+      killed?: boolean;
+      signal?: string | null;
+      stdout?: string;
+      stderr?: string;
+      message?: string;
+    };
+    const output = `${e.stdout ?? ""}${e.stderr ?? ""}`;
+
+    // The `docker` CLI died without reporting an exit status: killed on
+    // timeout, or never started. Neither is a verdict on the repair — and a
+    // timeout leaves the CONTAINER running, because what was killed is the CLI
+    // that launched it.
+    if (typeof e.code !== "number") {
+      const timedOut = e.killed === true || e.signal != null;
+      if (timedOut) await removeContainer(name);
+      return {
+        passed: false,
+        output,
+        sandboxError: timedOut
+          ? `the sandbox timed out after ${args.timeoutMs}ms`
+          : `the sandbox did not run: ${e.message ?? "unknown error"}`,
+      };
+    }
+
+    // `docker run` reports 125 for its own failure to start a container
+    // (unknown image, bad flag) — as opposed to 126/127 (command not
+    // executable / not found) and any other code, which come from the command.
+    if (e.code === 125) {
+      return {
+        passed: false,
+        output,
+        sandboxError: `the sandbox could not start (image "${args.image}" missing or unusable)`,
+      };
+    }
+
+    return { passed: false, output };
+  }
+}