pr-shepherd 0.46.3 → 0.46.5

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

package/README.md

@@ -69,12 +69,12 @@ Conversations Resolved: No [Not Required]
 1. Review each item under `## Review threads` and `## Failing checks` and decide whether it needs a code change.
 2. Apply every warranted review fix in each file referenced above.
 3. Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for read-only inspection rules.
-4. If you changed code, commit any remaining changes and push to the PR head branch, then run 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.
+4. If you changed code, commit any remaining changes and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate immediately with the same options. If you did not change code, do not commit and continue.
 5. Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an earlier Shepherd reply: a marked viewer-authored human thread is emitted resolve-only when authorized, while a marked other-human thread is already acknowledged and has no further mutation.
 6. If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, commit and push to the PR head branch first, then replace `$HEAD_SHA` with the pushed commit SHA.
 7. Replace `$DISMISS_MESSAGE` with one sentence describing what changed.
 8. Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.
-9. `[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate again with the same options; without code changes, complete the authorized review mutations and iterate again.
+9. `[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate immediately with the same options; without code changes, complete the authorized review mutations and iterate immediately.
 ```
 
 See [docs/actions.md](docs/actions.md) for the complete output contract and [docs/escalations.md](docs/escalations.md) for the exact finite human-handoff boundary. Iterate/poll PR outcomes use exit codes `0` and `10`–`15`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).

package/bin/cli/api-usage-formatter.mjs

@@ -18,7 +18,7 @@ export function formatQuotaWarning(warning) {
         `- Reset: ${resetTime(warning.resetAt)}`,
         `- Recommended poll interval: ${warning.pollIntervalMinutes} minutes`,
         `- Recommended bounded CLI timeout: ${warning.pollTimeoutMinutes} minutes`,
-        "- Recommendation: prefer non-GraphQL `gh` CLI commands for PR operations until the reset above, then resume pr-shepherd",
+        "- Recommendation: keep polling pr-shepherd at the cadence above; for incidental PR operations prefer REST `gh` (`gh pr view`, `gh pr review`, `gh api`); do not substitute `gh pr checks`/`gh pr watch`",
     ].join("\n");
 }
 export function formatApiUsage(usage) {

package/bin/cli/iterate-instructions.mjs

@@ -10,7 +10,7 @@ export function buildSimpleIterateInstructions(result) {
                 ];
             }
             return [
-                "Non-terminal — no action needed this tick. Iterate again with the same options to continue.",
+                "Non-terminal — no action needed this tick. Iterate immediately with the same options to continue.",
             ];
         case "mark_ready":
             if (result.quotaWarning) {
@@ -19,7 +19,7 @@ export function buildSimpleIterateInstructions(result) {
                 ];
             }
             return [
-                "The CLI marked the PR ready for review. Iterate again with the same options to continue.",
+                "The CLI marked the PR ready for review. Iterate immediately with the same options to continue.",
             ];
         case "merge": {
             const instructions = [
@@ -33,7 +33,7 @@ export function buildSimpleIterateInstructions(result) {
             }
             instructions.push(result.quotaWarning
                 ? buildQuotaAwareContinuation(result.quotaWarning, "After running the merge command.")
-                : "Then iterate again with the same options to monitor until the PR merges or needs work.");
+                : "Then iterate immediately with the same options to monitor until the PR merges or needs work.");
             return instructions;
         }
         case "cancel":

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:
@@ -73,12 +90,12 @@ export function buildFailingCheckInstructions(checks) {
 }
 export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false) {
     if (hasConflicts)
-        return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate again with the same options.";
+        return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate immediately with the same options.";
     if (hasShaGatedReviewMutations) {
-        return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate again with the same options; if you did not change code, complete the authorized review mutations and iterate again with the same options.";
+        return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate immediately with the same options; if you did not change code, complete the authorized review mutations and iterate immediately with the same options.";
     }
     if (checks.some((check) => check.rerunCommand)) {
-        return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate again with the same options to continue.";
+        return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate immediately with the same options to continue.";
     }
-    return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.";
+    return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate immediately with the same options to continue.";
 }

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

@@ -180,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 ||
@@ -194,7 +197,6 @@ 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}`)
@@ -257,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,8 +95,11 @@ 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 immediately.");
+    }
     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.");
+        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 immediately with the same options. If you did not change code, do not commit and continue with the remaining steps.");
     }
     if (viewerCanUpdate &&
         (hasReviewMutations ||

package/bin/quota-warning.mjs

@@ -2,5 +2,5 @@ export function buildQuotaAwareContinuation(warning, prefix) {
     const interval = `${warning.pollIntervalMinutes}m`;
     const timeout = `${warning.pollTimeoutMinutes}m`;
     const resetTime = new Date(warning.resetAt * 1000).toISOString();
-    return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). For the time being, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr checks\`, \`gh pr review\`, \`gh api\` REST endpoints) for PR operations — they draw on the separate REST budget, not the depleted GraphQL pool. Resume pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, replace any existing interval and timeout flags with \`--interval ${interval} --timeout ${timeout}\`, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
+    return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool. Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, replace any existing interval and timeout flags with \`--interval ${interval} --timeout ${timeout}\`, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
 }

package/package.json

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

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

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

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

@@ -8,7 +8,7 @@ allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob", "Edit", "Write"]
 
 # pr-shepherd
 
-Thin dispatcher for creating or iterating a PR. Poll with the CLI; use MCP `iterate` only when the CLI is unavailable.
+Thin dispatcher for creating or iterating a PR. Poll with the CLI; use MCP `iterate` only when the CLI is unavailable. Keep invoking until `[CANCEL]` or `[ESCALATE]`. Do not wait for CI to finish before the next Shepherd step — fetching check logs is fine; blocking on `gh pr checks`, `gh pr watch`, `gh run watch`, or equivalent GitHub MCP check waiters is not. Shepherd already returns CI plus review comments, and waiting for CI before applying review feedback wastes CI.
 
 ## PR creation authorization
 
@@ -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, immediately 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. After a push or `rerun:`, do not wait for CI to finish first — you may pull check logs, but do not poll with `gh pr checks`, `gh pr watch`, `gh run watch`, or equivalent GitHub MCP check waiters.
 
 ## Playbooks
 
@@ -50,15 +50,15 @@ A `[rerun authorized]` tag with a `rerun:` command means the viewer's repository
 
 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.
 
-| Tag / kind                                                               | Do                                                                                                                                                                                                                                                |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt. Apply a warranted code fix, or run the printed `rerun:` command when the evidence indicates a transient failure, then iterate again. Missing autonomous follow-up becomes `[ESCALATE]` when no other work remains. |
-| Transient infrastructure failure                                         | Run the `rerun:` command when present, then iterate again once it completes. If no command is present, complete any other surfaced work and iterate; Shepherd owns any later `[ESCALATE]`.                                                        |
-| Real test or build failure                                               | Apply a code fix — do not rerun, even if `[rerun authorized]` is shown.                                                                                                                                                                           |
-| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered. Run the printed `rerun:` command, then iterate again once it completes. Without a command, complete any other work and iterate; Shepherd escalates when this remains the only blocker.                                |
-| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered. Run the printed `rerun:` command, then iterate again once it completes. Without a command, complete any other work and iterate; Shepherd escalates when this remains the only blocker.                                |
-| `[conclusion: ACTION_REQUIRED]`                                          | This appears in `[FIX_CODE]` only alongside other autonomous work. Complete that work and iterate; Shepherd returns `[ESCALATE]` if manual workflow approval remains necessary.                                                                   |
-| `external` (no run ID, has a URL)                                        | Treat the URL as an autonomous investigation path: inspect the provider or reproduce the failure locally, apply any warranted fix, and iterate. A non-empty external URL does not trigger `[ESCALATE]` by itself.                                 |
+| Tag / kind                                                               | Do                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt. Apply a warranted code fix, or run the printed `rerun:` command when the evidence indicates a transient failure, then iterate immediately. Missing autonomous follow-up becomes `[ESCALATE]` when no other work remains. |
+| Transient infrastructure failure                                         | Run the `rerun:` command when present, then iterate immediately. Do not wait for the rerun to finish. If no command is present, complete any other surfaced work and iterate; Shepherd owns any later `[ESCALATE]`.                                     |
+| Real test or build failure                                               | Apply a code fix — do not rerun, even if `[rerun authorized]` is shown.                                                                                                                                                                                 |
+| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered. Run the printed `rerun:` command, then iterate immediately. Do not wait for the rerun to finish. Without a command, complete any other work and iterate; Shepherd escalates when this remains the only blocker.             |
+| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered. Run the printed `rerun:` command, then iterate immediately. Do not wait for the rerun to finish. Without a command, complete any other work and iterate; Shepherd escalates when this remains the only blocker.             |
+| `[conclusion: ACTION_REQUIRED]`                                          | This appears in `[FIX_CODE]` only alongside other autonomous work. Complete that work and iterate; Shepherd returns `[ESCALATE]` if manual workflow approval remains necessary.                                                                         |
+| `external` (no run ID, has a URL)                                        | Treat the URL as an autonomous investigation path: inspect the provider or reproduce the failure locally, apply any warranted fix, and iterate. A non-empty external URL does not trigger `[ESCALATE]` by itself.                                       |
 
 ### Review-mutation mechanics