@gethmy/harness 1.2.1 → 1.4.0

package/src/git-pr.ts

@@ -137,15 +137,124 @@ export function upsertReviewedSha(description: string, sha: string): string {
   return `${description}${sep}${line}`;
 }
 
+// The independent-review request ledger (card #1003). Deliberately the same
+// shape and channel as `Reviewed-SHA` above: one line in the card description,
+// keyed by the head it applies to.
+//
+// It exists to bound cost, not to record a verdict. Requesting a CI review is a
+// remove-then-add of a label, which GitHub answers with a fresh paid Opus/Sonnet
+// pass — and the merge monitor ticks every 60s. Without a per-head record of
+// "already asked", a review that has not yet registered a check run would be
+// re-requested on every tick, billing a full review a minute. Keyed by SHA
+// rather than a bare boolean so that a branch which moves after its review
+// (the `rereview` path) correctly asks again for the new head.
+const CI_REVIEW_REQUESTED_SHA_RE =
+  /^CI-Review-Requested-SHA:\s*([0-9a-f]{7,40})\s*$/im;
+
+export function extractCiReviewRequestedSha(
+  description: string | null,
+): string | null {
+  if (!description) return null;
+  const m = description.match(CI_REVIEW_REQUESTED_SHA_RE);
+  return m ? m[1] : null;
+}
+
+export function upsertCiReviewRequestedSha(
+  description: string,
+  sha: string,
+): string {
+  const line = `CI-Review-Requested-SHA: ${sha}`;
+  if (CI_REVIEW_REQUESTED_SHA_RE.test(description)) {
+    return description.replace(CI_REVIEW_REQUESTED_SHA_RE, line);
+  }
+  const sep = description ? "\n" : "";
+  return `${description}${sep}${line}`;
+}
+
+/**
+ * Whether a rollup entry is the check called `wanted` — matched against the
+ * check-run name (`review`) or its workflow name (`Claude PR Review`), so an
+ * operator can configure whichever of the two their own UI shows them.
+ *
+ * `wanted` must already be trimmed and lower-cased. A blank one matches nothing
+ * rather than the first entry: the callers below all read a configured name, and
+ * a typo that silently matched *something* is the dangerous direction.
+ *
+ * Known gap, inherited from #1003 and deliberately left as it was: a real legacy
+ * `StatusContext` carries its name in `context`, not `name`, so it is never
+ * matched here — only a CheckRun is. Both readers below still have a
+ * `StatusContext` branch, reachable only for an entry carrying both fields. It
+ * costs nothing today (GitHub Actions produces CheckRuns, and #1018's verdict is
+ * created through the Checks API) and widening it would change what the shipped
+ * #1003 reader matches, which is not this card's to change.
+ */
+function checkMatchesName(c: Record<string, unknown>, wanted: string): boolean {
+  if (!wanted) return false;
+  const name = typeof c.name === "string" ? c.name.toLowerCase() : "";
+  const workflow =
+    typeof c.workflowName === "string" ? c.workflowName.toLowerCase() : "";
+  return name === wanted || workflow === wanted;
+}
+
+/**
+ * Whether a rollup entry is the CHECK RUN called `skip` — by its own name only,
+ * never by workflow name. That restriction is the whole point (#1018).
+ *
+ * One workflow now publishes two checks with opposite meanings (`review` says a
+ * pass ran, `review-verdict` says what it concluded), and `checkMatchesName`
+ * above accepts the workflow name — a spelling `.github/CLAUDE.md` documents.
+ * So an operator on `checkName: "Claude PR Review"` has BOTH entries matching
+ * the review reader, and a truncated review beside a neutral verdict read as
+ * `passed`: the failure was reported as a healthy review, with nothing on the
+ * board. Each reader therefore skips the other's check.
+ *
+ * Skipping by workflow name would be worse than not skipping: both entries
+ * carry the same workflow name, so it would erase the reader's own check too and
+ * hold every merge on `absent`.
+ */
+function isNamedCheck(
+  c: Record<string, unknown>,
+  skip: string | undefined,
+): boolean {
+  if (!skip) return false;
+  const wanted = skip.trim().toLowerCase();
+  if (!wanted) return false;
+  return typeof c.name === "string" && c.name.toLowerCase() === wanted;
+}
+
 /** Derive a single CI verdict from a `gh pr view --json statusCheckRollup` array.
  * Handles both CheckRun ({status, conclusion}) and legacy StatusContext ({state}).
- * Empty/non-array (no checks configured) → unknown (conservative: never auto-merge). */
-export function deriveCiStatus(rollup: unknown): PrCiStatus {
+ * Empty/non-array (no checks configured) → unknown (conservative: never auto-merge).
+ *
+ * `excludeChecks` names checks this verdict must NOT speak for (card #1018).
+ * The review checks are the only intended members: they are read separately by
+ * the two functions below, and folding them in here made the collapsed word lie
+ * about WHOSE failure it was. A red `review` check meant "the review ran out of
+ * turns" and a red `review-verdict` check means "the reviewer found something",
+ * yet both arrived at the merge gate as an indistinguishable `failure` — which
+ * stamped `CI checks failed` on the card and, with `ciRepair.enabled`, re-ran a
+ * CI that was never broken.
+ *
+ * Excluding is not the same as ignoring: every excluded state is answered by
+ * `deriveIndependentReviewState` / `deriveReviewVerdictState`, and both HOLD a
+ * merge on anything but a pass. The rollup being empty *after* exclusion still
+ * 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.
+ */
+export function deriveCiStatus(
+  rollup: unknown,
+  excludeChecks: string[] = [],
+): PrCiStatus {
   if (!Array.isArray(rollup) || rollup.length === 0) return "unknown";
+  const excluded = excludeChecks
+    .map((n) => n.trim().toLowerCase())
+    .filter(Boolean);
   let anyPending = false;
   for (const check of rollup) {
     if (typeof check !== "object" || check === null) continue;
     const c = check as Record<string, unknown>;
+    if (excluded.some((name) => checkMatchesName(c, name))) continue;
     if (typeof c.status === "string") {
       // CheckRun
       if (c.status.toUpperCase() !== "COMPLETED") {
@@ -171,14 +280,314 @@ export function deriveCiStatus(rollup: unknown): PrCiStatus {
   return anyPending ? "pending" : "success";
 }
 
+/**
+ * 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
+ * `{name: "review", conclusion: "SKIPPED"}` — and the collapsed verdict for that
+ * PR is `"success"`. The merge gate could not tell "reviewed and clean" from
+ * "nobody looked".
+ *
+ * `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
+ * shouting into a void — or the head moved and the rollup has not caught up yet.
+ * Both hold the merge; only the caller can say which deserves a request.
+ */
+export type IndependentReviewState =
+  | "passed"
+  | "failed"
+  | "pending"
+  | "skipped"
+  | "absent";
+
+/**
+ * Read one named check out of a `statusCheckRollup` array.
+ *
+ * `checkName` matches either the check-run name (`review`) or its workflow name
+ * (`Claude PR Review`), case-insensitively, so an operator can configure
+ * whichever of the two they can see in their own UI.
+ *
+ * Precedence when several runs share the name — a re-request makes this normal —
+ * is `passed > pending > failed > skipped`. A pass anywhere means someone
+ * 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.
+ */
+export function deriveIndependentReviewState(
+  rollup: unknown,
+  checkName: string,
+  /**
+   * The VERDICT check's name, skipped by check-run name (#1018). Required
+   * whenever a verdict check exists: `checkName` may legitimately be the
+   * workflow name, which both checks share, and without this a truncated
+   * review sitting beside a neutral verdict reads as `passed`.
+   */
+  skipCheckName?: string,
+): IndependentReviewState {
+  if (!Array.isArray(rollup)) return "absent";
+  const wanted = checkName.trim().toLowerCase();
+  if (!wanted) return "absent";
+
+  let sawPending = false;
+  let sawFailed = false;
+  let sawSkipped = false;
+
+  for (const check of rollup) {
+    if (typeof check !== "object" || check === null) continue;
+    const c = check as Record<string, unknown>;
+    if (isNamedCheck(c, skipCheckName)) continue;
+    if (!checkMatchesName(c, wanted)) continue;
+
+    // CheckRun. A run that has not COMPLETED is in flight whatever else it says.
+    if (typeof c.status === "string") {
+      if (c.status.toUpperCase() !== "COMPLETED") {
+        sawPending = true;
+        continue;
+      }
+      const conclusion =
+        typeof c.conclusion === "string" ? c.conclusion.toUpperCase() : "";
+      if (conclusion === "SKIPPED") {
+        sawSkipped = true;
+        continue;
+      }
+      // NEUTRAL counts as a pass for the same reason `deriveCiStatus` accepts
+      // it: the reviewer ran and declined to fail the PR. What matters here is
+      // that an independent pass happened, not what it concluded — which is
+      // this function's whole scope, and why `deriveReviewVerdictState` below
+      // exists to answer the other half (#1018).
+      if (conclusion === "SUCCESS" || conclusion === "NEUTRAL") return "passed";
+      sawFailed = true;
+      continue;
+    }
+
+    // Legacy StatusContext — no notion of "skipped".
+    if (typeof c.state === "string") {
+      const state = c.state.toUpperCase();
+      if (state === "SUCCESS") return "passed";
+      if (state === "PENDING") {
+        sawPending = true;
+        continue;
+      }
+      sawFailed = true;
+    }
+  }
+
+  if (sawPending) return "pending";
+  if (sawFailed) return "failed";
+  if (sawSkipped) return "skipped";
+  return "absent";
+}
+
+/**
+ * What the independent review CONCLUDED, as opposed to whether it ran (#1018).
+ *
+ * `deriveIndependentReviewState` above answers "did anyone outside this daemon
+ * read this head?", which is all #1003 claimed. It cannot answer "and did they
+ * object?", because a routine `claude-review.yml` pass posts its findings as PR
+ * comments and exits 0 — so a review that wrote `critical: …` on the PR arrived
+ * at the merge gate looking exactly like a clean one, and under sweep nobody
+ * read those comments before the merge.
+ *
+ * The verdict therefore needs its own signal, and the workflow now publishes one
+ * as a separate check run (`review-verdict`) whose conclusion carries the
+ * reviewer's own answer. Reading a *distinct* check rather than failing the
+ * review job is what keeps the two questions separable: the review check stays
+ * "it ran", so a truncated review and a review that found a bug remain
+ * different states on the board instead of collapsing into one red X.
+ *
+ * The five states and why each is what it is:
+ *  - `clean` — SUCCESS. The reviewer says nothing blocks the merge.
+ *  - `blocking` — FAILURE. It found something a person must resolve.
+ *  - `unknown` — NEUTRAL or SKIPPED. The run produced no verdict to read (it
+ *    truncated, or it never emitted the line). Held, not waved through: "no
+ *    answer" is not "no findings".
+ *  - `pending` — a run under this name is still going.
+ *  - `absent` — no such check on this head. The repo's workflow predates the
+ *    verdict, the head moved and the rollup has not caught up, or the API call
+ *    that publishes it failed (a fork PR gets a read-only token). Also held.
+ */
+export type ReviewVerdictState =
+  | "clean"
+  | "blocking"
+  | "unknown"
+  | "pending"
+  | "absent";
+
+/**
+ * Read the verdict check out of a `statusCheckRollup` array.
+ *
+ * Precedence when several runs share the name — a re-request makes this normal —
+ * is the INVERSE of `deriveIndependentReviewState`'s: `blocking > pending >
+ * unknown > clean`. That reader takes the most permissive answer because a
+ * single independent read satisfies it; this one takes the most restrictive,
+ * 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.
+ */
+export function deriveReviewVerdictState(
+  rollup: unknown,
+  checkName: string,
+  /**
+   * The REVIEW-RAN check's name, skipped by check-run name — the mirror of the
+   * argument on the reader above, so the two questions stay separable whichever
+   * of the two spellings an operator configured.
+   */
+  skipCheckName?: string,
+): ReviewVerdictState {
+  if (!Array.isArray(rollup)) return "absent";
+  const wanted = checkName.trim().toLowerCase();
+  if (!wanted) return "absent";
+
+  let sawPending = false;
+  let sawUnknown = false;
+  let sawClean = false;
+
+  for (const check of rollup) {
+    if (typeof check !== "object" || check === null) continue;
+    const c = check as Record<string, unknown>;
+    if (isNamedCheck(c, skipCheckName)) continue;
+    if (!checkMatchesName(c, wanted)) continue;
+
+    // CheckRun. A run that has not COMPLETED has no verdict yet.
+    if (typeof c.status === "string") {
+      if (c.status.toUpperCase() !== "COMPLETED") {
+        sawPending = true;
+        continue;
+      }
+      const conclusion =
+        typeof c.conclusion === "string" ? c.conclusion.toUpperCase() : "";
+      if (conclusion === "SUCCESS") {
+        sawClean = true;
+        continue;
+      }
+      // NEUTRAL is the workflow saying "I could not read a verdict", and
+      // SKIPPED is it declining to evaluate one. Neither is a pass here —
+      // unlike in the two readers above, where NEUTRAL means a reviewer ran and
+      // chose not to fail the PR.
+      if (conclusion === "NEUTRAL" || conclusion === "SKIPPED") {
+        sawUnknown = true;
+        continue;
+      }
+      return "blocking";
+    }
+
+    // Legacy StatusContext — a commit status has no neutral, so the only
+    // readings available are pass, in flight, and everything else.
+    if (typeof c.state === "string") {
+      const state = c.state.toUpperCase();
+      if (state === "SUCCESS") {
+        sawClean = true;
+        continue;
+      }
+      if (state === "PENDING") {
+        sawPending = true;
+        continue;
+      }
+      return "blocking";
+    }
+  }
+
+  if (sawPending) return "pending";
+  if (sawUnknown) return "unknown";
+  if (sawClean) return "clean";
+  return "absent";
+}
+
+/** The three answers `readPrChecks` derives from one rollup. */
+export interface PrCheckStates {
+  ciStatus: PrCiStatus;
+  independentReview: IndependentReviewState;
+  reviewVerdict: ReviewVerdictState;
+}
+
+/**
+ * Turn one `statusCheckRollup` into three orthogonal answers (#1018).
+ *
+ * Pure, and split out of `getPrStatus` deliberately: this wiring — which name
+ * goes to which reader, which names come out of the collapsed CI word, and which
+ * name each reader must skip — is where both of the review's majors lived, and a
+ * unit test on the readers alone could not reach it.
+ *
+ * The three do not overlap: `ciStatus` speaks for the build/test checks,
+ * `independentReview` for whether a review ran, and `reviewVerdict` for what it
+ * said. **Every NAMED check is excluded from `ciStatus`**, so the merge gate can
+ * never stamp `CI checks failed` for something a review gate already owns — and
+ * each reader skips the other's check by run name, so one workflow publishing
+ * both cannot make either answer for the other.
+ *
+ * Naming a check is all-or-nothing per caller: omit `independentReviewCheck` and
+ * the review's state is not reported AND its failures land back in `ciStatus` —
+ * exactly the pre-#1003 behaviour an operator with `independentReview.enabled:
+ * false` asked for. The caller therefore names the verdict check whenever the
+ * review gate is on, whether or not it GATES on the verdict, because the
+ * alternative is a check this card introduced becoming a new red build for
+ * someone who opted out of reading it.
+ */
+export function readPrChecks(
+  rollup: unknown,
+  checks: {
+    independentReviewCheck?: string;
+    reviewVerdictCheck?: string;
+  } = {},
+): PrCheckStates {
+  const { independentReviewCheck, reviewVerdictCheck } = checks;
+  return {
+    ciStatus: deriveCiStatus(
+      rollup,
+      [independentReviewCheck, reviewVerdictCheck].filter(
+        (n): n is string => typeof n === "string",
+      ),
+    ),
+    independentReview: independentReviewCheck
+      ? deriveIndependentReviewState(
+          rollup,
+          independentReviewCheck,
+          reviewVerdictCheck,
+        )
+      : "absent",
+    reviewVerdict: reviewVerdictCheck
+      ? deriveReviewVerdictState(
+          rollup,
+          reviewVerdictCheck,
+          independentReviewCheck,
+        )
+      : "absent",
+  };
+}
+
+/**
+ * One `gh pr view` read, three orthogonal answers about the same head.
+ * See {@link readPrChecks} for what each one speaks for and what it excludes.
+ */
 export async function getPrStatus(
   prUrl: string,
   cwd: string,
   provider: GitProvider,
-): Promise<{ ciStatus: PrCiStatus; headSha: string | null }> {
-  if (provider !== "github" || !isValidPrUrl(prUrl)) {
-    return { ciStatus: "unknown", headSha: null };
-  }
+  /**
+   * Check to read the independent-review state from. Omitted → not reported,
+   * and its result stays inside `ciStatus`.
+   */
+  independentReviewCheck?: string,
+  /** Check to read the review VERDICT from (#1018). Same all-or-nothing rule. */
+  reviewVerdictCheck?: string,
+): Promise<{
+  ciStatus: PrCiStatus;
+  headSha: string | null;
+  independentReview: IndependentReviewState;
+  reviewVerdict: ReviewVerdictState;
+}> {
+  const unreadable = {
+    ciStatus: "unknown",
+    headSha: null,
+    independentReview: "absent",
+    reviewVerdict: "absent",
+  } as const;
+  if (provider !== "github" || !isValidPrUrl(prUrl)) return { ...unreadable };
   try {
     const { stdout } = await execFileAsync()(
       "gh",
@@ -191,10 +600,54 @@ export async function getPrStatus(
     };
     const headSha =
       typeof parsed.headRefOid === "string" ? parsed.headRefOid : null;
-    return { ciStatus: deriveCiStatus(parsed.statusCheckRollup), headSha };
+    return {
+      ...readPrChecks(parsed.statusCheckRollup, {
+        independentReviewCheck,
+        reviewVerdictCheck,
+      }),
+      headSha,
+    };
+  } catch {
+    return { ...unreadable };
+  }
+}
+
+/**
+ * Ask CI for an independent review by (re-)applying its request label.
+ *
+ * The remove-then-add is not defensive coding, it is the API: GitHub emits
+ * `labeled` only on an absent→present transition, so an already-labelled PR
+ * needs the label taken off first or the workflow never fires. The remove is
+ * expected to fail when the label is not there, and that failure is discarded.
+ *
+ * Callers must rate-limit themselves — every successful call bills a full review
+ * pass. `extractCiReviewRequestedSha` / `upsertCiReviewRequestedSha` above are
+ * the intended ledger.
+ */
+export async function requestIndependentReview(
+  prUrl: string,
+  cwd: string,
+  provider: GitProvider,
+  label: string,
+): Promise<void> {
+  if (provider !== "github") {
+    throw new Error(`independent review request unsupported for "${provider}"`);
+  }
+  const opts = { cwd, encoding: "utf-8" as const, timeout: 30_000 };
+  try {
+    await execFileAsync()(
+      "gh",
+      ["pr", "edit", prUrl, "--remove-label", label],
+      opts,
+    );
   } catch {
-    return { ciStatus: "unknown", headSha: null };
+    // Not present, so nothing to clear. The add below is the operative half.
   }
+  await execFileAsync()(
+    "gh",
+    ["pr", "edit", prUrl, "--add-label", label],
+    opts,
+  );
 }
 
 export async function mergePullRequest(

package/src/index.ts

@@ -13,6 +13,7 @@
 export const MOTOR_NAME = "harmony-harness";
 
 export * from "./artifact-judge.js";
+export * from "./ci-failure.js";
 export * from "./command-metric.js";
 export * from "./confine-to-repo.js";
 export * from "./error-classifier.js";
@@ -30,6 +31,7 @@ export * from "./oracle-collector.js";
 export * from "./pm.js";
 export * from "./process-group.js";
 export * from "./project-type.js";
+export * from "./repair-sandbox.js";
 export * from "./revert-guard.js";
 export * from "./review-types.js";
 export * from "./run-sizing.js";

package/src/model-tier.test.ts

@@ -14,10 +14,9 @@ const claude: ModelTierConfig = {
   tiers: { simple: "haiku", advanced: "sonnet", research: "opus" },
 };
 
-function card(p: Partial<Card>): Card {
+function card(p: Partial<Card> & Record<string, unknown>): Card {
   return {
     priority: "medium",
-    model_tier: null,
     model_override: null,
     ...p,
   } as Card;
@@ -120,12 +119,18 @@ describe("chooseImplementModel", () => {
     ).toEqual({ model: "claude-opus-4-8", escalated: true, source: "policy" });
   });
 
-  it("ignores card.model_tier entirely", () => {
-    // The column still exists and still holds stale values written by the
-    // retired create-time classifier. Nothing may read it.
+  it("ignores a stale classifier tier still riding on the card object", () => {
+    // The columns are dropped, but a cached board row — TanStack Query on web,
+    // the persisted zustand store on mobile — can still carry the retired keys
+    // for as long as that cache lives. `model_override` is the ONLY card-level
+    // model control; anything else on the row must change nothing.
     const r = chooseImplementModel(
       claude,
-      card({ model_tier: "research" }),
+      card({
+        model_tier: "research",
+        complexity_score: 9,
+        intent: "implement",
+      }),
       1,
       undefined,
     );

package/src/model-tier.ts

@@ -74,13 +74,13 @@ export interface RunSizing {
  *   2. `sized.tier` — the pickup preflight. On a retry (attempts >=
  *      escalateAfterAttempts) the tier bumps one level before resolving.
  *
- *      This replaces the retired `card.model_tier`, which a create-time
- *      classifier wrote by guessing engineering effort from a title composed
+ *      This replaces the retired create-time classifier, which wrote a tier
+ *      onto the card by guessing engineering effort from a title composed
  *      before anyone had looked at the code. The preflight runs at pickup with
  *      the repo readable, so the answer is measured rather than guessed — and
  *      it is run-scoped, so a stale value can never outlive the run it was for.
- *      `card.model_tier` is deliberately NOT read here; the column survives
- *      only so old rows stay readable until a follow-up drops it.
+ *      The card column that held that guess has been dropped, so there is no
+ *      card-level tier left to read: `model_override` is the only one.
  *   3. Global policy fallback — escalate on high/urgent priority or on a retry.
  *      This is also where EVERY preflight failure lands (spawn error, timeout,
  *      malformed output, or an operator who disabled it), so a broken preflight