pr-shepherd 0.56.2 → 0.56.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.56.2",
+  "version": "0.56.3",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/checks/classify.d.mts

@@ -7,11 +7,10 @@
  *      to PR readiness.
  *   2. Drop checks with `conclusion == SKIPPED` or `conclusion == NEUTRAL` from the
  *      pass/fail tally. Report them as "skipped" for transparency but don't block on them.
- *   3. Reclassify `CANCELLED` checks as "superseded" (non-blocking) when a newer run of
- *      the same workflow exists on the same commit — this is GitHub's concurrency-group
- *      eviction behavior, not a real failure. GitHub branch protection itself resolves
- *      required status checks by latest-run-per-name and merges past these; mirroring
- *      that here keeps shepherd's verdict aligned with what GitHub will actually allow.
+ *   3. Reclassify `CANCELLED` checks as "superseded" (non-blocking) when a newer
+ *      run of the same workflow exists on the same commit and event, or when an
+ *      exact matching check from a lower-ID run started and succeeded later.
+ *      GitHub can start jobs out of workflow-run creation order.
  */
 import type { CheckRun, ClassifiedCheck } from "../types.mts";
 /**
@@ -36,7 +35,7 @@ export interface CiVerdict {
     filteredNames: string[];
     /** Names of checks suppressed by the user's ignoreChecks config. */
     ignoredNames: string[];
-    /** Names of CANCELLED checks superseded by a newer run of the same workflow (concurrency-group eviction). */
+    /** Names of CANCELLED checks covered by another run of the same workflow and event. */
     supersededNames: string[];
 }
 /** Compute a high-level CI verdict from a list of classified checks. */

package/bin/checks/classify.mjs

@@ -7,11 +7,10 @@
  *      to PR readiness.
  *   2. Drop checks with `conclusion == SKIPPED` or `conclusion == NEUTRAL` from the
  *      pass/fail tally. Report them as "skipped" for transparency but don't block on them.
- *   3. Reclassify `CANCELLED` checks as "superseded" (non-blocking) when a newer run of
- *      the same workflow exists on the same commit — this is GitHub's concurrency-group
- *      eviction behavior, not a real failure. GitHub branch protection itself resolves
- *      required status checks by latest-run-per-name and merges past these; mirroring
- *      that here keeps shepherd's verdict aligned with what GitHub will actually allow.
+ *   3. Reclassify `CANCELLED` checks as "superseded" (non-blocking) when a newer
+ *      run of the same workflow exists on the same commit and event, or when an
+ *      exact matching check from a lower-ID run started and succeeded later.
+ *      GitHub can start jobs out of workflow-run creation order.
  */
 import { loadConfig } from "../config/load.mjs";
 import { buildSupersededIndices } from "./superseded.mjs";
@@ -37,8 +36,7 @@ export function classifyChecks(checks, opts = {}) {
             return { ...c, category: "ignored" };
         }
         const classified = classify(c, relevantEvents);
-        // Only ever override a "failing" verdict (i.e. conclusion === CANCELLED, guaranteed by
-        // buildSupersededIndices below) — never touch filtered/skipped/passed classifications.
+        // Only override a failing CANCELLED check, never filtered/skipped/passed classifications.
         if (classified.category === "failing" && supersededIndices.has(index)) {
             return { ...classified, category: "superseded" };
         }

package/bin/checks/superseded.d.mts

@@ -1,21 +1,8 @@
-/**
- * Detects check runs that are `CANCELLED` because a newer run of the *same workflow*
- * superseded them on the same commit (concurrency-group eviction), rather than a genuine
- * cancellation. Split out of classify.mts to stay under the file-length cap.
- */
+/** Identify cancelled checks covered by another run on the same commit and event. */
 import type { CheckRun } from "../types.mts";
 /**
- * Grouping key is `workflowId ?? workflowName` — the numeric GitHub Actions workflow database
- * ID when available, falling back to the display name. Checks with neither a workflow identity
- * nor a numeric `runId` (status contexts, startup-failure synthetics) never participate: they
- * can neither be marked superseded nor count as evidence of a newer run.
- *
- * A check is superseded iff its own conclusion is `CANCELLED` and some other check sharing its
- * workflow key has a strictly greater `runId`. The newest run for a workflow is therefore never
- * superseded, even if it is itself cancelled — that case stays "failing" so the agent can decide
- * whether to rerun it.
- *
- * @returns Indices into `checks` (not object identities, since check-run objects are not
- *   deduplicated by reference elsewhere) that should be reclassified as "superseded".
+ * A later-created run supersedes an older cancellation as before. GitHub can start
+ * check jobs out of run-ID order, so a lower-ID run can also cover a cancellation
+ * when its matching successful job actually started and completed later.
  */
 export declare function buildSupersededIndices(checks: CheckRun[]): Set<number>;

package/bin/checks/superseded.mjs

@@ -1,59 +1,83 @@
-/**
- * Detects check runs that are `CANCELLED` because a newer run of the *same workflow*
- * superseded them on the same commit (concurrency-group eviction), rather than a genuine
- * cancellation. Split out of classify.mts to stay under the file-length cap.
- */
-/** Grouping key for a check's workflow: numeric `workflowId`, falling back to `workflowName`. */
+/** Identify cancelled checks covered by another run on the same commit and event. */
+/** Prefer the stable workflow ID; retain the name fallback for the older-run rule. */
 function workflowKeyOf(check) {
-    return check.workflowId ?? check.workflowName;
+    if (check.workflowId)
+        return `id:${check.workflowId}`;
+    return check.workflowName ? `name:${check.workflowName}` : undefined;
+}
+function groupKeyOf(check) {
+    const workflow = workflowKeyOf(check);
+    if (workflow === undefined)
+        return undefined;
+    return JSON.stringify([workflow, check.event, check.scope ?? null, check.commitOid ?? null]);
+}
+function numericRunId(check) {
+    if (check.runId === null || !/^[1-9]\d*$/.test(check.runId))
+        return undefined;
+    const id = Number(check.runId);
+    return Number.isSafeInteger(id) ? id : undefined;
+}
+function validTimes(check) {
+    const { startedAtUnix: start, completedAtUnix: completion } = check;
+    return (typeof start === "number" &&
+        Number.isFinite(start) &&
+        start > 0 &&
+        typeof completion === "number" &&
+        Number.isFinite(completion) &&
+        completion > 0 &&
+        completion >= start);
 }
 /**
- * Grouping key is `workflowId ?? workflowName` — the numeric GitHub Actions workflow database
- * ID when available, falling back to the display name. Checks with neither a workflow identity
- * nor a numeric `runId` (status contexts, startup-failure synthetics) never participate: they
- * can neither be marked superseded nor count as evidence of a newer run.
- *
- * A check is superseded iff its own conclusion is `CANCELLED` and some other check sharing its
- * workflow key has a strictly greater `runId`. The newest run for a workflow is therefore never
- * superseded, even if it is itself cancelled — that case stays "failing" so the agent can decide
- * whether to rerun it.
- *
- * @returns Indices into `checks` (not object identities, since check-run objects are not
- *   deduplicated by reference elsewhere) that should be reclassified as "superseded".
+ * A later-created run supersedes an older cancellation as before. GitHub can start
+ * check jobs out of run-ID order, so a lower-ID run can also cover a cancellation
+ * when its matching successful job actually started and completed later.
  */
 export function buildSupersededIndices(checks) {
-    const runIdByIndex = new Map();
-    const maxRunIdByWorkflow = new Map();
+    const maxRunIdByGroup = new Map();
+    const runIds = checks.map(numericRunId);
     checks.forEach((check, index) => {
-        const workflowKey = workflowKeyOf(check);
-        if (workflowKey === undefined || check.runId === null)
-            return;
-        const runIdNum = Number(check.runId);
-        if (!Number.isFinite(runIdNum))
+        const group = groupKeyOf(check);
+        const runId = runIds[index];
+        if (group === undefined || runId === undefined)
             return;
-        runIdByIndex.set(index, runIdNum);
-        const currentMax = maxRunIdByWorkflow.get(workflowKey);
-        if (currentMax === undefined || runIdNum > currentMax) {
-            maxRunIdByWorkflow.set(workflowKey, runIdNum);
-        }
+        const previous = maxRunIdByGroup.get(group);
+        if (previous === undefined || runId > previous)
+            maxRunIdByGroup.set(group, runId);
     });
     const superseded = new Set();
-    checks.forEach((check, index) => {
-        if (check.conclusion !== "CANCELLED")
+    checks.forEach((cancelled, index) => {
+        if (cancelled.conclusion !== "CANCELLED")
             return;
-        const runIdNum = runIdByIndex.get(index);
-        if (runIdNum === undefined)
+        const group = groupKeyOf(cancelled);
+        const runId = runIds[index];
+        if (group === undefined || runId === undefined)
             return;
-        // workflowKeyOf(check) is guaranteed defined here, with a corresponding entry in
-        // maxRunIdByWorkflow: runIdByIndex is only ever populated in the loop above alongside a
-        // maxRunIdByWorkflow entry for that same workflow key (at minimum, this check's own
-        // runIdNum) — the two maps are always updated together for a given index. A defensive
-        // undefined-check here would therefore guard a branch no input can ever exercise, which
-        // would silently fail this repo's 100%-coverage requirement instead of catching a real bug.
-        const maxRunId = maxRunIdByWorkflow.get(workflowKeyOf(check));
-        if (maxRunId > runIdNum) {
+        if (maxRunIdByGroup.get(group) > runId) {
             superseded.add(index);
+            return;
         }
+        if (cancelled.status !== "COMPLETED" ||
+            !cancelled.workflowId ||
+            cancelled.event === null ||
+            !validTimes(cancelled))
+            return;
+        const covered = checks.some((success, candidateIndex) => {
+            const candidateRunId = runIds[candidateIndex];
+            return (candidateRunId !== undefined &&
+                candidateRunId < runId &&
+                success.status === "COMPLETED" &&
+                success.conclusion === "SUCCESS" &&
+                success.workflowId === cancelled.workflowId &&
+                success.event === cancelled.event &&
+                success.scope === cancelled.scope &&
+                success.commitOid === cancelled.commitOid &&
+                success.name === cancelled.name &&
+                validTimes(success) &&
+                success.startedAtUnix > cancelled.startedAtUnix &&
+                success.completedAtUnix > cancelled.completedAtUnix);
+        });
+        if (covered)
+            superseded.add(index);
     });
     return superseded;
 }

package/bin/github/gql/poll-summary-check-contexts.gql

@@ -12,6 +12,8 @@ fragment PollSummaryCheckContexts on StatusCheckRollupContextConnection {
       status
       conclusion
       detailsUrl
+      startedAt
+      completedAt
       checkSuite {
         createdAt
         workflowRun {

package/bin/github/poll-summary-checks.mjs

@@ -1,10 +1,9 @@
 import { classifyChecks } from "../checks/classify.mjs";
+import { parseCreatedAt } from "./batch-parser-helpers.mjs";
 export function summarizePollSummaryChecks(raw) {
     const rollups = summaryRollups(raw);
     const counts = {};
-    for (const check of classifyChecks(checkRuns(rollups), {
-        additionalRelevantEvents: ["merge_group"],
-    })) {
+    for (const check of classifiedSummaryChecks(raw)) {
         const key = {
             passed: "passing",
             failing: "failing",
@@ -17,33 +16,36 @@ export function summarizePollSummaryChecks(raw) {
         counts[key] = (counts[key] ?? 0) + 1;
     }
     const summary = counts;
-    if (rollups.some((rollup) => rollup.contexts.pageInfo.hasPreviousPage)) {
+    if (rollups.some(({ rollup }) => rollup.contexts.pageInfo.hasPreviousPage)) {
         summary.incomplete = true;
     }
     return summary;
 }
 /** Names of failing checks in the loaded summary rollup. */
 export function failingSummaryCheckNames(raw) {
-    return classifyChecks(checkRuns(summaryRollups(raw)), {
-        additionalRelevantEvents: ["merge_group"],
-    })
+    return classifiedSummaryChecks(raw)
         .filter((check) => check.category === "failing")
         .map((check) => check.name);
 }
 function summaryRollups(raw) {
     return [
-        raw.commits.nodes[0]?.commit.statusCheckRollup,
-        raw.mergeQueueEntry?.headCommit?.statusCheckRollup,
-    ].filter((rollup) => rollup !== null && rollup !== undefined);
+        { rollup: raw.commits.nodes[0]?.commit.statusCheckRollup, scope: undefined },
+        {
+            rollup: raw.mergeQueueEntry?.headCommit?.statusCheckRollup,
+            scope: "merge_group",
+        },
+    ].flatMap(({ rollup, scope }) => (rollup ? [{ rollup, scope }] : []));
 }
-function checkRuns(rollups) {
-    return rollups.flatMap((rollup, rollupIndex) => rollup.contexts.nodes.map((context) => {
+function classifiedSummaryChecks(raw) {
+    // A successful check on the queue commit cannot cover a PR-head cancellation, or vice versa.
+    return summaryRollups(raw).flatMap(({ rollup, scope }) => classifyChecks(checkRuns(rollup, scope), scope === "merge_group" ? { additionalRelevantEvents: ["merge_group"] } : {}));
+}
+function checkRuns(rollup, scope) {
+    return rollup.contexts.nodes.map((context) => {
         if (context.__typename === "StatusContext") {
             return {
                 name: context.context,
-                status: context.state === "PENDING" || context.state === "EXPECTED"
-                    ? "IN_PROGRESS"
-                    : "COMPLETED",
+                status: context.state === "PENDING" || context.state === "EXPECTED" ? "IN_PROGRESS" : "COMPLETED",
                 conclusion: context.state === "SUCCESS"
                     ? "SUCCESS"
                     : context.state === "FAILURE" || context.state === "ERROR"
@@ -53,7 +55,7 @@ function checkRuns(rollups) {
                 detailsUrl: "",
                 event: null,
                 runId: null,
-                ...(rollupIndex === 1 && { scope: "merge_group" }),
+                ...(scope && { scope }),
             };
         }
         const run = context.checkSuite?.workflowRun;
@@ -70,7 +72,9 @@ function checkRuns(rollups) {
             ...(run?.workflow?.databaseId != null && {
                 workflowId: String(run.workflow.databaseId),
             }),
-            ...(rollupIndex === 1 && { scope: "merge_group" }),
+            ...(context.startedAt && { startedAtUnix: parseCreatedAt(context.startedAt) }),
+            ...(context.completedAt && { completedAtUnix: parseCreatedAt(context.completedAt) }),
+            ...(scope && { scope }),
         };
-    }));
+    });
 }

package/bin/github/poll-summary-raw.d.mts

@@ -26,6 +26,8 @@ type RawCheckContext = {
     status: string;
     conclusion: string | null;
     detailsUrl?: string;
+    startedAt?: string | null;
+    completedAt?: string | null;
     annotations?: {
         totalCount: number;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.56.2",
+  "version": "0.56.3",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -89,7 +89,7 @@
     "husky": "^9.1.7",
     "knip": "^6.14.1",
     "marked": "^18.0.11",
-    "oxfmt": "^0.68.0",
+    "oxfmt": "^0.70.0",
     "oxlint": "^1.60.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.56.2",
+  "version": "0.56.3",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.56.2", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.56.3", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.56.2", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.56.3", "pr-shepherd-mcp"]
   }
 }