pr-shepherd 0.52.0 → 0.52.1

package/bin/commands/poll-progress.mjs

@@ -1,6 +1,9 @@
 function writeTickProgress(tick, elapsedSeconds, detail) {
     process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — ${detail}\n`);
 }
+function waitReason(result) {
+    return result.log.replace(/^WAIT: /, "");
+}
 function waitSignature(result) {
     const activity = result.activity ?? {
         commitCount: 0,
@@ -36,7 +39,10 @@ export function writeWaitProgress(opts) {
     const elapsedSeconds = Math.round(opts.elapsedMs / 1000);
     const sleepSeconds = Math.round(opts.sleepMs / 1000);
     if (!opts.quietStatus) {
-        writeTickProgress(opts.tick, elapsedSeconds, opts.verbose ? `sleeping ${sleepSeconds}s` : `still running; next tick in ${sleepSeconds}s`);
+        const reason = waitReason(opts.result);
+        writeTickProgress(opts.tick, elapsedSeconds, opts.verbose
+            ? `${reason} — sleeping ${sleepSeconds}s`
+            : `${reason}; next tick in ${sleepSeconds}s`);
         return opts.lastWaitSignature;
     }
     const signature = waitSignature(opts.result);

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

@@ -1,3 +1,8 @@
-import type { PollSummaryResult } from "../types.mts";
+import type { PollSummaryItem, PollSummaryResult } from "../types.mts";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
 export declare function withPollSummaryInstructions(result: PollSummaryResult, mergeRequested: boolean): PollSummaryResult;
+/** The projected summary, plus the idle layers when the stack plan can only wait on them. */
+export declare function planPollSummary(result: PollSummaryResult, mergeRequested: boolean): {
+    result: PollSummaryResult;
+    idle?: PollSummaryItem[];
+};

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

@@ -1,15 +1,21 @@
 /* eslint-disable max-lines */
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
+import { appendAutonomousInstructions, appendHumanHandoffInstructions, findHumanHandoffs, idleWaitPlan, isStackLayerReady, planBottomDrain, retargetWaitPlan, stackPosition, } from "./stack-drain.mjs";
+import { 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)
+    const firstUnready = prs.find((item) => item.state === "OPEN" && (!isStackLayerReady(item) || staleChildren.has(item.pr)));
+    const blocked = prs.map((item) => firstUnready && item.state === "OPEN" && stackPosition(item) > stackPosition(firstUnready)
         ? {
             ...item,
             ...(["cancel", "mark_ready", "merge"].includes(item.action) && {
@@ -21,10 +27,11 @@ export function withPollSummaryInstructions(result, mergeRequested) {
                 item.pollCommand && {
                 pollCommand: item.pollCommand.replace(" --until-terminal", " --timeout 1s --debounce 0s") +
                     (item.pollCommand.includes("--no-auto-mark-ready") ? "" : " --no-auto-mark-ready"),
+                pollProbe: true,
             }),
         }
         : item.state === "OPEN" &&
-            (!isReady(item) || staleChildren.has(item.pr)) &&
+            (!isStackLayerReady(item) || staleChildren.has(item.pr)) &&
             ["cancel", "merge"].includes(item.action)
             ? {
                 ...item,
@@ -68,50 +75,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 = planBottomDrain(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 +129,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 +173,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/poll.mjs

@@ -1,4 +1,5 @@
 import { runIterate } from "./iterate/index.mjs";
+import { heldByLowerLayer } from "./iterate/parent-first.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { withPollApiUsage } from "./poll-run.mjs";
 import { loadConfig } from "../config/load.mjs";
@@ -97,7 +98,8 @@ async function runPollCore(opts) {
             }
             break;
         }
-        if (lastResult.action === "wait" && !pastDebounce) {
+        // A held draft waits on another layer's session, so hand it straight back.
+        if (lastResult.action === "wait" && !pastDebounce && !heldByLowerLayer(lastResult)) {
             if (pendingQuotaWarning === undefined)
                 debounceUntil = null;
             const elapsedMs = Date.now() - start;

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 bottom layer by 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 planBottomDrain(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, or on a lower layer that does. */
+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,129 @@
+import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
+import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
+/**
+ * The lowest open layer when it can merge by itself: every layer below it
+ * merged, GitHub retargeted it onto the stack base, it holds a current READY
+ * receipt, and no layer is already in the merge queue.
+ */
+function drainableBottom(result) {
+    const layers = [...result.prs].sort((left, right) => stackPosition(left) - stackPosition(right));
+    const bottom = layers.find((item) => item.state !== "MERGED");
+    if (!bottom || !isStackLayer(bottom) || bottom.state !== "OPEN")
+        return undefined;
+    if (bottom.action === "escalate" || !isStackLayerReady(bottom))
+        return undefined;
+    if (bottom.baseRefName !== bottom.stack.baseRefName)
+        return undefined;
+    if (result.stackAncestry?.some((gap) => gap.childPr === bottom.pr))
+        return undefined;
+    if (layers.some((item) => item.state === "OPEN" && item.isInMergeQueue))
+        return undefined;
+    return bottom;
+}
+/**
+ * Merge the ready bottom layer by 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 planBottomDrain(result, mergeRequested) {
+    if (!mergeRequested)
+        return undefined;
+    const bottom = drainableBottom(result);
+    if (!bottom)
+        return undefined;
+    const gaps = result.stackAncestry ?? [];
+    const staleChildren = new Set(gaps.map((gap) => gap.childPr));
+    const open = result.prs.filter((item) => item.state === "OPEN");
+    const uppers = splitStackWork(open.filter((item) => item.pr !== bottom.pr &&
+        item.action !== "escalate" &&
+        (!isStackLayerReady(item) || staleChildren.has(item.pr))), staleChildren);
+    const instructions = [
+        `1. PR #${bottom.pr} is the bottom open layer of stack #${bottom.stack.number} in \`${result.repo}\` and is ready. Run \`GH_REPO=${result.repo} gh stack merge ${bottom.pr} --yes --squash\` to merge that layer alone, or to enqueue it when the base uses a merge queue. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\` first.`,
+    ];
+    appendAutonomousInstructions(instructions, uppers.sessions);
+    appendMarkReadyInstructions(instructions, uppers.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 \`${bottom.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, or on a lower layer that does. */
+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.blockedByPr ? `stack-blocked by PR #${item.blockedByPr}` : 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.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.`);
+}
+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,7 @@
+import type { PollSummaryItem, StackLayerBlockReason } from "../types.mts";
+/**
+ * Why a native stack layer does not yet let the layers above it advance, or undefined
+ * when it does. The stack selector and an upper draft's parent-first mark-ready check
+ * share this predicate so both always name the same blocking layer.
+ */
+export declare function stackLayerBlockReason(item: PollSummaryItem): StackLayerBlockReason | undefined;

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

@@ -0,0 +1,35 @@
+/**
+ * Why a native stack layer does not yet let the layers above it advance, or undefined
+ * when it does. The stack selector and an upper draft's parent-first mark-ready check
+ * share this predicate so both always name the same blocking layer.
+ */
+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
+    // do not let its otherwise-current receipt promote a child draft.
+    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 sufficient evidence for the layers above it.
+    return item.readyReceipt === true ? undefined : "no-ready-receipt";
+}

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

@@ -0,0 +1,14 @@
+import type { PollSummaryItem, PollSummaryResult } from "../types.mts";
+/**
+ * A `--stack` plan that can only wait never reruns its layers' one-PR sessions, so their own
+ * stall guards cannot fire. Escalate `stall-timeout` once that idle plan's fingerprint stays
+ * unchanged for `stallTimeoutSeconds`; any other plan, or `0`, clears the timer. When the enabled
+ * timer cannot be read or written, escalate `stall-state-unavailable` instead of restarting it.
+ */
+export declare function applyStackStallGuard(planned: {
+    result: PollSummaryResult;
+    idle?: PollSummaryItem[];
+}, repo: {
+    owner: string;
+    name: string;
+}, stallTimeoutSeconds: number): Promise<PollSummaryResult>;