pr-shepherd 0.46.8 → 0.47.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.46.8",
+  "version": "0.47.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/api.d.mts

@@ -8,7 +8,7 @@ export interface CreatePrShepherdOptions {
 }
 /** A positive PR number, GitHub pull-request URL, or owner/repo#number reference. */
 export type PrReference = number | string;
-export type IterateInput = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "deferQuotaWarning"> & {
+export type IterateInput = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "fingerprintCache" | "deferQuotaWarning"> & {
     pr?: PrReference;
 };
 export interface ReviewMutationsOperation {

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

@@ -0,0 +1,8 @@
+import { type RepoInfo } from "../github/client.mts";
+import type { PrShepherdConfig } from "../config/load.mts";
+import type { ShepherdReport } from "../types.mts";
+export declare function tryReuseFingerprintReport(prNumber: number, repo: RepoInfo, stateKey: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, config: PrShepherdConfig): Promise<ShepherdReport | null>;

package/bin/commands/check-fingerprint.mjs

@@ -0,0 +1,69 @@
+import { getMergeableState } from "../github/client.mjs";
+import { fetchPrFingerprint, fingerprintsEqual, } from "../github/fingerprint.mjs";
+import { fingerprintInputDigest, loadPrFingerprint } from "../state/pr-fingerprint.mjs";
+import { hasCheckDrivenActionableWork } from "./check-annotations.mjs";
+function reportAllowsFingerprintSkip(report) {
+    if (report.status === "READY")
+        return false;
+    if (report.mergeStatus.state !== "OPEN")
+        return false;
+    if (report.mergeQueue?.inQueue === true)
+        return false;
+    return (report.threads.actionable.length === 0 &&
+        report.threads.resolutionOnly.length === 0 &&
+        report.threads.firstLook.length === 0 &&
+        (report.threads.ruleAutoResolveIds?.length ?? 0) === 0 &&
+        report.comments.actionable.length === 0 &&
+        (report.comments.minimizeIds?.length ?? 0) === 0 &&
+        report.comments.firstLook.length === 0 &&
+        report.changesRequestedReviews.length === 0 &&
+        report.approvedReviews.length === 0 &&
+        report.firstLookSummaries.length === 0 &&
+        report.editedSummaries.length === 0 &&
+        (report.ruleAutoResolveReviewSummaryIds?.length ?? 0) === 0 &&
+        !hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status));
+}
+export async function tryReuseFingerprintReport(prNumber, repo, stateKey, config) {
+    const cached = await loadPrFingerprint(stateKey);
+    if (cached?.inputDigest == null || cached.inputDigest !== fingerprintInputDigest(config)) {
+        return null;
+    }
+    if (!reportAllowsFingerprintSkip(cached.report))
+        return null;
+    const live = await fetchPrFingerprint(prNumber, repo);
+    if (live.isInMergeQueue || cached.fingerprint.isInMergeQueue)
+        return null;
+    if (!live.checkSuitesComplete || !cached.fingerprint.checkSuitesComplete)
+        return null;
+    if (live.commentCount > 100 || cached.fingerprint.commentCount > 100)
+        return null;
+    if (live.reviewCount > 100 || cached.fingerprint.reviewCount > 100)
+        return null;
+    if (live.threadCount > 20 || cached.fingerprint.threadCount > 20)
+        return null;
+    if (live.hasMultiCommentThreads || cached.fingerprint.hasMultiCommentThreads)
+        return null;
+    if (!live.rulesComplete || !cached.fingerprint.rulesComplete)
+        return null;
+    if (!fingerprintsEqual(cached.fingerprint, live))
+        return null;
+    if (!(await cachedReportSurvivesMergeabilityRefresh(prNumber, repo, cached.report, cached.fingerprint))) {
+        return null;
+    }
+    return { ...cached.report, fingerprintReused: true };
+}
+async function cachedReportSurvivesMergeabilityRefresh(prNumber, repo, report, fingerprint) {
+    const restDerived = fingerprint.mergeable !== report.mergeStatus.mergeable ||
+        fingerprint.mergeStateStatus !== report.mergeStatus.mergeStateStatus;
+    if (report.status !== "READY" && report.mergeStatus.status !== "UNKNOWN" && !restDerived) {
+        return true;
+    }
+    const rest = await getMergeableState(prNumber, repo.owner, repo.name);
+    if (rest.state === "MERGED" || rest.state === "CLOSED")
+        return false;
+    if (rest.mergeable !== report.mergeStatus.mergeable)
+        return false;
+    if (rest.mergeStateStatus !== report.mergeStatus.mergeStateStatus)
+        return false;
+    return true;
+}

package/bin/commands/check.d.mts

@@ -4,5 +4,6 @@ export declare function runCheck(opts: GlobalOptions & {
     autoMinimizeSuppressed?: boolean;
     skipTriage?: boolean;
     persistSeen?: boolean;
+    fingerprintCache?: boolean;
     merge?: boolean;
 }): Promise<ShepherdReport>;

package/bin/commands/check.mjs

@@ -1,4 +1,6 @@
 import { fetchPrBatch } from "../github/batch.mjs";
+import { storePrFingerprint } from "../state/pr-fingerprint.mjs";
+import { tryReuseFingerprintReport } from "./check-fingerprint.mjs";
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
@@ -30,6 +32,12 @@ export async function runCheck(opts) {
     }
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const config = loadConfig();
+    const reuseFingerprint = opts.fingerprintCache === true;
+    if (reuseFingerprint) {
+        const cached = await tryReuseFingerprintReport(prNumber, repo, stateKey, config);
+        if (cached)
+            return cached;
+    }
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
     const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
     let batchData = result.data;
@@ -38,7 +46,11 @@ export async function runCheck(opts) {
     const didRefreshMergeability = unknownRefresh.didRefresh;
     let mergeStatus = deriveMergeStatus(batchData);
     if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
-        return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+        const terminal = buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+        if (result.fingerprint) {
+            await storePrFingerprint(stateKey, result.fingerprint, terminal, config);
+        }
+        return terminal;
     }
     const startupFailuresNeedAttempt = batchData.checks.some((check) => check.source === "startup_failure" && check.runAttempt === undefined);
     const startupFailureChecks = result.checkSuitesComplete && !startupFailuresNeedAttempt
@@ -145,7 +157,11 @@ export async function runCheck(opts) {
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
         if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
-            return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+            const terminal = buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+            if (result.fingerprint) {
+                await storePrFingerprint(stateKey, result.fingerprint, terminal, config);
+            }
+            return terminal;
         }
     }
     // Mirrors the deferral gate in commands/iterate/index.mts exactly (via the shared
@@ -225,7 +241,7 @@ export async function runCheck(opts) {
         batchData.isInMergeQueue ||
         batchData.autoMergeRequest ||
         batchData.latestMergeQueueRemoval);
-    return {
+    const report = {
         pr: prNumber,
         nodeId: batchData.nodeId,
         headSha: batchData.headRefOid,
@@ -290,6 +306,10 @@ export async function runCheck(opts) {
             },
         }),
     };
+    if (result.fingerprint) {
+        await storePrFingerprint(stateKey, result.fingerprint, report, config);
+    }
+    return report;
 }
 async function remainingRuleAutoResolveIds(partition, autoMinimizeSuppressed = false) {
     const consumedIds = autoMinimizeSuppressed

package/bin/commands/iterate/base.mjs

@@ -21,5 +21,6 @@ export function buildIterateBase(report, readyState) {
         ...buildSuppressedCheckFields(report),
         activity: report.activity,
         mergeQueue: report.mergeQueue,
+        ...(report.fingerprintReused === true && { fingerprintReused: true }),
     };
 }

package/bin/commands/iterate/mark-ready.mjs

@@ -4,6 +4,14 @@ import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.m
 export async function markReadyIfAuthorized(enabled, base, report) {
     if (!enabled)
         return null;
+    if (report.fingerprintReused === true) {
+        return {
+            ...base,
+            action: "mark_ready",
+            markedReady: false,
+            log: `READY: PR #${report.pr} is ready to mark; refresh required before converting draft`,
+        };
+    }
     if (report.viewerAuthorization?.viewerCanUpdate === true) {
         await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });
         return {

package/bin/commands/poll-progress.d.mts

@@ -0,0 +1,11 @@
+import type { IterateResult } from "../types.mts";
+export declare function writeWaitProgress(opts: {
+    tick: number;
+    elapsedMs: number;
+    sleepMs: number;
+    result: IterateResult;
+    quietStatus: boolean;
+    verbose: boolean;
+    lastWaitSignature: string | null;
+}): string | null;
+export declare function writeDebounceProgress(tick: number, elapsedMs: number, remainingMs: number): void;

package/bin/commands/poll-progress.mjs

@@ -0,0 +1,52 @@
+function writeTickProgress(tick, elapsedSeconds, detail) {
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — ${detail}\n`);
+}
+function waitSignature(result) {
+    const activity = result.activity ?? {
+        commitCount: 0,
+        reviewRoundCount: 0,
+        latestCommitCommittedAtUnix: null,
+        reviewItemsSinceLatestCommit: [],
+    };
+    return JSON.stringify({
+        status: result.status,
+        mergeStateStatus: result.mergeStateStatus,
+        reviewDecision: result.reviewDecision,
+        state: result.state,
+        active: (result.inProgressChecks ?? []).map((c) => [c.name, c.status, c.runId]),
+        commitCount: activity.commitCount,
+        latestCommitCommittedAtUnix: activity.latestCommitCommittedAtUnix,
+        reviewRoundCount: activity.reviewRoundCount,
+        reviewItemsSinceLatestCommit: activity.reviewItemsSinceLatestCommit.length,
+    });
+}
+function writeQuietStatus(tick, elapsedSeconds, sleepSeconds, result) {
+    const activeChecks = result.inProgressChecks ?? [];
+    const activeCheckText = activeChecks.map((c) => `${c.name} (${c.status})`).join(", ");
+    const active = activeChecks.length > 0 ? ` · active: ${activeCheckText}` : "";
+    const commitCount = result.activity?.commitCount ?? 0;
+    const reviewItems = result.activity?.reviewItemsSinceLatestCommit.length ?? 0;
+    const reviewRounds = result.activity?.reviewRoundCount ?? 0;
+    const commitSeg = commitCount > 0 ? ` · ${commitCount} commits` : "";
+    const reviewRoundSeg = reviewRounds > 0 ? ` · ${reviewRounds} review rounds` : "";
+    const reviewSeg = reviewItems > 0 ? ` · ${reviewItems} review items since latest commit` : "";
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT ${result.status}/${result.mergeStateStatus}/${result.reviewDecision ?? "NO_REVIEW_DECISION"}${active}${commitSeg}${reviewRoundSeg}${reviewSeg} — sleeping ${sleepSeconds}s\n`);
+}
+export function writeWaitProgress(opts) {
+    const elapsedSeconds = Math.round(opts.elapsedMs / 1000);
+    const sleepSeconds = Math.round(opts.sleepMs / 1000);
+    if (!opts.quietStatus) {
+        writeTickProgress(opts.tick, elapsedSeconds, opts.verbose ? `sleeping ${sleepSeconds}s` : `still running; next tick in ${sleepSeconds}s`);
+        return opts.lastWaitSignature;
+    }
+    const signature = waitSignature(opts.result);
+    if (signature !== opts.lastWaitSignature) {
+        writeQuietStatus(opts.tick, elapsedSeconds, sleepSeconds, opts.result);
+    }
+    return signature;
+}
+export function writeDebounceProgress(tick, elapsedMs, remainingMs) {
+    const elapsedSeconds = Math.round(elapsedMs / 1000);
+    const remainingSeconds = Math.round(remainingMs / 1000);
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
+}

package/bin/commands/poll-quota.d.mts

@@ -0,0 +1,9 @@
+import type { GraphqlQuotaWarningBand } from "../config/load.mts";
+import type { GraphqlApiUsage } from "../types.mts";
+/** Sleep at least `--interval`, and at least the active crossed quota band. */
+export declare function graphqlQuotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], usage: Pick<GraphqlApiUsage, "remaining" | "limit"> | undefined, fallbackMs: number, maxMs: number): number;
+/**
+ * Retry delay for `--until-terminal` when GitHub returns a GraphQL 429 / secondary
+ * limit. `null` means the error is not a retryable rate limit.
+ */
+export declare function pollGraphQlRetryAfterMs(err: unknown): number | null;

package/bin/commands/poll-quota.mjs

@@ -0,0 +1,36 @@
+import { GitHubRequestError } from "../github/errors.mjs";
+import { isRateLimitMessage } from "../comments/rate-limit.mjs";
+const GRAPHQL_RETRY_AFTER_DEFAULT_MS = 60_000;
+/** Sleep at least `--interval`, and at least the active crossed quota band. */
+export function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
+    if (usage === undefined || usage.limit <= 0 || bands.length === 0) {
+        return Math.min(fallbackMs, maxMs);
+    }
+    const crossed = bands.filter((band) => usage.remaining * 100 <= usage.limit * band.remainingPercent);
+    if (crossed.length === 0)
+        return Math.min(fallbackMs, maxMs);
+    const active = crossed.reduce((lowest, band) => band.remainingPercent < lowest.remainingPercent ? band : lowest);
+    const bandMs = active.pollIntervalMinutes * 60_000;
+    return Math.min(Math.max(fallbackMs, bandMs), maxMs);
+}
+/**
+ * Retry delay for `--until-terminal` when GitHub returns a GraphQL 429 / secondary
+ * limit. `null` means the error is not a retryable rate limit.
+ */
+export function pollGraphQlRetryAfterMs(err) {
+    if (!(err instanceof GitHubRequestError))
+        return null;
+    const retryable = err.status === 429 ||
+        err.retryAfterSeconds !== undefined ||
+        isRateLimitMessage(err.message) ||
+        (err.graphqlErrors?.some((error) => isRateLimitMessage(error.message)) ?? false) ||
+        (err.rateLimit !== undefined && err.rateLimit.remaining <= 0);
+    if (!retryable)
+        return null;
+    if (err.retryAfterSeconds !== undefined)
+        return Math.max(err.retryAfterSeconds, 0) * 1000;
+    if (err.rateLimit !== undefined && err.rateLimit.remaining <= 0) {
+        return Math.max(err.rateLimit.resetAt * 1000 - Date.now(), 0);
+    }
+    return GRAPHQL_RETRY_AFTER_DEFAULT_MS;
+}

package/bin/commands/poll.mjs

@@ -1,66 +1,12 @@
 import { runIterate } from "./iterate/index.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { withPollApiUsage } from "./poll-run.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs } from "./poll-quota.mjs";
+import { writeDebounceProgress, writeWaitProgress } from "./poll-progress.mjs";
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
-function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
-    if (verbose) {
-        process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — sleeping ${sleepSeconds}s\n`);
-    }
-    else {
-        process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — still running; next tick in ${sleepSeconds}s\n`);
-    }
-}
-function waitSignature(result) {
-    const activity = result.activity ?? {
-        commitCount: 0,
-        reviewRoundCount: 0,
-        latestCommitCommittedAtUnix: null,
-        reviewItemsSinceLatestCommit: [],
-    };
-    return JSON.stringify({
-        status: result.status,
-        mergeStateStatus: result.mergeStateStatus,
-        reviewDecision: result.reviewDecision,
-        state: result.state,
-        active: (result.inProgressChecks ?? []).map((c) => [c.name, c.status, c.runId]),
-        commitCount: activity.commitCount,
-        latestCommitCommittedAtUnix: activity.latestCommitCommittedAtUnix,
-        reviewRoundCount: activity.reviewRoundCount,
-        reviewItemsSinceLatestCommit: activity.reviewItemsSinceLatestCommit.length,
-    });
-}
-function writeQuietStatus(tick, elapsedSeconds, sleepSeconds, result) {
-    const activeChecks = result.inProgressChecks ?? [];
-    const activeCheckText = activeChecks.map((c) => `${c.name} (${c.status})`).join(", ");
-    const active = activeChecks.length > 0 ? ` · active: ${activeCheckText}` : "";
-    const commitCount = result.activity?.commitCount ?? 0;
-    const reviewItems = result.activity?.reviewItemsSinceLatestCommit.length ?? 0;
-    const reviewRounds = result.activity?.reviewRoundCount ?? 0;
-    const commitSeg = commitCount > 0 ? ` · ${commitCount} commits` : "";
-    const reviewRoundSeg = reviewRounds > 0 ? ` · ${reviewRounds} review rounds` : "";
-    const reviewSeg = reviewItems > 0 ? ` · ${reviewItems} review items since latest commit` : "";
-    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT ${result.status}/${result.mergeStateStatus}/${result.reviewDecision ?? "NO_REVIEW_DECISION"}${active}${commitSeg}${reviewRoundSeg}${reviewSeg} — sleeping ${sleepSeconds}s\n`);
-}
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const TIMER_DRIFT_TOLERANCE_MS = 500;
-function writeWaitProgress(opts) {
-    const elapsedSeconds = Math.round(opts.elapsedMs / 1000);
-    const sleepSeconds = Math.round(opts.sleepMs / 1000);
-    if (!opts.quietStatus) {
-        writeTickProgress(opts.tick, elapsedSeconds, sleepSeconds, opts.verbose);
-        return opts.lastWaitSignature;
-    }
-    const signature = waitSignature(opts.result);
-    if (signature !== opts.lastWaitSignature) {
-        writeQuietStatus(opts.tick, elapsedSeconds, sleepSeconds, opts.result);
-    }
-    return signature;
-}
-function writeDebounceProgress(tick, elapsedMs, remainingMs) {
-    const elapsedSeconds = Math.round(elapsedMs / 1000);
-    const remainingSeconds = Math.round(remainingMs / 1000);
-    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
-}
 /** @deprecated Hidden implementation for the legacy `poll` alias. */
 export function runPoll(opts) {
     return withPollApiUsage(() => runPollCore(opts), opts.untilTerminal === true);
@@ -71,6 +17,7 @@ async function runPollCore(opts) {
     const timeoutMs = Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
     const debounceSeconds = debounceSecondsOpt ?? DEFAULT_POLL_DEBOUNCE_SECONDS;
     const debounceMs = Math.min(debounceSeconds * 1000, MAX_TIMER_MS);
+    const quotaBands = loadConfig().watch.graphqlQuotaWarnings;
     const start = Date.now();
     let tick = 0;
     let lastResult;
@@ -82,23 +29,64 @@ async function runPollCore(opts) {
     // Pin the PR resolved by the first tick; branch inference only matches OPEN PRs.
     let prNumber = opts.prNumber;
     let debounceUntil = null;
+    let rateLimitRetries = 0;
     while (true) {
         tick += 1;
         const pastDebounce = debounceUntil !== null && Date.now() >= debounceUntil;
-        lastResult = await runIterate({
+        const remainingBefore = untilTerminal
+            ? Number.POSITIVE_INFINITY
+            : timeoutMs - (Date.now() - start);
+        // Cache only internal continuation ticks. Last bounded tick, FIX_CODE debounce,
+        // and any tick we return to the caller must fetch BatchPr.
+        const allowCache = debounceUntil === null && remainingBefore + TIMER_DRIFT_TOLERANCE_MS >= intervalMs;
+        const iterateTick = (fingerprintCache) => runIterate({
             ...iterateOpts,
             prNumber,
             persistSeen: debounceSeconds === 0 || pastDebounce,
-            // Until-terminal must persist before deciding to return.
+            fingerprintCache,
             deferQuotaWarning: !untilTerminal,
         });
+        const runTick = async (fingerprintCache) => {
+            try {
+                const result = await iterateTick(fingerprintCache);
+                rateLimitRetries = 0;
+                return result;
+            }
+            catch (err) {
+                const retryMs = untilTerminal ? pollGraphQlRetryAfterMs(err) : null;
+                if (retryMs === null || rateLimitRetries >= 1)
+                    throw err;
+                rateLimitRetries += 1;
+                process.stderr.write(`[poll tick ${tick} / +${Math.round((Date.now() - start) / 1000)}s] GraphQL rate limit — retrying in ${Math.round(retryMs / 1000)}s\n`);
+                await sleep(retryMs);
+                const result = await iterateTick(fingerprintCache);
+                rateLimitRetries = 0;
+                return result;
+            }
+        };
+        lastResult = await runTick(allowCache);
         prNumber ??= lastResult.pr;
         if (lastResult.quotaWarning !== undefined)
             pendingQuotaWarning = lastResult.quotaWarning;
+        const refreshIfReturning = async () => {
+            if (lastResult?.fingerprintReused !== true)
+                return;
+            lastResult = await runTick(false);
+            if (lastResult.quotaWarning !== undefined)
+                pendingQuotaWarning = lastResult.quotaWarning;
+        };
         if (untilTerminal &&
             pendingQuotaWarning !== undefined &&
             !(lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) &&
             !(debounceUntil !== null && !pastDebounce)) {
+            await refreshIfReturning();
+            if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
+                debounceUntil ??= Date.now() + debounceMs;
+                const remainingMs = Math.max(debounceUntil - Date.now(), 0);
+                writeDebounceProgress(tick, Date.now() - start, remainingMs);
+                await sleep(Math.min(intervalMs, remainingMs));
+                continue;
+            }
             if (["cancel", "escalate"].includes(lastResult.action)) {
                 const { quotaWarning: _quotaWarning, ...withoutQuotaWarning } = lastResult;
                 lastResult = withoutQuotaWarning;
@@ -112,30 +100,40 @@ async function runPollCore(opts) {
             if (pendingQuotaWarning === undefined)
                 debounceUntil = null;
             const elapsedMs = Date.now() - start;
+            const sleepMs = graphqlQuotaPollIntervalMs(quotaBands, lastResult.apiUsage?.graphql, intervalMs, MAX_TIMER_MS);
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
-                if (remainingMs <= 0)
-                    break;
-                if (remainingMs + TIMER_DRIFT_TOLERANCE_MS < intervalMs)
+                if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
+                    await refreshIfReturning();
                     break;
+                }
             }
             lastWaitSignature = writeWaitProgress({
                 tick,
                 elapsedMs,
-                sleepMs: intervalMs,
+                sleepMs,
                 result: lastResult,
                 quietStatus,
                 verbose,
                 lastWaitSignature,
             });
-            await sleep(intervalMs);
+            await sleep(sleepMs);
             continue;
         }
         if ((untilTerminal || iterateOpts.merge) &&
             lastResult.action === "mark_ready" &&
             !pastDebounce) {
             debounceUntil = null;
-            await sleep(intervalMs);
+            const elapsedMs = Date.now() - start;
+            const sleepMs = graphqlQuotaPollIntervalMs(quotaBands, lastResult.apiUsage?.graphql, intervalMs, MAX_TIMER_MS);
+            if (!untilTerminal) {
+                const remainingMs = timeoutMs - elapsedMs;
+                if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
+                    await refreshIfReturning();
+                    break;
+                }
+            }
+            await sleep(sleepMs);
             continue;
         }
         if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
@@ -147,6 +145,7 @@ async function runPollCore(opts) {
             }
             continue;
         }
+        await refreshIfReturning();
         break;
     }
     return lastResult;

package/bin/config/load.mjs

@@ -166,7 +166,17 @@ function parseGraphqlQuotaWarnings(value) {
         seen.add(remainingPercent);
         return { remainingPercent, pollIntervalMinutes };
     });
-    return parsed.sort((left, right) => right.remainingPercent - left.remainingPercent);
+    parsed.sort((left, right) => right.remainingPercent - left.remainingPercent);
+    for (let index = 1; index < parsed.length; index += 1) {
+        const previous = parsed[index - 1];
+        const current = parsed[index];
+        if (previous !== undefined &&
+            current !== undefined &&
+            current.pollIntervalMinutes < previous.pollIntervalMinutes) {
+            throw new Error("Invalid config: watch.graphqlQuotaWarnings pollIntervalMinutes must not decrease as remainingPercent decreases");
+        }
+    }
+    return parsed;
 }
 const KNOWN_CONFIG_KEYS = new Set([
     "classify",

package/bin/github/batch-raw-rules.d.mts

@@ -21,7 +21,7 @@ interface RawCheckCommit {
             oid: string;
         }>;
     };
-    statusCheckRollup: {
+    statusCheckRollup?: {
         contexts: {
             pageInfo: {
                 hasNextPage: boolean;
@@ -82,6 +82,9 @@ interface RawRuleParameters {
 export interface RawBaseRef {
     branchProtectionRule: RawBranchProtectionRule | null;
     rules: {
+        pageInfo?: {
+            hasNextPage: boolean;
+        };
         nodes: RawRepositoryRule[];
     } | null;
 }

package/bin/github/batch-raw-types.d.mts

@@ -1,6 +1,9 @@
 import type { CommentAuthorAssociation } from "../types/github.mts";
 import type { RawPrMergeFields } from "./batch-raw-rules.mts";
 export interface RawBatchResponse {
+    viewer?: {
+        login: string | null;
+    } | null;
     repository: {
         viewerPermission: string | null;
         viewerCanAdminister: boolean;
@@ -10,6 +13,7 @@ export interface RawBatchResponse {
 export interface RawPr extends RawPrMergeFields {
     id: string;
     number: number;
+    updatedAt?: string;
     state: string;
     isDraft: boolean;
     viewerDidAuthor: boolean;
@@ -42,6 +46,7 @@ export interface RawPr extends RawPrMergeFields {
         }>;
     };
     reviewThreads: {
+        totalCount?: number;
         pageInfo: {
             hasPreviousPage: boolean;
             startCursor: string | null;
@@ -49,6 +54,7 @@ export interface RawPr extends RawPrMergeFields {
         nodes: RawThread[];
     };
     comments: {
+        totalCount?: number;
         pageInfo: {
             hasPreviousPage: boolean;
             startCursor: string | null;
@@ -71,6 +77,10 @@ export interface RawPr extends RawPrMergeFields {
     };
     allReviews?: {
         totalCount: number;
+        nodes?: Array<{
+            id: string;
+            updatedAt?: string;
+        }>;
     };
     approvedReviews: {
         pageInfo: {
@@ -87,6 +97,7 @@ export interface RawPr extends RawPrMergeFields {
                 committedDate?: string;
                 checkSuites?: RawCheckSuites;
                 statusCheckRollup: {
+                    state?: string | null;
                     contexts: {
                         pageInfo: {
                             hasNextPage: boolean;
@@ -104,6 +115,7 @@ interface RawCheckSuites {
         hasNextPage: boolean;
     };
     nodes: Array<{
+        id?: string;
         conclusion: string | null;
         workflowRun: {
             databaseId: number | null;
@@ -134,6 +146,7 @@ export interface RawThreadComment {
     line: number | null;
     startLine: number | null;
     createdAt?: string;
+    updatedAt?: string;
 }
 export interface RawThread {
     id: string;
@@ -173,6 +186,7 @@ export interface RawComment {
     author: RawAuthor | null;
     body: string;
     createdAt?: string;
+    updatedAt?: string;
 }
 export interface RawReview {
     id: string;

package/bin/github/batch.d.mts

@@ -1,7 +1,9 @@
 import { type RateLimitInfo, type RepoInfo } from "./client.mts";
 import type { BatchPrData } from "../types.mts";
+import { type PrFingerprint } from "./fingerprint.mts";
 interface BatchResult {
     data: BatchPrData;
+    fingerprint?: PrFingerprint;
     rateLimit?: RateLimitInfo;
     /** True when GraphQL returned a complete CheckSuite page; skip REST startup-failure fetch. */
     checkSuitesComplete?: boolean;

package/bin/github/batch.mjs

@@ -7,6 +7,7 @@ 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";
 /**
  * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
  */
@@ -24,6 +25,7 @@ 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),
         rateLimit: paged.rateLimit ?? result.rateLimit,
         ...(parseCheckSuitesComplete(raw) && { checkSuitesComplete: true }),
     };