pr-shepherd 0.56.6 → 0.57.1

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

@@ -0,0 +1,19 @@
+import { type MergeMethod } from "../../config/merge-method.mts";
+import type { MergeCommandPlan } from "../../types.mts";
+import type { RestMergeStackGuard } from "../../github/rest-merge.mts";
+export interface MergePlanInput {
+    transport?: "rest";
+    pr: number;
+    repo: string;
+    nodeId: string;
+    headSha: string;
+    queue: boolean;
+    queueKnown?: boolean;
+    /** Omitted when the batch did not select repository merge settings. */
+    allowedMergeMethods?: readonly MergeMethod[];
+    expectedStack?: RestMergeStackGuard;
+}
+export interface MergeMethodUnavailable {
+    unavailable: string;
+}
+export declare function buildMergeCommandPlan(input: MergePlanInput): MergeCommandPlan | MergeMethodUnavailable;

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.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}\``,
@@ -55,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.mjs

@@ -2,6 +2,9 @@ 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";
+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) {
@@ -31,11 +34,24 @@ export async function lookupUpperLayerTrunkConflict(input) {
         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) {

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`.",
     ];
 }

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

@@ -3,4 +3,8 @@ export declare function applyStallGuard(stallKey: {
     owner: string;
     repo: string;
     pr: number;
-}, stallTimeoutSeconds: number, headSha: string, base: IterateResultBase, prNumber: number, prospectiveResult: IterateResult, report: ShepherdReport, reviewSummaryIds: string[]): Promise<IterateResult>;
+}, stallTimeoutSeconds: number, headSha: string, base: IterateResultBase, prNumber: number, prospectiveResult: IterateResult, report: ShepherdReport, reviewSummaryIds: string[], stallDeadlineSink?: StallDeadlineSink): Promise<IterateResult>;
+/** Internal out-parameter: when the earliest unstarted check would trip the CI-start stall. */
+export interface StallDeadlineSink {
+    ciStartDeadlineSeconds?: number;
+}

package/bin/commands/iterate/stall.mjs

@@ -62,13 +62,14 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
         annotations,
     });
 }
-export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds) {
+export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds, stallDeadlineSink) {
     const prReference = formatPrUrl(report.repo, prNumber);
     const nowSeconds = Math.floor(Date.now() / 1000);
-    const stalledChecks = findCiStartStalledChecks(report.checks.inProgress, nowSeconds, {
-        stallTimeoutSeconds,
-        action: prospectiveResult.action,
-    });
+    const ciStartOpts = { stallTimeoutSeconds, action: prospectiveResult.action };
+    const stalledChecks = findCiStartStalledChecks(report.checks.inProgress, nowSeconds, ciStartOpts);
+    if (stallDeadlineSink) {
+        stallDeadlineSink.ciStartDeadlineSeconds = ciStartStallDeadline(report.checks.inProgress, nowSeconds, ciStartOpts);
+    }
     if (stalledChecks.length > 0) {
         const pending = pendingReviewCommandsFromResult(prospectiveResult);
         const stalledDuration = formatDurationApprox(Math.max(...stalledChecks.map((c) => c.ageSeconds)));
@@ -168,13 +169,24 @@ function stallStateUnavailable(base, prReference, prospectiveResult, reason) {
         },
     };
 }
-function findCiStartStalledChecks(checks, nowSeconds, opts) {
+function unstartedStallCandidates(checks, nowSeconds, opts) {
     if (opts.stallTimeoutSeconds <= 0 || opts.action !== "wait")
         return [];
     return checks
         .filter((c) => isUnstartedCheck(c))
         .map((c) => toAgentStalledCheck(c, nowSeconds))
-        .filter((c) => c.createdAtUnix !== undefined && c.ageSeconds >= opts.stallTimeoutSeconds);
+        .filter((c) => c.createdAtUnix !== undefined);
+}
+function findCiStartStalledChecks(checks, nowSeconds, opts) {
+    return unstartedStallCandidates(checks, nowSeconds, opts).filter((c) => c.ageSeconds >= opts.stallTimeoutSeconds);
+}
+/** Unix seconds at which the oldest unstarted check reaches the stall timeout, if any. */
+function ciStartStallDeadline(checks, nowSeconds, opts) {
+    const candidates = unstartedStallCandidates(checks, nowSeconds, opts);
+    if (candidates.length === 0)
+        return undefined;
+    const maxAge = Math.max(...candidates.map((c) => c.ageSeconds));
+    return nowSeconds - maxAge + opts.stallTimeoutSeconds;
 }
 function isUnstartedCheck(check) {
     if (check.source === "status_context")

package/bin/commands/iterate/thread-mutation-routing.d.mts

@@ -10,6 +10,7 @@ export interface ThreadMutationRouting {
 }
 export declare function threadHasAuthorizedMutation(thread: {
     id: string;
+    isResolved?: boolean;
     viewerCanReply?: boolean;
     viewerCanResolve?: boolean;
 }, replyThreadIds: ReadonlySet<string>, resolveThreadIds: ReadonlySet<string>): boolean;

package/bin/commands/iterate/thread-mutation-routing.mjs

@@ -1,6 +1,7 @@
 import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "../../comments/authors.mjs";
 import { threadEndedByShepherd } from "../../comments/marker.mjs";
 import { shouldResolveOtherHumanThread } from "../../comments/thread-resolve-policy.mjs";
+import { canGenerateGithubMutation } from "../../github/mutation-policy.mjs";
 function dedupeIds(ids) {
     return [...new Set(ids)];
 }
@@ -19,9 +20,10 @@ export function threadHasAuthorizedMutation(thread, replyThreadIds, resolveThrea
     const inResolve = resolveThreadIds.has(thread.id);
     if (!inReply && !inResolve)
         return false;
-    if (inReply && thread.viewerCanReply !== true)
+    if (inReply && !canGenerateGithubMutation(thread.viewerCanReply, "reply"))
         return false;
-    if (inResolve && thread.viewerCanResolve !== true)
+    if (inResolve &&
+        (thread.isResolved !== false || !canGenerateGithubMutation(thread.viewerCanResolve, "resolve")))
         return false;
     return true;
 }

package/bin/commands/iterate/unreported-required.mjs

@@ -4,6 +4,7 @@ import { readCiRetrigger, sameCiRetrigger, writeCiRetrigger } from "../../state/
 import { buildFixCompletionInstruction } from "./check-instructions.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
 import { buildNativeStackRebaseInstruction } from "./native-stack-rebase.mjs";
+import { getGithubTransport } from "../../github/transport.mjs";
 /** Rebase when the trunk or the PR base is behind; otherwise close and reopen once. */
 function decideUnreportedRequired(input) {
     if (input.behind)
@@ -29,12 +30,14 @@ function buildUnreportedRequiredInstructions(input) {
     if (!input.behind) {
         return [
             facts,
-            `Retrigger workflows once for this head with \`gh pr close ${input.pr} -R ${input.repo}\` then \`gh pr reopen ${input.pr} -R ${input.repo}\`.`,
+            getGithubTransport() === "rest"
+                ? `Retrigger workflows once for this head: run \`gh api --method PATCH repos/${input.repo}/pulls/${input.pr} -f state=closed\`, then run \`gh api --method PATCH repos/${input.repo}/pulls/${input.pr} -f state=open\`.`
+                : `Retrigger workflows once for this head with \`gh pr close ${input.pr} -R ${input.repo}\` then \`gh pr reopen ${input.pr} -R ${input.repo}\`.`,
             "If those checks are still missing on the next poll, investigate why the workflows did not start. Do not close the PR again. Shepherd escalates with `required-checks-unreported` when this remains the only blocker.",
         ];
     }
     const rebase = input.stackRebase
-        ? `${input.stackRebase} Then push the rewritten stack with \`gh stack push\`.`
+        ? `${input.stackRebase} Then push the rewritten stack${getGithubTransport() === "rest" ? " using the repository's stack-update procedure" : " with `gh stack push`"}.`
         : `Rebase onto \`${input.baseBranch}\` and push.`;
     return [
         facts,