pr-shepherd 0.46.2 → 0.46.4

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.4",
   "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/check-instructions.d.mts

@@ -11,6 +11,15 @@ export declare function buildCrStaleClause(reviews: Review[]): string;
  * discarding the rest of the user's config.
  */
 export declare function buildBehindBaseHintInstruction(baseBranch: string, hint: string, isBehind: boolean): string[];
+/**
+ * Give one branch-refresh recovery path after Shepherd's single workflow rerun has failed.
+ * The fetched PR base branch is raw context; the caller still owns repository-specific git
+ * mechanics and decides whether the base contains a relevant fix.
+ */
+export declare function buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch: string, hasExhaustedWorkflowRerun: boolean, branch: {
+    isBehind: boolean;
+    hasConflicts: boolean;
+}): string[];
 /**
  * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
  * whenever the *unmodified, as-printed* command is unsafe without them:

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

@@ -20,6 +20,23 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
         return [];
     return [`The branch is behind PR base branch \`${baseBranch}\`. ${trimmedHint} before pushing.`];
 }
+/**
+ * Give one branch-refresh recovery path after Shepherd's single workflow rerun has failed.
+ * The fetched PR base branch is raw context; the caller still owns repository-specific git
+ * mechanics and decides whether the base contains a relevant fix.
+ */
+export function buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, branch) {
+    if (!hasExhaustedWorkflowRerun || (!branch.isBehind && !branch.hasConflicts))
+        return [];
+    const state = branch.hasConflicts ? "conflicts with" : "is behind";
+    const instructions = [
+        `The workflow rerun still fails while the branch ${state} PR base branch \`${baseBranch}\`. Inspect the current base branch for an existing fix before choosing a remediation.`,
+    ];
+    instructions.push(branch.hasConflicts
+        ? `Rebase or otherwise update the PR branch from \`${baseBranch}\` according to repository conventions, resolving conflicts as part of that update.`
+        : `Rebase or otherwise update the PR branch from \`${baseBranch}\` according to repository conventions.`);
+    return instructions;
+}
 /**
  * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
  * whenever the *unmodified, as-printed* command is unsafe without them:

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" &&
@@ -171,7 +180,10 @@ export async function handleFixCode(ctx) {
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
     const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
     const manualFollowUpChecks = failingAgentChecks.filter((check) => !belongsToActiveWorkflowRun(check) && checkRequiresHumanFollowUp(check));
+    const exhaustedAttempts = manualFollowUpChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
+    const hasBehindBaseRecovery = isBehind && exhaustedAttempts.length > 0;
     const hasAutonomousWork = hasConflicts ||
+        hasBehindBaseRecovery ||
         threads.length > 0 ||
         resolutionOnlyThreads.length > 0 ||
         actionableComments.length > 0 ||
@@ -185,13 +197,18 @@ 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 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,
@@ -242,7 +259,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0);
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/render.d.mts

@@ -2,4 +2,4 @@ import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, Fir
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
 export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind?: boolean, viewerCanUpdate?: boolean): string[];
+isBehind?: boolean, viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean): string[];

package/bin/commands/iterate/render.mjs

@@ -1,5 +1,5 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
-import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
+import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildRepeatedWorkflowBranchRecoveryInstructions, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
@@ -11,11 +11,16 @@ export function renderResolveCommand(rc) {
     return renderShellCommand(parts);
 }
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false, viewerCanUpdate = false) {
+isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
     const instructions = [];
     const locatedThreads = threads.filter((thread) => thread.path !== null && thread.line !== null);
     const unlocatedThreads = threads.filter((thread) => thread.path === null || thread.line === null);
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
+    const repeatedWorkflowBranchRecoveryInstructions = buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, {
+        isBehind,
+        hasConflicts,
+    });
+    const hasRepeatedWorkflowBranchRecovery = repeatedWorkflowBranchRecoveryInstructions.length > 0;
     const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
     const hasNonConflictHints = threads.length > 0 ||
         failingChecks.length > 0 ||
@@ -41,7 +46,7 @@ isBehind = false, viewerCanUpdate = false) {
         const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
         instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
     }
-    if (hasConflicts) {
+    if (hasConflicts && !hasRepeatedWorkflowBranchRecovery) {
         instructions.push("The branch has merge conflicts (see `**branch**` above). Resolve them before committing.");
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
@@ -76,7 +81,7 @@ isBehind = false, viewerCanUpdate = false) {
     if (resolutionOnlyThreads.length > 0) {
         instructions.push('Review the threads under `## Review threads to resolve` before running mutations. Use the generated commands as shown — see "Review-mutation routing" in the pr-shepherd skill for which flag applies to which ID.');
     }
-    instructions.push(...buildFailingCheckInstructions(failingChecks));
+    instructions.push(...buildFailingCheckInstructions(failingChecks), ...repeatedWorkflowBranchRecoveryInstructions);
     if (hasAnnotations) {
         instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.");
     }
@@ -90,6 +95,9 @@ isBehind = false, viewerCanUpdate = false) {
     if (hasConflicts) {
         instructions.push(`Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`);
     }
+    else if (hasRepeatedWorkflowBranchRecovery) {
+        instructions.push("Push the updated PR head branch before iterating again.");
+    }
     else if (hasNonConflictHints) {
         instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate again with the same options. If you did not change code, do not commit and continue with the remaining steps.");
     }

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.4",
   "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.4",
   "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.4", "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.4", "pr-shepherd-mcp"]
   }
 }

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

@@ -20,11 +20,11 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
 
 1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL and an optional `--merge` flag from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
 
-2. For the CLI, convert supplied `owner/repo#N` to `https://github.com/owner/repo/pull/N`; otherwise pass the supplied URL or bare number unchanged, then run the poll command `pr-shepherd` with the optional PR argument and forward `--merge` when supplied. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `iterate` with that qualified reference, plus `merge: true` when `--merge` was supplied, and print its full result.
+2. For the CLI, convert supplied `owner/repo#N` to `https://github.com/owner/repo/pull/N`; otherwise pass the supplied URL or bare number unchanged, then run the canonical poll command `pr-shepherd [PR] --until-terminal`, omitting `[PR]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; it returns for agent-facing work, a quota warning, `[CANCEL]`, or `[ESCALATE]`. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `iterate` with that qualified reference, plus `merge: true` when `--merge` was supplied, and print its full result.
 
 3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.
 
-4. After completing the returned instructions, repeat step 2 unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. `[FIX_CODE]` is always non-terminal: complete its instructions and rerun the same canonical command without asking whether to continue. Only `[ESCALATE]` hands work to a human.
+4. After completing the returned instructions, repeat step 2 with the same target and canonical options unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. Preserve `--until-terminal` and any requested `--merge`; apply any polling-cadence adjustment printed by the CLI. Every other action is non-terminal: complete its instructions and rerun without asking whether to continue. `[FIX_CODE]` is always non-terminal, and only `[ESCALATE]` hands work to a human.
 
 ## Playbooks
 
@@ -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.