pr-shepherd 1.0.0 → 1.1.1

package/bin/commands/poll-summary.mjs

@@ -4,6 +4,7 @@ import { ShepherdError } from "../exit-codes.mjs";
 import { getRepoInfo } from "../github/client.mjs";
 import { getGithubTransport } from "../github/transport.mjs";
 import { withApiTelemetryScope, summarizeApiTelemetry } from "../github/api-telemetry.mjs";
+import { aggregateRerunCommand } from "../github/poll-summary-command.mjs";
 import { fetchPollSummary } from "../github/poll-summary.mjs";
 import { writeStackHandoffs } from "../github/stack-handoff.mjs";
 import { sleep } from "../util/sleep.mjs";
@@ -19,7 +20,7 @@ export function runPollSummary(opts) {
     return withApiTelemetryScope(async () => {
         const tick = await readPollSummaryTick(opts);
         await handOffRoutedLayers(tick);
-        return attachUsage(tick.result, opts.merge);
+        return attachUsage(tick.result, opts);
     });
 }
 export function runAggregatePoll(opts) {
@@ -60,7 +61,7 @@ async function readPollSummaryTick(opts) {
         prs: fetched.prs,
         ...(fetched.stackAncestry?.length && { stackAncestry: fetched.stackAncestry }),
         ...(fetched.allowedMergeMethods && { allowedMergeMethods: fetched.allowedMergeMethods }),
-    }, opts.merge === true);
+    }, opts.merge === true, aggregateRerunCommand(`${repo.owner}/${repo.name}`, fetched.selection, opts));
     const result = await applyStackStallGuard(planned, repo, opts.stallTimeoutSeconds ?? loadConfig().iterate["stall-timeout-minutes"] * 60);
     return { result, repo, ...(fetched.handoffSource && { handoffSource: fetched.handoffSource }) };
 }
@@ -82,6 +83,7 @@ async function runAggregatePollCore(opts) {
         try {
             lastTick = await readPollSummaryTick(opts);
             last = lastTick.result;
+            writeAggregateRuleAutoResolve(last);
             rateLimitRetry.reset();
         }
         catch (error) {
@@ -103,7 +105,7 @@ async function runAggregatePollCore(opts) {
                         stackMergeable: true,
                         instructions: ["1. Stop — every stack layer is merged."],
                         ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                    }, opts.merge);
+                    }, opts);
                 }
                 return attachUsage({
                     ...explicit,
@@ -115,7 +117,7 @@ async function runAggregatePollCore(opts) {
                         `1. Native stack #${last.selection.stackNumber} disappeared before every tracked layer merged. Stop and ask the stack owner to reconcile the remaining PRs; do not claim the stack is complete.`,
                     ],
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                }, opts.merge);
+                }, opts);
             }
             const early = await rateLimitRetry.wait(error, {
                 untilTerminal: opts.untilTerminal === true,
@@ -126,7 +128,7 @@ async function runAggregatePollCore(opts) {
                 onAllTerminal: (pulls) => aggregateCancelFromPulls(last, opts.targetRepository, pulls),
             });
             if (early) {
-                return presentProbedCancel(pendingQuotaWarning ? { ...early, quotaWarning: pendingQuotaWarning } : early, opts.merge);
+                return presentProbedCancel(pendingQuotaWarning ? { ...early, quotaWarning: pendingQuotaWarning } : early, opts);
             }
             continue;
         }
@@ -147,14 +149,14 @@ async function runAggregatePollCore(opts) {
                 ...last,
                 reason: "all_terminal",
                 ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-            }, opts.merge);
+            }, opts);
         }
         if (immediate) {
             return attachUsage({
                 ...last,
                 reason: "actionable",
                 ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-            }, opts.merge);
+            }, opts);
         }
         if (hasFix) {
             if (debounceMs === 0 || Date.now() >= (debounceUntil ??= Date.now() + debounceMs)) {
@@ -163,13 +165,13 @@ async function runAggregatePollCore(opts) {
                     ...last,
                     reason: "actionable",
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                }, opts.merge);
+                }, opts);
             }
         }
         else {
             debounceUntil = null;
             if (opts.untilTerminal && pendingQuotaWarning) {
-                return attachUsage({ ...last, quotaWarning: pendingQuotaWarning }, opts.merge);
+                return attachUsage({ ...last, quotaWarning: pendingQuotaWarning }, opts);
             }
         }
         const elapsedMs = Date.now() - start;
@@ -179,7 +181,7 @@ async function runAggregatePollCore(opts) {
         if (!opts.untilTerminal && debounceUntil === null) {
             const remainingMs = timeoutMs - elapsedMs;
             if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
-                return attachUsage({ ...last, reason: "timeout" }, opts.merge);
+                return attachUsage({ ...last, reason: "timeout" }, opts);
             }
         }
         const statusSignature = summaryStatusSignature(last);
@@ -192,15 +194,21 @@ async function runAggregatePollCore(opts) {
         await sleep(sleepMs);
     }
 }
-function presentProbedCancel(result, merge) {
+/** An auto-resolve is a one-tick event; forward it so a swallowed tick still records it. */
+function writeAggregateRuleAutoResolve(result) {
+    for (const item of result.prs)
+        if (item.ruleAutoResolve?.summary)
+            process.stderr.write(`#${item.pr} ${item.ruleAutoResolve.summary}\n`);
+}
+function presentProbedCancel(result, opts) {
     // The stack planner already cancels an all-merged stack and escalates a
     // closed-unmerged layer. Do not rewrite that into a successful stop.
-    return attachUsage({ ...result, reason: "all_terminal" }, merge);
+    return attachUsage({ ...result, reason: "all_terminal" }, opts);
 }
 function isMissingStack(error) {
     return (error instanceof ShepherdError && error.message.includes("not part of a native GitHub stack"));
 }
-function attachUsage(result, mergeRequested) {
+function attachUsage(result, opts) {
     const apiUsage = summarizeApiTelemetry();
     const enriched = apiUsage ? { ...result, apiUsage } : result;
     // A disappeared native stack is an aggregate-level terminal handoff. Keep
@@ -209,5 +217,5 @@ function attachUsage(result, mergeRequested) {
     if (enriched.selection.kind === "stack" && enriched.nextAction === "escalate") {
         return enriched;
     }
-    return withPollSummaryInstructions(enriched, mergeRequested === true);
+    return withPollSummaryInstructions(enriched, opts.merge === true, aggregateRerunCommand(enriched.repo, enriched.selection, opts));
 }

package/bin/commands/ready-delay.d.mts

@@ -30,6 +30,7 @@ interface ReadyDelayState {
 export declare function updateReadyDelay(prNumber: number, isReady: boolean, readyDelaySeconds: number, owner: string, repo: string, options: {
     headSha: string;
     alreadyElapsed?: boolean;
+    summary?: boolean;
 }): Promise<ReadyDelayState>;
 /** Delete the ready-delay marker once an elapsed delay has been consumed. */
 export declare function clearReadyDelay(prNumber: number, owner: string, repo: string): Promise<void>;

package/bin/commands/ready-delay.mjs

@@ -21,7 +21,7 @@ import { resolvePrStatePath } from "../state/base.mjs";
  * the loop and tells one-shot agents to stop.
  */
 export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, owner, repo, options) {
-    const markerPath = readySincePath(prNumber, owner, repo);
+    const markerPath = readySincePath(prNumber, owner, repo, options.summary);
     if (!isReady) {
         // Reset the timer.
         await safeUnlink(markerPath);
@@ -75,8 +75,13 @@ export async function readyDelayElapsed(prNumber, owner, repo, readyDelaySeconds
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-function readySincePath(pr, owner, repo) {
-    return resolvePrStatePath({ owner, repo, pr }, "ready-since.txt");
+/**
+ * The one-PR session owns `ready-since.txt`. The aggregate summary's coarser
+ * view keeps its own `ready-since-summary.txt` so it can never reset or start
+ * the authoritative timer.
+ */
+function readySincePath(pr, owner, repo, summary = false) {
+    return resolvePrStatePath({ owner, repo, pr }, summary ? "ready-since-summary.txt" : "ready-since.txt");
 }
 /** The marker's start time, or null when it is missing, malformed, or bound to another head. */
 async function readReadySince(path, headSha) {

package/bin/commands/ready-mergeability.d.mts

@@ -10,6 +10,6 @@ export declare function refreshUnknownMergeability(prNumber: number, repo: RepoI
     batchData: BatchPrData;
     didRefresh: boolean;
 }>;
-export declare function refreshReadyMergeability(prNumber: number, repo: RepoInfo, batchData: BatchPrData, verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, changesRequestedCount: number, hasUnreportedRequired?: boolean): Promise<ReadyMergeabilityRefresh>;
+export declare function refreshReadyMergeability(prNumber: number, repo: RepoInfo, batchData: BatchPrData, verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, changesRequestedCount: number, awaitingChecks?: boolean): Promise<ReadyMergeabilityRefresh>;
 export declare function isBlockedByFilteredCheck(mergeStatus: MergeStatusResult, verdict: CiVerdict): boolean;
 export {};

package/bin/commands/ready-mergeability.mjs

@@ -8,10 +8,10 @@ export async function refreshUnknownMergeability(prNumber, repo, batchData) {
     }
     return { batchData: await readMergeability(prNumber, repo, batchData), didRefresh: true };
 }
-export async function refreshReadyMergeability(prNumber, repo, batchData, verdict, unresolvedThreads, unresolvedComments, changesRequestedCount, hasUnreportedRequired = false) {
+export async function refreshReadyMergeability(prNumber, repo, batchData, verdict, unresolvedThreads, unresolvedComments, changesRequestedCount, awaitingChecks = false) {
     const refreshedBatchData = await readMergeability(prNumber, repo, batchData);
     const mergeStatus = deriveMergeStatus(refreshedBatchData);
-    const status = computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedCount, hasUnreportedRequired);
+    const status = computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedCount, awaitingChecks);
     return { batchData: refreshedBatchData, mergeStatus, status };
 }
 export function isBlockedByFilteredCheck(mergeStatus, verdict) {

package/bin/commands/rule-auto-resolve-format.d.mts

@@ -3,6 +3,13 @@ export declare function uniqueReasons(reasons: readonly string[]): string[];
 export declare function decorateAutoResolveError(error: string, reasons: readonly string[]): string;
 export declare function reasonsForError(error: string, ids: readonly string[], ruleReasons: ReadonlyMap<string, readonly string[]>): string[];
 export declare function ruleAutoResolveFromReport(report: ShepherdReport): RuleAutoResolveReport | undefined;
+/** The one report shape iterate and the aggregate summary both surface. */
+export declare function buildRuleAutoResolveReport(input: {
+    threads: AutoResolvedThread[];
+    minimized: AutoMinimizedItem[];
+    errors: string[];
+    errorReasons: string[];
+}): RuleAutoResolveReport | undefined;
 export declare function projectRuleAutoResolve(event: RuleAutoResolveReport): Record<string, unknown>;
 export declare function insertRuleAutoResolveSection(text: string, event: RuleAutoResolveReport | undefined): string;
 export declare function stripReplayedRuleAutoResolve(report: ShepherdReport): ShepherdReport;

package/bin/commands/rule-auto-resolve-format.mjs

@@ -57,9 +57,16 @@ function splitJoined(reason) {
     return reason.split("; ").filter(Boolean);
 }
 export function ruleAutoResolveFromReport(report) {
-    const threads = report.threads.autoResolved;
-    const minimized = report.comments.autoMinimized ?? [];
-    const errors = report.threads.autoResolveErrors;
+    return buildRuleAutoResolveReport({
+        threads: report.threads.autoResolved,
+        minimized: report.comments.autoMinimized ?? [],
+        errors: report.threads.autoResolveErrors,
+        errorReasons: report.threads.autoResolveErrorReasons ?? [],
+    });
+}
+/** The one report shape iterate and the aggregate summary both surface. */
+export function buildRuleAutoResolveReport(input) {
+    const { threads, minimized, errors } = input;
     if (threads.length === 0 && minimized.length === 0 && errors.length === 0)
         return undefined;
     const comments = minimized.filter((item) => item.kind === "pr-comment").length;
@@ -70,7 +77,7 @@ export function ruleAutoResolveFromReport(report) {
             ...threads.flatMap((thread) => splitJoined(thread.ruleReason)),
             ...minimized.flatMap((item) => splitJoined(item.ruleReason)),
         ])
-        : uniqueReasons(report.threads.autoResolveErrorReasons ?? []);
+        : uniqueReasons(input.errorReasons);
     const body = ruleAutoResolveBody({ threads: threads.length, comments, reviewSummaries }) ??
         `auto-resolve failed for ${plural(errors.length, "mutation")}`;
     return {

package/bin/commands/rule-auto-resolve.d.mts

@@ -1,5 +1,5 @@
 import type { BatchPartition } from "../classify/apply.mts";
-import type { AutoMinimizedItem, AutoResolvedThread, BatchPrData } from "../types.mts";
+import type { AutoMinimizedItem, AutoResolvedThread, ReviewThread } from "../types.mts";
 export interface RuleAutoResolveApplied {
     threadIds: string[];
     commentIds: string[];
@@ -9,8 +9,20 @@ export interface RuleAutoResolveApplied {
     autoResolveErrors: string[];
     errorReasons: string[];
 }
+interface MinimizableItem {
+    id: string;
+    url?: string;
+    viewerCanMinimize?: boolean;
+}
+/** The part of a PR read the mutations need. A full batch and a compact summary both satisfy it. */
+export interface RuleAutoResolveBatch {
+    comments: readonly MinimizableItem[];
+    reviewSummaries: readonly MinimizableItem[];
+    reviewThreads: readonly ReviewThread[];
+}
 export declare function applySuppressedRuleAutoResolve(input: {
     enabled: boolean;
     partition: BatchPartition;
-    batch: BatchPrData;
+    batch: RuleAutoResolveBatch;
 }): Promise<RuleAutoResolveApplied>;
+export {};

package/bin/commands/stack-drain.d.mts

@@ -8,7 +8,7 @@ export interface StackPlan {
     idle?: PollSummaryItem[];
     instructions: string[];
 }
-export declare function planPrefixDrain(result: PollSummaryResult, mergeRequested: boolean): StackPlan | undefined;
+export declare function planPrefixDrain(result: PollSummaryResult, mergeRequested: boolean, rerunCommand?: string): StackPlan | undefined;
 /**
  * A merge-requested, fully ready stack whose bottom open layer still targets
  * the merged layer below it until GitHub retargets it onto the stack base.

package/bin/commands/stack-drain.mjs

@@ -2,7 +2,7 @@ import { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-hando
 export { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-handoffs.mjs";
 import { stackMergeFlag } from "./stack-merge-flag.mjs";
 import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
-import { splitStackWork } from "./stack-work.mjs";
+import { splitStackWork, stackRerunTarget } from "./stack-work.mjs";
 import { getGithubTransport } from "../github/transport.mjs";
 import { buildMergeCommandPlan, renderMergeCommand } from "./iterate/merge.mjs";
 function readyPrefixTop(result) {
@@ -28,7 +28,7 @@ function readyPrefixTop(result) {
     }
     return top;
 }
-export function planPrefixDrain(result, mergeRequested) {
+export function planPrefixDrain(result, mergeRequested, rerunCommand) {
     if (!mergeRequested)
         return undefined;
     const top = readyPrefixTop(result);
@@ -92,7 +92,7 @@ export function planPrefixDrain(result, mergeRequested) {
     const handoffs = findHumanHandoffs(result);
     if (handoffs)
         appendHumanHandoffInstructions(instructions, handoffs, false);
-    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun this same \`stack --merge\` command; GitHub retargets the next layer onto \`${top.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
+    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun ${rerunCommand ? stackRerunTarget(rerunCommand) : "this same `stack --merge` command"}; GitHub retargets the next layer onto \`${top.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
     return {
         action: "merge",
         stackMergeable: gaps.length === 0 && open.every(isStackLayerReady),

package/bin/commands/stack-work.d.mts

@@ -17,8 +17,11 @@ export declare function onlyDraftReadinessVerification(sessions: PollSummaryItem
  * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export declare function splitStackWork(candidates: PollSummaryItem[], staleChildren: ReadonlySet<number>): StackWork;
+/** The literal stack command to rerun, or the generic name when the caller's command is unknown. */
+export declare function stackRerunTarget(command?: string): string;
 /**
  * The closing step after routed sessions: rerun the stack command, or stop when nothing is owned.
  * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
+ * `keepWatching` is false when a human handoff may end the run before every layer is terminal.
  */
-export declare function appendStackRerunInstruction(instructions: string[], layers: PollSummaryItem[], rerun: string): "shepherd" | "escalate";
+export declare function appendStackRerunInstruction(instructions: string[], layers: PollSummaryItem[], rerun: string, keepWatching?: boolean): "shepherd" | "escalate";

package/bin/commands/stack-work.mjs

@@ -35,12 +35,20 @@ function isProbed(item) {
 function onlyUnownedWork(layers) {
     return layers.length > 0 && layers.every((item) => !item.owned);
 }
+/** The turn must outlive every non-terminal layer; a one-PR session ending does not end the stack. */
+const STACK_KEEP_WATCHING = "Keep watching until every layer is terminal.";
+/** The literal stack command to rerun, or the generic name when the caller's command is unknown. */
+export function stackRerunTarget(command) {
+    return command ? `\`${command}\`` : "this same `stack` command";
+}
 /**
  * The closing step after routed sessions: rerun the stack command, or stop when nothing is owned.
  * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
+ * `keepWatching` is false when a human handoff may end the run before every layer is terminal.
  */
-export function appendStackRerunInstruction(instructions, layers, rerun) {
+export function appendStackRerunInstruction(instructions, layers, rerun, keepWatching = true) {
     const stop = onlyUnownedWork(layers);
-    instructions.push(`${instructions.length + 1}. ${stop ? "No owned layer needs a session. Report this overview and stop." : rerun}`);
+    const step = keepWatching ? `${rerun} ${STACK_KEEP_WATCHING}` : rerun;
+    instructions.push(`${instructions.length + 1}. ${stop ? "No owned layer needs a session. Report this overview and stop." : step}`);
     return stop ? "escalate" : "shepherd";
 }

package/bin/commands/tick.mjs

@@ -86,6 +86,7 @@ async function withAggregateNextCheck(result, opts) {
 function withoutPollingCadence(step) {
     return step
         .replace(/ Recheck(?: them)? at the configured polling cadence\./g, "")
+        .replace(/Do not end the turn while any selected row is non-terminal: /g, "Keep watching every non-terminal selected row through the wake-up below: ")
         .replace("rerun that command at the configured cadence to resume its UUID", "rerun that command after the wake-up below to resume its UUID");
 }
 function aggregateNextCheck(result, stallDeadlineSeconds) {

package/bin/comments/thread-visibility.d.mts

@@ -8,5 +8,11 @@ interface ThreadVisibility {
     firstLookThreads: FirstLookThread[];
     toMarkSeen: ReviewThread[];
 }
+/**
+ * Whether an unresolved thread with a known outdated state keeps returning every tick once seen,
+ * given an authorized mutation. The compact summary calls this so its count cannot drift from
+ * `classifyThreadVisibility`.
+ */
+export declare function unresolvedThreadRepeats(thread: ReviewThread, ended: boolean, botUsernames: NormalizedBotUsernames, policy: ResolveOtherHumanThreads): boolean;
 export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames, repeatableThreadIds?: ReadonlySet<string>, resolveOtherHumanThreads?: ResolveOtherHumanThreads): ThreadVisibility;
 export {};

package/bin/comments/thread-visibility.mjs

@@ -3,6 +3,9 @@ import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "./authors.mjs";
 import { threadEndedByShepherd } from "./marker.mjs";
 import { shouldResolveOtherHumanThread } from "./thread-resolve-policy.mjs";
+function isOrdinaryHuman(thread, botUsernames) {
+    return isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
+}
 function withEdited(thread, edited) {
     return edited ? { ...thread, edited: true } : thread;
 }
@@ -20,9 +23,33 @@ function classifyFirstLookThread(thread, seenMap, firstLookStatus) {
         return null;
     return { ...visible, firstLookStatus };
 }
+/** An unresolved, current thread whose author class makes it repeat while a mutation is authorized. */
+function repeatsAsActive(thread, ended, botUsernames, policy) {
+    if (thread.isOutdated !== false || thread.isMinimized === true || ended)
+        return false;
+    return (isConfiguredBotAuthor(thread, botUsernames) ||
+        isViewerAuthoredHuman(thread, botUsernames) ||
+        (isOrdinaryHuman(thread, botUsernames) && policy === "always"));
+}
+/** An unresolved thread that is resolution-only work: outdated, minimized or ended by Shepherd. */
+function isResolutionOnlyCandidate(thread, ended, botUsernames, policy) {
+    if (!ended)
+        return thread.isOutdated === true || thread.isMinimized === true;
+    if (!isOrdinaryHuman(thread, botUsernames))
+        return true;
+    return (isViewerAuthoredHuman(thread, botUsernames) || shouldResolveOtherHumanThread(thread, policy));
+}
+/**
+ * Whether an unresolved thread with a known outdated state keeps returning every tick once seen,
+ * given an authorized mutation. The compact summary calls this so its count cannot drift from
+ * `classifyThreadVisibility`.
+ */
+export function unresolvedThreadRepeats(thread, ended, botUsernames, policy) {
+    return (repeatsAsActive(thread, ended, botUsernames, policy) ||
+        isResolutionOnlyCandidate(thread, ended, botUsernames, policy));
+}
 export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set(), repeatableThreadIds, resolveOtherHumanThreads = "none") {
     const shouldRepeat = (thread) => repeatableThreadIds?.has(thread.id) ?? true;
-    const isOrdinaryHuman = (thread) => isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
     const unknownStatusThreads = threads.filter((thread) => thread.isResolved === undefined || thread.isOutdated === undefined);
     const unresolvedThreads = threads.filter((thread) => thread.isResolved === false && thread.isOutdated !== undefined);
     const activeThreads = unresolvedThreads
@@ -30,25 +57,13 @@ export function classifyThreadVisibility(threads, seenMap, botUsernames = new Se
         .flatMap((t) => {
         if (threadEndedByShepherd(t))
             return [];
-        const repeatAuthor = isConfiguredBotAuthor(t, botUsernames) ||
-            isViewerAuthoredHuman(t, botUsernames) ||
-            (isOrdinaryHuman(t) && resolveOtherHumanThreads === "always");
-        if (repeatAuthor && shouldRepeat(t))
+        if (repeatsAsActive(t, false, botUsernames, resolveOtherHumanThreads) && shouldRepeat(t))
             return [t];
         const visible = classifyVisibleThread(t, seenMap);
         return visible ? [visible] : [];
     });
     const resolutionOnlyThreads = unresolvedThreads
-        .filter((t) => {
-        const endedByShepherd = threadEndedByShepherd(t);
-        if (endedByShepherd) {
-            if (!isOrdinaryHuman(t))
-                return true;
-            return (isViewerAuthoredHuman(t, botUsernames) ||
-                shouldResolveOtherHumanThread(t, resolveOtherHumanThreads));
-        }
-        return t.isOutdated || t.isMinimized;
-    })
+        .filter((t) => isResolutionOnlyCandidate(t, threadEndedByShepherd(t), botUsernames, resolveOtherHumanThreads))
         .flatMap((t) => {
         const visible = classifyVisibleThread(t, seenMap);
         if (visible)

package/bin/github/batch-parse-suites.d.mts

@@ -5,6 +5,20 @@ export declare function parseCheckSuitesComplete(raw: RawPr): boolean;
 /** True only when the head commit's suite page finished and listed nothing. */
 export declare function parseHeadCheckSuitesEmpty(raw: RawPr): boolean;
 export declare function parseSuiteStartupFailures(raw: RawPr): CheckRun[];
+/** One failing check per STARTUP_FAILURE workflow-run suite; shared by the one-PR and summary reads. */
+export declare function startupFailureChecksFromSuites(suites: {
+    nodes: Array<{
+        conclusion: string | null;
+        workflowRun: {
+            databaseId?: number | null;
+            event: string | null;
+            url?: string | null;
+            workflow?: {
+                name: string | null;
+            } | null;
+        } | null;
+    }>;
+} | null | undefined): CheckRun[];
 /** `headWorkflowSuites`, omitted when the head has none. */
 export declare function workflowSuites(raw: RawPr): {
     headWorkflowSuites?: WorkflowSuiteSnapshot[];

package/bin/github/batch-parse-suites.mjs

@@ -22,7 +22,10 @@ function parseHeadWorkflowSuites(raw) {
     });
 }
 export function parseSuiteStartupFailures(raw) {
-    const suites = raw.commits.nodes[0]?.commit.checkSuites;
+    return startupFailureChecksFromSuites(raw.commits.nodes[0]?.commit.checkSuites);
+}
+/** One failing check per STARTUP_FAILURE workflow-run suite; shared by the one-PR and summary reads. */
+export function startupFailureChecksFromSuites(suites) {
     if (!suites)
         return [];
     return suites.nodes.flatMap((node) => {

package/bin/github/batch-parser-helpers.mjs

@@ -28,6 +28,7 @@ export function mapCheckRunNode(node) {
     const summary = extractCheckRunSummary(node.title, node.summary);
     const rawCreatedAt = node.checkSuite?.workflowRun?.createdAt ?? node.checkSuite?.createdAt;
     const rawUpdatedAt = node.checkSuite?.workflowRun?.updatedAt ?? node.checkSuite?.updatedAt;
+    const suiteStatus = node.checkSuite?.status || undefined;
     const createdAtUnix = rawCreatedAt ? parseCreatedAt(rawCreatedAt) : undefined;
     const startedAtUnix = node.startedAt ? parseCreatedAt(node.startedAt) : undefined;
     const completedAtUnix = node.completedAt ? parseCreatedAt(node.completedAt) : undefined;
@@ -43,11 +44,15 @@ export function mapCheckRunNode(node) {
         runId,
         ...(workflowName !== undefined && { workflowName }),
         ...(workflowId !== undefined && { workflowId }),
+        ...(suiteStatus !== undefined && { suiteStatus }),
         ...(createdAtUnix !== undefined && { createdAtUnix }),
         ...(startedAtUnix !== undefined && { startedAtUnix }),
         ...(completedAtUnix !== undefined && { completedAtUnix }),
         ...(updatedAtUnix !== undefined && { updatedAtUnix }),
         ...(summary !== undefined && { summary }),
+        ...((node.annotations?.totalCount ?? 0) > 0 && {
+            annotationCount: node.annotations.totalCount,
+        }),
         ...(((node.annotations?.totalCount ?? 0) > 0 || (node.annotations?.nodes.length ?? 0) > 0) && {
             hasAnnotations: true,
         }),

package/bin/github/batch-raw-types.d.mts

@@ -234,6 +234,7 @@ export type RawContextNode = {
         }>;
     };
     checkSuite: {
+        status?: string | null;
         createdAt?: string;
         updatedAt?: string;
         workflowRun: {

package/bin/github/check-annotation-cache.d.mts

@@ -3,6 +3,11 @@ import type { CheckAnnotation } from "../types.mts";
 export interface AnnotationCacheOptions {
     stateKey: StateKey;
     headSha?: string;
+    /**
+     * Annotation total GitHub reports per check run right now. A cached list whose length
+     * differs is stale (a publisher added annotations to a completed run) and is not reused.
+     */
+    expectedCounts?: ReadonlyMap<string, number>;
 }
 export declare function readFreshCheckAnnotations(checkRunId: string, cacheOpts: AnnotationCacheOptions | undefined): Promise<CheckAnnotation[] | undefined>;
 export declare function storeCheckAnnotations(checkRunId: string, annotations: CheckAnnotation[], cacheOpts: AnnotationCacheOptions | undefined): Promise<void>;

package/bin/github/check-annotation-cache.mjs

@@ -12,9 +12,12 @@ export async function readFreshCheckAnnotations(checkRunId, cacheOpts) {
     if (!cacheOpts)
         return undefined;
     const cached = await loadDerived(cacheOpts.stateKey, cacheName(checkRunId));
-    if (cached && Date.now() - cached.storedAt < ANNOTATION_CACHE_MAX_AGE_MS)
-        return cached.value;
-    return undefined;
+    if (!cached || Date.now() - cached.storedAt >= ANNOTATION_CACHE_MAX_AGE_MS)
+        return undefined;
+    const expected = cacheOpts.expectedCounts?.get(checkRunId);
+    if (expected !== undefined && cached.value.length !== expected)
+        return undefined;
+    return cached.value;
 }
 export async function storeCheckAnnotations(checkRunId, annotations, cacheOpts) {
     if (!cacheOpts)

package/bin/github/fingerprint.mjs

@@ -12,6 +12,10 @@ export function fingerprintFromRaw(raw, viewerPermission = null, viewerLogin = n
         isMergeQueueEnabled: Boolean(raw.isMergeQueueEnabled),
         mergePolicy: mergePolicyFingerprint(raw),
         commentCount: raw.comments.totalCount ?? raw.comments.nodes.length,
+        // Raw `updatedAt` on purpose, even for bot or rule-suppressed comments (#635 gap 7). A miss
+        // continues the same BatchPr request into the full snapshot, so an edited bot comment costs
+        // no extra request over a hit, while excluding it would need rule evaluation here and would
+        // risk hiding an edit that un-suppresses the comment or edits a minimized human comment.
         commentRevisions: commentRevisions(raw.comments.nodes),
         threadCount: raw.reviewThreads.totalCount ?? raw.reviewThreads.nodes.length,
         reviewCount: raw.allReviews?.totalCount ?? 0,

package/bin/github/github-fetch.d.mts

@@ -1,2 +1,6 @@
-/** Attach proxy routing to GitHub requests without changing the host's dispatcher. */
-export declare function githubFetch(input: string | URL, init?: RequestInit): Promise<Response>;
+/**
+ * Attach proxy routing to GitHub requests without changing the host's dispatcher.
+ * The request, including reading its body, is bounded by `timeoutMs`; a stall
+ * rejects with an ETIMEDOUT error that the transport retry treats as transient.
+ */
+export declare function githubFetch(input: string | URL, init?: RequestInit, timeoutMs?: number): Promise<Response>;

package/bin/github/github-fetch.mjs

@@ -1,5 +1,7 @@
 import { createRequire } from "node:module";
 import { createCapturedProxyAgent } from "./captured-proxy-agent.mjs";
+import { GITHUB_API_TIMEOUT_MS } from "./github-timeouts.mjs";
+import { redactUrl } from "./http-utils.mjs";
 import { loadUndiciKeepingLegacyDispatcher } from "./legacy-dispatcher.mjs";
 const require = createRequire(import.meta.url);
 let proxyAgent;
@@ -9,8 +11,41 @@ function loadUndici() {
     undiciModule ??= loadUndiciKeepingLegacyDispatcher(() => require("undici"));
     return undiciModule;
 }
-/** Attach proxy routing to GitHub requests without changing the host's dispatcher. */
-export async function githubFetch(input, init) {
+/**
+ * Attach proxy routing to GitHub requests without changing the host's dispatcher.
+ * The request, including reading its body, is bounded by `timeoutMs`; a stall
+ * rejects with an ETIMEDOUT error that the transport retry treats as transient.
+ */
+export async function githubFetch(input, init, timeoutMs = GITHUB_API_TIMEOUT_MS) {
+    const deadline = AbortSignal.timeout(timeoutMs);
+    const signal = init?.signal ? AbortSignal.any([init.signal, deadline]) : deadline;
+    try {
+        return await bufferBody(await routedFetch(input, { ...init, signal }));
+    }
+    catch (err) {
+        if (deadline.aborted && !init?.signal?.aborted) {
+            const method = init?.method ?? "GET";
+            throw Object.assign(new Error(`GitHub request timed out after ${timeoutMs / 1000}s: ${method} ${redactUrl(String(input))}`, { cause: err }), { code: "ETIMEDOUT" });
+        }
+        throw err;
+    }
+}
+/**
+ * Read a streamed body inside the deadline and the callers' transport retry, so a
+ * body that stalls after the headers is retried like a stalled request. Callers
+ * read every body in full anyway.
+ */
+async function bufferBody(response) {
+    if (typeof response.body?.getReader !== "function")
+        return response;
+    const bytes = await response.arrayBuffer();
+    return new Response(bytes.byteLength > 0 ? bytes : null, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+async function routedFetch(input, init) {
     const httpProxy = process.env["http_proxy"] ?? process.env["HTTP_PROXY"] ?? "";
     const httpsProxy = process.env["https_proxy"] ?? process.env["HTTPS_PROXY"] ?? "";
     if (!httpProxy && !httpsProxy)

package/bin/github/github-timeouts.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Deadline for one GitHub REST or GraphQL request, headers and body included.
+ * Without it a half-open connection waits for undici's 300s headers/body
+ * defaults (10s for connect) and the tick prints nothing meanwhile.
+ */
+export declare const GITHUB_API_TIMEOUT_MS = 60000;
+/** Deadline for Actions log downloads, which can be several megabytes. */
+export declare const GITHUB_LOG_TIMEOUT_MS = 180000;

package/bin/github/github-timeouts.mjs

@@ -0,0 +1,8 @@
+/**
+ * Deadline for one GitHub REST or GraphQL request, headers and body included.
+ * Without it a half-open connection waits for undici's 300s headers/body
+ * defaults (10s for connect) and the tick prints nothing meanwhile.
+ */
+export const GITHUB_API_TIMEOUT_MS = 60_000;
+/** Deadline for Actions log downloads, which can be several megabytes. */
+export const GITHUB_LOG_TIMEOUT_MS = 180_000;

package/bin/github/gql/batch-pr-page.gql

@@ -196,6 +196,7 @@ query BatchPrPage(
                       }
                     }
                     checkSuite {
+                      status
                       createdAt
                       updatedAt
                       workflowRun {