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

package/README.md

@@ -84,7 +84,7 @@ See [docs/actions.md](docs/actions.md) for the complete output contract and [doc
 This system is opinionated and works best with PRs that use required status checks and conversation resolution.
 
 - A human inline thread whose original comment has `viewerDidAuthor: true` is replied to and resolved when its latest comment is unmarked. An unmarked other-human inline thread remains reply-only; a marker-ended other-human thread is already acknowledged and receives no further mutation. Human items are never minimized.
-- Detected bots and configured `botUsernames` review threads are returned until resolved when the required mutation is authorized and the thread has a source location. Unauthorized or unlocated items are surfaced once and then marker-gated until edited. Bot/non-human threads, PR comments, and review summaries can be resolved or minimized when eligible. Review summaries are not minimized while known inline child threads from that review remain unresolved.
+- Detected bots and configured `botUsernames` review threads are returned until resolved when the required mutation is authorized and the thread has a source location. Authorized outdated bot threads remain resolution-only work even when GitHub clears their source line, because resolving by thread ID does not require that location. Unauthorized or other unlocated items are surfaced once and then marker-gated until edited. Bot/non-human threads, PR comments, and review summaries can be resolved or minimized when eligible. Review summaries are not minimized while known inline child threads from that review remain unresolved.
 - Shepherd identifies its own latest reply only when that comment begins `<!-- pr-shepherd -->`, not from author equality. A marked viewer-authored thread can be resolved without another reply as a retry.
 - Every review thread/comment/review summary is surfaced at least once, even if already outdated, resolved, or minimized; edited items re-surface through seen markers.
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.

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

@@ -17,7 +17,7 @@ import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, }
 import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
-import { buildThreadMutationRouting } from "./iterate/thread-mutation-routing.mjs";
+import { buildThreadMutationRouting, canResolveOutdatedBotWithoutLocation, } from "./iterate/thread-mutation-routing.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.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);
@@ -86,10 +87,11 @@ export async function runCheck(opts) {
     const replyThreadIds = new Set(threadMutationRouting.replyThreadIds);
     const resolveThreadIds = new Set(threadMutationRouting.resolveThreadIds);
     const repeatableThreadIds = new Set(visibleThreadCandidates
-        .filter((thread) => thread.path !== null &&
+        .filter((thread) => (thread.path !== null &&
         thread.line !== null &&
         (!replyThreadIds.has(thread.id) || thread.viewerCanReply === true) &&
-        (!resolveThreadIds.has(thread.id) || thread.viewerCanResolve === true))
+        (!resolveThreadIds.has(thread.id) || thread.viewerCanResolve === true)) ||
+        canResolveOutdatedBotWithoutLocation(thread, botUsernames))
         .map((thread) => thread.id));
     const threadVisibility = classifyThreadVisibility(visibleThreadCandidates, seenMap, botUsernames, repeatableThreadIds);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {

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

@@ -5,7 +5,7 @@ import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/ag
 import { hashBody, markSeen } from "../../state/seen-comments.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
 import { buildResolveCommand } from "./classify.mjs";
-import { buildThreadMutationRouting } from "./thread-mutation-routing.mjs";
+import { buildThreadMutationRouting, canResolveOutdatedBotWithoutLocation, } from "./thread-mutation-routing.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.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" &&
@@ -157,7 +166,9 @@ export async function handleFixCode(ctx) {
         isConfiguredBotAuthor(review, botUsernames));
     const skippedDismissalIds = new Set(unauthorizedDismissals.map((review) => review.id));
     const changesRequestedReviewsForWork = actionableChangesRequestedReviews.filter((review) => !skippedDismissalIds.has(review.id));
-    const resolutionOnlyThreadsForWork = resolutionOnlyThreads.filter((thread) => !skippedThreadIds.has(thread.id) && thread.path !== null && thread.line !== null);
+    const resolutionOnlyThreadsForWork = resolutionOnlyThreads.filter((thread) => !skippedThreadIds.has(thread.id) &&
+        ((thread.path !== null && thread.line !== null) ||
+            canResolveOutdatedBotWithoutLocation(thread, botUsernames)));
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
     const { behindBaseHint } = loadConfig().iterate;
@@ -183,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,
@@ -209,15 +226,16 @@ export async function handleFixCode(ctx) {
     const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(retryableAgentThreads, resolutionOnlyThreadsForWork, allCommentIds, changesRequestedReviewsForWork, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads);
     // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
     // would need the correct base to rebase safely. This is a conservative guard, not a
-    // prediction that the agent *will* push. Intentionally broader than `pushLikely` above:
-    // resolution-only threads also need a known base in case the agent does push.
+    // prediction that the agent *will* push. Located resolution-only threads retain that guard;
+    // an outdated bot thread resolved only by ID has no code or push path.
+    const locatedResolutionOnlyThreadsForWork = resolutionOnlyThreadsForWork.filter((thread) => thread.path !== null && thread.line !== null);
     const pushIsPlausible = retryableActionableThreads.length > 0 ||
         failingAgentChecks.length > 0 ||
         annotatedExtra.length > 0 ||
         hasConflicts ||
         changesRequestedReviewsForWork.length > 0 ||
         actionableComments.length > 0 ||
-        resolutionOnlyThreadsForWork.length > 0;
+        locatedResolutionOnlyThreadsForWork.length > 0;
     if (baseLookup.isFallback && pushIsPlausible) {
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],

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/commands/iterate/thread-mutation-routing.d.mts

@@ -6,4 +6,5 @@ export interface ThreadMutationRouting {
     standaloneResolveThreadIds: string[];
     resolveThreadIds: string[];
 }
+export declare function canResolveOutdatedBotWithoutLocation(thread: ReviewThread, botUsernames: NormalizedBotUsernames): boolean;
 export declare function buildThreadMutationRouting(threads: Array<AgentThread | ReviewThread>, botUsernames: NormalizedBotUsernames, ruleAutoResolveThreadIds: string[]): ThreadMutationRouting;

package/bin/commands/iterate/thread-mutation-routing.mjs

@@ -3,6 +3,13 @@ import { threadEndedByShepherd } from "../../comments/marker.mjs";
 function dedupeIds(ids) {
     return [...new Set(ids)];
 }
+export function canResolveOutdatedBotWithoutLocation(thread, botUsernames) {
+    return (!thread.isResolved &&
+        thread.isOutdated &&
+        (thread.path === null || thread.line === null) &&
+        isConfiguredBotAuthor(thread, botUsernames) &&
+        thread.viewerCanResolve === true);
+}
 export function buildThreadMutationRouting(threads, botUsernames, ruleAutoResolveThreadIds) {
     const isOrdinaryHuman = (thread) => isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
     const replyThreadIds = dedupeIds(threads

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.1",
+  "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.1",
+  "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.1", "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.1", "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.
 
@@ -64,7 +64,7 @@ When several bullets share one runId (matrix jobs from the same run), the `rerun
 
 Applies to every `apply review:` / `resolve-only:` command the CLI prints. Covers only what stays safe if you run the printed command **unmodified** — `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution remains a separate CLI-printed step because the command is unsafe by default without those placeholders.
 
-The CLI only includes IDs whose per-object GitHub viewer capability and semantic routing authorize the corresponding generated action. Direct `apply review` honors those emitted IDs without a second authorization preflight and surfaces GitHub's per-operation result. Do not reconstruct omitted review reply, thread resolution, or bot-review dismissal IDs and do not hand them off: denied or unverifiable generated mutations are one-look skips that Shepherd suppresses until the item is edited. Threads without a path or line follow the same skip rule.
+The CLI only includes IDs whose per-object GitHub viewer capability and semantic routing authorize the corresponding generated action. Direct `apply review` honors those emitted IDs without a second authorization preflight and surfaces GitHub's per-operation result. Do not reconstruct omitted review reply, thread resolution, or bot-review dismissal IDs and do not hand them off: denied or unverifiable generated mutations are one-look skips that Shepherd suppresses until the item is edited. Active threads without a path or line follow the same skip rule; authorized outdated bot threads are emitted for resolution by thread ID even when GitHub clears their source line.
 
 - Run every generated `apply review:` / `resolve-only:` command even when no code change is warranted. The command records the agent's disposition of the included review items; skipping it leaves bot threads active and can eventually trigger `fix-thrash`.
 - Never add first-look-only or check-annotation IDs to `--reply-thread-ids`, `--resolve-thread-ids`, `--dismiss-review-ids`, or `--minimize-comment-ids` — those flags are pre-populated by the CLI.