pr-shepherd 0.56.6 → 0.57.0

package/bin/commands/check-annotations.mjs

@@ -45,10 +45,11 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber,
     const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber, cacheOpts);
     const byId = new Map(annotated.flatMap((c) => (c.id != null ? [[c.id, c]] : [])));
     const apply = (list) => list.map((c) => {
-        if (c.id == null)
-            return c;
-        const next = byId.get(c.id);
-        return next !== undefined ? next : c;
+        const next = (c.id == null ? undefined : byId.get(c.id)) ?? c;
+        if (next.inlineAnnotations === undefined)
+            return next;
+        const { inlineAnnotations: _inline, ...rest } = next;
+        return rest;
     });
     return {
         passing: apply(buckets.passing),
@@ -61,22 +62,31 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber,
 async function attachUnseenCheckAnnotations(checks, seenMap, prNumber, cacheOpts) {
     if (checks.length === 0)
         return checks;
-    const ids = checks.flatMap((check) => (check.id == null ? [] : [check.id]));
-    let batch;
-    try {
-        batch = await fetchCheckRunAnnotationsBatch(ids, cacheOpts);
+    const annotations = new Map();
+    for (const check of checks) {
+        if (check.id != null && check.inlineAnnotations)
+            annotations.set(check.id, check.inlineAnnotations);
     }
-    catch (err) {
-        if (pollRateLimitRetryAfterMs(err) !== null)
-            throw err;
-        writeAnnotationFailureSummary(prNumber, ids.length, err);
-        return checks;
-    }
-    const firstFailure = batch.failures[0];
-    if (firstFailure !== undefined) {
-        writeAnnotationFailureSummary(prNumber, batch.failures.length, firstFailure.error);
+    const ids = checks.flatMap((check) => check.id == null || annotations.has(check.id) ? [] : [check.id]);
+    if (ids.length > 0) {
+        let batch;
+        try {
+            batch = await fetchCheckRunAnnotationsBatch(ids, cacheOpts);
+        }
+        catch (err) {
+            if (pollRateLimitRetryAfterMs(err) !== null)
+                throw err;
+            writeAnnotationFailureSummary(prNumber, ids.length, err);
+            return checks.map((check) => withUnseenAnnotations(check, annotations, seenMap));
+        }
+        const firstFailure = batch.failures[0];
+        if (firstFailure !== undefined) {
+            writeAnnotationFailureSummary(prNumber, batch.failures.length, firstFailure.error);
+        }
+        for (const [id, list] of batch.annotations)
+            annotations.set(id, list);
     }
-    return checks.map((check) => withUnseenAnnotations(check, batch.annotations, seenMap));
+    return checks.map((check) => withUnseenAnnotations(check, annotations, seenMap));
 }
 function withUnseenAnnotations(check, annotations, seenMap) {
     const fetched = check.id == null ? undefined : annotations.get(check.id);

package/bin/commands/check-execution-context.d.mts

@@ -1,9 +1,14 @@
 import type { RepoInfo } from "../github/client.mts";
 import { readStackTopology } from "../github/stack-read.mts";
+import type { BatchStackEvidence, TrunkRules } from "../github/batch-stack-evidence.mts";
 import type { RawSummaryPr } from "../github/poll-summary-raw.mts";
 /** Fresh for each iterate tick; never persisted or exposed in CLI output. */
 export declare function createCheckExecutionContext(readyDelaySeconds?: number): {
     readStackTopology(pr: number, repo: RepoInfo): ReturnType<typeof readStackTopology>;
+    /** Adopt the stack reads that this tick's `BatchPr` first page already answered. */
+    seedStack(pr: number, repo: RepoInfo, evidence: BatchStackEvidence): void;
+    /** Trunk rules from this tick's `BatchPr`, only when they are for `refName`. */
+    trunkRules(pr: number, repo: RepoInfo, refName: string): TrunkRules | undefined;
     wantsReceiptSummary(pr: number, repo: RepoInfo): Promise<boolean>;
     setReceiptSummary(raw: RawSummaryPr | null): void;
     getReceiptSummary(): RawSummaryPr | null;

package/bin/commands/check-execution-context.mjs

@@ -4,11 +4,13 @@ import { readyDelayElapsed } from "./ready-delay.mjs";
 /** Fresh for each iterate tick; never persisted or exposed in CLI output. */
 export function createCheckExecutionContext(readyDelaySeconds) {
     const topologies = new Map();
+    const trunks = new Map();
+    const keyOf = (pr, repo) => `${repo.owner.toLowerCase()}/${repo.name.toLowerCase()}#${pr}`;
     let receiptSummary = null;
     let receiptSummaryInvalidated = false;
     return {
         readStackTopology(pr, repo) {
-            const key = `${repo.owner.toLowerCase()}/${repo.name.toLowerCase()}#${pr}`;
+            const key = keyOf(pr, repo);
             let pending = topologies.get(key);
             if (!pending) {
                 pending = readStackTopology(pr, repo);
@@ -16,6 +18,19 @@ export function createCheckExecutionContext(readyDelaySeconds) {
             }
             return pending;
         },
+        /** Adopt the stack reads that this tick's `BatchPr` first page already answered. */
+        seedStack(pr, repo, evidence) {
+            const key = keyOf(pr, repo);
+            if (evidence.topology)
+                topologies.set(key, Promise.resolve(evidence.topology));
+            if (evidence.trunk)
+                trunks.set(key, evidence.trunk);
+        },
+        /** Trunk rules from this tick's `BatchPr`, only when they are for `refName`. */
+        trunkRules(pr, repo, refName) {
+            const trunk = trunks.get(keyOf(pr, repo));
+            return trunk?.refName === refName ? trunk : undefined;
+        },
         async wantsReceiptSummary(pr, repo) {
             if (readyDelaySeconds === undefined)
                 return false;

package/bin/commands/check-fingerprint.d.mts

@@ -1,8 +1,32 @@
 import { type RepoInfo } from "../github/client.mts";
+import { type PrFingerprint } from "../github/fingerprint.mts";
+import type { RestSnapshotState } from "../github/rest-conditional-scope.mts";
 import type { PrShepherdConfig } from "../config/load.mts";
 import type { ShepherdReport } from "../types.mts";
-export declare function tryReuseFingerprintReport(prNumber: number, repo: RepoInfo, stateKey: {
+export declare function reportAllowsFingerprintSkip(report: ShepherdReport): boolean;
+/** Whether a fingerprint's windows cover everything it summarizes, so equality means unchanged. */
+export declare function fingerprintIsComplete(fingerprint: PrFingerprint): boolean;
+/**
+ * GraphQL fingerprint reuse. Returns a decider for `fetchPrBatch`'s first page, or `undefined`
+ * when the stored report cannot be reused whatever GitHub says. The decider replays the stored
+ * report only when the first page's fingerprint equals the stored one, so a hit costs the one
+ * BatchPr request and skips every supplement, and a miss continues the same snapshot.
+ */
+export declare function fingerprintReuser(prNumber: number, repo: RepoInfo, stateKey: {
     owner: string;
     repo: string;
     pr: number;
-}, config: PrShepherdConfig): Promise<ShepherdReport | null>;
+}, config: PrShepherdConfig): Promise<((live: PrFingerprint) => Promise<ShepherdReport | null>) | undefined>;
+/**
+ * REST counterpart of `fingerprintReuser`: after the snapshot reads, reuse the previous
+ * report only when every conditional read came back 304 with the same validators it was built
+ * from. No separate mergeability read is made. Mergeability moves when the head or the base
+ * moves: the head is in the pull body, and the base branch summary read by
+ * `readRestBranchRules` carries the base's `commit.sha`, so a base push answers 200 and blocks
+ * reuse. An unsettled `mergeable: null` pull body is never cached, so it cannot answer 304.
+ */
+export declare function tryReuseRestSnapshotReport(stateKey: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, config: PrShepherdConfig, snapshot: RestSnapshotState | undefined): Promise<ShepherdReport | null>;

package/bin/commands/check-fingerprint.mjs

@@ -1,9 +1,11 @@
 import { getMergeableState } from "../github/client.mjs";
-import { fetchPrFingerprint, fingerprintsEqual, } from "../github/fingerprint.mjs";
+import { fingerprintsEqual } from "../github/fingerprint.mjs";
 import { fingerprintInputDigest, loadPrFingerprint } from "../state/pr-fingerprint.mjs";
+import { loadRestSnapshotReport } from "../state/rest-snapshot-report.mjs";
 import { hasCheckDrivenActionableWork } from "./check-annotations.mjs";
 import { stripReplayedRuleAutoResolve } from "./rule-auto-resolve-format.mjs";
-function reportAllowsFingerprintSkip(report) {
+import { getGithubTransport } from "../github/transport.mjs";
+export function reportAllowsFingerprintSkip(report) {
     if (report.status === "READY")
         return false;
     if (report.mergeStatus.state !== "OPEN")
@@ -26,40 +28,74 @@ function reportAllowsFingerprintSkip(report) {
         (report.ruleAutoResolveReviewSummaryIds?.length ?? 0) === 0 &&
         !hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status));
 }
-export async function tryReuseFingerprintReport(prNumber, repo, stateKey, config) {
+/** Whether a fingerprint's windows cover everything it summarizes, so equality means unchanged. */
+export function fingerprintIsComplete(fingerprint) {
+    return (!fingerprint.isInMergeQueue &&
+        fingerprint.checkSuitesComplete &&
+        fingerprint.commentCount <= 100 &&
+        fingerprint.reviewCount <= 100 &&
+        fingerprint.threadCount <= 20 &&
+        !fingerprint.hasMultiCommentThreads &&
+        fingerprint.rulesComplete);
+}
+/**
+ * GraphQL fingerprint reuse. Returns a decider for `fetchPrBatch`'s first page, or `undefined`
+ * when the stored report cannot be reused whatever GitHub says. The decider replays the stored
+ * report only when the first page's fingerprint equals the stored one, so a hit costs the one
+ * BatchPr request and skips every supplement, and a miss continues the same snapshot.
+ */
+export async function fingerprintReuser(prNumber, repo, stateKey, config) {
+    if (getGithubTransport() === "rest")
+        return undefined;
     const cached = await loadPrFingerprint(stateKey);
     if (cached?.inputDigest == null || cached.inputDigest !== fingerprintInputDigest(config)) {
-        return null;
+        return undefined;
     }
     if (!reportAllowsFingerprintSkip(cached.report))
+        return undefined;
+    if (!fingerprintIsComplete(cached.fingerprint))
+        return undefined;
+    return async (live) => {
+        if (!fingerprintIsComplete(live) || !fingerprintsEqual(cached.fingerprint, live))
+            return null;
+        try {
+            const survives = await cachedReportSurvivesMergeabilityRefresh(prNumber, repo, cached.report, cached.fingerprint);
+            if (!survives)
+                return null;
+        }
+        catch {
+            // This REST read runs inside the GraphQL BatchPr operation. Its failure must not read as a
+            // GraphQL failure (which could switch transports), so build the full snapshot instead.
+            return null;
+        }
+        return {
+            ...stripReplayedRuleAutoResolve(cached.report),
+            fingerprintReused: true,
+        };
+    };
+}
+/**
+ * REST counterpart of `fingerprintReuser`: after the snapshot reads, reuse the previous
+ * report only when every conditional read came back 304 with the same validators it was built
+ * from. No separate mergeability read is made. Mergeability moves when the head or the base
+ * moves: the head is in the pull body, and the base branch summary read by
+ * `readRestBranchRules` carries the base's `commit.sha`, so a base push answers 200 and blocks
+ * reuse. An unsettled `mergeable: null` pull body is never cached, so it cannot answer 304.
+ */
+export async function tryReuseRestSnapshotReport(stateKey, config, snapshot) {
+    if (snapshot === undefined || !snapshot.allNotModified)
         return null;
-    if (cached.fingerprint.isInMergeQueue)
-        return null;
-    if (!cached.fingerprint.checkSuitesComplete)
-        return null;
-    if (cached.fingerprint.commentCount > 100)
-        return null;
-    if (cached.fingerprint.reviewCount > 100)
-        return null;
-    if (cached.fingerprint.threadCount > 20)
-        return null;
-    if (cached.fingerprint.hasMultiCommentThreads)
-        return null;
-    if (!cached.fingerprint.rulesComplete)
-        return null;
-    const live = await fetchPrFingerprint(prNumber, repo);
-    if (live.isInMergeQueue || !live.checkSuitesComplete)
-        return null;
-    if (live.commentCount > 100 || live.reviewCount > 100 || live.threadCount > 20)
-        return null;
-    if (live.hasMultiCommentThreads || !live.rulesComplete)
+    const cached = await loadRestSnapshotReport(stateKey);
+    if (cached === null || cached.snapshotDigest !== snapshot.digest)
         return null;
-    if (!fingerprintsEqual(cached.fingerprint, live))
+    if (cached.inputDigest !== fingerprintInputDigest(config))
         return null;
-    if (!(await cachedReportSurvivesMergeabilityRefresh(prNumber, repo, cached.report, cached.fingerprint))) {
+    if (!reportAllowsFingerprintSkip(cached.report))
         return null;
-    }
-    return { ...stripReplayedRuleAutoResolve(cached.report), fingerprintReused: true };
+    return {
+        ...stripReplayedRuleAutoResolve(cached.report),
+        fingerprintReused: true,
+    };
 }
 async function cachedReportSurvivesMergeabilityRefresh(prNumber, repo, report, fingerprint) {
     const restDerived = fingerprint.mergeable !== report.mergeStatus.mergeable ||

package/bin/commands/check-terminal-report.mjs

@@ -1,12 +1,22 @@
+/** A merged PR answered from its first REST pull read never read reviews, threads or rules. */
+const requirementsUnread = (batchData) => (batchData.transportUnavailable ?? []).some(({ field }) => field === "mergeRequirements");
+function withoutRequirements(mergeStatus) {
+    const { mergeRequirements: _unread, ...rest } = mergeStatus;
+    return rest;
+}
 export function buildTerminalReport(prNumber, repo, batchData, mergeStatus, status) {
     return {
         pr: prNumber,
         nodeId: batchData.nodeId,
+        ...(batchData.transport && { transport: batchData.transport }),
+        ...(batchData.transportUnavailable?.length && {
+            transportUnavailable: batchData.transportUnavailable,
+        }),
         headSha: batchData.headRefOid,
         repo: `${repo.owner}/${repo.name}`,
         status,
         baseBranch: batchData.baseRefName,
-        mergeStatus,
+        mergeStatus: requirementsUnread(batchData) ? withoutRequirements(mergeStatus) : mergeStatus,
         checks: {
             passing: [],
             failing: [],

package/bin/commands/check-unreported.d.mts

@@ -3,6 +3,8 @@ import type { BatchPrData, CheckRun, ShepherdReport } from "../types.mts";
 import type { RepoInfo } from "../github/client.mts";
 import type { CheckExecutionContext } from "./check-execution-context.mts";
 export interface UnreportedRequiredFields {
+    /** Required contexts of the merge target: the stack trunk for a native-stack layer. */
+    requiredContexts: string[];
     unreportedRequiredChecks?: string[];
     trunkBehindBy?: number;
     /** Commits on the PR base that this head does not contain. Omitted when zero or a stack. */
@@ -24,6 +26,8 @@ export declare function collectUnreportedRequired(input: {
 }, context?: CheckExecutionContext): Promise<UnreportedRequiredFields>;
 /**
  * A fingerprint hit can keep a stale trunk `behindBy`. Refresh the trunk compare
- * and the required-context diff without refetching the whole batch.
+ * and the required-context diff without refetching the whole batch. Returns null
+ * when the trunk's required contexts changed: they decide how checks classify, so
+ * the cached report cannot be patched and the caller must check afresh.
  */
-export declare function refreshCachedUnreported(report: ShepherdReport, repo: RepoInfo, context?: CheckExecutionContext): Promise<ShepherdReport>;
+export declare function refreshCachedUnreported(report: ShepherdReport, repo: RepoInfo, context?: CheckExecutionContext, baseTipOid?: string): Promise<ShepherdReport | null>;

package/bin/commands/check-unreported.mjs

@@ -11,18 +11,24 @@ export async function collectUnreportedRequired(input, context) {
         pr: input.pr,
         baseRefName: input.batchData.baseRefName,
         headRefName: input.batchData.headRefName,
+        headRefOid: input.batchData.headRefOid,
         localContexts,
         stack: input.batchData.stack,
     }, context);
     const unreported = unreportedRequiredContexts(target.contexts, reportedCheckNames(input.checks));
+    // Like `baseBehindBy`, the trunk compare matters only to an unreported required check.
+    const trunkBehindBy = unreported.length > 0 && target.trunkBehindBy ? await target.trunkBehindBy() : 0;
     const actionsRunning = actionsWorkflowInProgress(input.suites, new Set(input.relevantEvents));
     const baseBehindBy = unreported.length > 0 && !input.batchData.stack
-        ? await loadBaseBehindBy(input.owner, input.name, input.batchData.baseRefName, input.batchData.headRefOid)
+        ? await loadBaseBehindBy(input.owner, input.name, input.batchData.baseRefName, input.batchData.headRefOid, {
+            stateKey: { owner: input.owner, repo: input.name, pr: input.pr },
+            ...(input.batchData.baseTipOid && { baseTipOid: input.batchData.baseTipOid }),
+        })
         : 0;
     return {
+        requiredContexts: target.contexts,
         ...(unreported.length > 0 && { unreportedRequiredChecks: unreported }),
-        ...(target.trunkBehindBy !== undefined &&
-            target.trunkBehindBy > 0 && { trunkBehindBy: target.trunkBehindBy }),
+        ...(trunkBehindBy > 0 && { trunkBehindBy }),
         ...(baseBehindBy > 0 && { baseBehindBy }),
         ...(actionsRunning && { actionsWorkflowInProgress: true }),
         ...(target.stackBottomPr !== undefined && { stackBottomPr: target.stackBottomPr }),
@@ -32,32 +38,38 @@ export async function collectUnreportedRequired(input, context) {
 }
 /**
  * A fingerprint hit can keep a stale trunk `behindBy`. Refresh the trunk compare
- * and the required-context diff without refetching the whole batch.
+ * and the required-context diff without refetching the whole batch. Returns null
+ * when the trunk's required contexts changed: they decide how checks classify, so
+ * the cached report cannot be patched and the caller must check afresh.
  */
-export async function refreshCachedUnreported(report, repo, context) {
+export async function refreshCachedUnreported(report, repo, context, baseTipOid) {
     const stack = report.mergeStatus?.mergeRequirements?.stack;
     if (!report.headRefName)
         return report;
     if (!stack)
-        return refreshBaseBehind(report, repo);
+        return refreshBaseBehind(report, repo, baseTipOid);
+    const cached = report.mergeStatus.mergeRequirements?.requiredStatusChecks?.contexts ?? [];
     const target = await loadMergeTargetStatus({
         owner: repo.owner,
         name: repo.name,
         pr: report.pr,
         baseRefName: report.baseBranch,
         headRefName: report.headRefName,
-        localContexts: report.mergeStatus.mergeRequirements?.requiredStatusChecks?.contexts ?? [],
+        ...(report.headSha && { headRefOid: report.headSha }),
+        localContexts: cached,
         stack,
     }, context);
+    if (!sameContexts(cached, target.contexts))
+        return null;
     const unreported = unreportedRequiredContexts(target.contexts, reportedCheckNames(reportChecks(report)));
     const next = { ...report };
     if (unreported.length > 0)
         next.unreportedRequiredChecks = unreported;
     else
         delete next.unreportedRequiredChecks;
-    if (target.trunkBehindBy !== undefined && target.trunkBehindBy > 0) {
-        next.trunkBehindBy = target.trunkBehindBy;
-    }
+    const trunkBehindBy = unreported.length > 0 && target.trunkBehindBy ? await target.trunkBehindBy() : 0;
+    if (trunkBehindBy > 0)
+        next.trunkBehindBy = trunkBehindBy;
     else
         delete next.trunkBehindBy;
     if (target.stackBottomPr !== undefined)
@@ -67,7 +79,7 @@ export async function refreshCachedUnreported(report, repo, context) {
     return next;
 }
 /** A fingerprint hit can keep a stale base compare after main moves. */
-async function refreshBaseBehind(report, repo) {
+async function refreshBaseBehind(report, repo, baseTipOid) {
     if ((report.unreportedRequiredChecks?.length ?? 0) === 0) {
         if (report.baseBehindBy === undefined)
             return report;
@@ -80,7 +92,10 @@ async function refreshBaseBehind(report, repo) {
     const headOid = report.headSha;
     if (!headOid)
         return report;
-    const behind = await loadBaseBehindBy(repo.owner, repo.name, report.baseBranch, headOid);
+    const behind = await loadBaseBehindBy(repo.owner, repo.name, report.baseBranch, headOid, {
+        stateKey: { owner: repo.owner, repo: repo.name, pr: report.pr },
+        ...(baseTipOid && { baseTipOid }),
+    });
     const next = { ...report };
     if (behind > 0)
         next.baseBehindBy = behind;
@@ -99,3 +114,8 @@ function reportChecks(report) {
         ...(report.checks.supersededNames ?? []).map((name) => ({ name })),
     ];
 }
+function sameContexts(a, b) {
+    const left = new Set(a.map((c) => c.trim()));
+    const right = new Set(b.map((c) => c.trim()));
+    return left.size === right.size && [...right].every((c) => left.has(c));
+}

package/bin/commands/check-wait-detectors.d.mts

@@ -0,0 +1,35 @@
+import type { RepoInfo } from "../github/client.mts";
+import { type PrFingerprint } from "../github/fingerprint.mts";
+import type { PrShepherdConfig } from "../config/load.mts";
+import type { ShepherdReport } from "../types.mts";
+type StateKey = {
+    owner: string;
+    repo: string;
+    pr: number;
+};
+/**
+ * Outcome of the GraphQL transport's REST change detectors. `reused` replays the stored report
+ * without any GraphQL request. Otherwise `digest` is what the detectors read before this tick's
+ * GraphQL snapshot, recorded beside the new report by `recordWaitDetectors`.
+ */
+export type WaitDetectorResult = {
+    reused: ShepherdReport;
+    baseTipOid: string;
+} | {
+    digest: string;
+    readAt: number;
+};
+/**
+ * On the GraphQL transport, run the REST change detectors for an idle stored report. Returns
+ * `undefined` when the detectors do not apply. A detector failure never reaches the GraphQL
+ * transport's fallback: the tick just takes its ordinary GraphQL path. A secondary rate limit
+ * is rethrown so the tick aborts and polling backs off.
+ */
+export declare function readWaitDetectors(prNumber: number, repo: RepoInfo, stateKey: StateKey, config: PrShepherdConfig, now?: number): Promise<WaitDetectorResult | undefined>;
+/**
+ * After a GraphQL tick, store the digest its detectors read beside the report that tick built.
+ * `fingerprint` is the tick's live fingerprint; the stored entry must be the one it wrote (or
+ * the unchanged entry a fingerprint hit replayed), so a stale report never gains a digest.
+ */
+export declare function recordWaitDetectors(stateKey: StateKey, config: PrShepherdConfig, detectors: WaitDetectorResult | undefined, fingerprint: PrFingerprint | undefined): Promise<void>;
+export {};

package/bin/commands/check-wait-detectors.mjs

@@ -0,0 +1,107 @@
+import { fingerprintsEqual } from "../github/fingerprint.mjs";
+import { readRest, readRestPages, restCollection, restObject, restRepoPath, restString, } from "../github/rest-reader-core.mjs";
+import { restSnapshotState, withRestConditionalScope } from "../github/rest-conditional-scope.mjs";
+import { getGithubTransport } from "../github/transport.mjs";
+import { GitHubRequestError } from "../github/errors.mjs";
+import { rateLimitKind } from "../github/rate-limit-kind.mjs";
+import { attachWaitDetectors, fingerprintInputDigest, loadPrFingerprint, } from "../state/pr-fingerprint.mjs";
+import { fingerprintIsComplete, reportAllowsFingerprintSkip } from "./check-fingerprint.mjs";
+import { stripReplayedRuleAutoResolve } from "./rule-auto-resolve-format.mjs";
+/**
+ * Whether conditional REST reads can stand in for the GraphQL snapshot of this stored report.
+ * Only an idle wait qualifies: nothing to act on, no check still running, a settled single-PR
+ * merge state from GraphQL, and a fingerprint whose windows cover everything it summarizes.
+ */
+function detectorsCover(stored) {
+    const { report, fingerprint } = stored;
+    return (report.transport === undefined &&
+        report.headSha !== undefined &&
+        reportAllowsFingerprintSkip(report) &&
+        fingerprintIsComplete(fingerprint) &&
+        report.checks.inProgress.length === 0 &&
+        report.actionsWorkflowInProgress !== true &&
+        report.mergeStatus.status !== "UNKNOWN" &&
+        report.mergeStatus.mergeRequirements?.stack === undefined &&
+        fingerprint.stackKey === "" &&
+        fingerprint.mergeable === report.mergeStatus.mergeable &&
+        fingerprint.mergeStateStatus === report.mergeStatus.mergeStateStatus);
+}
+/**
+ * Read the PR's REST change detectors: the pull, the head's check runs, check suites and
+ * statuses, the three feedback lists, and the base branch. Every read is conditional, so an
+ * unchanged resource answers a free 304.
+ */
+async function readDetectors(prNumber, repo, report) {
+    const prefix = restRepoPath(repo);
+    const head = encodeURIComponent(report.headSha);
+    await readRest("GET", `${prefix}/pulls/${prNumber}`);
+    await readRestPages(`${prefix}/commits/${head}/check-runs?filter=latest`, (body) => restCollection(body, "check_runs"));
+    await readRestPages(`${prefix}/commits/${head}/check-suites`, (body) => restCollection(body, "check_suites"));
+    await readRestPages(`${prefix}/commits/${head}/statuses`);
+    await readRestPages(`${prefix}/pulls/${prNumber}/reviews`);
+    await readRestPages(`${prefix}/issues/${prNumber}/comments`);
+    await readRestPages(`${prefix}/pulls/${prNumber}/comments`);
+    const branch = restObject(await readRest("GET", `${prefix}/branches/${encodeURIComponent(report.baseBranch)}`), "base branch");
+    return restString(restObject(branch.commit, "base branch commit").sha, "base branch sha");
+}
+/**
+ * On the GraphQL transport, run the REST change detectors for an idle stored report. Returns
+ * `undefined` when the detectors do not apply. A detector failure never reaches the GraphQL
+ * transport's fallback: the tick just takes its ordinary GraphQL path. A secondary rate limit
+ * is rethrown so the tick aborts and polling backs off.
+ */
+export async function readWaitDetectors(prNumber, repo, stateKey, config, now = Date.now()) {
+    const reconcileMs = config.poll.reconcileSeconds * 1000;
+    if (reconcileMs === 0 || getGithubTransport() === "rest")
+        return undefined;
+    const stored = await loadPrFingerprint(stateKey);
+    if (stored === null || stored.inputDigest !== fingerprintInputDigest(config))
+        return undefined;
+    if (!detectorsCover(stored))
+        return undefined;
+    let observed;
+    try {
+        observed = await withRestConditionalScope(stateKey, async () => {
+            const baseTipOid = await readDetectors(prNumber, repo, stored.report);
+            return { baseTipOid, state: restSnapshotState() };
+        });
+    }
+    catch (error) {
+        // A secondary limit aborts the tick, as at the other REST call sites, so polling backs off.
+        if (error instanceof GitHubRequestError && rateLimitKind(error) === "secondary")
+            throw error;
+        return undefined;
+    }
+    const state = observed.state;
+    const previous = stored.detectors;
+    if (state.allNotModified &&
+        previous?.digest === state.digest &&
+        typeof previous.fullAt === "number" &&
+        now - previous.fullAt < reconcileMs) {
+        return {
+            reused: { ...stripReplayedRuleAutoResolve(stored.report), fingerprintReused: true },
+            baseTipOid: observed.baseTipOid,
+        };
+    }
+    return { digest: state.digest, readAt: now };
+}
+/**
+ * After a GraphQL tick, store the digest its detectors read beside the report that tick built.
+ * `fingerprint` is the tick's live fingerprint; the stored entry must be the one it wrote (or
+ * the unchanged entry a fingerprint hit replayed), so a stale report never gains a digest.
+ */
+export async function recordWaitDetectors(stateKey, config, detectors, fingerprint) {
+    if (detectors === undefined || "reused" in detectors)
+        return;
+    const stored = await loadPrFingerprint(stateKey);
+    if (stored === null || stored.inputDigest !== fingerprintInputDigest(config))
+        return;
+    if (fingerprint !== undefined && !fingerprintsEqual(stored.fingerprint, fingerprint))
+        return;
+    if (!detectorsCover(stored))
+        return;
+    await attachWaitDetectors(stateKey, stored, {
+        digest: detectors.digest,
+        fullAt: detectors.readAt,
+    });
+}

package/bin/commands/check.d.mts

@@ -1,10 +1,12 @@
 import type { CheckExecutionContext } from "./check-execution-context.mts";
 import type { GlobalOptions, ShepherdReport } from "../types.mts";
-export declare function runCheck(opts: GlobalOptions & {
+type CheckOptions = GlobalOptions & {
     autoResolve?: boolean;
     autoMinimizeSuppressed?: boolean;
     skipTriage?: boolean;
     persistSeen?: boolean;
     fingerprintCache?: boolean;
     merge?: boolean;
-}, context?: CheckExecutionContext): Promise<ShepherdReport>;
+};
+export declare function runCheck(opts: CheckOptions, context?: CheckExecutionContext): Promise<ShepherdReport>;
+export {};