pr-shepherd 0.46.2 → 0.46.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.46.2",
+  "version": "0.46.3",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/checks/triage.mjs

@@ -12,18 +12,18 @@ export function triageFailingChecks(failingChecks, repo, stateKey) {
     return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, stateKey)));
 }
 async function triageCheck(check, repo, jobsCache, stateKey) {
-    if (check.runId === null ||
-        check.conclusion === "CANCELLED" ||
-        check.conclusion === "STARTUP_FAILURE") {
+    if (check.runId === null || check.conclusion === "STARTUP_FAILURE") {
         return { ...check };
     }
     const jobs = await fetchJobs(check.runId, repo, jobsCache, stateKey);
     const jobInfo = jobs ? pickJobInfo(jobs, check.name) : undefined;
-    const logExcerpt = jobInfo?.jobId
+    const runAttempt = jobs ? pickRunAttempt(jobs) : undefined;
+    const logExcerpt = check.conclusion !== "CANCELLED" && jobInfo?.jobId
         ? await fetchJobLogExcerpt(jobInfo.jobId, repo, stateKey, jobInfo.jobConclusion != null)
         : undefined;
     return {
         ...check,
+        ...(runAttempt !== undefined && { runAttempt }),
         ...(jobInfo?.workflowName !== undefined && { workflowName: jobInfo.workflowName }),
         ...(jobInfo?.jobName !== undefined && { jobName: jobInfo.jobName }),
         ...(jobInfo?.failedStep !== undefined && { failedStep: jobInfo.failedStep }),
@@ -72,6 +72,7 @@ async function fetchStartupFailureChecksUncached(repo, headSha, prNumber, stateK
 }
 function workflowRunToCheckRun(run) {
     const summary = run.display_title?.trim() || undefined;
+    const runAttempt = normalizeRunAttempt(run.run_attempt);
     return {
         name: run.name?.trim() || `workflow run ${run.id}`,
         status: "COMPLETED",
@@ -80,9 +81,21 @@ function workflowRunToCheckRun(run) {
         detailsUrl: run.html_url,
         event: run.event,
         runId: String(run.id),
+        ...(runAttempt !== undefined && { runAttempt }),
         ...(summary !== undefined && { summary }),
     };
 }
+function normalizeRunAttempt(value) {
+    return Number.isSafeInteger(value) && (value ?? 0) > 0 ? value : undefined;
+}
+function pickRunAttempt(jobs) {
+    for (const job of jobs) {
+        const attempt = normalizeRunAttempt(job.run_attempt);
+        if (attempt !== undefined)
+            return attempt;
+    }
+    return undefined;
+}
 function runBelongsToPr(run, prNumber, headSha) {
     return (run.pull_requests ?? []).some((pr) => pr.number === prNumber && (pr.head?.sha ?? headSha) === headSha);
 }

package/bin/cli/fix-formatter.mjs

@@ -63,12 +63,13 @@ export function formatFixCodeResult(header, result) {
                     ? `external \`${ch.detailsUrl}\``
                     : "(no runId)";
             const conclusionTag = ch.conclusion !== null ? ` [conclusion: ${ch.conclusion}]` : "";
+            const attemptTag = ch.runAttempt !== undefined ? ` [attempt: ${ch.runAttempt}]` : "";
             const scopeTag = ch.scope
                 ? ` [scope: ${ch.scope}${ch.commitOid ? `, commit: ${ch.commitOid}` : ""}]`
                 : "";
             const rerunTag = ch.rerunCommand ? " [rerun authorized]" : "";
             const lines = [
-                `- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${scopeTag}${rerunTag}`,
+                `- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${attemptTag}${scopeTag}${rerunTag}`,
             ];
             if (ch.conclusion !== "CANCELLED") {
                 if (ch.failedStep)

package/bin/commands/check.mjs

@@ -40,7 +40,8 @@ export async function runCheck(opts) {
     if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
         return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
     }
-    const startupFailureChecks = result.checkSuitesComplete
+    const startupFailuresNeedAttempt = batchData.checks.some((check) => check.source === "startup_failure" && check.runAttempt === undefined);
+    const startupFailureChecks = result.checkSuitesComplete && !startupFailuresNeedAttempt
         ? []
         : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber, stateKey);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);

package/bin/commands/iterate/escalate.mjs

@@ -41,8 +41,9 @@ function renderEscalateCheck(check) {
     const workflowPrefix = check.workflowName ? `${check.workflowName} › ` : "";
     const jobLabel = check.jobName ?? check.name;
     const conclusion = check.conclusion ?? "UNKNOWN";
+    const attempt = check.runAttempt !== undefined ? ` [attempt: ${check.runAttempt}]` : "";
     const lines = [
-        `- ${renderCheckTarget(check)} — \`${workflowPrefix}${jobLabel}\` [conclusion: ${conclusion}]${renderCheckScope(check)}`,
+        `- ${renderCheckTarget(check)} — \`${workflowPrefix}${jobLabel}\` [conclusion: ${conclusion}]${attempt}${renderCheckScope(check)}`,
     ];
     if (check.failedStep)
         lines.push(`  > failed step: ${check.failedStep}`);

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

@@ -17,6 +17,11 @@ import { formatPrUrl } from "../../pr-reference.mjs";
 function checkRequiresHumanFollowUp(check) {
     if (check.rerunCommand)
         return false;
+    // Once GitHub advances beyond the original attempt, Shepherd's one autonomous rerun has
+    // already been consumed. Hand the repeated failure off even when logs are available; the
+    // human still receives that evidence in the escalation payload.
+    if (check.runAttempt !== undefined && check.runAttempt > 1)
+        return true;
     if (check.conclusion === "ACTION_REQUIRED" ||
         check.conclusion === "CANCELLED" ||
         check.conclusion === "STARTUP_FAILURE")
@@ -138,9 +143,13 @@ export async function handleFixCode(ctx) {
     const actionsRunIds = new Set(failingChecks.flatMap((c) => c.runId !== null && (c.source === "startup_failure" || c.workflowName !== undefined)
         ? [c.runId]
         : []));
+    const initialAttemptRunIds = new Set(failingChecks.flatMap((c) => (c.runId !== null && c.runAttempt === 1 ? [c.runId] : [])));
     const failingAgentChecks = toAgentChecks(failingChecks).map((c) => rerunAuthorized &&
         c.runId &&
         actionsRunIds.has(c.runId) &&
+        // GitHub increments run_attempt after every rerun. Recommend at most one rerun by limiting
+        // the command to the original attempt; missing attempt metadata is denied conservatively.
+        initialAttemptRunIds.has(c.runId) &&
         // ACTION_REQUIRED means the run is paused pending manual workflow approval; rerunning does
         // not grant that approval, so no rerun command applies.
         c.conclusion !== "ACTION_REQUIRED" &&
@@ -185,13 +194,19 @@ export async function handleFixCode(ctx) {
         checks.some((check) => (check.annotations?.length ?? 0) > 0) ||
         failingAgentChecks.some((check) => belongsToActiveWorkflowRun(check) || !checkRequiresHumanFollowUp(check));
     if (manualFollowUpChecks.length > 0 && !hasAutonomousWork) {
+        const exhaustedAttempts = manualFollowUpChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
+        const checkSuggestion = exhaustedAttempts.length > 0
+            ? `GitHub reports a later workflow attempt (${exhaustedAttempts
+                .map((check) => `${check.runId ?? check.name}: attempt ${check.runAttempt}`)
+                .join(", ")}), so Shepherd's single rerun allowance is exhausted. Use the included evidence to handle the repeated failure manually before resuming.`
+            : buildEscalateSuggestion(["check-follow-up-unavailable"]);
         const checkEscalateBase = {
             triggers: ["check-follow-up-unavailable"],
             unresolvedThreads: [],
             ambiguousComments: [],
             changesRequestedReviews,
             checks: manualFollowUpChecks,
-            suggestion: buildEscalateSuggestion(["check-follow-up-unavailable"]),
+            suggestion: checkSuggestion,
         };
         return {
             ...base,

package/bin/commands/iterate/stall.mjs

@@ -5,7 +5,7 @@ import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
-        ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
+        ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}:${f.runId ?? "no-run"}:${f.runAttempt ?? "unknown"}`),
         ...report.checks.inProgress.map((p) => `inProgress:${p.name}`),
     ].sort();
     const threads = report.threads.actionable.map((t) => t.id).sort();

package/bin/reporters/agent.mjs

@@ -60,6 +60,7 @@ export function toAgentCheck(c) {
         runId: c.runId,
         detailsUrl: c.detailsUrl,
         conclusion: c.conclusion,
+        ...(c.runAttempt !== undefined && c.runAttempt > 1 && { runAttempt: c.runAttempt }),
         ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
         ...(c.jobName !== undefined && { jobName: c.jobName }),
         ...(c.failedStep !== undefined && { failedStep: c.failedStep }),

package/bin/types/github.d.mts

@@ -30,6 +30,8 @@ export interface CheckRun {
     detailsUrl: string;
     event: string | null;
     runId: string | null;
+    /** GitHub Actions workflow-run attempt number. Omitted for non-Actions or unavailable metadata. */
+    runAttempt?: number;
     /** Commit scope that supplied this check. Omitted for ordinary PR-head checks. */
     scope?: "merge_group";
     /** Synthetic merge-group commit OID, when `scope` is `merge_group`. */

package/bin/types/report.d.mts

@@ -138,6 +138,8 @@ export interface AgentCheck {
     logExcerpt?: string;
     /** `gh run rerun` command, present only when the check has a runId and the viewer's repository role grants Actions rerun capability (WRITE+). */
     rerunCommand?: string;
+    /** Workflow-run attempt number, surfaced only after the initial attempt. */
+    runAttempt?: number;
     annotations?: CheckAnnotation[];
     annotationOnly?: true;
     scope?: "merge_group";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.46.2",
+  "version": "0.46.3",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.46.2",
+  "version": "0.46.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.46.2", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.46.3", "pr-shepherd-mcp"]
     }
   }
 }

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

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

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -46,7 +46,7 @@ Match each failure's `[conclusion: …]` tag under `## Failing checks` to a rule
 
 More specific rows win over the general "GitHub Actions failure" row — check conclusion first.
 
-A `[rerun authorized]` tag with a `rerun:` command means the viewer's repository role grants GitHub's Actions rerun capability (WRITE+) — Shepherd verified this from `repositoryPermission`. Run the printed command at most once. A run still in progress, an `ACTION_REQUIRED` run (paused pending manual workflow approval — a rerun cannot grant that approval), or a check whose runId does not resolve to a GitHub Actions workflow never gets `[rerun authorized]`, regardless of role. When a check has no autonomous follow-up and no other agent work remains, Shepherd returns `[ESCALATE]`; do not invent a handoff from a `[FIX_CODE]` result.
+A `[rerun authorized]` tag with a `rerun:` command means the viewer's repository role grants GitHub's Actions rerun capability (WRITE+) and GitHub reports the original workflow attempt — Shepherd verified these from `repositoryPermission` and `run_attempt`. Run the printed command at most once. Later attempts carry an `[attempt: N]` tag, never get another command, and return `[ESCALATE]` when no other autonomous work remains, even when a log excerpt exists. A run still in progress, an `ACTION_REQUIRED` run (paused pending manual workflow approval — a rerun cannot grant that approval), a check whose runId does not resolve to a GitHub Actions workflow, or a run whose attempt metadata is unavailable never gets `[rerun authorized]`. When a check has no autonomous follow-up and no other agent work remains, Shepherd returns `[ESCALATE]`; do not invent a handoff from a `[FIX_CODE]` result.
 
 When several bullets share one runId (matrix jobs from the same run), the `rerun:` command is printed once, on the first bullet; every bullet for that runId still carries `[rerun authorized]` and is covered by that single command — do not run it more than once.