@gethmy/harness 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/harness",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Execution motor for Harmony playbook stages. Runs exactly one stage per invocation: worktree, role-separated subagents, held oracle, gate evidence. It never routes, never judges, never pushes.",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.178",
-    "@gethmy/mcp": "3.1.0",
+    "@gethmy/mcp": "3.2.0",
     "@supabase/supabase-js": "2.95.3"
   },
   "devDependencies": {

package/src/ci-failure.ts

@@ -2,6 +2,7 @@ import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 import type { GitProvider } from "./git-pr.js";
 import { log } from "./log.js";
+import { GIT_NO_HOOKS } from "./run-containment.js";
 
 /**
  * Reading a red CI in enough detail to act on it (card #981).
@@ -137,11 +138,15 @@ export function isPrOnOrigin(prUrl: string, cwd: string): boolean {
   const prSlug = githubSlug(prUrl);
   if (!prSlug) return false;
   try {
-    const remote = execFileSync("git", ["remote", "get-url", "origin"], {
-      cwd,
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "pipe"],
-    }).trim();
+    const remote = execFileSync(
+      "git",
+      [...GIT_NO_HOOKS, "remote", "get-url", "origin"],
+      {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    ).trim();
     return githubSlug(remote) === prSlug;
   } catch {
     return false;

package/src/exec-types.ts

@@ -58,13 +58,11 @@ export interface VerificationConfig {
      * until then this is the fallback for all cards.)
      */
     model: string;
-    /**
-     * `--setting-sources` value for lean spawns (review, auto-fix, deep-review)
-     * that don't need the project CLAUDE.md / @-imports (~23KB). `"local,user"`
-     * keeps the local-scoped harmony MCP server + user settings while dropping
-     * the project docs. Empty string omits the flag (full default behaviour).
-     */
-    leanSettingSources: string;
+    // `leanSettingSources` was removed in #988. The three spawns that read it —
+    // review, auto-fix and deep-review — are now pinned to the containment's
+    // own `settingSources`, so an operator value here could only ever widen a
+    // security boundary. Removed rather than ignored, so a config that sets it
+    // fails to typecheck instead of appearing to work.
   };
   worktree: {
     baseBranch: string;
@@ -97,9 +95,73 @@ export interface VerificationConfig {
      * report a timeout as a test failure.
      */
     testTimeout: number;
+    /**
+     * Container image for the verification steps (#1036). Empty — the default —
+     * runs them in the daemon process as before.
+     *
+     * `runBuild` / `runTests` / `runFormatFix` / `runLint` execute
+     * `bun run <script>` 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). #988 gave those spawns
+     * `containedEnv()`, which removes the secret-shaped variables and was
+     * stated there as a reduction and not a fix: the command still ran as the
+     * operator and could read `~/.ssh` and `~/.harmony-mcp/config.json` off
+     * disk. Setting this moves them into `repair-sandbox.ts`'s container, where
+     * the only mount is the worktree and there is no network.
+     *
+     * **Opt-in on purpose, unlike #988's own containment.** That one could ship
+     * on by default because the SDK sandbox is inside the CLI. This one needs a
+     * reachable Docker AND an image carrying the repo's toolchain, so a default
+     * would stop verification dead on every host that has neither. There is
+     * deliberately no guessed image, for the reason `types.ts` already records
+     * for the repair path: a container that cannot build anything reports every
+     * run as unverified.
+     *
+     * The image must carry the toolchain — the container has no network, so
+     * nothing installs at verification time. Dependencies are already present:
+     * `worktree.ts` installs them at worktree creation with `--ignore-scripts`.
+     * Point this at whatever your CI uses.
+     *
+     * Does NOT cover the two `dev` servers (`runDeepReview` and the review
+     * worker's). Those are probed over HTTP from the daemon, so a no-network
+     * container is unreachable by construction; they remain in
+     * `run-containment.ts`'s residual list.
+     */
+    sandboxImage: string;
   };
 }
 
+/**
+ * A configured verification container (#1036), or `undefined` for host
+ * execution. Resolved once by the caller from {@link VerificationConfig} so the
+ * four steps need no config import and stay unit-testable.
+ */
+export interface VerificationSandbox {
+  /** Image carrying the repo's toolchain. Empty means "not configured". */
+  image: string;
+}
+
+/**
+ * Head-room added to a step's own timeout when it runs in a container (#1036).
+ *
+ * There is deliberately NO separate sandbox timeout knob. Each step already
+ * carries the cap its operator chose — `verification.timeout` for build, lint
+ * and format, `verification.testTimeout` for the suite, and those two are
+ * separate precisely because a real suite outruns a build. A single
+ * container-wide cap would silently replace all four: with the values this repo
+ * ships, turning an image on would have taken build and lint from 2 minutes to
+ * 10, and would have ignored a `testTimeout` an operator had narrowed for a
+ * fast suite. Switching on containment must not change what any other setting
+ * means.
+ *
+ * So the step's own timeout wins, and this covers only what the container adds
+ * on top: image resolution and process start. Measured at ~5.1 s on macOS /
+ * Docker Desktop with a warm image; 60 s is that with an order of magnitude of
+ * head-room for a slower host or a cold layer, and it is not a budget for the
+ * command, which has already been capped by the time it is added.
+ */
+export const SANDBOX_STARTUP_GRACE_MS = 60_000;
+
 /** The slice of the daemon's config that the git helpers actually read. */
 export interface WorktreeConfig {
   worktree: VerificationConfig["worktree"];

package/src/gate-collectors.ts

@@ -46,6 +46,7 @@ import {
   CommandMetricCollector,
   type CommandMetricDeps,
 } from "./command-metric.js";
+import type { VerificationSandbox } from "./exec-types.js";
 import { log } from "./log.js";
 import type { OracleDeps } from "./oracle.js";
 import { OracleCollector, OracleRedCollector } from "./oracle-collector.js";
@@ -152,10 +153,25 @@ export interface BuildGreenDeps {
   worktreePath: string;
   buildTimeout: number;
   lintTimeout: number;
+  /**
+   * Verification container (#1036). Passed straight through to `runBuild` /
+   * `runLint`, so the gate's build runs wherever the daemon's own verification
+   * runs — a gate that ran the worktree's scripts in this process while
+   * `runVerification` contained them would be the hole under a different name.
+   */
+  sandbox?: VerificationSandbox;
   /** Inject for tests; defaults to verification.ts `runBuild`. Returns error lines. */
-  runBuild?: (worktreePath: string, timeout: number) => string[];
+  runBuild?: (
+    worktreePath: string,
+    timeout: number,
+    sandbox?: VerificationSandbox,
+  ) => string[] | Promise<string[]>;
   /** Inject for tests; defaults to verification.ts `runLint`. Returns warning lines. */
-  runLint?: (worktreePath: string, timeout: number) => string[];
+  runLint?: (
+    worktreePath: string,
+    timeout: number,
+    sandbox?: VerificationSandbox,
+  ) => string[] | Promise<string[]>;
 }
 
 /**
@@ -192,8 +208,18 @@ export class BuildGreenCollector implements GateEvidenceCollector {
   async collect(_context: GateEvidenceContext): Promise<GateEvidence> {
     const doBuild = this.deps.runBuild ?? runBuild;
     const doLint = this.deps.runLint ?? runLint;
-    const buildErrors = doBuild(this.deps.worktreePath, this.deps.buildTimeout);
-    const lintWarnings = doLint(this.deps.worktreePath, this.deps.lintTimeout);
+    // Awaited: both are async since #1036, and an injected test double may
+    // still be sync — `await` accepts either.
+    const buildErrors = await doBuild(
+      this.deps.worktreePath,
+      this.deps.buildTimeout,
+      this.deps.sandbox,
+    );
+    const lintWarnings = await doLint(
+      this.deps.worktreePath,
+      this.deps.lintTimeout,
+      this.deps.sandbox,
+    );
     const buildPassed = buildErrors.length === 0;
     const lintPassed = lintWarnings.length === 0;
     // Match verification.ts: only a failing BUILD makes the gate red. Lint

package/src/git-diff-stat.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { log } from "./log.js";
+import { GIT_NO_HOOKS } from "./run-containment.js";
 
 const TAG = "git-diff-stat";
 
@@ -134,7 +135,7 @@ export function captureDiffStat(
   try {
     const raw = execFileSync(
       "git",
-      ["diff", "--numstat", `${baseBranch}...HEAD`],
+      [...GIT_NO_HOOKS, "diff", "--numstat", `${baseBranch}...HEAD`],
       { cwd: worktreePath, encoding: "utf-8", timeout: 30_000 },
     );
     return parseNumstat(raw, maxFiles);

package/src/git-pr.ts

@@ -4,6 +4,7 @@ import type { Card } from "@harmony/shared";
 import { SAFE_GIT_REF_PATTERN } from "@harmony/shared";
 import type { MergeStrategy, WorktreeConfig } from "./exec-types.js";
 import { log } from "./log.js";
+import { GIT_NO_HOOKS } from "./run-containment.js";
 
 // Lazy + memoised: promisify(execFile) has no reason to run at module load.
 // git-pr.ts sits in the motor's public barrel (@gethmy/harness `export *`), so
@@ -33,10 +34,14 @@ export type GitProvider =
 
 export function detectGitProvider(cwd?: string): GitProvider {
   try {
-    const url = execFileSync("git", ["remote", "get-url", "origin"], {
-      cwd,
-      encoding: "utf-8",
-    }).trim();
+    const url = execFileSync(
+      "git",
+      [...GIT_NO_HOOKS, "remote", "get-url", "origin"],
+      {
+        cwd,
+        encoding: "utf-8",
+      },
+    ).trim();
 
     if (url.includes("github.com")) return "github";
     if (url.includes("dev.azure.com") || url.includes("visualstudio.com"))
@@ -671,7 +676,7 @@ export async function mergePullRequest(
 
 export function getHeadSha(cwd: string): string | null {
   try {
-    return execFileSync("git", ["rev-parse", "HEAD"], {
+    return execFileSync("git", [...GIT_NO_HOOKS, "rev-parse", "HEAD"], {
       cwd,
       encoding: "utf-8",
     }).trim();
@@ -947,7 +952,13 @@ export function remoteBranchExists(branchName: string, cwd: string): boolean {
   try {
     execFileSync(
       "git",
-      ["ls-remote", "--exit-code", "origin", `refs/heads/${branchName}`],
+      [
+        ...GIT_NO_HOOKS,
+        "ls-remote",
+        "--exit-code",
+        "origin",
+        `refs/heads/${branchName}`,
+      ],
       { cwd, stdio: "pipe" },
     );
     return true;
@@ -965,13 +976,13 @@ export function pushBranch(branchName: string, cwd: string): void {
     // lets a concurrent update slip through. Fetch + pin the expected SHA.
     let expectedSha: string | null = null;
     try {
-      execFileSync("git", ["fetch", "origin", branchName], {
+      execFileSync("git", [...GIT_NO_HOOKS, "fetch", "origin", branchName], {
         cwd,
         stdio: "pipe",
       });
       expectedSha = execFileSync(
         "git",
-        ["rev-parse", `refs/remotes/origin/${branchName}`],
+        [...GIT_NO_HOOKS, "rev-parse", `refs/remotes/origin/${branchName}`],
         { cwd, encoding: "utf-8" },
       ).trim();
     } catch (err) {
@@ -983,12 +994,16 @@ export function pushBranch(branchName: string, cwd: string): void {
     const lease = expectedSha
       ? `--force-with-lease=refs/heads/${branchName}:${expectedSha}`
       : "--force-with-lease";
-    execFileSync("git", ["push", lease, "-u", "origin", branchName], {
-      cwd,
-      stdio: "pipe",
-    });
+    execFileSync(
+      "git",
+      [...GIT_NO_HOOKS, "push", lease, "-u", "origin", branchName],
+      {
+        cwd,
+        stdio: "pipe",
+      },
+    );
   } else {
-    execFileSync("git", ["push", "-u", "origin", branchName], {
+    execFileSync("git", [...GIT_NO_HOOKS, "push", "-u", "origin", branchName], {
       cwd,
       stdio: "pipe",
     });
@@ -1009,7 +1024,7 @@ export function renameRemoteBranch(
   if (oldRef === newRef) return;
   let sha: string;
   try {
-    sha = execFileSync("git", ["rev-parse", "HEAD"], {
+    sha = execFileSync("git", [...GIT_NO_HOOKS, "rev-parse", "HEAD"], {
       cwd,
       encoding: "utf-8",
     }).trim();
@@ -1021,14 +1036,24 @@ export function renameRemoteBranch(
   log.info(TAG, `Renaming remote ${oldRef} → ${newRef}`);
   execFileSync(
     "git",
-    ["push", "origin", `${sha}:refs/heads/${newRef}`, "--force-with-lease"],
+    [
+      ...GIT_NO_HOOKS,
+      "push",
+      "origin",
+      `${sha}:refs/heads/${newRef}`,
+      "--force-with-lease",
+    ],
     { cwd, stdio: "pipe" },
   );
   try {
-    execFileSync("git", ["push", "origin", `:refs/heads/${oldRef}`], {
-      cwd,
-      stdio: "pipe",
-    });
+    execFileSync(
+      "git",
+      [...GIT_NO_HOOKS, "push", "origin", `:refs/heads/${oldRef}`],
+      {
+        cwd,
+        stdio: "pipe",
+      },
+    );
   } catch (err) {
     log.warn(
       TAG,
@@ -1036,7 +1061,7 @@ export function renameRemoteBranch(
     );
   }
   try {
-    execFileSync("git", ["branch", "-m", oldRef, newRef], {
+    execFileSync("git", [...GIT_NO_HOOKS, "branch", "-m", oldRef, newRef], {
       cwd,
       stdio: "pipe",
     });
@@ -1055,10 +1080,14 @@ export function getBranchWebUrl(
   cwd: string,
 ): string | null {
   try {
-    const remoteUrl = execFileSync("git", ["remote", "get-url", "origin"], {
-      cwd,
-      encoding: "utf-8",
-    }).trim();
+    const remoteUrl = execFileSync(
+      "git",
+      [...GIT_NO_HOOKS, "remote", "get-url", "origin"],
+      {
+        cwd,
+        encoding: "utf-8",
+      },
+    ).trim();
     const encoded = branchName.split("/").map(encodeURIComponent).join("/");
     if (/github\.com[:/]([^/]+)\/([^/.]+)/.test(remoteUrl)) {
       const m = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/);
@@ -1126,7 +1155,12 @@ export function createPullRequest(
   try {
     commitLog = execFileSync(
       "git",
-      ["log", "--oneline", `origin/${config.worktree.baseBranch}..HEAD`],
+      [
+        ...GIT_NO_HOOKS,
+        "log",
+        "--oneline",
+        `origin/${config.worktree.baseBranch}..HEAD`,
+      ],
       { cwd: worktreePath, encoding: "utf-8" },
     ).trim();
   } catch {

package/src/index.ts

@@ -34,6 +34,7 @@ export * from "./project-type.js";
 export * from "./repair-sandbox.js";
 export * from "./revert-guard.js";
 export * from "./review-types.js";
+export * from "./run-containment.js";
 export * from "./run-sizing.js";
 export * from "./runner.js";
 export * from "./sdk-agent-runner.js";

package/src/pm.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { log } from "./log.js";
+import { GIT_NO_HOOKS } from "./run-containment.js";
 
 const TAG = "pm";
 
@@ -16,9 +17,13 @@ export function detectPackageManager(): PackageManager {
 
   let repoRoot: string;
   try {
-    repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
-      encoding: "utf-8",
-    }).trim();
+    repoRoot = execFileSync(
+      "git",
+      [...GIT_NO_HOOKS, "rev-parse", "--show-toplevel"],
+      {
+        encoding: "utf-8",
+      },
+    ).trim();
   } catch {
     repoRoot = process.cwd();
   }

package/src/revert-guard.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { log } from "./log.js";
+import { GIT_NO_HOOKS } from "./run-containment.js";
 
 const TAG = "revert-guard";
 
@@ -44,7 +45,7 @@ export function filterTestFiles(paths: string[]): string[] {
  */
 function refetchBase(worktreePath: string, baseBranch: string): void {
   try {
-    execFileSync("git", ["fetch", "origin", baseBranch], {
+    execFileSync("git", [...GIT_NO_HOOKS, "fetch", "origin", baseBranch], {
       cwd: worktreePath,
       stdio: "pipe",
     });
@@ -69,7 +70,13 @@ export function listDeletedFilesAgainstBase(
   try {
     const out = execFileSync(
       "git",
-      ["diff", "--diff-filter=D", "--name-only", `origin/${baseBranch}...HEAD`],
+      [
+        ...GIT_NO_HOOKS,
+        "diff",
+        "--diff-filter=D",
+        "--name-only",
+        `origin/${baseBranch}...HEAD`,
+      ],
       { cwd: worktreePath, encoding: "utf-8" },
     );
     return out