pr-shepherd 0.49.0 → 0.50.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -72,7 +72,7 @@ Conversations Resolved: No [Not Required]
 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 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 thread that is still being resolved is emitted resolve-only when authorized.
+5. Substitute any command placeholders and run the generated review mutations.
 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.
@@ -92,7 +92,7 @@ This system is opinionated and works best with PRs that use required status chec
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
 - With `--merge`, actionable review threads/comments/reviews/summaries are held back (`WAIT`, with raw deferred-work counts) while a PR sits in the merge queue, since a Shepherd-initiated push would eject it; set `actions.workWhileQueued: true` to act on them immediately instead. Failing checks and merge conflicts are never deferred.
 - The CLI never performs git mutations itself — it only emits commit/push instructions for the agent to run. Push access to the PR head is a usage precondition; GitHub viewer fields do not create a separate push-authorization handoff.
-- Generated iterate mutations and automatic actions are capability-aware and omit unauthorized commands. Explicit `apply` operations honor the caller's intent and surface GitHub's result; semantic human-content protections still apply.
+- Generated iterate mutations and automatic actions are capability-aware and omit unauthorized commands. Explicit `apply` operations forward the caller's requested IDs without iterate's author or capability policy and surface GitHub's result.
 - `build_suggestion_patches` turns one or more ordered GitHub suggestion threads into checked patches and commit metadata, but never edits the working tree or git history. Local HEAD may be ahead when the live PR head is its ancestor.
 
 ## Usage

package/bin/cli/help-command-pages.d.mts

@@ -14,7 +14,8 @@ Run 'pr-shepherd apply <review|files|journal> --help' for command-specific detai
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply review": `pr-shepherd apply review
 
-Apply GitHub review-state mutations after fixes.
+Apply user-directed GitHub review-state mutations after fixes. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd apply review [PR] --reply-thread-ids A,B --message MSG
@@ -24,10 +25,9 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with reply or dismiss IDs.
   --require-sha <sha>             Wait for this full 40-character lowercase PR head SHA.
   --format text|json              Output format. Default: text.
@@ -121,7 +121,8 @@ Use --dry-run to preview paths without removing them.
     readonly "admin log-file": string;
     readonly resolve: `pr-shepherd resolve
 
-Apply GitHub review-state mutations after fixes.
+Deprecated compatibility alias for user-directed GitHub review-state mutations. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
@@ -131,11 +132,10 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
                                   Note: comment IDs (PRRC_*) from gh api are not thread IDs and will fail.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with --reply-thread-ids
                                   or --dismiss-review-ids.
   --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.

package/bin/cli/help-command-pages.mjs

@@ -17,7 +17,8 @@ Run 'pr-shepherd apply <review|files|journal> --help' for command-specific detai
 --help, -h                      Print this help and exit before GitHub I/O.`,
     "apply review": `pr-shepherd apply review
 
-Apply GitHub review-state mutations after fixes.
+Apply user-directed GitHub review-state mutations after fixes. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd apply review [PR] --reply-thread-ids A,B --message MSG
@@ -27,10 +28,9 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with reply or dismiss IDs.
   --require-sha <sha>             Wait for this full 40-character lowercase PR head SHA.
   --format text|json              Output format. Default: text.
@@ -124,7 +124,8 @@ Use --dry-run to preview paths without removing them.
     "admin log-file": LOG_FILE_USAGE.replaceAll("pr-shepherd log-file", "pr-shepherd admin log-file"),
     resolve: `pr-shepherd resolve
 
-Apply GitHub review-state mutations after fixes.
+Deprecated compatibility alias for user-directed GitHub review-state mutations. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
@@ -134,11 +135,10 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
                                   Note: comment IDs (PRRC_*) from gh api are not thread IDs and will fail.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with --reply-thread-ids
                                   or --dismiss-review-ids.
   --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.

package/bin/cli/help.d.mts

@@ -14,7 +14,8 @@ Run 'pr-shepherd apply <review|files|journal> --help' for command-specific detai
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply review": `pr-shepherd apply review
 
-Apply GitHub review-state mutations after fixes.
+Apply user-directed GitHub review-state mutations after fixes. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd apply review [PR] --reply-thread-ids A,B --message MSG
@@ -24,10 +25,9 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with reply or dismiss IDs.
   --require-sha <sha>             Wait for this full 40-character lowercase PR head SHA.
   --format text|json              Output format. Default: text.
@@ -121,7 +121,8 @@ Use --dry-run to preview paths without removing them.
     readonly "admin log-file": string;
     readonly resolve: `pr-shepherd resolve
 
-Apply GitHub review-state mutations after fixes.
+Deprecated compatibility alias for user-directed GitHub review-state mutations. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
@@ -131,11 +132,10 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
                                   Note: comment IDs (PRRC_*) from gh api are not thread IDs and will fail.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with --reply-thread-ids
                                   or --dismiss-review-ids.
   --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.

package/bin/cli/iterate-instructions.mjs

@@ -38,8 +38,15 @@ export function buildSimpleIterateInstructions(result) {
         }
         case "cancel":
             return ["Stop — the PR loop is complete. No further polling is needed."];
-        case "escalate":
-            return ["Stop — human direction is required before automated polling can resume."];
+        case "escalate": {
+            const pending = result.escalate.pendingReviewCommands;
+            if (!pending)
+                return ["Stop — human direction is required before automated polling can resume."];
+            return [
+                "Stop polling. Ask the user whether to run the pending review commands shown above.",
+                "If yes, replace any `$HEAD_SHA` with the full 40-character pushed PR-head SHA and any `$DISMISS_MESSAGE` with a one-sentence disposition, run every pending command, then rerun Shepherd with the same options.",
+            ];
+        }
     }
 }
 export function adaptIterateLog(log) {

package/bin/cli/iterate-lean.mjs

@@ -160,6 +160,14 @@ export function projectIterateLean(result, opts) {
                     ...(result.escalate.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.escalate.changesRequestedReviews,
                     }),
+                    ...(result.escalate.firstLookSummaries &&
+                        result.escalate.firstLookSummaries.length > 0 && {
+                        firstLookSummaries: result.escalate.firstLookSummaries,
+                    }),
+                    ...(result.escalate.editedSummaries &&
+                        result.escalate.editedSummaries.length > 0 && {
+                        editedSummaries: result.escalate.editedSummaries,
+                    }),
                     ...(result.escalate.checks &&
                         result.escalate.checks.length > 0 && {
                         checks: result.escalate.checks,
@@ -182,6 +190,9 @@ export function projectIterateLean(result, opts) {
                         result.escalate.authorization.length > 0 && {
                         authorization: result.escalate.authorization,
                     }),
+                    ...(result.escalate.pendingReviewCommands && {
+                        pendingReviewCommands: result.escalate.pendingReviewCommands,
+                    }),
                     suggestion: result.escalate.suggestion,
                     humanMessage: result.escalate.humanMessage,
                 },

package/bin/cli-parser.mjs

@@ -213,4 +213,7 @@ async function handleResolve(args, command = "apply review") {
     process.stdout.write(globalOpts.format === "json"
         ? `${JSON.stringify(result, null, 2)}\n`
         : `${formatMutateResult(result)}\n`);
+    if (result.errors.length > 0) {
+        process.exitCode = result.rateLimit ? EXIT.TEMPFAIL : EXIT.UNAVAILABLE;
+    }
 }

package/bin/commands/iterate/check-instructions.d.mts

@@ -26,15 +26,9 @@ export declare function buildRepeatedWorkflowBranchRecoveryInstructions(baseBran
  *
  * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
  *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
- * Marker-based self-reply routing is already reflected in the generated IDs. The instruction
- * below makes that behavior explicit so an authenticated viewer's unmarked human feedback is
- * not mistaken for an automated reply merely because the GitHub login matches.
- *
  * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
- * dismiss-ID retention and the first-look/annotation ID-exclusion rules. Those only matter
- * if the caller *edits* the printed command (removes an ID, or adds one back); the printed
- * command run unmodified is already correct for them. The pointer below is load-bearing:
- * without it, nothing in CLI output tells the agent that playbook exists.
+ * dismiss-ID retention. The pointer below is load-bearing: without it, nothing in CLI output
+ * tells the agent that playbook exists.
  */
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
 /** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */

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

@@ -43,23 +43,14 @@ export function buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasE
  *
  * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
  *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
- * Marker-based self-reply routing is already reflected in the generated IDs. The instruction
- * below makes that behavior explicit so an authenticated viewer's unmarked human feedback is
- * not mistaken for an automated reply merely because the GitHub login matches.
- *
  * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
- * dismiss-ID retention and the first-look/annotation ID-exclusion rules. Those only matter
- * if the caller *edits* the printed command (removes an ID, or adds one back); the printed
- * command run unmodified is already correct for them. The pointer below is load-bearing:
- * without it, nothing in CLI output tells the agent that playbook exists.
+ * dismiss-ID retention. The pointer below is load-bearing: without it, nothing in CLI output
+ * tells the agent that playbook exists.
  */
 export function buildResolveCommandInstruction(resolveCommand) {
     if (!resolveCommand.hasMutations)
         return [];
     const instructions = [];
-    if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
-        instructions.push("Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an established Shepherd reply; a marked thread that is still being resolved is emitted resolve-only, not for another reply.");
-    }
     if (resolveCommand.requiresHeadSha) {
         instructions.push("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.");
     }

package/bin/commands/iterate/escalate.mjs

@@ -1,5 +1,6 @@
 import { loadConfig } from "../../config/load.mjs";
 import { inlineCode } from "../../util/markdown.mjs";
+import { renderResolveCommand } from "./render.mjs";
 function renderEscalateAuthor(item) {
     return [`@${item.author}`, item.authorType, item.authorAssociation].filter(Boolean).join(" · ");
 }
@@ -121,6 +122,8 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
     const hasItems = escalate.unresolvedThreads.length > 0 ||
         escalate.changesRequestedReviews.length > 0 ||
         escalate.ambiguousComments.length > 0 ||
+        (escalate.firstLookSummaries?.length ?? 0) > 0 ||
+        (escalate.editedSummaries?.length ?? 0) > 0 ||
         (escalate.checks?.length ?? 0) > 0 ||
         (escalate.stalledChecks?.length ?? 0) > 0;
     if (hasItems) {
@@ -157,6 +160,20 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
                 lines.push(`  > ${bodyLine}`);
             lines.push("");
         }
+        for (const [heading, summaries] of [
+            ["Review summaries (first look)", escalate.firstLookSummaries ?? []],
+            ["Review summaries (edited since first look)", escalate.editedSummaries ?? []],
+        ]) {
+            if (summaries.length === 0)
+                continue;
+            lines.push(`### ${heading}`, "");
+            for (const summary of summaries) {
+                lines.push(`- review \`${summary.id}\` (${renderEscalateAuthor(summary)}):`, "");
+                for (const bodyLine of summary.body.split("\n"))
+                    lines.push(`  > ${bodyLine}`);
+                lines.push("");
+            }
+        }
         for (const c of escalate.ambiguousComments) {
             lines.push(`- comment \`${c.id}\` (${renderEscalateAuthor(c)}):`);
             lines.push("");
@@ -194,7 +211,17 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
         lines.push("## Fix attempts");
         lines.push("");
         for (const a of escalate.thrashHistory) {
-            lines.push(`- thread \`${a.threadId}\` attempted ${a.attempts} times`);
+            lines.push(`- thread \`${a.threadId}\` pending commands returned ${a.attempts} times`);
+        }
+    }
+    const pending = escalate.pendingReviewCommands;
+    if (pending?.resolveOnlyCommand?.hasMutations || pending?.resolveCommand?.hasMutations) {
+        lines.push("", "## Pending review commands", "");
+        if (pending.resolveOnlyCommand?.hasMutations) {
+            lines.push(`- resolve-only: \`${renderResolveCommand(pending.resolveOnlyCommand)}\``);
+        }
+        if (pending.resolveCommand?.hasMutations) {
+            lines.push(`- apply review: \`${renderResolveCommand(pending.resolveCommand)}\``);
         }
     }
     lines.push("");
@@ -227,7 +254,8 @@ export function buildEscalateSuggestion(triggers, detail) {
         return `Could not determine the PR's base branch${reason} — automated rebases are paused because branch safety is unclear. Run the rebase manually against the PR's real target branch.`;
     }
     if (triggers.includes("fix-thrash")) {
-        return "Same thread(s) reached the automated attempt limit — treat this as a manual handoff. Apply the fix by hand.";
+        const attempts = loadConfig().iterate.fixAttemptsPerThread;
+        return `The same thread(s) remain unresolved after their pending review commands were returned for ${attempts} FIX_CODE ticks. Automated iteration is paused for a manual decision.`;
     }
     if (triggers.includes("bot-cr-not-dismissed")) {
         const ids = detail ? ` (review IDs: ${detail})` : "";

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

@@ -33,7 +33,7 @@ function checkRequiresHumanFollowUp(check) {
         return !check.detailsUrl?.trim();
     return !check.logExcerpt?.trim();
 }
-function nextFixAttempts(stored, headSha, threads) {
+function nextFixAttempts(stored, threads, countAttempt) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};
     const threadBodyHashes = stored?.threadBodyHashes
         ? { ...stored.threadBodyHashes }
@@ -41,13 +41,32 @@ function nextFixAttempts(stored, headSha, threads) {
     for (const t of threads) {
         const bodyHash = hashBody(threadTranscriptBody(t));
         const previousHash = threadBodyHashes[t.id];
-        if (stored?.headSha === headSha && (previousHash === undefined || previousHash === bodyHash))
+        if (!countAttempt)
             continue;
         threadAttempts[t.id] = previousHash === bodyHash ? (threadAttempts[t.id] ?? 0) + 1 : 1;
         threadBodyHashes[t.id] = bodyHash;
     }
     return { threadAttempts, threadBodyHashes };
 }
+function previousFixAttempts(stored, threads) {
+    if (!stored?.threadBodyHashes)
+        return {};
+    const attempts = {};
+    for (const thread of threads) {
+        const bodyHash = hashBody(threadTranscriptBody(thread));
+        if (stored.threadBodyHashes[thread.id] === bodyHash) {
+            attempts[thread.id] = stored.threadAttempts[thread.id] ?? 0;
+        }
+    }
+    return attempts;
+}
+function pendingReviewCommands(resolveCommand, resolveOnlyCommand) {
+    const pending = {
+        ...(resolveOnlyCommand?.hasMutations && { resolveOnlyCommand }),
+        ...(resolveCommand.hasMutations && { resolveCommand }),
+    };
+    return Object.keys(pending).length > 0 ? pending : undefined;
+}
 export async function handleFixCode(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
@@ -70,7 +89,22 @@ export async function handleFixCode(ctx) {
     const retryableActionableThreads = mutationActionableThreads.filter((thread) => thread.path !== null && thread.line !== null);
     const protectedRuns = [];
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
-    const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, retryableActionableThreads);
+    const countFixCodeAttempt = opts.persistSeen !== false;
+    const priorThreadAttempts = previousFixAttempts(stored, retryableActionableThreads);
+    const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, retryableActionableThreads, countFixCodeAttempt);
+    const resolutionOnlyThreadsForWork = report.threads.resolutionOnly.filter((thread) => !skippedThreadIds.has(thread.id) &&
+        ((thread.path !== null && thread.line !== null) ||
+            threadHasAuthorizedMutation(thread, replyIdSet, resolveIdSet)));
+    const actionableChangesRequestedReviews = report.changesRequestedReviews.filter((review) => review.staleReview !== true ||
+        !isHumanAuthor(review) ||
+        isConfiguredBotAuthor(review, botUsernames));
+    const changesRequestedReviewsForWork = actionableChangesRequestedReviews.filter((review) => !unauthorizedDismissals.some((candidate) => candidate.id === review.id));
+    const buildReviewCommands = (checks) => buildResolveCommand(report.threads.actionable
+        .filter((thread) => mutationActionableThreads.some((candidate) => candidate.id === thread.id))
+        .map(toAgentThread), resolutionOnlyThreadsForWork, [
+        ...(report.comments.minimizeIds ?? report.comments.actionable.map((comment) => comment.id)),
+        ...reviewSummaryIds,
+    ], changesRequestedReviewsForWork, checks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads, resolveOtherHumanThreads);
     const botCrReviews = report.changesRequestedReviews.filter((r) => (!isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames)) &&
         report.viewerAuthorization?.viewerCanAdminister === true);
     const botCrStateKey = { owner: repoOwner, repo: repoName, pr: prNumber };
@@ -79,13 +113,16 @@ export async function handleFixCode(ctx) {
     const { next: nextBotCrState, staleIds: staleBotCrIds } = updateBotCrSeenState(previousBotCrState, botCrReviews, nowSeconds, stallTimeoutSeconds);
     await writeBotCrSeenState(botCrStateKey, nextBotCrState);
     if (staleBotCrIds.length > 0) {
-        const staleSet = new Set(staleBotCrIds);
-        const staleReviews = botCrReviews.filter((r) => staleSet.has(r.id));
+        const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(toAgentChecks(failingChecks));
+        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
         const escalateBase = {
             triggers: ["bot-cr-not-dismissed"],
             unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
             ambiguousComments: report.comments.actionable.map(toAgentComment),
-            changesRequestedReviews: staleReviews,
+            changesRequestedReviews: report.changesRequestedReviews,
+            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
+            ...(editedSummaries.length > 0 && { editedSummaries }),
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: buildEscalateSuggestion(["bot-cr-not-dismissed"], staleBotCrIds.join(", ")),
         };
         return {
@@ -99,14 +136,21 @@ export async function handleFixCode(ctx) {
             },
         };
     }
-    const escalateTriggers = checkEscalateTriggers(retryableActionableThreads, threadAttempts);
+    const escalateTriggers = countFixCodeAttempt
+        ? checkEscalateTriggers(retryableActionableThreads, priorThreadAttempts)
+        : { triggers: [], thrashHistory: undefined };
     if (escalateTriggers.triggers.length > 0) {
+        const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(toAgentChecks(failingChecks));
+        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
         const escalateBase = {
             triggers: escalateTriggers.triggers,
             unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
             ambiguousComments: report.comments.actionable.map(toAgentComment),
             changesRequestedReviews: report.changesRequestedReviews,
+            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
+            ...(editedSummaries.length > 0 && { editedSummaries }),
             thrashHistory: escalateTriggers.thrashHistory,
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: buildEscalateSuggestion(escalateTriggers.triggers),
         };
         return {
@@ -120,7 +164,6 @@ export async function handleFixCode(ctx) {
             },
         };
     }
-    await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
     // GitHub does not expose a per-run viewer capability for cancellation, so Shepherd never
     // issues or recommends a cancellation regardless of repository role. A rerun is different:
     // GitHub's Actions rerun API requires actions:write, which rides with WRITE+ repo access, so
@@ -163,14 +206,6 @@ export async function handleFixCode(ctx) {
         ...toAgentChecks(annotatedExtra).map((c) => ({ ...c, annotationOnly: true })),
     ];
     const { changesRequestedReviews } = report;
-    const actionableChangesRequestedReviews = changesRequestedReviews.filter((review) => review.staleReview !== true ||
-        !isHumanAuthor(review) ||
-        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) ||
-            threadHasAuthorizedMutation(thread, replyIdSet, resolveIdSet)));
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
     const { behindBaseHint } = loadConfig().iterate;
@@ -179,7 +214,6 @@ export async function handleFixCode(ctx) {
     // unnecessary cancellation.
     const inProgressRunIds = [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
-    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);
@@ -199,6 +233,8 @@ 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 { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
+        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
         const checkSuggestion = exhaustedAttempts.length > 0
             ? `GitHub reports a later workflow attempt (${exhaustedAttempts
                 .map((check) => `${check.runId ?? check.name}: attempt ${check.runAttempt}`)
@@ -209,7 +245,10 @@ export async function handleFixCode(ctx) {
             unresolvedThreads: [],
             ambiguousComments: [],
             changesRequestedReviews,
+            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
+            ...(editedSummaries.length > 0 && { editedSummaries }),
             checks: manualFollowUpChecks,
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: checkSuggestion,
         };
         return {
@@ -225,9 +264,7 @@ export async function handleFixCode(ctx) {
     }
     // Push access to the PR head branch is a usage precondition. Build review mutations for
     // conflict ticks normally so the caller can push and complete the same fix_code cycle.
-    const mutationActionableIds = new Set(mutationActionableThreads.map((thread) => thread.id));
-    const mutationAgentThreads = threads.filter((thread) => mutationActionableIds.has(thread.id));
-    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(mutationAgentThreads, resolutionOnlyThreadsForWork, allCommentIds, changesRequestedReviewsForWork, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads, resolveOtherHumanThreads);
+    const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
     // 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. Located resolution-only threads retain that guard;
@@ -241,11 +278,15 @@ export async function handleFixCode(ctx) {
         actionableComments.length > 0 ||
         locatedResolutionOnlyThreadsForWork.length > 0;
     if (baseLookup.isFallback && pushIsPlausible) {
+        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],
             unresolvedThreads: [...threads, ...resolutionOnlyThreads.map(toAgentThread)],
             ambiguousComments: actionableComments,
             changesRequestedReviews,
+            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
+            ...(editedSummaries.length > 0 && { editedSummaries }),
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: buildEscalateSuggestion(["base-branch-unknown"], baseLookup.failureReason),
         };
         return {
@@ -288,6 +329,7 @@ export async function handleFixCode(ctx) {
     };
     const result = await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds);
     if (result.action === "fix_code" && opts.persistSeen !== false) {
+        await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
         await Promise.allSettled(result.fix.checks.flatMap((ch) => (ch.annotations ?? []).map((a) => markSeen(stallKey, a.id, annotationMarkerBody(a)))));
     }
     return result;

package/bin/commands/iterate/render.mjs

@@ -69,7 +69,7 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
         instructions.push(`Apply every warranted review fix in ${filesRef}.`);
     }
     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("Review the threads under `## Review threads to resolve` before running the generated mutations.");
     }
     instructions.push(...buildFailingCheckInstructions(failingChecks), ...repeatedWorkflowBranchRecoveryInstructions);
     if (hasAnnotations) {

package/bin/commands/iterate/stall.mjs

@@ -1,8 +1,32 @@
+/* eslint-disable max-lines */
 import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
 import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
 import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationApprox, } from "./escalate.mjs";
 import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
+function pendingReviewCommandsFromResult(result) {
+    if (result.action !== "fix_code")
+        return undefined;
+    const pending = {
+        ...(result.fix.resolveOnlyCommand?.hasMutations && {
+            resolveOnlyCommand: result.fix.resolveOnlyCommand,
+        }),
+        ...(result.fix.resolveCommand.hasMutations && { resolveCommand: result.fix.resolveCommand }),
+    };
+    return Object.keys(pending).length > 0 ? pending : undefined;
+}
+function surfacedSummariesFromResult(result) {
+    if (result.action !== "fix_code")
+        return {};
+    return {
+        ...(result.fix.firstLookSummaries.length > 0 && {
+            firstLookSummaries: result.fix.firstLookSummaries,
+        }),
+        ...(result.fix.editedSummaries.length > 0 && {
+            editedSummaries: result.fix.editedSummaries,
+        }),
+    };
+}
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}:${f.runId ?? "no-run"}:${f.runAttempt ?? "unknown"}`),
@@ -44,13 +68,16 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
         action: prospectiveResult.action,
     });
     if (stalledChecks.length > 0) {
+        const pending = pendingReviewCommandsFromResult(prospectiveResult);
         const stalledDuration = formatDurationApprox(Math.max(...stalledChecks.map((c) => c.ageSeconds)));
         const escalateBase = {
             triggers: ["stall-timeout"],
             unresolvedThreads: [],
             ambiguousComments: [],
             changesRequestedReviews: [],
+            ...surfacedSummariesFromResult(prospectiveResult),
             stalledChecks,
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: buildEscalateSuggestion(["stall-timeout"], stalledDuration),
         };
         return {
@@ -76,11 +103,14 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
         }
         else if (ageSeconds >= stallTimeoutSeconds) {
             const stalledDuration = formatDurationApprox(ageSeconds);
+            const pending = pendingReviewCommandsFromResult(prospectiveResult);
             const escalateBase = {
                 triggers: ["stall-timeout"],
                 unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
                 ambiguousComments: report.comments.actionable.map(toAgentComment),
                 changesRequestedReviews: report.changesRequestedReviews,
+                ...surfacedSummariesFromResult(prospectiveResult),
+                ...(pending && { pendingReviewCommands: pending }),
                 suggestion: buildEscalateSuggestion(["stall-timeout"], stalledDuration),
             };
             return {

package/bin/commands/iterate/thread-mutation-routing.d.mts

@@ -1,8 +1,6 @@
 import { type NormalizedBotUsernames } from "../../comments/authors.mts";
-import { shouldResolveOtherHumanThread } from "../../comments/thread-resolve-policy.mts";
 import type { ResolveOtherHumanThreads } from "../../config/load.mts";
 import type { AgentThread, ReviewThread } from "../../types.mts";
-export { shouldResolveOtherHumanThread };
 export type RoutableThread = AgentThread | ReviewThread;
 export interface ThreadMutationRouting {
     replyThreadIds: string[];

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

@@ -1,7 +1,6 @@
 import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "../../comments/authors.mjs";
 import { threadEndedByShepherd } from "../../comments/marker.mjs";
 import { shouldResolveOtherHumanThread } from "../../comments/thread-resolve-policy.mjs";
-export { shouldResolveOtherHumanThread };
 function dedupeIds(ids) {
     return [...new Set(ids)];
 }
@@ -32,7 +31,7 @@ export function buildThreadMutationRouting(threads, botUsernames, ruleAutoResolv
         .filter((thread) => shouldPairResolve(thread, botUsernames, policy) && !threadEndedByShepherd(thread))
         .map((thread) => thread.id));
     const pairedResolveIdSet = new Set(pairedResolveThreadIds);
-    // Rule-matched threads bypass author routing; resolve-mutate retains the human-author guard.
+    // Rule-matched threads bypass the generated-command author routing.
     const standaloneResolveThreadIds = dedupeIds([
         ...threads
             .filter((thread) => shouldPairResolve(thread, botUsernames, policy) && threadEndedByShepherd(thread))

package/bin/commands/resolve-mutate.mjs

@@ -1,12 +1,9 @@
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { applyResolveOptions } from "../comments/resolve.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
-import { loadConfig } from "../config/load.mjs";
-import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, normalizeBotUsernames, } from "../comments/authors.mjs";
-import { shouldResolveOtherHumanThread } from "./iterate/thread-mutation-routing.mjs";
 import { markReplySeen } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
-import { addPrShepherdMarker, threadEndedByShepherd } from "../comments/marker.mjs";
+import { addPrShepherdMarker } from "../comments/marker.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 /** @deprecated Hidden implementation for `resolve`; use `apply review`. */
 export async function runResolveMutate(opts) {
@@ -15,73 +12,30 @@ export async function runResolveMutate(opts) {
     if (prNumber === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
-    const { data } = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews: true });
-    const config = loadConfig();
-    const botUsernames = normalizeBotUsernames(config.botUsernames);
-    const threadById = new Map(data.reviewThreads.map((t) => [t.id, t]));
-    const humanThreadIds = new Set(data.reviewThreads
-        .filter((t) => isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames))
-        .map((t) => t.id));
-    const humanCommentIds = new Set(data.comments
-        .filter((c) => isHumanAuthor(c) && !isConfiguredBotAuthor(c, botUsernames))
-        .map((c) => c.id));
-    const humanReviewIds = new Set([...data.reviewSummaries, ...data.approvedReviews, ...data.changesRequestedReviews]
-        .filter((r) => isHumanAuthor(r) && !isConfiguredBotAuthor(r, botUsernames))
-        .map((r) => r.id));
-    // Iterate uses viewer capability fields while deciding which commands to
-    // print. Once a caller explicitly runs apply, GitHub's mutation response is
-    // authoritative and this path must not second-guess that intent.
-    const requestedReplyIds = new Set(opts.replyThreadIds ?? []);
-    const policy = config.iterate?.resolveOtherHumanThreads ?? "none";
-    const allowedHumanResolveIds = new Set(data.reviewThreads
-        .filter((thread) => {
-        if (!humanThreadIds.has(thread.id))
-            return false;
-        const paired = requestedReplyIds.has(thread.id) || threadEndedByShepherd(thread);
-        if (!paired)
-            return false;
-        if (isViewerAuthoredHuman(thread, botUsernames))
-            return true;
-        return shouldResolveOtherHumanThread(thread, policy);
-    })
-        .map((thread) => thread.id));
-    const resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => !humanThreadIds.has(id) || allowedHumanResolveIds.has(id));
-    const skippedHumanResolves = (opts.resolveThreadIds ?? []).filter((id) => humanThreadIds.has(id) && !allowedHumanResolveIds.has(id));
-    const knownThreadIds = new Set(data.reviewThreads.map((thread) => thread.id));
-    const replyThreadIds = opts.replyThreadIds?.filter((id) => knownThreadIds.has(id));
-    const skippedNonHumanReplies = (opts.replyThreadIds ?? []).filter((id) => !knownThreadIds.has(id));
-    const minimizeCommentIds = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id));
-    const skippedHumanMinimizes = (opts.minimizeCommentIds ?? []).filter((id) => humanCommentIds.has(id) || humanReviewIds.has(id));
-    const dismissReviewIds = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && data.changesRequestedReviews.some((review) => review.id === id));
-    const skippedHumanDismissals = (opts.dismissReviewIds ?? []).filter((id) => humanReviewIds.has(id));
-    const skippedIneligibleDismissals = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && !dismissReviewIds.includes(id));
-    const hasMutation = resolveThreadIds.length > 0 ||
-        (replyThreadIds?.length ?? 0) > 0 ||
-        minimizeCommentIds.length > 0 ||
-        dismissReviewIds.length > 0;
+    // Fetch only to retain the pre-reply transcript for successful-reply seen
+    // markers. It never determines which user-supplied IDs are sent to GitHub.
+    let threadById;
+    if (opts.replyThreadIds?.length) {
+        try {
+            threadById = new Map((await fetchPrBatch(prNumber, repo, { paginateApprovedReviews: true })).data.reviewThreads.map((thread) => [thread.id, thread]));
+        }
+        catch {
+            // Seen-marker bookkeeping is best-effort. A failed read must not block
+            // the explicit mutation request; GitHub's mutation response is authoritative.
+        }
+    }
+    // Iterate capability-checks and routes its generated commands. Direct apply
+    // requests are user-directed: forward every supplied ID unchanged and let
+    // GitHub report whether each requested mutation is permitted or applicable.
     const result = await applyResolveOptions(prNumber, repo, {
-        resolveThreadIds,
-        replyThreadIds,
-        minimizeCommentIds,
-        dismissReviewIds,
+        resolveThreadIds: opts.resolveThreadIds,
+        replyThreadIds: opts.replyThreadIds,
+        minimizeCommentIds: opts.minimizeCommentIds,
+        dismissReviewIds: opts.dismissReviewIds,
         dismissMessage: opts.dismissMessage,
-        requireSha: hasMutation ? opts.requireSha : undefined,
+        requireSha: opts.requireSha,
     });
-    if (skippedHumanResolves.length > 0)
-        result.skippedHumanResolves = skippedHumanResolves;
-    if (skippedHumanMinimizes.length > 0)
-        result.skippedHumanMinimizes = skippedHumanMinimizes;
-    if (skippedHumanDismissals.length > 0)
-        result.skippedHumanDismissals = skippedHumanDismissals;
-    if (skippedNonHumanReplies.length > 0)
-        result.skippedNonHumanReplies = skippedNonHumanReplies;
-    if (skippedIneligibleDismissals.length > 0) {
-        result.skippedDismissals = [
-            ...(result.skippedDismissals ?? []),
-            ...skippedIneligibleDismissals,
-        ];
-    }
-    if (opts.dismissMessage) {
+    if (opts.dismissMessage && threadById) {
         const markedMessage = addPrShepherdMarker(opts.dismissMessage);
         await Promise.all(result.repliedThreads.map((id) => {
             const thread = threadById.get(id);

package/bin/comments/resolve.d.mts

@@ -7,10 +7,15 @@ export interface ResolveResult {
     minimizedComments: string[];
     dismissedReviews: string[];
     errors: string[];
+    /** @deprecated Direct apply forwards every supplied dismissal ID to GitHub. */
     skippedDismissals?: string[];
+    /** @deprecated Direct apply no longer applies author policy. */
     skippedHumanResolves?: string[];
+    /** @deprecated Direct apply no longer applies author policy. */
     skippedHumanMinimizes?: string[];
+    /** @deprecated Direct apply no longer applies author policy. */
     skippedHumanDismissals?: string[];
+    /** @deprecated Direct apply forwards every supplied reply ID to GitHub. */
     skippedNonHumanReplies?: string[];
     /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedReplies?: string[];

package/bin/comments/resolve.mjs

@@ -35,9 +35,6 @@ export async function applyResolveOptions(pr, repo, opts) {
     const replyThreadIds = dedupeIds(opts.replyThreadIds ?? []);
     const minimizeCommentIds = opts.minimizeCommentIds ?? [];
     const dismissReviewIds = dedupeIds(opts.dismissReviewIds ?? []);
-    const minimizeCommentIdSet = new Set(minimizeCommentIds);
-    const filteredDismissReviewIds = dismissReviewIds.filter((id) => !minimizeCommentIdSet.has(id));
-    const overlappingDismissIds = dismissReviewIds.filter((id) => minimizeCommentIdSet.has(id));
     const result = {
         repliedThreads: [],
         resolvedThreads: [],
@@ -45,13 +42,7 @@ export async function applyResolveOptions(pr, repo, opts) {
         dismissedReviews: [],
         errors: [],
     };
-    if (overlappingDismissIds.length > 0) {
-        result.skippedDismissals = [];
-        for (const id of overlappingDismissIds) {
-            result.skippedDismissals.push(id);
-        }
-    }
-    if ((filteredDismissReviewIds.length > 0 || replyThreadIds.length > 0) && !opts.dismissMessage) {
+    if ((dismissReviewIds.length > 0 || replyThreadIds.length > 0) && !opts.dismissMessage) {
         throw new Error("--message is required when replying to threads or dismissing reviews");
     }
     if (opts.requireSha) {
@@ -59,7 +50,7 @@ export async function applyResolveOptions(pr, repo, opts) {
         // before reviewers see the fix.
         await waitForSha(pr, repo, opts.requireSha);
     }
-    await bulkApply(replyThreadIds, resolveThreadIds, minimizeCommentIds, filteredDismissReviewIds, opts.dismissMessage ?? "", result);
+    await bulkApply(replyThreadIds, resolveThreadIds, minimizeCommentIds, dismissReviewIds, opts.dismissMessage ?? "", result);
     return result;
 }
 /** @deprecated Compatibility alias; use `autoResolveThreads`. */

package/bin/state/fix-attempts.d.mts

@@ -1,14 +1,13 @@
 /**
  * Persistent attempt counter for the iterate escalation guard.
  *
- * Tracks how many times each review thread has been dispatched to the fix_code
- * handler without being resolved. Counts are reset automatically when the HEAD
- * commit SHA changes (i.e. a new push landed).
+ * Tracks how many caller-visible times each review thread has been dispatched to
+ * the fix_code handler without being resolved. Body edits reset the count.
  *
  * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
  */
 export interface FixAttemptsState {
-    /** HEAD SHA at the time the counts were last written. Reset key. */
+    /** HEAD SHA at the time the counts were last written, retained for observability/compatibility. */
     headSha: string;
     /** Map from thread ID → number of fix_code dispatches that included this thread. */
     threadAttempts: Record<string, number>;

package/bin/state/fix-attempts.mjs

@@ -1,9 +1,8 @@
 /**
  * Persistent attempt counter for the iterate escalation guard.
  *
- * Tracks how many times each review thread has been dispatched to the fix_code
- * handler without being resolved. Counts are reset automatically when the HEAD
- * commit SHA changes (i.e. a new push landed).
+ * Tracks how many caller-visible times each review thread has been dispatched to
+ * the fix_code handler without being resolved. Body edits reset the count.
  *
  * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
  */

package/bin/types/escalate.d.mts

@@ -1,4 +1,5 @@
 import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
+import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus, StackStatus } from "./merge-requirements.mts";
 export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "check-follow-up-unavailable" | "authorization-required" | "bot-cr-not-dismissed" | "merge-queue-removed" | "stacked-pr";
@@ -19,6 +20,10 @@ export interface EscalateDetails {
     unresolvedThreads: AgentThread[];
     ambiguousComments: AgentComment[];
     changesRequestedReviews: Review[];
+    /** First-look review summaries that must be shown before any pending minimization. */
+    firstLookSummaries?: Review[];
+    /** Previously seen review summaries whose edited bodies must be shown again. */
+    editedSummaries?: Review[];
     /** Failing checks whose next step requires human attention. */
     checks?: AgentCheck[];
     stalledChecks?: AgentStalledCheck[];
@@ -26,6 +31,11 @@ export interface EscalateDetails {
         threadId: string;
         attempts: number;
     }>;
+    /** Review mutations generated for this tick, retained so an escalation cannot strand them. */
+    pendingReviewCommands?: {
+        resolveOnlyCommand?: ResolveCommand;
+        resolveCommand?: ResolveCommand;
+    };
     suggestion: string;
     humanMessage: string;
     mergeQueueRemoval?: MergeQueueRemovalStatus;

package/package.json

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

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

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

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

@@ -51,7 +51,7 @@ annotations, or CI log excerpts.
 - The command builds from the fetched PR head and accepts a clean local descendant only when the complete ordered patch stream passes `git apply --check`.
 - If the command refuses because a suggestion is unsafe or no longer applies, inspect the current source, the displayed replacement block, and reviewer intent before editing manually. Do not apply a stale numeric range blindly or retry unchanged input.
 - A returned patch was checked against the then-current worktree. If it later fails, re-inspect the worktree because it changed after validation.
-- Keep the generated thread IDs and flag placement unchanged. Viewer-authored human feedback may intentionally appear in both reply and resolve flags; unmarked other-human feedback remains reply-only. Marker-ended other-human feedback is already acknowledged and has no generated mutation.
+- Use the generated thread IDs and flag placement returned with the patch command.
 
 ### CI failure triage
 
@@ -77,16 +77,11 @@ 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. Location is not required for generated reply/resolve mutations; unauthorized threads without a path or line remain one-look skips.
+The CLI only includes IDs whose per-object GitHub viewer capability and semantic routing authorize the corresponding generated action. Generated commands are pre-populated; omission is not a prohibition. A separate, user-directed `apply review` request may supply any reply, resolve, minimize, or dismiss IDs; it forwards them without Shepherd author, capability, or current-state filtering, and GitHub's per-operation response is authoritative.
 
-- 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 authorized 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.
+- When `## Instructions` says to run a generated `apply review:` / `resolve-only:` command, run it even when no code change is warranted. An `[ESCALATE]` instruction may require user direction first. The command records the agent's disposition of the included review items; skipping it leaves authorized threads active and can eventually trigger `fix-thrash`.
 - Keep every existing `--dismiss-review-ids` ID the CLI already included. Each is a bot or non-human review that must be dismissed; omitting one leaves the PR in `CHANGES_REQUESTED`.
 
-### Review-mutation routing
-
-For threads under both `## Review threads` and `## Review threads to resolve`, evaluate every thread before running mutations. Keep unmarked bot/non-human and viewer-authored IDs in both `--reply-thread-ids` and `--resolve-thread-ids`, including when the feedback is advisory, already satisfied, or otherwise warrants no code change: the reply runs before the resolve. Unmarked other-human IDs use `--reply-thread-ids` only unless the CLI also put them in `--resolve-thread-ids`. When the latest comment begins `<!-- pr-shepherd -->`, it is an established Shepherd reply—not merely a same-account comment. A marked thread that is still being resolved is resolve-only for retry. Do not add IDs the CLI omitted, and do not move IDs between flags.
-
 ### Shepherd Journal
 
 Link threads and comments in a journal entry from their headings in the CLI output. Cite reviews by ID.