pr-shepherd 0.56.6 → 0.57.0

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

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

@@ -0,0 +1,124 @@
+import { readRestPages, restRepoPath, restCollection, restString, restNumber, malformedRest, } from "./rest-reader-core.mjs";
+import { recordRestIdentity } from "./rest-identities.mjs";
+import { readRest as rest } from "./rest-reader-core.mjs";
+export async function readRestCommitChecks(oid, repo, pr = 0) {
+    const prefix = restRepoPath(repo);
+    const checks = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-runs?filter=latest`, (body) => restCollection(body, "check_runs"));
+    const suites = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-suites`, (body) => restCollection(body, "check_suites"));
+    const statuses = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/statuses`);
+    const workflowRuns = await readRestPages(`${prefix}/actions/runs?head_sha=${encodeURIComponent(oid)}`, (body) => restCollection(body, "workflow_runs"));
+    for (const suite of suites.nodes) {
+        restNumber(suite.id, "check suite id");
+        restString(suite.status, "check suite status");
+        if (suite.conclusion !== null)
+            restString(suite.conclusion, "check suite conclusion");
+    }
+    for (const run of workflowRuns.nodes) {
+        restNumber(run.id, "workflow run id");
+        restNumber(run.check_suite_id, "workflow check suite id");
+        restNumber(run.workflow_id, "workflow id");
+        restString(run.event, "workflow event");
+    }
+    const workflows = new Map(workflowRuns.nodes.map((run) => [run.check_suite_id, run]));
+    const suiteMap = new Map(suites.nodes.map((suite) => [suite.id, suite]));
+    const nodes = [];
+    const checkIds = new Set();
+    for (const check of checks.nodes) {
+        restNumber(check.id, "check run id");
+        restString(check.node_id, "check run node_id");
+        restString(check.name, "check run name");
+        restString(check.status, "check run status");
+        if (!["QUEUED", "IN_PROGRESS", "COMPLETED", "WAITING", "PENDING", "REQUESTED"].includes(check.status.toUpperCase()))
+            malformedRest("unknown check run status");
+        if (check.conclusion !== null &&
+            ![
+                "ACTION_REQUIRED",
+                "CANCELLED",
+                "FAILURE",
+                "NEUTRAL",
+                "SKIPPED",
+                "STALE",
+                "STARTUP_FAILURE",
+                "SUCCESS",
+                "TIMED_OUT",
+            ].includes(restString(check.conclusion, "check conclusion").toUpperCase()))
+            malformedRest("unknown check conclusion");
+        restNumber(check.output?.annotations_count, "check run annotation count");
+        if (checkIds.has(check.node_id))
+            throw new Error("REST check run pagination duplicated an ID");
+        checkIds.add(check.node_id);
+        await recordRestIdentity(repo, pr, check.node_id, String(check.id), "check");
+        const suite = check.check_suite ? suiteMap.get(check.check_suite.id) : undefined;
+        const run = check.check_suite ? workflows.get(check.check_suite.id) : undefined;
+        nodes.push({
+            __typename: "CheckRun",
+            id: check.node_id,
+            name: check.name,
+            status: check.status.toUpperCase(),
+            conclusion: check.conclusion?.toUpperCase() ?? null,
+            detailsUrl: check.details_url,
+            startedAt: check.started_at,
+            completedAt: check.completed_at,
+            title: check.output.title,
+            summary: check.output.summary,
+            annotations: { totalCount: check.output.annotations_count, nodes: [] },
+            checkSuite: suite
+                ? {
+                    createdAt: suite.created_at,
+                    updatedAt: suite.updated_at,
+                    workflowRun: run
+                        ? {
+                            databaseId: run.id,
+                            event: run.event,
+                            createdAt: run.created_at,
+                            updatedAt: run.updated_at,
+                            workflow: { name: run.name, databaseId: run.workflow_id },
+                        }
+                        : null,
+                }
+                : null,
+        });
+    }
+    // REST statuses include history; only the latest status for each context is current.
+    const latest = new Map();
+    for (const status of statuses.nodes) {
+        restString(status.context, "status context");
+        restString(status.state, "status state");
+        if (!["PENDING", "EXPECTED", "SUCCESS", "FAILURE", "ERROR"].includes(status.state.toUpperCase()))
+            malformedRest("unknown status context state");
+        if (!Number.isFinite(Date.parse(status.created_at)))
+            malformedRest("status context created_at");
+        const old = latest.get(status.context);
+        if (!old ||
+            Date.parse(status.created_at) > Date.parse(old.created_at) ||
+            (status.created_at === old.created_at && status.id > old.id))
+            latest.set(status.context, status);
+    }
+    for (const status of latest.values())
+        nodes.push({
+            __typename: "StatusContext",
+            context: status.context,
+            state: status.state.toUpperCase(),
+            targetUrl: status.target_url,
+            description: status.description,
+            createdAt: status.created_at,
+        });
+    return {
+        nodes,
+        suites: suites.nodes,
+        workflowRuns: workflowRuns.nodes,
+        rateLimit: workflowRuns.rateLimit ?? checks.rateLimit,
+    };
+}
+export async function readRestAnnotationCounts(oid, repo) {
+    const checks = await readRestPages(`${restRepoPath(repo)}/commits/${encodeURIComponent(oid)}/check-runs?filter=latest`, (body) => restCollection(body, "check_runs"));
+    return checks.nodes.map((check) => ({
+        __typename: "CheckRun",
+        id: restString(check.node_id, "check node_id"),
+        annotations: { totalCount: restNumber(check.output?.annotations_count, "annotations_count") },
+    }));
+}
+export async function readRestBehind(repo, base, head) {
+    const comparison = await rest("GET", `${restRepoPath(repo)}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`);
+    return restNumber(comparison.behind_by, "compare behind_by");
+}

package/bin/github/rest-comment-authorship.d.mts

@@ -0,0 +1,7 @@
+import type { RestComment } from "./rest-feedback-read.mts";
+export declare function restCommentAuthorFields(comment: RestComment, viewerLogin?: string | null): {
+    author: string;
+    authorType: import("../types.mts").AuthorType;
+    viewerDidAuthor?: true | undefined;
+    authorAssociation: import("../types.mts").CommentAuthorAssociation;
+};

package/bin/github/rest-comment-authorship.mjs

@@ -0,0 +1,11 @@
+import { mapAuthorType } from "./batch-parser-helpers.mjs";
+export function restCommentAuthorFields(comment, viewerLogin) {
+    const login = typeof comment.user?.login === "string" ? comment.user.login : undefined;
+    return {
+        author: login ?? "unknown",
+        authorType: mapAuthorType(comment.user?.type, login),
+        ...(viewerLogin &&
+            login?.toLowerCase() === viewerLogin.toLowerCase() && { viewerDidAuthor: true }),
+        ...(comment.author_association && { authorAssociation: comment.author_association }),
+    };
+}

package/bin/github/rest-conditional-scope.d.mts

@@ -0,0 +1,20 @@
+import type { StateKey } from "../state/rest-cache.mts";
+export interface RestSnapshotState {
+    /**
+     * True when at least one conditional read answered 304 and every other read was a settled body
+     * without an ETag (fingerprinted by content instead). Any changed ETag-bearing body is fresh.
+     */
+    allNotModified: boolean;
+    /** Stable digest of every (path, validator) the snapshot observed. */
+    digest: string;
+}
+export declare function withRestConditionalScope<T>(key: StateKey, fn: () => Promise<T>): Promise<T>;
+export declare function currentRestConditionalKey(): StateKey | undefined;
+/**
+ * Record how one read was answered. `contentBody` is passed only for a settled 200 that carried
+ * no ETag: a route that cannot answer 304 (the Claude Code cloud proxy's `/ccr/review_threads`
+ * may not send validators) is then validated by a hash of its content, so an unchanged body
+ * still lets the snapshot's digest match. Every other non-304 read is fresh and blocks reuse.
+ */
+export declare function recordRestConditionalRead(path: string, notModified: boolean, etag: string | undefined, contentBody?: unknown): void;
+export declare function restSnapshotState(): RestSnapshotState | undefined;

package/bin/github/rest-conditional-scope.mjs

@@ -0,0 +1,44 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+const storage = new AsyncLocalStorage();
+export function withRestConditionalScope(key, fn) {
+    return storage.run({ key, fresh: 0, notModified: 0, etags: new Map() }, fn);
+}
+export function currentRestConditionalKey() {
+    return storage.getStore()?.key;
+}
+/**
+ * Record how one read was answered. `contentBody` is passed only for a settled 200 that carried
+ * no ETag: a route that cannot answer 304 (the Claude Code cloud proxy's `/ccr/review_threads`
+ * may not send validators) is then validated by a hash of its content, so an unchanged body
+ * still lets the snapshot's digest match. Every other non-304 read is fresh and blocks reuse.
+ */
+export function recordRestConditionalRead(path, notModified, etag, contentBody) {
+    const scope = storage.getStore();
+    if (scope === undefined)
+        return;
+    if (notModified)
+        scope.notModified += 1;
+    else if (etag !== undefined || contentBody === undefined)
+        scope.fresh += 1;
+    scope.etags.set(path, etag ?? (contentBody === undefined ? "" : `content:${contentDigest(contentBody)}`));
+}
+function contentDigest(body) {
+    return createHash("sha256")
+        .update(JSON.stringify(body) ?? "")
+        .digest("hex")
+        .slice(0, 16);
+}
+export function restSnapshotState() {
+    const scope = storage.getStore();
+    if (scope === undefined)
+        return undefined;
+    const hash = createHash("sha256");
+    for (const [path, etag] of [...scope.etags].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        hash.update(`${path}\0${etag}\0`);
+    }
+    return {
+        allNotModified: scope.fresh === 0 && scope.notModified > 0,
+        digest: hash.digest("hex").slice(0, 16),
+    };
+}

package/bin/github/rest-explicit-summary-read.d.mts

@@ -0,0 +1,3 @@
+import type { RepoInfo } from "./client.mts";
+/** One principal read for this explicit PR chunk, without assuming its PRs are standalone. */
+export declare function readRestExplicitSummary(prs: number[], repo: RepoInfo): Promise<import("./poll-summary-raw.mts").RawSummaryPr[]>;

package/bin/github/rest-explicit-summary-read.mjs

@@ -0,0 +1,8 @@
+import { fetchRestRawSummaryPr } from "./rest-batch-read.mjs";
+import { readRestViewerLogin } from "./rest-viewer-read.mjs";
+import { mapPool } from "../util/pool.mjs";
+/** One principal read for this explicit PR chunk, without assuming its PRs are standalone. */
+export async function readRestExplicitSummary(prs, repo) {
+    const viewerLogin = await readRestViewerLogin();
+    return mapPool(prs, 4, (pr) => fetchRestRawSummaryPr(pr, repo, undefined, viewerLogin));
+}

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

@@ -0,0 +1,36 @@
+import type { RepoInfo } from "./client.mts";
+import type { PrComment, Review, ReviewThread, CommentAuthorAssociation } from "../types.mts";
+export interface RestComment {
+    id: number;
+    node_id: string;
+    body: string;
+    html_url: string;
+    created_at: string;
+    updated_at: string;
+    user: {
+        login: string;
+        type: string;
+    } | null;
+    author_association: CommentAuthorAssociation;
+    in_reply_to_id?: number;
+    pull_request_review_id?: number;
+    path?: string;
+    line?: number | null;
+    start_line?: number | null;
+}
+export interface RestReview extends RestComment {
+    state: string;
+    commit_id: string;
+    submitted_at?: string | null;
+}
+export declare function readRestFeedback(pr: number, repo: RepoInfo, knownViewerLogin?: string | null): Promise<{
+    threads: ReviewThread[];
+    comments: PrComment[];
+    reviews: RestReview[];
+    unavailable: {
+        field: string;
+        reason: string;
+    }[];
+    viewerLogin: string | null;
+}>;
+export declare function restReviewToReview(review: RestReview): Review;