pr-shepherd 1.0.0 → 1.1.0

package/.claude-plugin/plugin.json

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

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

@@ -3,6 +3,7 @@ import { withPollSummaryInstructions } from "../commands/poll-summary-instructio
 import { formatStackOverview, projectStackOverview } from "./stack-overview.mjs";
 import { formatTransportEvidence } from "./transport-formatter.mjs";
 import { formatNextCheckLines } from "./next-check-format.mjs";
+import { formatRuleAutoResolveLines } from "./rule-auto-resolve-lines.mjs";
 export function formatPollSummaryResult(result) {
     if (result.selection.kind === "stack")
         return formatStackOverview(projectStackOverview(result));
@@ -69,12 +70,14 @@ function formatItem(item) {
         ...(review
             ? [`  - review: ${formatCounts(review, review.incomplete ? ", incomplete" : "")}`]
             : []),
+        ...formatRuleAutoResolveLines(item.ruleAutoResolve),
         ...(item.queueRemoval
             ? [
                 `  - queue removal: reason \`${item.queueRemoval.reason ?? "UNKNOWN"}\` · at \`${item.queueRemoval.createdAtUnix}\`${item.queueRemoval.actor ? ` · actor \`@${item.queueRemoval.actor}\`` : ""}${item.queueRemoval.beforeCommitOid ? ` · commit \`${item.queueRemoval.beforeCommitOid}\`` : ""}${item.queueRemoval.beforeCommitParentOids?.length ? ` · parents \`${item.queueRemoval.beforeCommitParentOids.join(",")}\`` : ""}`,
             ]
             : []),
         `  - reasons: ${item.reasons.map((reason) => `\`${reason}\``).join(", ")}`,
+        ...(item.error ? [`  - error: ${item.error.replace(/\s*[\r\n]+\s*/g, " ")}`] : []),
         ...(item.transport ? [`  - transport \`${item.transport}\``] : []),
         ...(item.transportUnavailable ?? []).map(({ field, reason }) => `  - unavailable \`${field}\`: ${reason}`),
         ...(item.pollCommand

package/bin/cli/rule-auto-resolve-lines.d.mts

@@ -0,0 +1,3 @@
+import type { PollSummaryRuleAutoResolve } from "../types.mts";
+/** Row lines for an aggregate row or stack layer: the one-PR `## Classification auto-resolve` content. */
+export declare function formatRuleAutoResolveLines(event: PollSummaryRuleAutoResolve | undefined): string[];

package/bin/cli/rule-auto-resolve-lines.mjs

@@ -0,0 +1,12 @@
+/** Row lines for an aggregate row or stack layer: the one-PR `## Classification auto-resolve` content. */
+export function formatRuleAutoResolveLines(event) {
+    if (!event)
+        return [];
+    const link = (kind, id, url) => `    - ${kind} \`${id}\`${url ? ` ${url}` : ""}`;
+    return [
+        `  - classification auto-resolve: ${event.summary}`,
+        ...(event.threads ?? []).map((thread) => link("thread", thread.id, thread.url)),
+        ...(event.minimized ?? []).map((item) => link(item.kind, item.id, item.url)),
+        ...(event.errors ?? []).map((error) => `    - ${error}`),
+    ];
+}

package/bin/cli/stack-layer-view.d.mts

@@ -1,4 +1,4 @@
-import type { PollSummaryItem } from "../types.mts";
+import type { PollSummaryItem, PollSummaryRuleAutoResolve } from "../types.mts";
 /** One lean stack row shared by Markdown, JSON, and MCP. */
 export interface StackLayerView {
     transport?: "rest";
@@ -26,6 +26,7 @@ export interface StackLayerView {
     actionable?: number;
     checksIncomplete?: true;
     reviewIncomplete?: true;
+    ruleAutoResolve?: PollSummaryRuleAutoResolve;
     queueRemoval?: {
         reason: string | null;
         actor?: string;

package/bin/cli/stack-overview.mjs

@@ -3,6 +3,7 @@ import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
 import { formatTransportEvidence } from "./transport-formatter.mjs";
 import { formatNextCheckLines } from "./next-check-format.mjs";
 import { formatPrUrl } from "../pr-reference.mjs";
+import { formatRuleAutoResolveLines } from "./rule-auto-resolve-lines.mjs";
 /** Lean stack payload shared by Markdown, JSON, and MCP. */
 export function projectStackOverview(result) {
     const selection = result.selection;
@@ -59,6 +60,7 @@ function projectLayer(item, stale) {
             (item.review?.actionable ?? 0) > 0 && { actionable: item.review?.actionable }),
         ...(item.checks?.incomplete && { checksIncomplete: true }),
         ...(item.review?.incomplete && { reviewIncomplete: true }),
+        ...(item.ruleAutoResolve && { ruleAutoResolve: item.ruleAutoResolve }),
         ...(removal && {
             queueRemoval: {
                 reason: removal.reason,
@@ -156,6 +158,7 @@ function formatLayerLines(layer, index, overview) {
     return [
         `- ${layer.url === formatPrUrl(overview.repo, layer.pr) ? `PR #${layer.pr}: ${layer.title}` : `[PR #${layer.pr}: ${layer.title}](${layer.url})`}${facts.length > 0 ? ` — ${facts.join(" · ")}` : ""}`,
         `  - ${details.join(" · ")}`,
+        ...formatRuleAutoResolveLines(layer.ruleAutoResolve),
         ...(layer.transport ? [`  - transport \`${layer.transport}\``] : []),
         ...(layer.transportUnavailable ?? []).map(({ field, reason }) => `  - unavailable \`${field}\`: ${reason}`),
     ];

package/bin/commands/check-activity.d.mts

@@ -0,0 +1,8 @@
+import type { BatchPartition } from "../classify/apply.mts";
+import type { PrActivitySummary } from "../types.mts";
+/**
+ * Drop rule-suppressed items from the activity digest, matching what `check` hides from the
+ * agent. IDs whose automatic minimize/resolve was denied stay visible: `check` surfaces those
+ * once so the caller can act. `reviewRoundCount` is raw review history and stays unchanged.
+ */
+export declare function filterSuppressedActivity(activity: PrActivitySummary | undefined, partition: BatchPartition, denied: Iterable<string>): PrActivitySummary | undefined;

package/bin/commands/check-activity.mjs

@@ -0,0 +1,26 @@
+/**
+ * Drop rule-suppressed items from the activity digest, matching what `check` hides from the
+ * agent. IDs whose automatic minimize/resolve was denied stay visible: `check` surfaces those
+ * once so the caller can act. `reviewRoundCount` is raw review history and stays unchanged.
+ */
+export function filterSuppressedActivity(activity, partition, denied) {
+    if (!activity)
+        return activity;
+    const deniedIds = new Set(denied);
+    const hidden = (id, suppressed) => suppressed.has(id) && !deniedIds.has(id);
+    const reviewItemsSinceLatestCommit = activity.reviewItemsSinceLatestCommit.filter((item) => {
+        switch (item.kind) {
+            case "pr-comment":
+                return !hidden(item.id, partition.suppressedCommentIds);
+            case "review-thread-comment":
+                return !item.threadId || !hidden(item.threadId, partition.suppressedThreadIds);
+            case "review-summary":
+                return !hidden(item.id, partition.suppressedReviewSummaryIds);
+            case "changes-requested-review":
+                return !partition.suppressedChangesRequestedIds.has(item.id);
+            default:
+                return true;
+        }
+    });
+    return { ...activity, reviewItemsSinceLatestCommit };
+}

package/bin/commands/check-annotations.mjs

@@ -42,7 +42,8 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber,
         ...buckets.filtered,
         ...buckets.ignored,
     ].filter(shouldFetchCheckAnnotations);
-    const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber, cacheOpts);
+    const expectedCounts = new Map(candidates.flatMap((c) => c.id != null && c.annotationCount ? [[c.id, c.annotationCount]] : []));
+    const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber, cacheOpts && { ...cacheOpts, expectedCounts });
     const byId = new Map(annotated.flatMap((c) => (c.id != null ? [[c.id, c]] : [])));
     const apply = (list) => list.map((c) => {
         const next = (c.id == null ? undefined : byId.get(c.id)) ?? c;

package/bin/commands/check-wait-detectors.mjs

@@ -30,6 +30,17 @@ function detectorsCover(stored) {
  * Read the PR's REST change detectors: the pull, the head's check runs, check suites and
  * statuses, the three feedback lists, and the base branch. Every read is conditional, so an
  * unchanged resource answers a free 304.
+ *
+ * The feedback lists are deliberately not rule-aware (#635 gap 7). An edited bot comment, even
+ * a rule-suppressed or minimized one, answers 200 and wakes the tick. The wake costs one
+ * charged list read plus one `BatchPr` first page (a complete fingerprint needs no more),
+ * the same point a fingerprint hit spends. Once the digest is re-recorded, a later eligible
+ * tick can replay for free again, but only if every detector answers 304 with that digest and
+ * the stored snapshot is within `poll.reconcile-seconds`; otherwise it goes to `BatchPr`. Being
+ * rule-aware would need the loaded rules, a persisted set of hidden comment ids (REST has no
+ * `isMinimized`), and a content digest in place of the ETag. That is more code, and more risk
+ * of sleeping through a real change (a rule-suppressed comment edited so it no longer matches,
+ * an edited minimized human comment, which `check` surfaces), than the one point it saves.
  */
 async function readDetectors(prNumber, repo, report) {
     const prefix = restRepoPath(repo);

package/bin/commands/check.mjs

@@ -33,6 +33,7 @@ import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers
 import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./iterate/thread-mutation-routing.mjs";
 import { loadClassifyRules } from "../classify/loader.mjs";
+import { filterSuppressedActivity } from "./check-activity.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
@@ -449,7 +450,11 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         ...(batchData.allowedMergeMethods && {
             allowedMergeMethods: batchData.allowedMergeMethods,
         }),
-        activity: batchData.activity,
+        activity: filterSuppressedActivity(batchData.activity, partition, [
+            ...deniedRuleAutoResolveCommentIds,
+            ...deniedRuleAutoResolveThreadIds,
+            ...deniedRuleAutoResolveReviewSummaryIds,
+        ]),
         ...(hasQueueState && {
             mergeQueue: {
                 enabled: Boolean(batchData.isMergeQueueEnabled),

package/bin/commands/poll-summary-signature.d.mts

@@ -1,2 +1,8 @@
 import type { PollSummaryResult } from "../types.mts";
+/**
+ * Decision-relevant state only. Raw review totals and the ignored, skipped, filtered, and
+ * superseded check counts move when rules suppress a bot notice or a bot reposts a status
+ * check, which would reprint quiet polls and keep an idle stack from reaching `stall-timeout`.
+ * Post-rule `actionable` and the check transitions that drive routing stay in.
+ */
 export declare function summaryStatusSignature(result: PollSummaryResult): string;

package/bin/commands/poll-summary-signature.mjs

@@ -1,3 +1,9 @@
+/**
+ * Decision-relevant state only. Raw review totals and the ignored, skipped, filtered, and
+ * superseded check counts move when rules suppress a bot notice or a bot reposts a status
+ * check, which would reprint quiet polls and keep an idle stack from reaching `stall-timeout`.
+ * Post-rule `actionable` and the check transitions that drive routing stay in.
+ */
 export function summaryStatusSignature(result) {
     return JSON.stringify({
         nextAction: result.nextAction,
@@ -9,8 +15,19 @@ export function summaryStatusSignature(result) {
             mergeable: item.mergeable,
             mergeStateStatus: item.mergeStateStatus,
             reviewDecision: item.reviewDecision,
-            checks: item.checks,
-            review: item.review,
+            checks: item.checks && {
+                passing: item.checks.passing,
+                failing: item.checks.failing,
+                inProgress: item.checks.inProgress,
+                incomplete: item.checks.incomplete,
+                annotated: item.checks.annotated,
+                unreportedRequired: item.checks.unreportedRequired,
+                actionsWorkflowInProgress: item.checks.actionsWorkflowInProgress,
+            },
+            review: item.review && {
+                actionable: item.review.actionable,
+                incomplete: item.review.incomplete,
+            },
         })),
     });
 }

package/bin/commands/poll-summary.mjs

@@ -82,6 +82,7 @@ async function runAggregatePollCore(opts) {
         try {
             lastTick = await readPollSummaryTick(opts);
             last = lastTick.result;
+            writeAggregateRuleAutoResolve(last);
             rateLimitRetry.reset();
         }
         catch (error) {
@@ -192,6 +193,12 @@ async function runAggregatePollCore(opts) {
         await sleep(sleepMs);
     }
 }
+/** 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, merge) {
     // The stack planner already cancels an all-merged stack and escalates a
     // closed-unmerged layer. Do not rewrite that into a successful stop.

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/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/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

@@ -48,6 +48,9 @@ export function mapCheckRunNode(node) {
         ...(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/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/poll-summary-annotation-probe.d.mts

@@ -19,3 +19,8 @@ export declare function hydrateReadyAnnotationProbe(pr: RawSummaryPr, repo: Repo
     actionable?: number;
     incomplete?: true;
 }): Promise<void>;
+/**
+ * Load annotation totals once per summary row, from the same probe the READY receipt
+ * hash uses. False when a page could not be read, so no total is trustworthy.
+ */
+export declare function hydrateAnnotationTotals(pr: RawSummaryPr, repo: RepoInfo): Promise<boolean>;

package/bin/github/poll-summary-annotation-probe.mjs

@@ -7,6 +7,7 @@ import { fingerprintRawSummaryPr } from "./poll-summary-fingerprint.mjs";
 import { POLL_SUMMARY_ANNOTATION_PROBE_QUERY } from "./queries.mjs";
 const PROBE_UNAVAILABLE = Symbol.for("prShepherd.annotationProbeUnavailable");
 const COMPLETE_FROM_BATCH = new WeakSet();
+const HYDRATED = new WeakSet();
 /** Annotation totals copied from the same full-snapshot request; no follow-up probe is needed. */
 export function markReadyAnnotationProbeComplete(pr) {
     COMPLETE_FROM_BATCH.add(pr);
@@ -36,9 +37,22 @@ export async function hydrateReadyAnnotationProbe(pr, repo, review) {
     const checks = summarizePollSummaryChecks(pr);
     if (!isCurrentSummaryReady(pr, checks, review))
         return;
-    if (!(await hydrateCommitAnnotations(pr, repo))) {
-        pr[PROBE_UNAVAILABLE] = true;
-    }
+    await hydrateAnnotationTotals(pr, repo);
+}
+/**
+ * Load annotation totals once per summary row, from the same probe the READY receipt
+ * hash uses. False when a page could not be read, so no total is trustworthy.
+ */
+export async function hydrateAnnotationTotals(pr, repo) {
+    if (COMPLETE_FROM_BATCH.has(pr))
+        return true;
+    if (HYDRATED.has(pr))
+        return !annotationProbeUnavailable(pr);
+    HYDRATED.add(pr);
+    if (await hydrateCommitAnnotations(pr, repo))
+        return true;
+    pr[PROBE_UNAVAILABLE] = true;
+    return false;
 }
 async function hydrateCommitAnnotations(pr, repo) {
     const commit = pr.commits.nodes[0]?.commit;

package/bin/github/poll-summary-annotations.d.mts

@@ -0,0 +1,14 @@
+import type { PollSummaryChecks, PollSummaryItem } from "../types.mts";
+import type { RepoInfo } from "./client.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+type Routed = Pick<PollSummaryItem, "action" | "reasons">;
+/**
+ * The one-PR check treats unseen annotations on any non-SUCCESS check (failing, skipped,
+ * filtered, ignored or neutral) as actionable work. The compact summary only has annotation
+ * totals, and only for a row that otherwise claims readiness, so it loads them then and reads
+ * the annotations of just the non-SUCCESS checks that have any. A row with unseen annotations,
+ * or whose annotations cannot be read, goes to its one-PR `pollCommand` instead of
+ * claiming `appears-ready`, `cancel`, `mark_ready` or `merge`.
+ */
+export declare function applyUnseenCheckAnnotations(raw: RawSummaryPr, repo: RepoInfo, routed: Routed, checks: PollSummaryChecks, seen: ReadonlyMap<string, unknown>, required: readonly string[]): Promise<Routed>;
+export {};