pr-shepherd 0.52.0 → 0.53.0

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

@@ -1,65 +1,57 @@
 /* eslint-disable max-lines */
 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";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
 export function withPollSummaryInstructions(result, mergeRequested) {
+    return planPollSummary(result, mergeRequested).result;
+}
+/** The projected summary, plus the idle layers when the stack plan can only wait on them. */
+export function planPollSummary(result, mergeRequested) {
     if (result.selection.kind !== "stack") {
-        return { ...result, instructions: explicitInstructions(result) };
+        return { result: { ...result, instructions: explicitInstructions(result) } };
     }
-    const prs = [...result.prs].sort((left, right) => position(left) - position(right));
+    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" && (!isReady(item) || staleChildren.has(item.pr)));
-    const blocked = prs.map((item) => firstUnready && item.state === "OPEN" && position(item) > position(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"),
-            }),
-        }
-        : item.state === "OPEN" &&
-            (!isReady(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);
@@ -68,50 +60,45 @@ export function withPollSummaryInstructions(result, mergeRequested) {
         instructions.push(buildQuotaAwareContinuation(result.quotaWarning, `${instructions.length + 1}. After completing the stack action,`));
     }
     return {
-        ...projected,
-        reason: planned.action === "cancel"
-            ? "all_terminal"
-            : planned.waiting
-                ? result.reason === "timeout"
-                    ? "timeout"
-                    : "waiting"
-                : "actionable",
-        stackMergeable: planned.stackMergeable,
-        nextAction: planned.action,
-        instructions,
+        result: {
+            ...projected,
+            reason: planned.action === "cancel"
+                ? "all_terminal"
+                : planned.waiting
+                    ? result.reason === "timeout"
+                        ? "timeout"
+                        : "waiting"
+                    : "actionable",
+            stackMergeable: planned.stackMergeable,
+            nextAction: planned.action,
+            instructions,
+        },
+        ...(planned.idle && { idle: planned.idle }),
     };
 }
 function planStack(result, mergeRequested) {
     const open = result.prs.filter((item) => item.state === "OPEN");
-    const lastOpen = open.at(-1);
-    const closedDependencyPr = result.prs.find((item) => item.state === "CLOSED" && lastOpen && position(item) < position(lastOpen));
-    const unverifiedLayer = result.prs.find((item) => item.state !== "OPEN" && item.state !== "MERGED");
     const gaps = result.stackAncestry ?? [];
-    const stackMergeable = gaps.length === 0 && open.every(isReady);
-    const candidates = open.filter((item) => !isReady(item) || gaps.some((gap) => gap.childPr === item.pr));
-    const autonomousCandidates = candidates.filter((item) => item.action !== "escalate");
-    const runnableCandidates = autonomousCandidates.filter((item) => item.pollCommand);
-    const missingCommands = autonomousCandidates.filter((item) => !item.pollCommand);
-    const escalated = result.prs.filter((item) => item.action === "escalate");
-    if (closedDependencyPr || unverifiedLayer || escalated.length > 0) {
+    const staleChildren = new Set(gaps.map((gap) => gap.childPr));
+    const stackMergeable = gaps.length === 0 && open.every(isStackLayerReady);
+    const work = splitStackWork(open.filter((item) => (!isStackLayerReady(item) || staleChildren.has(item.pr)) && item.action !== "escalate"), staleChildren);
+    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 = planPrefixDrain(result, mergeRequested);
+    if (drain)
+        return drain;
+    const handoffs = findHumanHandoffs(result);
+    if (handoffs) {
         const instructions = [];
         appendAutonomousInstructions(instructions, runnableCandidates);
-        const stop = runnableCandidates.length === 0;
-        if (closedDependencyPr) {
-            instructions.push(`${instructions.length + 1}. PR #${closedDependencyPr.pr} was closed without merging below an open layer. ${stop ? "Stop and ask" : "After autonomous shepherding, ask"} the stack owner whether to restore that dependency or rebuild the upper branches.`);
-        }
-        if (unverifiedLayer && unverifiedLayer.pr !== closedDependencyPr?.pr) {
-            instructions.push(`${instructions.length + 1}. PR #${unverifiedLayer.pr} has state \`${unverifiedLayer.state}\` rather than open or merged. ${stop ? "Stop and ask" : "After autonomous shepherding, ask"} the stack owner to reconcile this layer before declaring the stack complete.`);
-        }
-        for (const item of escalated) {
-            if (item.pr === closedDependencyPr?.pr || item.pr === unverifiedLayer?.pr)
-                continue;
-            instructions.push(`${instructions.length + 1}. PR #${item.pr} requires human action (${item.reasons.join(", ")}). ${stop ? "Stop for that decision." : "Keep shepherding other PRs before the handoff."}`);
-        }
+        appendMarkReadyInstructions(instructions, work.markReady);
+        const stop = !agentWork;
+        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 (runnableCandidates.length > 0) {
+        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.`);
         }
         return { action: stop ? "escalate" : "shepherd", stackMergeable: false, instructions };
@@ -127,20 +114,20 @@ function planStack(result, mergeRequested) {
         if (missingCommands.length > 0) {
             const instructions = [];
             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. ${runnableCandidates.length === 0 ? "Stop and ask" : "After autonomous shepherding, ask"} for direction.`);
+                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.`);
             }
-            if (runnableCandidates.length > 0) {
+            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.`);
             }
-            return {
-                action: runnableCandidates.length > 0 ? "shepherd" : "escalate",
-                stackMergeable: false,
-                instructions,
-            };
+            return { action: agentWork ? "shepherd" : "escalate", stackMergeable: false, instructions };
         }
+        if (!agentWork)
+            return idleWaitPlan(work.idle);
         const instructions = [];
-        appendAutonomousInstructions(instructions, autonomousCandidates);
+        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 };
     }
@@ -171,49 +158,11 @@ function planStack(result, mergeRequested) {
             instructions,
         };
     }
-    const stackNumber = result.selection.kind === "stack" ? result.selection.stackNumber : 0;
-    return {
-        action: "merge",
-        stackMergeable: true,
-        instructions: [
-            "1. Check `gh stack merge --help`. If the `gh-stack` extension is unavailable, run `gh extension install github/gh-stack`, then rerun this same `--stack --merge` selector before merging.",
-            `2. Stack #${stackNumber} in \`${result.repo}\` is mergeable through PR #${open.at(-1).pr}. Run \`GH_REPO=${result.repo} gh stack merge --yes --squash ${stackNumber}\` to merge the whole native stack or enqueue it when the base uses a merge queue.`,
-            "3. After the merge attempt, rerun this same `--stack --merge` selector until every layer is merged (`CANCEL`); shepherd any layer that GitHub rejects or ejects.",
-        ],
-    };
+    return retargetWaitPlan(open[0]);
 }
 function closedDependency(items, pr) {
     const open = items.filter((item) => item.state === "OPEN");
     const lastOpen = open.at(-1);
     return Boolean(lastOpen &&
-        items.some((item) => item.pr === pr && item.state === "CLOSED" && position(item) < position(lastOpen)));
-}
-function appendAutonomousInstructions(instructions, candidates) {
-    if (candidates.length === 0)
-        return;
-    instructions.push(`${instructions.length + 1}. Start or delegate the relevant one-PR sessions below; review and CI work on separate layers can proceed concurrently.`);
-    for (const item of candidates) {
-        instructions.push(item.pollCommand
-            ? `${instructions.length + 1}. Run \`${item.pollCommand}\` for PR #${item.pr}${item.blockedByPr ? ` (stack-blocked by PR #${item.blockedByPr})` : ""}${item.queueRemoval ? `; GitHub removed it from the merge queue (${item.queueRemoval.reason ?? "unknown reason"})` : ""}.`
-            : `${instructions.length + 1}. PR #${item.pr} needs a one-PR Shepherd session, but no command was available.`);
-    }
-    instructions.push(`${instructions.length + 1}. Keep upper draft PRs in draft until every lower layer has completed Shepherd READY.`);
-}
-function isReady(item) {
-    return (item.state === "OPEN" &&
-        item.stack !== undefined &&
-        item.readyReceipt === true &&
-        !item.isDraft &&
-        !item.queueRemoval &&
-        item.mergeable !== "CONFLICTING" &&
-        item.mergeStateStatus !== "DIRTY" &&
-        (item.isInMergeQueue || item.mergeable === "MERGEABLE") &&
-        (item.isInMergeQueue ||
-            !["DIRTY", "BEHIND", "UNKNOWN", "BLOCKED", "HAS_HOOKS"].includes(item.mergeStateStatus)) &&
-        (item.checks?.failing ?? 0) === 0 &&
-        (item.isInMergeQueue || (item.checks?.inProgress ?? 0) === 0) &&
-        (item.review?.actionable ?? 0) === 0);
-}
-function position(item) {
-    return item.stack?.position ?? Number.MAX_SAFE_INTEGER;
+        items.some((item) => item.pr === pr && item.state === "CLOSED" && stackPosition(item) < stackPosition(lastOpen)));
 }

package/bin/commands/poll-summary.mjs

@@ -6,8 +6,9 @@ import { withApiTelemetryScope, summarizeApiTelemetry } from "../github/api-tele
 import { fetchPollSummary } from "../github/poll-summary.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { aggregateQuotaWarning, graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs, } from "./poll-quota.mjs";
-import { withPollSummaryInstructions } from "./poll-summary-instructions.mjs";
+import { planPollSummary, withPollSummaryInstructions } from "./poll-summary-instructions.mjs";
 import { summaryStatusSignature } from "./poll-summary-signature.mjs";
+import { applyStackStallGuard } from "./stack-stall.mjs";
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const TIMER_DRIFT_TOLERANCE_MS = 500;
 export function runPollSummary(opts) {
@@ -21,7 +22,7 @@ async function runPollSummaryCore(opts) {
     const fetched = await fetchPollSummary(opts, repo);
     const allTerminal = fetched.prs.every((item) => item.action === "cancel");
     const actionable = fetched.prs.some((item) => item.action !== "wait" && item.action !== "cancel");
-    return withPollSummaryInstructions({
+    const planned = planPollSummary({
         mode: "summary",
         repo: `${repo.owner}/${repo.name}`,
         selection: fetched.selection,
@@ -29,6 +30,7 @@ async function runPollSummaryCore(opts) {
         prs: fetched.prs,
         ...(fetched.stackAncestry?.length && { stackAncestry: fetched.stackAncestry }),
     }, opts.merge === true);
+    return applyStackStallGuard(planned, repo, opts.stallTimeoutSeconds ?? loadConfig().iterate.stallTimeoutMinutes * 60);
 }
 async function runAggregatePollCore(opts) {
     const intervalMs = Math.min(opts.intervalSeconds * 1000, MAX_TIMER_MS);

package/bin/commands/ready-delay.d.mts

@@ -2,8 +2,10 @@
  * Ready-delay state machine for the shepherd iterate loop.
  *
  * When all READY conditions hold, shepherd writes a `ready-since.txt` marker
- * to the state dir. The loop continues until the PR has been READY for
- * `readyDelaySeconds` consecutively. Any not-READY result resets the timer.
+ * bound to the PR head to the state dir. The loop continues until the PR has
+ * been READY on that head for `readyDelaySeconds` consecutively. Any not-READY
+ * result, or a different head, resets the timer. An elapsed marker stays until
+ * the caller consumes it with `clearReadyDelay`.
  */
 interface ReadyDelayState {
     isReady: boolean;
@@ -25,7 +27,10 @@ interface ReadyDelayState {
  * When `shouldCancel == true`, the formatter tells loop-capable agents to cancel
  * the loop and tells one-shot agents to stop.
  */
-export declare function updateReadyDelay(prNumber: number, isReady: boolean, readyDelaySeconds: number, owner: string, repo: string, options?: {
-    retainElapsed?: boolean;
+export declare function updateReadyDelay(prNumber: number, isReady: boolean, readyDelaySeconds: number, owner: string, repo: string, options: {
+    headSha: string;
+    alreadyElapsed?: boolean;
 }): Promise<ReadyDelayState>;
+/** Delete the ready-delay marker once an elapsed delay has been consumed. */
+export declare function clearReadyDelay(prNumber: number, owner: string, repo: string): Promise<void>;
 export {};

package/bin/commands/ready-delay.mjs

@@ -2,8 +2,10 @@
  * Ready-delay state machine for the shepherd iterate loop.
  *
  * When all READY conditions hold, shepherd writes a `ready-since.txt` marker
- * to the state dir. The loop continues until the PR has been READY for
- * `readyDelaySeconds` consecutively. Any not-READY result resets the timer.
+ * bound to the PR head to the state dir. The loop continues until the PR has
+ * been READY on that head for `readyDelaySeconds` consecutively. Any not-READY
+ * result, or a different head, resets the timer. An elapsed marker stays until
+ * the caller consumes it with `clearReadyDelay`.
  */
 import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -18,47 +20,59 @@ import { resolvePrStatePath } from "../state/base.mjs";
  * When `shouldCancel == true`, the formatter tells loop-capable agents to cancel
  * the loop and tells one-shot agents to stop.
  */
-export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, owner, repo, options = {}) {
+export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, owner, repo, options) {
     const markerPath = readySincePath(prNumber, owner, repo);
     if (!isReady) {
         // Reset the timer.
         await safeUnlink(markerPath);
         return { isReady: false, shouldCancel: false, remainingSeconds: readyDelaySeconds };
     }
+    // Durable evidence (a current READY receipt) already proves the delay
+    // elapsed for this exact state, so a re-poll must not start a fresh timer.
+    if (options.alreadyElapsed) {
+        return { isReady: true, shouldCancel: true, remainingSeconds: 0 };
+    }
     // PR is READY — check or create the marker.
     const now = Math.floor(Date.now() / 1000);
-    let readySince;
-    try {
-        const raw = await readFile(markerPath, "utf8");
-        readySince = parseInt(raw.trim(), 10);
-        // Reset if the stored value is not finite or is in the future (clock skew,
-        // corrupted file, or manual edit). A future timestamp would produce a
-        // negative elapsed value and an inflated remainingSeconds.
-        if (!Number.isFinite(readySince) || readySince > now) {
-            readySince = now;
-            await safeWriteFile(markerPath, String(now));
-        }
-    }
-    catch {
-        // Marker doesn't exist yet — create it.
+    let readySince = await readReadySince(markerPath, options.headSha);
+    // Reset if the marker is missing, names another head, is not finite, or is
+    // in the future (clock skew, corrupted file, or manual edit). A future
+    // timestamp would produce a negative elapsed value and an inflated
+    // remainingSeconds.
+    if (readySince === null || readySince > now) {
         readySince = now;
-        await safeWriteFile(markerPath, String(now));
+        await safeWriteFile(markerPath, `${now} ${options.headSha}`);
     }
     const elapsed = now - readySince;
     const remaining = readyDelaySeconds - elapsed;
     if (remaining <= 0) {
-        if (!options.retainElapsed)
-            await safeUnlink(markerPath);
         return { isReady: true, shouldCancel: true, remainingSeconds: 0 };
     }
     return { isReady: true, shouldCancel: false, remainingSeconds: remaining };
 }
+/** Delete the ready-delay marker once an elapsed delay has been consumed. */
+export async function clearReadyDelay(prNumber, owner, repo) {
+    await safeUnlink(readySincePath(prNumber, owner, repo));
+}
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function readySincePath(pr, owner, repo) {
     return resolvePrStatePath({ owner, repo, pr }, "ready-since.txt");
 }
+/** The marker's start time, or null when it is missing, malformed, or bound to another head. */
+async function readReadySince(path, headSha) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const [since, head] = raw.trim().split(" ");
+    const readySince = Number(since);
+    return head === headSha && Number.isSafeInteger(readySince) ? readySince : null;
+}
 async function safeUnlink(path) {
     try {
         await unlink(path);

package/bin/commands/shepherd-journal.mjs

@@ -1,3 +1,4 @@
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
 export const SHEPHERD_JOURNAL_SECTION = "Shepherd Journal";
 export const SHEPHERD_JOURNAL_SECTION_PATTERN = /^##\s+Shepherd\s+Journal$/;
 export const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
@@ -12,5 +13,7 @@ export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `##
  * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
  */
 export function buildShepherdJournalInstruction(prReference) {
-    return `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`pr-shepherd apply journal ${prReference} '- <decision>'\`. See "Shepherd Journal" in the pr-shepherd skill for citation conventions.`;
+    // Single-quote the placeholder so a substituted decision stays literal in the shell.
+    const command = `${buildPrShepherdCommand(["apply", "journal", String(prReference)]).text} '- <decision>'`;
+    return `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`${command}\`. See "Shepherd Journal" in the pr-shepherd skill for citation conventions.`;
 }

package/bin/commands/stack-drain.d.mts

@@ -0,0 +1,35 @@
+import type { PollSummaryItem, PollSummaryResult, StackNextAction } from "../types.mts";
+export interface StackPlan {
+    action: StackNextAction;
+    stackMergeable: boolean;
+    waiting?: boolean;
+    /** Set only by {@link idleWaitPlan}: the layers whose one-PR probes could only report waiting. */
+    idle?: PollSummaryItem[];
+    instructions: string[];
+}
+/**
+ * Merge the ready prefix by its highest PR number. `gh stack merge <n>` tries a
+ * stack number first, but stack numbers come from the repository's issue and
+ * pull request sequence, so a PR number never names a stack.
+ */
+export declare function planPrefixDrain(result: PollSummaryResult, mergeRequested: boolean): StackPlan | undefined;
+/**
+ * A merge-requested, fully ready stack whose bottom open layer still targets
+ * the merged layer below it until GitHub retargets it onto the stack base.
+ */
+export declare function retargetWaitPlan(first: PollSummaryItem): StackPlan;
+/** Every remaining layer only waits on CI or merge state. */
+export declare function idleWaitPlan(idle: PollSummaryItem[]): StackPlan;
+export declare function describeIdleLayers(idle: PollSummaryItem[]): string;
+export declare function appendAutonomousInstructions(instructions: string[], candidates: PollSummaryItem[]): void;
+/** Layers only a human can resolve: a closed dependency, an unverified state, or an escalation. */
+export interface HumanHandoffs {
+    closedDependency?: PollSummaryItem;
+    unverified?: PollSummaryItem;
+    escalated: PollSummaryItem[];
+}
+export declare function findHumanHandoffs(result: PollSummaryResult): HumanHandoffs | undefined;
+/** Name every human handoff; `stop` when no autonomous work precedes it. */
+export declare function appendHumanHandoffInstructions(instructions: string[], { closedDependency, unverified, escalated }: HumanHandoffs, stop: boolean): void;
+export declare function isStackLayerReady(item: PollSummaryItem): boolean;
+export declare function stackPosition(item: PollSummaryItem): number;

package/bin/commands/stack-drain.mjs

@@ -0,0 +1,138 @@
+import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
+import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
+/**
+ * Highest open layer such that it and every open layer below it are ready to
+ * merge together. `gh stack merge <PR>` lands that PR and every unmerged layer
+ * below it. A merge queue accepts the same prefix and evaluates each layer
+ * from the bottom; a failure ejects that layer and those above it.
+ */
+function readyPrefixTop(result) {
+    const layers = [...result.prs].sort((left, right) => stackPosition(left) - stackPosition(right));
+    if (layers.some((item) => item.state === "OPEN" && item.isInMergeQueue))
+        return undefined;
+    const open = layers.filter((item) => item.state === "OPEN");
+    const bottom = open[0];
+    if (!bottom || !isStackLayer(bottom) || bottom.state !== "OPEN")
+        return undefined;
+    if (bottom.baseRefName !== bottom.stack.baseRefName)
+        return undefined;
+    const stale = new Set((result.stackAncestry ?? []).map((gap) => gap.childPr));
+    let top;
+    for (const item of open) {
+        if (!isStackLayer(item))
+            break;
+        if (item.action === "escalate" || !isStackLayerReady(item) || stale.has(item.pr))
+            break;
+        if (layers.some((layer) => layer.state === "CLOSED" && stackPosition(layer) < stackPosition(item)))
+            break;
+        top = item;
+    }
+    return top;
+}
+/**
+ * Merge the ready prefix by its highest PR number. `gh stack merge <n>` tries a
+ * stack number first, but stack numbers come from the repository's issue and
+ * pull request sequence, so a PR number never names a stack.
+ */
+export function planPrefixDrain(result, mergeRequested) {
+    if (!mergeRequested)
+        return undefined;
+    const top = readyPrefixTop(result);
+    if (!top)
+        return undefined;
+    const gaps = result.stackAncestry ?? [];
+    const staleChildren = new Set(gaps.map((gap) => gap.childPr));
+    const open = result.prs
+        .filter((item) => item.state === "OPEN")
+        .sort((left, right) => stackPosition(left) - stackPosition(right));
+    const above = splitStackWork(open.filter((item) => stackPosition(item) > stackPosition(top) &&
+        item.action !== "escalate" &&
+        (!isStackLayerReady(item) || staleChildren.has(item.pr))), staleChildren);
+    const span = open[0]?.pr === top.pr ? "that layer alone" : `PR #${top.pr} and every unmerged layer below it`;
+    const instructions = [
+        `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes --squash\` to merge ${span}. When the base uses a merge queue, the same command queues that prefix together and GitHub evaluates each layer from the bottom; a failure ejects that layer and the layers above it. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\` first.`,
+    ];
+    appendAutonomousInstructions(instructions, above.sessions);
+    appendMarkReadyInstructions(instructions, above.markReady);
+    const handoffs = findHumanHandoffs(result);
+    if (handoffs)
+        appendHumanHandoffInstructions(instructions, handoffs, false);
+    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun this same \`--stack --merge\` selector; GitHub retargets the next layer onto \`${top.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
+    return {
+        action: "merge",
+        stackMergeable: gaps.length === 0 && open.every(isStackLayerReady),
+        instructions,
+    };
+}
+/**
+ * A merge-requested, fully ready stack whose bottom open layer still targets
+ * the merged layer below it until GitHub retargets it onto the stack base.
+ */
+export function retargetWaitPlan(first) {
+    return {
+        action: "wait",
+        stackMergeable: true,
+        waiting: true,
+        instructions: [
+            `1. PR #${first.pr} still targets \`${first.baseRefName}\` rather than \`${first.stack?.baseRefName}\`; wait for GitHub to retarget it before merging. Recheck at the configured polling cadence.`,
+        ],
+    };
+}
+/** Every remaining layer only waits on CI or merge state. */
+export function idleWaitPlan(idle) {
+    return {
+        action: "wait",
+        stackMergeable: false,
+        waiting: true,
+        idle,
+        instructions: [
+            `1. No one-PR session can advance the stack yet: ${describeIdleLayers(idle)}. Recheck at the configured polling cadence.`,
+        ],
+    };
+}
+export function describeIdleLayers(idle) {
+    return idle.map((item) => `PR #${item.pr} (${item.reasons.join(", ")})`).join("; ");
+}
+export function appendAutonomousInstructions(instructions, candidates) {
+    if (candidates.length === 0)
+        return;
+    instructions.push(`${instructions.length + 1}. Start or delegate the relevant one-PR sessions below; review and CI work on separate layers can proceed concurrently.`);
+    for (const item of candidates) {
+        instructions.push(item.pollCommand
+            ? `${instructions.length + 1}. Run \`${item.pollCommand}\` for PR #${item.pr}${item.queueRemoval ? `; GitHub removed it from the merge queue (${item.queueRemoval.reason ?? "unknown reason"})` : ""}.`
+            : `${instructions.length + 1}. PR #${item.pr} needs a one-PR Shepherd session, but no command was available.`);
+    }
+}
+export function findHumanHandoffs(result) {
+    const lastOpen = result.prs.filter((item) => item.state === "OPEN").at(-1);
+    const closedDependency = result.prs.find((item) => item.state === "CLOSED" && lastOpen && stackPosition(item) < stackPosition(lastOpen));
+    const unverified = result.prs.find((item) => item.state !== "OPEN" && item.state !== "MERGED");
+    const escalated = result.prs.filter((item) => item.action === "escalate");
+    return closedDependency || unverified || escalated.length > 0
+        ? { closedDependency, unverified, escalated }
+        : undefined;
+}
+/** Name every human handoff; `stop` when no autonomous work precedes it. */
+export function appendHumanHandoffInstructions(instructions, { closedDependency, unverified, escalated }, stop) {
+    const ask = stop ? "Stop and ask" : "After autonomous shepherding, ask";
+    if (closedDependency) {
+        instructions.push(`${instructions.length + 1}. PR #${closedDependency.pr} was closed without merging below an open layer. ${ask} the stack owner whether to restore that dependency or rebuild the upper branches.`);
+    }
+    if (unverified && unverified.pr !== closedDependency?.pr) {
+        instructions.push(`${instructions.length + 1}. PR #${unverified.pr} has state \`${unverified.state}\` rather than open or merged. ${ask} the stack owner to reconcile this layer before declaring the stack complete.`);
+    }
+    for (const item of escalated) {
+        if (item.pr === closedDependency?.pr || item.pr === unverified?.pr)
+            continue;
+        instructions.push(`${instructions.length + 1}. PR #${item.pr} requires human action (${item.reasons.join(", ")}). ${stop ? "Stop for that decision." : "Keep shepherding other PRs before the handoff."}`);
+    }
+}
+export function isStackLayerReady(item) {
+    return item.stack !== undefined && stackLayerBlockReason(item) === undefined;
+}
+export function stackPosition(item) {
+    return item.stack?.position ?? Number.MAX_SAFE_INTEGER;
+}
+function isStackLayer(item) {
+    return item.stack !== undefined;
+}

package/bin/commands/stack-layer-readiness.d.mts

@@ -0,0 +1,6 @@
+import type { PollSummaryItem, StackLayerBlockReason } from "../types.mts";
+/**
+ * Why a native stack layer is not ready to merge, or undefined when it is.
+ * A draft is marked ready by its own session; this predicate does not gate that.
+ */
+export declare function stackLayerBlockReason(item: PollSummaryItem): StackLayerBlockReason | undefined;

package/bin/commands/stack-layer-readiness.mjs

@@ -0,0 +1,34 @@
+/**
+ * Why a native stack layer is not ready to merge, or undefined when it is.
+ * A draft is marked ready by its own session; this predicate does not gate that.
+ */
+export function stackLayerBlockReason(item) {
+    if (item.state !== "OPEN")
+        return "closed";
+    if (item.isDraft)
+        return "draft";
+    if (item.mergeable === "CONFLICTING" || item.mergeStateStatus === "DIRTY")
+        return "conflicting";
+    // A receipt only establishes readiness after a merge-queue removal once
+    // the one-PR session has observed and acknowledged that exact removal.
+    // The aggregate projection preserves an unacknowledged removal here, so
+    // the layer is not ready to merge.
+    if (item.queueRemoval)
+        return "queue-removal";
+    if ((item.checks?.failing ?? 0) > 0)
+        return "failing-checks";
+    if ((item.review?.actionable ?? 0) > 0)
+        return "review-work";
+    // Merge-group checks and the queue's own merge state supersede the source
+    // PR's while it is queued.
+    if (!item.isInMergeQueue) {
+        if ((item.checks?.inProgress ?? 0) > 0)
+            return "checks-in-progress";
+        if (item.mergeable !== "MERGEABLE" ||
+            ["BEHIND", "UNKNOWN", "BLOCKED", "HAS_HOOKS"].includes(item.mergeStateStatus))
+            return "merge-state";
+    }
+    // A layer that looks ready but has not completed its own one-PR receipt
+    // is not ready to merge.
+    return item.readyReceipt === true ? undefined : "no-ready-receipt";
+}