pr-shepherd 0.35.0 → 0.37.0

package/bin/commands/check.mjs

@@ -7,7 +7,7 @@ import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
 import { computeStatus } from "./check-status.mjs";
-import { attachUnseenCheckAnnotations } from "./check-annotations.mjs";
+import { attachAndMergeCheckAnnotations } from "./check-annotations.mjs";
 import { buildTerminalReport } from "./check-terminal-report.mjs";
 import { isBlockedByFilteredCheck, refreshReadyMergeability, refreshUnknownMergeability, } from "./ready-mergeability.mjs";
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
@@ -38,7 +38,9 @@ export async function runCheck(opts) {
     if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
         return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
     }
-    const startupFailureChecks = await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
+    const startupFailureChecks = result.checkSuitesComplete
+        ? []
+        : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
     const classifiedChecks = classifyChecks(allChecks);
     const verdict = getCiVerdict(classifiedChecks);
@@ -47,6 +49,7 @@ export async function runCheck(opts) {
     const inProgress = classifiedChecks.filter((c) => c.category === "in_progress");
     const skipped = classifiedChecks.filter((c) => c.category === "skipped");
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
+    const ignored = classifiedChecks.filter((c) => c.category === "ignored");
     const triagedBase = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing, repo) : failing;
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const seenMap = await loadSeenMap(stateKey);
@@ -54,7 +57,8 @@ export async function runCheck(opts) {
     const ruleSet = await loadRules(discoverRuleFiles(getEffectiveCwd()));
     const classifyIndex = buildClassifyIndex(ruleSet, batchData);
     const partition = partitionBatch(classifyIndex, batchData);
-    const triaged = await attachUnseenCheckAnnotations(triagedBase, seenMap, prNumber);
+    const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered, ignored }, seenMap, prNumber);
+    const ignoredAnnotated = merged.ignored.filter((c) => (c.annotations?.length ?? 0) > 0);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized && !partition.suppressedCommentIds.has(c.id));
     const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
     const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id)), seenMap, botUsernames);
@@ -80,27 +84,29 @@ export async function runCheck(opts) {
     }
     const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
-    await Promise.allSettled([
-        ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
-        ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
-        ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
-        ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
-        ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
-        ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
-        ...batchData.comments
-            .filter((c) => partition.suppressedCommentIds.has(c.id))
-            .map((c) => markSeen(stateKey, c.id, c.body)),
-        ...batchData.reviewThreads
-            .filter((t) => partition.suppressedThreadIds.has(t.id))
-            .map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
-        ...batchData.reviewSummaries
-            .filter((r) => partition.suppressedReviewSummaryIds.has(r.id))
-            .map((r) => markSeen(stateKey, r.id, r.body)),
-        ...batchData.changesRequestedReviews
-            .filter((r) => partition.suppressedChangesRequestedIds.has(r.id))
-            .map((r) => markSeen(stateKey, r.id, r.body)),
-    ]);
-    await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
+    if (opts.persistSeen !== false) {
+        await Promise.allSettled([
+            ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
+            ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
+            ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
+            ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
+            ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+            ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+            ...batchData.comments
+                .filter((c) => partition.suppressedCommentIds.has(c.id))
+                .map((c) => markSeen(stateKey, c.id, c.body)),
+            ...batchData.reviewThreads
+                .filter((t) => partition.suppressedThreadIds.has(t.id))
+                .map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
+            ...batchData.reviewSummaries
+                .filter((r) => partition.suppressedReviewSummaryIds.has(r.id))
+                .map((r) => markSeen(stateKey, r.id, r.body)),
+            ...batchData.changesRequestedReviews
+                .filter((r) => partition.suppressedChangesRequestedIds.has(r.id))
+                .map((r) => markSeen(stateKey, r.id, r.body)),
+        ]);
+        await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
+    }
     const { threadIds: ruleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(partition, opts.autoMinimizeSuppressed);
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
     const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)).length;
@@ -121,11 +127,12 @@ export async function runCheck(opts) {
         baseBranch: batchData.baseRefName,
         mergeStatus,
         checks: {
-            passing,
-            failing: triaged,
+            passing: merged.passing,
+            failing: merged.failing,
             inProgress: inProgress,
-            skipped,
-            filtered,
+            skipped: merged.skipped,
+            filtered: merged.filtered,
+            ...(ignoredAnnotated.length > 0 && { ignored: ignoredAnnotated }),
             filteredNames: verdict.filteredNames,
             blockedByFilteredCheck,
             ...(verdict.ignoredNames.length > 0 && { ignoredNames: verdict.ignoredNames }),

package/bin/commands/commit-suggestion.mjs

@@ -1,9 +1,9 @@
 import { execFile as execFileCb } from "node:child_process";
 import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/client.mjs";
-import { fetchPrBatch } from "../github/batch.mjs";
+import { fetchSuggestionThread } from "../github/suggestion-thread.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
@@ -28,7 +28,7 @@ export async function runCommitSuggestion(opts) {
         cwd: getExecutionCwd(),
     });
     const localHeadSha = localHeadOut.trim();
-    const { data } = await fetchPrBatch(prNumber, repo);
+    const data = await fetchSuggestionThread(prNumber, repo, opts.threadId);
     if (!data.headRepoWithOwner) {
         throw new ShepherdError(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`, EXIT.UNAVAILABLE);
     }
@@ -40,7 +40,7 @@ export async function runCommitSuggestion(opts) {
         throw new ShepherdError(`Local HEAD ${localHeadSha} does not match PR head ${data.headRefOid}. ` +
             `Pull/rebase "${data.headRefName}" to the latest PR head and try again.`, EXIT.UNAVAILABLE);
     }
-    const thread = data.reviewThreads.find((t) => t.id === opts.threadId);
+    const thread = data.thread;
     if (!thread) {
         throw new ShepherdError(`Thread ${opts.threadId} not found on PR #${prNumber}.`, EXIT.UNAVAILABLE);
     }
@@ -73,7 +73,13 @@ export async function runCommitSuggestion(opts) {
     const startLine = thread.startLine ?? thread.line;
     const endLine = thread.line;
     const filePath = thread.path;
-    const originalContent = await readFile(resolve(getEffectiveCwd(), filePath), "utf8");
+    const cwd = getEffectiveCwd();
+    const resolvedPath = resolve(cwd, filePath);
+    const rel = relative(cwd, resolvedPath);
+    if (rel.startsWith("..") || rel === "") {
+        throw new ShepherdError(`Thread ${opts.threadId} path escapes the working tree.`, EXIT.UNAVAILABLE);
+    }
+    const originalContent = await readFile(resolvedPath, "utf8");
     const patch = buildUnifiedDiff({
         path: filePath,
         originalContent,

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

@@ -8,7 +8,7 @@ import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun, buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./helpers.mjs";
-import { annotationMarkerBody } from "../check-annotations.mjs";
+import { annotationMarkerBody, checksWithUnseenAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
 import { loadConfig } from "../../config/load.mjs";
@@ -30,6 +30,7 @@ function nextFixAttempts(stored, headSha, threads) {
 export async function handleFixCode(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
     const failingChecks = report.checks.failing;
+    const annotatedExtra = checksWithUnseenAnnotations(report).filter((c) => c.category !== "failing");
     const { protectedRunIds, protectedRuns } = buildRunProtection([...failingChecks, ...report.checks.inProgress], opts.neverCancelRuns);
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);
@@ -89,7 +90,11 @@ export async function handleFixCode(ctx) {
     const threads = report.threads.actionable.map(toAgentThread);
     const resolutionOnlyThreads = report.threads.resolutionOnly;
     const actionableComments = report.comments.actionable.map(toAgentComment);
-    const checks = toAgentChecks(failingChecks);
+    const failingAgentChecks = toAgentChecks(failingChecks);
+    const checks = [
+        ...failingAgentChecks,
+        ...toAgentChecks(annotatedExtra).map((c) => ({ ...c, annotationOnly: true })),
+    ];
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
@@ -98,7 +103,8 @@ export async function handleFixCode(ctx) {
     // summary-only iterations have no path to a push, so listing runs would prompt
     // unnecessary cancellation.
     const pushLikely = threads.length > 0 ||
-        checks.length > 0 ||
+        failingAgentChecks.length > 0 ||
+        annotatedExtra.length > 0 ||
         hasConflicts ||
         changesRequestedReviews.length > 0 ||
         actionableComments.length > 0;
@@ -110,13 +116,14 @@ export async function handleFixCode(ctx) {
         : [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, botUsernames, ruleAutoResolveThreadIds);
+    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, failingAgentChecks, prNumber, botUsernames, ruleAutoResolveThreadIds);
     // 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. Intentionally broader than `pushLikely` above:
     // resolution-only threads also need a known base in case the agent does push.
     const pushIsPlausible = threads.length > 0 ||
-        checks.length > 0 ||
+        failingAgentChecks.length > 0 ||
+        annotatedExtra.length > 0 ||
         hasConflicts ||
         changesRequestedReviews.length > 0 ||
         actionableComments.length > 0 ||
@@ -166,7 +173,7 @@ export async function handleFixCode(ctx) {
         cancelled,
     };
     const result = await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds);
-    if (result.action === "fix_code") {
+    if (result.action === "fix_code" && opts.persistSeen !== false) {
         await Promise.allSettled(result.fix.checks.flatMap((ch) => (ch.annotations ?? []).map((a) => markSeen(stallKey, a.id, annotationMarkerBody(a)))));
     }
     return result;

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

@@ -11,3 +11,4 @@ export declare function buildActiveChecks(report: ShepherdReport): ActiveCheck[]
 export declare function tryCancelRun(runId: string, owner: string, repo: string): Promise<string | null>;
 export declare function getCurrentHeadSha(): Promise<string | null>;
 export declare function buildWaitLog(base: IterateResultBase): string;
+export declare function blockedCancelNote(base: IterateResultBase): string;

package/bin/commands/iterate/helpers.mjs

@@ -2,6 +2,7 @@ import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { rest } from "../../github/http.mjs";
 import { getExecutionCwd } from "../../execution-context.mjs";
+import { blockedReasonFromRequirements } from "../../merge-status/requirements-format.mjs";
 const execFile = promisify(execFileCb);
 export { buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./reruns.mjs";
 export function buildSummary(report) {
@@ -40,6 +41,7 @@ export function buildTerminalCancelResult(report) {
         summary: buildSummary(report),
         baseBranch: report.baseBranch,
         branchProtection: report.branchProtection,
+        mergeRequirements: report.mergeStatus.mergeRequirements,
         checks: buildRelevantChecks(report),
         inProgressChecks: buildActiveChecks(report),
         ...buildSuppressedCheckFields(report),
@@ -134,14 +136,15 @@ export function buildWaitLog(base) {
             .join(", ")}`);
     }
     switch (base.mergeStatus) {
-        case "BLOCKED":
-            if (base.reviewDecision === "REVIEW_REQUIRED")
-                parts.push("awaiting human review");
-            else if (base.reviewDecision === "APPROVED")
-                parts.push("awaiting additional approvals");
-            else
+        case "BLOCKED": {
+            const fromRules = blockedReasonFromRequirements(base.mergeRequirements);
+            if (fromRules)
+                parts.push(fromRules);
+            else if (!base.blockingBotReviewInProgress) {
                 parts.push("awaiting human review or branch protection");
+            }
             break;
+        }
         case "BEHIND":
             parts.push("branch is behind base");
             break;
@@ -157,3 +160,9 @@ export function buildWaitLog(base) {
     }
     return parts.join(" — ");
 }
+export function blockedCancelNote(base) {
+    if (base.mergeStatus !== "BLOCKED")
+        return "has been ready for review";
+    const fromRules = blockedReasonFromRequirements(base.mergeRequirements);
+    return fromRules ? `is ${fromRules}` : "is awaiting human review or branch protection resolution";
+}

package/bin/commands/iterate/index.mjs

@@ -5,13 +5,14 @@ import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { EXIT, ShepherdError } from "../../exit-codes.mjs";
-import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, buildSuppressedCheckFields, buildTerminalCancelResult, } from "./helpers.mjs";
+import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, buildSuppressedCheckFields, buildTerminalCancelResult, blockedCancelNote, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleFixCode } from "./fix-code.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
+import { checksWithUnseenAnnotations } from "../check-annotations.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
@@ -69,6 +70,7 @@ export async function runIterate(opts) {
         report.comments.firstLook.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
         report.checks.failing.length > 0 ||
+        checksWithUnseenAnnotations(report).length > 0 ||
         report.mergeStatus.status === "CONFLICTS" ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
@@ -90,6 +92,7 @@ export async function runIterate(opts) {
         summary: buildSummary(report),
         baseBranch: report.baseBranch,
         branchProtection: report.branchProtection,
+        mergeRequirements: report.mergeStatus.mergeRequirements,
         checks: buildRelevantChecks(report),
         inProgressChecks: buildActiveChecks(report),
         ...buildSuppressedCheckFields(report),
@@ -97,15 +100,7 @@ export async function runIterate(opts) {
     };
     if (readyState.shouldCancel) {
         await clearStallState(stallKey);
-        let cancelNote;
-        if (base.mergeStatus !== "BLOCKED")
-            cancelNote = "has been ready for review";
-        else if (base.reviewDecision === "REVIEW_REQUIRED")
-            cancelNote = "is awaiting human review";
-        else if (base.reviewDecision === "APPROVED")
-            cancelNote = "is awaiting additional approvals";
-        else
-            cancelNote = "is awaiting human review or branch protection resolution";
+        const cancelNote = blockedCancelNote(base);
         return {
             ...base,
             action: "cancel",

package/bin/commands/iterate/render.mjs

@@ -1,6 +1,7 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
 import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildResolveCommandInstruction, } from "./check-instructions.mjs";
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
+import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 const FIX_INSTRUCTION_STOP = "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.";
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
@@ -13,8 +14,11 @@ export function renderResolveCommand(rc) {
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
 isBehind = false) {
     const instructions = [];
+    const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
+    const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
     const hasNonConflictHints = threads.length > 0 ||
-        checks.length > 0 ||
+        failingChecks.length > 0 ||
+        hasAnnotations ||
         changesRequestedReviews.length > 0 ||
         actionableComments.length > 0;
     // Leading decision or mandatory instruction depending on what actionable items exist.
@@ -24,9 +28,9 @@ isBehind = false) {
             actionableSections.push("`## Review threads`");
         if (actionableComments.length > 0)
             actionableSections.push("`## Actionable comments`");
-        if (checks.length > 0)
+        if (failingChecks.length > 0)
             actionableSections.push("`## Failing checks`");
-        if (checks.some((c) => (c.annotations?.length ?? 0) > 0)) {
+        if (hasAnnotations) {
             actionableSections.push("`## Check annotations`");
         }
         if (changesRequestedReviews.length > 0)
@@ -68,8 +72,8 @@ isBehind = false) {
     if (resolutionOnlyThreads.length > 0) {
         instructions.push(`Review the threads under \`## Review threads to resolve\`. Human-authored threads are replied to by the \`apply review:\` command shown below; Shepherd does not resolve them. Bot/non-human threads are included in \`--resolve-thread-ids\`.`);
     }
-    instructions.push(...buildFailingCheckInstructions(checks));
-    if (checks.some((c) => (c.annotations?.length ?? 0) > 0)) {
+    instructions.push(...buildFailingCheckInstructions(failingChecks));
+    if (hasAnnotations) {
         instructions.push(`For each item under \`## Check annotations\`: inspect the referenced file range and decide whether the annotation requires a code change. These annotations are surfaced once per PR and do not need any resolve/minimize mutation.`);
     }
     if (changesRequestedReviews.length > 0) {

package/bin/commands/iterate/stall.mjs

@@ -1,6 +1,7 @@
 import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
 import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
 import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationApprox, } from "./escalate.mjs";
+import { checksWithUnseenAnnotations } from "../check-annotations.mjs";
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
@@ -13,6 +14,9 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
     const reviews = report.changesRequestedReviews.map((r) => r.id).sort();
     const summaries = [...reviewSummaryIds].sort();
     const ruleAutoResolveSummaries = (report.ruleAutoResolveReviewSummaryIds ?? []).sort((a, b) => a.localeCompare(b));
+    const annotations = checksWithUnseenAnnotations(report)
+        .flatMap((c) => (c.annotations ?? []).map((a) => a.id))
+        .sort((a, b) => a.localeCompare(b));
     return JSON.stringify({
         action,
         headSha,
@@ -28,6 +32,7 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
         reviews,
         summaries,
         ruleAutoResolveSummaries,
+        annotations,
     });
 }
 export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds) {

package/bin/commands/poll.d.mts

@@ -2,6 +2,8 @@ import type { IterateCommandOptions, IterateResult } from "../types.mts";
 interface PollCommandOptions extends IterateCommandOptions {
     intervalSeconds: number;
     timeoutSeconds: number;
+    /** Settle window after first FIX_CODE before returning. Default 60. 0 disables. */
+    debounceSeconds?: number;
     quietStatus?: boolean;
     untilTerminal?: boolean;
 }

package/bin/commands/poll.mjs

@@ -1,5 +1,6 @@
 import { runIterate } from "./iterate/index.mjs";
 import { sleep } from "../util/sleep.mjs";
+const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
     if (verbose) {
         process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — sleeping ${sleepSeconds}s\n`);
@@ -54,11 +55,18 @@ function writeWaitProgress(opts) {
     }
     return signature;
 }
+function writeDebounceProgress(tick, elapsedMs, remainingMs) {
+    const elapsedSeconds = Math.round(elapsedMs / 1000);
+    const remainingSeconds = Math.round(remainingMs / 1000);
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
+}
 /** @deprecated Hidden implementation for the legacy `poll` alias. */
 export async function runPoll(opts) {
-    const { intervalSeconds, timeoutSeconds, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
+    const { intervalSeconds, timeoutSeconds, debounceSeconds: debounceSecondsOpt, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
     const intervalMs = Math.min(intervalSeconds * 1000, MAX_TIMER_MS);
     const timeoutMs = Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
+    const debounceSeconds = debounceSecondsOpt ?? DEFAULT_POLL_DEBOUNCE_SECONDS;
+    const debounceMs = Math.min(debounceSeconds * 1000, MAX_TIMER_MS);
     const start = Date.now();
     let tick = 0;
     let lastResult;
@@ -73,27 +81,30 @@ export async function runPoll(opts) {
     // terminal CANCEL/merged result. Pin the PR resolved by the first tick so later ticks target it
     // directly and never re-run branch discovery.
     let prNumber = opts.prNumber;
+    let debounceUntil = null;
     while (true) {
         tick += 1;
-        lastResult = await runIterate({ ...iterateOpts, prNumber });
+        const pastDebounce = debounceUntil !== null && Date.now() >= debounceUntil;
+        lastResult = await runIterate({
+            ...iterateOpts,
+            prNumber,
+            persistSeen: debounceSeconds === 0 || pastDebounce,
+        });
         prNumber ??= lastResult.pr;
-        if (lastResult.action !== "wait" && !(untilTerminal && lastResult.action === "mark_ready")) {
-            break;
-        }
-        const elapsedMs = Date.now() - start;
-        if (!untilTerminal) {
-            const remainingMs = timeoutMs - elapsedMs;
-            if (remainingMs <= 0)
-                break;
-            if (remainingMs + TIMER_DRIFT_TOLERANCE_MS < intervalMs)
-                break;
-        }
-        const nextSleepMs = intervalMs;
-        if (lastResult.action === "wait") {
+        if (lastResult.action === "wait" && !pastDebounce) {
+            debounceUntil = null;
+            const elapsedMs = Date.now() - start;
+            if (!untilTerminal) {
+                const remainingMs = timeoutMs - elapsedMs;
+                if (remainingMs <= 0)
+                    break;
+                if (remainingMs + TIMER_DRIFT_TOLERANCE_MS < intervalMs)
+                    break;
+            }
             lastWaitSignature = writeWaitProgress({
                 tick,
                 elapsedMs,
-                sleepMs: nextSleepMs,
+                sleepMs: intervalMs,
                 result: lastResult,
                 quietStatus,
                 verbose,
@@ -101,8 +112,31 @@ export async function runPoll(opts) {
             });
             if (!quietStatus && !verbose)
                 dotsPrinted = true;
+            await sleep(intervalMs);
+            continue;
+        }
+        if (untilTerminal && lastResult.action === "mark_ready" && !pastDebounce) {
+            debounceUntil = null;
+            await sleep(intervalMs);
+            continue;
+        }
+        if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
+            debounceUntil ??= Date.now() + debounceMs;
+            const remainingMs = debounceUntil - Date.now();
+            if (remainingMs > 0) {
+                if (dotsPrinted) {
+                    process.stderr.write("\n");
+                    dotsPrinted = false;
+                }
+                writeDebounceProgress(tick, Date.now() - start, remainingMs);
+                await sleep(Math.min(intervalMs, remainingMs));
+            }
+            // Always continue so a tick that *started* before debounceUntil but *finished*
+            // after it cannot return with persistSeen: false. The next loop iteration
+            // sees pastDebounce and persists.
+            continue;
         }
-        await sleep(nextSleepMs);
+        break;
     }
     if (dotsPrinted)
         process.stderr.write("\n");

package/bin/commands/ready-delay.mjs

@@ -6,9 +6,8 @@
  * `readyDelaySeconds` consecutively. Any not-READY result resets the timer.
  */
 import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
-import { join, dirname } from "node:path";
-import { SAFE_SEGMENT } from "../util/path-segment.mjs";
-import { resolveStateBase } from "../state/base.mjs";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "../state/base.mjs";
 /**
  * Update the ready-delay state machine and return the current decision.
  *
@@ -57,16 +56,7 @@ export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, own
 // Helpers
 // ---------------------------------------------------------------------------
 function readySincePath(pr, owner, repo) {
-    for (const [field, value] of [
-        ["owner", owner],
-        ["repo", repo],
-    ]) {
-        if (!SAFE_SEGMENT.test(value)) {
-            throw new Error(`Invalid path segment "${field}": ${value}`);
-        }
-    }
-    const base = resolveStateBase();
-    return join(base, `${owner}-${repo}`, String(pr), "ready-since.txt");
+    return resolvePrStatePath({ owner, repo, pr }, "ready-since.txt");
 }
 async function safeUnlink(path) {
     try {