pr-shepherd 0.55.1 → 0.56.0

package/bin/commands/iterate/render.mjs

@@ -38,8 +38,15 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, st
         const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
         instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
     }
-    if (hasConflicts && !hasRepeatedWorkflowBranchRecovery) {
-        instructions.push(buildConflictInstruction(stackRebase));
+    // A conflicting native stack layer follows the printed gh-stack route, so it omits the hint.
+    const branchUpdateHint = buildBehindBaseHintInstruction(baseBranch, behindBaseHint, {
+        isBehind,
+        hasConflicts: hasConflicts && !stackRebase,
+    });
+    // The conflict hint belongs with the conflict step; otherwise it precedes the push step.
+    const hintWithConflictStep = hasConflicts && !hasRepeatedWorkflowBranchRecovery;
+    if (hintWithConflictStep) {
+        instructions.push(buildConflictInstruction(stackRebase), ...branchUpdateHint);
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
@@ -77,14 +84,15 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, st
         const staleClause = buildCrStaleClause(changesRequestedReviews);
         instructions.push(`Read every body under \`## Changes-requested reviews\` and apply any warranted change.${staleClause}`);
     }
-    instructions.push(...buildBehindBaseHintInstruction(baseBranch, behindBaseHint, isBehind));
+    if (!hintWithConflictStep)
+        instructions.push(...branchUpdateHint);
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     if (hasConflicts || hasRepeatedWorkflowBranchRecovery) {
         instructions.push(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix));
     }
     else if (hasNonConflictHints) {
-        instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate immediately with the same options. If you did not change code, do not commit and continue with the remaining steps.");
+        instructions.push("If you changed code, commit any remaining changes and push to the PR head branch. If you did not, do not commit.");
     }
     if (viewerCanUpdate &&
         (hasReviewMutations ||
@@ -96,6 +104,6 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, st
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");
-    instructions.push(...buildResolveCommandInstruction(resolveCommand), buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha, stackRebase !== undefined));
+    instructions.push(...buildResolveCommandInstruction(resolveCommand), buildFixCompletionInstruction());
     return instructions;
 }

package/bin/commands/iterate/stale-ancestry.d.mts

@@ -1,6 +1,7 @@
 import type { RepoInfo } from "../../github/client.mts";
 import type { PollSummaryStackAncestry } from "../../types.mts";
 import type { ShepherdReport } from "../../types/report.mts";
+import type { CheckExecutionContext } from "../check-execution-context.mts";
 /**
  * A verified stale boundary for the PR being shepherded.
  *
@@ -19,4 +20,4 @@ export interface StaleNativeStackAncestry extends PollSummaryStackAncestry {
  * could not be verified. Callers must not emit a repair command from an
  * unverified snapshot.
  */
-export declare function findStaleNativeStackAncestry(report: Pick<ShepherdReport, "pr" | "mergeStatus">, repo: RepoInfo): Promise<StaleNativeStackAncestry | null>;
+export declare function findStaleNativeStackAncestry(report: Pick<ShepherdReport, "pr" | "mergeStatus">, repo: RepoInfo, context?: CheckExecutionContext): Promise<StaleNativeStackAncestry | null>;

package/bin/commands/iterate/stale-ancestry.mjs

@@ -8,12 +8,13 @@ import { buildNativeStackRebaseInstruction } from "./native-stack-rebase.mjs";
  * could not be verified. Callers must not emit a repair command from an
  * unverified snapshot.
  */
-export async function findStaleNativeStackAncestry(report, repo) {
+export async function findStaleNativeStackAncestry(report, repo, context) {
     const stack = report.mergeStatus.mergeRequirements?.stack;
     if (!stack || stack.position <= 1)
         return null;
     try {
-        const topology = await readStackTopology(report.pr, repo);
+        const topology = await (context?.readStackTopology(report.pr, repo) ??
+            readStackTopology(report.pr, repo));
         const ancestry = stackAncestryGaps(topology.ordered).find((gap) => gap.childPr === report.pr);
         if (!ancestry)
             return null;

package/bin/commands/iterate/unreported-required.mjs

@@ -98,7 +98,7 @@ export function buildUnreportedFixResult(base, report, instructions) {
                 requiresDismissMessage: false,
                 hasMutations: false,
             },
-            instructions: [...instructions, buildFixCompletionInstruction([])],
+            instructions: [...instructions, buildFixCompletionInstruction()],
             inProgressRunIds: [],
             protectedRuns: [],
             firstLookThreads: [],

package/bin/commands/playbook-pointer.d.mts

@@ -0,0 +1,2 @@
+/** Name an on-demand pr-shepherd skill reference. The skill maps the name to a file. */
+export declare function playbookPointer(name: string): string;

package/bin/commands/playbook-pointer.mjs

@@ -0,0 +1,4 @@
+/** Name an on-demand pr-shepherd skill reference. The skill maps the name to a file. */
+export function playbookPointer(name) {
+    return `Playbook: "${name}".`;
+}

package/bin/commands/poll-quota.d.mts

@@ -1,4 +1,5 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
+import { type RateLimitKind } from "../github/rate-limit-kind.mts";
 import type { ApiResourceUsage, GraphqlApiUsage, PollSummaryResult } from "../types.mts";
 /** Slow the poll for whichever of GraphQL or REST core is in a tighter band. */
 export declare function quotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], usage: {
@@ -8,6 +9,7 @@ export declare function quotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], us
 export interface RateLimitRetry {
     ms: number;
     resource: string;
+    kind: RateLimitKind;
     remaining?: number;
     limit?: number;
     resetAt?: number;

package/bin/commands/poll-quota.mjs

@@ -1,6 +1,6 @@
 import { summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { GitHubRequestError } from "../github/errors.mjs";
-import { isRateLimitMessage } from "../comments/rate-limit.mjs";
+import { rateLimitKind } from "../github/rate-limit-kind.mjs";
 import { exhaustedPrimaryLimitDelayMs } from "./poll-rate-limit-delay.mjs";
 import { selectQuotaWarning } from "./quota-selection.mjs";
 const GRAPHQL_RETRY_AFTER_DEFAULT_MS = 60_000;
@@ -28,36 +28,29 @@ export function quotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
 export function pollRateLimitRetryAfterMs(err) {
     if (!(err instanceof GitHubRequestError))
         return null;
-    const rateLimitMessage = isRateLimitMessage(err.message) ||
-        (err.graphqlErrors?.some((error) => isRateLimitMessage(error.message)) ?? false);
-    const exhausted = err.rateLimit !== undefined && err.rateLimit.remaining <= 0;
-    const retryable = err.status === 429 || err.retryAfterSeconds !== undefined || rateLimitMessage || exhausted;
-    if (!retryable)
+    const kind = rateLimitKind(err);
+    if (kind === null)
         return null;
-    const resource = retryResource(err);
+    const resource = kind === "secondary" ? "secondary" : (err.rateLimit?.resource ?? "graphql");
     const rateLimit = err.rateLimit;
     const details = {
+        kind,
         resource,
-        ...(rateLimit?.remaining !== undefined && { remaining: rateLimit.remaining }),
-        ...(rateLimit?.limit !== undefined && { limit: rateLimit.limit }),
-        ...(rateLimit?.resetAt !== undefined && { resetAt: rateLimit.resetAt }),
+        ...(kind === "primary" &&
+            rateLimit?.remaining !== undefined && { remaining: rateLimit.remaining }),
+        ...(kind === "primary" && rateLimit?.limit !== undefined && { limit: rateLimit.limit }),
+        ...(kind === "primary" && rateLimit?.resetAt !== undefined && { resetAt: rateLimit.resetAt }),
     };
-    if (err.retryAfterSeconds !== undefined) {
-        return { ...details, ms: Math.max(err.retryAfterSeconds, 0) * 1000 };
+    if (kind === "primary" && rateLimit !== undefined) {
+        return {
+            ...details,
+            ms: Math.max(exhaustedPrimaryLimitDelayMs(rateLimit.resetAt, Date.now()), Math.max(err.retryAfterSeconds ?? 0, 0) * 1000),
+        };
     }
-    if (exhausted && rateLimit !== undefined) {
-        return { ...details, ms: exhaustedPrimaryLimitDelayMs(rateLimit.resetAt, Date.now()) };
-    }
-    return { ...details, ms: GRAPHQL_RETRY_AFTER_DEFAULT_MS };
-}
-function retryResource(err) {
-    if (err.rateLimit?.resource)
-        return err.rateLimit.resource;
-    const secondary = err.status === 429 ||
-        err.retryAfterSeconds !== undefined ||
-        /secondary/i.test(err.message) ||
-        (err.graphqlErrors?.some((error) => /secondary/i.test(error.message)) ?? false);
-    return secondary ? "secondary" : "graphql";
+    return {
+        ...details,
+        ms: Math.max(GRAPHQL_RETRY_AFTER_DEFAULT_MS, Math.max(err.retryAfterSeconds ?? 0, 0) * 1000),
+    };
 }
 function rateLimitResourceLabel(resource) {
     if (resource === "graphql")

package/bin/commands/poll-rate-limit-wait.mjs

@@ -2,7 +2,8 @@ import { rest } from "../github/rest-http.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { formatRateLimitGiveUpLine, formatRateLimitRetryLine, pollRateLimitRetryAfterMs, } from "./poll-quota.mjs";
 const MAX_NO_PROGRESS_ATTEMPTS = 5;
-const NO_PROGRESS_BACKOFF_MS = [15_000, 30_000, 60_000];
+const PRIMARY_NO_PROGRESS_BACKOFF_MS = [15_000, 30_000, 60_000];
+const SECONDARY_NO_PROGRESS_BACKOFF_MS = [60_000, 120_000, 240_000, 480_000, 960_000];
 const MERGE_STATES = new Set([
     "BEHIND",
     "BLOCKED",
@@ -26,8 +27,10 @@ export function createUntilTerminalRateLimitRetry() {
         },
     };
 }
-function backoffMs(attempt) {
-    return NO_PROGRESS_BACKOFF_MS[Math.min(attempt, NO_PROGRESS_BACKOFF_MS.length) - 1] ?? 60_000;
+function backoffMs(attempt, kind) {
+    const backoff = kind === "secondary" ? SECONDARY_NO_PROGRESS_BACKOFF_MS : PRIMARY_NO_PROGRESS_BACKOFF_MS;
+    const index = kind === "secondary" ? attempt : attempt - 1;
+    return backoff[Math.min(index, backoff.length - 1)] ?? backoff.at(-1);
 }
 async function waitForRateLimit(state, err, opts) {
     const retry = opts.untilTerminal ? pollRateLimitRetryAfterMs(err) : null;
@@ -35,14 +38,16 @@ async function waitForRateLimit(state, err, opts) {
         throw err;
     const elapsed = Math.round((Date.now() - opts.startedAt) / 1000);
     const progressed = state.armed &&
+        retry.kind === "primary" &&
         retry.resetAt !== undefined &&
         (state.lastResetAt === undefined || retry.resetAt > state.lastResetAt);
     let sleepMs = retry.ms;
     if (!state.armed || progressed) {
         state.armed = true;
         state.noProgress = 0;
-        if (retry.resetAt !== undefined)
+        if (retry.kind === "primary" && retry.resetAt !== undefined) {
             state.lastResetAt = retry.resetAt;
+        }
     }
     else {
         state.noProgress += 1;
@@ -52,13 +57,13 @@ async function waitForRateLimit(state, err, opts) {
         }
         // Never sleep less than GitHub asked for. A short no-progress backoff must
         // not undercut an explicit Retry-After or the secondary-limit default.
-        sleepMs = Math.max(retry.ms, backoffMs(state.noProgress));
+        sleepMs = Math.max(retry.ms, backoffMs(state.noProgress, retry.kind));
     }
     process.stderr.write(formatRateLimitRetryLine(opts.tickLabel, elapsed, { ...retry, ms: sleepMs }));
-    return sleepRateLimit(sleepMs, opts, retry.resource);
+    return sleepRateLimit(sleepMs, opts, retry.kind, retry.resource);
 }
-async function sleepRateLimit(ms, opts, resource) {
-    const canProbe = resource !== "core" && opts.targets.length > 0;
+async function sleepRateLimit(ms, opts, kind, resource) {
+    const canProbe = kind === "primary" && resource === "graphql" && opts.targets.length > 0;
     if (ms <= opts.intervalMs || opts.intervalMs <= 0) {
         await sleep(ms);
         return undefined;

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

@@ -137,7 +137,7 @@ function planStack(result, mergeRequested) {
             stackMergeable: true,
             waiting: true,
             instructions: [
-                "1. The stack is in the merge queue. Recheck at the configured polling cadence; finish only after every layer is merged, and route any ejected layer to its one-PR session.",
+                "1. The queued layers are waiting on the merge queue. Recheck them at the configured polling cadence. Do not rewrite a queued layer. This wait does not block work on a layer that is not in the queue. Route any ejected layer to its one-PR session.",
             ],
         };
     }

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

@@ -33,4 +33,6 @@ export declare function updateReadyDelay(prNumber: number, isReady: boolean, rea
 }): 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>;
+/** Read-only hint for including compact receipt evidence in the next full PR snapshot. */
+export declare function readyDelayElapsed(prNumber: number, owner: string, repo: string, readyDelaySeconds: number): Promise<boolean>;
 export {};

package/bin/commands/ready-delay.mjs

@@ -54,6 +54,24 @@ export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, own
 export async function clearReadyDelay(prNumber, owner, repo) {
     await safeUnlink(readySincePath(prNumber, owner, repo));
 }
+/** Read-only hint for including compact receipt evidence in the next full PR snapshot. */
+export async function readyDelayElapsed(prNumber, owner, repo, readyDelaySeconds) {
+    const markerPath = readySincePath(prNumber, owner, repo);
+    let raw;
+    try {
+        raw = await readFile(markerPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const [since, head] = raw.trim().split(" ");
+    const readySince = Number(since);
+    const now = Math.floor(Date.now() / 1000);
+    return Boolean(head &&
+        Number.isSafeInteger(readySince) &&
+        readySince <= now &&
+        now - readySince >= readyDelaySeconds);
+}
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

package/bin/commands/resolve-mutate.mjs

@@ -1,8 +1,8 @@
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { applyResolveOptions } from "../comments/resolve.mjs";
-import { fetchPrBatch } from "../github/batch.mjs";
+import { fetchReplyThreadTranscripts } from "../github/reply-thread-transcripts.mjs";
 import { markReplySeen } from "../state/seen-comments.mjs";
-import { threadTranscriptBody } from "../threads/transcript.mjs";
+import { threadTranscriptBodies } from "../threads/transcript.mjs";
 import { addPrShepherdMarker } from "../comments/marker.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 /** @deprecated Hidden implementation for `resolve`; use `apply review`. */
@@ -14,10 +14,10 @@ export async function runResolveMutate(opts) {
     }
     // Fetch only to retain the pre-reply transcript for successful-reply seen
     // markers. It never determines which user-supplied IDs are sent to GitHub.
-    let threadById;
+    let transcriptById;
     if (opts.replyThreadIds?.length) {
         try {
-            threadById = new Map((await fetchPrBatch(prNumber, repo, { paginateApprovedReviews: true })).data.reviewThreads.map((thread) => [thread.id, thread]));
+            transcriptById = await fetchReplyThreadTranscripts(prNumber, repo, opts.replyThreadIds);
         }
         catch {
             // Seen-marker bookkeeping is best-effort. A failed read must not block
@@ -35,14 +35,13 @@ export async function runResolveMutate(opts) {
         dismissMessage: opts.dismissMessage,
         requireSha: opts.requireSha,
     });
-    if (opts.dismissMessage && threadById) {
+    if (opts.dismissMessage && transcriptById) {
         const markedMessage = addPrShepherdMarker(opts.dismissMessage);
         await Promise.all(result.repliedThreads.map((id) => {
-            const thread = threadById.get(id);
-            if (!thread)
+            const previousBody = transcriptById.get(id);
+            if (previousBody === undefined)
                 return Promise.resolve();
-            const previousBody = threadTranscriptBody(thread);
-            return markReplySeen({ owner: repo.owner, repo: repo.name, pr: prNumber }, id, previousBody, threadTranscriptBody(thread, [markedMessage]), markedMessage);
+            return markReplySeen({ owner: repo.owner, repo: repo.name, pr: prNumber }, id, previousBody, threadTranscriptBodies([previousBody, markedMessage]), markedMessage);
         }));
     }
     return result;

package/bin/commands/shepherd-journal.d.mts

@@ -4,7 +4,7 @@ export declare const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
 export declare const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
 export declare const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
-export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
+export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE: string;
 /**
  * Build the Shepherd Journal instruction step. The reference-citation convention (link
  * threads/comments from their headings, cite reviews by ID) is invariant across every

package/bin/commands/shepherd-journal.mjs

@@ -1,11 +1,12 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
+import { playbookPointer } from "./playbook-pointer.mjs";
 export const SHEPHERD_JOURNAL_SECTION = "Shepherd Journal";
 export const SHEPHERD_JOURNAL_SECTION_PATTERN = /^##\s+Shepherd\s+Journal$/;
 export const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
 export const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
 export const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
-export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
+export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = `Read each body under \`## Review summaries (first look)\` and journal any warranted note before review mutations. ${playbookPointer("Shepherd Journal")}`;
 /**
  * Build the Shepherd Journal instruction step. The reference-citation convention (link
  * threads/comments from their headings, cite reviews by ID) is invariant across every
@@ -15,5 +16,5 @@ export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `##
 export function buildShepherdJournalInstruction(prReference) {
     // Single-quote the placeholder so a substituted decision stays literal in the shell.
     const command = `${buildPrShepherdCommand(["apply", "journal", String(prReference)]).text} '- <decision>'`;
-    return `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`${command}\`. See "Shepherd Journal" in the pr-shepherd skill for citation conventions.`;
+    return `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`${command}\`. ${playbookPointer("Shepherd Journal")}`;
 }

package/bin/commands/stack-drain.mjs

@@ -1,3 +1,4 @@
+import { playbookPointer } from "./playbook-pointer.mjs";
 import { stackMergeFlag } from "./stack-merge-flag.mjs";
 import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
 import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
@@ -48,7 +49,7 @@ export function planPrefixDrain(result, mergeRequested) {
         };
     }
     const instructions = [
-        `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes ${method.flag}\` to merge ${span}. When the base uses a merge queue, the same command queues that prefix together and GitHub evaluates each layer from the bottom; a failure ejects that layer and the layers above it. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\` first.`,
+        `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes ${method.flag}\` to merge ${span}. ${playbookPointer("Stack merge")}`,
     ];
     appendAutonomousInstructions(instructions, above.sessions);
     appendMarkReadyInstructions(instructions, above.markReady);

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

@@ -11,6 +11,7 @@ export interface RawBatchResponse {
         squashMergeAllowed?: boolean;
         rebaseMergeAllowed?: boolean;
         pullRequest: RawPr | null;
+        receiptSummary?: import("./poll-summary-raw.mts").RawSummaryPr | null;
     } | null;
 }
 export interface RawPr extends RawPrMergeFields {
@@ -226,6 +227,7 @@ export type RawContextNode = {
     title: string | null;
     summary: string | null;
     annotations?: {
+        totalCount?: number;
         nodes: Array<{
             message: string;
         }>;

package/bin/github/batch-receipt-evidence.d.mts

@@ -0,0 +1,5 @@
+import type { RepoInfo } from "./client.mts";
+import type { RawContextNode, RawPr } from "./batch-raw-types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/** Keep the exact PollSummaryPr shape used by v1 receipts; add only complete annotation totals. */
+export declare function prepareBatchReceiptEvidence(summary: RawSummaryPr | null | undefined, batch: RawPr, checks: RawContextNode[], repo: RepoInfo): Promise<RawSummaryPr | null>;

package/bin/github/batch-receipt-evidence.mjs

@@ -0,0 +1,61 @@
+import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
+import { markReadyAnnotationProbeComplete } from "./poll-summary-annotation-probe.mjs";
+/** Keep the exact PollSummaryPr shape used by v1 receipts; add only complete annotation totals. */
+export async function prepareBatchReceiptEvidence(summary, batch, checks, repo) {
+    if (!summary ||
+        summary.number !== batch.number ||
+        summary.headRefOid !== batch.headRefOid ||
+        summary.baseRefOid !== batch.baseRefOid)
+        return null;
+    // Candidate evidence is best-effort. Wider windows need their own summary
+    // pagination, so use the existing standalone receipt path instead of issuing
+    // follow-ups from inside a full BatchPr read (which may have exhausted quota).
+    const headContexts = summary.commits.nodes[0]?.commit.statusCheckRollup?.contexts;
+    const queueContexts = summary.mergeQueueEntry?.headCommit?.statusCheckRollup?.contexts;
+    if (headContexts?.pageInfo.hasPreviousPage || queueContexts?.pageInfo.hasPreviousPage)
+        return null;
+    try {
+        await hydratePollSummaryChecks(summary, repo);
+    }
+    catch {
+        return null;
+    }
+    if (summary.mergeQueueEntry?.headCommit?.statusCheckRollup?.contexts.pageInfo.hasPreviousPage)
+        return null;
+    const summaryCommit = summary.commits.nodes[0]?.commit;
+    const batchCommit = batch.commits.nodes[0]?.commit;
+    if (!summaryCommit || summaryCommit.oid !== batchCommit?.oid)
+        return null;
+    const contexts = summaryCommit.statusCheckRollup?.contexts;
+    if (!contexts) {
+        if (batchCommit.statusCheckRollup !== null || checks.length > 0)
+            return null;
+        markReadyAnnotationProbeComplete(summary);
+        return summary;
+    }
+    if (contexts.pageInfo.hasPreviousPage || contexts.nodes.length !== contexts.totalCount)
+        return null;
+    if (checks.length !== contexts.totalCount)
+        return null;
+    const batchRuns = new Map();
+    for (const check of checks) {
+        if (check.__typename !== "CheckRun")
+            continue;
+        const count = check.annotations?.totalCount;
+        if (!Number.isSafeInteger(count) || count < 0 || batchRuns.has(check.id))
+            return null;
+        batchRuns.set(check.id, count);
+    }
+    const summaryRuns = contexts.nodes.filter((node) => node.__typename === "CheckRun");
+    if (summaryRuns.length !== batchRuns.size)
+        return null;
+    const seenSummaryIds = new Set();
+    for (const node of summaryRuns) {
+        if (!node.id || seenSummaryIds.has(node.id) || !batchRuns.has(node.id))
+            return null;
+        seenSummaryIds.add(node.id);
+        node.annotations = { totalCount: batchRuns.get(node.id) };
+    }
+    markReadyAnnotationProbeComplete(summary);
+    return summary;
+}

package/bin/github/batch.d.mts

@@ -1,5 +1,6 @@
 import { type RateLimitInfo, type RepoInfo } from "./client.mts";
 import type { WorkflowSuiteSnapshot } from "../checks/unreported-required.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
 import type { BatchPrData } from "../types.mts";
 import { type PrFingerprint } from "./fingerprint.mts";
 interface BatchResult {
@@ -12,6 +13,8 @@ interface BatchResult {
     headCheckSuitesEmpty?: true;
     /** Actions workflow suites on the head, excluding apps that have no workflow run. */
     headWorkflowSuites?: WorkflowSuiteSnapshot[];
+    /** Internal READY-receipt evidence from the same request, if complete. */
+    receiptSummary?: RawSummaryPr;
 }
 interface FetchPrBatchOptions {
     /**
@@ -23,6 +26,7 @@ interface FetchPrBatchOptions {
      * request — so there's no need to conditionally omit the field itself.
      */
     paginateApprovedReviews?: boolean;
+    includeReceiptSummary?: boolean;
 }
 /**
  * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.

package/bin/github/batch.mjs

@@ -1,6 +1,9 @@
 import { graphqlWithRateLimit } from "./client.mjs";
 import { hydrateThreadCommentPages } from "./thread-comments.mjs";
-import { BATCH_PR_QUERY } from "./queries.mjs";
+import { BATCH_PR_QUERY, BATCH_PR_RECEIPT_QUERY } from "./queries.mjs";
+import { prepareBatchReceiptEvidence } from "./batch-receipt-evidence.mjs";
+import { GitHubRequestError, isRetryableGraphQlResourceLimit, } from "./errors.mjs";
+import { rateLimitKind } from "./rate-limit-kind.mjs";
 import { parseRawPr } from "./batch-parsers.mjs";
 import { parseCheckSuitesComplete, parseHeadCheckSuitesEmpty, parseHeadWorkflowSuites, parseSuiteStartupFailures, } from "./batch-parse-suites.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
@@ -8,20 +11,50 @@ import { paginateBatchConnections } from "./batch-page.mjs";
 import { requireRawPr } from "./batch-response.mjs";
 import { hydrateMergeQueueChecks } from "./merge-queue-checks.mjs";
 import { fingerprintFromRaw } from "./fingerprint.mjs";
+function onlyReceiptSummaryErrors(errors) {
+    return (!!errors?.length &&
+        errors.every((error) => Array.isArray(error.path) &&
+            error.path[0] === "repository" &&
+            error.path[1] === "receiptSummary"));
+}
 /**
  * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
  */
 export async function fetchPrBatch(pr, repo, opts = {}) {
-    const result = await graphqlWithRateLimit(BATCH_PR_QUERY, {
+    const variables = {
         owner: repo.owner,
         repo: repo.name,
         pr,
-    });
+    };
+    let result;
+    try {
+        result = await graphqlWithRateLimit(opts.includeReceiptSummary ? BATCH_PR_RECEIPT_QUERY : BATCH_PR_QUERY, variables);
+    }
+    catch (error) {
+        if (!opts.includeReceiptSummary ||
+            !(error instanceof GitHubRequestError) ||
+            rateLimitKind(error) !== null ||
+            !(isRetryableGraphQlResourceLimit(error.graphqlErrors) ||
+                (error.status === 200 && onlyReceiptSummaryErrors(error.graphqlErrors))))
+            throw error;
+        // Receipt evidence is optional; a resource-limited combined query or an
+        // error confined to its sibling must not prevent the ordinary snapshot.
+        result = await graphqlWithRateLimit(BATCH_PR_QUERY, variables);
+    }
     const raw = requireRawPr(result.data, pr, repo);
-    await hydrateMergeQueueChecks(raw, repo);
-    const paged = await paginateBatchConnections(pr, repo, raw, opts, result.rateLimit);
-    const rawThreadPages = await hydrateThreadCommentPages(paged.threads);
-    const data = parseRawPr(raw, rawThreadPages, paged.comments, paged.changesRequested, paged.reviewSummaries, paged.approvedReviews, paged.checks, result.data.repository);
+    const queueRateLimit = await hydrateMergeQueueChecks(raw, repo, result.rateLimit);
+    const paged = await paginateBatchConnections(pr, repo, raw, opts, queueRateLimit);
+    const threadPages = await hydrateThreadCommentPages(paged.threads, paged.rateLimit);
+    let receiptSummary = null;
+    if (opts.includeReceiptSummary) {
+        try {
+            receiptSummary = await prepareBatchReceiptEvidence(result.data.repository?.receiptSummary, raw, paged.checks, repo);
+        }
+        catch {
+            // Malformed supplemental evidence must not discard a complete BatchPr.
+        }
+    }
+    const data = parseRawPr(raw, threadPages.threads, paged.comments, paged.changesRequested, paged.reviewSummaries, paged.approvedReviews, paged.checks, result.data.repository);
     const viewerLogin = result.data.viewer?.login;
     if (viewerLogin)
         data.viewerLogin = viewerLogin;
@@ -29,10 +62,11 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
     return {
         data,
         fingerprint: fingerprintFromRaw(raw, result.data.repository?.viewerPermission ?? null, result.data.viewer?.login ?? null),
-        rateLimit: paged.rateLimit ?? result.rateLimit,
+        rateLimit: threadPages.rateLimit ?? paged.rateLimit ?? result.rateLimit,
         ...(parseCheckSuitesComplete(raw) && { checkSuitesComplete: true }),
         ...(parseHeadCheckSuitesEmpty(raw) && { headCheckSuitesEmpty: true }),
         ...workflowSuites(raw),
+        ...(receiptSummary && { receiptSummary }),
     };
 }
 function workflowSuites(raw) {

package/bin/github/errors.d.mts

@@ -27,12 +27,15 @@ export declare class GitHubRequestError extends ShepherdError {
     readonly retryAfterSeconds?: number;
     readonly graphqlErrors?: GitHubGraphQlError[];
     readonly authSource?: string;
+    /** Response text without a request path; safe input for throttle classification. */
+    readonly responseMessage?: string;
     constructor(message: string, opts: {
         status: number;
         rateLimit?: RateLimitInfo;
         retryAfterSeconds?: number;
         graphqlErrors?: GitHubGraphQlError[];
         authSource?: string;
+        responseMessage?: string;
         /**
          * Bypasses status-based classification entirely — for callers that already
          * know the failure kind better than the HTTP status can express (e.g. a

package/bin/github/errors.mjs

@@ -1,4 +1,5 @@
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { rateLimitKind } from "./rate-limit-kind.mjs";
 // GitHub's GraphQL API reports field-level permission failures (e.g. a fine-grained
 // PAT missing a scope) as an `errors[].message` entry at HTTP 200, not as an HTTP
 // 401/403 — the transport-level request succeeded even though one field could not
@@ -47,16 +48,21 @@ export function isRetryableGraphQlResourceLimit(graphqlErrors) {
         return GRAPHQL_RESOURCE_LIMIT_MESSAGE.test(error.message);
     });
 }
-function classifyStatus(status, rateLimit, retryAfterSeconds, graphqlErrors) {
+function classifyStatus(status, message, responseMessage, rateLimit, retryAfterSeconds, graphqlErrors) {
     // Retry signals take priority over everything else: GitHub's secondary rate limit
     // returns 403 with a Retry-After header, which is a transient throttle — not the
     // permission-denied 403 a bad/missing token produces. Treat any retry signal as
     // TEMPFAIL first so it isn't shadowed by the checks below.
-    const rateLimitExhausted = rateLimit !== undefined && rateLimit.remaining <= 0;
-    if (status === 429 ||
+    const throttle = rateLimitKind({
+        status,
+        message,
+        responseMessage,
+        rateLimit,
+        retryAfterSeconds,
+        graphqlErrors,
+    });
+    if (throttle !== null ||
         status >= 500 ||
-        retryAfterSeconds !== undefined ||
-        rateLimitExhausted ||
         isRetryableGraphQlInternal(graphqlErrors) ||
         isRetryableGraphQlResourceLimit(graphqlErrors)) {
         return EXIT.TEMPFAIL;
@@ -75,14 +81,17 @@ export class GitHubRequestError extends ShepherdError {
     retryAfterSeconds;
     graphqlErrors;
     authSource;
+    /** Response text without a request path; safe input for throttle classification. */
+    responseMessage;
     constructor(message, opts) {
         super(message, opts.exitCodeOverride ??
-            classifyStatus(opts.status, opts.rateLimit, opts.retryAfterSeconds, opts.graphqlErrors));
+            classifyStatus(opts.status, message, opts.responseMessage, opts.rateLimit, opts.retryAfterSeconds, opts.graphqlErrors));
         this.name = "GitHubRequestError";
         this.status = opts.status;
         this.rateLimit = opts.rateLimit;
         this.retryAfterSeconds = opts.retryAfterSeconds;
         this.graphqlErrors = opts.graphqlErrors;
         this.authSource = opts.authSource;
+        this.responseMessage = opts.responseMessage;
     }
 }

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

@@ -174,6 +174,7 @@ query BatchPrPage(
                     title
                     summary
                     annotations(first: 1) {
+                      totalCount
                       nodes {
                         message
                       }