pr-shepherd 0.32.1 → 0.32.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.32.1",
+  "version": "0.32.3",
   "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/duration-flag.mjs

@@ -1,8 +1,10 @@
 import { parseSecondsDurationParts } from "./exit-codes.mjs";
-export function validateSecondsDurationFlag(command, flag, value, presentAsSeparateArg) {
+export function validateSecondsDurationFlag(command, flag, value, presentAsSeparateArg, opts = {}) {
+    const bareUnit = opts.defaultUnit === "m" ? "minutes" : "seconds";
+    const example = opts.defaultUnit === "m" ? "15m" : "30s";
     if (value === null) {
         if (presentAsSeparateArg) {
-            process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} 30s)\n`);
+            process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} ${example})\n`);
             process.exitCode = 1;
             return null;
         }
@@ -10,34 +12,12 @@ export function validateSecondsDurationFlag(command, flag, value, presentAsSepar
     }
     const trimmed = value.trim();
     if (trimmed.startsWith("--")) {
-        process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} 30s)\n`);
+        process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} ${example})\n`);
         process.exitCode = 1;
         return null;
     }
-    if (!parseSecondsDurationParts(trimmed)) {
-        process.stderr.write(`${command}: invalid ${flag}: ${value}. Expected a duration like 30s, 4.5m, 1h, or bare seconds (e.g. 30).\n`);
-        process.exitCode = 1;
-        return null;
-    }
-    return trimmed;
-}
-export function validateDurationFlag(command, flag, value, presentAsSeparateArg) {
-    if (value === null) {
-        if (presentAsSeparateArg) {
-            process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} 15m)\n`);
-            process.exitCode = 1;
-            return null;
-        }
-        return undefined;
-    }
-    const trimmed = value.trim();
-    if (trimmed.startsWith("--")) {
-        process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} 15m)\n`);
-        process.exitCode = 1;
-        return null;
-    }
-    if (!/^\d+(?:m|min|minutes?|h|hours?)?$/.test(trimmed)) {
-        process.stderr.write(`${command}: invalid ${flag}: ${value}. Expected a duration like 5m, 2h, 10m, or 1h.\n`);
+    if (!parseSecondsDurationParts(trimmed, opts)) {
+        process.stderr.write(`${command}: invalid ${flag}: ${value}. Expected a duration like 30s, 4.5m, 1h, or a bare number (${bareUnit}).\n`);
         process.exitCode = 1;
         return null;
     }

package/bin/cli/exit-codes.mjs

@@ -1,4 +1,3 @@
-import { loadConfig } from "../config/load.mjs";
 const SECOND_DURATION_UNITS = new Set([
     "s",
     "sec",
@@ -12,17 +11,7 @@ const SECOND_DURATION_UNITS = new Set([
     "hour",
     "hours",
 ]);
-export function parseDurationToMinutes(s, defaultMinutes) {
-    const m = /^(\d+)(m|min|minutes?|h|hours?)?$/.exec(s.trim());
-    if (!m)
-        return defaultMinutes ?? loadConfig().watch.readyDelayMinutes;
-    const n = parseInt(m[1], 10);
-    const unit = m[2] ?? "m";
-    if (unit.startsWith("h"))
-        return n * 60;
-    return n;
-}
-export function parseSecondsDurationParts(s) {
+export function parseSecondsDurationParts(s, opts = {}) {
     const trimmed = s.trim();
     const match = /^(\d+(?:\.\d+)?)([a-z]+)?$/.exec(trimmed);
     if (!match)
@@ -31,16 +20,18 @@ export function parseSecondsDurationParts(s) {
     const explicitUnit = match[2];
     if (!amount || (amount.includes(".") && !explicitUnit))
         return null;
-    const unit = explicitUnit ?? "s";
+    const unit = explicitUnit ?? opts.defaultUnit ?? "s";
     if (!SECOND_DURATION_UNITS.has(unit))
         return null;
     const value = Number(amount);
-    if (!Number.isFinite(value) || value <= 0)
+    if (!Number.isFinite(value))
+        return null;
+    if (opts.allowZero ? value < 0 : value <= 0)
         return null;
     return { value, unit };
 }
-export function parseDurationToSeconds(s, defaultSeconds) {
-    const parsed = parseSecondsDurationParts(s);
+export function parseDurationToSeconds(s, defaultSeconds, opts = {}) {
+    const parsed = parseSecondsDurationParts(s, opts);
     if (!parsed)
         return defaultSeconds;
     if (parsed.unit.startsWith("h"))

package/bin/cli/handlers.mjs

@@ -94,7 +94,7 @@ export async function handleIterate(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const cfg = loadConfig();
     const flags = parseIterateFlags(extra, cfg);
-    if (flags.readyDelaySuffix === null)
+    if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
         return;
     const result = await runIterate({
         ...globalOpts,

package/bin/cli/help-command-pages.mjs

@@ -80,14 +80,16 @@ Usage:
   pr-shepherd iterate [PR] [iterate-flags]
 
 Iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
-  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
 
+Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).
+
 Actions:
   WAIT        No immediate code action; recheck later or use pr-shepherd poll.
   MARK_READY  Draft PR was marked ready for review.
@@ -110,21 +112,23 @@ Usage:
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
 
 Poll flags:
-  --interval <duration>          Sleep between WAIT ticks. Default: 60s.
-  --timeout <duration>           Maximum wall-clock wait. Default: 4.5m.
+  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.
+  --timeout <duration>           Maximum wall-clock wait. Bare number = seconds. Default: 4.5m.
   --quiet-status                 During WAIT polling, print only changed status snapshots.
   --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
 
 Forwarded iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
-  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields and detailed per-tick lines.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
 
-Durations accept seconds, minutes, or hours: 30s, 4.5m, 1h, or bare seconds.
+Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds
+for --interval/--timeout, minutes for --ready-delay/--stall-timeout); decimals are allowed only with
+an explicit unit (4.5m).
 Each WAIT tick writes a single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
 With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.
 

package/bin/cli/help-top-page.mjs

@@ -36,14 +36,14 @@ Common flags:
   --help, -h           Print help and exit before any GitHub, git, config, or log I/O.
 
 Iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
-  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
 
 Poll flags:
-  --interval <duration>          Delay between WAIT ticks. Default: 60s.
-  --timeout <duration>           Poll wall-clock cap. Default: 4.5m.
+  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.
+  --timeout <duration>           Poll wall-clock cap. Bare number = seconds. Default: 4.5m.
   --quiet-status                 During WAIT polling, print only changed status snapshots.
   --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
 
@@ -60,6 +60,6 @@ Exit codes for iterate and poll:
   2  CANCEL
   3  ESCALATE
 
-Duration examples: 30s, 4.5m, 1h, or bare seconds.
+Duration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).
 
 Run 'pr-shepherd <command> --help' for command-specific details.`;

package/bin/cli/iterate-flags.mjs

@@ -1,19 +1,22 @@
 import { getFlag, hasFlag } from "./args.mjs";
-import { parseDurationToMinutes } from "./exit-codes.mjs";
-import { validateDurationFlag } from "./duration-flag.mjs";
+import { parseDurationToSeconds } from "./exit-codes.mjs";
+import { validateSecondsDurationFlag } from "./duration-flag.mjs";
+// --ready-delay and --stall-timeout are minute-family flags: a bare number means minutes, and 0 is a
+// valid value (it disables the ready-delay settle window / stall-timeout escalation, respectively).
+const MINUTE_FLAG_OPTS = { defaultUnit: "m", allowZero: true };
 export function parseIterateFlags(extra, cfg) {
     const readyDelayStr = getFlag(extra, "--ready-delay");
-    const readyDelaySuffix = validateDurationFlag("pr-shepherd", "--ready-delay", readyDelayStr, hasFlag(extra, "--ready-delay"));
-    const readyDelaySeconds = parseDurationToMinutes(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes) * 60;
+    const readyDelaySuffix = validateSecondsDurationFlag("pr-shepherd", "--ready-delay", readyDelayStr, hasFlag(extra, "--ready-delay"), MINUTE_FLAG_OPTS);
+    const readyDelaySeconds = parseDurationToSeconds(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes * 60, MINUTE_FLAG_OPTS);
     const noAutoMarkReady = hasFlag(extra, "--no-auto-mark-ready");
     const noAutoCancelActionable = hasFlag(extra, "--no-auto-cancel-actionable");
     const stallTimeoutStr = getFlag(extra, "--stall-timeout");
-    const stallTimeoutSeconds = stallTimeoutStr
-        ? parseDurationToMinutes(stallTimeoutStr, cfg.iterate.stallTimeoutMinutes) * 60
-        : cfg.iterate.stallTimeoutMinutes * 60;
+    const stallTimeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--stall-timeout", stallTimeoutStr, hasFlag(extra, "--stall-timeout"), MINUTE_FLAG_OPTS);
+    const stallTimeoutSeconds = parseDurationToSeconds(stallTimeoutSuffix ?? "", cfg.iterate.stallTimeoutMinutes * 60, MINUTE_FLAG_OPTS);
     return {
         readyDelaySuffix,
         readyDelaySeconds,
+        stallTimeoutSuffix,
         stallTimeoutSeconds,
         noAutoMarkReady,
         noAutoCancelActionable,

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/cli/poll-handler.mjs

@@ -11,7 +11,7 @@ export async function handlePoll(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const cfg = loadConfig();
     const flags = parseIterateFlags(extra, cfg);
-    if (flags.readyDelaySuffix === null)
+    if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
         return;
     const intervalStr = getFlag(extra, "--interval");
     const intervalSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--interval", intervalStr, hasFlag(extra, "--interval"));

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/escalate.mjs

@@ -25,6 +25,19 @@ export function checkEscalateTriggers(actionableThreads, threadAttempts) {
  * shell commands by `buildFixInstructions`, so we reject anything outside
  * `[A-Za-z0-9._/-]` to prevent shell injection.
  */
+/**
+ * Render a seconds count as an approximate human duration: "8 seconds" below one minute,
+ * otherwise whole minutes ("166 minutes", "60 minutes") — matching the precision the
+ * generic stall timer has always reported, just adding a seconds tier for sub-minute ages
+ * instead of always flooring to "0 minutes".
+ */
+export function formatDurationApprox(seconds) {
+    const s = Math.max(0, Math.floor(seconds));
+    if (s < 60)
+        return `${s} second${s === 1 ? "" : "s"}`;
+    const mins = Math.floor(s / 60);
+    return `${mins} minute${mins === 1 ? "" : "s"}`;
+}
 export function validateBaseBranch(raw) {
     const trimmed = raw.trim();
     if (trimmed === "") {
@@ -64,8 +77,7 @@ export function buildEscalateHumanMessage(escalate, pr) {
                 : c.detailsUrl
                     ? `external \`${c.detailsUrl}\``
                     : "no run ID";
-            const ageMinutes = Math.floor(c.ageSeconds / 60);
-            lines.push(`- check \`${c.name}\` — ${c.status} ${c.source}, ${target}, waiting ${ageMinutes} minute${ageMinutes === 1 ? "" : "s"}`);
+            lines.push(`- check \`${c.name}\` — ${c.status} ${c.source}, ${target}, waiting ${formatDurationApprox(c.ageSeconds)}`);
             if (c.summary)
                 lines.push(`  > ${c.summary}`);
         }
@@ -110,8 +122,8 @@ export function buildEscalateHumanMessage(escalate, pr) {
 }
 export function buildEscalateSuggestion(triggers, detail) {
     if (triggers.includes("stall-timeout")) {
-        const mins = detail ?? "60";
-        return `No progress detected for ${mins} minute${parseInt(mins, 10) === 1 ? "" : "s"} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
+        const duration = detail ?? "60 minutes";
+        return `No progress detected for ${duration} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
     }
     if (triggers.includes("base-branch-unknown")) {
         const reason = detail ? ` (${detail})` : "";

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/commands/iterate/stall.mjs

@@ -1,6 +1,6 @@
 import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
 import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
-import { buildEscalateSuggestion, buildEscalateHumanMessage } from "./escalate.mjs";
+import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationApprox, } from "./escalate.mjs";
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
@@ -37,14 +37,14 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
         action: prospectiveResult.action,
     });
     if (stalledChecks.length > 0) {
-        const stalledMinutes = Math.floor(Math.max(...stalledChecks.map((c) => c.ageSeconds)) / 60);
+        const stalledDuration = formatDurationApprox(Math.max(...stalledChecks.map((c) => c.ageSeconds)));
         const escalateBase = {
             triggers: ["stall-timeout"],
             unresolvedThreads: [],
             ambiguousComments: [],
             changesRequestedReviews: [],
             stalledChecks,
-            suggestion: buildEscalateSuggestion(["stall-timeout"], String(stalledMinutes)),
+            suggestion: buildEscalateSuggestion(["stall-timeout"], stalledDuration),
         };
         return {
             ...base,
@@ -68,13 +68,13 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
             await writeStallState(stallKey, { fingerprint, firstSeenAt: nowSeconds });
         }
         else if (ageSeconds >= stallTimeoutSeconds) {
-            const stalledMinutes = Math.floor(ageSeconds / 60);
+            const stalledDuration = formatDurationApprox(ageSeconds);
             const escalateBase = {
                 triggers: ["stall-timeout"],
                 unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
                 ambiguousComments: report.comments.actionable.map(toAgentComment),
                 changesRequestedReviews: report.changesRequestedReviews,
-                suggestion: buildEscalateSuggestion(["stall-timeout"], String(stalledMinutes)),
+                suggestion: buildEscalateSuggestion(["stall-timeout"], stalledDuration),
             };
             return {
                 ...base,

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.3",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -38,7 +38,7 @@
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
-    "oxfmt": "^0.56.0",
+    "oxfmt": "^0.57.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4"

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

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