pr-shepherd 0.56.6 → 0.57.0

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

@@ -0,0 +1,31 @@
+import type { NextCheck, NextCheckReason } from "../types/next-check.mts";
+/** A queued PR is rechecked about every five minutes, matching the poll cadence for queue waits. */
+export declare const MERGE_QUEUE_RECHECK_SECONDS = 300;
+/** Backstop for a missed GitHub event; events normally wake the session long before this. */
+export declare const SAFETY_NET_SECONDS = 3000;
+export interface NextCheckCandidate {
+    reason: NextCheckReason;
+    seconds: number;
+}
+/** The earliest candidate as a `NextCheck`, with `at` rounded up to a whole minute. */
+export declare function earliestNextCheck(candidates: NextCheckCandidate[], nowMs?: number): NextCheck | undefined;
+interface NextCheckFacts {
+    /** The action Shepherd returned for this tick. */
+    action: "wait" | "ready" | "mark_ready" | "fix_code" | "merge" | "cancel" | "escalate";
+    /** Ready-delay seconds left; only meaningful for `ready`. */
+    remainingSeconds?: number;
+    queued?: boolean;
+    /** A `merge` tick whose printed command is a REST merge request, which can stay `pending`. */
+    restMerge?: boolean;
+    /** A native-stack draft hold: repeating this one-PR session cannot advance it. */
+    stackDraftHold?: boolean;
+    /** Unix seconds when an unchanged state would trip the stall timeout. */
+    stallDeadlineSeconds?: number;
+}
+/**
+ * Deadlines for one PR, or none when the caller must not wait for one. `mark_ready` has none:
+ * its tick saw a draft, so only an immediate rerun can start the ready-delay timer. A REST
+ * merge can return `pending`, so it keeps a wake-up to resume the recorded request.
+ */
+export declare function nextCheckCandidates(facts: NextCheckFacts, nowMs: number): NextCheckCandidate[];
+export {};

package/bin/commands/next-check.mjs

@@ -0,0 +1,46 @@
+/** A queued PR is rechecked about every five minutes, matching the poll cadence for queue waits. */
+export const MERGE_QUEUE_RECHECK_SECONDS = 300;
+/** Backstop for a missed GitHub event; events normally wake the session long before this. */
+export const SAFETY_NET_SECONDS = 3000;
+/** The earliest candidate as a `NextCheck`, with `at` rounded up to a whole minute. */
+export function earliestNextCheck(candidates, nowMs = Date.now()) {
+    const first = [...candidates].sort((a, b) => a.seconds - b.seconds)[0];
+    if (!first)
+        return undefined;
+    const atMs = Math.ceil((nowMs + Math.max(0, first.seconds) * 1000) / 60_000) * 60_000;
+    return {
+        at: new Date(atMs).toISOString().replace(/\.\d{3}Z$/, "Z"),
+        inSeconds: Math.max(0, Math.round((atMs - nowMs) / 1000)),
+        reason: first.reason,
+    };
+}
+/**
+ * Deadlines for one PR, or none when the caller must not wait for one. `mark_ready` has none:
+ * its tick saw a draft, so only an immediate rerun can start the ready-delay timer. A REST
+ * merge can return `pending`, so it keeps a wake-up to resume the recorded request.
+ */
+export function nextCheckCandidates(facts, nowMs) {
+    if (facts.action === "merge" && facts.restMerge) {
+        return [{ reason: "merge-pending", seconds: MERGE_QUEUE_RECHECK_SECONDS }];
+    }
+    const terminal = ["cancel", "escalate", "merge", "mark_ready"].includes(facts.action);
+    if (terminal || facts.stackDraftHold)
+        return [];
+    const candidates = [];
+    if (facts.action === "ready" && (facts.remainingSeconds ?? 0) > 0) {
+        candidates.push({ reason: "ready-delay", seconds: facts.remainingSeconds });
+    }
+    else if (facts.queued && facts.action === "wait") {
+        candidates.push({ reason: "merge-queue", seconds: MERGE_QUEUE_RECHECK_SECONDS });
+    }
+    else {
+        candidates.push({ reason: "safety-net", seconds: SAFETY_NET_SECONDS });
+    }
+    if (facts.stallDeadlineSeconds !== undefined) {
+        candidates.push({
+            reason: "stall-timeout",
+            seconds: facts.stallDeadlineSeconds - nowMs / 1000,
+        });
+    }
+    return candidates;
+}

package/bin/commands/playbook.d.mts

@@ -0,0 +1,13 @@
+export type PlaybookResult = {
+    playbooks: string[];
+} | {
+    name: string;
+    content: string;
+};
+/**
+ * Resolve a playbook by name (case-insensitive; spaces and hyphens are equivalent) or file
+ * slug. With no name, list every playbook name. Unknown names fail with the available names.
+ */
+export declare function runPlaybook(name?: string): PlaybookResult;
+/** Markdown projection shared by the CLI text format and the MCP content channel. */
+export declare function formatPlaybookResult(result: PlaybookResult): string;

package/bin/commands/playbook.mjs

@@ -0,0 +1,48 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+/**
+ * Playbooks ship with the package under `plugins/pr-shepherd/skills/pr-shepherd/references/`
+ * (package.json `files` includes `plugins/**`), so a playbook pointer resolves
+ * with or without the skill installed. From `bin/commands/` or `src/commands/`, `../../` is
+ * the package root.
+ */
+const REFERENCES_DIR = new URL("../../plugins/pr-shepherd/skills/pr-shepherd/references/", import.meta.url);
+function normalize(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, "-");
+}
+/** Every shipped playbook, sorted by name. */
+function listPlaybooks() {
+    return readdirSync(REFERENCES_DIR)
+        .filter((file) => file.endsWith(".md"))
+        .map((file) => {
+        const content = readFileSync(new URL(file, REFERENCES_DIR), "utf8");
+        const slug = file.slice(0, -".md".length);
+        return {
+            name: /^# (.+)$/m.exec(content)?.[1]?.trim() ?? slug,
+            slug,
+            content,
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Resolve a playbook by name (case-insensitive; spaces and hyphens are equivalent) or file
+ * slug. With no name, list every playbook name. Unknown names fail with the available names.
+ */
+export function runPlaybook(name) {
+    const playbooks = listPlaybooks();
+    if (name === undefined || name.trim() === "")
+        return { playbooks: playbooks.map((p) => p.name) };
+    const wanted = normalize(name);
+    const match = playbooks.find((p) => normalize(p.name) === wanted || p.slug === wanted);
+    if (!match) {
+        throw new ShepherdError(`Unknown playbook ${JSON.stringify(name)}. Available: ${playbooks.map((p) => JSON.stringify(p.name)).join(", ")}`, EXIT.USAGE);
+    }
+    return { name: match.name, content: match.content };
+}
+/** Markdown projection shared by the CLI text format and the MCP content channel. */
+export function formatPlaybookResult(result) {
+    return "playbooks" in result
+        ? result.playbooks.map((name) => `- ${name}`).join("\n")
+        : result.content.trimEnd();
+}

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

@@ -0,0 +1,8 @@
+import type { PollMode } from "../config/load.mts";
+/** The mode a command actually runs in. `auto` has been resolved away. */
+export type ResolvedPollMode = "poll" | "event";
+/**
+ * Resolve `--poll-mode` / the `pollMode` option / `poll.mode`. An explicit request wins over
+ * config; `auto` becomes `event` only inside a cloud session. A missing value counts as `auto`.
+ */
+export declare function resolvePollMode(requested: PollMode | undefined, configured: PollMode | undefined): ResolvedPollMode;

package/bin/commands/poll-mode.mjs

@@ -0,0 +1,14 @@
+/** True when the process runs in a Claude Code cloud (remote) session. */
+function isCloudSession() {
+    return process.env["CLAUDE_CODE_REMOTE"] === "true";
+}
+/**
+ * Resolve `--poll-mode` / the `pollMode` option / `poll.mode`. An explicit request wins over
+ * config; `auto` becomes `event` only inside a cloud session. A missing value counts as `auto`.
+ */
+export function resolvePollMode(requested, configured) {
+    const mode = requested ?? configured ?? "auto";
+    if (mode === "auto")
+        return isCloudSession() ? "event" : "poll";
+    return mode;
+}

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

@@ -12,4 +12,5 @@ export declare function writeWaitProgress(opts: {
     lastWaitSignature: string | null;
 }): string | null;
 export declare function writeDebounceProgress(tick: number, elapsedMs: number, remainingMs: number): void;
+export declare function writeRuleAutoResolveProgress(result: IterateResult): void;
 export {};

package/bin/commands/poll-progress.mjs

@@ -40,9 +40,8 @@ export function writeWaitProgress(opts) {
     const sleepSeconds = Math.round(opts.sleepMs / 1000);
     if (!opts.quietStatus) {
         const reason = waitReason(opts.result);
-        writeTickProgress(opts.tick, elapsedSeconds, opts.verbose
-            ? `${reason} — sleeping ${sleepSeconds}s`
-            : `${reason}; next tick in ${sleepSeconds}s`);
+        // The tick interval is the caller's own `--interval`; only verbose mode repeats it.
+        writeTickProgress(opts.tick, elapsedSeconds, opts.verbose ? `${reason} — sleeping ${sleepSeconds}s` : reason);
         return opts.lastWaitSignature;
     }
     const signature = waitSignature(opts.result);
@@ -56,3 +55,7 @@ export function writeDebounceProgress(tick, elapsedMs, remainingMs) {
     const remainingSeconds = Math.round(remainingMs / 1000);
     process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
 }
+export function writeRuleAutoResolveProgress(result) {
+    if (result.ruleAutoResolve?.summary)
+        process.stderr.write(`${result.ruleAutoResolve.summary}\n`);
+}

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

@@ -1,11 +1,12 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
 import { type RateLimitKind } from "../github/rate-limit-kind.mts";
-import type { ApiResourceUsage, GraphqlApiUsage, PollSummaryResult } from "../types.mts";
+import type { ApiResourceUsage, GraphqlApiUsage, GraphqlQuotaWarning, PollSummaryResult } from "../types.mts";
+export declare function carryQuotaWarning(pending: GraphqlQuotaWarning | undefined, current: GraphqlQuotaWarning | undefined, transport?: "graphql" | "rest"): GraphqlQuotaWarning | undefined;
 /** 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;
+} | undefined, fallbackMs: number, maxMs: number, transport?: "graphql" | "rest"): number;
 export interface RateLimitRetry {
     ms: number;
     resource: string;

package/bin/commands/poll-quota.mjs

@@ -3,7 +3,11 @@ import { GitHubRequestError } from "../github/errors.mjs";
 import { rateLimitKind } from "../github/rate-limit-kind.mjs";
 import { exhaustedPrimaryLimitDelayMs } from "./poll-rate-limit-delay.mjs";
 import { selectQuotaWarning } from "./quota-selection.mjs";
+import { getGithubTransport } from "../github/transport.mjs";
 const GRAPHQL_RETRY_AFTER_DEFAULT_MS = 60_000;
+export function carryQuotaWarning(pending, current, transport = getGithubTransport()) {
+    return current ?? (transport === "rest" && pending?.resource !== "core" ? undefined : pending);
+}
 /** Sleep at least `--interval`, and at least the active crossed quota band. */
 function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
     if (usage === undefined || usage.limit <= 0 || bands.length === 0) {
@@ -17,9 +21,9 @@ function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
     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) {
+export function quotaPollIntervalMs(bands, usage, fallbackMs, maxMs, transport) {
     const core = usage?.rest?.find((item) => item.resource === "core");
-    return Math.max(graphqlQuotaPollIntervalMs(bands, usage?.graphql, fallbackMs, maxMs), graphqlQuotaPollIntervalMs(bands, core, fallbackMs, maxMs));
+    return Math.max(graphqlQuotaPollIntervalMs(bands, transport === "rest" ? undefined : usage?.graphql, fallbackMs, maxMs), graphqlQuotaPollIntervalMs(bands, core, fallbackMs, maxMs));
 }
 /**
  * Retry delay for `--until-terminal` when GitHub exhausts a primary quota or
@@ -88,5 +92,5 @@ export async function aggregateQuotaWarning(result, bands, intervalSeconds) {
     return selectQuotaWarning({ owner, repo }, bands.map((band) => ({
         ...band,
         pollIntervalMinutes: Math.max(band.pollIntervalMinutes, intervalSeconds / 60),
-    })), usage, true);
+    })), usage, true, getGithubTransport());
 }

package/bin/commands/poll-summary-explicit-instructions.d.mts

@@ -1,2 +1,4 @@
 import type { PollSummaryResult } from "../types.mts";
+/** Every selected row already returned `CANCEL` or `ESCALATE`: no autonomous work remains. */
+export declare function isHandedOffSelection(result: PollSummaryResult): boolean;
 export declare function explicitInstructions(result: PollSummaryResult): string[];

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

@@ -1,4 +1,9 @@
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+/** Every selected row already returned `CANCEL` or `ESCALATE`: no autonomous work remains. */
+export function isHandedOffSelection(result) {
+    return (result.prs.length > 0 &&
+        result.prs.every((item) => item.action === "cancel" || item.action === "escalate"));
+}
 export function explicitInstructions(result) {
     if (result.reason === "all_terminal")
         return ["1. Stop — every selected PR is terminal."];
@@ -15,7 +20,11 @@ export function explicitInstructions(result) {
         "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
         "3. Run this aggregate poll again after selected work completes; one row's `ESCALATE` does not stop work on other rows.",
     ];
-    if (result.quotaWarning) {
+    if (isHandedOffSelection(result)) {
+        instructions[2] =
+            "3. Stop after reporting each `ESCALATE` handoff; every selected row is `CANCEL` or `ESCALATE`, so do not run this aggregate poll again.";
+    }
+    else if (result.quotaWarning) {
         instructions[2] = buildQuotaAwareContinuation(result.quotaWarning, "3. After selected work completes,");
     }
     return instructions;

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

@@ -2,7 +2,7 @@
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
 import { appendAutonomousInstructions, appendHumanHandoffInstructions, findHumanHandoffs, idleWaitPlan, isStackLayerReady, planPrefixDrain, retargetWaitPlan, stackPosition, } from "./stack-drain.mjs";
-import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
+import { appendMarkReadyInstructions, appendStackRerunInstruction, splitStackWork, } from "./stack-work.mjs";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
 export function withPollSummaryInstructions(result, mergeRequested) {
     return planPollSummary(result, mergeRequested).result;
@@ -85,6 +85,8 @@ 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;
+    // Only owned work defers a human handoff: rerunning cannot advance another author's layer.
+    const ownedWork = [...runnableCandidates, ...work.markReady].some((item) => item.owned);
     const drain = planPrefixDrain(result, mergeRequested);
     if (drain)
         return drain;
@@ -93,13 +95,13 @@ function planStack(result, mergeRequested) {
         const instructions = [];
         appendAutonomousInstructions(instructions, runnableCandidates);
         appendMarkReadyInstructions(instructions, work.markReady);
-        const stop = !agentWork;
+        const stop = !ownedWork;
         appendHumanHandoffInstructions(instructions, handoffs, stop);
         for (const item of missingCommands) {
             instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. Ask for direction.`);
         }
-        if (agentWork) {
-            instructions.push(`${instructions.length + 1}. After the listed one-PR sessions, rerun this same \`--stack\` selector. Stop for the human handoff only when no autonomous shepherding remains.`);
+        if (ownedWork) {
+            appendStackRerunInstruction(instructions, [...runnableCandidates, ...work.markReady], "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.");
         }
         return { action: stop ? "escalate" : "shepherd", stackMergeable: false, instructions };
     }
@@ -116,20 +118,20 @@ function planStack(result, mergeRequested) {
             appendAutonomousInstructions(instructions, runnableCandidates);
             appendMarkReadyInstructions(instructions, work.markReady);
             for (const item of missingCommands) {
-                instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. ${agentWork ? "After autonomous shepherding, ask" : "Stop and ask"} for direction.`);
+                instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. ${ownedWork ? "After autonomous shepherding, ask" : "Stop and ask"} for direction.`);
             }
-            if (agentWork) {
-                instructions.push(`${instructions.length + 1}. After the listed one-PR sessions, rerun this same \`--stack\` selector. Stop for the human handoff only when no autonomous shepherding remains.`);
+            if (ownedWork) {
+                appendStackRerunInstruction(instructions, [...runnableCandidates, ...work.markReady], "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.");
             }
-            return { action: agentWork ? "shepherd" : "escalate", stackMergeable: false, instructions };
+            return { action: ownedWork ? "shepherd" : "escalate", stackMergeable: false, instructions };
         }
         if (!agentWork)
             return idleWaitPlan(work.idle);
         const instructions = [];
         appendAutonomousInstructions(instructions, work.sessions);
         appendMarkReadyInstructions(instructions, work.markReady);
-        instructions.push(`${instructions.length + 1}. After the selected one-PR sessions, rerun this same \`--stack\` selector.`);
-        return { action: "shepherd", stackMergeable: false, instructions };
+        const action = appendStackRerunInstruction(instructions, [...work.sessions, ...work.markReady], "After the selected one-PR sessions, rerun this same `--stack` selector.");
+        return { action, stackMergeable: false, instructions };
     }
     if (open.some((item) => item.isInMergeQueue)) {
         return {
@@ -150,13 +152,10 @@ function planStack(result, mergeRequested) {
     }
     if (!mergeRequested) {
         const instructions = [];
-        appendAutonomousInstructions(instructions, open.filter((item) => item.action !== "cancel"));
-        instructions.push(`${instructions.length + 1}. After the selected one-PR sessions, rerun this same \`--stack\` selector.`);
-        return {
-            action: "shepherd",
-            stackMergeable,
-            instructions,
-        };
+        const sessions = open.filter((item) => item.action !== "cancel");
+        appendAutonomousInstructions(instructions, sessions);
+        const action = appendStackRerunInstruction(instructions, sessions, "After the selected one-PR sessions, rerun this same `--stack` selector.");
+        return { action, stackMergeable, instructions };
     }
     return retargetWaitPlan(open[0]);
 }

package/bin/commands/poll-summary.mjs

@@ -2,10 +2,12 @@
 import { loadConfig } from "../config/load.mjs";
 import { ShepherdError } from "../exit-codes.mjs";
 import { getRepoInfo } from "../github/client.mjs";
+import { getGithubTransport } from "../github/transport.mjs";
 import { withApiTelemetryScope, summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { fetchPollSummary } from "../github/poll-summary.mjs";
+import { writeStackHandoffs } from "../github/stack-handoff.mjs";
 import { sleep } from "../util/sleep.mjs";
-import { aggregateQuotaWarning, quotaPollIntervalMs } from "./poll-quota.mjs";
+import { aggregateQuotaWarning, carryQuotaWarning, 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";
@@ -14,12 +16,38 @@ import { applyStackStallGuard } from "./stack-stall.mjs";
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const TIMER_DRIFT_TOLERANCE_MS = 500;
 export function runPollSummary(opts) {
-    return withApiTelemetryScope(async () => attachUsage(await runPollSummaryCore(opts), opts.merge));
+    return withApiTelemetryScope(async () => {
+        const tick = await readPollSummaryTick(opts);
+        await handOffRoutedLayers(tick);
+        return attachUsage(tick.result, opts.merge);
+    });
 }
 export function runAggregatePoll(opts) {
     return withApiTelemetryScope(() => runAggregatePollCore(opts));
 }
 async function runPollSummaryCore(opts) {
+    return (await readPollSummaryTick(opts)).result;
+}
+/**
+ * The stack tick that routes owned layers to their one-PR sessions hands each
+ * routed layer this tick's read of it, so that session's first read is free.
+ * Every other tick clears earlier handoffs: a newer read supersedes them.
+ */
+async function handOffRoutedLayers(tick) {
+    const { result, handoffSource } = tick;
+    if (!handoffSource)
+        return;
+    const routing = result.nextAction === "shepherd" && result.reason !== "waiting";
+    const routed = routing
+        ? result.prs
+            .filter((item) => item.state === "OPEN" &&
+            item.pollCommand !== undefined &&
+            !["cancel", "wait", "escalate"].includes(item.action))
+            .map((item) => item.pr)
+        : [];
+    await writeStackHandoffs(handoffSource, routed, tick.repo);
+}
+async function readPollSummaryTick(opts) {
     const repo = opts.targetRepository ?? (await getRepoInfo());
     const fetched = await fetchPollSummary(opts, repo);
     const allTerminal = fetched.prs.every((item) => item.action === "cancel");
@@ -33,7 +61,8 @@ async function runPollSummaryCore(opts) {
         ...(fetched.stackAncestry?.length && { stackAncestry: fetched.stackAncestry }),
         ...(fetched.allowedMergeMethods && { allowedMergeMethods: fetched.allowedMergeMethods }),
     }, opts.merge === true);
-    return applyStackStallGuard(planned, repo, opts.stallTimeoutSeconds ?? loadConfig().iterate.stallTimeoutMinutes * 60);
+    const result = await applyStackStallGuard(planned, repo, opts.stallTimeoutSeconds ?? loadConfig().iterate.stallTimeoutMinutes * 60);
+    return { result, repo, ...(fetched.handoffSource && { handoffSource: fetched.handoffSource }) };
 }
 async function runAggregatePollCore(opts) {
     const intervalMs = Math.min(opts.intervalSeconds * 1000, MAX_TIMER_MS);
@@ -44,16 +73,19 @@ async function runAggregatePollCore(opts) {
     let tick = 0;
     let debounceUntil = null;
     let last;
+    let lastTick;
     let lastStatusSignature = null;
     const rateLimitRetry = createUntilTerminalRateLimitRetry();
     let pendingQuotaWarning;
     while (true) {
         tick += 1;
         try {
-            last = await runPollSummaryCore(opts);
+            lastTick = await readPollSummaryTick(opts);
+            last = lastTick.result;
             rateLimitRetry.reset();
         }
         catch (error) {
+            pendingQuotaWarning = carryQuotaWarning(pendingQuotaWarning, undefined);
             if (last?.selection.kind === "stack" && isMissingStack(error)) {
                 const explicit = await runPollSummaryCore({
                     ...opts,
@@ -62,8 +94,7 @@ async function runAggregatePollCore(opts) {
                 });
                 if (explicit.prs.every((item) => item.state === "MERGED")) {
                     const warning = await aggregateQuotaWarning(explicit, quotaBands, opts.intervalSeconds);
-                    if (warning)
-                        pendingQuotaWarning = warning;
+                    pendingQuotaWarning = carryQuotaWarning(pendingQuotaWarning, warning);
                     return attachUsage({
                         ...explicit,
                         selection: last.selection,
@@ -110,8 +141,7 @@ async function runAggregatePollCore(opts) {
             ? last.nextAction === "shepherd" && last.reason !== "waiting"
             : last.prs.some((item) => item.action === "fix_code");
         const warning = await aggregateQuotaWarning(last, quotaBands, opts.intervalSeconds);
-        if (warning)
-            pendingQuotaWarning = warning;
+        pendingQuotaWarning = carryQuotaWarning(pendingQuotaWarning, warning);
         if (allTerminal) {
             return attachUsage({
                 ...last,
@@ -127,19 +157,14 @@ async function runAggregatePollCore(opts) {
             }, opts.merge);
         }
         if (hasFix) {
-            if (debounceMs === 0)
-                return attachUsage({
-                    ...last,
-                    reason: "actionable",
-                    ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                }, opts.merge);
-            debounceUntil ??= Date.now() + debounceMs;
-            if (Date.now() >= debounceUntil)
+            if (debounceMs === 0 || Date.now() >= (debounceUntil ??= Date.now() + debounceMs)) {
+                await handOffRoutedLayers(lastTick);
                 return attachUsage({
                     ...last,
                     reason: "actionable",
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
                 }, opts.merge);
+            }
         }
         else {
             debounceUntil = null;
@@ -150,7 +175,7 @@ async function runAggregatePollCore(opts) {
         const elapsedMs = Date.now() - start;
         const sleepMs = debounceUntil
             ? Math.min(intervalMs, Math.max(debounceUntil - Date.now(), 0))
-            : quotaPollIntervalMs(quotaBands, summarizeApiTelemetry(), intervalMs, MAX_TIMER_MS);
+            : quotaPollIntervalMs(quotaBands, summarizeApiTelemetry(), intervalMs, MAX_TIMER_MS, getGithubTransport());
         if (!opts.untilTerminal && debounceUntil === null) {
             const remainingMs = timeoutMs - elapsedMs;
             if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {

package/bin/commands/poll.d.mts

@@ -7,5 +7,4 @@ export interface PollCommandOptions extends IterateCommandOptions {
     quietStatus?: boolean;
     untilTerminal?: boolean;
 }
-/** @deprecated Hidden implementation for the legacy `poll` alias. */
 export declare function runPoll(opts: PollCommandOptions): Promise<IterateResult>;

package/bin/commands/poll.mjs

@@ -2,18 +2,14 @@ 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 { quotaPollIntervalMs } from "./poll-quota.mjs";
+import { carryQuotaWarning, 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";
-function noteRuleAutoResolve(result) {
-    if (result.ruleAutoResolve?.summary)
-        process.stderr.write(`${result.ruleAutoResolve.summary}\n`);
-}
+import { writeDebounceProgress, writeRuleAutoResolveProgress, writeWaitProgress, } from "./poll-progress.mjs";
+import { getGithubTransport } from "../github/transport.mjs";
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const TIMER_DRIFT_TOLERANCE_MS = 500;
-/** @deprecated Hidden implementation for the legacy `poll` alias. */
 export function runPoll(opts) {
     return withPollApiUsage(() => runPollCore(opts), opts.untilTerminal === true, opts.intervalSeconds / 60);
 }
@@ -32,7 +28,6 @@ async function runPollCore(opts) {
     const untilTerminal = untilTerminalOpt === true;
     let lastWaitSignature = null;
     let pendingQuotaWarning;
-    // Pin the PR resolved by the first tick; branch inference only matches OPEN PRs.
     let prNumber = opts.prNumber;
     let debounceUntil = null;
     const rateLimitRetry = createUntilTerminalRateLimitRetry();
@@ -42,7 +37,6 @@ async function runPollCore(opts) {
         const remainingBefore = untilTerminal
             ? Number.POSITIVE_INFINITY
             : timeoutMs - (Date.now() - start);
-        // Cache only internal continuation ticks; returned ticks must fetch BatchPr.
         const allowCache = debounceUntil === null && remainingBefore + TIMER_DRIFT_TOLERANCE_MS >= intervalMs;
         const iterateTick = (fingerprintCache) => runIterate({
             ...iterateOpts,
@@ -75,14 +69,12 @@ async function runPollCore(opts) {
         };
         lastResult = await runTick(allowCache);
         prNumber ??= lastResult.pr;
-        if (lastResult.quotaWarning !== undefined)
-            pendingQuotaWarning = lastResult.quotaWarning;
+        pendingQuotaWarning = carryQuotaWarning(pendingQuotaWarning, lastResult.quotaWarning);
         const refreshIfReturning = async () => {
             if (lastResult?.fingerprintReused !== true)
                 return;
             lastResult = await runTick(false);
-            if (lastResult.quotaWarning !== undefined)
-                pendingQuotaWarning = lastResult.quotaWarning;
+            pendingQuotaWarning = carryQuotaWarning(pendingQuotaWarning, lastResult.quotaWarning);
         };
         if (untilTerminal &&
             pendingQuotaWarning !== undefined &&
@@ -92,7 +84,7 @@ async function runPollCore(opts) {
             if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
                 debounceUntil ??= Date.now() + debounceMs;
                 const remainingMs = Math.max(debounceUntil - Date.now(), 0);
-                noteRuleAutoResolve(lastResult);
+                writeRuleAutoResolveProgress(lastResult);
                 writeDebounceProgress(tick, Date.now() - start, remainingMs);
                 await sleep(Math.min(intervalMs, remainingMs));
                 continue;
@@ -110,7 +102,7 @@ async function runPollCore(opts) {
             if (pendingQuotaWarning === undefined)
                 debounceUntil = null;
             const elapsedMs = Date.now() - start;
-            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS);
+            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS, getGithubTransport());
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
                 if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
@@ -127,7 +119,7 @@ async function runPollCore(opts) {
                 verbose,
                 lastWaitSignature,
             });
-            noteRuleAutoResolve(lastResult);
+            writeRuleAutoResolveProgress(lastResult);
             await sleep(sleepMs);
             continue;
         }
@@ -136,7 +128,7 @@ async function runPollCore(opts) {
             !pastDebounce) {
             debounceUntil = null;
             const elapsedMs = Date.now() - start;
-            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS);
+            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS, getGithubTransport());
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
                 if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
@@ -144,12 +136,12 @@ async function runPollCore(opts) {
                     break;
                 }
             }
-            noteRuleAutoResolve(lastResult);
+            writeRuleAutoResolveProgress(lastResult);
             await sleep(sleepMs);
             continue;
         }
         if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
-            noteRuleAutoResolve(lastResult);
+            writeRuleAutoResolveProgress(lastResult);
             debounceUntil ??= Date.now() + debounceMs;
             const remainingMs = debounceUntil - Date.now();
             if (remainingMs > 0) {

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

@@ -1,7 +1,8 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
 import type { ApiUsage, GraphqlQuotaWarning } from "../types.mts";
+import type { GithubTransport } from "../github/transport.mts";
 /** Claim GraphQL and REST core warnings separately, then present one result. */
 export declare function selectQuotaWarning(key: {
     owner: string;
     repo: string;
-}, bands: GraphqlQuotaWarningBand[], usage: ApiUsage, persist: boolean): Promise<GraphqlQuotaWarning | undefined>;
+}, bands: GraphqlQuotaWarningBand[], usage: ApiUsage, persist: boolean, transport?: Exclude<GithubTransport, "auto">): Promise<GraphqlQuotaWarning | undefined>;