pr-shepherd 0.48.0 → 0.50.0

package/bin/cli/poll-handler.mjs

@@ -6,8 +6,21 @@ import { validateSecondsDurationFlag } from "./duration-flag.mjs";
 import { parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
 import { EXIT } from "../exit-codes.mjs";
+import { runAggregatePoll } from "../commands/poll-summary.mjs";
+import { emitPollSummaryResult } from "./poll-summary-emitter.mjs";
+import { parsePollTargets, resolvePollTargets } from "./poll-targets.mjs";
 export async function handlePoll(args) {
-    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const parsedTargets = parsePollTargets(args);
+    if (!parsedTargets)
+        return;
+    const needsResolution = parsedTargets.stack !== undefined || parsedTargets.refs.length > 1;
+    const resolvedTargets = needsResolution
+        ? await resolvePollTargets(parsedTargets)
+        : { prNumbers: [] };
+    const isAggregate = resolvedTargets.stackPrNumber !== undefined || resolvedTargets.prNumbers.length > 1;
+    const { prNumber, global: commonGlobalOpts, extra: commonExtra } = parseCommonArgs(args);
+    const globalOpts = isAggregate ? parsedTargets.global : commonGlobalOpts;
+    const extra = isAggregate ? parsedTargets.extra : commonExtra;
     const cfg = loadConfig();
     const flags = parseIterateFlags(extra, cfg);
     if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
@@ -37,9 +50,8 @@ export async function handlePoll(args) {
         return;
     }
     const quietStatus = quietStatusFlag || (!noQuietStatusFlag && cfg.poll.quietStatus);
-    const result = await runPoll({
+    const shared = {
         ...globalOpts,
-        prNumber,
         readyDelaySeconds: flags.readyDelaySeconds,
         stallTimeoutSeconds: flags.stallTimeoutSeconds,
         noAutoMarkReady: flags.noAutoMarkReady,
@@ -50,7 +62,16 @@ export async function handlePoll(args) {
         debounceSeconds,
         quietStatus,
         untilTerminal: hasFlag(extra, "--until-terminal"),
-    });
+    };
+    if (isAggregate) {
+        const result = await runAggregatePoll({
+            ...shared,
+            ...resolvedTargets,
+        });
+        emitPollSummaryResult(result, { format: globalOpts.format });
+        return;
+    }
+    const result = await runPoll({ ...shared, prNumber });
     emitIterateResult(result, {
         format: globalOpts.format,
         verbose: globalOpts.verbose ?? false,

package/bin/cli/poll-summary-emitter.d.mts

@@ -0,0 +1,4 @@
+import type { PollSummaryResult } from "../types.mts";
+export declare function emitPollSummaryResult(result: PollSummaryResult, opts: {
+    format: "text" | "json";
+}): void;

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

@@ -0,0 +1,22 @@
+import { EXIT } from "../exit-codes.mjs";
+import { formatPollSummaryResult } from "./poll-summary-formatter.mjs";
+export function emitPollSummaryResult(result, opts) {
+    process.stdout.write(opts.format === "json" ? `${JSON.stringify(result)}\n` : `${formatPollSummaryResult(result)}\n`);
+    process.exitCode = pollSummaryExitCode(result);
+}
+function pollSummaryExitCode(result) {
+    const actions = new Set(result.prs.map((item) => item.action));
+    if (actions.has("escalate"))
+        return EXIT.ESCALATE;
+    if (actions.has("fix_code"))
+        return EXIT.FIX_CODE;
+    if (actions.has("merge"))
+        return EXIT.MERGE;
+    if (actions.has("mark_ready"))
+        return EXIT.MARK_READY;
+    if (actions.has("wait"))
+        return EXIT.WAIT;
+    if (result.prs.some((item) => item.reasons.includes("closed")))
+        return EXIT.CLOSED;
+    return EXIT.OK;
+}

package/bin/cli/poll-summary-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { PollSummaryResult } from "../types.mts";
+export declare function formatPollSummaryResult(result: PollSummaryResult): string;

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

@@ -0,0 +1,96 @@
+import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
+import { buildQuotaAwareContinuation } from "../quota-warning.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)`
+        : `PRs ${result.selection.requested.map((pr) => `#${pr}`).join(", ")}`;
+    const lines = [
+        `# Poll summary [${result.reason.toUpperCase()}]`,
+        "",
+        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\``,
+        "",
+        "## Pull requests",
+        "",
+        ...result.prs.map(formatItem),
+    ];
+    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));
+    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)
+        .join(", ");
+    const stack = item.stack
+        ? ` · stack \`${item.stack.number}\` position \`${item.stack.position}/${item.stack.size}\` base \`${item.stack.baseRefName}\``
+        : "";
+    const reviewDecision = item.reviewDecision ? ` · reviewDecision \`${item.reviewDecision}\`` : "";
+    const stateFlags = flags ? ` · flags \`${flags}\`` : "";
+    const blockingReviewer = item.blockingReviewerInProgress
+        ? " · blocking reviewer `in progress`"
+        : "";
+    const readyDelay = item.remainingSeconds !== undefined ? ` · ready delay \`${item.remainingSeconds}s\`` : "";
+    const checks = item.checks;
+    const review = item.review;
+    return [
+        `- [PR #${item.pr}: ${escapeMarkdownText(item.title)}](${item.url}) [${item.action.toUpperCase()}]`,
+        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${stack}`,
+        `  - head \`${item.headRefName}\` at \`${item.headRefOid}\` · base \`${item.baseRefName}\``,
+        ...(checks
+            ? [`  - checks: ${formatCounts(checks, checks.incomplete ? ", incomplete" : "")}`]
+            : []),
+        ...(review
+            ? [`  - review: ${formatCounts(review, review.incomplete ? ", incomplete" : "")}`]
+            : []),
+        `  - reasons: ${item.reasons.map((reason) => `\`${reason}\``).join(", ")}`,
+        ...(item.pollCommand ? [`  - pollCommand: \`${item.pollCommand}\``] : []),
+    ].join("\n");
+}
+function formatCounts(counts, suffix) {
+    const plural = { inProgress: "in progress" };
+    const singular = {
+        comments: "comment",
+        inProgress: "in progress",
+        reviews: "review",
+        threads: "thread",
+    };
+    const rendered = Object.entries(counts)
+        .filter(([, count]) => typeof count === "number")
+        .map(([name, count]) => `${count} ${count === 1 ? (singular[name] ?? name) : (plural[name] ?? name)}`)
+        .join(", ");
+    return rendered ? `${rendered}${suffix}` : suffix.replace(/^, /, "");
+}
+function escapeMarkdownText(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/[\r\n]+/g, " ")
+        .replace(/([\\[\]])/g, "\\$1");
+}

package/bin/cli/poll-targets.d.mts

@@ -0,0 +1,15 @@
+import { type RepoInfo } from "../github/client.mts";
+import { type ParsedPrReference } from "../pr-reference.mts";
+import type { GlobalOptions } from "../types.mts";
+export interface ParsedPollTargets {
+    refs: ParsedPrReference[];
+    stack: ParsedPrReference | undefined;
+    global: GlobalOptions;
+    extra: string[];
+}
+export declare function parsePollTargets(args: string[]): ParsedPollTargets | null;
+export declare function resolvePollTargets(parsed: ParsedPollTargets): Promise<{
+    prNumbers: number[];
+    stackPrNumber?: number;
+    targetRepository?: RepoInfo;
+}>;

package/bin/cli/poll-targets.mjs

@@ -0,0 +1,114 @@
+import { parseArgs } from "node:util";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { getRepoInfo } from "../github/client.mjs";
+import { parseCliPrReference, normalizeRepositoryIdentity, resolveParsedPrTarget, } from "../pr-reference.mjs";
+const VALUE_FLAGS = new Set([
+    "--format",
+    "--ready-delay",
+    "--stall-timeout",
+    "--interval",
+    "--timeout",
+    "--debounce",
+    "--stack",
+]);
+export function parsePollTargets(args) {
+    const { values } = parseArgs({
+        args,
+        strict: false,
+        allowPositionals: true,
+        options: { format: { type: "string" }, verbose: { type: "boolean" } },
+    });
+    const consumed = new Set();
+    const refs = [];
+    let stack;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (VALUE_FLAGS.has(arg)) {
+            if (arg === "--format" || arg === "--stack") {
+                consumed.add(index);
+                if (index + 1 < args.length)
+                    consumed.add(index + 1);
+            }
+            if (arg === "--stack") {
+                const parsed = parseCliPrReference(args[index + 1] ?? "");
+                if (!parsed)
+                    return usage(`invalid --stack PR reference: ${args[index + 1] ?? "(missing)"}`);
+                if (stack)
+                    return usage("--stack may only be specified once");
+                stack = parsed;
+            }
+            index += 1;
+            continue;
+        }
+        const equals = arg.indexOf("=");
+        const name = equals < 0 ? arg : arg.slice(0, equals);
+        if (VALUE_FLAGS.has(name)) {
+            if (name === "--format" || name === "--stack")
+                consumed.add(index);
+            if (name === "--stack") {
+                const parsed = parseCliPrReference(arg.slice(equals + 1));
+                if (!parsed)
+                    return usage(`invalid --stack PR reference: ${arg.slice(equals + 1)}`);
+                if (stack)
+                    return usage("--stack may only be specified once");
+                stack = parsed;
+            }
+            continue;
+        }
+        if (arg === "--verbose") {
+            consumed.add(index);
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        const parsed = parseCliPrReference(arg);
+        if (!parsed)
+            continue;
+        refs.push(parsed);
+        consumed.add(index);
+    }
+    if (stack && refs.length > 0)
+        return usage("--stack cannot be combined with explicit PRs");
+    const format = (values.format ?? "text");
+    return {
+        refs,
+        stack,
+        global: { format, verbose: values.verbose === true },
+        extra: args.filter((_, index) => !consumed.has(index)),
+    };
+}
+export async function resolvePollTargets(parsed) {
+    const all = parsed.stack ? [parsed.stack] : parsed.refs;
+    if (all.length === 0)
+        return { prNumbers: [] };
+    const checkoutRepo = all.some((ref) => ref.repository === undefined)
+        ? await getRepoInfo()
+        : undefined;
+    let selectedRepo;
+    const prNumbers = [];
+    for (const ref of all) {
+        const target = resolveParsedPrTarget(ref);
+        if (target.prNumber === undefined)
+            return usageThrow("PR number is required");
+        const repo = target.targetRepository ?? checkoutRepo;
+        if (selectedRepo &&
+            normalizeRepositoryIdentity(`${selectedRepo.owner}/${selectedRepo.name}`) !==
+                normalizeRepositoryIdentity(`${repo.owner}/${repo.name}`)) {
+            return usageThrow("aggregate poll only supports PRs from one repository");
+        }
+        selectedRepo = repo;
+        if (!prNumbers.includes(target.prNumber))
+            prNumbers.push(target.prNumber);
+    }
+    return parsed.stack
+        ? { prNumbers: [], stackPrNumber: prNumbers[0], targetRepository: selectedRepo }
+        : { prNumbers, targetRepository: selectedRepo };
+}
+function usage(message) {
+    process.stderr.write(`pr-shepherd: ${message}\n`);
+    process.exitCode = EXIT.USAGE;
+    return null;
+}
+function usageThrow(message) {
+    throw new ShepherdError(message, EXIT.USAGE);
+}

package/bin/cli/validate-default-args.mjs

@@ -5,7 +5,6 @@ import { parsePrNumber } from "./args.mjs";
  * offending arg so callers can print their own usage message.
  */
 export function validateDefaultArgs(args, flagsWithValues, booleanFlags, onError) {
-    let sawPr = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (flagsWithValues.has(arg)) {
@@ -21,10 +20,8 @@ export function validateDefaultArgs(args, flagsWithValues, booleanFlags, onError
             continue;
         if (booleanFlags.has(arg))
             continue;
-        if (parsePrNumber(arg) !== null && !sawPr) {
-            sawPr = true;
+        if (parsePrNumber(arg) !== null)
             continue;
-        }
         onError(arg);
         return false;
     }

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;