pr-shepherd 0.56.6 → 0.57.0

package/bin/github/poll-summary-review.mjs

@@ -1,14 +1,16 @@
 import { normalizeBotUsernames } from "../comments/authors.mjs";
 import { applyRules } from "../classify/apply.mjs";
-import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
+import { loadClassifyRules } from "../classify/loader.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
 import { classifyItem } from "../state/seen-comments.mjs";
+import { mutationWasDenied } from "../state/seen-comments.mjs";
+import { canGenerateGithubMutation } from "./mutation-policy.mjs";
 const THREAD_COMMENT_SEPARATOR = "\n\n--- thread comment ---\n\n";
 export async function summarizePollSummaryReview(raw, seen, viewerCanAdminister) {
     const config = loadConfig();
     const bots = normalizeBotUsernames(config.botUsernames);
-    const rules = await loadRules(discoverRuleFiles(getEffectiveCwd()));
+    const rules = await loadClassifyRules(getEffectiveCwd(), config.standardRules);
     let actionable = 0;
     let incomplete = raw.comments.pageInfo.hasPreviousPage ||
         raw.reviews.pageInfo.hasPreviousPage ||
@@ -37,24 +39,31 @@ export async function summarizePollSummaryReview(raw, seen, viewerCanAdminister)
         if (isSuppressed(rules, "changes-requested", review))
             continue;
         const isBot = review.author?.__typename === "Bot" || bots.has(review.author?.login.toLowerCase() ?? "");
-        if ((isBot && viewerCanAdminister) ||
+        if ((isBot &&
+            canGenerateGithubMutation(viewerCanAdminister, "dismiss") &&
+            !mutationWasDenied(review.id, review.body, seen)) ||
             classifyItem(review.id, review.body, seen) !== "unchanged")
             actionable += 1;
     }
     for (const thread of raw.reviewThreads.nodes) {
-        if (thread.comments.pageInfo.hasPreviousPage)
+        // The window holds the first comments. Past it, a new reply leaves the window
+        // unchanged, so a long thread cannot prove it was seen.
+        const truncated = thread.comments.pageInfo.hasPreviousPage;
+        if (truncated)
             incomplete = true;
-        const root = thread.rootComments?.nodes[0] ?? thread.comments.nodes[0];
+        const root = thread.comments.nodes[0];
         const transcript = thread.comments.nodes
             .map((comment) => comment.body)
             .join(THREAD_COMMENT_SEPARATOR);
         if (isSuppressed(rules, "review-thread", root, thread.id, thread.path, transcript))
             continue;
-        const repeatable = root?.viewerDidAuthor === true ||
-            root?.author?.__typename === "Bot" ||
-            bots.has(root?.author?.login.toLowerCase() ?? "");
-        const unseen = classifyItem(thread.id, transcript, seen) !== "unchanged";
-        if ((!thread.isResolved && (repeatable || unseen)) ||
+        const repeatable = !mutationWasDenied(thread.id, transcript, seen) &&
+            (root?.viewerDidAuthor === true ||
+                root?.author?.__typename === "Bot" ||
+                bots.has(root?.author?.login.toLowerCase() ?? ""));
+        const unseen = truncated || classifyItem(thread.id, transcript, seen) !== "unchanged";
+        if ((thread.isResolved === false && (repeatable || unseen)) ||
+            (thread.isResolved === undefined && unseen) ||
             ((thread.isResolved || thread.isOutdated) && unseen))
             actionable += 1;
     }
@@ -81,5 +90,8 @@ function isSuppressed(rules, kind, raw, id = raw?.id ?? "unknown", path, body =
         ...(raw?.url && { url: raw.url }),
         ...(kind === "review-thread" && { path }),
     };
-    return applyRules(rules, item).suppress === true;
+    const action = applyRules(rules, item);
+    // An auto-resolve match is hidden only once the full check minimizes or resolves it, or
+    // surfaces a denied mutation once; until then it stays actionable so that check runs.
+    return action.suppress === true && (action.autoResolve !== true || kind === "changes-requested");
 }

package/bin/github/poll-summary-route.mjs

@@ -1,4 +1,7 @@
 import { loadConfig } from "../config/load.mjs";
+import { isKnownMergeStateStatus, transportReadinessGaps } from "./transport-evidence.mjs";
+import { canGenerateGithubMutation } from "./mutation-policy.mjs";
+import { getGithubTransport, isCcrTransport } from "./transport.mjs";
 export function routePollSummary(raw, checks, review, opts) {
     const actions = loadConfig().actions;
     const state = normalizePollSummaryState(raw.state);
@@ -22,7 +25,13 @@ export function routePollSummary(raw, checks, review, opts) {
         return { action: "fix_code", reasons: ["unreported-required-checks"] };
     }
     if ((checks.inProgress ?? 0) > 0 ||
+        !isKnownMergeStateStatus(raw.mergeStateStatus) ||
         raw.mergeable === "UNKNOWN" ||
+        raw.mergeStateStatus === "UNKNOWN")
+        return { action: "wait", reasons: ["pending-or-unknown"] };
+    if (transportReadinessGaps(raw, raw.mergeStateStatus).length > 0)
+        return { action: "escalate", reasons: ["transport-unsupported"] };
+    if (raw.mergeable === "UNKNOWN" ||
         raw.mergeStateStatus === "UNKNOWN" ||
         raw.mergeStateStatus === "BEHIND" ||
         raw.mergeStateStatus === "BLOCKED" ||
@@ -33,15 +42,22 @@ export function routePollSummary(raw, checks, review, opts) {
         const autoMarkReadyDisabled = opts.noAutoMarkReady || actions.autoMarkReady === false;
         // The stack selector asks the agent to mark a disabled draft ready, so
         // that transition needs the same capability as the automatic one.
-        if (!raw.viewerCanUpdate && (!autoMarkReadyDisabled || opts.stackPrNumber !== undefined)) {
+        if (!canGenerateGithubMutation(raw.viewerCanUpdate, "ready") &&
+            (!autoMarkReadyDisabled || opts.stackPrNumber !== undefined)) {
+            const unsupported = getGithubTransport() === "rest" && raw.viewerCanUpdate !== false && !isCcrTransport();
+            if (unsupported)
+                return { action: "escalate", reasons: ["transport-unsupported"] };
             return { action: "escalate", reasons: ["mark-ready-authorization-required"] };
         }
         return autoMarkReadyDisabled
             ? { action: "wait", reasons: ["draft-auto-mark-ready-disabled"] }
             : { action: "mark_ready", reasons: ["draft-appears-ready"] };
     }
-    if (opts.merge && raw.isInMergeQueue) {
-        return { action: "wait", reasons: ["already-in-merge-queue"] };
+    if (opts.merge && (raw.isInMergeQueue || raw.autoMergeRequest)) {
+        return {
+            action: "wait",
+            reasons: [raw.isInMergeQueue ? "already-in-merge-queue" : "already-auto-merging"],
+        };
     }
     if (opts.merge && raw.stack && opts.stackPrNumber === undefined) {
         return { action: "fix_code", reasons: ["authoritative-poll-required"] };

package/bin/github/poll-summary-stack-page.d.mts

@@ -0,0 +1,11 @@
+import type { RepoInfo } from "./client.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+import { type StackRead } from "./stack-read.mts";
+/**
+ * Read the hydrated stack in pages of at most `stackSize` entries.
+ * A wide check matrix can blow GitHub's per-query resource limit on the full
+ * page. Halve `first` down to one entry and let `readStack` follow `after`.
+ * The shared summary fragment stays intact: one layer is the same shape as an
+ * explicit summary, and check hydration still completes windows past 100.
+ */
+export declare function readGraphqlStackSummary(anchor: number, repo: RepoInfo, stackSize: number): Promise<StackRead<RawSummaryPr>>;

package/bin/github/poll-summary-stack-page.mjs

@@ -0,0 +1,27 @@
+import { GitHubRequestError, isRetryableGraphQlResourceLimit } from "./errors.mjs";
+import { POLL_STACK_SUMMARY_QUERY } from "./queries.mjs";
+import { MAX_STACK_ENTRIES_PER_PAGE, readStack } from "./stack-read.mjs";
+/**
+ * Read the hydrated stack in pages of at most `stackSize` entries.
+ * A wide check matrix can blow GitHub's per-query resource limit on the full
+ * page. Halve `first` down to one entry and let `readStack` follow `after`.
+ * The shared summary fragment stays intact: one layer is the same shape as an
+ * explicit summary, and check hydration still completes windows past 100.
+ */
+export async function readGraphqlStackSummary(anchor, repo, stackSize) {
+    let ceiling = MAX_STACK_ENTRIES_PER_PAGE;
+    for (;;) {
+        const first = Math.max(1, Math.min(stackSize, ceiling));
+        try {
+            return await readStack(POLL_STACK_SUMMARY_QUERY, anchor, repo, { first }, ceiling);
+        }
+        catch (err) {
+            if (!(err instanceof GitHubRequestError) ||
+                !isRetryableGraphQlResourceLimit(err.graphqlErrors) ||
+                first <= 1) {
+                throw err;
+            }
+            ceiling = Math.floor(first / 2);
+        }
+    }
+}

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

@@ -3,5 +3,7 @@ import type { PollSummaryChecks } from "../types.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
 /** Current trunk rules may remain available on a merged layer's base ref. */
 export declare function trunkRequiredContexts(ordered: readonly RawSummaryPr[], repo: RepoInfo): Promise<string[] | undefined>;
+/** Required contexts of the layer's merge target: the trunk's for a stack layer when known. */
+export declare function summaryRequiredContexts(raw: RawSummaryPr, mergeTargetContexts: readonly string[] | undefined): string[];
 /** Record missing required contexts. A running Actions workflow does not clear the names. */
-export declare function applyUnreportedRequiredChecks(raw: RawSummaryPr, checks: PollSummaryChecks, mergeTargetContexts: readonly string[] | undefined): void;
+export declare function applyUnreportedRequiredChecks(raw: RawSummaryPr, checks: PollSummaryChecks, required: readonly string[]): void;

package/bin/github/poll-summary-unreported.mjs

@@ -16,15 +16,18 @@ export async function trunkRequiredContexts(ordered, repo) {
     const loaded = await loadRefRules(repo.owner, repo.name, `refs/heads/${trunk}`, bottom.headRefOid);
     return loaded.contexts;
 }
-/** Record missing required contexts. A running Actions workflow does not clear the names. */
-export function applyUnreportedRequiredChecks(raw, checks, mergeTargetContexts) {
+/** Required contexts of the layer's merge target: the trunk's for a stack layer when known. */
+export function summaryRequiredContexts(raw, mergeTargetContexts) {
     const trunk = raw.stack?.baseRefName;
-    const required = selectMergeTargetContexts({
+    return selectMergeTargetContexts({
         localContexts: parseBranchRules(raw.baseRef).requiredStatusCheckContexts,
         ...(mergeTargetContexts !== undefined && { trunkContexts: mergeTargetContexts }),
         baseRefName: raw.baseRefName,
         ...(trunk !== undefined && mergeTargetContexts !== undefined && { trunkRefName: trunk }),
     });
+}
+/** Record missing required contexts. A running Actions workflow does not clear the names. */
+export function applyUnreportedRequiredChecks(raw, checks, required) {
     const missing = unreportedRequiredContexts(required, reportedNames(raw));
     if (missing.length === 0)
         return;

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

@@ -1,12 +1,15 @@
 import type { PollSummaryCommandOptions, PollSummaryItem, PollSummarySelection, PollSummaryStackAncestry } from "../types.mts";
 import { type RepoInfo } from "./client.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
+import type { StackHandoffSource } from "./stack-handoff-page.mts";
 export interface FetchedPollSummary {
     selection: PollSummarySelection;
     prs: PollSummaryItem[];
     stackAncestry?: PollSummaryStackAncestry[];
     allowedMergeMethods?: import("../config/merge-method.mts").MergeMethod[];
+    /** GraphQL stack reads only: the raw layers a routing tick hands to its one-PR sessions. */
+    handoffSource?: StackHandoffSource;
 }
-export declare function fetchPollSummary(opts: PollSummaryCommandOptions, repo: RepoInfo): Promise<FetchedPollSummary>;
 /** Fresh, read-only snapshot used to bind a one-PR READY receipt to stack routing. */
 export declare function fetchRawSummaryPr(pr: number, repo: RepoInfo): Promise<RawSummaryPr>;
+export declare function fetchPollSummary(opts: PollSummaryCommandOptions, repo: RepoInfo): Promise<FetchedPollSummary>;

package/bin/github/poll-summary.mjs

@@ -1,22 +1,29 @@
+import { readRestStackSummary } from "./rest-stack-summary.mjs";
+import { githubOperation, getGithubTransport, runWithGithubTransport } from "./transport.mjs";
+import { readRestExplicitSummary } from "./rest-explicit-summary-read.mjs";
+import { withRestConditionalScope } from "./rest-conditional-scope.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
-import { GitHubRequestError, isRetryableGraphQlResourceLimit, missingRepositoryError, } from "./errors.mjs";
+import { missingRepositoryError } from "./errors.mjs";
 import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
 import { refreshUnknownSummaryMergeability } from "./poll-summary-mergeability.mjs";
 import { summarizePollSummaryPr } from "./poll-summary-projector.mjs";
 import { trunkRequiredContexts } from "./poll-summary-unreported.mjs";
-import { POLL_STACK_SUMMARY_QUERY, POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
-import { MAX_STACK_ENTRIES_PER_PAGE, readStack, readStackTopology, stackAncestryGaps, } from "./stack-read.mjs";
+import { loadStackSizeHint, storeStackSizeHint } from "./stack-size-hint.mjs";
+import { POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
+import { stackAncestryGaps } from "./stack-read.mjs";
+import { readGraphqlStackSummary } from "./poll-summary-stack-page.mjs";
+import { stackHandoffSource } from "./stack-handoff.mjs";
 const MAX_EXPLICIT_PRS_PER_QUERY = 50;
-export async function fetchPollSummary(opts, repo) {
+async function fetchSelectedPollSummary(opts, repo) {
     if (opts.stackPrNumber !== undefined)
         return fetchStackSummary(opts, repo);
-    const requested = deduplicate(opts.prNumbers ?? []);
+    const requested = [...new Set(opts.prNumbers ?? [])];
     if (requested.length === 0) {
         throw new ShepherdError("Aggregate poll requires at least two PRs or --stack <PR>", EXIT.USAGE);
     }
     const raw = [];
-    let viewerCanAdminister = false;
+    let viewerCanAdminister;
     for (let offset = 0; offset < requested.length; offset += MAX_EXPLICIT_PRS_PER_QUERY) {
         const chunk = requested.slice(offset, offset + MAX_EXPLICIT_PRS_PER_QUERY);
         const fetched = await fetchExplicitChunk(chunk, repo);
@@ -33,7 +40,7 @@ export async function fetchRawSummaryPr(pr, repo) {
     const fetched = await fetchExplicitChunk([pr], repo);
     return fetched.prs[0];
 }
-async function fetchExplicitChunk(prs, repo) {
+async function fetchGraphqlExplicitChunk(prs, repo) {
     const declarations = prs.map((_, index) => `$pr${index}: Int!`).join(", ");
     const aliases = prs
         .map((_, index) => `pr${index}: pullRequest(number: $pr${index}) { ...PollSummaryPr }`)
@@ -59,18 +66,39 @@ async function fetchExplicitChunk(prs, repo) {
     }
     return { prs: rawPrs, viewerCanAdminister: result.data.repository.viewerCanAdminister };
 }
+async function fetchExplicitChunk(prs, repo) {
+    return githubOperation("PollSummary", () => runWithGithubTransport("graphql", () => fetchGraphqlExplicitChunk(prs, repo)), async () => ({
+        prs: await withSummaryConditionalScope(repo, prs[0], () => readRestExplicitSummary(prs, repo)),
+    }));
+}
+/**
+ * Entries on an unsized first summary page. GitHub prices `first`, not the
+ * nodes returned, and four layers are the most that still price at 1 point.
+ * Larger stacks page on, sized to the entries that remain.
+ */
+const UNSIZED_STACK_SUMMARY_FIRST = 4;
 /**
- * Read the stack's topology first so the hydrated page requests only as many
- * entries as the stack holds: GitHub prices `first`, not the nodes returned.
+ * Size the hydrated page to the stack so it requests only as many entries as the
+ * stack holds. The size comes from the anchor's last summary; the first summary
+ * reads four entries and pages on, which never costs more than reading the
+ * topology first. A stack that has since grown pages on, and one that shrank
+ * overpays once.
  */
 async function fetchStackSummary(opts, repo) {
     const anchor = opts.stackPrNumber;
-    const topology = await readStackTopology(anchor, repo);
-    const { stackNumber, stackSize, viewerLogin, viewerCanAdminister, ordered, allowedMergeMethods } = await readStackSummary(anchor, repo, topology.stackSize);
+    const stateKey = { owner: repo.owner, repo: repo.name, pr: anchor };
+    const graphql = getGithubTransport() !== "rest";
+    const hint = graphql ? await loadStackSizeHint(stateKey) : 0;
+    const sizeHint = hint || UNSIZED_STACK_SUMMARY_FIRST;
+    const read = await readStackSummary(anchor, repo, sizeHint);
+    const { stackNumber, stackSize, viewerLogin, viewerCanAdminister, ordered, allowedMergeMethods } = read;
+    if (graphql && stackSize !== hint)
+        await storeStackSizeHint(stateKey, stackSize);
     for (const pr of ordered) {
         await hydratePollSummaryChecks(pr, repo);
         await refreshUnknownSummaryMergeability(pr, repo);
     }
+    const handoffSource = getGithubTransport() === "rest" ? undefined : stackHandoffSource(read);
     const stackAncestry = stackAncestryGaps(ordered);
     const required = await trunkRequiredContexts(ordered, repo);
     return {
@@ -78,30 +106,16 @@ async function fetchStackSummary(opts, repo) {
         prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister, required, viewerLogin))),
         ...(stackAncestry.length > 0 && { stackAncestry }),
         ...(allowedMergeMethods && { allowedMergeMethods }),
+        ...(handoffSource && { handoffSource }),
     };
 }
-/**
- * A wide check matrix can blow GitHub's per-query resource limit on the full
- * page. Halve `first` down to one entry and let `readStack` follow `after`.
- * The shared summary fragment stays intact: one layer is the same shape as an
- * explicit summary, and check hydration still completes windows past 100.
- */
 async function readStackSummary(anchor, repo, stackSize) {
-    let first = Math.min(stackSize, MAX_STACK_ENTRIES_PER_PAGE);
-    for (;;) {
-        try {
-            return await readStack(POLL_STACK_SUMMARY_QUERY, anchor, repo, { first });
-        }
-        catch (err) {
-            if (!(err instanceof GitHubRequestError) ||
-                !isRetryableGraphQlResourceLimit(err.graphqlErrors) ||
-                first <= 1) {
-                throw err;
-            }
-            first = Math.floor(first / 2);
-        }
-    }
+    return githubOperation("PollStackSummary", () => readGraphqlStackSummary(anchor, repo, stackSize), () => withSummaryConditionalScope(repo, anchor, () => readRestStackSummary(anchor, repo)));
+}
+/** REST summary reads are conditional under the anchor PR's state: an unchanged body is a free 304. */
+function withSummaryConditionalScope(repo, pr, read) {
+    return withRestConditionalScope({ owner: repo.owner, repo: repo.name, pr }, read);
 }
-function deduplicate(values) {
-    return [...new Set(values)];
+export function fetchPollSummary(opts, repo) {
+    return githubOperation("PollSummarySelection", () => runWithGithubTransport("graphql", () => fetchSelectedPollSummary(opts, repo)), () => fetchSelectedPollSummary(opts, repo));
 }

package/bin/github/queries.d.mts

@@ -10,11 +10,13 @@
 export declare const BATCH_PR_QUERY: string;
 /** Slim @include follow-up for outstanding batch-query connections. */
 export declare const BATCH_PR_PAGE_QUERY: string;
-/** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
-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. */
+/**
+ * Exact compact summary sibling only when a one-PR READY receipt needs evidence.
+ * The batch's first context page shrinks to 50 so the sibling still prices at 1 point;
+ * `BatchPrPage` reads any further contexts.
+ */
 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;
@@ -68,3 +70,5 @@ export declare const MARK_PR_READY_MUTATION: string;
 export declare const GET_PR_BODY_QUERY: string;
 /** Update the PR body. */
 export declare const UPDATE_PR_BODY_MUTATION: string;
+/** CheckRun titles, summaries, and first annotations for routed stack-layer handoffs. */
+export declare const STACK_HANDOFF_CHECK_RUNS_QUERY: string;

package/bin/github/queries.mjs

@@ -14,13 +14,15 @@ const withSharedFragments = (query) => `${gql("ref-rules.gql")}\n${gql("pr-merge
 export const BATCH_PR_QUERY = withSharedFragments(gql("batch-pr.gql"));
 /** Slim @include follow-up for outstanding batch-query connections. */
 export const BATCH_PR_PAGE_QUERY = gql("batch-pr-page.gql");
-/** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
-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) {")}`;
+/**
+ * Exact compact summary sibling only when a one-PR READY receipt needs evidence.
+ * The batch's first context page shrinks to 50 so the sibling still prices at 1 point;
+ * `BatchPrPage` reads any further contexts.
+ */
+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) {").replace("contexts(first: 100) {", "contexts(first: 50) {")}`;
 /** 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. */
@@ -73,3 +75,5 @@ export const MARK_PR_READY_MUTATION = gql("mark-pr-ready.gql");
 export const GET_PR_BODY_QUERY = gql("get-pr-body.gql");
 /** Update the PR body. */
 export const UPDATE_PR_BODY_MUTATION = gql("update-pr-body.gql");
+/** CheckRun titles, summaries, and first annotations for routed stack-layer handoffs. */
+export const STACK_HANDOFF_CHECK_RUNS_QUERY = gql("stack-handoff-check-runs.gql");

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

@@ -0,0 +1,7 @@
+import type { RateLimitInfo } from "./http-utils.mts";
+/**
+ * Same reset window: the lowest remaining and the highest used, taken independently. The Claude
+ * Code proxy can answer one tick's routes with `X-RateLimit-Used` values that disagree with each
+ * other and with `X-RateLimit-Remaining`, so neither half of one sample is trusted over the other.
+ */
+export declare function mostConservativeSample<T extends Pick<RateLimitInfo, "remaining" | "used">>(current: T, candidate: T): T;

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

@@ -0,0 +1,12 @@
+/**
+ * Same reset window: the lowest remaining and the highest used, taken independently. The Claude
+ * Code proxy can answer one tick's routes with `X-RateLimit-Used` values that disagree with each
+ * other and with `X-RateLimit-Remaining`, so neither half of one sample is trusted over the other.
+ */
+export function mostConservativeSample(current, candidate) {
+    const base = candidate.remaining < current.remaining ? candidate : current;
+    const used = current.used === undefined || candidate.used === undefined
+        ? (current.used ?? candidate.used)
+        : Math.max(current.used, candidate.used);
+    return { ...base, ...(used !== undefined && { used }) };
+}

package/bin/github/reply-recovery-read.d.mts

@@ -0,0 +1,50 @@
+import { type RepoInfo } from "./client.mts";
+export interface ReplyEvidence {
+    viewer: string;
+    comments: Array<{
+        id: string;
+        body: string;
+        author: string | null;
+    }>;
+}
+interface Page {
+    totalCount: number;
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor: string | null;
+    };
+    nodes: Array<{
+        id: string;
+        databaseId: number;
+        body: string;
+        author: {
+            login: string;
+        } | null;
+    }>;
+}
+interface Node {
+    id: string;
+    pullRequest: {
+        number: number;
+        repository: {
+            nameWithOwner: string;
+        };
+    };
+    comments: Page;
+}
+export interface ReplyEvidenceResponse {
+    viewer: {
+        login: string;
+    } | null;
+    nodes: Array<Node | null>;
+}
+/** Thread selection shared with the `apply review` preflight, which needs `$cursor: String`. */
+export declare const REPLY_EVIDENCE_THREAD_SELECTION = "... on PullRequestReviewThread {\n    id pullRequest { number repository { nameWithOwner } }\n    comments(first: 100, after: $cursor) {\n      totalCount\n      pageInfo { hasNextPage endCursor }\n      nodes { id databaseId body author { login } }\n    }\n  }";
+/**
+ * Complete evidence for one GraphQL thread, starting from a response that already holds its first
+ * comment page. Later pages use `ReplyRecoveryEvidence`. Throws when anything is unverifiable.
+ */
+export declare function threadReplyEvidence(repo: RepoInfo, pr: number, id: string, first: ReplyEvidenceResponse): Promise<ReplyEvidence>;
+/** Complete, bounded evidence for one mutation batch; unavailable evidence never certifies a retry. */
+export declare function readReplyRecoveryEvidence(repo: RepoInfo, pr: number, requestedIds: readonly string[]): Promise<Map<string, ReplyEvidence>>;
+export {};

package/bin/github/reply-recovery-read.mjs

@@ -0,0 +1,118 @@
+import { graphqlWithRateLimit } from "./client.mjs";
+import { githubOperation } from "./transport.mjs";
+import { recordThreadIdentity, resolveGraphqlThreadId, resolveRestThreadRoot, } from "./rest-identities.mjs";
+import { readRest, readRestPages, restRepoPath } from "./rest-reader-core.mjs";
+import { mapPool } from "../util/pool.mjs";
+/** Thread selection shared with the `apply review` preflight, which needs `$cursor: String`. */
+export const REPLY_EVIDENCE_THREAD_SELECTION = `... on PullRequestReviewThread {
+    id pullRequest { number repository { nameWithOwner } }
+    comments(first: 100, after: $cursor) {
+      totalCount
+      pageInfo { hasNextPage endCursor }
+      nodes { id databaseId body author { login } }
+    }
+  }`;
+const QUERY = `query ReplyRecoveryEvidence($ids: [ID!]!, $cursor: String) {
+  _shepherdRateLimit: rateLimit { cost limit nodeCount remaining resetAt used }
+  viewer { login }
+  nodes(ids: $ids) { ${REPLY_EVIDENCE_THREAD_SELECTION} }
+}`;
+const readEvidencePage = (ids, cursor) => graphqlWithRateLimit(QUERY, { ids, cursor });
+/**
+ * Complete evidence for one GraphQL thread, starting from a response that already holds its first
+ * comment page. Later pages use `ReplyRecoveryEvidence`. Throws when anything is unverifiable.
+ */
+export async function threadReplyEvidence(repo, pr, id, first) {
+    const viewer = first.viewer?.login;
+    if (typeof viewer !== "string" || !viewer)
+        throw new Error("Reply recovery viewer is unavailable");
+    let node = first.nodes.find((item) => item?.id === id);
+    const comments = [];
+    const cursors = new Set();
+    const total = node?.comments?.totalCount;
+    const root = node?.comments?.nodes?.[0]?.databaseId;
+    const seenIds = new Set();
+    for (let page = 0; page < 100; page++) {
+        if (!node ||
+            node.pullRequest?.number !== pr ||
+            node.pullRequest.repository.nameWithOwner.toLowerCase() !==
+                `${repo.owner}/${repo.name}`.toLowerCase() ||
+            !node.comments?.pageInfo ||
+            typeof node.comments.pageInfo.hasNextPage !== "boolean" ||
+            !Array.isArray(node.comments.nodes) ||
+            !Number.isSafeInteger(total) ||
+            total < 1 ||
+            node.comments.totalCount !== total)
+            throw new Error("Reply recovery transcript is unavailable");
+        if (page === 0) {
+            if (!Number.isSafeInteger(root) || root < 1)
+                throw new Error("Reply recovery root identity is unavailable");
+            await recordThreadIdentity(repo, pr, id, root);
+        }
+        for (const comment of node.comments.nodes) {
+            if (typeof comment.id !== "string" ||
+                !comment.id ||
+                seenIds.has(comment.id) ||
+                typeof comment.body !== "string" ||
+                (comment.author !== null && typeof comment.author?.login !== "string"))
+                throw new Error("Reply recovery comment is incomplete");
+            seenIds.add(comment.id);
+            comments.push({ id: comment.id, body: comment.body, author: comment.author?.login ?? null });
+        }
+        if (!node.comments.pageInfo.hasNextPage && comments.length === total)
+            return { viewer, comments };
+        if (!node.comments.pageInfo.hasNextPage)
+            break;
+        const cursor = node.comments.pageInfo.endCursor;
+        if (!cursor || cursors.has(cursor))
+            break;
+        cursors.add(cursor);
+        const next = await readEvidencePage([id], cursor);
+        if (next.data.viewer?.login !== viewer)
+            throw new Error("Reply recovery viewer changed");
+        node = next.data.nodes.find((item) => item?.id === id);
+    }
+    throw new Error("Reply recovery transcript pagination is incomplete");
+}
+/** Complete, bounded evidence for one mutation batch; unavailable evidence never certifies a retry. */
+export async function readReplyRecoveryEvidence(repo, pr, requestedIds) {
+    if (requestedIds.length === 0)
+        return new Map();
+    if (requestedIds.length > 10)
+        throw new Error("Reply recovery batch exceeds 10 threads");
+    return githubOperation("ReplyRecoveryEvidence", async () => {
+        const ids = await Promise.all(requestedIds.map(resolveGraphqlThreadId));
+        const first = await readEvidencePage(ids, null);
+        const viewer = first.data.viewer?.login;
+        if (typeof viewer !== "string" || !viewer)
+            throw new Error("Reply recovery viewer is unavailable");
+        const entries = await mapPool(ids, 4, async (id, index) => [requestedIds[index], await threadReplyEvidence(repo, pr, id, first.data)]);
+        return new Map(entries);
+    }, async () => {
+        const viewer = await readRest("GET", "/user");
+        if (typeof viewer.login !== "string" || !viewer.login)
+            throw new Error("Reply recovery viewer is unavailable");
+        const inline = (await readRestPages(`${restRepoPath(repo)}/pulls/${pr}/comments`)).nodes;
+        const entries = await Promise.all(requestedIds.map(async (id) => {
+            const root = await resolveRestThreadRoot(repo, pr, id);
+            if (!inline.some((comment) => String(comment.id) === root))
+                throw new Error("Reply recovery thread is unavailable");
+            const comments = inline
+                .filter((comment) => String(comment.id) === root || String(comment.in_reply_to_id) === root)
+                .map((comment) => {
+                if (typeof comment.node_id !== "string" ||
+                    !comment.node_id ||
+                    typeof comment.body !== "string" ||
+                    (comment.user !== null && typeof comment.user?.login !== "string"))
+                    throw new Error("Reply recovery comment is incomplete");
+                return {
+                    id: comment.node_id,
+                    body: comment.body,
+                    author: comment.user?.login ?? null,
+                };
+            });
+            return [id, { viewer: viewer.login, comments }];
+        }));
+        return new Map(entries);
+    });
+}

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

@@ -1,3 +1,2 @@
 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>>;

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

@@ -1,3 +1,6 @@
+import { githubOperation } from "./transport.mjs";
+import { readRestFeedback } from "./rest-feedback-read.mjs";
+import { resolveRestThreadRoot, restThreadId } from "./rest-identities.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { rateLimitKind } from "./rate-limit-kind.mjs";
@@ -8,7 +11,7 @@ const IDS_PER_REQUEST = 20;
 const CONCURRENCY = 4;
 const MAX_COMMENT_PAGES = 100;
 /** Best-effort transcript evidence; it never filters user-supplied mutation IDs. */
-export async function fetchReplyThreadTranscripts(pr, repo, requestedIds) {
+async function fetchGraphqlReplyThreadTranscripts(pr, repo, requestedIds) {
     const ids = [...new Set(requestedIds)];
     if (ids.length === 0)
         return new Map();
@@ -87,3 +90,23 @@ async function completeThread(thread, isStopped, stop) {
 function isThrottle(error) {
     return error instanceof GitHubRequestError && rateLimitKind(error) !== null;
 }
+export function fetchReplyThreadTranscripts(pr, repo, requestedIds) {
+    if (requestedIds.length === 0)
+        return Promise.resolve(new Map());
+    return githubOperation("ReplyThreadTranscripts", () => fetchGraphqlReplyThreadTranscripts(pr, repo, requestedIds), async () => {
+        const feedback = await readRestFeedback(pr, repo);
+        const result = new Map();
+        for (const id of new Set(requestedIds)) {
+            try {
+                const root = await resolveRestThreadRoot(repo, pr, id);
+                const thread = feedback.threads.find((thread) => thread.id === restThreadId(root));
+                if (thread)
+                    result.set(id, threadTranscriptBodies((thread.comments ?? []).map((comment) => comment.body)));
+            }
+            catch {
+                /* Transcript evidence never prohibits an explicit mutation. */
+            }
+        }
+        return result;
+    });
+}

package/bin/github/rest-annotation-read.d.mts

@@ -0,0 +1,5 @@
+import type { CheckAnnotation } from "../types.mts";
+import type { AnnotationCacheOptions } from "./check-annotation-cache.mts";
+/** An annotation fallback can follow a GraphQL snapshot with no persisted REST check IDs. */
+export declare function ensureRestCheckIdentities(checkRunIds: string[], scope?: AnnotationCacheOptions): Promise<void>;
+export declare function readRestCheckAnnotations(checkRunId: string, scope?: AnnotationCacheOptions): Promise<CheckAnnotation[]>;