pr-shepherd 0.55.2 → 0.56.0

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

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

@@ -279,6 +279,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
                     title
                     summary
                     annotations(first: 1) {
+                      totalCount
                       nodes {
                         message
                       }

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

@@ -4,6 +4,14 @@ query PollSummaryAnnotationProbe(
   $oid: GitObjectID!
   $before: String
 ) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     object(oid: $oid) {
       __typename

package/bin/github/gql/reply-thread-comments.gql

@@ -0,0 +1,25 @@
+query ReplyThreadComments($id: ID!, $cursor: String!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  node(id: $id) {
+    __typename
+    ... on PullRequestReviewThread {
+      id
+      comments(first: 100, after: $cursor) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          body
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/reply-thread-transcripts.gql

@@ -0,0 +1,31 @@
+query ReplyThreadTranscripts($ids: [ID!]!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  nodes(ids: $ids) {
+    __typename
+    ... on PullRequestReviewThread {
+      id
+      pullRequest {
+        number
+        repository {
+          nameWithOwner
+        }
+      }
+      comments(first: 100) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          body
+        }
+      }
+    }
+  }
+}

package/bin/github/merge-queue-checks.d.mts

@@ -1,4 +1,5 @@
+import { type RateLimitInfo } from "./client.mts";
 import type { RepoInfo } from "./client.mts";
 import type { RawPr } from "./batch-raw-types.mts";
 /** Hydrate all status contexts for the active or most recently removed queue commit. */
-export declare function hydrateMergeQueueChecks(raw: RawPr, repo: RepoInfo): Promise<void>;
+export declare function hydrateMergeQueueChecks(raw: RawPr, repo: RepoInfo, initialRateLimit?: RateLimitInfo): Promise<RateLimitInfo | undefined>;

package/bin/github/merge-queue-checks.mjs

@@ -1,5 +1,6 @@
 import { parseCreatedAt } from "./batch-parser-helpers.mjs";
-import { graphql } from "./client.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
+import { GitHubRequestError } from "./errors.mjs";
 import { headPushUnixFromCheckNodes, queueRemovalAppliesToHead, } from "./queue-removal-freshness.mjs";
 import { requireContextNodes } from "./batch-response.mjs";
 import { COMMIT_CHECK_CONTEXTS_QUERY } from "./queries.mjs";
@@ -18,13 +19,20 @@ function initialQueueCursor(existing, oid) {
         return null;
     return nextPageCursor(existing, oid);
 }
-async function fetchQueuePage(oid, repo, cursor) {
-    const result = await graphql(COMMIT_CHECK_CONTEXTS_QUERY, {
+async function fetchQueuePage(oid, repo, cursor, gate) {
+    if (gate.rateLimit?.remaining === 0) {
+        throw new GitHubRequestError("GitHub GraphQL rate limit remaining is 0; merge queue check pagination incomplete", {
+            status: 403,
+            rateLimit: gate.rateLimit,
+        });
+    }
+    const result = await graphqlWithRateLimit(COMMIT_CHECK_CONTEXTS_QUERY, {
         owner: repo.owner,
         repo: repo.name,
         oid,
         ...(cursor !== null && { cursor }),
     });
+    gate.rateLimit = result.rateLimit ?? gate.rateLimit;
     const object = result.data.repository?.object;
     if (object?.__typename !== "Commit" || object.oid !== oid) {
         if (cursor === null)
@@ -33,13 +41,13 @@ async function fetchQueuePage(oid, repo, cursor) {
     }
     return object.statusCheckRollup?.contexts ?? null;
 }
-async function hydrateCommitContexts(commit, repo) {
+async function hydrateCommitContexts(commit, repo, gate) {
     const existing = commit.statusCheckRollup?.contexts;
     const nodes = existing ? [...requireContextNodes(existing.nodes)] : [];
     let cursor = initialQueueCursor(existing, commit.oid);
     while (cursor !== undefined) {
         // eslint-disable-next-line no-await-in-loop
-        const next = await fetchQueuePage(commit.oid, repo, cursor);
+        const next = await fetchQueuePage(commit.oid, repo, cursor, gate);
         if (!next) {
             if (cursor === null) {
                 cursor = undefined;
@@ -78,11 +86,13 @@ function currentRemovalCommit(raw) {
     return removal.beforeCommit;
 }
 /** Hydrate all status contexts for the active or most recently removed queue commit. */
-export async function hydrateMergeQueueChecks(raw, repo) {
+export async function hydrateMergeQueueChecks(raw, repo, initialRateLimit) {
+    const gate = { rateLimit: initialRateLimit };
     const active = raw.mergeQueueEntry?.headCommit;
     const removed = currentRemovalCommit(raw);
     if (active)
-        await hydrateCommitContexts(active, repo);
+        await hydrateCommitContexts(active, repo, gate);
     if (removed && removed.oid !== active?.oid)
-        await hydrateCommitContexts(removed, repo);
+        await hydrateCommitContexts(removed, repo, gate);
+    return gate.rateLimit;
 }

package/bin/github/merge-target-rules.d.mts

@@ -1,3 +1,4 @@
+import type { CheckExecutionContext } from "../commands/check-execution-context.mts";
 export interface MergeTargetStatus {
     contexts: string[];
     trunkBehindBy?: number;
@@ -17,7 +18,7 @@ export declare function loadMergeTargetStatus(input: {
     stack?: {
         baseRefName: string;
     } | null;
-}): Promise<MergeTargetStatus>;
+}, context?: CheckExecutionContext): Promise<MergeTargetStatus>;
 /**
  * Commits on the PR base that `headRef` does not contain.
  * Pass the head commit OID. A fork's branch name can exist on the base

package/bin/github/merge-target-rules.mjs

@@ -8,14 +8,14 @@ import { readStackTopology } from "./stack-read.mjs";
  * Required status contexts for the branch GitHub actually merges into.
  * A native stack uses the trunk ref, and `behindBy` is that trunk against the bottom open layer.
  */
-export async function loadMergeTargetStatus(input) {
+export async function loadMergeTargetStatus(input, context) {
     const trunk = input.stack?.baseRefName;
     if (!trunk)
         return { contexts: [...input.localContexts] };
     let headRef = input.headRefName;
     let stackBottomPr = input.pr;
     if (trunk !== input.baseRefName) {
-        const bottom = await bottomOpenLayer(input.pr, { owner: input.owner, name: input.name }, trunk);
+        const bottom = await bottomOpenLayer(input.pr, { owner: input.owner, name: input.name }, trunk, context);
         headRef = bottom.headRefName;
         stackBottomPr = bottom.number;
     }
@@ -26,8 +26,8 @@ export async function loadMergeTargetStatus(input) {
         stackBottomPr,
     };
 }
-async function bottomOpenLayer(pr, repo, trunk) {
-    const topology = await readStackTopology(pr, repo);
+async function bottomOpenLayer(pr, repo, trunk, context) {
+    const topology = await (context?.readStackTopology(pr, repo) ?? readStackTopology(pr, repo));
     const bottom = topology.ordered.find((member) => member.state === "OPEN" && member.baseRefName === trunk);
     if (!bottom) {
         throw new ShepherdError(`Native stack for PR #${pr} has no open layer based on ${trunk}`, EXIT.TEMPFAIL);

package/bin/github/poll-summary-annotation-probe.d.mts

@@ -1,5 +1,7 @@
 import { type RepoInfo } from "./client.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/** Annotation totals copied from the same full-snapshot request; no follow-up probe is needed. */
+export declare function markReadyAnnotationProbeComplete(pr: RawSummaryPr): void;
 /**
  * True when a ready layer's annotation probe failed or stopped short of every
  * check page. Callers must not store or compare a fingerprint of that snapshot:

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

@@ -4,6 +4,11 @@ import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
 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();
+/** Annotation totals copied from the same full-snapshot request; no follow-up probe is needed. */
+export function markReadyAnnotationProbeComplete(pr) {
+    COMPLETE_FROM_BATCH.add(pr);
+}
 /**
  * True when a ready layer's annotation probe failed or stopped short of every
  * check page. Callers must not store or compare a fingerprint of that snapshot:
@@ -24,6 +29,8 @@ export function readyFingerprint(raw, stored) {
  * a check gains an annotation.
  */
 export async function hydrateReadyAnnotationProbe(pr, repo, review) {
+    if (COMPLETE_FROM_BATCH.has(pr))
+        return;
     const checks = summarizePollSummaryChecks(pr);
     if (!isCurrentSummaryReady(pr, checks, review))
         return;

package/bin/github/queries.d.mts

@@ -14,6 +14,8 @@ export declare const BATCH_PR_PAGE_QUERY: string;
 export declare const PR_FINGERPRINT_QUERY: string;
 /** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
 export declare const POLL_SUMMARY_FRAGMENT: string;
+/** Exact compact summary sibling only when a one-PR READY receipt needs evidence. */
+export declare const BATCH_PR_RECEIPT_QUERY: string;
 /** Trunk branch rules plus how far `headRef` is behind that branch. */
 export declare const REF_RULES_QUERY: string;
 /** How far a non-stack head is behind its PR base. One compare, no rules payload. */
@@ -41,6 +43,9 @@ export declare const UPPER_LAYER_CONFLICT_TARGET_QUERY: string;
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export declare const REVIEW_THREAD_COMMENTS_QUERY: string;
+/** Requested review-thread transcripts for best-effort reply seen markers. */
+export declare const REPLY_THREAD_TRANSCRIPTS_QUERY: string;
+export declare const REPLY_THREAD_COMMENTS_QUERY: string;
 /** Fetch inline annotations for a single CheckRun by node ID. */
 export declare const CHECK_RUN_ANNOTATIONS_QUERY: string;
 /**

package/bin/github/queries.mjs

@@ -19,6 +19,8 @@ export const PR_FINGERPRINT_QUERY = withSharedFragments(gql("pr-fingerprint.gql"
 const POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT = gql("poll-summary-check-contexts.gql");
 /** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
 export const POLL_SUMMARY_FRAGMENT = `${gql("ref-rules.gql")}\n${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}`;
+/** Exact compact summary sibling only when a one-PR READY receipt needs evidence. */
+export const BATCH_PR_RECEIPT_QUERY = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}\n${BATCH_PR_QUERY.replace("    pullRequest(number: $pr) {", "    receiptSummary: pullRequest(number: $pr) { ...PollSummaryPr }\n    pullRequest(number: $pr) {")}`;
 /** Trunk branch rules plus how far `headRef` is behind that branch. */
 export const REF_RULES_QUERY = `${gql("ref-rules.gql")}\n${gql("ref-rules-query.gql")}`;
 /** How far a non-stack head is behind its PR base. One compare, no rules payload. */
@@ -46,6 +48,9 @@ export const UPPER_LAYER_CONFLICT_TARGET_QUERY = gql("upper-layer-conflict-targe
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export const REVIEW_THREAD_COMMENTS_QUERY = gql("review-thread-comments.gql");
+/** Requested review-thread transcripts for best-effort reply seen markers. */
+export const REPLY_THREAD_TRANSCRIPTS_QUERY = gql("reply-thread-transcripts.gql");
+export const REPLY_THREAD_COMMENTS_QUERY = gql("reply-thread-comments.gql");
 /** Fetch inline annotations for a single CheckRun by node ID. */
 export const CHECK_RUN_ANNOTATIONS_QUERY = gql("check-run-annotations.gql");
 /**

package/bin/github/rate-limit-kind.d.mts

@@ -0,0 +1,13 @@
+import type { RateLimitInfo } from "./http-utils.mts";
+export type RateLimitKind = "primary" | "secondary";
+/** Interpret GitHub's throttle signals independently of the quota resource header. */
+export declare function rateLimitKind(input: {
+    status: number;
+    message: string;
+    responseMessage?: string;
+    rateLimit?: RateLimitInfo;
+    retryAfterSeconds?: number;
+    graphqlErrors?: Array<{
+        message: string;
+    }>;
+}): RateLimitKind | null;

package/bin/github/rate-limit-kind.mjs

@@ -0,0 +1,25 @@
+/** Interpret GitHub's throttle signals independently of the quota resource header. */
+export function rateLimitKind(input) {
+    const exhausted = input.rateLimit !== undefined && input.rateLimit.remaining <= 0;
+    const responseText = input.responseMessage ?? input.message;
+    const graphqlMessages = (input.graphqlErrors ?? []).map((error) => error.message);
+    const textThrottleCapable = input.status === 403 || input.status === 429;
+    const explicitlySecondary = /secondary (?:rate )?limit|abuse detection/i;
+    if ((textThrottleCapable && explicitlySecondary.test(responseText)) ||
+        graphqlMessages.some((message) => explicitlySecondary.test(message))) {
+        return "secondary";
+    }
+    // A 429 with an empty primary bucket is an actual primary-limit response.
+    if (input.status === 429 && exhausted)
+        return "primary";
+    if (exhausted)
+        return "primary";
+    if (input.status === 429 ||
+        input.retryAfterSeconds !== undefined ||
+        (textThrottleCapable && /\brate limit\b/i.test(responseText)) ||
+        graphqlMessages.some((message) => /\brate limit\b/i.test(message))) {
+        // Without a measured empty bucket, do not spend REST core on a probe.
+        return "secondary";
+    }
+    return null;
+}

package/bin/github/reply-thread-transcripts.d.mts

@@ -0,0 +1,3 @@
+import { type RepoInfo } from "./client.mts";
+/** Best-effort transcript evidence; it never filters user-supplied mutation IDs. */
+export declare function fetchReplyThreadTranscripts(pr: number, repo: RepoInfo, requestedIds: readonly string[]): Promise<Map<string, string>>;