pr-shepherd 0.56.5 → 0.57.0

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

@@ -0,0 +1,88 @@
+import { loadConfig } from "../../config/load.mjs";
+import { findMergeStrategies } from "../../config/merge-command-args.mjs";
+import { chooseMergeMethod, configuredMergeMethod, } from "../../config/merge-method.mjs";
+import { formatPrUrl } from "../../pr-reference.mjs";
+import { buildPrShepherdCommand } from "../../cli/runner.mjs";
+import { getGithubTransport } from "../../github/transport.mjs";
+const ENQUEUE_MUTATION = "mutation EnqueuePullRequest($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: { pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid }) { mergeQueueEntry { id } } }";
+export function buildMergeCommandPlan(input) {
+    if (input.transport === "rest" || getGithubTransport() === "rest") {
+        const configured = configuredMergeMethod(loadConfig().merge ?? {});
+        if (!input.queue && input.queueKnown !== true && configured)
+            return {
+                unavailable: "REST cannot verify merge-queue policy and cannot apply a configured direct merge method to an automatic merge request. Refresh branch policy before merging.",
+            };
+        let method;
+        if (!input.queue && input.queueKnown === true) {
+            const decision = chooseMergeMethod({
+                allowed: input.allowedMergeMethods,
+                configured,
+                fallback: "merge",
+            });
+            if ("unavailable" in decision)
+                return decision;
+            method = decision.method;
+        }
+        return {
+            mode: "rest",
+            command: buildPrShepherdCommand([
+                "apply",
+                "merge",
+                formatPrUrl(input.repo, input.pr),
+                "--require-sha",
+                input.headSha,
+                "--merge-action",
+                input.queue ? "merge_queue" : input.queueKnown ? "direct_merge" : "default",
+                ...(method ? ["--method", method] : []),
+                ...(input.expectedStack ? ["--expected-stack", JSON.stringify(input.expectedStack)] : []),
+                "--transport",
+                "rest",
+            ]),
+        };
+    }
+    const base = [
+        "gh",
+        "pr",
+        "merge",
+        String(input.pr),
+        "--repo",
+        input.repo,
+        "--match-head-commit",
+        input.headSha,
+    ];
+    if (input.queue) {
+        return {
+            mode: "queue",
+            command: { argv: base },
+            queueApiFallbackCommand: {
+                argv: [
+                    "gh",
+                    "api",
+                    "graphql",
+                    "-f",
+                    `query=${ENQUEUE_MUTATION}`,
+                    "-f",
+                    `pullRequestId=${input.nodeId}`,
+                    "-f",
+                    `expectedHeadOid=${input.headSha}`,
+                ],
+            },
+        };
+    }
+    const mergeConfig = loadConfig().merge;
+    const configuredArgs = mergeConfig?.commandArgs ?? [];
+    const decision = chooseMergeMethod({
+        allowed: input.allowedMergeMethods,
+        configured: configuredMergeMethod(mergeConfig ?? {}),
+        fallback: "merge",
+    });
+    if ("unavailable" in decision)
+        return decision;
+    const hasStrategy = findMergeStrategies(configuredArgs).length > 0;
+    const commandArgs = hasStrategy ? configuredArgs : [...configuredArgs, `--${decision.method}`];
+    return {
+        mode: "auto",
+        command: { argv: [...base, "--auto", ...commandArgs] },
+        fallbackCommand: { argv: [...base, ...commandArgs] },
+    };
+}

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

@@ -51,10 +51,13 @@ export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
     const plan = buildMergeCommandPlan({
         pr: report.pr,
+        ...(report.transport && { transport: report.transport }),
         repo: report.repo,
         nodeId: report.nodeId,
         headSha: report.headSha ?? "unknown",
         queue,
+        queueKnown: (report.transport !== "rest" || report.branchProtection === null) &&
+            !(report.transportUnavailable ?? []).some(({ field }) => ["branchProtection", "branchRules"].includes(field)),
         ...(report.allowedMergeMethods && { allowedMergeMethods: report.allowedMergeMethods }),
     });
     if ("unavailable" in plan)

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

@@ -1,29 +1,18 @@
-import { type MergeMethod } from "../../config/merge-method.mts";
+export { buildMergeCommandPlan } from "./merge-plan.mts";
 import type { AgentCheck, IterateResult, IterateResultBase, MergeCommandPlan, ShepherdReport } from "../../types.mts";
-interface MergePlanInput {
-    pr: number;
-    repo: string;
-    nodeId: string;
-    headSha: string;
-    queue: boolean;
-    /** Omitted when the batch did not select repository merge settings. */
-    allowedMergeMethods?: readonly MergeMethod[];
-}
-export interface MergeMethodUnavailable {
+interface QueueRecoveryUnavailable {
     unavailable: string;
 }
-export declare function buildMergeCommandPlan(input: MergePlanInput): MergeCommandPlan | MergeMethodUnavailable;
 export declare function renderMergeCommand(command: {
     argv: string[];
 }): string;
 /** Offer a guarded queue command; the caller decides whether the failure warrants a PR fix. */
-export declare function buildRemovedQueueRecovery(report: ShepherdReport, checks: AgentCheck[], merge: boolean | undefined): MergeCommandPlan | undefined;
+export declare function buildRemovedQueueRecovery(report: ShepherdReport, checks: AgentCheck[], merge: boolean | undefined): MergeCommandPlan | QueueRecoveryUnavailable | undefined;
 /** Bind a caller's disposition to one removed stack queue commit, without submitting a merge. */
 export declare function buildStackQueueRemovalAcknowledgment(report: ShepherdReport, checks: AgentCheck[]): {
     argv: string[];
-} | undefined;
+} | QueueRecoveryUnavailable | undefined;
 export declare function unavailableMergeResult(base: IterateResultBase, report: {
     pr: number;
     repo: string;
 }, unavailable: string): IterateResult;
-export {};

package/bin/commands/iterate/merge.mjs

@@ -1,59 +1,11 @@
-import { loadConfig } from "../../config/load.mjs";
-import { findMergeStrategies } from "../../config/merge-command-args.mjs";
-import { chooseMergeMethod, configuredMergeMethod, } from "../../config/merge-method.mjs";
+import { buildMergeCommandPlan } from "./merge-plan.mjs";
+export { buildMergeCommandPlan } from "./merge-plan.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 import { renderShellCommand, buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { hasQueueRecoveryEvidence } from "./check-evidence.mjs";
 import { isCiQueueRemovalReason } from "../../state/queue-removal-ack.mjs";
 import { buildEscalateHumanMessage } from "./escalate.mjs";
-const ENQUEUE_MUTATION = "mutation EnqueuePullRequest($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: { pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid }) { mergeQueueEntry { id } } }";
-export function buildMergeCommandPlan(input) {
-    const base = [
-        "gh",
-        "pr",
-        "merge",
-        String(input.pr),
-        "--repo",
-        input.repo,
-        "--match-head-commit",
-        input.headSha,
-    ];
-    if (input.queue) {
-        return {
-            mode: "queue",
-            command: { argv: base },
-            queueApiFallbackCommand: {
-                argv: [
-                    "gh",
-                    "api",
-                    "graphql",
-                    "-f",
-                    `query=${ENQUEUE_MUTATION}`,
-                    "-f",
-                    `pullRequestId=${input.nodeId}`,
-                    "-f",
-                    `expectedHeadOid=${input.headSha}`,
-                ],
-            },
-        };
-    }
-    const mergeConfig = loadConfig().merge;
-    const configuredArgs = mergeConfig?.commandArgs ?? [];
-    const decision = chooseMergeMethod({
-        allowed: input.allowedMergeMethods,
-        configured: configuredMergeMethod(mergeConfig ?? {}),
-        fallback: "merge",
-    });
-    if ("unavailable" in decision)
-        return decision;
-    const hasStrategy = findMergeStrategies(configuredArgs).length > 0;
-    const commandArgs = hasStrategy ? configuredArgs : [...configuredArgs, `--${decision.method}`];
-    return {
-        mode: "auto",
-        command: { argv: [...base, "--auto", ...commandArgs] },
-        fallbackCommand: { argv: [...base, ...commandArgs] },
-    };
-}
+import { getGithubTransport } from "../../github/transport.mjs";
 export function renderMergeCommand(command) {
     return renderShellCommand(command.argv);
 }
@@ -63,6 +15,11 @@ export function buildRemovedQueueRecovery(report, checks, merge) {
         return undefined;
     if (!removedQueueRecoveryAvailable(report, checks, merge))
         return undefined;
+    // REST cannot prove that a recorded enqueue was removed or that no later enqueue exists.
+    // Never offer a resume command as if it could authorize a fresh same-head submission.
+    const unsupported = unsupportedRestQueueRecovery(report);
+    if (unsupported)
+        return unsupported;
     const plan = buildMergeCommandPlan({
         pr: report.pr,
         repo: report.repo,
@@ -79,6 +36,9 @@ export function buildStackQueueRemovalAcknowledgment(report, checks) {
     // This records a local disposition, without enqueueing; aggregate child sessions omit --merge.
     if (!removedQueueRecoveryAvailable(report, checks, true))
         return undefined;
+    const unsupported = unsupportedRestQueueRecovery(report);
+    if (unsupported)
+        return unsupported;
     const removal = report.mergeQueue.latestRemoval;
     return buildPrShepherdCommand([
         "apply",
@@ -92,6 +52,13 @@ export function buildStackQueueRemovalAcknowledgment(report, checks) {
         String(removal.createdAtUnix),
     ]);
 }
+function unsupportedRestQueueRecovery(report) {
+    if (report.transport !== "rest" && getGithubTransport() !== "rest")
+        return undefined;
+    return {
+        unavailable: "Queue recovery is transport-unsupported: REST cannot verify current merge-queue removal evidence. Continue the printed fix steps; requeue and removal acknowledgment require verified current removal evidence.",
+    };
+}
 function removedQueueRecoveryAvailable(report, checks, merge) {
     const queue = report.mergeQueue;
     const removedCommit = queue?.latestRemoval?.beforeCommitOid;

package/bin/commands/iterate/merged-base-pull-requests.d.mts

@@ -1,8 +1,4 @@
 import type { MergedBasePullRequest } from "../../types.mts";
+import { type MergedBaseLookupInput } from "../../github/rest-merged-base-read.mts";
 /** A bounded, best-effort lookup; matching OIDs and repository prevent branch-name reuse false positives. */
-export declare function lookupMergedBasePullRequests(input: {
-    owner: string;
-    repo: string;
-    baseRefName: string;
-    baseRefOid: string;
-}): Promise<MergedBasePullRequest[]>;
+export declare function lookupMergedBasePullRequests(input: MergedBaseLookupInput): Promise<MergedBasePullRequest[]>;

package/bin/commands/iterate/merged-base-pull-requests.mjs

@@ -1,22 +1,26 @@
 import { graphql } from "../../github/client.mjs";
 import { MERGED_BASE_PULL_REQUESTS_QUERY } from "../../github/queries.mjs";
 import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
+import { githubOperation, isGithubReadFallbackError } from "../../github/transport.mjs";
+import { readRestMergedBasePullRequests, } from "../../github/rest-merged-base-read.mjs";
 /** A bounded, best-effort lookup; matching OIDs and repository prevent branch-name reuse false positives. */
 export async function lookupMergedBasePullRequests(input) {
     try {
-        const { data } = await graphql(MERGED_BASE_PULL_REQUESTS_QUERY, {
-            owner: input.owner,
-            repo: input.repo,
-            branch: input.baseRefName,
-        });
-        return (data.repository?.pullRequests.nodes ?? []).filter((candidate) => candidate !== null &&
-            candidate.state === "MERGED" &&
-            candidate.headRefName === input.baseRefName &&
-            candidate.headRefOid === input.baseRefOid &&
-            candidate.headRepository?.nameWithOwner === `${input.owner}/${input.repo}`);
+        return await githubOperation("MergedBasePullRequests", async () => {
+            const { data } = await graphql(MERGED_BASE_PULL_REQUESTS_QUERY, {
+                owner: input.owner,
+                repo: input.repo,
+                branch: input.baseRefName,
+            });
+            return (data.repository?.pullRequests.nodes ?? []).filter((candidate) => candidate !== null &&
+                candidate.state === "MERGED" &&
+                candidate.headRefName === input.baseRefName &&
+                candidate.headRefOid === input.baseRefOid &&
+                candidate.headRepository?.nameWithOwner === `${input.owner}/${input.repo}`);
+        }, () => readRestMergedBasePullRequests(input));
     }
     catch (error) {
-        if (pollRateLimitRetryAfterMs(error) !== null)
+        if (pollRateLimitRetryAfterMs(error) !== null || isGithubReadFallbackError(error))
             throw error;
         process.stderr.write(`pr-shepherd: merged-base PR lookup unavailable (ignored): ${error instanceof Error ? error.message : String(error)}\n`);
         return [];

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

@@ -22,10 +22,11 @@ export declare function buildNativeStackRebaseInstruction(repo: string, stackNum
 /**
  * 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. `trunkConflict` means that
- * upper layer already contains its parent, so the rebase starts at the bottom open layer.
+ * The first open layer in validated stack order is the bottom open layer, even when GitHub
+ * retains its merged parent's branch as its PR base. Without that topology, a PR base matching
+ * the stack trunk also identifies a bottom layer. Other layers rebase from their PR base.
+ * `trunkConflict` means an upper layer already contains its parent, so the rebase starts
+ * at the bottom open layer.
  */
 export declare function buildNativeStackLayerRebase(repo: string, pr: {
     number: number;
@@ -33,7 +34,7 @@ export declare function buildNativeStackLayerRebase(repo: string, pr: {
 }, stack: StackStatus | undefined, trunkConflict?: {
     trunk: string;
     bottomPr?: number;
-}): string | undefined;
+}, stackBottomPr?: number): 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;
 /**

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

@@ -1,4 +1,5 @@
 import { playbookPointer } from "../playbook-pointer.mjs";
+import { getGithubTransport } from "../../github/transport.mjs";
 /**
  * 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.
@@ -8,6 +9,14 @@ import { playbookPointer } from "../playbook-pointer.mjs";
  * stack number before a PR number) and checks each local layer against its PR head.
  */
 export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
+    if (getGithubTransport() === "rest") {
+        const boundary = "parentBranch" in start
+            ? `parent branch \`${start.parentBranch}\``
+            : "trunk" in start
+                ? `trunk \`${start.trunk}\``
+                : `bottom open layer PR #${start.bottomPr}`;
+        return `Use the repository's stack-update procedure for native stack #${stackNumber} in \`${repo}\`, starting at ${boundary} and preserving the ordered parent boundaries of every affected upper layer. Read membership with REST-backed Shepherd \`--stack\` output and update and push affected branches using the caller's git workflow. ${playbookPointer("Branch update")}`;
+    }
     const [checkout, command] = "parentBranch" in start
         ? [
             `check out the parent stack branch \`${start.parentBranch}\``,
@@ -15,26 +24,32 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
         ]
         : "bottomPr" in start
             ? [`check out the head branch of PR #${start.bottomPr}`, "gh stack rebase"]
-            : [`check out the bottom open layer whose base is \`${start.trunk}\``, "gh stack rebase"];
+            : [
+                `check out the bottom open layer of the stack to rebase onto \`${start.trunk}\``,
+                "gh stack rebase",
+            ];
     const prepare = `if \`gh stack\` does not track stack #${stackNumber} locally, import it with \`gh stack checkout ${stackNumber}\``;
     return `From a clean checkout of \`${repo}\`, ${prepare}. Then ${checkout} and run \`${command}\`. ${playbookPointer("Branch update")}`;
 }
 /**
  * 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. `trunkConflict` means that
- * upper layer already contains its parent, so the rebase starts at the bottom open layer.
+ * The first open layer in validated stack order is the bottom open layer, even when GitHub
+ * retains its merged parent's branch as its PR base. Without that topology, a PR base matching
+ * the stack trunk also identifies a bottom layer. Other layers rebase from their PR base.
+ * `trunkConflict` means an upper layer already contains its parent, so the rebase starts
+ * at the bottom open layer.
  */
-export function buildNativeStackLayerRebase(repo, pr, stack, trunkConflict) {
+export function buildNativeStackLayerRebase(repo, pr, stack, trunkConflict, stackBottomPr) {
     if (!stack)
         return undefined;
     const start = trunkConflict
         ? trunkConflict.bottomPr !== undefined
             ? { bottomPr: trunkConflict.bottomPr }
             : { trunk: trunkConflict.trunk }
-        : pr.baseBranch === stack.baseRefName
+        : (stackBottomPr !== undefined
+            ? pr.number === stackBottomPr
+            : pr.baseBranch === stack.baseRefName)
             ? { bottomPr: pr.number }
             : { parentBranch: pr.baseBranch };
     return buildNativeStackRebaseInstruction(repo, stack.number, start);
@@ -49,6 +64,8 @@ export function buildConflictInstruction(stackRebase) {
  * After a merge-queue ejection update, push only when the update or a fix changed the head.
  */
 export function buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix, ejectionUpdate = false) {
+    if (stackRebase && getGithubTransport() === "rest")
+        return `If the base update or a fix changed any heads, commit the remaining changes and push every affected stack branch using the repository's stack-update procedure${mutationSuffix}. If no heads changed, do not push.`;
     if (ejectionUpdate) {
         const push = stackRebase
             ? "commit any remaining changes on the PR head branch and push the rewritten stack with `gh stack push`"

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

@@ -1,7 +1,13 @@
 import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, FirstLookThread, FirstLookComment, ReviewThread } from "../../types.mts";
 import { type QueueEjectionRecovery } from "./queue-recovery-instructions.mts";
-/** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
+import type { InstructionStyle } from "../../config/load.mts";
+/**
+ * Render a resolve command as a shell snippet. Appends `--require-sha HEAD` when set: run after
+ * the push step, the local HEAD is the pushed PR head, and `apply review` rejects the mutations
+ * if it is not. `apply review` reads that HEAD itself with a read-only `git rev-parse HEAD`.
+ */
 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, stackRebase?: string, // native stack layers rebase with gh-stack, not branch by branch
-queueEjection?: QueueEjectionRecovery): string[];
+queueEjection?: QueueEjectionRecovery, // current merge-queue removal with failing queue checks
+instructionStyle?: InstructionStyle): string[];

package/bin/commands/iterate/render.mjs

@@ -1,23 +1,28 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
 import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildRepeatedWorkflowBranchRecoveryInstructions, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
-import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
+import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE } from "../shepherd-journal.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
-import { partitionFixThreads, reviewSectionRefs } from "./fix-instruction-threads.mjs";
+import { partitionFixThreads } from "./fix-instruction-threads.mjs";
 import { buildBranchPushInstruction, buildConflictInstruction } from "./native-stack-rebase.mjs";
 import { queueEjectionSteps } from "./queue-recovery-instructions.mjs";
-/** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
+import { buildPushJournalSteps } from "./fix-loop-instruction.mjs";
+/**
+ * Render a resolve command as a shell snippet. Appends `--require-sha HEAD` when set: run after
+ * the push step, the local HEAD is the pushed PR head, and `apply review` rejects the mutations
+ * if it is not. `apply review` reads that HEAD itself with a read-only `git rev-parse HEAD`.
+ */
 export function renderResolveCommand(rc) {
-    const parts = [...rc.argv];
-    if (rc.requiresHeadSha)
-        parts.push("--require-sha", "$HEAD_SHA");
-    return renderShellCommand(parts);
+    const command = renderShellCommand(rc.argv);
+    return rc.requiresHeadSha ? `${command} ${REQUIRE_HEAD_SHA}` : command;
 }
+const REQUIRE_HEAD_SHA = "--require-sha HEAD";
 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, stackRebase, // native stack layers rebase with gh-stack, not branch by branch
-queueEjection) {
+queueEjection, // current merge-queue removal with failing queue checks
+instructionStyle = "inline") {
     const instructions = [];
-    const { locatedThreads, unlocatedMutatedThreads, unlocatedThreads } = partitionFixThreads(threads, resolveCommand, resolveOnlyCommand);
+    const { locatedThreads, unlocatedThreads } = partitionFixThreads(threads, resolveCommand, resolveOnlyCommand);
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
     const repeatedWorkflowBranchRecoveryInstructions = buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, { isBehind, hasConflicts }, stackRebase);
     const hasRepeatedWorkflowBranchRecovery = repeatedWorkflowBranchRecoveryInstructions.length > 0;
@@ -28,18 +33,8 @@ queueEjection) {
         changesRequestedReviews.length > 0 ||
         actionableComments.length > 0;
     // Start with interpretation. The agent decides what raw feedback warrants a code change.
-    if (hasNonConflictHints) {
-        const actionableSections = reviewSectionRefs({
-            hasReviewThreads: locatedThreads.length > 0 || unlocatedMutatedThreads.length > 0,
-            hasUnlocatedSkipThreads: unlocatedThreads.length > 0,
-            hasActionableComments: actionableComments.length > 0,
-            hasFailingChecks: failingChecks.length > 0,
-            hasAnnotations,
-            hasChangesRequested: changesRequestedReviews.length > 0,
-        });
-        const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
-        instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
-    }
+    if (hasNonConflictHints)
+        instructions.push("Fix each warranted item.");
     // A conflicting native stack layer follows the printed gh-stack route, so it omits the hint.
     const branchUpdateHint = buildBehindBaseHintInstruction(baseBranch, behindBaseHint, {
         isBehind,
@@ -66,41 +61,32 @@ queueEjection) {
     const hasSuggestions = locatedThreads.some((t) => t.suggestion);
     if (hasSuggestions)
         instructions.push(buildCommitSuggestionInstruction(prReference, "## Review threads"));
-    if (locatedThreads.length > 0 || actionableComments.length > 0) {
-        // Actionable comments carry no file/line location (unlike threads), so "referenced above"
-        // is only accurate when threads are present.
-        const filesRef = locatedThreads.length > 0 ? "each file referenced above" : "the relevant files";
-        instructions.push(`Apply every warranted review fix in ${filesRef}.`);
-    }
     if (resolutionOnlyThreads.length > 0)
         instructions.push("Review the threads under `## Review threads to resolve` before running the generated mutations.");
     instructions.push(...buildFailingCheckInstructions(failingChecks), ...repeatedWorkflowBranchRecoveryInstructions, ...queueEjectionSteps(queueEjection, stackRebase, branchRecovery));
     if (hasAnnotations)
         instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.");
-    if (changesRequestedReviews.length > 0) {
-        const staleClause = buildCrStaleClause(changesRequestedReviews);
-        instructions.push(`Read every body under \`## Changes-requested reviews\` and apply any warranted change.${staleClause}`);
-    }
+    // The first step already covers applying changes-requested bodies; only stale CRs add a step.
+    const staleClause = buildCrStaleClause(changesRequestedReviews);
+    if (staleClause)
+        instructions.push(staleClause);
     if (!hintWithConflictStep)
         instructions.push(...branchUpdateHint);
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
-    if (branchRecovery || queueEjection) {
-        instructions.push(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix, !branchRecovery));
-    }
-    else if (hasNonConflictHints) {
-        instructions.push("If you changed code, commit any remaining changes and push to the PR head branch. If you did not, do not commit.");
-    }
-    if (viewerCanUpdate &&
+    const genericPush = !(branchRecovery || queueEjection) && hasNonConflictHints;
+    const wantsJournal = viewerCanUpdate &&
         (hasReviewMutations ||
             hasNonConflictHints ||
             firstLookTotal > 0 ||
             firstLookSummaries.length > 0 ||
-            editedTotal > 0)) {
-        instructions.push(buildShepherdJournalInstruction(prReference));
+            editedTotal > 0);
+    if (branchRecovery || queueEjection) {
+        instructions.push(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix, !branchRecovery));
     }
+    instructions.push(...buildPushJournalSteps(instructionStyle, prReference, genericPush, wantsJournal));
     if (resolveOnlyCommand?.hasMutations)
-        instructions.push("Run the `resolve-only:` command shown above.");
-    instructions.push(...buildResolveCommandInstruction(resolveCommand), buildFixCompletionInstruction());
+        instructions.push(`Run: \`${renderResolveCommand(resolveOnlyCommand)}\``);
+    instructions.push(...buildResolveCommandInstruction(resolveCommand, renderResolveCommand(resolveCommand)), buildFixCompletionInstruction());
     return instructions;
 }

package/bin/commands/iterate/stack-trunk-conflict.d.mts

@@ -1,7 +1,7 @@
-/** An upper layer already contains its parent, so the dirty state is against trunk. */
+/** A bottom open layer, or an upper layer that already contains its parent, updates from trunk. */
 export interface UpperLayerTrunkConflict {
     trunk: string;
-    /** Open layer whose PR base is the trunk. Omitted when that layer is not on this page. */
+    /** First open layer after a verified merged prefix. Omitted when topology is unavailable. */
     bottomPr?: number;
 }
 export declare function lookupUpperLayerTrunkConflict(input: {
@@ -10,4 +10,6 @@ export declare function lookupUpperLayerTrunkConflict(input: {
     pr: number;
     headRef: string;
     trunk: string;
+    /** Reuse the bottom layer already resolved for the report, avoiding a topology fetch. */
+    bottomPr?: number;
 }): Promise<UpperLayerTrunkConflict | undefined>;

package/bin/commands/iterate/stack-trunk-conflict.mjs

@@ -1,25 +1,57 @@
 import { graphql } from "../../github/client.mjs";
+import { readStackTopology, verifiedBottomOpenLayer } from "../../github/stack-read.mjs";
 import { UPPER_LAYER_CONFLICT_TARGET_QUERY } from "../../github/queries.mjs";
 import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
-/** Lowest-position open layer whose base is the stack trunk, if this page contains one. */
-function selectBottomOpenLayer(nodes, trunk) {
-    const onTrunk = nodes.flatMap((node) => {
-        const pull = node?.pullRequest;
-        if (!node || !pull || pull.state !== "OPEN" || pull.baseRefName !== trunk)
-            return [];
-        return [{ position: node.position, number: pull.number }];
-    });
-    onTrunk.sort((a, b) => a.position - b.position);
-    return onTrunk[0]?.number;
-}
+import { githubOperation } from "../../github/transport.mjs";
+import { readRestPull } from "../../github/rest-pr-core.mjs";
+import { readRestBehind } from "../../github/rest-check-read.mjs";
 export async function lookupUpperLayerTrunkConflict(input) {
+    let bottomPr = input.bottomPr;
+    if (bottomPr === undefined) {
+        let topology;
+        try {
+            topology = await readStackTopology(input.pr, { owner: input.owner, name: input.name });
+        }
+        catch (err) {
+            if (pollRateLimitRetryAfterMs(err) !== null)
+                throw err;
+            ignore(input.pr, err instanceof Error ? err.message : String(err));
+        }
+        if (topology) {
+            try {
+                bottomPr = verifiedBottomOpenLayer(topology.ordered, input.pr).number;
+            }
+            catch (err) {
+                ignore(input.pr, err instanceof Error ? err.message : String(err));
+                // A base comparison cannot prove that a closed or unverified predecessor merged.
+                return undefined;
+            }
+        }
+    }
+    // Merged lower layers need not cause GitHub to retarget this PR to trunk. Even when its
+    // head is behind that old parent branch, the first open layer rebases the stack onto trunk.
+    if (bottomPr === input.pr)
+        return { trunk: input.trunk, bottomPr };
     let data;
     try {
-        ({ data } = await graphql(UPPER_LAYER_CONFLICT_TARGET_QUERY, {
+        ({ data } = await githubOperation("UpperLayerConflictTarget", () => graphql(UPPER_LAYER_CONFLICT_TARGET_QUERY, {
             owner: input.owner,
             name: input.name,
             number: input.pr,
             headRef: input.headRef,
+        }), async () => {
+            const repo = { owner: input.owner, name: input.name };
+            const pull = await readRestPull(input.pr, repo);
+            const behindBy = await readRestBehind(repo, pull.base.ref, input.headRef);
+            return {
+                data: {
+                    repository: {
+                        pullRequest: {
+                            baseRef: { compare: { behindBy } },
+                        },
+                    },
+                },
+            };
         }));
     }
     catch (err) {
@@ -37,13 +69,6 @@ export async function lookupUpperLayerTrunkConflict(input) {
     // behindBy > 0: the layer is still behind its parent. Keep the parent rebase.
     if (behindBy !== 0)
         return undefined;
-    const entries = pull.stack?.entries;
-    const bottomPr = entries ? selectBottomOpenLayer(entries.nodes, input.trunk) : undefined;
-    if (bottomPr === undefined) {
-        ignore(input.pr, entries?.pageInfo.hasNextPage
-            ? "stack entry page truncated before the trunk layer"
-            : "bottom open layer not found");
-    }
     return { trunk: input.trunk, ...(bottomPr !== undefined && { bottomPr }) };
 }
 function ignore(pr, message) {

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

@@ -1,5 +1,6 @@
 import { readStackTopology, stackAncestryGaps } from "../../github/stack-read.mjs";
 import { buildNativeStackRebaseInstruction } from "./native-stack-rebase.mjs";
+import { getGithubTransport } from "../../github/transport.mjs";
 /**
  * Find a stale immediate parent boundary for one PR.
  *
@@ -36,6 +37,8 @@ function buildStaleNativeStackAncestryInstructions(repo, stackNumber, ancestry)
         buildNativeStackRebaseInstruction(`${repo.owner}/${repo.name}`, stackNumber, {
             parentBranch: ancestry.parentHeadRefName,
         }),
-        "Push the rewritten stack with `gh stack push`.",
+        getGithubTransport() === "rest"
+            ? "Push every affected stack branch using the repository's stack-update procedure."
+            : "Push the rewritten stack with `gh stack push`.",
     ];
 }