pr-shepherd 0.52.0 → 0.52.1

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";
@@ -22,7 +22,7 @@ import { fingerprintRawSummaryPr } from "../../github/poll-summary-fingerprint.m
 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 { parentBlocksMarkReady } from "./parent-first.mjs";
+import { findParentMarkReadyBlock, heldByLowerLayer, stackDraftHold } from "./parent-first.mjs";
 import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
@@ -51,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);
     }
@@ -74,19 +76,22 @@ 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 staleAncestry = await findStaleNativeStackAncestry(report, {
         owner: repoOwner,
@@ -94,15 +99,17 @@ async function runIterateCore(opts) {
     });
     const isCleanReadyState = report.status === "READY" &&
         !report.mergeStatus.isDraft &&
-        !hasActionableWork &&
+        !hasReadinessWork &&
         !activeMerge &&
         staleAncestry === null;
-    const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName);
-    if (report.mergeStatus.mergeRequirements?.stack) {
-        await invalidateStaleReadyReceipt({ owner: repoOwner, repo: repoName, pr: report.pr }, report, hasActionableWork);
-    }
+    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/
@@ -168,27 +175,28 @@ async function runIterateCore(opts) {
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
         !report.mergeStatus.blockingBotReviewInProgress;
-    const blockedByParent = canMarkReady
-        ? await parentBlocksMarkReady(report, { owner: repoOwner, name: repoName })
-        : false;
-    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !blockedByParent && !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 && !report.mergeStatus.isDraft) {
-        const needsStackReceipt = report.mergeStatus.mergeRequirements?.stack !== undefined;
-        const receiptWritten = needsStackReceipt
-            ? await recordReadyReceipt({ owner: repoOwner, repo: repoName, pr: report.pr }, report)
-            : true;
-        if (!receiptWritten) {
+        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,
-                remainingSeconds: readyDelaySeconds,
                 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)
@@ -201,7 +209,20 @@ 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" ||
@@ -245,10 +266,11 @@ async function recordReadyReceipt(key, report) {
         return false;
     }
 }
-async function invalidateStaleReadyReceipt(key, report, hasActionableWork) {
+/** 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;
+        return false;
     const retainQueuedReceipt = report.mergeQueue?.inQueue === true &&
         report.mergeStatus.state === "OPEN" &&
         !report.mergeStatus.isDraft &&
@@ -257,9 +279,9 @@ async function invalidateStaleReadyReceipt(key, report, hasActionableWork) {
         report.mergeStatus.isDraft ||
         !report.headSha ||
         !report.baseRefOid ||
-        (!retainQueuedReceipt && (report.status !== "READY" || hasActionableWork))) {
+        (!retainQueuedReceipt && (report.status !== "READY" || hasReadinessWork))) {
         await clearReadyReceipt(key);
-        return;
+        return false;
     }
     try {
         const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
@@ -268,7 +290,12 @@ async function invalidateStaleReadyReceipt(key, report, hasActionableWork) {
         // 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,
@@ -277,10 +304,13 @@ async function invalidateStaleReadyReceipt(key, report, hasActionableWork) {
                 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,9 +2,11 @@ import { clearStallState } from "../../state/iterate-stall.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
 import { buildMergeCommandPlan } from "./merge.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
+import { buildPrShepherdCommand } from "../../cli/runner.mjs";
+import { inlineCode } from "../../util/markdown.mjs";
 /**
- * A one-PR poll cannot prove every native-stack layer is ready or linear. Route it through the
- * aggregate stack selector, which does that reconciliation before emitting the whole-stack merge.
+ * 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);
@@ -22,14 +24,14 @@ function buildStackedRouteResult(base, report, stack) {
             checks: [],
             changesRequestedReviews: [],
             resolveCommand: {
-                argv: ["pr-shepherd", "apply", "review", prUrl],
+                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 \`pr-shepherd --stack ${prUrl} --until-terminal --merge\` to reconcile the complete stack and run its emitted whole-stack merge command.`,
+                `Run ${inlineCode(buildPrShepherdCommand(["--stack", prUrl, "--until-terminal", "--merge"]).text)} to reconcile the stack and run each bottom-layer merge command it emits.`,
             ],
             inProgressRunIds: [],
             protectedRuns: [],

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

@@ -1,9 +1,25 @@
 import type { RepoInfo } from "../../github/client.mts";
-import type { ShepherdReport } from "../../types.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 parentBlocksMarkReady(report: ShepherdReport, repo: RepoInfo): Promise<boolean>;
+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;

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

@@ -1,16 +1,17 @@
 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 parentBlocksMarkReady(report, repo) {
+export async function findParentMarkReadyBlock(report, repo) {
     const stack = report.mergeStatus.mergeRequirements?.stack;
     if (!stack || stack.position === 1)
-        return false;
+        return undefined;
     if (stack.position < 1)
-        return true;
+        return "unverifiable";
     try {
         const summary = await fetchPollSummary({ stackPrNumber: report.pr }, repo);
         const child = summary.prs.find((item) => item.pr === report.pr);
@@ -19,39 +20,51 @@ export async function parentBlocksMarkReady(report, repo) {
             .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 true;
-        // Any stale boundary up through the child means at least one lower layer
-        // is no longer the base it was reviewed against. Ignore gaps above this
-        // child because they do not affect its immediate promotion boundary.
-        const checkedLayers = new Set([report.pr, ...lowerLayers.map((item) => item.pr)]);
-        if (summary.stackAncestry?.some((gap) => checkedLayers.has(gap.childPr)))
-            return true;
-        for (const parent of lowerLayers) {
-            // A merged parent is already satisfied; GitHub may have retargeted the
-            // child to the trunk as part of the merge.
-            if (parent.state === "MERGED")
+            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;
-            if (parent.state !== "OPEN")
-                return true;
-            if (parent.isDraft || parent.mergeable === "CONFLICTING")
-                return true;
-            if (["DIRTY", "BEHIND", "UNKNOWN"].includes(parent.mergeStateStatus))
-                return true;
-            // 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 (parent.queueRemoval)
-                return true;
-            // A parent that looks ready but has not completed its own one-PR receipt
-            // is not sufficient evidence for a child draft transition.
-            if (parent.readyReceipt !== true)
-                return true;
+            const reason = staleChildren.has(layer.pr) ? "stale-ancestry" : stackLayerBlockReason(layer);
+            if (reason)
+                return { pr: layer.pr, reason };
         }
-        return false;
+        // 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 true;
+        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

@@ -4,7 +4,7 @@ import type { ShepherdReport } from "../../types/report.mts";
 /**
  * A verified stale boundary for the PR being shepherded.
  *
- * The aggregate stack read is authoritative for this check: it compares the
+ * 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.
  */

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

@@ -1,4 +1,5 @@
-import { fetchPollSummary } from "../../github/poll-summary.mjs";
+import { readStackTopology, stackAncestryGaps } from "../../github/stack-read.mjs";
+import { buildNativeStackRebaseInstruction } from "./native-stack-rebase.mjs";
 /**
  * Find a stale immediate parent boundary for one PR.
  *
@@ -12,13 +13,13 @@ export async function findStaleNativeStackAncestry(report, repo) {
     if (!stack || stack.position <= 1)
         return null;
     try {
-        const summary = await fetchPollSummary({ stackPrNumber: report.pr }, repo);
-        const ancestry = summary.stackAncestry?.find((gap) => gap.childPr === report.pr);
+        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, ancestry),
+            instructions: buildStaleNativeStackAncestryInstructions(repo, stack.number, ancestry),
         };
     }
     catch {
@@ -28,10 +29,12 @@ export async function findStaleNativeStackAncestry(report, repo) {
     }
 }
 /** Build the one-PR repair guidance after a stale boundary was verified. */
-function buildStaleNativeStackAncestryInstructions(repo, ancestry) {
+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}\`.`,
-        `From a clean checkout of \`${repo.owner}/${repo.name}\`, check out the parent stack branch \`${ancestry.parentHeadRefName}\`.`,
-        "Run `gh stack rebase --upstack --no-trunk`, resolve any conflicts, and push the rewritten stack with `gh stack push`.",
+        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 {};