@gethmy/harness 1.4.0 → 1.6.0

package/src/sdk-agent-runner.ts

@@ -36,6 +36,7 @@ import {
   type McpServerConfig,
   type Options,
   query,
+  type SandboxSettings,
   type SDKMessage,
   type SettingSource,
   type SpawnedProcess,
@@ -143,6 +144,18 @@ export interface SdkRunnerConfig {
    * Only the sizing preflight sets this. Every other spawn keeps CLI parity.
    */
   gateEveryToolCall?: boolean;
+  /**
+   * OS-level isolation for COMMAND EXECUTION — Seatbelt on macOS, bubblewrap on
+   * Linux (#988). Built by `implementRunContainment` (`run-containment.ts`),
+   * which is where the reasoning for each field lives.
+   *
+   * This is the only containment knob that leaves `Bash` usable. `canUseTool` +
+   * `confineToRepo` gate the agent's own TOOL calls, so they can confine a
+   * spawn that only reads and edits; they say nothing about what a command that
+   * spawn runs may then reach. An implement run has to run commands, so it
+   * needs the bound one layer down.
+   */
+  sandbox?: SandboxSettings;
   /**
    * Hands the spawned process-group leader to the worker so its existing
    * pause/resume/cancel paths can keep operating on `this.process`.
@@ -322,6 +335,12 @@ export class SdkAgentRunner implements AgentRunner {
         : {}),
       ...(this.cfg.mcpServers ? { mcpServers: this.cfg.mcpServers } : {}),
       ...(this.cfg.strictMcpConfig ? { strictMcpConfig: true } : {}),
+      // Execution sandbox (#988). Omitted entirely when unset, so every spawn
+      // that has not opted in keeps its current behaviour — the same shape as
+      // `canUseTool` above. When it IS set, `failIfUnavailable` inside it means
+      // an unsupported host fails the run rather than quietly running it
+      // uncontained, so there is no silent third state.
+      ...(this.cfg.sandbox ? { sandbox: this.cfg.sandbox } : {}),
       stderr: (data) => {
         this.capturedStderr += data;
       },

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,7 +14,13 @@ import {
   supportsDevServer,
   testCommand,
 } from "./project-type.js";
+import { runInSandbox, sandboxAvailable } from "./repair-sandbox.js";
 import { findDeletedTestFiles } from "./revert-guard.js";
+import {
+  containedEnv,
+  GIT_NO_HOOKS,
+  implementRunContainmentCliArgs,
+} from "./run-containment.js";
 
 const TAG = "verification";
 
@@ -58,6 +68,11 @@ 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. The two dev servers below are deliberately not passed it.
+  const sandbox = verificationSandbox(config);
+
   if (config.verification.revertGuard) {
     log.info(TAG, `[worker:${workerId}] Checking for reverted merged work...`);
     const deletedTests = findDeletedTestFiles(
@@ -84,7 +99,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,
@@ -102,9 +121,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(
@@ -120,7 +140,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,
@@ -148,34 +172,198 @@ export async function runVerification(
   return result;
 }
 
-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 [];
+/**
+ * ## 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.
+ *
+ * ## Still uncontained: the two `dev` servers, and the standalone CLI
+ *
+ * `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.
+ *
+ * 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.
+ */
+/**
+ * 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,
       timeout,
       stdio: "pipe",
       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);
+}
+
 /**
  * Run the repo's own test suite. Returns the failures (empty = passed, or no
  * 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(
@@ -184,24 +372,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,
-    });
-    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);
 }
 
 /**
@@ -216,35 +403,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,
-    });
+  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(
@@ -253,17 +447,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,
-    });
-    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(
@@ -290,6 +483,19 @@ export async function runDeepReview(
     devServer = spawn(cmd, 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
+      // 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.
+      env: containedEnv(),
     });
 
     // Wait for dev server to be ready, then confirm it answers HTTP.
@@ -311,7 +517,7 @@ export async function runDeepReview(
       // "(unable to retrieve diff)" — reviewing the change with no change (#701).
       diff = execFileSync(
         "git",
-        ["diff", `origin/${config.worktree.baseBranch}..HEAD`],
+        [...GIT_NO_HOOKS, "diff", `origin/${config.worktree.baseBranch}..HEAD`],
         {
           cwd: worktreePath,
           encoding: "utf-8",
@@ -336,7 +542,6 @@ export async function runDeepReview(
       "```",
     ].join("\n");
 
-    const leanSources = config.claude.leanSettingSources;
     const output = execFileSync(
       "claude",
       [
@@ -345,8 +550,16 @@ export async function runDeepReview(
         "sonnet",
         "--max-turns",
         "10",
-        // Lean spawn — skip project CLAUDE.md/@-imports (#348).
-        ...(leanSources ? ["--setting-sources", leanSources] : []),
+        // Contained (#988). This spawn reads a diff the implement run wrote, in
+        // that run's own worktree, so it is downstream of untrusted text by
+        // construction — and it used to run with no sandbox and no credential
+        // deny at all. It has no `--allowedTools` of its own, which bounds it
+        // less than it looks: the default set still reads files.
+        ...implementRunContainmentCliArgs({
+          worktree: worktreePath,
+          // Reads a diff and reports findings; it writes nothing.
+          readOnly: true,
+        }),
         "--",
         reviewPrompt,
       ],
@@ -356,6 +569,7 @@ export async function runDeepReview(
         timeout: config.verification.timeout,
         stdio: "pipe",
         maxBuffer: MAX_OUTPUT_BUFFER,
+        env: containedEnv(),
       },
     );
 
@@ -396,7 +610,6 @@ export function attemptAutoFix(
     "```",
   ].join("\n");
 
-  const leanSources = config.claude.leanSettingSources;
   const args = [
     "--print",
     "--model",
@@ -405,8 +618,23 @@ export function attemptAutoFix(
     "50",
     "--allowedTools",
     "Bash,Read,Write,Edit,Glob,Grep",
-    // Lean spawn — concrete build/lint errors, no project docs needed (#348).
-    ...(leanSources ? ["--setting-sources", leanSources] : []),
+    // Contained exactly like the implement run (#988). This spawn used to pass
+    // `--setting-sources local,user` and nothing else: no sandbox, no
+    // credential denies, no env strip — measured reading
+    // `~/.harmony-mcp/config.json` (the Harmony API key), reaching the open
+    // internet and writing to `$HOME`.
+    //
+    // It is not an edge path. `maxFixAttempts` defaults to 1, so a failing
+    // build reaches here on an ordinary run — and whether the build fails is
+    // under the CONTAINED run's control, which made this the cheap way out of
+    // the containment: break the build, get an uncontained spawn in the same
+    // worktree, on the same branch.
+    //
+    // `leanSettingSources` is deliberately no longer read here. It exists to
+    // drop the project docs an auto-fix does not need (#348), and the
+    // containment's `settingSources` already excludes `user`; honouring both
+    // would let the operator's config widen a boundary.
+    ...implementRunContainmentCliArgs({ worktree: worktreePath }),
     "--",
     fixPrompt,
   ];
@@ -419,6 +647,7 @@ export function attemptAutoFix(
     timeout: config.verification.timeout,
     stdio: "pipe",
     maxBuffer: MAX_OUTPUT_BUFFER,
+    env: containedEnv(),
   });
 }