@gethmy/harness 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/harness",
-  "version": "1.2.1",
+  "version": "1.3.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": "2.25.0",
+    "@gethmy/mcp": "3.0.0",
     "@supabase/supabase-js": "2.95.3"
   },
   "devDependencies": {

package/src/ci-failure.ts

@@ -0,0 +1,465 @@
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import type { GitProvider } from "./git-pr.js";
+import { log } from "./log.js";
+
+/**
+ * Reading a red CI in enough detail to act on it (card #981).
+ *
+ * `getPrStatus` collapses `statusCheckRollup` into one of four strings, which is
+ * everything the merge gate needs and nothing a repair can use: it cannot say
+ * WHICH check failed, and it throws away the `detailsUrl` that names the
+ * workflow run. This module keeps both, and adds the one distinction that
+ * decides how much a red CI is worth spending on.
+ *
+ * **A flaky or infrastructure failure is a re-run, not a code change.** The repo
+ * has a documented history of them — `deploy-supabase` failing on an esm.sh 522,
+ * a GitHub Actions job dying in "Set up job" on DNS, `setup-bun` taking a 503
+ * from the runner's IP. Editing source to "fix" any of those produces a wrong
+ * change that happens to go green. Re-dispatching them costs a `gh run rerun`.
+ *
+ * The split mirrors `error-classifier.ts`, which does this job for API errors:
+ * {@link classifyCiFailure} is a pure ordered-regex matcher, so the whole
+ * taxonomy is table-testable, and the three `gh` wrappers below are the only
+ * part that touches a network.
+ *
+ * GitHub-only, like every other consumer of `statusCheckRollup`. A non-GitHub
+ * provider gets an empty list and the caller falls back to today's behaviour.
+ */
+
+// Lazy + memoised for the same reason git-pr.ts does it: this module sits in the
+// harness barrel, and constructing a promisified execFile at module load would
+// charge every consumer of every harness export for it.
+function createExecFileAsync() {
+  return promisify(execFile);
+}
+
+let cachedExecFileAsync: ReturnType<typeof createExecFileAsync> | undefined;
+
+function execFileAsync() {
+  return (cachedExecFileAsync ??= createExecFileAsync());
+}
+
+const TAG = "ci-failure";
+
+/** How much of a failing job's log the classifier reads. */
+const LOG_TAIL_BYTES = 16_000;
+
+/** A check's display name is a label, not a document. Anything longer is noise. */
+const MAX_CHECK_NAME = 200;
+
+/**
+ * Everything this module returns is UNTRUSTED REMOTE TEXT, and the repair loop
+ * feeds it to an LLM that runs with file-editing tools inside the checkout. That
+ * makes prompt injection a real code path rather than a theoretical one, so the
+ * text is neutralised HERE, at the boundary where it enters the process, rather
+ * than at the point of use where a future caller could forget.
+ *
+ * Two properties, both load-bearing:
+ *
+ *  - **No fence can be closed.** The consumer embeds this text in a ``` block.
+ *    A check name or log line containing its own ``` would end that block and
+ *    let whatever follows read as instructions to the model. Backticks are
+ *    replaced outright — nothing downstream needs them, and stripping is safer
+ *    than escaping, which has to be right at every layer.
+ *  - **No control characters.** ANSI escapes and carriage returns let text
+ *    rewrite what a reader (human or model) sees above it.
+ *
+ * This is defence in depth, not the primary control: {@link isPrOnOrigin} keeps
+ * a foreign PR out of the loop altogether, and the repair spawns without `Bash`.
+ * It is here because a compromised third-party action can put arbitrary text
+ * into the daemon's OWN job log, where neither of those two helps.
+ */
+export function sanitizeCiText(text: string, maxLength: number): string {
+  return (
+    text
+      // Backtick = fence escape. Replaced rather than escaped: nothing
+      // downstream needs one, and stripping cannot be got subtly wrong the
+      // way escaping can at each layer that re-renders the string.
+      .replace(/`/g, "'")
+      // ANSI escapes and other control bytes, keeping \t and \n. They let
+      // text rewrite what a reader sees above it.
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: neutralising terminal control bytes is the point
+      .replace(/[\u0000-\u0008\u000B-\u001F\u007F]/g, " ")
+      .slice(0, maxLength)
+  );
+}
+
+/** `owner/repo` out of a GitHub remote URL (ssh or https), or null. */
+function githubSlug(remoteOrPrUrl: string): string | null {
+  const m = remoteOrPrUrl.match(
+    /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?(?:\/|$)/i,
+  );
+  return m ? `${m[1].toLowerCase()}/${m[2].toLowerCase()}` : null;
+}
+
+/**
+ * The only PR url shape the repair loop will act on: `https://github.com/<owner>/<repo>/pull/<n>`,
+ * with nothing after the number.
+ *
+ * The slug check alone was not enough. `extractPrUrl` captures any run of
+ * non-whitespace after the card's `PR:` line, and a query component legally
+ * carries characters a path does not — including U+0060 backtick, which WHATWG
+ * URL normalisation percent-encodes in the path and fragment but NOT in the
+ * query. `gh pr view` ignores the query when resolving the PR, so
+ * `…/pull/123?x=<backticks and text>` addressed the right PR while smuggling
+ * fence-breaking text into anything that interpolated the url. Requiring the
+ * exact shape drops query and fragment entirely rather than trying to clean them.
+ */
+const STRICT_PR_URL_RE =
+  /^https:\/\/github\.com\/[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\/pull\/\d+$/;
+
+/**
+ * Is this PR in the repository the daemon itself is checked out from?
+ *
+ * **The primary trust control for the repair loop.** The PR url reaching the
+ * merge monitor comes from the card's `PR:` line — ordinary board data that any
+ * workspace member can edit. Without this check, editing that line to a pull
+ * request in a repository the editor controls would point the repair at a
+ * `statusCheckRollup` they compose: check-run names are free text via the GitHub
+ * Checks API, and job logs are whatever their workflow prints. That text is read
+ * by an LLM that runs with file-editing tools inside the daemon's checkout, on a
+ * host holding `gh` credentials and the daemon's own API key.
+ *
+ * So the loop reads checks and logs only from its OWN origin, and only from a url
+ * of the exact {@link STRICT_PR_URL_RE} shape — the slug alone let a query string
+ * ride along, which is its own problem (see that constant). Checked before any
+ * remote read, and fails CLOSED: an unreadable remote, an off-shape or
+ * unparseable url, or a non-GitHub remote all answer `false`. A daemon that
+ * cannot prove the PR is its own does not read it.
+ *
+ * Deliberately narrower than `isValidPrUrl` in git-pr.ts, which only asserts the
+ * HOST is a known forge — enough to decide whether to poll a CI status, not
+ * enough to decide whose text to feed a model.
+ */
+export function isPrOnOrigin(prUrl: string, cwd: string): boolean {
+  if (!STRICT_PR_URL_RE.test(prUrl)) return false;
+  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();
+    return githubSlug(remote) === prSlug;
+  } catch {
+    return false;
+  }
+}
+
+/** One failing entry of a PR's `statusCheckRollup`. */
+export interface FailedCheck {
+  /** The check's display name, e.g. "Type Check" or "deploy-supabase". */
+  name: string;
+  /** The upper-cased conclusion, e.g. "FAILURE", "TIMED_OUT", "CANCELLED". */
+  conclusion: string;
+  /** The check's link, e.g. `https://github.com/o/r/actions/runs/123/job/456`. */
+  detailsUrl: string | null;
+  /** The workflow run id parsed out of {@link detailsUrl}, when it has one. */
+  workflowRunId: string | null;
+}
+
+const RUN_ID_RE = /\/actions\/runs\/(\d+)/;
+
+/**
+ * The workflow run id inside a check's `detailsUrl`, or null.
+ *
+ * This is what makes a re-dispatch addressable: `gh run rerun` takes a RUN id,
+ * while `statusCheckRollup` hands out a JOB url. A check that is not an Actions
+ * run at all (an external status context, a third-party app) has no run id, and
+ * gets null rather than a guess.
+ */
+export function extractWorkflowRunId(
+  detailsUrl: string | null | undefined,
+): string | null {
+  if (!detailsUrl) return null;
+  return detailsUrl.match(RUN_ID_RE)?.[1] ?? null;
+}
+
+/**
+ * The FAILING entries of a `gh pr view --json statusCheckRollup` array, with the
+ * per-check fields kept.
+ *
+ * Pure, and deliberately the same shape-handling as `deriveCiStatus`: a CheckRun
+ * (`{status, conclusion}`) and a legacy StatusContext (`{state}`) both appear in
+ * the rollup, and a repair that only understood one of them would read half a
+ * red CI as green. A still-running check is NOT a failure and never appears
+ * here — that is `pending`, which the merge gate already waits on.
+ */
+export function parseFailedChecks(rollup: unknown): FailedCheck[] {
+  if (!Array.isArray(rollup)) return [];
+  const failed: FailedCheck[] = [];
+  for (const check of rollup) {
+    if (typeof check !== "object" || check === null) continue;
+    const c = check as Record<string, unknown>;
+    // Sanitised HERE, not at the point of use. A check-run name is
+    // attacker-chosen text — anyone who can create a check run via the GitHub
+    // Checks API sets it freely — and it ends up inside an LLM prompt.
+    const name = sanitizeCiText(
+      (typeof c.name === "string" && c.name) ||
+        (typeof c.context === "string" && c.context) ||
+        "unnamed check",
+      MAX_CHECK_NAME,
+    );
+    const detailsUrl =
+      (typeof c.detailsUrl === "string" && c.detailsUrl) ||
+      (typeof c.targetUrl === "string" && c.targetUrl) ||
+      null;
+
+    if (typeof c.status === "string") {
+      // CheckRun — only a COMPLETED run has a verdict to read.
+      if (c.status.toUpperCase() !== "COMPLETED") continue;
+      const conclusion =
+        typeof c.conclusion === "string" ? c.conclusion.toUpperCase() : "";
+      if (["SUCCESS", "NEUTRAL", "SKIPPED"].includes(conclusion)) continue;
+      failed.push({
+        name,
+        conclusion: conclusion || "FAILURE",
+        detailsUrl,
+        workflowRunId: extractWorkflowRunId(detailsUrl),
+      });
+      continue;
+    }
+
+    if (typeof c.state === "string") {
+      // Legacy StatusContext.
+      const state = c.state.toUpperCase();
+      if (state === "SUCCESS" || state === "PENDING") continue;
+      failed.push({
+        name,
+        conclusion: state,
+        detailsUrl,
+        workflowRunId: extractWorkflowRunId(detailsUrl),
+      });
+    }
+  }
+  return failed;
+}
+
+/**
+ * What kind of red this is.
+ *
+ * `infra` means nothing in the branch caused it and nothing in the branch can
+ * fix it — re-dispatch. `code` means the branch is genuinely broken and only an
+ * edit resolves it.
+ */
+export type CiFailureKind = "infra" | "code";
+
+export interface CiFailureClass {
+  kind: CiFailureKind;
+  /**
+   * The signature that matched, for the log line and the board event. Null on
+   * the `code` default, where nothing matched and there is no signature to name.
+   */
+  signal: string | null;
+}
+
+/**
+ * The infrastructure signatures, most specific first.
+ *
+ * Every one is a failure this repo has actually taken, recorded where the
+ * evidence for it lives. They are matched against the failing job's log and the
+ * check's own name, because some of them (a job that dies in "Set up job")
+ * produce almost no log at all.
+ *
+ * Order matters, as in `error-classifier.ts`: a narrow signature must precede a
+ * broad one, or the broad one claims its matches and the log line names the
+ * wrong cause. Keep additions in the same style — a named signal, a comment
+ * saying where the case came from, and a pattern narrow enough that a genuine
+ * test failure quoting the same words cannot trip it.
+ */
+const INFRA_SIGNATURES: { signal: string; pattern: RegExp }[] = [
+  // deploy-supabase pulls Deno deps from esm.sh, which returns 522 under load.
+  { signal: "esm.sh 5xx", pattern: /esm\.sh[^\n]{0,200}?\b5\d\d\b/i },
+  // setup-bun 503s from runner IPs; pinning an exact version is the workaround.
+  {
+    signal: "setup-bun unavailable",
+    pattern: /setup-bun[^\n]{0,200}?\b(?:503|502|504)\b/i,
+  },
+  // A job that fails inside "Set up job" never ran a step of ours. NOT anchored
+  // to a line start: `gh run view --log-failed` prefixes every line with
+  // `<job>\t<step>\t<timestamp> `, so an anchored pattern could only ever match
+  // the check NAME half of the haystack and would be dead against the log it was
+  // written for.
+  {
+    signal: "runner setup failed",
+    pattern: /(?:##\[error\])?Set up job[^\n]{0,120}?(?:fail|error)/i,
+  },
+  // Runner DNS / TLS / connection resets reaching a host.
+  //
+  // Deliberately NOT a bare alternation of the socket error codes. A genuine
+  // test failure prints its assertion values, and a suite that exercises network
+  // error handling — this repo's own `ci-failure.test.ts` among them — puts
+  // `ECONNRESET` or `EAI_AGAIN` straight into the failing output. Reading that
+  // as infrastructure is the DANGEROUS direction: it re-runs a branch that is
+  // really broken until the cap is gone and never looks at the diff. So each
+  // token must arrive the way the runner actually emits it — as a syscall
+  // failure naming a host, or a Node error line — rather than as a bare word
+  // anywhere in a log.
+  {
+    signal: "runner network",
+    pattern:
+      /(?:getaddrinfo\s+(?:EAI_AGAIN|ENOTFOUND)|connect\s+(?:ETIMEDOUT|ECONNREFUSED)\s+[\d.:]|(?:read|write)\s+ECONNRESET\b[^\n]{0,80}(?:https?:|\.com|\.org|\.io|\.sh|\.dev)|TLS handshake timeout)/i,
+  },
+  // GitHub's own infrastructure telling us so.
+  {
+    signal: "actions infrastructure",
+    pattern:
+      /(?:The (?:self-hosted )?runner[^\n]{0,80}lost communication|The operation was canceled[^\n]{0,80}runner|We are experiencing (?:a )?(?:degraded|high) )/i,
+  },
+  // A registry or proxy 5xx during dependency install.
+  {
+    signal: "registry 5xx",
+    pattern:
+      /(?:npm|bun|yarn|pnpm)[^\n]{0,200}?\b(?:502 Bad Gateway|503 Service Unavailable|504 Gateway Time-?out)\b/i,
+  },
+];
+
+/**
+ * Is this red worth an edit, or only a re-dispatch?
+ *
+ * Pure. **Defaults to `code`**, and that asymmetry is deliberate: an
+ * unrecognised failure is far more often a real one, and the two mistakes do not
+ * cost the same. Reading infra as code spends one bounded repair attempt that
+ * finds nothing to change (and, finding nothing, commits nothing and pushes
+ * nothing). Reading code as infra re-dispatches a genuinely broken branch until
+ * the cap runs out and never looks at the diff. The cap bounds the first
+ * mistake; nothing bounds the damage of the second except this default.
+ */
+export function classifyCiFailure(input: {
+  /** The failing check's name. */
+  checkName: string;
+  /** The failing job's log, or as much of it as could be fetched. May be empty. */
+  log: string;
+}): CiFailureClass {
+  const haystack = `${input.checkName}\n${input.log}`;
+  for (const { signal, pattern } of INFRA_SIGNATURES) {
+    if (pattern.test(haystack)) return { kind: "infra", signal };
+  }
+  return { kind: "code", signal: null };
+}
+
+/** One sentence naming what the classifier decided, for a log line or the board. */
+export function describeCiFailure(failure: CiFailureClass): string {
+  return failure.kind === "infra"
+    ? `infrastructure failure (${failure.signal}) — re-dispatching, no code change`
+    : "a real build or test failure — repairing the branch";
+}
+
+/**
+ * The verdict for a red CI made of SEVERAL failing checks.
+ *
+ * `infra` only when EVERY failing check is infrastructure. One genuinely broken
+ * check among a set of flakes still needs an edit, and re-dispatching the batch
+ * would spend the repair budget re-running a break that can never pass — the
+ * "misreading code as infra" direction the module doc names as the dangerous
+ * one. This repo makes that concrete: `deploy-supabase` flakes on an esm.sh 522
+ * about a fifth of the time, so a PR can easily show that flake beside a real
+ * `Type Check` failure, and classifying from whichever the rollup happened to
+ * list first would park the card having never read the diff.
+ *
+ * An empty list is `code` — the same conservative default a single unrecognised
+ * failure gets.
+ */
+export function classifyCiFailures(failures: CiFailureClass[]): CiFailureClass {
+  if (failures.length === 0) return { kind: "code", signal: null };
+  const infra = failures.filter((f) => f.kind === "infra");
+  if (infra.length !== failures.length) return { kind: "code", signal: null };
+  // Name every distinct signature, so the log and the board event say which
+  // failures were re-dispatched rather than only the first one.
+  const signals = [...new Set(infra.map((f) => f.signal).filter(Boolean))];
+  return { kind: "infra", signal: signals.join(", ") || null };
+}
+
+/**
+ * The failing checks on a PR, with their per-check detail.
+ *
+ * Best-effort in the same posture as `getPrStatus`: any failure — a missing
+ * `gh`, an auth problem, a rate limit, unparseable JSON — returns an empty list,
+ * and the caller then does nothing rather than acting on half a picture.
+ */
+export async function getPrFailedChecks(
+  prUrl: string,
+  cwd: string,
+  provider: GitProvider,
+): Promise<FailedCheck[]> {
+  if (provider !== "github") return [];
+  try {
+    const { stdout } = await execFileAsync()(
+      "gh",
+      ["pr", "view", prUrl, "--json", "statusCheckRollup"],
+      { cwd, encoding: "utf-8", timeout: 15_000 },
+    );
+    const parsed = JSON.parse(stdout.trim()) as { statusCheckRollup?: unknown };
+    return parseFailedChecks(parsed.statusCheckRollup);
+  } catch (err) {
+    log.warn(
+      TAG,
+      `could not read failing checks for ${prUrl}: ${err instanceof Error ? err.message : err}`,
+    );
+    return [];
+  }
+}
+
+/**
+ * The tail of a workflow run's FAILED steps — the classifier's evidence.
+ *
+ * `--log-failed` is the whole point: a full run log is megabytes of successful
+ * steps, and the signature we are looking for is in the step that died. Returns
+ * "" on any failure, which the classifier then reads as "no evidence" and
+ * resolves to `code` — the safe default.
+ */
+export async function getFailedRunLog(
+  runId: string,
+  cwd: string,
+): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync()(
+      "gh",
+      ["run", "view", runId, "--log-failed"],
+      { cwd, encoding: "utf-8", timeout: 60_000, maxBuffer: 32 * 1024 * 1024 },
+    );
+    // Tail first, then sanitise — the cap inside `sanitizeCiText` takes a
+    // PREFIX, and the evidence worth reading is at the end of a failing job.
+    return sanitizeCiText(stdout.slice(-LOG_TAIL_BYTES), LOG_TAIL_BYTES);
+  } catch (err) {
+    // A run whose logs expired, a job still uploading, a `gh` without scope —
+    // all of them mean "no evidence", never "not a failure".
+    log.debug(
+      TAG,
+      `could not read failed-step log for run ${runId}: ${err instanceof Error ? err.message : err}`,
+    );
+    return "";
+  }
+}
+
+/**
+ * Re-dispatch only the failed jobs of a workflow run.
+ *
+ * `--failed` rather than a whole re-run: the successful jobs already proved
+ * themselves against this exact head, and re-running them spends runner minutes
+ * to learn nothing. Returns whether the re-dispatch was accepted, so the caller
+ * can tell "asked GitHub to try again" from "could not ask" and count only the
+ * former as an attempt.
+ */
+export async function rerunFailedJobs(
+  runId: string,
+  cwd: string,
+): Promise<boolean> {
+  try {
+    await execFileAsync()("gh", ["run", "rerun", runId, "--failed"], {
+      cwd,
+      encoding: "utf-8",
+      timeout: 30_000,
+    });
+    log.info(TAG, `re-dispatched failed jobs of run ${runId}`);
+    return true;
+  } catch (err) {
+    log.warn(
+      TAG,
+      `could not re-dispatch run ${runId}: ${err instanceof Error ? err.message : err}`,
+    );
+    return false;
+  }
+}

package/src/cli.ts

@@ -306,12 +306,19 @@ async function main(): Promise<void> {
   // accident.
   assertStageIsAgentRunnable(pinned.stage);
 
+  // Resolved ONCE and used twice: the author's prompt needs it to know which
+  // stage to POST its held test against, and an `oracle_red` gate needs it to
+  // read that same row back (the row is keyed to the TARGET, not to the writer).
+  // Two independent resolutions could disagree and would put the author's write
+  // and the red gate's read on different keys.
+  const oracleTargetStageId = findOracleTargetStage(version, stageId);
+
   const prompt = buildStagePrompt({
     cardId,
     stageId,
     stage: pinned.stage,
     sessionId,
-    oracleTargetStageId: findOracleTargetStage(version, stageId),
+    oracleTargetStageId,
   });
 
   const request: StageRunRequest = {
@@ -354,6 +361,9 @@ async function main(): Promise<void> {
         oracle: {
           repoPath: req.repoPath,
           sessionId: req.sessionId,
+          // Only `oracle_red` reads this (its own stage is not the key); the
+          // green collector addresses the row by `context.stageId`.
+          targetStageId: oracleTargetStageId,
           fetchOracle: (oracleCardId, oracleStageId, oracleSessionId) =>
             client.fetchOracle(oracleCardId, oracleStageId, oracleSessionId),
           place,