pr-shepherd 0.56.5 → 0.57.0

package/bin/commands/iterate/stall.d.mts

@@ -3,4 +3,8 @@ export declare function applyStallGuard(stallKey: {
     owner: string;
     repo: string;
     pr: number;
-}, stallTimeoutSeconds: number, headSha: string, base: IterateResultBase, prNumber: number, prospectiveResult: IterateResult, report: ShepherdReport, reviewSummaryIds: string[]): Promise<IterateResult>;
+}, stallTimeoutSeconds: number, headSha: string, base: IterateResultBase, prNumber: number, prospectiveResult: IterateResult, report: ShepherdReport, reviewSummaryIds: string[], stallDeadlineSink?: StallDeadlineSink): Promise<IterateResult>;
+/** Internal out-parameter: when the earliest unstarted check would trip the CI-start stall. */
+export interface StallDeadlineSink {
+    ciStartDeadlineSeconds?: number;
+}

package/bin/commands/iterate/stall.mjs

@@ -62,13 +62,14 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
         annotations,
     });
 }
-export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds) {
+export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds, stallDeadlineSink) {
     const prReference = formatPrUrl(report.repo, prNumber);
     const nowSeconds = Math.floor(Date.now() / 1000);
-    const stalledChecks = findCiStartStalledChecks(report.checks.inProgress, nowSeconds, {
-        stallTimeoutSeconds,
-        action: prospectiveResult.action,
-    });
+    const ciStartOpts = { stallTimeoutSeconds, action: prospectiveResult.action };
+    const stalledChecks = findCiStartStalledChecks(report.checks.inProgress, nowSeconds, ciStartOpts);
+    if (stallDeadlineSink) {
+        stallDeadlineSink.ciStartDeadlineSeconds = ciStartStallDeadline(report.checks.inProgress, nowSeconds, ciStartOpts);
+    }
     if (stalledChecks.length > 0) {
         const pending = pendingReviewCommandsFromResult(prospectiveResult);
         const stalledDuration = formatDurationApprox(Math.max(...stalledChecks.map((c) => c.ageSeconds)));
@@ -168,13 +169,24 @@ function stallStateUnavailable(base, prReference, prospectiveResult, reason) {
         },
     };
 }
-function findCiStartStalledChecks(checks, nowSeconds, opts) {
+function unstartedStallCandidates(checks, nowSeconds, opts) {
     if (opts.stallTimeoutSeconds <= 0 || opts.action !== "wait")
         return [];
     return checks
         .filter((c) => isUnstartedCheck(c))
         .map((c) => toAgentStalledCheck(c, nowSeconds))
-        .filter((c) => c.createdAtUnix !== undefined && c.ageSeconds >= opts.stallTimeoutSeconds);
+        .filter((c) => c.createdAtUnix !== undefined);
+}
+function findCiStartStalledChecks(checks, nowSeconds, opts) {
+    return unstartedStallCandidates(checks, nowSeconds, opts).filter((c) => c.ageSeconds >= opts.stallTimeoutSeconds);
+}
+/** Unix seconds at which the oldest unstarted check reaches the stall timeout, if any. */
+function ciStartStallDeadline(checks, nowSeconds, opts) {
+    const candidates = unstartedStallCandidates(checks, nowSeconds, opts);
+    if (candidates.length === 0)
+        return undefined;
+    const maxAge = Math.max(...candidates.map((c) => c.ageSeconds));
+    return nowSeconds - maxAge + opts.stallTimeoutSeconds;
 }
 function isUnstartedCheck(check) {
     if (check.source === "status_context")

package/bin/commands/iterate/thread-mutation-routing.d.mts

@@ -10,6 +10,7 @@ export interface ThreadMutationRouting {
 }
 export declare function threadHasAuthorizedMutation(thread: {
     id: string;
+    isResolved?: boolean;
     viewerCanReply?: boolean;
     viewerCanResolve?: boolean;
 }, replyThreadIds: ReadonlySet<string>, resolveThreadIds: ReadonlySet<string>): boolean;

package/bin/commands/iterate/thread-mutation-routing.mjs

@@ -1,6 +1,7 @@
 import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "../../comments/authors.mjs";
 import { threadEndedByShepherd } from "../../comments/marker.mjs";
 import { shouldResolveOtherHumanThread } from "../../comments/thread-resolve-policy.mjs";
+import { canGenerateGithubMutation } from "../../github/mutation-policy.mjs";
 function dedupeIds(ids) {
     return [...new Set(ids)];
 }
@@ -19,9 +20,10 @@ export function threadHasAuthorizedMutation(thread, replyThreadIds, resolveThrea
     const inResolve = resolveThreadIds.has(thread.id);
     if (!inReply && !inResolve)
         return false;
-    if (inReply && thread.viewerCanReply !== true)
+    if (inReply && !canGenerateGithubMutation(thread.viewerCanReply, "reply"))
         return false;
-    if (inResolve && thread.viewerCanResolve !== true)
+    if (inResolve &&
+        (thread.isResolved !== false || !canGenerateGithubMutation(thread.viewerCanResolve, "resolve")))
         return false;
     return true;
 }

package/bin/commands/iterate/unreported-required.mjs

@@ -4,6 +4,7 @@ import { readCiRetrigger, sameCiRetrigger, writeCiRetrigger } from "../../state/
 import { buildFixCompletionInstruction } from "./check-instructions.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
 import { buildNativeStackRebaseInstruction } from "./native-stack-rebase.mjs";
+import { getGithubTransport } from "../../github/transport.mjs";
 /** Rebase when the trunk or the PR base is behind; otherwise close and reopen once. */
 function decideUnreportedRequired(input) {
     if (input.behind)
@@ -29,12 +30,14 @@ function buildUnreportedRequiredInstructions(input) {
     if (!input.behind) {
         return [
             facts,
-            `Retrigger workflows once for this head with \`gh pr close ${input.pr} -R ${input.repo}\` then \`gh pr reopen ${input.pr} -R ${input.repo}\`.`,
+            getGithubTransport() === "rest"
+                ? `Retrigger workflows once for this head: run \`gh api --method PATCH repos/${input.repo}/pulls/${input.pr} -f state=closed\`, then run \`gh api --method PATCH repos/${input.repo}/pulls/${input.pr} -f state=open\`.`
+                : `Retrigger workflows once for this head with \`gh pr close ${input.pr} -R ${input.repo}\` then \`gh pr reopen ${input.pr} -R ${input.repo}\`.`,
             "If those checks are still missing on the next poll, investigate why the workflows did not start. Do not close the PR again. Shepherd escalates with `required-checks-unreported` when this remains the only blocker.",
         ];
     }
     const rebase = input.stackRebase
-        ? `${input.stackRebase} Then push the rewritten stack with \`gh stack push\`.`
+        ? `${input.stackRebase} Then push the rewritten stack${getGithubTransport() === "rest" ? " using the repository's stack-update procedure" : " with `gh stack push`"}.`
         : `Rebase onto \`${input.baseBranch}\` and push.`;
     return [
         facts,

package/bin/commands/mark-files-as-viewed.mjs

@@ -3,6 +3,8 @@ import { graphql, graphqlWithRateLimit, getCurrentPrNumber, getRepoInfo, } from
 import { paginateForward } from "../github/pagination.mjs";
 import { isRateLimitMessage, rateLimitFromError, rateLimitFromGraphQlResult, } from "../comments/rate-limit.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { githubOperation } from "../github/transport.mjs";
+import { UnsupportedRestOperationError } from "../github/unsupported-rest.mjs";
 const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr: Int!, $filesCursor: String) {
   _shepherdRateLimit: rateLimit {
     cost
@@ -34,6 +36,11 @@ const TEST_FILE_RE = /(^|\/)(tests?|__tests__|spec)(\/|$)|\.(test|spec)\.[cm]?[j
 const MARK_FILES_CHUNK_SIZE = 10;
 /** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */
 export async function runMarkFilesAsViewed(opts) {
+    return githubOperation("markFileAsViewed", () => runGraphqlMarkFilesAsViewed(opts), async () => {
+        throw new UnsupportedRestOperationError("markFileAsViewed");
+    }, { mutation: true });
+}
+async function runGraphqlMarkFilesAsViewed(opts) {
     const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (!prNumber) {

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