pr-shepherd 0.51.1 → 0.52.1

package/bin/commands/poll-summary.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import { loadConfig } from "../config/load.mjs";
 import { ShepherdError } from "../exit-codes.mjs";
 import { getRepoInfo } from "../github/client.mjs";
@@ -5,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) {
@@ -20,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,
@@ -28,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);
@@ -54,16 +57,31 @@ async function runAggregatePollCore(opts) {
                     stackPrNumber: undefined,
                     prNumbers: last.prs.map((item) => item.pr),
                 });
-                if (explicit.prs.every((item) => item.action === "cancel")) {
+                if (explicit.prs.every((item) => item.state === "MERGED")) {
                     const warning = await aggregateQuotaWarning(explicit, quotaBands, opts.intervalSeconds);
                     if (warning)
                         pendingQuotaWarning = warning;
                     return attachUsage({
                         ...explicit,
+                        selection: last.selection,
                         reason: "all_terminal",
+                        nextAction: "cancel",
+                        stackMergeable: true,
+                        instructions: ["1. Stop — every stack layer is merged."],
                         ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
                     }, opts.merge);
                 }
+                return attachUsage({
+                    ...explicit,
+                    selection: last.selection,
+                    reason: "actionable",
+                    nextAction: "escalate",
+                    stackMergeable: false,
+                    instructions: [
+                        `1. Native stack #${last.selection.stackNumber} disappeared before every tracked layer merged. Stop and ask the stack owner to reconcile the remaining PRs; do not claim the stack is complete.`,
+                    ],
+                    ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+                }, opts.merge);
             }
             const retryMs = opts.untilTerminal ? pollGraphQlRetryAfterMs(error) : null;
             if (retryMs === null || rateLimitRetries >= 1)
@@ -77,10 +95,11 @@ async function runAggregatePollCore(opts) {
             ? last.nextAction === "cancel"
             : last.prs.every((item) => item.action === "cancel");
         const immediate = last.selection.kind === "stack"
-            ? ["escalate", "merge", "mark_ready"].includes(last.nextAction ?? "wait")
+            ? (last.nextAction === "escalate" || last.nextAction === "merge") &&
+                last.reason !== "waiting"
             : last.prs.some((item) => ["escalate", "merge", "mark_ready"].includes(item.action));
         const hasFix = last.selection.kind === "stack"
-            ? last.nextAction === "fix_code"
+            ? last.nextAction === "shepherd" && last.reason !== "waiting"
             : last.prs.some((item) => item.action === "fix_code");
         const warning = await aggregateQuotaWarning(last, quotaBands, opts.intervalSeconds);
         if (warning)
@@ -145,5 +164,12 @@ function isMissingStack(error) {
 }
 function attachUsage(result, mergeRequested) {
     const apiUsage = summarizeApiTelemetry();
-    return withPollSummaryInstructions(apiUsage ? { ...result, apiUsage } : result, mergeRequested === true);
+    const enriched = apiUsage ? { ...result, apiUsage } : result;
+    // A disappeared native stack is an aggregate-level terminal handoff. Keep
+    // that explicit escalation intact even when the one-PR fallback contains
+    // open orphan rows that would otherwise be re-planned as fix_code.
+    if (enriched.selection.kind === "stack" && enriched.nextAction === "escalate") {
+        return enriched;
+    }
+    return withPollSummaryInstructions(enriched, mergeRequested === true);
 }

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

package/bin/commands/stack-stall.mjs

@@ -0,0 +1,69 @@
+import { clearStackStallState, readStackStallState, writeStackStallState, } from "../state/stack-stall.mjs";
+import { formatDurationApprox } from "./iterate/escalate.mjs";
+import { summaryStatusSignature } from "./poll-summary-signature.mjs";
+import { describeIdleLayers } from "./stack-drain.mjs";
+/**
+ * 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 async function applyStackStallGuard(planned, repo, stallTimeoutSeconds) {
+    const { result, idle } = planned;
+    if (result.selection.kind !== "stack")
+        return result;
+    const key = { owner: repo.owner, repo: repo.name, stack: result.selection.stackNumber };
+    if (!idle || stallTimeoutSeconds <= 0) {
+        await clearStackStallState(key);
+        return result;
+    }
+    const fingerprint = stackStallFingerprint(result);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const read = await readStackStallState(key);
+    if (!read.ok)
+        return stackStateUnavailable(result, read.reason);
+    const stored = read.state;
+    if (!stored || stored.fingerprint !== fingerprint || stored.firstSeenAt > nowSeconds) {
+        const wrote = await writeStackStallState(key, { fingerprint, firstSeenAt: nowSeconds });
+        if (!wrote.ok)
+            return stackStateUnavailable(result, wrote.reason);
+        return result;
+    }
+    const ageSeconds = nowSeconds - stored.firstSeenAt;
+    if (ageSeconds < stallTimeoutSeconds)
+        return result;
+    return {
+        ...result,
+        reason: "actionable",
+        nextAction: "escalate",
+        stackMergeable: false,
+        instructions: [
+            `1. \`stall-timeout\`: the stack has not changed for ${formatDurationApprox(ageSeconds)} while no one-PR session could advance it: ${describeIdleLayers(idle)}. Stop and ask a human to unblock the waiting layers.`,
+        ],
+    };
+}
+function stackStateUnavailable(result, reason) {
+    return {
+        ...result,
+        reason: "actionable",
+        nextAction: "escalate",
+        stackMergeable: false,
+        instructions: [
+            `1. \`stall-state-unavailable\`: the stack stall timer could not be saved (${reason}). Stop and ask a human to fix the state directory before resuming.`,
+        ],
+    };
+}
+/** The status signature plus the per-layer evidence it omits, so a push resets the timer. */
+function stackStallFingerprint(result) {
+    return JSON.stringify({
+        status: summaryStatusSignature(result),
+        layers: result.prs.map((item) => ({
+            pr: item.pr,
+            headRefOid: item.headRefOid,
+            isDraft: item.isDraft,
+            readyReceipt: item.readyReceipt,
+            reasons: item.reasons,
+            blockedByPr: item.blockedByPr,
+        })),
+    });
+}

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

@@ -0,0 +1,32 @@
+import type { PollSummaryItem } from "../types.mts";
+type ProbedLayer = PollSummaryItem & {
+    pollCommand: string;
+    pollProbe: true;
+};
+/**
+ * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
+ * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
+ */
+export declare const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
+/** How the stack selector routes the autonomous layers that still need work. */
+export interface StackWork {
+    /** Layers that need a one-PR Shepherd session, with or without a known command. */
+    sessions: PollSummaryItem[];
+    /** Clean, unblocked drafts that the agent marks ready because the poll loop will not. */
+    markReady: ProbedLayer[];
+    /** Layers whose bounded probe could only report that they are still waiting. */
+    idle: ProbedLayer[];
+}
+/**
+ * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
+ * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A clean draft
+ * that no lower layer blocks becomes an agent ready-for-review step instead. A stale-ancestry
+ * child keeps its session, which returns the ancestry repair.
+ */
+export declare function splitStackWork(candidates: PollSummaryItem[], staleChildren: ReadonlySet<number>): StackWork;
+/**
+ * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
+ * first because only the one-PR session reads the full review context and current lower layers.
+ */
+export declare function appendMarkReadyInstructions(instructions: string[], layers: ProbedLayer[]): void;
+export {};

package/bin/commands/stack-work.mjs

@@ -0,0 +1,39 @@
+/**
+ * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
+ * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
+ */
+export const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
+/**
+ * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
+ * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A clean draft
+ * that no lower layer blocks becomes an agent ready-for-review step instead. A stale-ancestry
+ * child keeps its session, which returns the ancestry repair.
+ */
+export function splitStackWork(candidates, staleChildren) {
+    const work = { sessions: [], markReady: [], idle: [] };
+    for (const item of candidates) {
+        if (!isProbed(item) || item.action !== "wait" || staleChildren.has(item.pr)) {
+            work.sessions.push(item);
+        }
+        else if (item.blockedByPr === undefined &&
+            item.reasons.includes("draft-auto-mark-ready-disabled")) {
+            work.markReady.push(item);
+        }
+        else {
+            work.idle.push(item);
+        }
+    }
+    return work;
+}
+/**
+ * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
+ * first because only the one-PR session reads the full review context and current lower layers.
+ */
+export function appendMarkReadyInstructions(instructions, layers) {
+    for (const item of layers) {
+        instructions.push(`${instructions.length + 1}. Automatic mark-ready is disabled, so marking PR #${item.pr} ready for review is your step. Run \`${item.pollCommand}\` first. If it returns \`[WAIT]\` saying PR #${item.pr} stays in draft because ${AUTO_MARK_READY_DISABLED_HOLD}, run \`gh pr ready ${item.pr} -R ${item.repo}\`; otherwise complete its instructions and leave PR #${item.pr} in draft this round.`);
+    }
+}
+function isProbed(item) {
+    return item.pollProbe === true && item.pollCommand !== undefined;
+}

package/bin/config/load.d.mts

@@ -15,6 +15,8 @@ interface PollConfig {
 export interface PrShepherdConfig {
     /** Optional user classification configuration; preserved for rule consumers. */
     classify?: unknown;
+    /** Argv prefix for every pr-shepherd command Shepherd emits, e.g. `["pnpm", "exec", "pr-shepherd"]`. */
+    cliCommand: string[];
     /** GitHub logins that should be treated as bots even when GitHub reports User/Unknown. */
     botUsernames: string[];
     /** Case-insensitive glob patterns for check/status context names Shepherd should ignore. */

package/bin/config/load.mjs

@@ -76,6 +76,14 @@ function parseResolveOtherHumanThreads(value) {
     }
     throw new Error(`Invalid config: iterate.resolveOtherHumanThreads must be one of "none", "outdated", or "always", got ${JSON.stringify(value)}`);
 }
+function parseCliCommand(value) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        !value.every((arg) => typeof arg === "string" && arg.trim() !== "")) {
+        throw new Error("Invalid config: cliCommand must be a non-empty array of non-empty strings");
+    }
+    return value;
+}
 function parseBotUsernames(value) {
     if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
         throw new Error(`Invalid config: botUsernames must be an array of strings`);
@@ -223,6 +231,7 @@ function parseGraphqlQuotaWarnings(value, pollIntervalSeconds) {
 }
 const KNOWN_CONFIG_KEYS = new Set([
     "classify",
+    "cliCommand",
     "botUsernames",
     "ignoreChecks",
     "iterate",
@@ -284,6 +293,7 @@ function warnUnknownConfigKeys(config) {
 const rawDefaults = builtins;
 function parseConfig(value, normalizeMergeArgs = true) {
     const config = value;
+    config.cliCommand = parseCliCommand(config.cliCommand);
     config.botUsernames = parseBotUsernames(config.botUsernames);
     config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
     config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);