pr-shepherd 0.30.0 → 0.31.0

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

package/bin/cli/fix-formatter-extra.mjs

@@ -0,0 +1,25 @@
+import { blockquote } from "./list-formatters.mjs";
+export function renderCheckAnnotation(a) {
+    const loc = `${a.path}:${renderAnnotationRange(a)}`;
+    const link = a.blobUrl ? ` [↗](${a.blobUrl})` : "";
+    const title = a.title ? ` — ${a.title}` : "";
+    const lines = [`- \`${a.id}\`${link} \`${loc}\` [${a.level}]${title}`];
+    if (a.message.trim() !== "")
+        lines.push(blockquote(a.message));
+    if (a.rawDetails !== undefined && a.rawDetails.trim() !== "")
+        lines.push(blockquote(a.rawDetails));
+    return lines.join("\n");
+}
+export function renderProtectedRun(run) {
+    const label = run.workflowName
+        ? `${run.workflowName} (${run.checkNames.join(", ")})`
+        : run.checkNames.join(", ");
+    return `- \`${run.runId}\` — \`${label}\` [matched: \`${run.matchedPattern}\`]`;
+}
+function renderAnnotationRange(a) {
+    if (a.startLine === null && a.endLine === null)
+        return "?";
+    const start = a.startLine ?? a.endLine;
+    const end = a.endLine ?? a.startLine;
+    return start === end ? String(start) : `${start}-${end}`;
+}

package/bin/cli/fix-formatter.mjs

@@ -3,6 +3,7 @@ import { joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
 import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, renderThreadConversation, blockquote, } from "./list-formatters.mjs";
 import { numberInstructions } from "./iterate-instructions.mjs";
+import { renderCheckAnnotation, renderProtectedRun } from "./fix-formatter-extra.mjs";
 export function formatFixCodeResult(header, result) {
     const sections = [header];
     if (result.fix.threads.length > 0) {
@@ -116,6 +117,9 @@ export function formatFixCodeResult(header, result) {
         sections.push("## In-progress runs");
         sections.push(result.fix.inProgressRunIds.map((id) => `- \`${id}\``).join("\n"));
     }
+    if (result.fix.protectedRuns.length > 0) {
+        sections.push("## Protected runs", result.fix.protectedRuns.map(renderProtectedRun).join("\n"));
+    }
     if (result.cancelled.length > 0) {
         sections.push("## Cancelled runs");
         sections.push(result.cancelled.map((id) => `- \`${id}\``).join("\n"));
@@ -132,29 +136,9 @@ export function formatFixCodeResult(header, result) {
     sections.push(numberInstructions(result.fix.instructions));
     return joinSections(sections);
 }
-function renderCheckAnnotation(a) {
-    const loc = `${a.path}:${renderAnnotationRange(a)}`;
-    const link = a.blobUrl ? ` [↗](${a.blobUrl})` : "";
-    const title = a.title ? ` — ${a.title}` : "";
-    const lines = [`- \`${a.id}\`${link} \`${loc}\` [${a.level}]${title}`];
-    if (a.message.trim() !== "")
-        lines.push(blockquote(a.message));
-    if (a.rawDetails !== undefined && a.rawDetails.trim() !== "")
-        lines.push(blockquote(a.rawDetails));
-    return lines.join("\n");
-}
 function indentBlockquote(body, indent) {
     return blockquote(body)
         .split("\n")
         .map((line) => `${indent}${line}`)
         .join("\n");
 }
-function renderAnnotationRange(a) {
-    if (a.startLine === null && a.endLine === null)
-        return "?";
-    const start = a.startLine ?? a.endLine;
-    const end = a.endLine ?? a.startLine;
-    if (start === end)
-        return String(start);
-    return `${start}-${end}`;
-}

package/bin/cli/iterate-lean.mjs

@@ -114,6 +114,9 @@ export function projectIterateLean(result, opts) {
                     ...(result.fix.inProgressRunIds.length > 0 && {
                         inProgressRunIds: result.fix.inProgressRunIds,
                     }),
+                    ...(result.fix.protectedRuns.length > 0 && {
+                        protectedRuns: result.fix.protectedRuns,
+                    }),
                     ...(result.fix.checks.length > 0 && { checks: result.fix.checks }),
                     ...(result.fix.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.fix.changesRequestedReviews,

package/bin/commands/iterate/fix-code.mjs

@@ -7,7 +7,7 @@ import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, bui
 import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
-import { tryCancelRun, buildInProgressRunIds } from "./helpers.mjs";
+import { tryCancelRun, buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./helpers.mjs";
 import { annotationMarkerBody } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
@@ -29,6 +29,7 @@ function nextFixAttempts(stored, headSha, threads) {
 export async function handleFixCode(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
     const failingChecks = report.checks.failing;
+    const { protectedRunIds, protectedRuns } = buildRunProtection([...failingChecks, ...report.checks.inProgress], opts.neverCancelRuns);
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);
     const botCrReviews = report.changesRequestedReviews.filter((r) => !isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames));
@@ -78,10 +79,8 @@ export async function handleFixCode(ctx) {
     await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
     let cancelled = [];
     if (!opts.noAutoCancelActionable) {
-        const uniqueRunIds = [
-            ...new Set(failingChecks.map((c) => c.runId).filter((id) => id !== null)),
-        ];
-        const results = await Promise.all(uniqueRunIds.map((id) => tryCancelRun(id, repoOwner, repoName)));
+        const runIds = buildAutoCancelRunIdsWithOptions(report, { protectedRunIds });
+        const results = await Promise.all(runIds.map((id) => tryCancelRun(id, repoOwner, repoName)));
         cancelled = results.filter((id) => id !== null);
     }
     const cancelledSet = new Set(cancelled);
@@ -100,7 +99,12 @@ export async function handleFixCode(ctx) {
         hasConflicts ||
         changesRequestedReviews.length > 0 ||
         actionableComments.length > 0;
-    const inProgressRunIds = pushLikely ? buildInProgressRunIds(report, cancelledSet) : [];
+    const inProgressRunIds = pushLikely
+        ? buildInProgressRunIds(report, cancelledSet, {
+            suppressProtectedFreshReruns: false,
+            protectedRunIds,
+        })
+        : [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
     const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, botUsernames, ruleAutoResolveThreadIds);
@@ -154,6 +158,7 @@ export async function handleFixCode(ctx) {
             firstLookThreads,
             firstLookComments,
             inProgressRunIds,
+            protectedRuns,
         },
         cancelled,
     };

package/bin/commands/iterate/helpers.mjs

@@ -2,13 +2,7 @@ import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { rest } from "../../github/http.mjs";
 const execFile = promisify(execFileCb);
-export function buildInProgressRunIds(report, cancelledSet) {
-    return [
-        ...new Set(report.checks.inProgress
-            .map((c) => c.runId)
-            .filter((id) => id !== null && !cancelledSet.has(id))),
-    ];
-}
+export { buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./reruns.mjs";
 export function buildSummary(report) {
     return {
         passing: report.checks.passing.length,
@@ -17,12 +11,7 @@ export function buildSummary(report) {
         inProgress: report.checks.inProgress.length,
     };
 }
-/**
- * Build the full list of CI checks relevant to PR readiness: triggered by a PR
- * event (or StatusContext with null event), completed, and not skipped/neutral.
- * Includes both passing and failing. Failing entries carry workflowName, jobName,
- * failedStep, and summary.
- */
+/** Build completed, non-skipped checks relevant to PR readiness. */
 export function buildRelevantChecks(report) {
     const excluded = new Set([null, "SKIPPED", "NEUTRAL"]);
     const passing = report.checks.passing.flatMap((c) => {
@@ -35,6 +24,7 @@ export function buildRelevantChecks(report) {
                 conclusion,
                 runId: c.runId,
                 detailsUrl: c.detailsUrl || null,
+                ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
                 summary: c.summary,
             },
         ];
@@ -66,6 +56,7 @@ export function buildActiveChecks(report) {
         status: c.status,
         runId: c.runId,
         detailsUrl: c.detailsUrl || null,
+        ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
         ...(c.summary !== undefined && { summary: c.summary }),
     }));
 }

package/bin/commands/iterate/index.mjs

@@ -16,12 +16,12 @@ export async function runIterate(opts) {
     const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
     const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate.stallTimeoutMinutes * 60;
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
-    if (prNumber === null) {
+    if (prNumber === null)
         throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
-    }
-    const optsWithPr = { ...opts, prNumber };
+    const neverCancelRuns = opts.neverCancelRuns ?? config.actions.neverCancelRuns;
     const report = await runCheck({
-        ...optsWithPr,
+        ...opts,
+        prNumber,
         autoResolve: config.actions.autoResolveOutdated,
         autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
     });
@@ -121,7 +121,7 @@ export async function runIterate(opts) {
         return handleFixCode({
             base,
             report,
-            opts,
+            opts: { ...opts, prNumber, neverCancelRuns },
             headSha,
             stallKey,
             prNumber,

package/bin/commands/iterate/reruns.mjs

@@ -0,0 +1,105 @@
+import picomatch from "picomatch";
+function matchesRerunCheck(failure, check) {
+    if (failure.runId !== null && check.runId !== null) {
+        return failure.runId === check.runId && failure.name === check.name;
+    }
+    return failure.runId === null && check.runId === null && failure.name === check.name;
+}
+function isProtectedByFreshRerun(failure, check) {
+    const attemptStartedAt = check.startedAtUnix ?? check.updatedAtUnix ?? check.createdAtUnix;
+    return (attemptStartedAt !== undefined &&
+        matchesRerunCheck(failure, check) &&
+        failure.completedAtUnix !== undefined &&
+        attemptStartedAt >= failure.completedAtUnix &&
+        (failure.startedAtUnix === undefined || failure.startedAtUnix < attemptStartedAt));
+}
+function hasProtectedFreshRerun(failure, checks) {
+    return checks.some((check) => isProtectedByFreshRerun(failure, check));
+}
+function isProtectedFreshRerun(check, failures) {
+    const matchingFailures = failures.filter((failure) => matchesRerunCheck(failure, check));
+    return (matchingFailures.length > 0 &&
+        matchingFailures.every((failure) => isProtectedByFreshRerun(failure, check)));
+}
+function protectedFreshRerunIds(report) {
+    return new Set(report.checks.inProgress
+        .filter((check) => isProtectedFreshRerun(check, report.checks.failing))
+        .map((check) => check.runId)
+        .filter((id) => id !== null));
+}
+export function buildAutoCancelRunIdsWithOptions(report, opts = {}) {
+    return [
+        ...new Set(report.checks.failing
+            .filter((check) => !hasProtectedFreshRerun(check, report.checks.inProgress))
+            .map((check) => check.runId)
+            .filter((id) => id !== null && !(opts.protectedRunIds?.has(id) ?? false))),
+    ];
+}
+export function buildInProgressRunIds(report, cancelledSet, opts = {}) {
+    const protectedRunIds = opts.suppressProtectedFreshReruns === false ? new Set() : protectedFreshRerunIds(report);
+    return [
+        ...new Set(report.checks.inProgress
+            .map((check) => check.runId)
+            .filter((id) => id !== null &&
+            !cancelledSet.has(id) &&
+            !protectedRunIds.has(id) &&
+            !(opts.protectedRunIds?.has(id) ?? false))),
+    ];
+}
+export function buildRunProtection(checks, patterns = []) {
+    if (patterns.length === 0)
+        return { protectedRunIds: new Set(), protectedRuns: [] };
+    const matchers = patterns.map((pattern) => ({
+        pattern,
+        isMatch: picomatch(pattern, { nocase: true }),
+    }));
+    const byRunId = new Map();
+    for (const check of checks) {
+        if (check.runId === null)
+            continue;
+        const match = findProtectionMatch(check, matchers);
+        if (match === null)
+            continue;
+        addProtectedRun(byRunId, check.runId, check, match);
+    }
+    const protectedRuns = [...byRunId.values()];
+    return {
+        protectedRunIds: new Set(protectedRuns.map((run) => run.runId)),
+        protectedRuns,
+    };
+}
+function addProtectedRun(byRunId, runId, check, matchedPattern) {
+    const existing = byRunId.get(runId);
+    if (existing) {
+        updateProtectedRun(existing, check);
+        return;
+    }
+    byRunId.set(runId, createProtectedRun(runId, check, matchedPattern));
+}
+function updateProtectedRun(run, check) {
+    if (!run.checkNames.includes(check.name))
+        run.checkNames.push(check.name);
+    if (run.workflowName === undefined && check.workflowName !== undefined) {
+        run.workflowName = check.workflowName;
+    }
+}
+function createProtectedRun(runId, check, matchedPattern) {
+    return {
+        runId,
+        matchedPattern,
+        checkNames: [check.name],
+        ...(check.workflowName !== undefined && { workflowName: check.workflowName }),
+    };
+}
+function findProtectionMatch(check, matchers) {
+    const candidates = [
+        check.workflowName,
+        "jobName" in check ? check.jobName : undefined,
+        check.name,
+    ].filter((value) => value !== undefined && value.trim() !== "");
+    for (const matcher of matchers) {
+        if (candidates.some((candidate) => matcher.isMatch(candidate)))
+            return matcher.pattern;
+    }
+    return null;
+}

package/bin/config/load.mjs

@@ -57,6 +57,12 @@ function parseIgnoreChecks(value) {
     }
     return value;
 }
+function parseNeverCancelRuns(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new Error(`Invalid config: actions.neverCancelRuns must be an array of strings`);
+    }
+    return value;
+}
 const defaults = builtins;
 const configCache = new Map();
 export function loadConfig() {
@@ -74,6 +80,7 @@ export function loadConfig() {
         const config = deepMerge(defaults, parsed);
         config.botUsernames = parseBotUsernames(config.botUsernames);
         config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
+        config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
         config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
         configCache.set(cwd, config);
         return config;

package/bin/config.json

@@ -39,6 +39,7 @@
     "autoResolveOutdated": true,
     "autoMinimizeSuppressed": true,
     "autoMarkReady": true,
-    "commitSuggestions": true
+    "commitSuggestions": true,
+    "neverCancelRuns": []
   }
 }

package/bin/github/batch-parsers.mjs

@@ -82,16 +82,14 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
     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
-                ? (node.checkSuite.workflowRun?.createdAt ?? node.checkSuite.createdAt)
-                : undefined;
-            const rawUpdatedAt = node.checkSuite
-                ? (node.checkSuite.workflowRun?.updatedAt ?? node.checkSuite.updatedAt)
-                : undefined;
+            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 [
                 {
@@ -103,8 +101,10 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
                     detailsUrl: node.detailsUrl ?? "",
                     event,
                     runId,
+                    ...(workflowName !== undefined && { workflowName }),
                     ...(createdAtUnix !== undefined && { createdAtUnix }),
                     ...(startedAtUnix !== undefined && { startedAtUnix }),
+                    ...(completedAtUnix !== undefined && { completedAtUnix }),
                     ...(updatedAtUnix !== undefined && { updatedAtUnix }),
                     ...(summary !== undefined && { summary }),
                 },

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

@@ -192,6 +192,7 @@ query BatchPr(
                     status
                     conclusion
                     detailsUrl
+                    completedAt
                     startedAt
                     title
                     summary
@@ -202,6 +203,9 @@ query BatchPr(
                         event
                         createdAt
                         updatedAt
+                        workflow {
+                          name
+                        }
                       }
                     }
                   }

package/bin/types/protected-run.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "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.52.0",
+    "oxfmt": "^0.53.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.30.0",
+  "version": "0.31.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",