pr-shepherd 0.56.6 → 0.57.0

package/bin/github/batch.mjs

@@ -1,3 +1,6 @@
+import { recordThreadIdentity } from "./rest-identities.mjs";
+import { githubOperation, runWithGithubTransport } from "./transport.mjs";
+import { fetchRestPrBatch } from "./rest-batch-read.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { hydrateThreadCommentPages } from "./thread-comments.mjs";
 import { BATCH_PR_QUERY, BATCH_PR_RECEIPT_QUERY } from "./queries.mjs";
@@ -5,30 +8,24 @@ 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 { parseCheckSuitesComplete, parseHeadCheckSuitesEmpty, workflowSuites, parseSuiteStartupFailures, } from "./batch-parse-suites.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
 import { paginateBatchConnections } from "./batch-page.mjs";
 import { requireRawPr } from "./batch-response.mjs";
 import { hydrateMergeQueueChecks } from "./merge-queue-checks.mjs";
 import { fingerprintFromRaw } from "./fingerprint.mjs";
+import { stackEvidenceFromRaw } from "./batch-stack-evidence.mjs";
+import { takeStackHandoff } from "./stack-handoff.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 variables = {
-        owner: repo.owner,
-        repo: repo.name,
-        pr,
-    };
-    let result;
+async function readBatchFirstPage(pr, repo, opts) {
+    const variables = { owner: repo.owner, repo: repo.name, pr };
     try {
-        result = await graphqlWithRateLimit(opts.includeReceiptSummary ? BATCH_PR_RECEIPT_QUERY : BATCH_PR_QUERY, variables);
+        return await graphqlWithRateLimit(opts.includeReceiptSummary ? BATCH_PR_RECEIPT_QUERY : BATCH_PR_QUERY, variables);
     }
     catch (error) {
         if (!opts.includeReceiptSummary ||
@@ -39,9 +36,23 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
             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);
+        return graphqlWithRateLimit(BATCH_PR_QUERY, variables);
     }
+}
+/**
+ * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
+ */
+async function fetchGraphqlPrBatch(pr, repo, opts = {}, reuse) {
+    const handoff = await takeStackHandoff(repo, pr); // a routed stack layer's first read
+    const result = handoff ? { data: handoff } : await readBatchFirstPage(pr, repo, opts);
     const raw = requireRawPr(result.data, pr, repo);
+    const fingerprint = fingerprintFromRaw(raw, result.data.repository?.viewerPermission ?? null, result.data.viewer?.login ?? null);
+    // Decide reuse from the first page alone, before any supplement is paid for.
+    const reused = reuse && (await reuse(fingerprint));
+    const baseTipOid = raw.baseRef?.target?.oid;
+    const stackEvidence = stackEvidenceFromRaw(raw, result.data);
+    if (reused)
+        return { reused, ...(baseTipOid && { baseTipOid }), ...(stackEvidence && { stackEvidence }) };
     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);
@@ -54,6 +65,12 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
             // Malformed supplemental evidence must not discard a complete BatchPr.
         }
     }
+    for (const thread of threadPages.threads) {
+        const root = thread.comments.nodes[0];
+        const numericId = root?.url?.match(/discussion_r([0-9]+)/)?.[1];
+        if (numericId)
+            await recordThreadIdentity(repo, pr, thread.id, numericId);
+    }
     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)
@@ -61,15 +78,15 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
     data.checks = mergeStartupFailureChecks(data.checks, parseSuiteStartupFailures(raw));
     return {
         data,
-        fingerprint: fingerprintFromRaw(raw, result.data.repository?.viewerPermission ?? null, result.data.viewer?.login ?? null),
+        fingerprint,
         rateLimit: threadPages.rateLimit ?? paged.rateLimit ?? result.rateLimit,
         ...(parseCheckSuitesComplete(raw) && { checkSuitesComplete: true }),
         ...(parseHeadCheckSuitesEmpty(raw) && { headCheckSuitesEmpty: true }),
         ...workflowSuites(raw),
         ...(receiptSummary && { receiptSummary }),
+        ...(stackEvidence && { stackEvidence }),
     };
 }
-function workflowSuites(raw) {
-    const suites = parseHeadWorkflowSuites(raw);
-    return suites.length > 0 ? { headWorkflowSuites: suites } : {};
+export function fetchPrBatch(pr, repo, opts = {}, reuse) {
+    return githubOperation("BatchPr", () => runWithGithubTransport("graphql", () => fetchGraphqlPrBatch(pr, repo, opts, reuse)), () => fetchRestPrBatch(pr, repo, opts));
 }

package/bin/github/check-annotations-batch.d.mts

@@ -8,10 +8,5 @@ interface CheckAnnotationBatchResult {
     annotations: Map<string, CheckAnnotation[]>;
     failures: AnnotationBatchFailure[];
 }
-/**
- * First annotation page for every uncached id, in chunks of 20. Further pages
- * use the single-node query and only run when that first page has `hasNextPage`.
- * A retryable rate limit aborts the remaining chunks and pages.
- */
 export declare function fetchCheckRunAnnotationsBatch(checkRunIds: string[], cacheOpts?: AnnotationCacheOptions): Promise<CheckAnnotationBatchResult>;
 export {};

package/bin/github/check-annotations-batch.mjs

@@ -1,3 +1,6 @@
+import { githubOperation, runWithGithubTransport, isGithubReadFallbackError, } from "./transport.mjs";
+import { mapPool } from "../util/pool.mjs";
+import { ensureRestCheckIdentities } from "./rest-annotation-read.mjs";
 import { pollRateLimitRetryAfterMs } from "../commands/poll-quota.mjs";
 import { readFreshCheckAnnotations, } from "./check-annotation-cache.mjs";
 import {} from "./check-annotation-shape.mjs";
@@ -24,7 +27,7 @@ function retryableRateLimit(err) {
  * use the single-node query and only run when that first page has `hasNextPage`.
  * A retryable rate limit aborts the remaining chunks and pages.
  */
-export async function fetchCheckRunAnnotationsBatch(checkRunIds, cacheOpts) {
+async function fetchGraphqlCheckRunAnnotationsBatch(checkRunIds, cacheOpts) {
     const annotations = new Map();
     const failures = [];
     const cached = await Promise.all(checkRunIds.map((id) => readFreshCheckAnnotations(id, cacheOpts)));
@@ -48,7 +51,7 @@ async function fetchChunk(chunk, annotations, failures, cacheOpts) {
         await applyBatchNodes(chunk, nodes, annotations, failures, cacheOpts);
     }
     catch (err) {
-        if (retryableRateLimit(err))
+        if (retryableRateLimit(err) || isGithubReadFallbackError(err))
             throw err;
         // A non-rate-limit batch failure (one NOT_FOUND or FORBIDDEN node rejects
         // the whole `nodes(ids:)` request) must not drop the other ids.
@@ -67,7 +70,7 @@ async function applyBatchNodes(chunk, nodes, annotations, failures, cacheOpts) {
             annotations.set(id, await fetchCheckRunAnnotations(id, cacheOpts, node.annotations));
         }
         catch (err) {
-            if (retryableRateLimit(err))
+            if (retryableRateLimit(err) || isGithubReadFallbackError(err))
                 throw err;
             failures.push({ checkRunId: id, error: err });
         }
@@ -80,7 +83,7 @@ async function fetchChunkOneByOne(chunk, annotations, failures, cacheOpts) {
             annotations.set(id, await fetchCheckRunAnnotations(id, cacheOpts));
         }
         catch (err) {
-            if (retryableRateLimit(err))
+            if (retryableRateLimit(err) || isGithubReadFallbackError(err))
                 throw err;
             failures.push({ checkRunId: id, error: err });
         }
@@ -90,3 +93,21 @@ async function requestFirstPages(ids) {
     const res = await graphql(CHECK_RUN_ANNOTATIONS_BATCH_QUERY, { ids }, { allowPartialData: true });
     return res.data.nodes ?? [];
 }
+export function fetchCheckRunAnnotationsBatch(checkRunIds, cacheOpts) {
+    return githubOperation("CheckRunAnnotationsBatch", () => runWithGithubTransport("graphql", () => fetchGraphqlCheckRunAnnotationsBatch(checkRunIds, cacheOpts)), async () => {
+        const annotations = new Map();
+        const failures = [];
+        await ensureRestCheckIdentities(checkRunIds, cacheOpts);
+        await mapPool([...new Set(checkRunIds)], 4, async (id) => {
+            try {
+                annotations.set(id, await fetchCheckRunAnnotations(id, cacheOpts));
+            }
+            catch (error) {
+                if (retryableRateLimit(error))
+                    throw error;
+                failures.push({ checkRunId: id, error });
+            }
+        });
+        return { annotations, failures };
+    });
+}

package/bin/github/check-annotations.mjs

@@ -1,3 +1,5 @@
+import { githubOperation } from "./transport.mjs";
+import { readRestCheckAnnotations } from "./rest-annotation-read.mjs";
 import { readFreshCheckAnnotations, storeCheckAnnotations, } from "./check-annotation-cache.mjs";
 import { collectAnnotations } from "./check-annotation-pages.mjs";
 /**
@@ -14,7 +16,7 @@ export async function fetchCheckRunAnnotations(checkRunId, cacheOpts, initialPag
         if (cached)
             return cached;
     }
-    const annotations = await collectAnnotations(checkRunId, initialPage);
+    const annotations = await githubOperation("CheckRunAnnotations", () => collectAnnotations(checkRunId, initialPage), () => readRestCheckAnnotations(checkRunId, cacheOpts));
     await storeCheckAnnotations(checkRunId, annotations, cacheOpts);
     return annotations;
 }

package/bin/github/client.d.mts

@@ -1,10 +1,3 @@
-/**
- * High-level GitHub client — wraps http.mts for application-level concerns.
- *
- * All GitHub I/O goes through native fetch (via http.mts); the `gh` CLI is no
- * longer used for GitHub API calls, but may be invoked as an auth-token
- * fallback via `gh auth token` when neither GH_TOKEN nor GITHUB_TOKEN is set.
- */
 import type { MergeableState, MergeStateStatus } from "../types.mts";
 export type { RateLimitInfo } from "./http.mts";
 export { graphql, graphqlWithRateLimit } from "./http.mts";
@@ -22,22 +15,11 @@ export declare function getRepoInfo(): Promise<RepoInfo>;
  * Returns null if no open PR is found.
  */
 export declare function getCurrentPrNumber(): Promise<number | null>;
-/** Returns the PR number for a given branch, or null if no open PR is found. */
-export declare function getPrNumberForBranch(branch: string, owner: string, repo: string): Promise<number | null>;
-/** Returns the `headRefOid` (commit SHA) of the given PR as reported by GitHub. */
-export declare function getPrHeadSha(pr: number, owner: string, name: string): Promise<string>;
-/** Fetches the node ID and body text for a PR. GitHub returns null body for empty bodies — coerced to "". */
-export declare function getPullRequestBody(pr: number, owner: string, name: string): Promise<{
-    nodeId: string;
-    body: string;
-}>;
-/** Overwrites the PR body. */
-export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;
 /**
  * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
  * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
- * READY state. The same response carries state so a concurrent merge or
+ * READY state. The read is conditional inside a PR's REST conditional scope. The same response carries state so a concurrent merge or
  * close can supersede the earlier GraphQL snapshot without another request.
  */
 export declare function getMergeableState(pr: number, owner: string, repo: string): Promise<{
@@ -46,3 +28,10 @@ export declare function getMergeableState(pr: number, owner: string, repo: strin
     state?: "OPEN" | "CLOSED" | "MERGED";
 }>;
 export declare function getCurrentBranch(): Promise<string>;
+export declare function getPrNumberForBranch(branch: string, owner: string, name: string): Promise<number | null>;
+export declare function getPrHeadSha(pr: number, owner: string, name: string): Promise<string>;
+export declare function getPullRequestBody(pr: number, owner: string, name: string): Promise<{
+    nodeId: string;
+    body: string;
+}>;
+export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;

package/bin/github/client.mjs

@@ -1,3 +1,7 @@
+import { githubOperation } from "./transport.mjs";
+import { readRestPull } from "./rest-pr-core.mjs";
+import { readRest, readRestPages, restRepoPath, restObject, restNumber, restString, } from "./rest-reader-core.mjs";
+import { recordRestIdentity, resolveRestIdentity } from "./rest-identities.mjs";
 /* eslint-disable max-lines */
 /**
  * High-level GitHub client — wraps http.mts for application-level concerns.
@@ -44,17 +48,12 @@ export async function getCurrentPrNumber() {
     }
 }
 /** Returns the PR number for a given branch, or null if no open PR is found. */
-export async function getPrNumberForBranch(branch, owner, repo) {
-    try {
-        const result = await httpGraphql(PR_NUMBER_BY_BRANCH_QUERY, { owner, repo, branch });
-        return result.data.repository?.pullRequests.nodes[0]?.number ?? null;
-    }
-    catch {
-        return null;
-    }
+async function getGraphqlPrNumberForBranch(branch, owner, repo) {
+    const result = await httpGraphql(PR_NUMBER_BY_BRANCH_QUERY, { owner, repo, branch });
+    return result.data.repository?.pullRequests.nodes[0]?.number ?? null;
 }
 /** Returns the `headRefOid` (commit SHA) of the given PR as reported by GitHub. */
-export async function getPrHeadSha(pr, owner, name) {
+async function getGraphqlPrHeadSha(pr, owner, name) {
     const result = await httpGraphql(GET_PR_HEAD_SHA_QUERY, { owner, repo: name, pr });
     const sha = result.data.repository?.pullRequest?.headRefOid;
     if (!sha) {
@@ -68,7 +67,7 @@ export async function getPrHeadSha(pr, owner, name) {
     return sha;
 }
 /** Fetches the node ID and body text for a PR. GitHub returns null body for empty bodies — coerced to "". */
-export async function getPullRequestBody(pr, owner, name) {
+async function getGraphqlPullRequestBody(pr, owner, name) {
     const result = await httpGraphql(GET_PR_BODY_QUERY, { owner, repo: name, pr });
     const pullRequest = result.data.repository?.pullRequest;
     if (!pullRequest) {
@@ -77,24 +76,31 @@ export async function getPullRequestBody(pr, owner, name) {
             : "PR not found or access denied";
         throw new Error(`Could not fetch body for ${owner}/${name} PR #${pr}: ${detail}`);
     }
+    if (pullRequest.fullDatabaseId != null) {
+        if (typeof pullRequest.fullDatabaseId !== "string")
+            restNumber(pullRequest.fullDatabaseId, "pull request fullDatabaseId");
+        await recordRestIdentity({ owner, name }, pr, pullRequest.id, pullRequest.fullDatabaseId, "pull");
+    }
     return {
         nodeId: pullRequest.id,
         body: pullRequest.body ?? "",
     };
 }
 /** Overwrites the PR body. */
-export async function updatePullRequestBody(pullRequestId, body) {
+async function updateGraphqlPullRequestBody(pullRequestId, body) {
     await httpGraphql(UPDATE_PR_BODY_MUTATION, { pullRequestId, body });
 }
 /**
  * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
  * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
- * READY state. The same response carries state so a concurrent merge or
+ * READY state. The read is conditional inside a PR's REST conditional scope. The same response carries state so a concurrent merge or
  * close can supersede the earlier GraphQL snapshot without another request.
  */
 export async function getMergeableState(pr, owner, repo) {
-    const data = await rest("GET", `/repos/${owner}/${repo}/pulls/${pr}`);
+    // Inside a PR's conditional scope this shares the pull's ETag with the snapshot and wait
+    // detectors: a 304 proves GitHub's current mergeability equals the stored settled body.
+    const data = await readRest("GET", `${restRepoPath({ owner, name: repo })}/pulls/${pr}`);
     const mergeable = data.mergeable === true ? "MERGEABLE" : data.mergeable === false ? "CONFLICTING" : "UNKNOWN";
     const mergeStateStatus = data.mergeable_state.toUpperCase();
     const rawState = data.state?.toUpperCase();
@@ -137,3 +143,29 @@ function parseRemoteUrl(url) {
     }
     throw new Error(`Cannot parse GitHub remote URL: ${url}`);
 }
+export function getPrNumberForBranch(branch, owner, name) {
+    return githubOperation("PrNumberByBranch", () => getGraphqlPrNumberForBranch(branch, owner, name), async () => {
+        const listed = await readRestPages(`${restRepoPath({ owner, name })}/pulls?state=open`);
+        // REST's head filter requires an owner, but GraphQL's headRefName also matches fork heads.
+        const pull = listed.nodes.find((value) => {
+            const head = restObject(restObject(value, "pull request").head, "pull request head");
+            return restString(head.ref, "pull request head ref") === branch;
+        });
+        return pull ? restNumber(pull.number, "pull number") : null;
+    }).catch(() => null);
+}
+export function getPrHeadSha(pr, owner, name) {
+    return githubOperation("GetPrHeadSha", () => getGraphqlPrHeadSha(pr, owner, name), async () => (await readRestPull(pr, { owner, name })).head.sha);
+}
+export function getPullRequestBody(pr, owner, name) {
+    return githubOperation("GetPrBody", () => getGraphqlPullRequestBody(pr, owner, name), async () => {
+        const pull = await readRestPull(pr, { owner, name });
+        return { nodeId: pull.node_id, body: pull.body ?? "" };
+    });
+}
+export function updatePullRequestBody(pullRequestId, body) {
+    return githubOperation("UpdatePrBody", () => updateGraphqlPullRequestBody(pullRequestId, body), async () => {
+        const identity = await resolveRestIdentity(pullRequestId, "pull");
+        await rest("PATCH", `${restRepoPath(identity.repo)}/pulls/${identity.pr}`, { body });
+    }, { mutation: true });
+}

package/bin/github/fingerprint-fields.d.mts

@@ -35,9 +35,17 @@ export declare function threadCommentRevisions(nodes: Array<{
         }>;
     };
 }>): string;
+/**
+ * A thread whose earlier comments the fingerprint cannot see. BatchPr's `comments(first: 100)`
+ * carries the nodes and `hasNextPage`; a stored `totalCount` is honored when present.
+ */
 export declare function hasMultiCommentThreads(nodes: Array<{
     comments?: {
         totalCount?: number;
+        nodes?: unknown[];
+        pageInfo?: {
+            hasNextPage?: boolean;
+        };
     };
 }>): boolean;
 export declare function rulesComplete(baseRef?: {

package/bin/github/fingerprint-fields.mjs

@@ -26,8 +26,13 @@ export function threadCommentRevisions(nodes) {
     })
         .join(",");
 }
+/**
+ * A thread whose earlier comments the fingerprint cannot see. BatchPr's `comments(first: 100)`
+ * carries the nodes and `hasNextPage`; a stored `totalCount` is honored when present.
+ */
 export function hasMultiCommentThreads(nodes) {
-    return nodes.some((thread) => (thread.comments?.totalCount ?? 0) > 1);
+    return nodes.some(({ comments }) => (comments?.totalCount ?? comments?.nodes?.length ?? 0) > 1 ||
+        comments?.pageInfo?.hasNextPage === true);
 }
 export function rulesComplete(baseRef) {
     return baseRef?.rules?.pageInfo?.hasNextPage !== true;

package/bin/github/fingerprint.d.mts

@@ -1,5 +1,8 @@
-import type { RepoInfo } from "./client.mts";
 import type { RawPr } from "./batch-raw-types.mts";
+/**
+ * Summary of BatchPr's first page. Two equal fingerprints mean the first page is unchanged, as
+ * long as every window it summarizes is complete (see `fingerprintReuser`).
+ */
 export interface PrFingerprint {
     headRefOid: string;
     updatedAt: string;
@@ -32,4 +35,3 @@ export interface PrFingerprint {
 }
 export declare function fingerprintFromRaw(raw: RawPr, viewerPermission?: string | null, viewerLogin?: string | null): PrFingerprint;
 export declare function fingerprintsEqual(left: PrFingerprint, right: PrFingerprint): boolean;
-export declare function fetchPrFingerprint(pr: number, repo: RepoInfo): Promise<PrFingerprint>;

package/bin/github/fingerprint.mjs

@@ -1,9 +1,5 @@
-import { graphqlWithRateLimit } from "./client.mjs";
-import { PR_FINGERPRINT_QUERY } from "./queries.mjs";
-import { GitHubRequestError } from "./errors.mjs";
-import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { commentRevisions, mergePolicyFingerprint, rulesComplete, stackKey, suiteFingerprint, hasMultiCommentThreads, threadCommentRevisions, } from "./fingerprint-fields.mjs";
-function coreFingerprint(raw, counts, viewer) {
+export function fingerprintFromRaw(raw, viewerPermission = null, viewerLogin = null) {
     return {
         headRefOid: raw.headRefOid,
         updatedAt: raw.updatedAt ?? "",
@@ -18,50 +14,22 @@ function coreFingerprint(raw, counts, viewer) {
         commentCount: raw.comments.totalCount ?? raw.comments.nodes.length,
         commentRevisions: commentRevisions(raw.comments.nodes),
         threadCount: raw.reviewThreads.totalCount ?? raw.reviewThreads.nodes.length,
-        reviewCount: counts.reviewCount,
-        reviewRevisions: counts.reviewRevisions,
+        reviewCount: raw.allReviews?.totalCount ?? 0,
+        reviewRevisions: commentRevisions(raw.allReviews?.nodes ?? []),
         latestCommentId: raw.comments.nodes.at(-1)?.id ?? null,
         latestThreadId: raw.reviewThreads.nodes.at(-1)?.id ?? null,
-        latestReviewId: counts.latestReviewId,
+        latestReviewId: raw.allReviews?.nodes?.at(-1)?.id ?? null,
         checkRollupState: raw.commits.nodes[0]?.commit.statusCheckRollup?.state ?? null,
         ...suiteFingerprint(raw.commits.nodes[0]?.commit.checkSuites),
         viewerCanUpdate: raw.viewerCanUpdate === true,
-        viewerPermission: viewer.permission,
-        viewerLogin: viewer.login,
+        viewerPermission,
+        viewerLogin,
         stackKey: stackKey(raw),
         threadCommentRevisions: threadCommentRevisions(raw.reviewThreads.nodes),
         rulesComplete: rulesComplete(raw.baseRef),
         hasMultiCommentThreads: hasMultiCommentThreads(raw.reviewThreads.nodes),
     };
 }
-export function fingerprintFromRaw(raw, viewerPermission = null, viewerLogin = null) {
-    return coreFingerprint(raw, {
-        reviewCount: raw.allReviews?.totalCount ?? 0,
-        latestReviewId: raw.allReviews?.nodes?.at(-1)?.id ?? null,
-        reviewRevisions: commentRevisions(raw.allReviews?.nodes ?? []),
-    }, { permission: viewerPermission, login: viewerLogin });
-}
 export function fingerprintsEqual(left, right) {
     return JSON.stringify(left) === JSON.stringify(right);
 }
-export async function fetchPrFingerprint(pr, repo) {
-    const result = await graphqlWithRateLimit(PR_FINGERPRINT_QUERY, {
-        owner: repo.owner,
-        repo: repo.name,
-        pr,
-    });
-    if (!result.data.repository) {
-        throw new GitHubRequestError(`GitHub GraphQL response did not include repository ${repo.owner}/${repo.name} (not found or access denied)`, { status: 200 });
-    }
-    const raw = result.data.repository.pullRequest;
-    if (!raw)
-        throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
-    return coreFingerprint(raw, {
-        reviewCount: raw.reviews.totalCount,
-        latestReviewId: raw.reviews.nodes.at(-1)?.id ?? null,
-        reviewRevisions: commentRevisions(raw.reviews.nodes),
-    }, {
-        permission: result.data.repository.viewerPermission,
-        login: result.data.viewer?.login ?? null,
-    });
-}

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

@@ -0,0 +1,2 @@
+/** Attach proxy routing to GitHub requests without changing the host's dispatcher. */
+export declare function githubFetch(input: string | URL, init?: RequestInit): Promise<Response>;

package/bin/github/github-fetch.mjs

@@ -0,0 +1,19 @@
+import { EnvHttpProxyAgent } from "undici";
+let proxyAgent;
+let proxyConfiguration;
+/** Attach proxy routing to GitHub requests without changing the host's dispatcher. */
+export function githubFetch(input, init) {
+    const httpProxy = process.env["http_proxy"] ?? process.env["HTTP_PROXY"] ?? "";
+    const httpsProxy = process.env["https_proxy"] ?? process.env["HTTPS_PROXY"] ?? "";
+    if (!httpProxy && !httpsProxy)
+        return fetch(input, init);
+    const configuration = JSON.stringify([httpProxy, httpsProxy]);
+    if (!proxyAgent || configuration !== proxyConfiguration) {
+        const previous = proxyAgent;
+        proxyAgent = new EnvHttpProxyAgent();
+        proxyConfiguration = configuration;
+        // close waits for in-flight bodies before releasing the previous pool.
+        void previous?.close().catch(() => { });
+    }
+    return fetch(input, { ...init, dispatcher: proxyAgent });
+}

package/bin/github/gql/base-behind.gql

@@ -12,6 +12,9 @@ query BaseBehind($owner: String!, $repo: String!, $qualifiedName: String!, $head
   }
   repository(owner: $owner, name: $repo) {
     ref(qualifiedName: $qualifiedName) {
+      target {
+        oid
+      }
       compare(headRef: $headRef) {
         behindBy
       }

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

@@ -176,7 +176,23 @@ query BatchPrPage(
                     annotations(first: 1) {
                       totalCount
                       nodes {
+                        fullDatabaseId
+                        path
+                        annotationLevel
+                        title
                         message
+                        rawDetails
+                        blobUrl
+                        location {
+                          start {
+                            line
+                            column
+                          }
+                          end {
+                            line
+                            column
+                          }
+                        }
                       }
                     }
                     checkSuite {

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

@@ -39,6 +39,12 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
       }
       baseRefName
       baseRefOid
+      # Live base tip (an object, no connection cost): keys the BaseBehind cache.
+      baseRef {
+        target {
+          oid
+        }
+      }
       isInMergeQueue
       ...PrMergePolicy
       autoMergeRequest {
@@ -102,10 +108,45 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           }
         }
       }
+      # Native-stack topology and trunk rules ride along so a stack layer needs no
+      # separate PollStackTopology or RefRules read. Neither nested selection
+      # multiplies a connection by 50, so together they add about 3 requests.
       stack {
+        id
         number
         size
         baseRefName
+        entries(first: 50) {
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+          nodes {
+            position
+            pullRequest {
+              number
+              state
+              headRefName
+              headRefOid
+              baseRefName
+              baseRefOid
+            }
+          }
+        }
+        # The bottom entry's base is the trunk: its rules and live tip.
+        trunkEntry: entries(first: 1) {
+          nodes {
+            pullRequest {
+              baseRefName
+              baseRef {
+                ...RefRules
+                target {
+                  oid
+                }
+              }
+            }
+          }
+        }
       }
       stackEntry {
         position
@@ -295,7 +336,23 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
                     annotations(first: 1) {
                       totalCount
                       nodes {
+                        fullDatabaseId
+                        path
+                        annotationLevel
+                        title
                         message
+                        rawDetails
+                        blobUrl
+                        location {
+                          start {
+                            line
+                            column
+                          }
+                          end {
+                            line
+                            column
+                          }
+                        }
                       }
                     }
                     checkSuite {

package/bin/github/gql/commit-check-contexts.gql

@@ -31,8 +31,25 @@ query CommitCheckContexts($owner: String!, $repo: String!, $oid: String!, $curso
                 title
                 summary
                 annotations(first: 1) {
+                  totalCount
                   nodes {
+                    fullDatabaseId
+                    path
+                    annotationLevel
+                    title
                     message
+                    rawDetails
+                    blobUrl
+                    location {
+                      start {
+                        line
+                        column
+                      }
+                      end {
+                        line
+                        column
+                      }
+                    }
                   }
                 }
                 checkSuite {

package/bin/github/gql/get-pr-body.gql

@@ -10,6 +10,7 @@ query GetPrBody($owner: String!, $repo: String!, $pr: Int!) {
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       id
+      fullDatabaseId
       body
     }
   }

package/bin/github/gql/poll-stack-summary.gql

@@ -17,6 +17,7 @@ query PollStackSummary(
     login
   }
   repository(owner: $owner, name: $repo) {
+    viewerPermission
     viewerCanAdminister
     mergeCommitAllowed
     squashMergeAllowed