pr-shepherd 0.53.1 → 0.54.0

package/bin/commands/check-blocker-ref.mjs

@@ -0,0 +1,50 @@
+const NAME = /^[A-Za-z0-9_.-]+$/;
+const SHORTHAND = /^(?:(issue):)?([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)#([1-9]\d*)$/;
+/** Parse `--blocked-by`. Returns null for anything other than the four accepted forms. */
+export function parseBlockedByRef(raw) {
+    const text = raw.trim();
+    const short = SHORTHAND.exec(text);
+    if (short?.[2] && short[3] && short[4]) {
+        const number = Number(short[4]);
+        if (!Number.isSafeInteger(number))
+            return null;
+        return {
+            owner: short[2],
+            name: short[3],
+            number,
+            kind: short[1] === "issue" ? "issue" : "pull",
+        };
+    }
+    return parseUrl(text);
+}
+function parseUrl(text) {
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return null;
+    if (url.hostname !== "github.com" && url.hostname !== "www.github.com")
+        return null;
+    if (url.search !== "" || url.hash !== "")
+        return null;
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (parts.length !== 4)
+        return null;
+    const [owner, name, type, num] = parts;
+    if (!owner || !name || !num || !NAME.test(owner) || !NAME.test(name))
+        return null;
+    if (!/^[1-9]\d*$/.test(num))
+        return null;
+    const number = Number(num);
+    if (!Number.isSafeInteger(number))
+        return null;
+    if (type === "pull")
+        return { owner, name, number, kind: "pull" };
+    if (type === "issues")
+        return { owner, name, number, kind: "issue" };
+    return null;
+}

package/bin/commands/iterate/check-blocker-gate.d.mts

@@ -0,0 +1,18 @@
+import type { IterateResult } from "../../types.mts";
+export interface CheckBlockerGate {
+    deferredNames: ReadonlySet<string>;
+    releasedNames: ReadonlySet<string>;
+    /** `owner/name#number` for blockers that are still open. */
+    openBlockers: readonly string[];
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export declare function resolveCheckBlockerGate(key: StateKey, failing: readonly {
+    name: string;
+}[], mergeStatus?: string): Promise<CheckBlockerGate | null>;
+/** Append the open blocker to a WAIT log. Other actions are unchanged. */
+export declare function annotateBlockedWait(result: IterateResult, gate: CheckBlockerGate | null): IterateResult;
+export {};

package/bin/commands/iterate/check-blocker-gate.mjs

@@ -0,0 +1,115 @@
+import { graphql } from "../../github/client.mjs";
+import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
+import { clearCheckBlocker, formatCheckBlockerRef, readCheckBlockers, } from "../../state/check-blockers.mjs";
+const RATE_LIMIT = "cost limit nodeCount remaining resetAt used";
+const PULL_QUERY = `query CheckBlockerPull($owner: String!, $name: String!, $number: Int!) {
+  _shepherdRateLimit: rateLimit { ${RATE_LIMIT} }
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) { state merged }
+  }
+}`;
+const ISSUE_QUERY = `query CheckBlockerIssue($owner: String!, $name: String!, $number: Int!) {
+  _shepherdRateLimit: rateLimit { ${RATE_LIMIT} }
+  repository(owner: $owner, name: $name) {
+    issue(number: $number) { state }
+  }
+}`;
+/**
+ * Match failing checks to stored blockers. No records, or none of them name a
+ * failing check, skips GitHub. Rate-limit errors propagate; other lookup
+ * failures leave that check as a normal failure.
+ */
+/** Behind or conflicting branches still need the update-branch instruction. */
+const KEEP_RELEASED_STATUS = new Set(["BEHIND", "CONFLICTS", "DIRTY", "UNKNOWN"]);
+export async function resolveCheckBlockerGate(key, failing, mergeStatus) {
+    const records = await readCheckBlockers(key);
+    if (records.length === 0 || failing.length === 0)
+        return null;
+    const failingNames = new Set(failing.map((check) => check.name));
+    const matched = records.filter((record) => failingNames.has(record.checkName));
+    if (matched.length === 0)
+        return null;
+    const lookups = new Map();
+    for (const record of matched) {
+        const id = blockerKey(record.blocker);
+        if (lookups.has(id))
+            continue;
+        lookups.set(id, await lookupBlocker(record.blocker));
+    }
+    const deferredNames = new Set();
+    const releasedNames = new Set();
+    const openBlockers = [];
+    const seen = new Set();
+    for (const record of matched) {
+        const status = lookups.get(blockerKey(record.blocker));
+        if (status === "deferred") {
+            deferredNames.add(record.checkName);
+            const label = formatCheckBlockerRef(record.blocker);
+            if (!seen.has(label)) {
+                seen.add(label);
+                openBlockers.push(label);
+            }
+        }
+        else if (status === "released") {
+            if (mergeStatus !== undefined && !KEEP_RELEASED_STATUS.has(mergeStatus)) {
+                // The branch is already current, so update-branch would no-op and a
+                // later unrelated failure must be a normal check again.
+                await clearCheckBlocker(key, record.checkName);
+            }
+            else {
+                releasedNames.add(record.checkName);
+            }
+        }
+    }
+    if (deferredNames.size === 0 && releasedNames.size === 0)
+        return null;
+    return { deferredNames, releasedNames, openBlockers };
+}
+/** Append the open blocker to a WAIT log. Other actions are unchanged. */
+export function annotateBlockedWait(result, gate) {
+    if (result.action !== "wait" || gate === null || gate.openBlockers.length === 0)
+        return result;
+    const note = `blocked by ${gate.openBlockers.join(", ")}`;
+    if (result.log.includes(note))
+        return result;
+    return { ...result, log: `${result.log} — ${note}` };
+}
+async function lookupBlocker(blocker) {
+    try {
+        const vars = { owner: blocker.owner, name: blocker.name, number: blocker.number };
+        if (blocker.kind === "issue") {
+            const { data } = await graphql(ISSUE_QUERY, vars);
+            const issue = data.repository?.issue;
+            if (!issue)
+                return ignore(blocker, "not found");
+            if (issue.state === "OPEN")
+                return "deferred";
+            if (issue.state === "CLOSED")
+                return "released";
+            return ignore(blocker, `unexpected state ${issue.state}`);
+        }
+        const { data } = await graphql(PULL_QUERY, vars);
+        const pull = data.repository?.pullRequest;
+        if (!pull)
+            return ignore(blocker, "not found");
+        if (pull.state === "OPEN" && pull.merged !== true)
+            return "deferred";
+        if (pull.state === "MERGED" || pull.state === "CLOSED" || pull.merged === true) {
+            return "released";
+        }
+        return ignore(blocker, `unexpected state ${pull.state}`);
+    }
+    catch (err) {
+        if (pollRateLimitRetryAfterMs(err) !== null)
+            throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        return ignore(blocker, message);
+    }
+}
+function ignore(blocker, message) {
+    process.stderr.write(`pr-shepherd: check blocker lookup failed for ${formatCheckBlockerRef(blocker)} (ignored): ${message}\n`);
+    return "ignored";
+}
+function blockerKey(blocker) {
+    return `${blocker.kind}:${formatCheckBlockerRef(blocker)}`;
+}

package/bin/commands/iterate/check-instructions.d.mts

@@ -33,4 +33,6 @@ export declare function buildRepeatedWorkflowBranchRecoveryInstructions(baseBran
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
 /** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
+/** Update the PR branch after an external blocker merges or closes. Never rerun that job. */
+export declare function buildReleasedBlockerInstruction(prNumber: number): string;
 export declare function buildFixCompletionInstruction(checks: AgentCheck[], hasConflicts?: boolean, hasShaGatedReviewMutations?: boolean, pushesRewrittenStack?: boolean): string;

package/bin/commands/iterate/check-instructions.mjs

@@ -80,6 +80,10 @@ export function buildFailingCheckInstructions(checks) {
     }
     return instructions;
 }
+/** Update the PR branch after an external blocker merges or closes. Never rerun that job. */
+export function buildReleasedBlockerInstruction(prNumber) {
+    return `Update this PR branch from its base with \`gh pr update-branch ${prNumber} --rebase\`. Do not rerun the job; a rerun retests the old merge ref.`;
+}
 export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false, pushesRewrittenStack = false) {
     const push = pushesRewrittenStack
         ? "push the rewritten stack with `gh stack push`"

package/bin/commands/iterate/fix-code.d.mts

@@ -19,6 +19,8 @@ interface HandleFixCodeContext {
     editedSummaries: Review[];
     surfacedApprovals: Review[];
     botUsernames: NormalizedBotUsernames;
+    /** Failing checks whose external blocker has merged or closed. */
+    releasedCheckNames?: ReadonlySet<string>;
     ruleAutoResolveThreadIds?: string[];
     /** Verified stack-repair guidance, when ancestry is stale. */
     repairInstructions?: string[];

package/bin/commands/iterate/fix-code.mjs

@@ -6,6 +6,7 @@ import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, bui
 import { buildResolveCommand } from "./classify.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./thread-mutation-routing.mjs";
 import { buildFixInstructions } from "./render.mjs";
+import { buildReleasedBlockerInstruction } from "./check-instructions.mjs";
 import { buildNativeStackLayerRebase } from "./native-stack-rebase.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
@@ -14,6 +15,7 @@ import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs
 import { canRerunWorkflows } from "../../checks/conclusions.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
+const EMPTY_RELEASED = new Set();
 function checkRequiresHumanFollowUp(check) {
     if (check.rerunCommand)
         return false;
@@ -68,7 +70,7 @@ function pendingReviewCommands(resolveCommand, resolveOnlyCommand) {
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, releasedCheckNames = EMPTY_RELEASED, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
     const failingChecks = report.checks.failing;
     const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
@@ -158,18 +160,22 @@ export async function handleFixCode(ctx) {
         ? [c.runId]
         : []));
     const initialAttemptRunIds = new Set(failingChecks.flatMap((c) => (c.runId !== null && c.runAttempt === 1 ? [c.runId] : [])));
-    const failingAgentChecks = toAgentChecks(failingChecks).map((c) => rerunAuthorized &&
-        c.runId &&
-        actionsRunIds.has(c.runId) &&
-        // GitHub increments run_attempt after every rerun. Recommend at most one rerun by limiting
-        // the command to the original attempt; missing attempt metadata is denied conservatively.
-        initialAttemptRunIds.has(c.runId) &&
-        // ACTION_REQUIRED means the run is paused pending manual workflow approval; rerunning does
-        // not grant that approval, so no rerun command applies.
-        c.conclusion !== "ACTION_REQUIRED" &&
-        !inProgressWorkflowRunIds.has(c.runId)
-        ? { ...c, rerunCommand: `gh run rerun ${c.runId} -R ${report.repo}` }
-        : c);
+    const failingAgentChecks = toAgentChecks(failingChecks).map((c) => {
+        if (releasedCheckNames.has(c.name))
+            return c;
+        return rerunAuthorized &&
+            c.runId &&
+            actionsRunIds.has(c.runId) &&
+            // GitHub increments run_attempt after every rerun. Recommend at most one rerun by limiting
+            // the command to the original attempt; missing attempt metadata is denied conservatively.
+            initialAttemptRunIds.has(c.runId) &&
+            // ACTION_REQUIRED means the run is paused pending manual workflow approval; rerunning does
+            // not grant that approval, so no rerun command applies.
+            c.conclusion !== "ACTION_REQUIRED" &&
+            !inProgressWorkflowRunIds.has(c.runId)
+            ? { ...c, rerunCommand: `gh run rerun ${c.runId} -R ${report.repo}` }
+            : c;
+    });
     const checks = [
         ...failingAgentChecks,
         ...toAgentChecks(annotatedExtra).map((c) => ({ ...c, annotationOnly: true })),
@@ -184,7 +190,9 @@ export async function handleFixCode(ctx) {
     const inProgressRunIds = [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
-    const manualFollowUpChecks = failingAgentChecks.filter((check) => !belongsToActiveWorkflowRun(check) && checkRequiresHumanFollowUp(check));
+    const manualFollowUpChecks = failingAgentChecks.filter((check) => !releasedCheckNames.has(check.name) &&
+        !belongsToActiveWorkflowRun(check) &&
+        checkRequiresHumanFollowUp(check));
     const exhaustedAttempts = failingAgentChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
     const manualExhaustedAttempts = exhaustedAttempts.filter((check) => manualFollowUpChecks.includes(check));
     const hasBehindBaseRecovery = isBehind && manualExhaustedAttempts.length > 0;
@@ -201,7 +209,9 @@ export async function handleFixCode(ctx) {
         report.threads.firstLook.length > 0 ||
         report.comments.firstLook.length > 0 ||
         checks.some((check) => (check.annotations?.length ?? 0) > 0) ||
-        failingAgentChecks.some((check) => belongsToActiveWorkflowRun(check) || !checkRequiresHumanFollowUp(check));
+        failingAgentChecks.some((check) => releasedCheckNames.has(check.name) ||
+            belongsToActiveWorkflowRun(check) ||
+            !checkRequiresHumanFollowUp(check));
     if (manualFollowUpChecks.length > 0 && !hasAutonomousWork) {
         const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
         const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
@@ -277,6 +287,12 @@ export async function handleFixCode(ctx) {
         ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, report.mergeStatus.mergeRequirements?.stack)
         : undefined;
     const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase);
+    if (failingAgentChecks.some((check) => releasedCheckNames.has(check.name))) {
+        const completion = instructions.pop();
+        instructions.push(buildReleasedBlockerInstruction(prNumber));
+        if (completion !== undefined)
+            instructions.push(completion);
+    }
     if (repairInstructions && repairInstructions.length > 0) {
         instructions.unshift(...repairInstructions);
     }

package/bin/commands/iterate/index.mjs

@@ -24,6 +24,7 @@ import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
 import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyReceipt, } from "../../state/ready-receipts.mjs";
 import { stackDraftHold } from "./parent-first.mjs";
 import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
+import { annotateBlockedWait, resolveCheckBlockerGate } from "./check-blocker-gate.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -58,6 +59,17 @@ async function runIterateCore(opts) {
         await clearStallState(stallKey);
         return buildTerminalCancelResult(report);
     }
+    const blockerGate = await resolveCheckBlockerGate({ owner: repoOwner, repo: repoName, pr: prNumber }, report.checks.failing, report.mergeStatus.status);
+    const deferredNames = blockerGate?.deferredNames;
+    const reportForWork = deferredNames === undefined || deferredNames.size === 0
+        ? report
+        : {
+            ...report,
+            checks: {
+                ...report.checks,
+                failing: report.checks.failing.filter((check) => !deferredNames.has(check.name)),
+            },
+        };
     const { minimizeIds, selfMinimizeIds, firstLookSummaries, editedSummaries, surfacedApprovals } = classifyReviewSummaries({
         firstLook: report.firstLookSummaries,
         seen: report.reviewSummaries,
@@ -86,7 +98,7 @@ async function runIterateCore(opts) {
         report.comments.actionable.length > 0 ||
         (report.comments.minimizeIds?.length ?? 0) > 0 ||
         report.changesRequestedReviews.length > 0 ||
-        hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status) ||
+        hasCheckDrivenActionableWork(reportForWork.checks, report.mergeStatus.status) ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
         editedSummaries.length > 0 ||
@@ -109,20 +121,20 @@ async function runIterateCore(opts) {
     // current already proves the delay elapsed for this exact head, base, and
     // readiness evidence, so a rerun (e.g. with --merge) does not wait again.
     const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName, { headSha, alreadyElapsed: receiptCurrent });
-    const base = buildIterateBase(report, readyState);
+    const base = buildIterateBase(reportForWork, readyState);
     // Checks (including merge-queue synthetic-commit checks) and hard conflicts are signals
     // GitHub itself is already acting on — the queue will eject the PR for these regardless of
     // what Shepherd does, so they always surface immediately. Only review threads/comments/
     // changes-requested reviews/review summaries — the categories that would otherwise cause a
     // Shepherd-initiated push while the PR sits safely in the queue — are eligible for deferral.
-    const checkDrivenActionableWork = hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status);
+    const checkDrivenActionableWork = hasCheckDrivenActionableWork(reportForWork.checks, report.mergeStatus.status);
     const deferWhileQueued = opts.merge === true &&
         report.mergeQueue?.inQueue === true &&
         config.actions.workWhileQueued !== true;
     if (hasActionableWork && !(deferWhileQueued && !checkDrivenActionableWork)) {
         return handleFixCode({
             base,
-            report,
+            report: reportForWork,
             opts: { ...opts, prNumber, neverCancelRuns },
             headSha,
             stallKey,
@@ -135,6 +147,7 @@ async function runIterateCore(opts) {
             editedSummaries,
             surfacedApprovals,
             botUsernames,
+            releasedCheckNames: blockerGate?.releasedNames,
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
@@ -151,11 +164,11 @@ async function runIterateCore(opts) {
         minimizeApprovals: config.iterate.minimizeApprovals,
     });
     if (mergeStateResult)
-        return mergeStateResult;
+        return annotateBlockedWait(mergeStateResult, blockerGate);
     if (staleAncestry) {
         return handleFixCode({
             base,
-            report,
+            report: reportForWork,
             opts: { ...opts, prNumber, neverCancelRuns },
             headSha,
             stallKey,
@@ -168,6 +181,7 @@ async function runIterateCore(opts) {
             editedSummaries,
             surfacedApprovals,
             botUsernames,
+            releasedCheckNames: blockerGate?.releasedNames,
             repairInstructions: staleAncestry.instructions,
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
@@ -191,7 +205,7 @@ async function runIterateCore(opts) {
                 shouldCancel: false,
                 log: `WAIT: PR #${base.pr} reached ready-delay but its stack readiness receipt could not be persisted`,
             };
-            return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, receiptWait, report, reviewSummaryIds);
+            return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, receiptWait, reportForWork, reviewSummaryIds), blockerGate);
         }
         await clearReadyDelay(report.pr, repoOwner, repoName);
         await clearStallState(stallKey);
@@ -213,7 +227,7 @@ async function runIterateCore(opts) {
         log: buildWaitLog(base),
         ...(hold && { stackDraftHold: hold }),
     };
-    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, report, reviewSummaryIds);
+    return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, reportForWork, reviewSummaryIds), blockerGate);
 }
 async function recordReadyReceipt(key, report) {
     if (report.status !== "READY" ||

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