pr-shepherd 0.56.6 → 0.57.1

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[]>;

package/bin/github/rest-annotation-read.mjs

@@ -0,0 +1,44 @@
+import { readRestPages, restRepoPath, restString, restNumber, restCollection, restObject, } from "./rest-reader-core.mjs";
+import { recordRestIdentity, resolveRestIdentity } from "./rest-identities.mjs";
+import { toCheckAnnotation } from "./check-annotation-shape.mjs";
+import { readRestPull } from "./rest-pr-core.mjs";
+/** An annotation fallback can follow a GraphQL snapshot with no persisted REST check IDs. */
+export async function ensureRestCheckIdentities(checkRunIds, scope) {
+    if (!scope || checkRunIds.length === 0)
+        return;
+    const identities = await Promise.allSettled(checkRunIds.map((id) => resolveRestIdentity(id, "check")));
+    if (identities.every((identity) => identity.status === "fulfilled"))
+        return;
+    const repo = { owner: scope.stateKey.owner, name: scope.stateKey.repo };
+    const pr = scope.stateKey.pr;
+    const sha = scope.headSha ?? (await readRestPull(pr, repo)).head.sha;
+    const checks = await readRestPages(`${restRepoPath(repo)}/commits/${encodeURIComponent(sha)}/check-runs?filter=all`, (body) => restCollection(body, "check_runs"));
+    await Promise.all(checks.nodes.map((value) => {
+        const check = restObject(value, "check run identity");
+        return recordRestIdentity(repo, pr, restString(check.node_id, "check node_id"), restNumber(check.id, "check id"), "check");
+    }));
+}
+export async function readRestCheckAnnotations(checkRunId, scope) {
+    await ensureRestCheckIdentities([checkRunId], scope);
+    const identity = await resolveRestIdentity(checkRunId, "check");
+    const result = await readRestPages(`${restRepoPath(identity.repo)}/check-runs/${identity.numericId}/annotations`);
+    return result.nodes.map((raw) => toCheckAnnotation(checkRunId, {
+        fullDatabaseId: null,
+        path: restString(raw.path, "annotation path"),
+        annotationLevel: restString(raw.annotation_level, "annotation level").toUpperCase(),
+        title: typeof raw.title === "string" ? raw.title : null,
+        message: restString(raw.message, "annotation message"),
+        rawDetails: typeof raw.raw_details === "string" ? raw.raw_details : null,
+        blobUrl: typeof raw.blob_href === "string" ? raw.blob_href : null,
+        location: {
+            start: {
+                line: restNumber(raw.start_line, "annotation start_line"),
+                column: typeof raw.start_column === "number" ? raw.start_column : null,
+            },
+            end: {
+                line: restNumber(raw.end_line, "annotation end_line"),
+                column: typeof raw.end_column === "number" ? raw.end_column : null,
+            },
+        },
+    }));
+}

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

@@ -0,0 +1,12 @@
+import type { RepoInfo } from "./client.mts";
+import type { BatchResult } from "./batch.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+import type { RestSnapshotContext } from "./rest-snapshot-context.mts";
+/** REST uses multiple resources; retry a moving head/base once rather than combining revisions. */
+export declare function fetchRestPrBatch(pr: number, repo: RepoInfo, opts?: {
+    includeReceiptSummary?: boolean;
+    terminalShortCircuit?: boolean;
+    snapshotContext?: RestSnapshotContext;
+    viewerLogin?: string | null;
+}): Promise<BatchResult>;
+export declare function fetchRestRawSummaryPr(pr: number, repo: RepoInfo, snapshotContext?: RestSnapshotContext, viewerLogin?: string | null): Promise<RawSummaryPr>;

package/bin/github/rest-batch-read.mjs

@@ -0,0 +1,57 @@
+import { readRestPull, restPullRevision } from "./rest-pr-core.mjs";
+import { readRestSnapshot } from "./rest-batch-snapshot.mjs";
+import { isRestPullMerged, restMergedBatchData } from "./rest-terminal-batch.mjs";
+import { restSummary } from "./rest-summary-read.mjs";
+import { markReadyAnnotationProbeComplete } from "./poll-summary-annotation-probe.mjs";
+import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { EXIT } from "../exit-codes.mjs";
+/** REST uses multiple resources; retry a moving head/base once rather than combining revisions. */
+export async function fetchRestPrBatch(pr, repo, opts = {}) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const pull = await readRestPull(pr, repo);
+        if (opts.terminalShortCircuit && isRestPullMerged(pull)) {
+            return { data: restMergedBatchData(pull), checkSuitesComplete: true };
+        }
+        const snapshot = await readRestSnapshot(pull, repo, opts.snapshotContext, opts.viewerLogin);
+        const latest = await readRestPull(pr, repo);
+        if (restPullRevision(pull) !== restPullRevision(latest))
+            continue;
+        opts.snapshotContext?.recordPullRevision(pr, restPullRevision(latest));
+        const receiptSummary = restSummary(snapshot.data, pull, snapshot.feedback, snapshot.checks, snapshot.rules.baseRef);
+        // Match the canonical check window hashed by aggregate stack reconciliation.
+        await hydratePollSummaryChecks(receiptSummary, repo);
+        markReadyAnnotationProbeComplete(receiptSummary);
+        return {
+            data: snapshot.data,
+            rateLimit: snapshot.checks.rateLimit,
+            checkSuitesComplete: true,
+            ...(snapshot.checks.suites.length === 0 && { headCheckSuitesEmpty: true }),
+            headWorkflowSuites: snapshot.checks.suites.flatMap((suite) => {
+                const run = snapshot.checks.workflowRuns.find((run) => run.check_suite_id === suite.id);
+                return run
+                    ? [
+                        {
+                            status: suite.status.toUpperCase(),
+                            conclusion: suite.conclusion?.toUpperCase() ?? null,
+                            workflowRun: { event: run.event },
+                        },
+                    ]
+                    : [];
+            }),
+            ...(opts.includeReceiptSummary && { receiptSummary }),
+        };
+    }
+    throw new GitHubRequestError("Pull request changed while REST snapshot was being read; retry", {
+        status: 409,
+        exitCodeOverride: EXIT.TEMPFAIL,
+    });
+}
+export async function fetchRestRawSummaryPr(pr, repo, snapshotContext, viewerLogin) {
+    const snapshot = await fetchRestPrBatch(pr, repo, {
+        includeReceiptSummary: true,
+        snapshotContext,
+        viewerLogin,
+    });
+    return snapshot.receiptSummary;
+}

package/bin/github/rest-batch-snapshot.d.mts

@@ -0,0 +1,30 @@
+import type { RepoInfo } from "./client.mts";
+import type { BatchPrData } from "../types.mts";
+import { type RestPull } from "./rest-pr-core.mts";
+import type { RestSnapshotContext } from "./rest-snapshot-context.mts";
+export declare function readRestSnapshot(pull: RestPull, repo: RepoInfo, context?: RestSnapshotContext, knownViewerLogin?: string | null): Promise<{
+    data: BatchPrData;
+    feedback: {
+        threads: import("../types.mts").ReviewThread[];
+        comments: import("../types.mts").PrComment[];
+        reviews: import("./rest-feedback-read.mts").RestReview[];
+        unavailable: {
+            field: string;
+            reason: string;
+        }[];
+        viewerLogin: string | null;
+    };
+    checks: {
+        nodes: import("./batch-raw-types.mts").RawContextNode[];
+        suites: import("./rest-check-read.mts").RestSuite[];
+        workflowRuns: import("./rest-check-read.mts").RestWorkflowRun[];
+        rateLimit: import("./http-utils.mts").RateLimitInfo | undefined;
+    };
+    rules: {
+        baseRef?: import("./batch-raw-rules.mts").RawBaseRef;
+        unavailable: Array<{
+            field: string;
+            reason: string;
+        }>;
+    };
+}>;

package/bin/github/rest-batch-snapshot.mjs

@@ -0,0 +1,115 @@
+import { restPullRefs } from "./rest-pr-core.mjs";
+import { readRestFeedback, restReviewToReview } from "./rest-feedback-read.mjs";
+import { readRestCommitChecks } from "./rest-check-read.mjs";
+import { readRestBranchRules } from "./rest-rules-read.mjs";
+import { readRestStackMembership } from "./rest-stack-read.mjs";
+import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
+import { parseCheckNodes } from "./batch-parse-checks.mjs";
+import { parseBranchRules } from "./batch-parsers-rules.mjs";
+import { isReviewStale } from "./batch-parser-helpers.mjs";
+import { readRest as rest, restRepoPath, restObject, restString } from "./rest-reader-core.mjs";
+import { restLatestReviews, restPendingReviews } from "./rest-review-read.mjs";
+import { REST_BATCH_UNAVAILABLE } from "./rest-batch-unavailable.mjs";
+export async function readRestSnapshot(pull, repo, context, knownViewerLogin) {
+    const [feedback, checks, rules, stack] = await Promise.all([
+        readRestFeedback(pull.number, repo, context ? context.viewerLogin : knownViewerLogin),
+        readRestCommitChecks(pull.head.sha, repo, pull.number),
+        context ? context.readBranchRules(pull.base.ref) : readRestBranchRules(repo, pull.base.ref),
+        context ? Promise.resolve(context.stack) : readRestStackMembership(pull.number, repo),
+    ]);
+    const repository = restObject(context?.repository ?? (await rest("GET", restRepoPath(repo))), "repository merge settings");
+    const allowedMergeMethods = [
+        ...(repository.allow_merge_commit === true ? ["merge"] : []),
+        ...(repository.allow_squash_merge === true ? ["squash"] : []),
+        ...(repository.allow_rebase_merge === true ? ["rebase"] : []),
+    ];
+    const latestReviews = restLatestReviews(feedback.reviews);
+    const requested = [
+        ...(pull.requested_reviewers ?? []).map((reviewer) => ({ login: reviewer.login })),
+        ...(pull.requested_teams ?? []).map((team) => ({ login: team.name })),
+    ];
+    const changes = feedback.reviews.filter((review) => review.state === "CHANGES_REQUESTED" &&
+        !["APPROVED", "DISMISSED"].includes(latestReviews.get(review.user?.login.toLowerCase() ?? "")?.state ?? ""));
+    const transportUnavailable = [
+        ...feedback.unavailable,
+        ...rules.unavailable,
+        ...REST_BATCH_UNAVAILABLE,
+    ];
+    const data = {
+        nodeId: pull.node_id,
+        ...(feedback.viewerLogin && { viewerLogin: feedback.viewerLogin }),
+        ...restPullRefs(pull),
+        state: restPullRefs(pull).state,
+        isDraft: pull.draft,
+        mergeable: pull.mergeable === true ? "MERGEABLE" : pull.mergeable === false ? "CONFLICTING" : "UNKNOWN",
+        mergeStateStatus: pull.mergeable_state.toUpperCase(),
+        reviewDecision: null,
+        ...(pull.auto_merge !== undefined && {
+            autoMergeRequest: pull.auto_merge
+                ? {
+                    mergeMethod: restString(pull.auto_merge.merge_method, "auto-merge merge_method").toUpperCase(),
+                    ...(pull.auto_merge.enabled_by?.login && {
+                        enabledBy: restString(pull.auto_merge.enabled_by.login, "auto-merge enabled_by login"),
+                    }),
+                }
+                : null,
+        }),
+        headRepoWithOwner: pull.head.repo?.full_name ?? null,
+        reviewRequests: requested,
+        latestReviews: [...restPendingReviews(feedback.reviews), ...latestReviews.values()],
+        reviewThreads: feedback.threads,
+        comments: feedback.comments,
+        changesRequestedReviews: changes.map((review) => {
+            const mapped = restReviewToReview(review);
+            if (isReviewStale(mapped, pull.head.sha, feedback.threads))
+                mapped.staleReview = true;
+            return mapped;
+        }),
+        reviewSummaries: feedback.reviews
+            .filter((review) => review.state === "COMMENTED" && review.body?.trim())
+            .map(restReviewToReview),
+        approvedReviews: feedback.reviews
+            .filter((review) => review.state === "APPROVED")
+            .map(restReviewToReview),
+        checks: mergeStartupFailureChecks(parseCheckNodes(checks.nodes), checks.suites.flatMap((suite) => {
+            const run = checks.workflowRuns.find((run) => run.check_suite_id === suite.id);
+            if (suite.conclusion?.toUpperCase() !== "STARTUP_FAILURE" || !run)
+                return [];
+            return [
+                {
+                    name: run.name || `workflow run ${run.id}`,
+                    status: "COMPLETED",
+                    conclusion: "STARTUP_FAILURE",
+                    source: "startup_failure",
+                    detailsUrl: run.html_url,
+                    event: run.event,
+                    runId: String(run.id),
+                },
+            ];
+        })),
+        branchProtection: rules.baseRef?.branchProtectionRule
+            ? {
+                requiresApprovingReviews: rules.baseRef.branchProtectionRule.requiresApprovingReviews,
+                requiredApprovingReviewCount: rules.baseRef.branchProtectionRule.requiredApprovingReviewCount,
+                requiresConversationResolution: rules.baseRef.branchProtectionRule.requiresConversationResolution,
+                requiresStatusChecks: rules.baseRef.branchProtectionRule.requiresStatusChecks,
+                requiredStatusCheckContexts: rules.baseRef.branchProtectionRule.requiredStatusCheckContexts ?? [],
+            }
+            : null,
+        ...(rules.baseRef && { branchRules: parseBranchRules(rules.baseRef) }),
+        ...(typeof repository.allow_merge_commit === "boolean" &&
+            typeof repository.allow_squash_merge === "boolean" &&
+            typeof repository.allow_rebase_merge === "boolean" && { allowedMergeMethods }),
+        stack: stack
+            ? {
+                number: stack.number,
+                size: stack.pull_requests.length,
+                position: stack.pull_requests.findIndex((member) => member.number === pull.number) + 1,
+                baseRefName: stack.base.ref,
+            }
+            : null,
+        transport: "rest",
+        transportUnavailable,
+    };
+    return { data, feedback, checks, rules };
+}

package/bin/github/rest-batch-unavailable.d.mts

@@ -0,0 +1,5 @@
+/** Batch fields no REST endpoint supplies; they stay unknown rather than defaulting to false. */
+export declare const REST_BATCH_UNAVAILABLE: ReadonlyArray<{
+    field: string;
+    reason: string;
+}>;

package/bin/github/rest-batch-unavailable.mjs

@@ -0,0 +1,16 @@
+/** Batch fields no REST endpoint supplies; they stay unknown rather than defaulting to false. */
+export const REST_BATCH_UNAVAILABLE = [
+    {
+        field: "reviewDecision",
+        reason: "REST does not expose an aggregate review decision; latest review states are supplied",
+    },
+    { field: "viewerAuthorization", reason: "REST does not expose viewer capability fields" },
+    {
+        field: "comments.isMinimized",
+        reason: "REST does not expose minimization state or support minimizing comments",
+    },
+    {
+        field: "mergeQueue",
+        reason: "REST does not expose queue membership, entry or removal history",
+    },
+];

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

@@ -0,0 +1,34 @@
+import type { RepoInfo } from "./client.mts";
+import type { RawContextNode } from "./batch-raw-types.mts";
+export interface RestSuite {
+    id: number;
+    node_id: string;
+    status: string;
+    conclusion: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface RestWorkflowRun {
+    id: number;
+    check_suite_id: number;
+    event: string;
+    workflow_id: number;
+    name: string;
+    created_at: string;
+    updated_at: string;
+    html_url: string;
+}
+export declare function readRestCommitChecks(oid: string, repo: RepoInfo, pr?: number): Promise<{
+    nodes: RawContextNode[];
+    suites: RestSuite[];
+    workflowRuns: RestWorkflowRun[];
+    rateLimit: import("./http-utils.mts").RateLimitInfo | undefined;
+}>;
+export declare function readRestAnnotationCounts(oid: string, repo: RepoInfo): Promise<{
+    __typename: "CheckRun";
+    id: string;
+    annotations: {
+        totalCount: number;
+    };
+}[]>;
+export declare function readRestBehind(repo: RepoInfo, base: string, head: string): Promise<number>;