pr-shepherd 0.52.1 → 0.53.1

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.52.1",
+  "version": "0.53.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -147,22 +147,24 @@ needed, every selected PR is complete, the bounded timeout expires, or `--until-
 configured GraphQL quota-warning band. Explicit PR sets give each actionable row an exact single-PR
 `pollCommand`, so independent rows can proceed before the next aggregate poll.
 
-Native-stack rows are ordered bottom-to-top. `--stack` never performs a mutation itself; only
-`--stack --merge` can emit a bottom-layer merge command for the agent. An unready layer (draft, missing a READY
-receipt, conflicting, failing, or stale) returns stack-level `SHEPHERD` with one-PR Shepherd instructions for
-the affected layers. A draft or other unready lower layer marks every higher open layer with
-`blockedByPr`; review and CI sessions on independent layers may proceed concurrently, but an upper
-draft cannot transition to ready until every lower layer has its READY receipt. With automatic
-mark-ready disabled, the instructions ask the agent to mark a clean, unblocked draft layer ready. A
-queued stack, or one whose remaining layers can only wait, returns `WAIT`; an idle `WAIT` that stays unchanged past the stall timeout returns `ESCALATE` with `stall-timeout`. A terminal READY or fully merged stack returns `CANCEL`. Closed or unverified
+Native-stack rows are ordered bottom-to-top. `--stack` never performs a mutation itself. Every
+layer that still has work gets its own one-PR session on the same tick, including a clean draft
+whose session marks it ready. Layers do not wait for a lower layer's READY receipt, so their
+ready-delays overlap. With automatic mark-ready disabled, the instructions ask the agent to mark
+a clean draft ready after its probe. A queued stack, or one whose remaining layers can only wait,
+returns `WAIT`; an idle `WAIT` that stays unchanged past the stall timeout returns `ESCALATE` with
+`stall-timeout`. A terminal READY or fully merged stack returns `CANCEL`. Closed or unverified
 topology returns `ESCALATE` for human direction after any other shepherdable PRs are handled;
 until then, `SHEPHERD` remains the immediate action and lists the human blockers too.
 
-With `--stack --merge`, a READY bottom open layer that GitHub has retargeted onto the stack base
-returns `MERGE` with `gh stack merge <PR number> --yes --squash`, which merges or enqueues that layer
-alone; unready upper layers keep their one-PR sessions alongside it. After each merge, GitHub
-retargets the next layer, so the rerun drains the stack layer by layer until it returns `CANCEL`. API and MCP aggregate calls perform one summary tick and leave recurrence to the
-caller.
+With `--stack --merge`, the highest open layer whose open lower layers all have current READY
+receipts, and whose bottom open layer GitHub has retargeted onto the stack base, returns `MERGE`
+with `gh stack merge <that PR number> --yes --squash`. That lands the named layer and every
+unmerged layer below it. When the base uses a merge queue, the same command queues the prefix
+together and GitHub evaluates each layer from the bottom; a failure ejects that layer and those
+above it. Layers above the prefix keep their one-PR sessions. After the merge, GitHub retargets
+the next layer, so the rerun continues until the stack returns `CANCEL`. API and MCP aggregate
+calls perform one summary tick and leave recurrence to the caller.
 
 Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSeconds`, `timeoutSeconds`, `debounceSeconds`, and `quietStatus`. Explicit flags override configuration, including `--no-quiet-status` when a shared config enables quiet output. Quiet status remains off by default.
 

package/bin/cli/api-usage-formatter.mjs

@@ -9,7 +9,7 @@ export function formatQuotaWarning(warning) {
     if (warning === undefined)
         return null;
     const used = warning.used === undefined ? "" : ` · used ${warning.used}`;
-    return [
+    const lines = [
         "## GitHub API quota warning",
         "",
         `- Resource: \`${warning.resource}\``,
@@ -18,8 +18,22 @@ export function formatQuotaWarning(warning) {
         `- Reset: ${resetTime(warning.resetAt)}`,
         `- Recommended poll interval: ${warning.pollIntervalMinutes} minutes`,
         `- Recommended bounded CLI timeout: ${warning.pollTimeoutMinutes} minutes`,
-        "- Recommendation: keep polling pr-shepherd at the cadence above; for incidental PR operations prefer REST `gh` (`gh pr view`, `gh pr review`, `gh api`); do not substitute `gh pr checks`/`gh pr watch`",
-    ].join("\n");
+        recommendation(warning),
+    ];
+    for (const budget of warning.budgets ?? []) {
+        const budgetUsed = budget.used === undefined ? "" : ` · used ${budget.used}`;
+        lines.push(`- Budget \`${budget.resource}\`: ${budget.remaining}/${budget.limit} remaining${budgetUsed} · crossed ${budget.thresholdPercent}% · resets ${resetTime(budget.resetAt)}`);
+    }
+    return lines.join("\n");
+}
+function recommendation(warning) {
+    if (warning.resource === "combined") {
+        return "- Recommendation: keep polling pr-shepherd at the cadence above; both GraphQL and REST core are below their warning thresholds, so do not shift work between them. Do not substitute `gh pr checks` or `gh pr watch`";
+    }
+    if (warning.resource === "core") {
+        return "- Recommendation: keep polling pr-shepherd at the cadence above; do not add incidental REST `gh` calls (`gh pr view`, `gh pr review`, `gh api`) while REST core is low. Do not substitute `gh pr checks` or `gh pr watch`";
+    }
+    return "- Recommendation: keep polling pr-shepherd at the cadence above; for incidental PR operations prefer REST `gh` (`gh pr view`, `gh pr review`, `gh api`); do not substitute `gh pr checks` or `gh pr watch`";
 }
 export function formatApiUsage(usage) {
     if (usage === undefined)

package/bin/cli/iterate-instructions.mjs

@@ -4,18 +4,6 @@ import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { formatPrUrl } from "../pr-reference.mjs";
 import { AUTO_MARK_READY_DISABLED_HOLD } from "../commands/stack-work.mjs";
 import { buildPrShepherdCommand } from "./runner.mjs";
-const STACK_LAYER_BLOCK_REASONS = {
-    closed: "was closed without merging",
-    draft: "is still a draft",
-    conflicting: "has merge conflicts",
-    "queue-removal": "has an unacknowledged merge-queue removal",
-    "failing-checks": "has failing checks",
-    "review-work": "has unresolved review work",
-    "checks-in-progress": "has checks in progress",
-    "merge-state": "is not in a mergeable state",
-    "no-ready-receipt": "has no current Shepherd READY receipt",
-    "stale-ancestry": "is not rebased onto its parent layer's current head",
-};
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "wait":
@@ -76,20 +64,13 @@ function buildStackDraftHoldInstruction(result, hold) {
         formatPrUrl(result.repo, result.pr),
         "--until-terminal",
     ]).text;
-    const lowerLayer = hold.kind === "lower-layer-not-ready" ? hold.lowerLayer : undefined;
     const handoff = `a \`--stack\` selector listed this session, finish that selector's remaining steps and rerun it with its original flags; otherwise run ${inlineCode(stackCommand)}, adding \`--merge\` when merging was requested.`;
-    const instruction = lowerLayer
-        ? `PR #${result.pr} stays in draft because lower stack layer PR #${lowerLayer.pr} ${STACK_LAYER_BLOCK_REASONS[lowerLayer.reason]}, so repeating this one-PR session cannot advance it. Advance PR #${lowerLayer.pr} first: if ${handoff}`
-        : `PR #${result.pr} stays in draft because ${holdReason(hold)}, so repeating this one-PR session cannot advance it. If ${handoff}`;
+    const reason = hold.kind === "auto-mark-ready-disabled" ? AUTO_MARK_READY_DISABLED_HOLD : hold.kind;
+    const instruction = `PR #${result.pr} stays in draft because ${reason}, so repeating this one-PR session cannot advance it. If ${handoff}`;
     return result.quotaWarning
         ? buildQuotaAwareContinuation(result.quotaWarning, instruction)
         : instruction;
 }
-function holdReason(hold) {
-    return hold.kind === "auto-mark-ready-disabled"
-        ? AUTO_MARK_READY_DISABLED_HOLD
-        : "its lower stack layers could not be verified";
-}
 export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }

package/bin/cli/poll-summary-formatter.mjs

@@ -43,12 +43,11 @@ function formatItem(item) {
         : "";
     const readyDelay = item.remainingSeconds !== undefined ? ` · ready delay \`${item.remainingSeconds}s\`` : "";
     const readyReceipt = item.readyReceipt ? " · Shepherd READY completion `verified`" : "";
-    const blockedBy = item.blockedByPr ? ` · stack blocked by PR #${item.blockedByPr}` : "";
     const checks = item.checks;
     const review = item.review;
     return [
         `- [PR #${item.pr}: ${escapeMarkdownText(item.title)}](${item.url}) [${item.action.toUpperCase()}]`,
-        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${blockedBy}${stack}`,
+        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${stack}`,
         `  - head \`${item.headRefName}\` at \`${item.headRefOid}\` · base \`${item.baseRefName}\``,
         ...(checks
             ? [`  - checks: ${formatCounts(checks, checks.incomplete ? ", incomplete" : "")}`]

package/bin/commands/iterate/api-usage.mjs

@@ -1,6 +1,6 @@
 import { loadConfig } from "../../config/load.mjs";
 import { summarizeApiTelemetry } from "../../github/api-telemetry.mjs";
-import { evaluateWorktreeGraphqlQuotaWarning } from "../../state/graphql-quota-warnings.mjs";
+import { selectQuotaWarning } from "../quota-selection.mjs";
 import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
 function shouldWarn(result) {
     return ["wait", "mark_ready", "merge", "fix_code"].includes(result.action);
@@ -10,14 +10,15 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
     if (apiUsage === undefined)
         return result;
     let quotaWarning = preservePersistedWarning ? result.quotaWarning : undefined;
-    if (quotaWarning === undefined && apiUsage.graphql !== undefined && shouldWarn(result)) {
+    const core = apiUsage.rest?.find((item) => item.resource === "core");
+    if (quotaWarning === undefined && shouldWarn(result) && (apiUsage.graphql || core)) {
         const [owner, repo] = result.repo.split("/");
         if (owner && repo) {
             const bands = loadConfig().watch.graphqlQuotaWarnings.map((band) => ({
                 ...band,
                 pollIntervalMinutes: Math.max(band.pollIntervalMinutes, minimumPollIntervalMinutes),
             }));
-            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands, apiUsage.graphql, persistWarning);
+            quotaWarning = await selectQuotaWarning({ owner, repo }, bands, apiUsage, persistWarning);
         }
     }
     const { quotaWarning: _deferredWarning, ...baseResult } = result;

package/bin/commands/iterate/index.mjs

@@ -22,7 +22,7 @@ import { fingerprintRawSummaryPr } from "../../github/poll-summary-fingerprint.m
 import { currentQueueRemovalEvent } from "../../github/poll-summary-queue-removal.mjs";
 import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
 import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyReceipt, } from "../../state/ready-receipts.mjs";
-import { findParentMarkReadyBlock, heldByLowerLayer, stackDraftHold } from "./parent-first.mjs";
+import { stackDraftHold } from "./parent-first.mjs";
 import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
@@ -175,11 +175,8 @@ async function runIterateCore(opts) {
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
         !report.mergeStatus.blockingBotReviewInProgress;
-    const parentBlock = canMarkReady
-        ? await findParentMarkReadyBlock(report, { owner: repoOwner, name: repoName })
-        : undefined;
     const autoMarkReady = !opts.noAutoMarkReady && config.actions.autoMarkReady;
-    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !parentBlock && autoMarkReady, base, report);
+    const markReadyResult = await markReadyIfAuthorized(canMarkReady && autoMarkReady, base, report);
     if (markReadyResult)
         return markReadyResult;
     if (readyState.shouldCancel && !report.mergeStatus.isDraft) {
@@ -209,19 +206,13 @@ async function runIterateCore(opts) {
             log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
         };
     }
-    const hold = stackDraftHold(report, autoMarkReady, parentBlock);
+    const hold = stackDraftHold(report, autoMarkReady);
     const wait = {
         ...base,
         action: "wait",
         log: buildWaitLog(base),
         ...(hold && { stackDraftHold: hold }),
     };
-    // The lower layer's own session owns progress here, so this draft cannot
-    // stall; its stall clock restarts once that layer releases it.
-    if (heldByLowerLayer(wait)) {
-        await clearStallState(stallKey);
-        return wait;
-    }
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, report, reviewSummaryIds);
 }
 async function recordReadyReceipt(key, report) {

package/bin/commands/iterate/parent-first.d.mts

@@ -1,25 +1,8 @@
-import type { RepoInfo } from "../../github/client.mts";
-import type { IterateResult, ShepherdReport, StackDraftHold, StackLowerLayerBlock } from "../../types.mts";
+import type { ShepherdReport, StackDraftHold } from "../../types.mts";
 /**
- * What keeps a draft child from being marked ready: the lowest blocking lower layer,
- * or a stack read that could not attribute the block to one.
+ * A native stack draft this one-PR session cannot promote because it is ready
+ * and automatic mark-ready is off. A draft that is not ready yet keeps the
+ * ordinary wait. A clean draft is marked ready on its own, without waiting
+ * for lower layers.
  */
-export type ParentMarkReadyBlock = StackLowerLayerBlock | "unverifiable";
-/**
- * Draft children may only be converted after their immediate parent has
- * independently completed a one-PR ready-delay and the stack boundary is
- * still linear.  A failed or incomplete stack read blocks this mutation but
- * does not block ordinary review/CI work in the caller.
- */
-export declare function findParentMarkReadyBlock(report: ShepherdReport, repo: RepoInfo): Promise<ParentMarkReadyBlock | undefined>;
-/**
- * A native stack draft this one-PR session cannot promote: a lower layer blocks it, or
- * automatic mark-ready is off. Undefined when the session can still advance the PR by
- * iterating.
- */
-export declare function stackDraftHold(report: ShepherdReport, autoMarkReady: boolean, parentBlock: ParentMarkReadyBlock | undefined): StackDraftHold | undefined;
-/**
- * The lower layer a held draft waits on. That layer's own session owns this draft's
- * progress, so the draft neither stalls nor keeps polling while it waits.
- */
-export declare function heldByLowerLayer(result: IterateResult): StackLowerLayerBlock | undefined;
+export declare function stackDraftHold(report: ShepherdReport, autoMarkReady: boolean): StackDraftHold | undefined;

package/bin/commands/iterate/parent-first.mjs

@@ -1,70 +1,13 @@
-import { fetchPollSummary } from "../../github/poll-summary.mjs";
-import { stackLayerBlockReason } from "../stack-layer-readiness.mjs";
 /**
- * Draft children may only be converted after their immediate parent has
- * independently completed a one-PR ready-delay and the stack boundary is
- * still linear.  A failed or incomplete stack read blocks this mutation but
- * does not block ordinary review/CI work in the caller.
+ * A native stack draft this one-PR session cannot promote because it is ready
+ * and automatic mark-ready is off. A draft that is not ready yet keeps the
+ * ordinary wait. A clean draft is marked ready on its own, without waiting
+ * for lower layers.
  */
-export async function findParentMarkReadyBlock(report, repo) {
-    const stack = report.mergeStatus.mergeRequirements?.stack;
-    if (!stack || stack.position === 1)
-        return undefined;
-    if (stack.position < 1)
-        return "unverifiable";
-    try {
-        const summary = await fetchPollSummary({ stackPrNumber: report.pr }, repo);
-        const child = summary.prs.find((item) => item.pr === report.pr);
-        const lowerLayers = summary.prs
-            .filter((item) => (item.stack?.position ?? Number.MAX_SAFE_INTEGER) < stack.position)
-            .sort((left, right) => (left.stack?.position ?? Number.MAX_SAFE_INTEGER) -
-            (right.stack?.position ?? Number.MAX_SAFE_INTEGER));
-        if (!child || child.state !== "OPEN" || lowerLayers.length !== stack.position - 1)
-            return "unverifiable";
-        // A stale boundary means that layer is no longer based on the parent it was
-        // reviewed against. Gaps above this child do not affect its promotion boundary.
-        const staleChildren = new Set(summary.stackAncestry?.map((gap) => gap.childPr));
-        for (const layer of lowerLayers) {
-            // A merged layer is already satisfied; GitHub may have retargeted the
-            // layer above it to the trunk as part of the merge.
-            if (layer.state === "MERGED")
-                continue;
-            const reason = staleChildren.has(layer.pr) ? "stale-ancestry" : stackLayerBlockReason(layer);
-            if (reason)
-                return { pr: layer.pr, reason };
-        }
-        // This layer's own stale boundary belongs to its own session's repair; the
-        // earlier stale-ancestry read missed it, so this snapshot is unsettled.
-        return staleChildren.has(report.pr) ? "unverifiable" : undefined;
-    }
-    catch {
-        // Never convert a child draft based on an unverifiable parent.
-        return "unverifiable";
-    }
-}
-/**
- * A native stack draft this one-PR session cannot promote: a lower layer blocks it, or
- * automatic mark-ready is off. Undefined when the session can still advance the PR by
- * iterating.
- */
-export function stackDraftHold(report, autoMarkReady, parentBlock) {
+export function stackDraftHold(report, autoMarkReady) {
     if (!report.mergeStatus.mergeRequirements?.stack || !report.mergeStatus.isDraft)
         return undefined;
-    // Any lower-layer block outranks the session flag: even with automatic
-    // mark-ready enabled, this draft cannot advance until that layer does, and a
-    // lower-layer read that failed must not hide behind the flag.
-    if (parentBlock === "unverifiable")
-        return { kind: "lower-layer-not-ready" };
-    if (parentBlock)
-        return { kind: "lower-layer-not-ready", lowerLayer: parentBlock };
+    if (report.status !== "READY" || report.mergeStatus.blockingBotReviewInProgress)
+        return undefined;
     return autoMarkReady ? undefined : { kind: "auto-mark-ready-disabled" };
 }
-/**
- * The lower layer a held draft waits on. That layer's own session owns this draft's
- * progress, so the draft neither stalls nor keeps polling while it waits.
- */
-export function heldByLowerLayer(result) {
-    return result.action === "wait" && result.stackDraftHold?.kind === "lower-layer-not-ready"
-        ? result.stackDraftHold.lowerLayer
-        : undefined;
-}

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

@@ -1,10 +1,22 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
-import type { GraphqlApiUsage, PollSummaryResult } 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;
+import type { ApiResourceUsage, GraphqlApiUsage, PollSummaryResult } from "../types.mts";
+/** Slow the poll for whichever of GraphQL or REST core is in a tighter band. */
+export declare function quotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], usage: {
+    graphql?: Pick<GraphqlApiUsage, "remaining" | "limit">;
+    rest?: Pick<ApiResourceUsage, "resource" | "remaining" | "limit">[];
+} | undefined, fallbackMs: number, maxMs: number): number;
+export interface RateLimitRetry {
+    ms: number;
+    resource: string;
+    remaining?: number;
+    limit?: number;
+    resetAt?: number;
+}
 /**
- * Retry delay for `--until-terminal` when GitHub returns a GraphQL 429 / secondary
- * limit. `null` means the error is not a retryable rate limit.
+ * Retry delay for `--until-terminal` when GitHub exhausts a primary quota or
+ * returns a secondary limit. `null` means the error is not a retryable rate limit.
  */
-export declare function pollGraphQlRetryAfterMs(err: unknown): number | null;
+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;
 export declare function aggregateQuotaWarning(result: PollSummaryResult, bands: GraphqlQuotaWarningBand[], intervalSeconds: number): Promise<PollSummaryResult["quotaWarning"]>;

package/bin/commands/poll-quota.mjs

@@ -1,10 +1,10 @@
-import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
 import { summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { GitHubRequestError } from "../github/errors.mjs";
 import { isRateLimitMessage } from "../comments/rate-limit.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. */
-export function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
+function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
     if (usage === undefined || usage.limit <= 0 || bands.length === 0) {
         return Math.min(fallbackMs, maxMs);
     }
@@ -15,33 +15,71 @@ export function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
     const bandMs = active.pollIntervalMinutes * 60_000;
     return Math.min(Math.max(fallbackMs, bandMs), maxMs);
 }
+/** Slow the poll for whichever of GraphQL or REST core is in a tighter band. */
+export function quotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
+    const core = usage?.rest?.find((item) => item.resource === "core");
+    return Math.max(graphqlQuotaPollIntervalMs(bands, usage?.graphql, fallbackMs, maxMs), graphqlQuotaPollIntervalMs(bands, core, fallbackMs, maxMs));
+}
 /**
- * Retry delay for `--until-terminal` when GitHub returns a GraphQL 429 / secondary
- * limit. `null` means the error is not a retryable rate limit.
+ * Retry delay for `--until-terminal` when GitHub exhausts a primary quota or
+ * returns a secondary limit. `null` means the error is not a retryable rate limit.
  */
-export function pollGraphQlRetryAfterMs(err) {
+export function pollRateLimitRetryAfterMs(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);
+    const rateLimitMessage = isRateLimitMessage(err.message) ||
+        (err.graphqlErrors?.some((error) => isRateLimitMessage(error.message)) ?? false);
+    const exhausted = err.rateLimit !== undefined && err.rateLimit.remaining <= 0;
+    const retryable = err.status === 429 || err.retryAfterSeconds !== undefined || rateLimitMessage || exhausted;
     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);
+    const resource = retryResource(err);
+    const rateLimit = err.rateLimit;
+    const details = {
+        resource,
+        ...(rateLimit?.remaining !== undefined && { remaining: rateLimit.remaining }),
+        ...(rateLimit?.limit !== undefined && { limit: rateLimit.limit }),
+        ...(rateLimit?.resetAt !== undefined && { resetAt: rateLimit.resetAt }),
+    };
+    if (err.retryAfterSeconds !== undefined) {
+        return { ...details, ms: Math.max(err.retryAfterSeconds, 0) * 1000 };
     }
-    return GRAPHQL_RETRY_AFTER_DEFAULT_MS;
+    if (exhausted && rateLimit !== undefined) {
+        return { ...details, ms: Math.max(rateLimit.resetAt * 1000 - Date.now(), 0) };
+    }
+    return { ...details, ms: GRAPHQL_RETRY_AFTER_DEFAULT_MS };
+}
+function retryResource(err) {
+    if (err.rateLimit?.resource)
+        return err.rateLimit.resource;
+    const secondary = err.status === 429 ||
+        err.retryAfterSeconds !== undefined ||
+        /secondary/i.test(err.message) ||
+        (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
+        ? ` (${retry.remaining}/${retry.limit})`
+        : "";
+    return `[${tickLabel} / +${elapsedSeconds}s] ${label}${counts} — retrying at ${clock} (in ${Math.round(retry.ms / 1000)}s)\n`;
 }
 export async function aggregateQuotaWarning(result, bands, intervalSeconds) {
-    const usage = summarizeApiTelemetry()?.graphql;
+    const usage = summarizeApiTelemetry();
     const [owner, repo] = result.repo.split("/");
     if (!usage || !owner || !repo)
         return undefined;
-    return evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands.map((band) => ({
+    if (!usage.graphql && !usage.rest?.some((item) => item.resource === "core"))
+        return undefined;
+    return selectQuotaWarning({ owner, repo }, bands.map((band) => ({
         ...band,
         pollIntervalMinutes: Math.max(band.pollIntervalMinutes, intervalSeconds / 60),
     })), usage, true);

package/bin/commands/poll-summary-instructions.mjs

@@ -1,7 +1,7 @@
 /* eslint-disable max-lines */
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
-import { appendAutonomousInstructions, appendHumanHandoffInstructions, findHumanHandoffs, idleWaitPlan, isStackLayerReady, planBottomDrain, retargetWaitPlan, stackPosition, } from "./stack-drain.mjs";
+import { appendAutonomousInstructions, appendHumanHandoffInstructions, findHumanHandoffs, idleWaitPlan, isStackLayerReady, planPrefixDrain, retargetWaitPlan, stackPosition, } from "./stack-drain.mjs";
 import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
 export function withPollSummaryInstructions(result, mergeRequested) {
@@ -14,59 +14,44 @@ export function planPollSummary(result, mergeRequested) {
     }
     const prs = [...result.prs].sort((left, right) => stackPosition(left) - stackPosition(right));
     const staleChildren = new Set(result.stackAncestry?.map((gap) => gap.childPr) ?? []);
-    const firstUnready = prs.find((item) => item.state === "OPEN" && (!isStackLayerReady(item) || staleChildren.has(item.pr)));
-    const blocked = prs.map((item) => firstUnready && item.state === "OPEN" && stackPosition(item) > stackPosition(firstUnready)
-        ? {
-            ...item,
-            ...(["cancel", "mark_ready", "merge"].includes(item.action) && {
-                action: "wait",
-                reasons: [...item.reasons, "lower-layer-not-ready"],
-            }),
-            blockedByPr: firstUnready.pr,
-            ...(item.isDraft &&
-                item.pollCommand && {
-                pollCommand: item.pollCommand.replace(" --until-terminal", " --timeout 1s --debounce 0s") +
-                    (item.pollCommand.includes("--no-auto-mark-ready") ? "" : " --no-auto-mark-ready"),
-                pollProbe: true,
-            }),
-        }
-        : item.state === "OPEN" &&
-            (!isStackLayerReady(item) || staleChildren.has(item.pr)) &&
-            ["cancel", "merge"].includes(item.action)
-            ? {
-                ...item,
-                action: "fix_code",
-                reasons: [
-                    ...item.reasons,
-                    staleChildren.has(item.pr) ? "stale-ancestry" : "ready-receipt-required",
-                ],
-            }
-            : item);
     const projected = {
         ...result,
-        prs: blocked.map((item) => {
-            if (item.state === "OPEN" && item.isInMergeQueue && item.action === "cancel") {
-                return {
+        prs: prs.map((item) => {
+            const needsOwnSession = item.state === "OPEN" &&
+                (!isStackLayerReady(item) || staleChildren.has(item.pr)) &&
+                ["cancel", "merge"].includes(item.action);
+            const layer = needsOwnSession
+                ? {
                     ...item,
+                    action: "fix_code",
+                    reasons: [
+                        ...item.reasons,
+                        staleChildren.has(item.pr) ? "stale-ancestry" : "ready-receipt-required",
+                    ],
+                }
+                : item;
+            if (layer.state === "OPEN" && layer.isInMergeQueue && layer.action === "cancel") {
+                return {
+                    ...layer,
                     action: "wait",
-                    reasons: [...item.reasons, "already-in-merge-queue"],
+                    reasons: [...layer.reasons, "already-in-merge-queue"],
                 };
             }
-            if (item.state === "CLOSED" && closedDependency(blocked, item.pr)) {
+            if (layer.state === "CLOSED" && closedDependency(prs, layer.pr)) {
                 return {
-                    ...item,
+                    ...layer,
                     action: "escalate",
-                    reasons: [...item.reasons, "closed-unmerged-dependency"],
+                    reasons: [...layer.reasons, "closed-unmerged-dependency"],
                 };
             }
-            if (item.state !== "OPEN" && item.state !== "MERGED") {
+            if (layer.state !== "OPEN" && layer.state !== "MERGED") {
                 return {
-                    ...item,
+                    ...layer,
                     action: "escalate",
-                    reasons: [...item.reasons, "unverified-stack-state"],
+                    reasons: [...layer.reasons, "unverified-stack-state"],
                 };
             }
-            return item;
+            return layer;
         }),
     };
     const planned = planStack(projected, mergeRequested);
@@ -100,7 +85,7 @@ function planStack(result, mergeRequested) {
     const runnableCandidates = work.sessions.filter((item) => item.pollCommand);
     const missingCommands = work.sessions.filter((item) => !item.pollCommand);
     const agentWork = runnableCandidates.length > 0 || work.markReady.length > 0;
-    const drain = planBottomDrain(result, mergeRequested);
+    const drain = planPrefixDrain(result, mergeRequested);
     if (drain)
         return drain;
     const handoffs = findHumanHandoffs(result);

package/bin/commands/poll-summary.mjs

@@ -5,7 +5,7 @@ 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, graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs, } from "./poll-quota.mjs";
+import { aggregateQuotaWarning, formatRateLimitRetryLine, pollRateLimitRetryAfterMs, quotaPollIntervalMs, } from "./poll-quota.mjs";
 import { planPollSummary, withPollSummaryInstructions } from "./poll-summary-instructions.mjs";
 import { summaryStatusSignature } from "./poll-summary-signature.mjs";
 import { applyStackStallGuard } from "./stack-stall.mjs";
@@ -83,12 +83,12 @@ async function runAggregatePollCore(opts) {
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
                 }, opts.merge);
             }
-            const retryMs = opts.untilTerminal ? pollGraphQlRetryAfterMs(error) : null;
-            if (retryMs === null || rateLimitRetries >= 1)
+            const retry = opts.untilTerminal ? pollRateLimitRetryAfterMs(error) : null;
+            if (retry === null || rateLimitRetries >= 1)
                 throw error;
             rateLimitRetries += 1;
-            process.stderr.write(`[aggregate poll tick ${tick} / +${Math.round((Date.now() - start) / 1000)}s] GraphQL rate limit — retrying in ${Math.round(retryMs / 1000)}s\n`);
-            await sleep(retryMs);
+            process.stderr.write(formatRateLimitRetryLine(`aggregate poll tick ${tick}`, Math.round((Date.now() - start) / 1000), retry));
+            await sleep(retry.ms);
             continue;
         }
         const allTerminal = last.selection.kind === "stack"
@@ -142,7 +142,7 @@ async function runAggregatePollCore(opts) {
         const elapsedMs = Date.now() - start;
         const sleepMs = debounceUntil
             ? Math.min(intervalMs, Math.max(debounceUntil - Date.now(), 0))
-            : graphqlQuotaPollIntervalMs(quotaBands, summarizeApiTelemetry()?.graphql, intervalMs, MAX_TIMER_MS);
+            : quotaPollIntervalMs(quotaBands, summarizeApiTelemetry(), intervalMs, MAX_TIMER_MS);
         if (!opts.untilTerminal && debounceUntil === null) {
             const remainingMs = timeoutMs - elapsedMs;
             if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {