pr-shepherd 0.53.1 → 0.54.1

package/bin/commands/iterate/stack-trunk-conflict.d.mts

@@ -0,0 +1,13 @@
+/** An upper layer already contains its parent, so the dirty state is against trunk. */
+export interface UpperLayerTrunkConflict {
+    trunk: string;
+    /** Open layer whose PR base is the trunk. Omitted when that layer is not on this page. */
+    bottomPr?: number;
+}
+export declare function lookupUpperLayerTrunkConflict(input: {
+    owner: string;
+    name: string;
+    pr: number;
+    headRef: string;
+    trunk: string;
+}): Promise<UpperLayerTrunkConflict | undefined>;

package/bin/commands/iterate/stack-trunk-conflict.mjs

@@ -0,0 +1,51 @@
+import { graphql } from "../../github/client.mjs";
+import { UPPER_LAYER_CONFLICT_TARGET_QUERY } from "../../github/queries.mjs";
+import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
+/** Lowest-position open layer whose base is the stack trunk, if this page contains one. */
+function selectBottomOpenLayer(nodes, trunk) {
+    const onTrunk = nodes.flatMap((node) => {
+        const pull = node?.pullRequest;
+        if (!node || !pull || pull.state !== "OPEN" || pull.baseRefName !== trunk)
+            return [];
+        return [{ position: node.position, number: pull.number }];
+    });
+    onTrunk.sort((a, b) => a.position - b.position);
+    return onTrunk[0]?.number;
+}
+export async function lookupUpperLayerTrunkConflict(input) {
+    let data;
+    try {
+        ({ data } = await graphql(UPPER_LAYER_CONFLICT_TARGET_QUERY, {
+            owner: input.owner,
+            name: input.name,
+            number: input.pr,
+            headRef: input.headRef,
+        }));
+    }
+    catch (err) {
+        if (pollRateLimitRetryAfterMs(err) !== null)
+            throw err;
+        ignore(input.pr, err instanceof Error ? err.message : String(err));
+        return undefined;
+    }
+    const pull = data.repository?.pullRequest;
+    const behindBy = pull?.baseRef?.compare?.behindBy;
+    if (!pull || behindBy == null) {
+        ignore(input.pr, pull ? "base comparison unavailable" : "pull request not found");
+        return undefined;
+    }
+    // behindBy > 0: the layer is still behind its parent. Keep the parent rebase.
+    if (behindBy !== 0)
+        return undefined;
+    const entries = pull.stack?.entries;
+    const bottomPr = entries ? selectBottomOpenLayer(entries.nodes, input.trunk) : undefined;
+    if (bottomPr === undefined) {
+        ignore(input.pr, entries?.pageInfo.hasNextPage
+            ? "stack entry page truncated before the trunk layer"
+            : "bottom open layer not found");
+    }
+    return { trunk: input.trunk, ...(bottomPr !== undefined && { bottomPr }) };
+}
+function ignore(pr, message) {
+    process.stderr.write(`pr-shepherd: upper-layer conflict target unavailable for PR #${pr} (ignored): ${message}\n`);
+}

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

@@ -19,4 +19,6 @@ export interface RateLimitRetry {
 export declare function pollRateLimitRetryAfterMs(err: unknown): RateLimitRetry | null;
 /** Stderr line naming the exhausted budget and when the sleep ends. */
 export declare function formatRateLimitRetryLine(tickLabel: string, elapsedSeconds: number, retry: RateLimitRetry): string;
+/** One stderr line before `--until-terminal` gives up and exits 75. */
+export declare function formatRateLimitGiveUpLine(tickLabel: string, elapsedSeconds: number, retry: RateLimitRetry): string;
 export declare function aggregateQuotaWarning(result: PollSummaryResult, bands: GraphqlQuotaWarningBand[], intervalSeconds: number): Promise<PollSummaryResult["quotaWarning"]>;

package/bin/commands/poll-quota.mjs

@@ -1,6 +1,7 @@
 import { summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { GitHubRequestError } from "../github/errors.mjs";
 import { isRateLimitMessage } from "../comments/rate-limit.mjs";
+import { exhaustedPrimaryLimitDelayMs } from "./poll-rate-limit-delay.mjs";
 import { selectQuotaWarning } from "./quota-selection.mjs";
 const GRAPHQL_RETRY_AFTER_DEFAULT_MS = 60_000;
 /** Sleep at least `--interval`, and at least the active crossed quota band. */
@@ -45,7 +46,7 @@ export function pollRateLimitRetryAfterMs(err) {
         return { ...details, ms: Math.max(err.retryAfterSeconds, 0) * 1000 };
     }
     if (exhausted && rateLimit !== undefined) {
-        return { ...details, ms: Math.max(rateLimit.resetAt * 1000 - Date.now(), 0) };
+        return { ...details, ms: exhaustedPrimaryLimitDelayMs(rateLimit.resetAt, Date.now()) };
     }
     return { ...details, ms: GRAPHQL_RETRY_AFTER_DEFAULT_MS };
 }
@@ -58,19 +59,31 @@ function retryResource(err) {
         (err.graphqlErrors?.some((error) => /secondary/i.test(error.message)) ?? false);
     return secondary ? "secondary" : "graphql";
 }
-/** Stderr line naming the exhausted budget and when the sleep ends. */
-export function formatRateLimitRetryLine(tickLabel, elapsedSeconds, retry) {
-    const resetAt = retry.resetAt ?? Math.ceil((Date.now() + retry.ms) / 1000);
-    const clock = `${new Date(resetAt * 1000).toISOString().slice(11, 19)}Z`;
-    const label = retry.resource === "graphql"
-        ? "GitHub GraphQL rate limit"
-        : retry.resource === "secondary"
-            ? "GitHub secondary rate limit"
-            : `GitHub REST ${retry.resource} rate limit`;
-    const counts = retry.remaining !== undefined && retry.limit !== undefined
+function rateLimitResourceLabel(resource) {
+    if (resource === "graphql")
+        return "GitHub GraphQL rate limit";
+    if (resource === "secondary")
+        return "GitHub secondary rate limit";
+    return `GitHub REST ${resource} rate limit`;
+}
+function rateLimitCounts(retry) {
+    return retry.remaining !== undefined && retry.limit !== undefined
         ? ` (${retry.remaining}/${retry.limit})`
         : "";
-    return `[${tickLabel} / +${elapsedSeconds}s] ${label}${counts} — retrying at ${clock} (in ${Math.round(retry.ms / 1000)}s)\n`;
+}
+function rateLimitClock(retry) {
+    const resetAt = retry.resetAt ?? Math.ceil((Date.now() + retry.ms) / 1000);
+    return `${new Date(resetAt * 1000).toISOString().slice(11, 19)}Z`;
+}
+/** Stderr line naming the exhausted budget and when the sleep ends. */
+export function formatRateLimitRetryLine(tickLabel, elapsedSeconds, retry) {
+    const clock = rateLimitClock(retry);
+    return `[${tickLabel} / +${elapsedSeconds}s] ${rateLimitResourceLabel(retry.resource)}${rateLimitCounts(retry)} — retrying at ${clock} (in ${Math.round(retry.ms / 1000)}s)\n`;
+}
+/** One stderr line before `--until-terminal` gives up and exits 75. */
+export function formatRateLimitGiveUpLine(tickLabel, elapsedSeconds, retry) {
+    const clock = rateLimitClock(retry);
+    return `[${tickLabel} / +${elapsedSeconds}s] ${rateLimitResourceLabel(retry.resource)}${rateLimitCounts(retry)} still exhausted at ${clock} after 5 attempts with no progress\n`;
 }
 export async function aggregateQuotaWarning(result, bands, intervalSeconds) {
     const usage = summarizeApiTelemetry();

package/bin/commands/poll-rate-limit-cancel.d.mts

@@ -0,0 +1,35 @@
+import type { IterateResult, MergeStateStatus, MergeableState, PollSummaryResult } from "../types.mts";
+export interface RateLimitPullTarget {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export interface RateLimitProbePull {
+    pr: number;
+    state: "MERGED" | "CLOSED";
+    title: string;
+    url: string;
+    draft: boolean;
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+    baseRefName: string;
+    headRefName: string;
+    headRefOid: string;
+}
+export declare function onePrRateLimitTargets(explicit: {
+    owner: string;
+    name: string;
+} | undefined, pr: number | undefined, repoSlug: string | undefined): RateLimitPullTarget[];
+/** Same fields as the merged/closed iterate cancel path, filled from the REST pull. */
+export declare function onePrCancelFromPulls(explicit: {
+    owner: string;
+    name: string;
+} | undefined, repoSlug: string | undefined, pulls: RateLimitProbePull[]): IterateResult | undefined;
+export declare function aggregateRateLimitTargets(last: PollSummaryResult | undefined, repo: {
+    owner: string;
+    name: string;
+} | undefined, prNumbers: number[] | undefined): RateLimitPullTarget[];
+export declare function aggregateCancelFromPulls(last: PollSummaryResult | undefined, repo: {
+    owner: string;
+    name: string;
+} | undefined, pulls: RateLimitProbePull[]): PollSummaryResult | undefined;

package/bin/commands/poll-rate-limit-cancel.mjs

@@ -0,0 +1,101 @@
+export function onePrRateLimitTargets(explicit, pr, repoSlug) {
+    if (pr === undefined)
+        return [];
+    const [slugOwner, slugName] = repoSlug?.split("/") ?? [];
+    const owner = explicit?.owner ?? slugOwner;
+    const repo = explicit?.name ?? slugName;
+    if (!owner || !repo)
+        return [];
+    return [{ owner, repo, pr }];
+}
+/** Same fields as the merged/closed iterate cancel path, filled from the REST pull. */
+export function onePrCancelFromPulls(explicit, repoSlug, pulls) {
+    const pull = pulls[0];
+    const slug = explicit ? `${explicit.owner}/${explicit.name}` : repoSlug;
+    if (!pull || !slug)
+        return undefined;
+    const state = pull.state;
+    return {
+        pr: pull.pr,
+        repo: slug,
+        status: state,
+        state,
+        mergeStateStatus: pull.mergeStateStatus,
+        mergeStatus: "UNKNOWN",
+        reviewDecision: null,
+        blockingBotReviewInProgress: false,
+        isDraft: pull.draft,
+        shouldCancel: true,
+        remainingSeconds: 0,
+        summary: { passing: 0, skipped: 0, filtered: 0, inProgress: 0, superseded: 0 },
+        baseBranch: pull.baseRefName,
+        branchProtection: null,
+        checks: [],
+        inProgressChecks: [],
+        action: "cancel",
+        reason: state === "MERGED" ? "merged" : "closed",
+        log: `CANCEL: PR #${pull.pr} is ${state.toLowerCase()} — stopping`,
+    };
+}
+export function aggregateRateLimitTargets(last, repo, prNumbers) {
+    if (last) {
+        return last.prs.flatMap((item) => {
+            if (item.state !== "OPEN")
+                return [];
+            const [owner, name] = item.repo.split("/");
+            if (!owner || !name)
+                return [];
+            return [{ owner, repo: name, pr: item.pr }];
+        });
+    }
+    if (!repo || !prNumbers?.length)
+        return [];
+    return prNumbers.map((pr) => ({ owner: repo.owner, repo: repo.name, pr }));
+}
+export function aggregateCancelFromPulls(last, repo, pulls) {
+    if (last) {
+        const byPr = new Map(pulls.map((pull) => [pull.pr, pull]));
+        const prs = last.prs.map((item) => applyProbe(item, byPr.get(item.pr)));
+        if (prs.some((item) => item.state !== "MERGED" && item.state !== "CLOSED"))
+            return undefined;
+        return { ...last, prs, reason: "all_terminal" };
+    }
+    if (!repo)
+        return undefined;
+    const slug = `${repo.owner}/${repo.name}`;
+    const prs = pulls.map((pull) => syntheticItem(slug, pull));
+    return {
+        mode: "summary",
+        repo: slug,
+        selection: { kind: "prs", requested: pulls.map((pull) => pull.pr) },
+        reason: "all_terminal",
+        prs,
+    };
+}
+function applyProbe(item, pull) {
+    if (!pull)
+        return item;
+    return {
+        ...item,
+        action: "cancel",
+        state: pull.state,
+        reasons: [pull.state === "MERGED" ? "merged" : "closed"],
+    };
+}
+function syntheticItem(repo, pull) {
+    return {
+        pr: pull.pr,
+        repo,
+        title: pull.title || `PR ${pull.pr}`,
+        url: pull.url || `https://github.com/${repo}/pull/${pull.pr}`,
+        action: "cancel",
+        reasons: [pull.state === "MERGED" ? "merged" : "closed"],
+        state: pull.state,
+        mergeable: pull.mergeable,
+        mergeStateStatus: pull.mergeStateStatus,
+        headRefName: pull.headRefName,
+        headRefOid: pull.headRefOid,
+        baseRefName: pull.baseRefName,
+        ...(pull.draft ? { isDraft: true } : {}),
+    };
+}

package/bin/commands/poll-rate-limit-delay.d.mts

@@ -0,0 +1 @@
+export declare function exhaustedPrimaryLimitDelayMs(resetAtSeconds: number, nowMs: number): number;

package/bin/commands/poll-rate-limit-delay.mjs

@@ -0,0 +1,7 @@
+/** Exhausted primary limit: time until resetAt, plus 5s, plus `resetAt % 5` seconds. */
+const EXHAUSTED_LIMIT_MARGIN_MS = 5_000;
+export function exhaustedPrimaryLimitDelayMs(resetAtSeconds, nowMs) {
+    return (Math.max(resetAtSeconds * 1000 - nowMs, 0) +
+        EXHAUSTED_LIMIT_MARGIN_MS +
+        (resetAtSeconds % 5) * 1000);
+}

package/bin/commands/poll-rate-limit-wait.d.mts

@@ -0,0 +1,14 @@
+import type { RateLimitProbePull, RateLimitPullTarget } from "./poll-rate-limit-cancel.mts";
+interface WaitOptions<T> {
+    untilTerminal: boolean;
+    intervalMs: number;
+    tickLabel: string;
+    startedAt: number;
+    targets: RateLimitPullTarget[];
+    onAllTerminal?: (pulls: RateLimitProbePull[]) => T | undefined;
+}
+export declare function createUntilTerminalRateLimitRetry(): {
+    reset(): void;
+    wait<T>(err: unknown, opts: WaitOptions<T>): Promise<T | undefined>;
+};
+export {};

package/bin/commands/poll-rate-limit-wait.mjs

@@ -0,0 +1,125 @@
+import { rest } from "../github/rest-http.mjs";
+import { sleep } from "../util/sleep.mjs";
+import { formatRateLimitGiveUpLine, formatRateLimitRetryLine, pollRateLimitRetryAfterMs, } from "./poll-quota.mjs";
+const MAX_NO_PROGRESS_ATTEMPTS = 5;
+const NO_PROGRESS_BACKOFF_MS = [15_000, 30_000, 60_000];
+const MERGE_STATES = new Set([
+    "BEHIND",
+    "BLOCKED",
+    "CLEAN",
+    "DIRTY",
+    "DRAFT",
+    "HAS_HOOKS",
+    "UNKNOWN",
+    "UNSTABLE",
+]);
+export function createUntilTerminalRateLimitRetry() {
+    const state = { armed: false, noProgress: 0 };
+    return {
+        reset() {
+            state.armed = false;
+            state.noProgress = 0;
+            state.lastResetAt = undefined;
+        },
+        wait(err, opts) {
+            return waitForRateLimit(state, err, opts);
+        },
+    };
+}
+function backoffMs(attempt) {
+    return NO_PROGRESS_BACKOFF_MS[Math.min(attempt, NO_PROGRESS_BACKOFF_MS.length) - 1] ?? 60_000;
+}
+async function waitForRateLimit(state, err, opts) {
+    const retry = opts.untilTerminal ? pollRateLimitRetryAfterMs(err) : null;
+    if (!retry)
+        throw err;
+    const elapsed = Math.round((Date.now() - opts.startedAt) / 1000);
+    const progressed = state.armed &&
+        retry.resetAt !== undefined &&
+        (state.lastResetAt === undefined || retry.resetAt > state.lastResetAt);
+    let sleepMs = retry.ms;
+    if (!state.armed || progressed) {
+        state.armed = true;
+        state.noProgress = 0;
+        if (retry.resetAt !== undefined)
+            state.lastResetAt = retry.resetAt;
+    }
+    else {
+        state.noProgress += 1;
+        if (state.noProgress >= MAX_NO_PROGRESS_ATTEMPTS) {
+            process.stderr.write(formatRateLimitGiveUpLine(opts.tickLabel, elapsed, retry));
+            throw err;
+        }
+        // Never sleep less than GitHub asked for. A short no-progress backoff must
+        // not undercut an explicit Retry-After or the secondary-limit default.
+        sleepMs = Math.max(retry.ms, backoffMs(state.noProgress));
+    }
+    process.stderr.write(formatRateLimitRetryLine(opts.tickLabel, elapsed, { ...retry, ms: sleepMs }));
+    return sleepRateLimit(sleepMs, opts, retry.resource);
+}
+async function sleepRateLimit(ms, opts, resource) {
+    const canProbe = resource !== "core" && opts.targets.length > 0;
+    if (ms <= opts.intervalMs || opts.intervalMs <= 0) {
+        await sleep(ms);
+        return undefined;
+    }
+    let remaining = ms;
+    let probesDisabled = !canProbe;
+    while (remaining > 0) {
+        const chunk = Math.min(opts.intervalMs, remaining);
+        await sleep(chunk);
+        remaining -= chunk;
+        if (remaining <= 0 || probesDisabled)
+            continue;
+        try {
+            const found = await probeOpenPulls(opts.targets, opts.onAllTerminal);
+            if (found !== undefined)
+                return found;
+        }
+        catch {
+            // The probe only notices a merge or close early. A 5xx, a 404, or a
+            // secondary limit must not abort the rate-limit sleep.
+            probesDisabled = true;
+        }
+    }
+    return undefined;
+}
+async function probeOpenPulls(targets, onAllTerminal) {
+    const pulls = [];
+    for (const target of targets) {
+        // GraphQL is exhausted for this sleep. REST core is a separate budget, so
+        // GET /repos/{owner}/{repo}/pulls/{n} can still see a merge or close.
+        const data = await rest("GET", `/repos/${target.owner}/${target.repo}/pulls/${target.pr}`);
+        const state = terminalState(data);
+        if (!state)
+            return undefined;
+        pulls.push(toProbePull(target.pr, state, data));
+    }
+    return onAllTerminal?.(pulls);
+}
+function terminalState(pull) {
+    if (!pull)
+        return undefined;
+    if (pull.merged === true || pull.merged_at != null)
+        return "MERGED";
+    if (pull.state?.toLowerCase() === "closed")
+        return "CLOSED";
+    return undefined;
+}
+function toProbePull(pr, state, pull) {
+    const mergeState = pull.mergeable_state?.toUpperCase();
+    return {
+        pr,
+        state,
+        title: pull.title ?? "",
+        url: pull.html_url ?? "",
+        draft: pull.draft === true,
+        mergeable: pull.mergeable === true ? "MERGEABLE" : pull.mergeable === false ? "CONFLICTING" : "UNKNOWN",
+        mergeStateStatus: MERGE_STATES.has(mergeState ?? "")
+            ? mergeState
+            : "UNKNOWN",
+        baseRefName: pull.base?.ref ?? "",
+        headRefName: pull.head?.ref ?? "",
+        headRefOid: pull.head?.sha ?? "",
+    };
+}

package/bin/commands/poll-summary.mjs

@@ -5,7 +5,9 @@ import { getRepoInfo } from "../github/client.mjs";
 import { withApiTelemetryScope, summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { fetchPollSummary } from "../github/poll-summary.mjs";
 import { sleep } from "../util/sleep.mjs";
-import { aggregateQuotaWarning, formatRateLimitRetryLine, pollRateLimitRetryAfterMs, quotaPollIntervalMs, } from "./poll-quota.mjs";
+import { aggregateQuotaWarning, quotaPollIntervalMs } from "./poll-quota.mjs";
+import { aggregateCancelFromPulls, aggregateRateLimitTargets } from "./poll-rate-limit-cancel.mjs";
+import { createUntilTerminalRateLimitRetry } from "./poll-rate-limit-wait.mjs";
 import { planPollSummary, withPollSummaryInstructions } from "./poll-summary-instructions.mjs";
 import { summaryStatusSignature } from "./poll-summary-signature.mjs";
 import { applyStackStallGuard } from "./stack-stall.mjs";
@@ -42,13 +44,13 @@ async function runAggregatePollCore(opts) {
     let debounceUntil = null;
     let last;
     let lastStatusSignature = null;
-    let rateLimitRetries = 0;
+    const rateLimitRetry = createUntilTerminalRateLimitRetry();
     let pendingQuotaWarning;
     while (true) {
         tick += 1;
         try {
             last = await runPollSummaryCore(opts);
-            rateLimitRetries = 0;
+            rateLimitRetry.reset();
         }
         catch (error) {
             if (last?.selection.kind === "stack" && isMissingStack(error)) {
@@ -83,12 +85,17 @@ async function runAggregatePollCore(opts) {
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
                 }, opts.merge);
             }
-            const retry = opts.untilTerminal ? pollRateLimitRetryAfterMs(error) : null;
-            if (retry === null || rateLimitRetries >= 1)
-                throw error;
-            rateLimitRetries += 1;
-            process.stderr.write(formatRateLimitRetryLine(`aggregate poll tick ${tick}`, Math.round((Date.now() - start) / 1000), retry));
-            await sleep(retry.ms);
+            const early = await rateLimitRetry.wait(error, {
+                untilTerminal: opts.untilTerminal === true,
+                intervalMs,
+                tickLabel: `aggregate poll tick ${tick}`,
+                startedAt: start,
+                targets: aggregateRateLimitTargets(last, opts.targetRepository, opts.prNumbers),
+                onAllTerminal: (pulls) => aggregateCancelFromPulls(last, opts.targetRepository, pulls),
+            });
+            if (early) {
+                return presentProbedCancel(pendingQuotaWarning ? { ...early, quotaWarning: pendingQuotaWarning } : early, opts.merge);
+            }
             continue;
         }
         const allTerminal = last.selection.kind === "stack"
@@ -159,6 +166,11 @@ async function runAggregatePollCore(opts) {
         await sleep(sleepMs);
     }
 }
+function presentProbedCancel(result, merge) {
+    // The stack planner already cancels an all-merged stack and escalates a
+    // closed-unmerged layer. Do not rewrite that into a successful stop.
+    return attachUsage({ ...result, reason: "all_terminal" }, merge);
+}
 function isMissingStack(error) {
     return (error instanceof ShepherdError && error.message.includes("not part of a native GitHub stack"));
 }

package/bin/commands/poll.mjs

@@ -2,7 +2,9 @@ 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 { formatRateLimitRetryLine, pollRateLimitRetryAfterMs, quotaPollIntervalMs, } from "./poll-quota.mjs";
+import { quotaPollIntervalMs } from "./poll-quota.mjs";
+import { onePrCancelFromPulls, onePrRateLimitTargets } from "./poll-rate-limit-cancel.mjs";
+import { createUntilTerminalRateLimitRetry } from "./poll-rate-limit-wait.mjs";
 import { writeDebounceProgress, writeWaitProgress } from "./poll-progress.mjs";
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 const MAX_TIMER_MS = 2 ** 31 - 1;
@@ -29,7 +31,7 @@ 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;
+    const rateLimitRetry = createUntilTerminalRateLimitRetry();
     while (true) {
         tick += 1;
         const pastDebounce = debounceUntil !== null && Date.now() >= debounceUntil;
@@ -48,21 +50,24 @@ async function runPollCore(opts) {
             quotaWarningMinimumPollIntervalMinutes: intervalSeconds / 60,
         });
         const runTick = async (fingerprintCache) => {
-            try {
-                const result = await iterateTick(fingerprintCache);
-                rateLimitRetries = 0;
-                return result;
-            }
-            catch (err) {
-                const retry = untilTerminal ? pollRateLimitRetryAfterMs(err) : null;
-                if (retry === null || rateLimitRetries >= 1)
-                    throw err;
-                rateLimitRetries += 1;
-                process.stderr.write(formatRateLimitRetryLine(`poll tick ${tick}`, Math.round((Date.now() - start) / 1000), retry));
-                await sleep(retry.ms);
-                const result = await iterateTick(fingerprintCache);
-                rateLimitRetries = 0;
-                return result;
+            while (true) {
+                try {
+                    const result = await iterateTick(fingerprintCache);
+                    rateLimitRetry.reset();
+                    return result;
+                }
+                catch (err) {
+                    const early = await rateLimitRetry.wait(err, {
+                        untilTerminal,
+                        intervalMs,
+                        tickLabel: `poll tick ${tick}`,
+                        startedAt: start,
+                        targets: onePrRateLimitTargets(iterateOpts.targetRepository, prNumber, lastResult?.repo),
+                        onAllTerminal: (pulls) => onePrCancelFromPulls(iterateOpts.targetRepository, lastResult?.repo, pulls),
+                    });
+                    if (early)
+                        return early;
+                }
             }
         };
         lastResult = await runTick(allowCache);

package/bin/config/load.d.mts

@@ -8,6 +8,8 @@ export interface GraphqlQuotaWarningBand {
 }
 interface PollConfig {
     intervalSeconds: number;
+    /** Multiplier for aggregate polls when `--interval` is omitted. Finite and at least 1. */
+    stackIntervalFactor: number;
     timeoutSeconds: number;
     debounceSeconds: number;
     quietStatus: boolean;

package/bin/config/load.mjs

@@ -153,11 +153,27 @@ function parsePollConfig(value) {
     const intervalSeconds = parsePollDuration(record["intervalSeconds"], "intervalSeconds");
     const timeoutSeconds = parsePollDuration(record["timeoutSeconds"], "timeoutSeconds");
     const debounceSeconds = parsePollDuration(record["debounceSeconds"], "debounceSeconds", true);
+    const stackIntervalFactor = parseStackIntervalFactor(record["stackIntervalFactor"]);
+    assertAggregateIntervalFits(intervalSeconds, stackIntervalFactor);
     const quietStatus = record["quietStatus"];
     if (typeof quietStatus !== "boolean") {
         throw new Error(`Invalid config: poll.quietStatus must be a boolean, got ${JSON.stringify(quietStatus)}`);
     }
-    return { intervalSeconds, timeoutSeconds, debounceSeconds, quietStatus };
+    return { intervalSeconds, stackIntervalFactor, timeoutSeconds, debounceSeconds, quietStatus };
+}
+function parseStackIntervalFactor(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+        throw new Error(`Invalid config: poll.stackIntervalFactor must be a finite number greater than or equal to 1, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/** Largest `setTimeout` delay. A bigger aggregate sleep would clamp to ~24.8 days. */
+const MAX_POLL_INTERVAL_MS = 2 ** 31 - 1;
+function assertAggregateIntervalFits(intervalSeconds, factor) {
+    const ms = intervalSeconds * factor * 1000;
+    if (!Number.isFinite(ms) || ms > MAX_POLL_INTERVAL_MS) {
+        throw new Error(`Invalid config: poll.intervalSeconds * poll.stackIntervalFactor must be finite and at most ${MAX_POLL_INTERVAL_MS} milliseconds, got ${JSON.stringify(ms)}`);
+    }
 }
 function parsePollDuration(value, key, allowZero = false) {
     if (typeof value !== "number" ||
@@ -252,7 +268,13 @@ const KNOWN_NESTED_KEYS = {
         "behindBaseHint",
         "resolveOtherHumanThreads",
     ]),
-    poll: new Set(["intervalSeconds", "timeoutSeconds", "debounceSeconds", "quietStatus"]),
+    poll: new Set([
+        "intervalSeconds",
+        "stackIntervalFactor",
+        "timeoutSeconds",
+        "debounceSeconds",
+        "quietStatus",
+    ]),
     watch: new Set(["readyDelayMinutes", "graphqlQuotaWarnings"]),
     resolve: new Set(["shaPoll"]),
     checks: new Set(["ciTriggerEvents", "ignoreLogLines"]),

package/bin/config.json

@@ -25,6 +25,7 @@
   },
   "poll": {
     "intervalSeconds": 60,
+    "stackIntervalFactor": 2,
     "timeoutSeconds": 270,
     "debounceSeconds": 60,
     "quietStatus": false

package/bin/github/batch-parse-suites.d.mts

@@ -1,4 +1,6 @@
 import type { CheckRun } from "../types.mts";
 import type { RawPr } from "./batch-raw-types.mts";
 export declare function parseCheckSuitesComplete(raw: RawPr): boolean;
+/** True only when the head commit's suite page finished and listed nothing. */
+export declare function parseHeadCheckSuitesEmpty(raw: RawPr): boolean;
 export declare function parseSuiteStartupFailures(raw: RawPr): CheckRun[];

package/bin/github/batch-parse-suites.mjs

@@ -1,6 +1,11 @@
 export function parseCheckSuitesComplete(raw) {
     return raw.commits.nodes[0]?.commit.checkSuites?.pageInfo.hasNextPage === false;
 }
+/** True only when the head commit's suite page finished and listed nothing. */
+export function parseHeadCheckSuitesEmpty(raw) {
+    const suites = raw.commits.nodes[0]?.commit.checkSuites;
+    return suites?.pageInfo.hasNextPage === false && suites.nodes.length === 0;
+}
 export function parseSuiteStartupFailures(raw) {
     const suites = raw.commits.nodes[0]?.commit.checkSuites;
     if (!suites)

package/bin/github/batch.d.mts

@@ -7,6 +7,8 @@ interface BatchResult {
     rateLimit?: RateLimitInfo;
     /** True when GraphQL returned a complete CheckSuite page; skip REST startup-failure fetch. */
     checkSuitesComplete?: boolean;
+    /** True when that complete page listed no check suites on the head commit. */
+    headCheckSuitesEmpty?: true;
 }
 interface FetchPrBatchOptions {
     /**

package/bin/github/batch.mjs

@@ -2,7 +2,7 @@ import { graphqlWithRateLimit } from "./client.mjs";
 import { hydrateThreadCommentPages } from "./thread-comments.mjs";
 import { BATCH_PR_QUERY } from "./queries.mjs";
 import { parseRawPr } from "./batch-parsers.mjs";
-import { parseCheckSuitesComplete, parseSuiteStartupFailures } from "./batch-parse-suites.mjs";
+import { parseCheckSuitesComplete, parseHeadCheckSuitesEmpty, parseSuiteStartupFailures, } from "./batch-parse-suites.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
 import { paginateBatchConnections } from "./batch-page.mjs";
 import { requireRawPr } from "./batch-response.mjs";
@@ -28,5 +28,6 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
         fingerprint: fingerprintFromRaw(raw, result.data.repository?.viewerPermission ?? null, result.data.viewer?.login ?? null),
         rateLimit: paged.rateLimit ?? result.rateLimit,
         ...(parseCheckSuitesComplete(raw) && { checkSuitesComplete: true }),
+        ...(parseHeadCheckSuitesEmpty(raw) && { headCheckSuitesEmpty: true }),
     };
 }