pr-shepherd 0.49.0 → 0.51.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.51.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
@@ -144,10 +144,15 @@ needs agent work, all rows are terminal, the bounded timeout expires, or `--unti
 a configured GraphQL quota-warning band. Check counts use the same ignored, protected-run,
 superseded-run, and event rules as singular iteration and include active merge-queue commit checks.
 Bounded review/check overflow remains visible without permanently forcing work, and clean rows use
-the configured ready-delay before becoming terminal. Each actionable row includes
-an exact single-PR `pollCommand`; run independent actionable rows, then invoke the aggregate selector again.
-Stack rows are ordered bottom-to-top. API and MCP aggregate calls perform one summary tick and leave
-recurrence to the caller.
+the configured ready-delay before becoming terminal. Explicit PR sets give each actionable row an
+exact single-PR `pollCommand`, so independent rows can proceed before the next aggregate poll.
+Stack rows are ordered bottom-to-top and follow the one ordered stack instruction block instead.
+The summary also checks that every open child was based on
+its direct parent's current head. A stale child/parent OID pair is actionable even when GitHub
+reports both PRs clean: without `--merge`, rebase the upstack branches from their parent and push
+them with the emitted `gh stack` commands; with `--merge`, finish the contiguous ready lower
+layers with the emitted `gh stack merge --squash` command, recheck, then repair the child. API and
+MCP aggregate calls perform one summary tick and leave recurrence to the caller.
 
 Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSeconds`, `timeoutSeconds`, `debounceSeconds`, and `quietStatus`. Explicit flags override configuration, including `--no-quiet-status` when a shared config enables quiet output. Quiet status remains off by default.
 
@@ -286,6 +291,8 @@ Environment variables:
 
 See [docs/configuration.md](docs/configuration.md) for the full reference.
 
+For guided noise reduction, use the plugin's `reduce-pr-noise` skill. It loads focused guidance for bot-comment classifiers or settings only when relevant; see [docs/skills.md](docs/skills.md).
+
 ### Classification rules
 
 Drop `.ts` / `.mts` / `.mjs` / `.js` files under `.pr-shepherd/classification/` to suppress and/or auto-resolve specific bot comments — useful for silencing repetitive noise like rate-limit notices from `gemini-code-assist` or "Reviews paused" from `coderabbitai`.

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/poll-summary-emitter.mjs

@@ -5,6 +5,21 @@ export function emitPollSummaryResult(result, opts) {
     process.exitCode = pollSummaryExitCode(result);
 }
 function pollSummaryExitCode(result) {
+    if (result.nextAction === "cancel" &&
+        result.prs.some((item) => item.reasons.includes("closed"))) {
+        return EXIT.CLOSED;
+    }
+    if (result.nextAction) {
+        const stackExitCode = {
+            escalate: EXIT.ESCALATE,
+            fix_code: EXIT.FIX_CODE,
+            merge: EXIT.MERGE,
+            mark_ready: EXIT.MARK_READY,
+            wait: EXIT.WAIT,
+            cancel: EXIT.OK,
+        };
+        return stackExitCode[result.nextAction] ?? EXIT.OK;
+    }
     const actions = new Set(result.prs.map((item) => item.action));
     if (actions.has("escalate"))
         return EXIT.ESCALATE;

package/bin/cli/poll-summary-formatter.mjs

@@ -1,5 +1,5 @@
 import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
-import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+import { withPollSummaryInstructions } from "../commands/poll-summary-instructions.mjs";
 export function formatPollSummaryResult(result) {
     const selection = result.selection.kind === "stack"
         ? `stack #${result.selection.stackNumber} anchored at PR #${result.selection.anchor} (${result.selection.stackSize} PRs)`
@@ -7,42 +7,28 @@ export function formatPollSummaryResult(result) {
     const lines = [
         `# Poll summary [${result.reason.toUpperCase()}]`,
         "",
-        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\``,
+        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
         "",
         "## Pull requests",
         "",
         ...result.prs.map(formatItem),
     ];
+    if (result.stackAncestry?.length) {
+        lines.push("", "## Stack ancestry", "");
+        for (const pair of result.stackAncestry) {
+            lines.push(`- PR #${pair.childPr} base \`${pair.childBaseRefName}\` at \`${pair.childBaseRefOid}\` differs from parent PR #${pair.parentPr} head \`${pair.parentHeadRefName}\` at \`${pair.parentHeadRefOid}\`.`);
+        }
+    }
     const apiUsage = result.apiUsage ? formatApiUsage(result.apiUsage) : null;
     const quotaWarning = formatQuotaWarning(result.quotaWarning);
     if (quotaWarning)
         lines.push("", quotaWarning);
     if (apiUsage)
         lines.push("", apiUsage);
-    lines.push("", "## Instructions", "", ...formatInstructions(result));
+    const instructions = result.instructions ?? withPollSummaryInstructions(result, false).instructions ?? [];
+    lines.push("", "## Instructions", "", ...instructions);
     return lines.join("\n");
 }
-function formatInstructions(result) {
-    if (result.reason === "all_terminal")
-        return ["1. Stop — every selected PR is terminal."];
-    if (result.quotaWarning && result.reason !== "actionable") {
-        return [
-            buildQuotaAwareContinuation(result.quotaWarning, "1. This aggregate selection is non-terminal. Before continuing,"),
-        ];
-    }
-    if (result.reason === "waiting" || result.reason === "timeout") {
-        return ["1. Run this aggregate selector again when the caller is ready to recheck."];
-    }
-    const instructions = [
-        "1. Choose each non-WAIT, non-CANCEL row that can proceed independently and run or delegate its exact `pollCommand`.",
-        "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
-        "3. Run this aggregate poll again after selected work completes; one row's `ESCALATE` does not stop work on other rows.",
-    ];
-    if (result.quotaWarning) {
-        instructions[2] = buildQuotaAwareContinuation(result.quotaWarning, "3. After selected work completes,");
-    }
-    return instructions;
-}
 function formatItem(item) {
     const flags = [item.isDraft ? "draft" : null, item.isInMergeQueue ? "queued" : null]
         .filter((value) => value !== null)

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})` : "";