pr-shepherd 0.32.1 → 0.32.2

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.32.1",
+  "version": "0.32.2",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/checks/classify.mjs

@@ -7,8 +7,14 @@
  *      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.
  */
 import { loadConfig } from "../config/load.mjs";
+import { buildSupersededIndices } from "./superseded.mjs";
 import picomatch from "picomatch";
 /**
  * Classify a list of raw check runs into shepherd categories.
@@ -22,9 +28,19 @@ export function classifyChecks(checks) {
     const isIgnored = buildMatcher(config.ignoreChecks ?? []);
     const isProtected = buildMatcher(config.actions.neverCancelRuns ?? []);
     const protectedRunIds = buildProtectedRunIds(checks, isProtected);
-    return checks.map((c) => isIgnored(c.name) && !isProtectedCheck(c, protectedRunIds)
-        ? { ...c, category: "ignored" }
-        : classify(c, relevantEvents));
+    const supersededIndices = buildSupersededIndices(checks);
+    return checks.map((c, index) => {
+        if (isIgnored(c.name) && !isProtectedCheck(c, protectedRunIds)) {
+            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.
+        if (classified.category === "failing" && supersededIndices.has(index)) {
+            return { ...classified, category: "superseded" };
+        }
+        return classified;
+    });
 }
 function buildMatcher(patterns) {
     if (patterns.length === 0)
@@ -74,7 +90,10 @@ function classify(check, relevantEvents) {
 }
 /** Compute a high-level CI verdict from a list of classified checks. */
 export function getCiVerdict(classified) {
-    const relevant = classified.filter((c) => c.category !== "filtered" && c.category !== "skipped" && c.category !== "ignored");
+    const relevant = classified.filter((c) => c.category !== "filtered" &&
+        c.category !== "skipped" &&
+        c.category !== "ignored" &&
+        c.category !== "superseded");
     const anyInProgress = relevant.some((c) => c.category === "in_progress");
     const anyFailing = relevant.some((c) => c.category === "failing");
     // When there are no relevant checks (e.g. docs-only PR where all checks are filtered/skipped),
@@ -83,5 +102,14 @@ export function getCiVerdict(classified) {
     const hasChecks = relevant.length > 0;
     const filteredNames = classified.filter((c) => c.category === "filtered").map((c) => c.name);
     const ignoredNames = Array.from(new Set(classified.filter((c) => c.category === "ignored").map((c) => c.name)));
-    return { allPassed, hasChecks, anyInProgress, anyFailing, filteredNames, ignoredNames };
+    const supersededNames = Array.from(new Set(classified.filter((c) => c.category === "superseded").map((c) => c.name)));
+    return {
+        allPassed,
+        hasChecks,
+        anyInProgress,
+        anyFailing,
+        filteredNames,
+        ignoredNames,
+        supersededNames,
+    };
 }

package/bin/checks/superseded.mjs

@@ -0,0 +1,59 @@
+/**
+ * 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`. */
+function workflowKeyOf(check) {
+    return check.workflowId ?? check.workflowName;
+}
+/**
+ * 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".
+ */
+export function buildSupersededIndices(checks) {
+    const runIdByIndex = new Map();
+    const maxRunIdByWorkflow = new Map();
+    checks.forEach((check, index) => {
+        const workflowKey = workflowKeyOf(check);
+        if (workflowKey === undefined || check.runId === null)
+            return;
+        const runIdNum = Number(check.runId);
+        if (!Number.isFinite(runIdNum))
+            return;
+        runIdByIndex.set(index, runIdNum);
+        const currentMax = maxRunIdByWorkflow.get(workflowKey);
+        if (currentMax === undefined || runIdNum > currentMax) {
+            maxRunIdByWorkflow.set(workflowKey, runIdNum);
+        }
+    });
+    const superseded = new Set();
+    checks.forEach((check, index) => {
+        if (check.conclusion !== "CANCELLED")
+            return;
+        const runIdNum = runIdByIndex.get(index);
+        if (runIdNum === 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) {
+            superseded.add(index);
+        }
+    });
+    return superseded;
+}

package/bin/cli/iterate-formatter.mjs

@@ -58,7 +58,7 @@ export function formatIterateResult(result, opts) {
         else if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
             verboseBranch = ` · **branch** conflicts with \`origin/${result.baseBranch}\``;
         }
-        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}`;
+        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress, ${result.summary.superseded} superseded · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}`;
     }
     else {
         const counts = [`${result.summary.passing} passing`];
@@ -68,6 +68,8 @@ export function formatIterateResult(result, opts) {
             counts.push(`${result.summary.filtered} filtered`);
         if (result.summary.inProgress > 0)
             counts.push(`${result.summary.inProgress} inProgress`);
+        if (result.summary.superseded > 0)
+            counts.push(`${result.summary.superseded} superseded`);
         const segs = [`**summary** ${counts.join(", ")}`];
         if (result.status === "READY" && result.remainingSeconds > 0) {
             segs.push(`**remainingSeconds** ${result.remainingSeconds}`);
@@ -116,6 +118,10 @@ export function formatIterateResult(result, opts) {
         const names = result.ignoredNames.map((n) => "`" + n + "`").join(", ");
         headerLines.push(`**ignored** ${names}`);
     }
+    if (result.supersededNames && result.supersededNames.length > 0) {
+        const names = result.supersededNames.map((n) => "`" + n + "`").join(", ");
+        headerLines.push(`**superseded** ${names}`);
+    }
     const activityLine = formatActivityLine(result);
     if (activityLine)
         headerLines.push(activityLine);
@@ -141,6 +147,10 @@ export function formatIterateResult(result, opts) {
                 const ignoredStr = result.ignoredNames.map((n) => "`" + n + "`").join(", ");
                 cancelHeaderLines.push(`**ignored** ${ignoredStr}`);
             }
+            if (result.supersededNames && result.supersededNames.length > 0) {
+                const supersededStr = result.supersededNames.map((n) => "`" + n + "`").join(", ");
+                cancelHeaderLines.push(`**superseded** ${supersededStr}`);
+            }
             if (activityLine)
                 cancelHeaderLines.push(activityLine);
             return joinSections([

package/bin/cli/iterate-lean.mjs

@@ -33,6 +33,7 @@ export function projectIterateLean(result, opts) {
             ...(result.summary.skipped > 0 && { skipped: result.summary.skipped }),
             ...(result.summary.filtered > 0 && { filtered: result.summary.filtered }),
             ...(result.summary.inProgress > 0 && { inProgress: result.summary.inProgress }),
+            ...(result.summary.superseded > 0 && { superseded: result.summary.superseded }),
         },
         ...(result.status === "READY" &&
             result.remainingSeconds > 0 && {
@@ -58,6 +59,9 @@ export function projectIterateLean(result, opts) {
         ...((result.ignoredNames?.length ?? 0) > 0 && {
             ignoredNames: result.ignoredNames,
         }),
+        ...((result.supersededNames?.length ?? 0) > 0 && {
+            supersededNames: result.supersededNames,
+        }),
     };
     switch (result.action) {
         case "wait":

package/bin/commands/check.mjs

@@ -127,6 +127,7 @@ export async function runCheck(opts) {
             filteredNames: verdict.filteredNames,
             blockedByFilteredCheck,
             ...(verdict.ignoredNames.length > 0 && { ignoredNames: verdict.ignoredNames }),
+            ...(verdict.supersededNames.length > 0 && { supersededNames: verdict.supersededNames }),
         },
         threads: {
             actionable: threadVisibility.activeThreads,

package/bin/commands/iterate/check-instructions.mjs

@@ -21,7 +21,7 @@ export function buildFailingCheckInstructions(checks) {
         parts.push("read any included log excerpt first; fetch the full log with `gh run view <runId> --log-failed` when the excerpt is insufficient; decide whether to rerun with `gh run rerun <runId> --failed` for transient infrastructure failures (network timeout, OOM kill, runner crash), or apply a code fix for real test/build failures; if GitHub omits workflow-evaluation details from API/log output, open the run URL in the GitHub UI");
     }
     if (hasCancelled) {
-        parts.push("for `[conclusion: CANCELLED]` entries: rerun with `gh run rerun <runId>` if the cancellation looks unintended (not superseded by a newer push or concurrency-group eviction); otherwise treat as resolved — do NOT confuse with IDs under `## Cancelled runs`");
+        parts.push("for `[conclusion: CANCELLED]` entries: these are not concurrency-superseded (superseded CANCELLED checks are excluded from this section and reported under `**superseded**` instead) — rerun with `gh run rerun <runId>` unless you are already pushing new commits this tick for other reasons, in which case the fresh run naturally supersedes it; do not silently treat a required CANCELLED check as resolved — do NOT confuse with IDs under `## Cancelled runs`");
     }
     if (hasStartupFailure) {
         parts.push("for `[conclusion: STARTUP_FAILURE]` entries: inspect with `gh run view <runId>` and rerun with `gh run rerun <runId>` if the workflow should be retried");

package/bin/commands/iterate/helpers.mjs

@@ -9,6 +9,43 @@ export function buildSummary(report) {
         skipped: report.checks.skipped.length,
         filtered: report.checks.filtered.length,
         inProgress: report.checks.inProgress.length,
+        superseded: report.checks.supersededNames?.length ?? 0,
+    };
+}
+/** Non-blocking check-name lists (ignored/superseded), omitted from the result when empty. */
+export function buildSuppressedCheckFields(report) {
+    return {
+        ...(report.checks.ignoredNames?.length ? { ignoredNames: report.checks.ignoredNames } : {}),
+        ...(report.checks.supersededNames?.length
+            ? { supersededNames: report.checks.supersededNames }
+            : {}),
+    };
+}
+/** Build the `cancel` result for a merged/closed PR — caller has already updated ready-delay/stall state. */
+export function buildTerminalCancelResult(report) {
+    const state = report.mergeStatus.state;
+    return {
+        pr: report.pr,
+        repo: report.repo,
+        status: report.status,
+        mergeStateStatus: report.mergeStatus.mergeStateStatus,
+        mergeStatus: report.mergeStatus.status,
+        reviewDecision: report.mergeStatus.reviewDecision,
+        blockingBotReviewInProgress: report.mergeStatus.blockingBotReviewInProgress,
+        isDraft: report.mergeStatus.isDraft,
+        shouldCancel: true,
+        remainingSeconds: 0,
+        state,
+        summary: buildSummary(report),
+        baseBranch: report.baseBranch,
+        branchProtection: report.branchProtection,
+        checks: buildRelevantChecks(report),
+        inProgressChecks: buildActiveChecks(report),
+        ...buildSuppressedCheckFields(report),
+        activity: report.activity,
+        action: "cancel",
+        reason: state === "MERGED" ? "merged" : "closed",
+        log: `CANCEL: PR #${report.pr} is ${state.toLowerCase()} — stopping`,
     };
 }
 /** Build completed, non-skipped checks relevant to PR readiness. */

package/bin/commands/iterate/index.mjs

@@ -4,7 +4,7 @@ import { getCurrentPrNumber } from "../../github/client.mjs";
 import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
-import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, } from "./helpers.mjs";
+import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, buildSuppressedCheckFields, buildTerminalCancelResult, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
@@ -31,32 +31,9 @@ export async function runIterate(opts) {
     }
     const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
     if (report.mergeStatus.state !== "OPEN") {
-        const state = report.mergeStatus.state.toLowerCase();
         await updateReadyDelay(report.pr, false, readyDelaySeconds, repoOwner, repoName);
         await clearStallState(stallKey);
-        return {
-            pr: report.pr,
-            repo: report.repo,
-            status: report.status,
-            mergeStateStatus: report.mergeStatus.mergeStateStatus,
-            mergeStatus: report.mergeStatus.status,
-            reviewDecision: report.mergeStatus.reviewDecision,
-            blockingBotReviewInProgress: report.mergeStatus.blockingBotReviewInProgress,
-            isDraft: report.mergeStatus.isDraft,
-            shouldCancel: true,
-            remainingSeconds: 0,
-            state: report.mergeStatus.state,
-            summary: buildSummary(report),
-            baseBranch: report.baseBranch,
-            branchProtection: report.branchProtection,
-            checks: buildRelevantChecks(report),
-            inProgressChecks: buildActiveChecks(report),
-            ...(report.checks.ignoredNames?.length ? { ignoredNames: report.checks.ignoredNames } : {}),
-            activity: report.activity,
-            action: "cancel",
-            reason: report.mergeStatus.state === "MERGED" ? "merged" : "closed",
-            log: `CANCEL: PR #${report.pr} is ${state} — stopping`,
-        };
+        return buildTerminalCancelResult(report);
     }
     const { minimizeIds: reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = classifyReviewSummaries({
         firstLook: report.firstLookSummaries,
@@ -95,7 +72,7 @@ export async function runIterate(opts) {
         branchProtection: report.branchProtection,
         checks: buildRelevantChecks(report),
         inProgressChecks: buildActiveChecks(report),
-        ...(report.checks.ignoredNames?.length ? { ignoredNames: report.checks.ignoredNames } : {}),
+        ...buildSuppressedCheckFields(report),
         activity: report.activity,
     };
     if (readyState.shouldCancel) {

package/bin/github/batch-parser-helpers.mjs

@@ -6,13 +6,48 @@ export function parseCreatedAt(iso) {
     const ms = new Date(iso).getTime();
     return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
 }
-export function extractRunId(url) {
+function extractRunId(url) {
     if (!url)
         return null;
     const m = /\/runs\/(\d+)/.exec(url);
     return m ? (m[1] ?? null) : null;
 }
-export function extractCheckRunSummary(title, summary) {
+/** Stringify a GraphQL Workflow.databaseId, when present, for use as a check-grouping key. */
+function resolveWorkflowId(databaseId) {
+    return databaseId !== null && databaseId !== undefined ? String(databaseId) : undefined;
+}
+/** Map a GraphQL CheckRun context node to a CheckRun. */
+export function mapCheckRunNode(node) {
+    const event = node.checkSuite?.workflowRun?.event ?? null;
+    const workflowName = node.checkSuite?.workflowRun?.workflow?.name?.trim() || undefined;
+    const workflowId = resolveWorkflowId(node.checkSuite?.workflowRun?.workflow?.databaseId);
+    const runId = extractRunId(node.detailsUrl);
+    const summary = extractCheckRunSummary(node.title, node.summary);
+    const rawCreatedAt = node.checkSuite?.workflowRun?.createdAt ?? node.checkSuite?.createdAt;
+    const rawUpdatedAt = node.checkSuite?.workflowRun?.updatedAt ?? node.checkSuite?.updatedAt;
+    const createdAtUnix = rawCreatedAt ? parseCreatedAt(rawCreatedAt) : undefined;
+    const startedAtUnix = node.startedAt ? parseCreatedAt(node.startedAt) : undefined;
+    const completedAtUnix = node.completedAt ? parseCreatedAt(node.completedAt) : undefined;
+    const updatedAtUnix = rawUpdatedAt ? parseCreatedAt(rawUpdatedAt) : undefined;
+    return {
+        id: node.id,
+        name: node.name,
+        status: node.status,
+        conclusion: node.conclusion,
+        source: "check_run",
+        detailsUrl: node.detailsUrl ?? "",
+        event,
+        runId,
+        ...(workflowName !== undefined && { workflowName }),
+        ...(workflowId !== undefined && { workflowId }),
+        ...(createdAtUnix !== undefined && { createdAtUnix }),
+        ...(startedAtUnix !== undefined && { startedAtUnix }),
+        ...(completedAtUnix !== undefined && { completedAtUnix }),
+        ...(updatedAtUnix !== undefined && { updatedAtUnix }),
+        ...(summary !== undefined && { summary }),
+    };
+}
+function extractCheckRunSummary(title, summary) {
     const t = title?.trim();
     if (t)
         return t;

package/bin/github/batch-parsers.mjs

@@ -1,4 +1,4 @@
-import { mapAuthorType, parseCreatedAt, extractRunId, extractCheckRunSummary, mapStatusContextState, latestApprovedLogins, isReviewStale, } from "./batch-parser-helpers.mjs";
+import { mapAuthorType, parseCreatedAt, mapStatusContextState, latestApprovedLogins, isReviewStale, mapCheckRunNode, } from "./batch-parser-helpers.mjs";
 import { buildPrActivitySummary } from "./activity.mjs";
 import { parseBranchProtection } from "./branch-protection.mjs";
 function parseReviewNode(r) {
@@ -81,34 +81,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         .map((r) => parseReviewNode(r));
     const checks = rawCheckNodes.flatMap((node) => {
         if (node.__typename === "CheckRun") {
-            const event = node.checkSuite?.workflowRun?.event ?? null;
-            const workflowName = node.checkSuite?.workflowRun?.workflow?.name?.trim() || undefined;
-            const runId = extractRunId(node.detailsUrl);
-            const summary = extractCheckRunSummary(node.title, node.summary);
-            const rawCreatedAt = node.checkSuite?.workflowRun?.createdAt ?? node.checkSuite?.createdAt;
-            const rawUpdatedAt = node.checkSuite?.workflowRun?.updatedAt ?? node.checkSuite?.updatedAt;
-            const createdAtUnix = rawCreatedAt ? parseCreatedAt(rawCreatedAt) : undefined;
-            const startedAtUnix = node.startedAt ? parseCreatedAt(node.startedAt) : undefined;
-            const completedAtUnix = node.completedAt ? parseCreatedAt(node.completedAt) : undefined;
-            const updatedAtUnix = rawUpdatedAt ? parseCreatedAt(rawUpdatedAt) : undefined;
-            return [
-                {
-                    id: node.id,
-                    name: node.name,
-                    status: node.status,
-                    conclusion: node.conclusion,
-                    source: "check_run",
-                    detailsUrl: node.detailsUrl ?? "",
-                    event,
-                    runId,
-                    ...(workflowName !== undefined && { workflowName }),
-                    ...(createdAtUnix !== undefined && { createdAtUnix }),
-                    ...(startedAtUnix !== undefined && { startedAtUnix }),
-                    ...(completedAtUnix !== undefined && { completedAtUnix }),
-                    ...(updatedAtUnix !== undefined && { updatedAtUnix }),
-                    ...(summary !== undefined && { summary }),
-                },
-            ];
+            return [mapCheckRunNode(node)];
         }
         if (node.__typename === "StatusContext") {
             const { status, conclusion } = mapStatusContextState(node.state);

package/bin/github/gql/batch-pr.gql

@@ -205,6 +205,7 @@ query BatchPr(
                         updatedAt
                         workflow {
                           name
+                          databaseId
                         }
                       }
                     }

package/bin/types/check-classification.mjs

@@ -0,0 +1,2 @@
+// Check-run classification types, split out of github.mts to stay under the file-length cap.
+export {};

package/bin/types/github.mjs

@@ -1,2 +1,4 @@
 // GitHub primitives, check runs, review threads, and batch PR data types.
+// Check classification types (CheckCategory/ClassifiedCheck/TriagedCheck) live in
+// check-classification.mts to stay under the file-length cap.
 export {};

package/bin/types.mjs

@@ -1,5 +1,6 @@
 /** Shared type definitions for the shepherd CLI. */
 export * from "./types/github.mjs";
+export * from "./types/check-classification.mjs";
 export * from "./types/activity.mjs";
 export * from "./types/review-thread.mjs";
 export * from "./types/agent-thread.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.32.1",
+  "version": "0.32.2",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",

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

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