pr-shepherd 0.51.1 → 0.52.1

package/bin/commands/iterate/escalate.mjs

@@ -1,5 +1,4 @@
 import { loadConfig } from "../../config/load.mjs";
-import { inlineCode } from "../../util/markdown.mjs";
 import { renderResolveCommand } from "./render.mjs";
 function renderEscalateAuthor(item) {
     return [`@${item.author}`, item.authorType, item.authorAssociation].filter(Boolean).join(" · ");
@@ -194,10 +193,6 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
         if (removal.beforeCommitOid)
             lines.push(`- queue commit: \`${removal.beforeCommitOid}\``);
     }
-    if (escalate.stack) {
-        const s = escalate.stack;
-        lines.push("", "## GitHub stack", "", `- layer: \`${s.position}\` of \`${s.size}\` in stack \`${s.number}\``, `- stack base: ${inlineCode(s.baseRefName)}`);
-    }
     if (escalate.authorization && escalate.authorization.length > 0) {
         lines.push("");
         lines.push("## Authorization");
@@ -231,10 +226,6 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
-    if (triggers.includes("stacked-pr")) {
-        const selector = detail ?? "<pr>";
-        return `This PR belongs to a GitHub stack, so Shepherd will not emit a merge command. \`gh pr merge\` targets the PR's own base branch — for a mid-stack layer that is the unmerged parent branch, not the stack's base — and auto-merge is unsupported on stacked PRs. Merge from the GitHub stack UI, or run \`gh stack merge --squash ${selector}\` (requires the \`github/gh-stack\` extension — run \`gh extension install github/gh-stack\` first if it's not installed), which lands this PR and every unmerged layer below it.`;
-    }
     if (triggers.includes("check-follow-up-unavailable")) {
         return "One or more failing checks have no autonomous follow-up available. Use the displayed conclusion, run or URL, and included evidence to handle them manually.";
     }
@@ -249,6 +240,10 @@ export function buildEscalateSuggestion(triggers, detail) {
         const duration = detail ?? "60 minutes";
         return `No progress detected for ${duration} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
     }
+    if (triggers.includes("stall-state-unavailable")) {
+        const reason = detail ?? "unknown error";
+        return `The stall timer could not be saved (${reason}). Fix PR_SHEPHERD_STATE_DIR or the directory permissions, then resume. Automated polling is paused because a stuck loop would not be detected.`;
+    }
     if (triggers.includes("base-branch-unknown")) {
         const reason = detail ? ` (${detail})` : "";
         return `Could not determine the PR's base branch${reason} — automated rebases are paused because branch safety is unclear. Run the rebase manually against the PR's real target branch.`;
@@ -257,9 +252,5 @@ export function buildEscalateSuggestion(triggers, detail) {
         const attempts = loadConfig().iterate.fixAttemptsPerThread;
         return `The same thread(s) remain unresolved after their pending review commands were returned for ${attempts} FIX_CODE ticks. Automated iteration is paused for a manual decision.`;
     }
-    if (triggers.includes("bot-cr-not-dismissed")) {
-        const ids = detail ? ` (review IDs: ${detail})` : "";
-        return `Bot CHANGES_REQUESTED review(s) remained undismissed past the stall window${ids}. The agent likely dropped \`--dismiss-review-ids\` from a prior apply command. Dismiss the review(s) manually (or re-run \`pr-shepherd apply review\` with the IDs) to unblock the PR.`;
-    }
     return "Ambiguous state — automated handling cannot proceed safely. Inspect the PR and act manually.";
 }

package/bin/commands/iterate/fix-code.d.mts

@@ -20,6 +20,8 @@ interface HandleFixCodeContext {
     surfacedApprovals: Review[];
     botUsernames: NormalizedBotUsernames;
     ruleAutoResolveThreadIds?: string[];
+    /** Verified stack-repair guidance, when ancestry is stale. */
+    repairInstructions?: string[];
 }
 export declare function handleFixCode(ctx: HandleFixCodeContext): Promise<IterateResult>;
 export {};

package/bin/commands/iterate/fix-code.mjs

@@ -1,12 +1,12 @@
 /* eslint-disable max-lines */
 import { readFixAttempts, writeFixAttempts, } from "../../state/fix-attempts.mjs";
-import { readBotCrSeenState, writeBotCrSeenState, updateBotCrSeenState, } from "../../state/bot-cr-seen.mjs";
 import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
 import { hashBody, markSeen } from "../../state/seen-comments.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
 import { buildResolveCommand } from "./classify.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./thread-mutation-routing.mjs";
 import { buildFixInstructions } from "./render.mjs";
+import { buildNativeStackLayerRebase } from "./native-stack-rebase.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
@@ -17,15 +17,15 @@ import { formatPrUrl } from "../../pr-reference.mjs";
 function checkRequiresHumanFollowUp(check) {
     if (check.rerunCommand)
         return false;
-    // Once GitHub advances beyond the original attempt, Shepherd's one autonomous rerun has
-    // already been consumed. Hand the repeated failure off even when logs are available; the
-    // human still receives that evidence in the escalation payload.
-    if (check.runAttempt !== undefined && check.runAttempt > 1)
-        return true;
     if (check.conclusion === "ACTION_REQUIRED" ||
         check.conclusion === "CANCELLED" ||
         check.conclusion === "STARTUP_FAILURE")
         return true;
+    // A later attempt cannot be rerun automatically, but its included log can still
+    // identify a code or configuration fix for the agent. Only a later failure with
+    // no actionable evidence needs a human handoff.
+    if (check.runAttempt !== undefined && check.runAttempt > 1)
+        return !check.logExcerpt?.trim();
     // An external check's direct URL is actionable evidence: the agent can inspect the
     // provider and/or reproduce the reported failure locally. Only a truly bare check
     // has no autonomous investigation path.
@@ -68,7 +68,7 @@ function pendingReviewCommands(resolveCommand, resolveOnlyCommand) {
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
     const failingChecks = report.checks.failing;
     const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
@@ -105,37 +105,6 @@ export async function handleFixCode(ctx) {
         ...(report.comments.minimizeIds ?? report.comments.actionable.map((comment) => comment.id)),
         ...reviewSummaryIds,
     ], changesRequestedReviewsForWork, checks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads, resolveOtherHumanThreads);
-    const botCrReviews = report.changesRequestedReviews.filter((r) => (!isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames)) &&
-        report.viewerAuthorization?.viewerCanAdminister === true);
-    const botCrStateKey = { owner: repoOwner, repo: repoName, pr: prNumber };
-    const previousBotCrState = await readBotCrSeenState(botCrStateKey);
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    const { next: nextBotCrState, staleIds: staleBotCrIds } = updateBotCrSeenState(previousBotCrState, botCrReviews, nowSeconds, stallTimeoutSeconds);
-    await writeBotCrSeenState(botCrStateKey, nextBotCrState);
-    if (staleBotCrIds.length > 0) {
-        const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(toAgentChecks(failingChecks));
-        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
-        const escalateBase = {
-            triggers: ["bot-cr-not-dismissed"],
-            unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
-            ambiguousComments: report.comments.actionable.map(toAgentComment),
-            changesRequestedReviews: report.changesRequestedReviews,
-            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
-            ...(editedSummaries.length > 0 && { editedSummaries }),
-            ...(pending && { pendingReviewCommands: pending }),
-            suggestion: buildEscalateSuggestion(["bot-cr-not-dismissed"], staleBotCrIds.join(", ")),
-        };
-        return {
-            ...base,
-            action: "escalate",
-            escalate: {
-                ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prReference, {
-                    merge: opts.merge,
-                }),
-            },
-        };
-    }
     const escalateTriggers = countFixCodeAttempt
         ? checkEscalateTriggers(retryableActionableThreads, priorThreadAttempts)
         : { triggers: [], thrashHistory: undefined };
@@ -216,8 +185,9 @@ export async function handleFixCode(ctx) {
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
     const manualFollowUpChecks = failingAgentChecks.filter((check) => !belongsToActiveWorkflowRun(check) && checkRequiresHumanFollowUp(check));
-    const exhaustedAttempts = manualFollowUpChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
-    const hasBehindBaseRecovery = isBehind && exhaustedAttempts.length > 0;
+    const exhaustedAttempts = failingAgentChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
+    const manualExhaustedAttempts = exhaustedAttempts.filter((check) => manualFollowUpChecks.includes(check));
+    const hasBehindBaseRecovery = isBehind && manualExhaustedAttempts.length > 0;
     const hasAutonomousWork = hasConflicts ||
         hasBehindBaseRecovery ||
         threads.length > 0 ||
@@ -235,8 +205,8 @@ export async function handleFixCode(ctx) {
     if (manualFollowUpChecks.length > 0 && !hasAutonomousWork) {
         const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
         const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
-        const checkSuggestion = exhaustedAttempts.length > 0
-            ? `GitHub reports a later workflow attempt (${exhaustedAttempts
+        const checkSuggestion = manualExhaustedAttempts.length > 0
+            ? `GitHub reports a later workflow attempt (${manualExhaustedAttempts
                 .map((check) => `${check.runId ?? check.name}: attempt ${check.runAttempt}`)
                 .join(", ")}), so Shepherd's single rerun allowance is exhausted. Use the included evidence to handle the repeated failure manually before resuming.`
             : buildEscalateSuggestion(["check-follow-up-unavailable"]);
@@ -302,7 +272,14 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0);
+    // Conflicts, and a behind branch whose rerun already failed, both ask for a branch update.
+    const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0)
+        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, report.mergeStatus.mergeRequirements?.stack)
+        : undefined;
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase);
+    if (repairInstructions && repairInstructions.length > 0) {
+        instructions.unshift(...repairInstructions);
+    }
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,

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

@@ -7,6 +7,5 @@ export declare function buildTerminalCancelResult(report: ShepherdReport): Itera
 /** Build completed, non-skipped checks relevant to PR readiness. */
 export declare function buildRelevantChecks(report: ShepherdReport): RelevantCheck[];
 export declare function buildActiveChecks(report: ShepherdReport): ActiveCheck[];
-export declare function getCurrentHeadSha(): Promise<string | null>;
 export declare function buildWaitLog(base: IterateResultBase): string;
 export declare function blockedCancelNote(base: IterateResultBase): string;

package/bin/commands/iterate/helpers.mjs

@@ -1,8 +1,4 @@
-import { execFile as execFileCb } from "node:child_process";
-import { promisify } from "node:util";
-import { getExecutionCwd } from "../../execution-context.mjs";
 import { blockedReasonFromRequirements } from "../../merge-status/requirements-format.mjs";
-const execFile = promisify(execFileCb);
 export function buildSummary(report) {
     return {
         passing: report.checks.passing.length,
@@ -104,17 +100,6 @@ export function buildActiveChecks(report) {
         ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
     }));
 }
-export async function getCurrentHeadSha() {
-    try {
-        const { stdout } = await execFile("git", ["rev-parse", "HEAD"], {
-            cwd: getExecutionCwd(),
-        });
-        return stdout.trim();
-    }
-    catch {
-        return null;
-    }
-}
 export function buildWaitLog(base) {
     const { summary, remainingSeconds } = base;
     const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];

package/bin/commands/iterate/index.mjs

@@ -1,10 +1,10 @@
 /* eslint-disable max-lines */
 import { runCheck } from "../check.mjs";
-import { updateReadyDelay } from "../ready-delay.mjs";
+import { clearReadyDelay, updateReadyDelay } from "../ready-delay.mjs";
 import { getCurrentPrNumber } from "../../github/client.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { EXIT, ShepherdError } from "../../exit-codes.mjs";
-import { getCurrentHeadSha, buildWaitLog, buildTerminalCancelResult, blockedCancelNote, } from "./helpers.mjs";
+import { buildWaitLog, buildTerminalCancelResult, blockedCancelNote } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
@@ -16,6 +16,14 @@ import { buildReadyMergeOutcome, handleActiveMergeState } from "./merge-state.mj
 import { buildIterateBase } from "./base.mjs";
 import { markReadyIfAuthorized } from "./mark-ready.mjs";
 import { withIterateApiUsage } from "./run.mjs";
+import { fetchRawSummaryPr } from "../../github/poll-summary.mjs";
+import { summarizePollSummaryPr } from "../../github/poll-summary-projector.mjs";
+import { fingerprintRawSummaryPr } from "../../github/poll-summary-fingerprint.mjs";
+import { currentQueueRemovalEvent } from "../../github/poll-summary-queue-removal.mjs";
+import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
+import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyReceipt, } from "../../state/ready-receipts.mjs";
+import { findParentMarkReadyBlock, heldByLowerLayer, stackDraftHold } from "./parent-first.mjs";
+import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -43,8 +51,10 @@ async function runIterateCore(opts) {
         throw new ShepherdError(`Unexpected repo format: "${report.repo}" (expected "owner/name")`, EXIT.DATAERR);
     }
     const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
+    const receiptKey = { owner: repoOwner, repo: repoName, pr: report.pr };
     if (report.mergeStatus.state !== "OPEN") {
-        await updateReadyDelay(report.pr, false, readyDelaySeconds, repoOwner, repoName);
+        await clearReadyDelay(report.pr, repoOwner, repoName);
+        await clearReadyReceipt(receiptKey);
         await clearStallState(stallKey);
         return buildTerminalCancelResult(report);
     }
@@ -66,24 +76,40 @@ async function runIterateCore(opts) {
         if (unminimized.length > 0)
             reviewSummaryIds = [...reviewSummaryIds, ...unminimized];
     }
-    const hasActionableWork = report.threads.actionable.length > 0 ||
+    // Hidden PR comments surface once so the agent can acknowledge them, but
+    // they are not readiness evidence: bots keep editing hidden notices after a
+    // PR settles. They never restart the ready-delay or void a READY receipt.
+    const hasReadinessWork = report.threads.actionable.length > 0 ||
         report.threads.resolutionOnly.length > 0 ||
         report.threads.firstLook.length > 0 ||
         (report.threads.ruleAutoResolveIds?.length ?? 0) > 0 ||
         report.comments.actionable.length > 0 ||
         (report.comments.minimizeIds?.length ?? 0) > 0 ||
-        report.comments.firstLook.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
         hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status) ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
         editedSummaries.length > 0 ||
         (config.iterate.minimizeApprovals && surfacedApprovals.length > 0);
+    const hasActionableWork = hasReadinessWork || report.comments.firstLook.length > 0;
     const activeMerge = Boolean(opts.merge && (report.mergeQueue?.inQueue || report.mergeQueue?.autoMergeRequest));
-    const isCleanReadyState = report.status === "READY" && !hasActionableWork && !activeMerge;
-    const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName);
+    const staleAncestry = await findStaleNativeStackAncestry(report, {
+        owner: repoOwner,
+        name: repoName,
+    });
+    const isCleanReadyState = report.status === "READY" &&
+        !report.mergeStatus.isDraft &&
+        !hasReadinessWork &&
+        !activeMerge &&
+        staleAncestry === null;
+    const receiptCurrent = await revalidateReadyReceipt(receiptKey, report, hasReadinessWork);
+    const headSha = report.headSha ?? "unknown";
+    // The elapsed marker survives a hidden-comment acknowledgement tick and is
+    // consumed only when this tick cancels or merges. A receipt that is still
+    // current already proves the delay elapsed for this exact head, base, and
+    // readiness evidence, so a rerun (e.g. with --merge) does not wait again.
+    const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName, { headSha, alreadyElapsed: receiptCurrent });
     const base = buildIterateBase(report, readyState);
-    const headSha = (await getCurrentHeadSha()) ?? "unknown";
     // Checks (including merge-queue synthetic-commit checks) and hard conflicts are signals
     // GitHub itself is already acting on — the queue will eject the PR for these regardless of
     // what Shepherd does, so they always surface immediately. Only review threads/comments/
@@ -126,13 +152,51 @@ async function runIterateCore(opts) {
     });
     if (mergeStateResult)
         return mergeStateResult;
+    if (staleAncestry) {
+        return handleFixCode({
+            base,
+            report,
+            opts: { ...opts, prNumber, neverCancelRuns },
+            headSha,
+            stallKey,
+            prNumber,
+            stallTimeoutSeconds,
+            repoOwner,
+            repoName,
+            reviewSummaryIds,
+            firstLookSummaries,
+            editedSummaries,
+            surfacedApprovals,
+            botUsernames,
+            repairInstructions: staleAncestry.instructions,
+            ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
+        });
+    }
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
         !report.mergeStatus.blockingBotReviewInProgress;
-    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady, base, report);
+    const parentBlock = canMarkReady
+        ? await findParentMarkReadyBlock(report, { owner: repoOwner, name: repoName })
+        : undefined;
+    const autoMarkReady = !opts.noAutoMarkReady && config.actions.autoMarkReady;
+    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !parentBlock && autoMarkReady, base, report);
     if (markReadyResult)
         return markReadyResult;
-    if (readyState.shouldCancel) {
+    if (readyState.shouldCancel && !report.mergeStatus.isDraft) {
+        const receiptWritten = receiptCurrent || (await recordReadyReceipt(receiptKey, report));
+        // Aggregate --stack routing trusts only a layer's receipt, so an unwritten
+        // one keeps the elapsed marker and retries next tick. A one-PR receipt
+        // only lets a rerun skip the wait, so its failure never changes the action.
+        if (!receiptWritten && report.mergeStatus.mergeRequirements?.stack !== undefined) {
+            const receiptWait = {
+                ...base,
+                action: "wait",
+                shouldCancel: false,
+                log: `WAIT: PR #${base.pr} reached ready-delay but its stack readiness receipt could not be persisted`,
+            };
+            return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, receiptWait, report, reviewSummaryIds);
+        }
+        await clearReadyDelay(report.pr, repoOwner, repoName);
         await clearStallState(stallKey);
         const mergeResult = buildReadyMergeOutcome(opts.merge, true, base, report);
         if (mergeResult)
@@ -145,5 +209,108 @@ async function runIterateCore(opts) {
             log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
         };
     }
-    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, { ...base, action: "wait", log: buildWaitLog(base) }, report, reviewSummaryIds);
+    const hold = stackDraftHold(report, autoMarkReady, parentBlock);
+    const wait = {
+        ...base,
+        action: "wait",
+        log: buildWaitLog(base),
+        ...(hold && { stackDraftHold: hold }),
+    };
+    // The lower layer's own session owns progress here, so this draft cannot
+    // stall; its stall clock restarts once that layer releases it.
+    if (heldByLowerLayer(wait)) {
+        await clearStallState(stallKey);
+        return wait;
+    }
+    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, report, reviewSummaryIds);
+}
+async function recordReadyReceipt(key, report) {
+    if (report.status !== "READY" ||
+        report.mergeStatus.state !== "OPEN" ||
+        report.mergeStatus.isDraft ||
+        !report.headSha ||
+        !report.baseRefOid)
+        return false;
+    try {
+        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        const fingerprint = fingerprintRawSummaryPr(raw);
+        if (fingerprint === null ||
+            raw.state !== "OPEN" ||
+            raw.isDraft ||
+            raw.headRefOid !== report.headSha ||
+            raw.baseRefOid !== report.baseRefOid)
+            return false;
+        const summary = await summarizePollSummaryPr(raw, { owner: key.owner, name: key.repo }, { stackPrNumber: report.pr });
+        if (!isCurrentSummaryReady(raw, summary.checks ?? {}, summary.review ?? {}))
+            return false;
+        const removalEvent = currentQueueRemovalEvent(raw);
+        await writeReadyReceipt({
+            version: 1,
+            ...key,
+            headRefOid: raw.headRefOid,
+            baseRefOid: raw.baseRefOid,
+            status: "READY",
+            isDraft: false,
+            readinessFingerprint: fingerprint,
+            ...(removalEvent?.id && {
+                acknowledgedQueueRemovalId: removalEvent.id,
+            }),
+            recordedAtUnix: Math.floor(Date.now() / 1000),
+        });
+        return true;
+    }
+    catch {
+        // The receipt is supplementary evidence. A transient summary fetch or
+        // state-directory failure must not turn a completed one-PR poll into a
+        // different Shepherd action.
+        return false;
+    }
+}
+/** Clear a stale READY receipt; return whether a current receipt remains. */
+async function revalidateReadyReceipt(key, report, hasReadinessWork) {
+    const receipt = await readReadyReceipt(key);
+    if (!receipt)
+        return false;
+    const retainQueuedReceipt = report.mergeQueue?.inQueue === true &&
+        report.mergeStatus.state === "OPEN" &&
+        !report.mergeStatus.isDraft &&
+        Boolean(report.headSha && report.baseRefOid);
+    if (report.mergeStatus.state !== "OPEN" ||
+        report.mergeStatus.isDraft ||
+        !report.headSha ||
+        !report.baseRefOid ||
+        (!retainQueuedReceipt && (report.status !== "READY" || hasReadinessWork))) {
+        await clearReadyReceipt(key);
+        return false;
+    }
+    try {
+        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        // Queue predecessors can advance the target branch without changing this
+        // PR's source. Compare against the receipt's base only while both fresh
+        // views still place the PR in the queue.
+        const queuedBaseAdvanced = retainQueuedReceipt && raw.isInMergeQueue;
+        const fingerprint = fingerprintRawSummaryPr(queuedBaseAdvanced ? { ...raw, baseRefOid: receipt.baseRefOid } : raw);
+        // The fresh snapshot must name the commits this tick evaluated, or the
+        // receipt would vouch for a head or base the report never saw.
+        const sameCommits = raw.headRefOid === report.headSha &&
+            (queuedBaseAdvanced || raw.baseRefOid === report.baseRefOid);
+        if (fingerprint === null ||
+            !sameCommits ||
+            !isReadyReceiptCurrent(receipt, {
+                headRefOid: raw.headRefOid,
+                baseRefOid: queuedBaseAdvanced ? receipt.baseRefOid : raw.baseRefOid,
+                readinessFingerprint: fingerprint,
+                status: "READY",
+                isDraft: raw.isDraft,
+            })) {
+            await clearReadyReceipt(key);
+            return false;
+        }
+        return true;
+    }
+    catch {
+        // Fail closed: an unreadable current snapshot cannot validate old evidence.
+        await clearReadyReceipt(key);
+        return false;
+    }
 }

package/bin/commands/iterate/merge-state.mjs

@@ -2,26 +2,43 @@ import { clearStallState } from "../../state/iterate-stall.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
 import { buildMergeCommandPlan } from "./merge.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
-/** A stacked PR's merge is human-only: `gh pr merge` targets the PR's own base, which for a
- * mid-stack layer is an unmerged parent branch, and auto-merge is unsupported on stacks. */
-function buildStackedEscalateResult(base, report, stack) {
-    const escalateBase = {
-        triggers: ["stacked-pr"],
-        unresolvedThreads: [],
-        ambiguousComments: [],
-        changesRequestedReviews: [],
-        stack,
-        suggestion: buildEscalateSuggestion(["stacked-pr"], String(report.pr)),
-    };
+import { buildPrShepherdCommand } from "../../cli/runner.mjs";
+import { inlineCode } from "../../util/markdown.mjs";
+/**
+ * A one-PR poll cannot prove the layers below it merged or that its PR number is a safe merge
+ * selector. Route it through the aggregate stack selector, which merges one bottom layer at a time.
+ */
+function buildStackedRouteResult(base, report, stack) {
+    const prUrl = formatPrUrl(report.repo, report.pr);
     return {
         ...base,
-        action: "escalate",
-        escalate: {
-            ...escalateBase,
-            humanMessage: buildEscalateHumanMessage(escalateBase, formatPrUrl(report.repo, report.pr), {
-                merge: true,
-            }),
+        action: "fix_code",
+        fix: {
+            threads: [],
+            resolutionOnlyThreads: [],
+            actionableComments: [],
+            reviewSummaryIds: [],
+            firstLookSummaries: [],
+            editedSummaries: [],
+            surfacedApprovals: [],
+            checks: [],
+            changesRequestedReviews: [],
+            resolveCommand: {
+                argv: buildPrShepherdCommand(["apply", "review", prUrl]).argv,
+                requiresHeadSha: false,
+                requiresDismissMessage: false,
+                hasMutations: false,
+            },
+            instructions: [
+                `PR #${report.pr} is layer ${stack.position} of ${stack.size} in native stack #${stack.number}; do not run \`gh pr merge\` for this layer.`,
+                `Run ${inlineCode(buildPrShepherdCommand(["--stack", prUrl, "--until-terminal", "--merge"]).text)} to reconcile the stack and run each bottom-layer merge command it emits.`,
+            ],
+            inProgressRunIds: [],
+            protectedRuns: [],
+            firstLookThreads: [],
+            firstLookComments: [],
         },
+        cancelled: [],
     };
 }
 export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
@@ -29,7 +46,7 @@ export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
         return null;
     const stack = report.mergeStatus.mergeRequirements?.stack;
     if (stack)
-        return buildStackedEscalateResult(base, report, stack);
+        return buildStackedRouteResult(base, report, stack);
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
     return {

package/bin/commands/iterate/native-stack-rebase.d.mts

@@ -0,0 +1,34 @@
+import type { StackStatus } from "../../types.mts";
+/**
+ * Where a native-stack rebase starts: an upper layer rebases from its parent stack branch
+ * without touching trunk; the bottom layer rebases the whole stack onto trunk.
+ */
+export type NativeStackRebaseStart = {
+    parentBranch: string;
+} | {
+    bottomPr: number;
+};
+/**
+ * One gh-stack rebase step. A native stack layer must not be rebased or merged from its base
+ * branch alone: that rewrites one branch and strands every layer above it.
+ *
+ * `gh stack` rebases the stack it tracks locally and `gh stack push` publishes those local
+ * layers, so the step first imports the stack by its number (a bare number resolves as a
+ * stack number before a PR number) and checks each local layer against its PR head.
+ */
+export declare function buildNativeStackRebaseInstruction(repo: string, stackNumber: number, start: NativeStackRebaseStart): string;
+/**
+ * The stack-aware branch update for a native stack layer (a conflict, or a behind branch whose
+ * workflow keeps failing); undefined outside a stack.
+ * A layer whose PR targets the stack's trunk (`stack.baseRefName`) is the bottom open layer —
+ * position 1, or a higher layer GitHub retargeted after every layer below it merged. Any other
+ * layer is an upper layer whose parent is its own PR base branch.
+ */
+export declare function buildNativeStackLayerRebase(repo: string, pr: {
+    number: number;
+    baseBranch: string;
+}, stack: StackStatus | undefined): string | undefined;
+/** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
+export declare function buildConflictInstruction(stackRebase: string | undefined): string;
+/** Push a conflict resolution or branch refresh: one branch, or the whole rewritten native stack. */
+export declare function buildBranchPushInstruction(stackRebase: string | undefined, hasConflicts: boolean, mutationSuffix: string): string;

package/bin/commands/iterate/native-stack-rebase.mjs

@@ -0,0 +1,43 @@
+/**
+ * One gh-stack rebase step. A native stack layer must not be rebased or merged from its base
+ * branch alone: that rewrites one branch and strands every layer above it.
+ *
+ * `gh stack` rebases the stack it tracks locally and `gh stack push` publishes those local
+ * layers, so the step first imports the stack by its number (a bare number resolves as a
+ * stack number before a PR number) and checks each local layer against its PR head.
+ */
+export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
+    const [checkout, command] = "parentBranch" in start
+        ? [
+            `check out the parent stack branch \`${start.parentBranch}\``,
+            "gh stack rebase --upstack --no-trunk",
+        ]
+        : [`check out the head branch of PR #${start.bottomPr}`, "gh stack rebase"];
+    const prepare = `if \`gh stack\` does not track stack #${stackNumber} locally, import it with \`gh stack checkout ${stackNumber}\`, then confirm every layer's local branch is at its PR's head commit — a stale local layer would overwrite that PR's newer commits on push`;
+    return `From a clean checkout of \`${repo}\`, ${prepare}. Then ${checkout} and run \`${command}\`; if it stops on a conflict, resolve it and run \`gh stack rebase --continue\`.`;
+}
+/**
+ * The stack-aware branch update for a native stack layer (a conflict, or a behind branch whose
+ * workflow keeps failing); undefined outside a stack.
+ * A layer whose PR targets the stack's trunk (`stack.baseRefName`) is the bottom open layer —
+ * position 1, or a higher layer GitHub retargeted after every layer below it merged. Any other
+ * layer is an upper layer whose parent is its own PR base branch.
+ */
+export function buildNativeStackLayerRebase(repo, pr, stack) {
+    if (!stack)
+        return undefined;
+    return buildNativeStackRebaseInstruction(repo, stack.number, pr.baseBranch === stack.baseRefName ? { bottomPr: pr.number } : { parentBranch: pr.baseBranch });
+}
+/** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
+export function buildConflictInstruction(stackRebase) {
+    const pointer = "The branch has merge conflicts (see `**branch**` above).";
+    return stackRebase ? `${pointer} ${stackRebase}` : `${pointer} Resolve them before committing.`;
+}
+/** Push a conflict resolution or branch refresh: one branch, or the whole rewritten native stack. */
+export function buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix) {
+    if (stackRebase)
+        return `Commit any remaining changes on the PR head branch and push the rewritten stack with \`gh stack push\`${mutationSuffix}.`;
+    return hasConflicts
+        ? `Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`
+        : "Push the updated PR head branch before iterating immediately.";
+}

package/bin/commands/iterate/parent-first.d.mts

@@ -0,0 +1,25 @@
+import type { RepoInfo } from "../../github/client.mts";
+import type { IterateResult, ShepherdReport, StackDraftHold, StackLowerLayerBlock } from "../../types.mts";
+/**
+ * What keeps a draft child from being marked ready: the lowest blocking lower layer,
+ * or a stack read that could not attribute the block to one.
+ */
+export type ParentMarkReadyBlock = StackLowerLayerBlock | "unverifiable";
+/**
+ * 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 declare function findParentMarkReadyBlock(report: ShepherdReport, repo: RepoInfo): Promise<ParentMarkReadyBlock | undefined>;
+/**
+ * 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 declare function stackDraftHold(report: ShepherdReport, autoMarkReady: boolean, parentBlock: ParentMarkReadyBlock | undefined): StackDraftHold | undefined;
+/**
+ * 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 declare function heldByLowerLayer(result: IterateResult): StackLowerLayerBlock | undefined;