pr-shepherd 0.51.1 → 0.52.1

package/bin/commands/iterate/parent-first.mjs

@@ -0,0 +1,70 @@
+import { fetchPollSummary } from "../../github/poll-summary.mjs";
+import { stackLayerBlockReason } from "../stack-layer-readiness.mjs";
+/**
+ * Draft children may only be converted after their immediate parent has
+ * independently completed a one-PR ready-delay and the stack boundary is
+ * still linear.  A failed or incomplete stack read blocks this mutation but
+ * does not block ordinary review/CI work in the caller.
+ */
+export async function findParentMarkReadyBlock(report, repo) {
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    if (!stack || stack.position === 1)
+        return undefined;
+    if (stack.position < 1)
+        return "unverifiable";
+    try {
+        const summary = await fetchPollSummary({ stackPrNumber: report.pr }, repo);
+        const child = summary.prs.find((item) => item.pr === report.pr);
+        const lowerLayers = summary.prs
+            .filter((item) => (item.stack?.position ?? Number.MAX_SAFE_INTEGER) < stack.position)
+            .sort((left, right) => (left.stack?.position ?? Number.MAX_SAFE_INTEGER) -
+            (right.stack?.position ?? Number.MAX_SAFE_INTEGER));
+        if (!child || child.state !== "OPEN" || lowerLayers.length !== stack.position - 1)
+            return "unverifiable";
+        // A stale boundary means that layer is no longer based on the parent it was
+        // reviewed against. Gaps above this child do not affect its promotion boundary.
+        const staleChildren = new Set(summary.stackAncestry?.map((gap) => gap.childPr));
+        for (const layer of lowerLayers) {
+            // A merged layer is already satisfied; GitHub may have retargeted the
+            // layer above it to the trunk as part of the merge.
+            if (layer.state === "MERGED")
+                continue;
+            const reason = staleChildren.has(layer.pr) ? "stale-ancestry" : stackLayerBlockReason(layer);
+            if (reason)
+                return { pr: layer.pr, reason };
+        }
+        // This layer's own stale boundary belongs to its own session's repair; the
+        // earlier stale-ancestry read missed it, so this snapshot is unsettled.
+        return staleChildren.has(report.pr) ? "unverifiable" : undefined;
+    }
+    catch {
+        // Never convert a child draft based on an unverifiable parent.
+        return "unverifiable";
+    }
+}
+/**
+ * A native stack draft this one-PR session cannot promote: a lower layer blocks it, or
+ * automatic mark-ready is off. Undefined when the session can still advance the PR by
+ * iterating.
+ */
+export function stackDraftHold(report, autoMarkReady, parentBlock) {
+    if (!report.mergeStatus.mergeRequirements?.stack || !report.mergeStatus.isDraft)
+        return undefined;
+    // Any lower-layer block outranks the session flag: even with automatic
+    // mark-ready enabled, this draft cannot advance until that layer does, and a
+    // lower-layer read that failed must not hide behind the flag.
+    if (parentBlock === "unverifiable")
+        return { kind: "lower-layer-not-ready" };
+    if (parentBlock)
+        return { kind: "lower-layer-not-ready", lowerLayer: parentBlock };
+    return autoMarkReady ? undefined : { kind: "auto-mark-ready-disabled" };
+}
+/**
+ * The lower layer a held draft waits on. That layer's own session owns this draft's
+ * progress, so the draft neither stalls nor keeps polling while it waits.
+ */
+export function heldByLowerLayer(result) {
+    return result.action === "wait" && result.stackDraftHold?.kind === "lower-layer-not-ready"
+        ? result.stackDraftHold.lowerLayer
+        : undefined;
+}

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

@@ -2,4 +2,4 @@ import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, Fir
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
 export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, _cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], _inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind?: boolean, viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean): string[];
+isBehind?: boolean, viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string): string[];

package/bin/commands/iterate/render.mjs

@@ -4,6 +4,7 @@ import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, buildShepherdJournalInstruction,
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 import { partitionFixThreads, reviewSectionRefs } from "./fix-instruction-threads.mjs";
+import { buildBranchPushInstruction, buildConflictInstruction } from "./native-stack-rebase.mjs";
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export function renderResolveCommand(rc) {
     const parts = [...rc.argv];
@@ -12,14 +13,11 @@ export function renderResolveCommand(rc) {
     return renderShellCommand(parts);
 }
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, _cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], _inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
+isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase) {
     const instructions = [];
     const { locatedThreads, unlocatedMutatedThreads, unlocatedThreads } = partitionFixThreads(threads, resolveCommand, resolveOnlyCommand);
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
-    const repeatedWorkflowBranchRecoveryInstructions = buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, {
-        isBehind,
-        hasConflicts,
-    });
+    const repeatedWorkflowBranchRecoveryInstructions = buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, { isBehind, hasConflicts }, stackRebase);
     const hasRepeatedWorkflowBranchRecovery = repeatedWorkflowBranchRecoveryInstructions.length > 0;
     const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
     const hasNonConflictHints = threads.length > 0 ||
@@ -41,7 +39,7 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
         instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
     }
     if (hasConflicts && !hasRepeatedWorkflowBranchRecovery) {
-        instructions.push("The branch has merge conflicts (see `**branch**` above). Resolve them before committing.");
+        instructions.push(buildConflictInstruction(stackRebase));
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
@@ -82,11 +80,8 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
     instructions.push(...buildBehindBaseHintInstruction(baseBranch, behindBaseHint, isBehind));
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
-    if (hasConflicts) {
-        instructions.push(`Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`);
-    }
-    else if (hasRepeatedWorkflowBranchRecovery) {
-        instructions.push("Push the updated PR head branch before iterating immediately.");
+    if (hasConflicts || hasRepeatedWorkflowBranchRecovery) {
+        instructions.push(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix));
     }
     else if (hasNonConflictHints) {
         instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate immediately with the same options. If you did not change code, do not commit and continue with the remaining steps.");
@@ -101,6 +96,6 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");
-    instructions.push(...buildResolveCommandInstruction(resolveCommand), buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha));
+    instructions.push(...buildResolveCommandInstruction(resolveCommand), buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha, stackRebase !== undefined));
     return instructions;
 }

package/bin/commands/iterate/stale-ancestry.d.mts

@@ -0,0 +1,22 @@
+import type { RepoInfo } from "../../github/client.mts";
+import type { PollSummaryStackAncestry } from "../../types.mts";
+import type { ShepherdReport } from "../../types/report.mts";
+/**
+ * A verified stale boundary for the PR being shepherded.
+ *
+ * The stack topology read is authoritative for this check: it compares the
+ * child's recorded base OID with the current head OID of its immediate open
+ * parent. GitHub can report both PRs CLEAN while this boundary is stale.
+ */
+export interface StaleNativeStackAncestry extends PollSummaryStackAncestry {
+    instructions: string[];
+}
+/**
+ * Find a stale immediate parent boundary for one PR.
+ *
+ * This helper is intentionally read-only. A null result means either the PR is
+ * not a non-root native-stack layer, its boundary is current, or the boundary
+ * could not be verified. Callers must not emit a repair command from an
+ * unverified snapshot.
+ */
+export declare function findStaleNativeStackAncestry(report: Pick<ShepherdReport, "pr" | "mergeStatus">, repo: RepoInfo): Promise<StaleNativeStackAncestry | null>;

package/bin/commands/iterate/stale-ancestry.mjs

@@ -0,0 +1,40 @@
+import { readStackTopology, stackAncestryGaps } from "../../github/stack-read.mjs";
+import { buildNativeStackRebaseInstruction } from "./native-stack-rebase.mjs";
+/**
+ * Find a stale immediate parent boundary for one PR.
+ *
+ * This helper is intentionally read-only. A null result means either the PR is
+ * not a non-root native-stack layer, its boundary is current, or the boundary
+ * could not be verified. Callers must not emit a repair command from an
+ * unverified snapshot.
+ */
+export async function findStaleNativeStackAncestry(report, repo) {
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    if (!stack || stack.position <= 1)
+        return null;
+    try {
+        const topology = await readStackTopology(report.pr, repo);
+        const ancestry = stackAncestryGaps(topology.ordered).find((gap) => gap.childPr === report.pr);
+        if (!ancestry)
+            return null;
+        return {
+            ...ancestry,
+            instructions: buildStaleNativeStackAncestryInstructions(repo, stack.number, ancestry),
+        };
+    }
+    catch {
+        // A stale repair is safe only when both OIDs were observed together. Let
+        // the caller retain the ordinary WAIT/ESCALATE path on an unreadable stack.
+        return null;
+    }
+}
+/** Build the one-PR repair guidance after a stale boundary was verified. */
+function buildStaleNativeStackAncestryInstructions(repo, stackNumber, ancestry) {
+    return [
+        `PR #${ancestry.childPr} records base \`${ancestry.childBaseRefName}\` at \`${ancestry.childBaseRefOid}\`, but its open parent PR #${ancestry.parentPr} currently ends at \`${ancestry.parentHeadRefName}\` \`${ancestry.parentHeadRefOid}\`.`,
+        buildNativeStackRebaseInstruction(`${repo.owner}/${repo.name}`, stackNumber, {
+            parentBranch: ancestry.parentHeadRefName,
+        }),
+        "Push the rewritten stack with `gh stack push`.",
+    ];
+}

package/bin/commands/iterate/stall.mjs

@@ -90,12 +90,27 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
         };
     }
     const fingerprint = computeStallFingerprint(prospectiveResult.action, headSha, base, report, reviewSummaryIds);
-    const stored = await readStallState(stallKey);
+    const read = await readStallState(stallKey);
+    if (!read.ok) {
+        if (stallTimeoutSeconds <= 0)
+            return prospectiveResult;
+        return stallStateUnavailable(base, prReference, prospectiveResult, read.reason);
+    }
+    const stored = read.state;
+    const persistTimer = async () => {
+        const wrote = await writeStallState(stallKey, { fingerprint, firstSeenAt: nowSeconds });
+        if (!wrote.ok && stallTimeoutSeconds > 0) {
+            return stallStateUnavailable(base, prReference, prospectiveResult, wrote.reason);
+        }
+        return undefined;
+    };
     if (stored && stored.fingerprint === fingerprint) {
         const ageSeconds = nowSeconds - stored.firstSeenAt;
         if (ageSeconds < 0) {
             // Clock skew: stored timestamp is in the future. Reset to avoid perpetually negative age.
-            await writeStallState(stallKey, { fingerprint, firstSeenAt: nowSeconds });
+            const failed = await persistTimer();
+            if (failed)
+                return failed;
         }
         else if (stallTimeoutSeconds <= 0) {
             // Stall detection disabled: refresh so re-enabling starts a fresh timer.
@@ -126,9 +141,31 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
         return prospectiveResult;
     }
     // Fingerprint changed or no prior state — reset the stall timer.
-    await writeStallState(stallKey, { fingerprint, firstSeenAt: nowSeconds });
+    const failed = await persistTimer();
+    if (failed)
+        return failed;
     return prospectiveResult;
 }
+function stallStateUnavailable(base, prReference, prospectiveResult, reason) {
+    const pending = pendingReviewCommandsFromResult(prospectiveResult);
+    const escalateBase = {
+        triggers: ["stall-state-unavailable"],
+        unresolvedThreads: [],
+        ambiguousComments: [],
+        changesRequestedReviews: [],
+        ...surfacedSummariesFromResult(prospectiveResult),
+        ...(pending && { pendingReviewCommands: pending }),
+        suggestion: buildEscalateSuggestion(["stall-state-unavailable"], reason),
+    };
+    return {
+        ...base,
+        action: "escalate",
+        escalate: {
+            ...escalateBase,
+            humanMessage: buildEscalateHumanMessage(escalateBase, prReference),
+        },
+    };
+}
 function findCiStartStalledChecks(checks, nowSeconds, opts) {
     if (opts.stallTimeoutSeconds <= 0 || opts.action !== "wait")
         return [];

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

@@ -1,11 +1,15 @@
 import type { IterateResult } from "../types.mts";
+type WaitResult = Extract<IterateResult, {
+    action: "wait";
+}>;
 export declare function writeWaitProgress(opts: {
     tick: number;
     elapsedMs: number;
     sleepMs: number;
-    result: IterateResult;
+    result: WaitResult;
     quietStatus: boolean;
     verbose: boolean;
     lastWaitSignature: string | null;
 }): string | null;
 export declare function writeDebounceProgress(tick: number, elapsedMs: number, remainingMs: number): void;
+export {};

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,139 +1,183 @@
+/* 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 planned = planStack(result, mergeRequested);
-    const reason = planned.action === "cancel"
-        ? "all_terminal"
-        : planned.action === "wait"
-            ? result.reason === "timeout"
-                ? "timeout"
-                : "waiting"
-            : "actionable";
+    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" && (!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) && {
+                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"),
+                pollProbe: true,
+            }),
+        }
+        : item.state === "OPEN" &&
+            (!isStackLayerReady(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 {
+                    ...item,
+                    action: "wait",
+                    reasons: [...item.reasons, "already-in-merge-queue"],
+                };
+            }
+            if (item.state === "CLOSED" && closedDependency(blocked, item.pr)) {
+                return {
+                    ...item,
+                    action: "escalate",
+                    reasons: [...item.reasons, "closed-unmerged-dependency"],
+                };
+            }
+            if (item.state !== "OPEN" && item.state !== "MERGED") {
+                return {
+                    ...item,
+                    action: "escalate",
+                    reasons: [...item.reasons, "unverified-stack-state"],
+                };
+            }
+            return item;
+        }),
+    };
+    const planned = planStack(projected, mergeRequested);
     const instructions = [...planned.instructions];
-    if (result.quotaWarning && planned.action !== "wait" && planned.action !== "cancel") {
+    if (result.quotaWarning && planned.action === "shepherd") {
         instructions.push(buildQuotaAwareContinuation(result.quotaWarning, `${instructions.length + 1}. After completing the stack action,`));
     }
-    return { ...result, reason, nextAction: planned.action, instructions };
+    return {
+        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");
-    if (open.length === 0) {
-        return { action: "cancel", instructions: ["1. Stop — every selected PR is terminal."] };
+    const gaps = result.stackAncestry ?? [];
+    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);
+        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 (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 };
     }
-    const lastOpenPosition = positionOf(result, open.at(-1).pr);
-    const closedBelowOpen = result.prs.find((item) => item.state === "CLOSED" && positionOf(result, item.pr) < lastOpenPosition);
-    if (closedBelowOpen) {
+    if (open.length === 0) {
         return {
-            action: "escalate",
-            instructions: [
-                `1. PR #${closedBelowOpen.pr} is closed without merging below an open stack layer. Stop stack merge and rebase operations here; the closed dependency must be restored or the higher branches rebuilt on a valid base.`,
-                "2. Ask the stack owner which recovery path to take, then rerun the same aggregate `--stack` selector after the stack is repaired.",
-            ],
+            action: "cancel",
+            stackMergeable: true,
+            instructions: ["1. Stop — every stack layer is merged."],
         };
     }
-    const gap = result.stackAncestry?.[0];
-    const firstOpen = open[0];
-    if (firstOpen.mergeStateStatus === "BEHIND")
-        return rebaseWholeStack(result, firstOpen);
-    if (mergeRequested) {
-        const mergeTarget = readyLowerStackTarget(open, result.stackAncestry ?? []);
-        if (mergeTarget) {
-            const stackNumber = result.selection.kind === "stack" ? result.selection.stackNumber : 0;
-            return {
-                action: "merge",
-                instructions: [
-                    `1. The contiguous ready lower stack ends at PR #${mergeTarget.pr}. Merge the native stack through that PR with \`gh stack merge --squash ${mergeTarget.pr}\`; verify that the selector names PR #${mergeTarget.pr} in stack #${stackNumber} before running it. This includes still-open lower layers and leaves higher layers open.`,
-                    "2. After GitHub completes the stack merge and updates the remaining branches, rerun the same aggregate `--stack` selector. If an ancestry mismatch remains, follow the rebase instructions returned then.",
-                ],
-            };
+    if (!stackMergeable) {
+        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. ${agentWork ? "After autonomous shepherding, ask" : "Stop and ask"} for direction.`);
+            }
+            if (agentWork) {
+                instructions.push(`${instructions.length + 1}. After the listed one-PR sessions, rerun this same \`--stack\` selector. Stop for the human handoff only when no autonomous shepherding remains.`);
+            }
+            return { action: agentWork ? "shepherd" : "escalate", stackMergeable: false, instructions };
         }
-        if (firstOpen.action === "wait") {
-            return waitingStack(result);
-        }
-    }
-    const firstWork = open.find((item) => ["fix_code", "mark_ready", "escalate"].includes(item.action));
-    if (firstWork && (!gap || positionOf(result, firstWork.pr) <= positionOf(result, gap.childPr))) {
-        return pollOneLayer(firstWork);
+        if (!agentWork)
+            return idleWaitPlan(work.idle);
+        const instructions = [];
+        appendAutonomousInstructions(instructions, work.sessions);
+        appendMarkReadyInstructions(instructions, work.markReady);
+        instructions.push(`${instructions.length + 1}. After the selected one-PR sessions, rerun this same \`--stack\` selector.`);
+        return { action: "shepherd", stackMergeable: false, instructions };
     }
-    if (gap) {
+    if (open.some((item) => item.isInMergeQueue)) {
         return {
-            action: "fix_code",
+            action: "wait",
+            stackMergeable: true,
+            waiting: true,
             instructions: [
-                `1. PR #${gap.childPr} still records base \`${gap.childBaseRefName}\` at \`${gap.childBaseRefOid}\`, while parent PR #${gap.parentPr} now ends at \`${gap.parentHeadRefName}\` \`${gap.parentHeadRefOid}\`. From a clean checkout of \`${result.repo}\`, check out the parent stack branch \`${gap.parentHeadRefName}\`.`,
-                "2. Rebase the upstack branches onto that parent with `gh stack rebase --upstack --no-trunk`, resolve any conflicts, and push the rewritten branches with `gh stack push`.",
-                "3. Rerun the same aggregate `--stack` selector and follow the next returned action.",
+                "1. The stack is in the merge queue. Recheck at the configured polling cadence; finish only after every layer is merged, and route any ejected layer to its one-PR session.",
             ],
         };
     }
-    const behind = open.find((item) => item.mergeStateStatus === "BEHIND");
-    if (behind)
-        return rebaseWholeStack(result, behind);
-    if (firstWork)
-        return pollOneLayer(firstWork);
-    if (!mergeRequested && open.every((item) => item.action === "cancel")) {
+    if (!mergeRequested && result.prs.every((item) => item.action === "cancel")) {
         return {
             action: "cancel",
-            instructions: ["1. Stop — every open stack layer is ready and the stack is linear."],
+            stackMergeable: true,
+            instructions: ["1. Stop — every stack layer is terminal or fully READY."],
         };
     }
-    return waitingStack(result);
-}
-function rebaseWholeStack(result, behind) {
-    return {
-        action: "fix_code",
-        instructions: [
-            `1. GitHub reports PR #${behind.pr} is behind its base \`${behind.baseRefName}\`. From a clean checkout of \`${result.repo}\`, check out its stack branch \`${behind.headRefName}\`.`,
-            "2. Rebase that native stack from its trunk with `gh stack rebase`, resolving any conflicts.",
-            "3. Push the updated stack with `gh stack push` and rerun the same aggregate `--stack` selector.",
-        ],
-    };
-}
-function readyLowerStackTarget(open, gaps) {
-    const mismatchedChildren = new Set(gaps.map((gap) => gap.childPr));
-    let target;
-    for (const item of open) {
-        if (mismatchedChildren.has(item.pr) || item.action !== "merge")
-            break;
-        target = item;
-    }
-    return target;
-}
-function positionOf(result, pr) {
-    return result.prs.find((item) => item.pr === pr)?.stack?.position ?? Number.MAX_SAFE_INTEGER;
-}
-function pollOneLayer(item) {
-    if (!item.pollCommand) {
+    if (!mergeRequested) {
+        const instructions = [];
+        appendAutonomousInstructions(instructions, open.filter((item) => item.action !== "cancel"));
+        instructions.push(`${instructions.length + 1}. After the selected one-PR sessions, rerun this same \`--stack\` selector.`);
         return {
-            action: "escalate",
-            instructions: [
-                `1. PR #${item.pr} needs attention, but GitHub returned no one-PR poll command.`,
-            ],
+            action: "shepherd",
+            stackMergeable,
+            instructions,
         };
     }
-    return {
-        action: item.action,
-        instructions: [
-            `1. Work on the lowest actionable layer, PR #${item.pr}: run \`${item.pollCommand}\`.`,
-            "2. Follow that one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
-            "3. Rerun the aggregate `--stack` selector before acting on a higher layer.",
-        ],
-    };
+    return retargetWaitPlan(open[0]);
 }
-function waitingStack(result) {
-    if (result.quotaWarning) {
-        return {
-            action: "wait",
-            instructions: [
-                buildQuotaAwareContinuation(result.quotaWarning, "1. This native stack is non-terminal. Before continuing,"),
-            ],
-        };
-    }
-    return {
-        action: "wait",
-        instructions: ["1. Recheck this native stack after the lowest open layer changes state."],
-    };
+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" && stackPosition(item) < stackPosition(lastOpen)));
 }