@gethmy/harness 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/harness",
-  "version": "1.5.0",
+  "version": "1.7.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.2.0",
+    "@gethmy/mcp": "3.3.0",
     "@supabase/supabase-js": "2.95.3"
   },
   "devDependencies": {

package/src/cli.ts

@@ -241,8 +241,28 @@ async function main(): Promise<void> {
     process.stderr.write(`${parsed.message}\n${STAGE_RUN_USAGE}\n`);
     process.exit(2);
   }
-  const { cardId, stageId, workspaceId, repoPath, sessionId, metricsPath } =
-    parsed.args;
+  const {
+    cardId,
+    stageId,
+    workspaceId,
+    repoPath,
+    sessionId,
+    metricsPath,
+    sandboxImage,
+  } = parsed.args;
+
+  // The DRIVER's container for everything this motor runs against the worktree
+  // (#1021): the held test, and the `build_green` gate's build and lint. One
+  // value, every gate command — an operator who set an image to keep untrusted
+  // code off their host did not mean "except this one".
+  //
+  // Absent ⇒ `undefined`, which is host execution exactly as before. Trimmed and
+  // re-checked for emptiness here as well as in the flag parser, because docker
+  // reads an empty image name as a missing argument and fails in a way that
+  // reads like a broken runtime.
+  const gateSandbox = sandboxImage?.trim()
+    ? { image: sandboxImage.trim() }
+    : undefined;
 
   // The driver's metric allowlist for `custom` gates (--metrics, optional).
   // Read + validated BEFORE anything runs: a driver that passed the flag wants
@@ -344,6 +364,12 @@ async function main(): Promise<void> {
           worktreePath: req.repoPath,
           buildTimeout: GATE_VERIFICATION_TIMEOUT_MS,
           lintTimeout: GATE_VERIFICATION_TIMEOUT_MS,
+          // #1021 closes the residual #1036 recorded here: the motor used to
+          // hold no operator config, so this gate re-ran the worktree's own
+          // build and lint scripts in the motor process while the daemon's
+          // identical gate ran them in a container. The driver passes the image
+          // now, so both paths honour one setting.
+          sandbox: gateSandbox,
         },
         // The metric allowlist is the DRIVER's, passed via --metrics — the
         // motor still holds no operator config of its own. Without the flag
@@ -361,6 +387,12 @@ async function main(): Promise<void> {
         oracle: {
           repoPath: req.repoPath,
           sessionId: req.sessionId,
+          // #1021. The held test is arbitrary code an untrusted author wrote,
+          // and this is the only place a container can be put around it — the
+          // oracle gates run in the motor and nowhere else (the daemon's own
+          // registry wires no oracle collector, by design: it cannot provide
+          // the actor separation these gates bind on).
+          sandbox: gateSandbox,
           // Only `oracle_red` reads this (its own stage is not the key); the
           // green collector addresses the row by `context.stageId`.
           targetStageId: oracleTargetStageId,

package/src/exec-types.ts

@@ -95,9 +95,102 @@ 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.
+     *
+     * **It covers the HELD TEST too since #1021**, and that is the one command
+     * here whose *input* is written by an untrusted author rather than being a
+     * script a contained run may have rewritten. The daemon forwards this value
+     * to the harness motor (`--sandbox-image`), which is where both held-test
+     * gates run, so one setting covers every command the gate machinery executes
+     * against a worktree. The image must carry the RUNNER the oracle's
+     * `runner_hint` names, not merely a toolchain — measured, `oven/bun:1` has
+     * `bun` and `node` but no `npx`, so a `vitest`-hinted held test in it reports
+     * the gate `blocked` with a message naming the image.
+     *
+     * Cost of the held-test half, measured on macOS / Docker Desktop with a warm
+     * image: ~0.14 s added for a trivial held test and ~1.4 s for one that
+     * resolves a dependency out of a real `node_modules`, twice per card. Far
+     * below the ~5.1 s per verification command above, because a held test reads
+     * one file and its imports rather than running the repo's whole build.
+     *
+     * **And the two `dev` servers since #1037** (`runDeepReview`'s and the
+     * review worker's) — one key, every command the daemon runs against a
+     * worktree, because the image requirement is the same one and an operator
+     * who set a second key but not this one would get a half-contained daemon.
+     *
+     * Their container is the same in every respect but the network: a dev
+     * server exists to be connected to, so it publishes `127.0.0.1:<port>`
+     * rather than taking `--network=none`, and therefore keeps egress. That is
+     * the one place this setting buys less than it does for the four
+     * verification steps and the held test, and `devServerSandboxArgs` says why
+     * no flag combination avoids it.
+     *
+     * Setting this makes Docker load-bearing for review, not only for
+     * verification: the dev server then starts through `docker run`, and a host
+     * that cannot start it fails the same way an unstartable host server
+     * already does — the review worker keeps the card in Review and labels it
+     * for a human rather than bouncing it back for rework.
+     */
+    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-pr.ts

@@ -246,6 +246,19 @@ function isNamedCheck(
  * reads `success` rather than `unknown`, because `unknown` means "this repo
  * configures no checks at all" — a repo whose only check is the review has a
  * green build by that repo's own definition, and the review gates it below.
+ *
+ * ## SKIPPED is a pass HERE, and that is correct — measured, card #903
+ *
+ * Folding `SKIPPED` in with `SUCCESS` is right for everything this function is
+ * still allowed to speak for. After the exclusion above, that is the build and
+ * test jobs, where a skip is a **path filter** doing its job: on the 45 PR heads
+ * sampled for #903, `test`, `build` and `EAS Build & TestFlight Submit` all
+ * report `SKIPPED` on scope-filtered PRs that are green by every definition
+ * their repo has. Failing on those would block every docs-only PR.
+ *
+ * The reason this is safe is the exclusion, NOT the fold: a review that never
+ * fired is a skip that must HOLD, and it does — because its check name is taken
+ * out of this verdict and answered by the two readers below.
  */
 export function deriveCiStatus(
   rollup: unknown,
@@ -289,14 +302,21 @@ export function deriveCiStatus(
  * Whether an INDEPENDENT review — one produced outside the daemon that wrote the
  * code — has run against the PR's current head (card #1003).
  *
- * `deriveCiStatus` above cannot answer this, and that is the whole bug: it folds
- * `SKIPPED` in with `SUCCESS` (see its `["SUCCESS", "NEUTRAL", "SKIPPED"]`
- * line). A daemon PR on an `agent/` branch has its review job skipped by the
- * workflow's own branch rule, so the rollup carries a real check run reading
+ * `deriveCiStatus` above cannot answer this, because it folds `SKIPPED` in with
+ * `SUCCESS` (see its `["SUCCESS", "NEUTRAL", "SKIPPED"]` line). A daemon PR on
+ * an `agent/` branch has its review job skipped by the workflow's own branch
+ * rule, so the rollup carries a real check run reading
  * `{name: "review", conclusion: "SKIPPED"}` — and the collapsed verdict for that
- * PR is `"success"`. The merge gate could not tell "reviewed and clean" from
+ * PR was `"success"`. The merge gate could not tell "reviewed and clean" from
  * "nobody looked".
  *
+ * That was a live bug until #1018, and it is **fixed by the exclusion, not by a
+ * change to the fold**: `readPrChecks` takes both review check names out of
+ * `deriveCiStatus`, so a skipped review no longer reaches the collapsed word at
+ * all. The fold stays, and stays correct, for the build/test jobs it still
+ * speaks for. Do not "reconcile" the three answers — see #903 on the ruling
+ * that they are three different questions and must keep three different answers.
+ *
  * `absent` and `skipped` are kept apart on purpose. `skipped` means the workflow
  * exists and declined this branch, which a `ci-review` request can fix. `absent`
  * means no such check is configured on this repo at all — a request would be
@@ -322,6 +342,28 @@ export type IndependentReviewState =
  * independent did read this head, which is the question being asked; a pending
  * re-run outranks the failed run it is retrying, so the gate waits for the
  * answer instead of acting on the stale one.
+ *
+ * ## Why "several runs share the name" is the normal case (measured, #903)
+ *
+ * `statusCheckRollup` **retains every check run on a SHA**. It does not collapse
+ * to the most recent run of a name, and nothing supersedes anything. Two
+ * mechanisms decide whether a re-review adds an entry or overwrites one:
+ *
+ *  - a **new triggering event** (`labeled` for `ci-review`, `reopened`, …)
+ *    starts a new workflow run, which publishes a NEW check run of the same
+ *    name. Both entries persist, forever, side by side.
+ *  - `gh run rerun` REUSES the run's `databaseId` and UPDATES its check run in
+ *    place, so that one leaves a single entry.
+ *
+ * Observed on PR 719 (`134d0a62`), where `review` reads `CANCELLED` and
+ * `SUCCESS` together — the cancel came from the review workflow's own
+ * `cancel-in-progress` concurrency group, and the success is the re-review that
+ * followed it. Note it did not REPLACE it, which is the point. This precedence
+ * is what makes that PR readable as `passed`
+ * instead of `failed`, and the #1018 exclusion is what keeps the stale
+ * `CANCELLED` out of `ciStatus`. On the 45 PR heads sampled, PR 719 is the ONE
+ * case where the exclusion changes the collapsed verdict — without it that PR
+ * reads `failure` on a branch whose review had actually succeeded.
  */
 export function deriveIndependentReviewState(
   rollup: unknown,
@@ -433,6 +475,12 @@ export type ReviewVerdictState =
  * because a finding does not stop being real when a later pass over the same
  * head fails to repeat it. The remedy for a blocking verdict is a commit that
  * fixes it, which moves the head and asks again with a clean slate.
+ *
+ * That remedy is not a preference, it is the only one that works. Because the
+ * rollup retains every run (measured, #903 — see the note on the reader above),
+ * a `blocking` verdict CANNOT be cleared by re-requesting a review on the same
+ * head: the re-request publishes a second check run and the failing one stays
+ * beside it. Moving the head is the exit.
  */
 export function deriveReviewVerdictState(
   rollup: unknown,

package/src/oracle-collector.ts

@@ -44,6 +44,7 @@ import {
   type HeldOracle,
   type OracleDeps,
   type OracleRunSummary,
+  OracleSandboxConfigError,
 } from "./oracle.js";
 
 const TAG = "oracle-collector";
@@ -142,6 +143,11 @@ abstract class HeldOracleCollector {
       const { exitCode, output, report } = await this.deps.run(
         this.deps.repoPath,
         oracle,
+        // #1021. Both polarities take the same container: `oracle_passed` runs
+        // the same untrusted file as `oracle_red`, so containing one and not
+        // the other would leave the hole under the other gate's name. Only the
+        // GRADING differs between them, and that stays where it is.
+        { sandbox: this.deps.sandbox },
       );
       // Full output is for the human operator's local log only — never the
       // persisted evidence. See the class doc comment: oracle_passed is a
@@ -161,12 +167,31 @@ abstract class HeldOracleCollector {
       });
     } catch (err) {
       const message = errText(err);
-      log.warn(TAG, `Oracle run threw: ${message} — blocked`);
+      // #823 rule 1: opt in, and ONLY for static config. A sandbox that is not
+      // answering, or an image that cannot start or does not carry the runner,
+      // is the operator's configuration — re-running the stage cannot change the
+      // answer, so an unmarked `blocked` would spend the card's whole attempt
+      // budget rediscovering it. Every other throw here (a bad path, a timeout,
+      // a runner that died) keeps the retryable default, because a next attempt
+      // genuinely can differ.
+      const configError = err instanceof OracleSandboxConfigError;
+      log.warn(
+        TAG,
+        `Oracle run threw: ${message} — blocked${configError ? " (config)" : ""}`,
+      );
       return {
         result: "blocked",
         structured: {
           oracle: { path: oracle.path, ...identity },
           error: message,
+          // `reason` as well as `error`, and only on this branch: it is the
+          // field `gateConfigErrorReason` reads, so without it the board renders
+          // the generic "the gate cannot be measured as configured" for a hold
+          // whose whole value is naming the image the operator has to fix.
+          // `error` stays for every existing reader of this shape.
+          ...(configError
+            ? { reason: message, ...GATE_CONFIG_ERROR_MARK }
+            : {}),
         },
       };
     } finally {
@@ -293,13 +318,18 @@ export class OracleCollector
  * the forgery.
  *
  * HOW FAR THAT GOES: it closes the stream forgeries outright, and it does NOT
- * make the verdict unforgeable. The held test runs as the motor's own user and
- * can write the report file itself — the directory is findable by a fixed name
- * prefix, and pre-writing the report then dropping write permission needs no
- * race at all. `runHeldOracle`'s mode check refuses that shape; a writer that
- * leaves the modes alone still wins. This gate is evidence against a careless
- * author, not a hostile one. `oracle.ts` has the full account, measurements
- * included, above `OracleRunnerSpec`.
+ * make the report FILE unforgeable — the held test executes inside the runner's
+ * process, so it can write that file on the host and in the container alike.
+ * What #1021 added is a claim check rather than an authentication one: neither
+ * allow-listed runner exits 0 while reporting a failing test, so a report saying
+ * `failed > 0` from a run that exited 0 is refused. That removes the free
+ * forgery — one file satisfying the red gate and the green gate out of a single
+ * run — and leaves a held test that wants both polarities having to exit
+ * differently before and after the fix. With `verification.sandboxImage` set the
+ * run also happens inside `repair-sandbox.ts`'s container, where the held test
+ * cannot reach the motor's host at all and no straggler outlives the run.
+ * `oracle.ts` has the full account, measurements included, above
+ * `OracleRunnerSpec`.
  *
  * Secrecy is inherited whole. The report is parsed in memory and only its two
  * counts reach the persisted evidence — never the assertion text, which is itself