pr-shepherd 0.56.5 → 0.57.0

package/bin/commands/iterate/check-instructions.mjs

@@ -1,11 +1,15 @@
 import { playbookPointer } from "../playbook-pointer.mjs";
-const FIX_CODE_CONTINUATION = "`[FIX_CODE]` is non-terminal. Iterate immediately with the same options.";
-/** Build the stale-CR clause appended to the `## Changes-requested reviews` instruction. */
+// The `[FIX_CODE]` heading and the skill already say the action is non-terminal.
+const FIX_CODE_CONTINUATION = "Rerun Shepherd now.";
+/** The `[FIX_CODE]` recurrence step, whether plain or rewritten by the quota warning. */
+export function isFixCodeContinuation(step) {
+    return step === FIX_CODE_CONTINUATION || /\[FIX_CODE\].*non-terminal/i.test(step);
+}
+/** Build the stale-CR step for `## Changes-requested reviews`. Empty when no human CR is stale. */
 export function buildCrStaleClause(reviews) {
-    const human = reviews.some((r) => r.staleReview && !r.staleBotCr)
-        ? " `[stale]` bullets are human CRs on an old commit. Ask the reviewer to re-review."
+    return reviews.some((r) => r.staleReview && !r.staleBotCr)
+        ? "`[stale]` changes-requested reviews are human CRs on an old commit. Ask the reviewer to re-review."
         : "";
-    return human;
 }
 /**
  * Build the optional branch-update hint. Empty unless the branch is behind or conflicts with its
@@ -42,27 +46,21 @@ export function buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasE
     return instructions;
 }
 /**
- * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
- * whenever the *unmodified, as-printed* command is unsafe without them:
- *
- * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
- *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
- * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
- * dismiss-ID retention. The pointer below is load-bearing: without it, nothing in CLI output
- * tells the agent that playbook exists.
+ * Build the `apply review` step, with the rendered command inline. The step stays here (not in
+ * the skill) because the *as-printed* command is invalid without `$DISMISS_MESSAGE`: an empty
+ * `--message` makes `apply review` reject the mutation. `--require-sha` needs no substitution:
+ * the rendered command reads the pushed HEAD itself. "Even if you changed no code": the
+ * command records each item's disposition either way.
  */
-export function buildResolveCommandInstruction(resolveCommand) {
+export function buildResolveCommandInstruction(resolveCommand, rendered) {
     if (!resolveCommand.hasMutations)
         return [];
-    const instructions = [];
-    if (resolveCommand.requiresHeadSha) {
-        instructions.push("If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)` (it must equal the remote PR head). If you did, use the pushed SHA.");
-    }
     if (resolveCommand.requiresDismissMessage) {
-        instructions.push("Replace `$DISMISS_MESSAGE` with one sentence describing what changed.");
+        return [
+            `\`$DISMISS_MESSAGE\`: one sentence on what changed. Run even if no code changed: \`${rendered}\``,
+        ];
     }
-    instructions.push(`Run the \`apply review:\` command above. ${playbookPointer("Review-mutation mechanics")}`);
-    return instructions;
+    return [`Run, even if no code changed: \`${rendered}\``];
 }
 /** One pointer. Conclusion, rerun, and bare-check rules live in the CI playbook. */
 export function buildFailingCheckInstructions(checks) {
@@ -72,9 +70,12 @@ export function buildFailingCheckInstructions(checks) {
 }
 /** Update the PR branch after an external blocker merges or closes. Never rerun that job. */
 export function buildReleasedBlockerInstruction(prNumber) {
-    return `Update this PR branch from its base with \`gh pr update-branch ${prNumber} --rebase\`. Do not rerun the job; a rerun retests the old merge ref.`;
+    return getGithubTransport() === "rest"
+        ? "Update this PR branch from its base using the repository's branch-update procedure. Do not rerun the job; a rerun retests the old merge ref."
+        : `Update this PR branch from its base with \`gh pr update-branch ${prNumber} --rebase\`. Do not rerun the job; a rerun retests the old merge ref.`;
 }
 /** Recurrence only. Commit, push, rerun, and SHA steps are earlier instructions. */
 export function buildFixCompletionInstruction() {
     return FIX_CODE_CONTINUATION;
 }
+import { getGithubTransport } from "../../github/transport.mjs";

package/bin/commands/iterate/classify.mjs

@@ -2,6 +2,8 @@ import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { shouldMinimizeAuthor } from "../../comments/minimize-policy.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, } from "../../comments/authors.mjs";
 import { buildThreadMutationRouting } from "./thread-mutation-routing.mjs";
+import { canGenerateGithubMutation } from "../../github/mutation-policy.mjs";
+import { durableStateRequested } from "../../state/durable-state.mjs";
 function dedupeIds(ids) {
     const seen = new Set();
     const out = [];
@@ -15,7 +17,7 @@ function dedupeIds(ids) {
 }
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all", botUsernames = new Set(), unresolvedThreads = [], ruleAutoResolveIds = []) {
     const blockedReviewIds = new Set(unresolvedThreads.flatMap((t) => (t.reviewId !== undefined ? [t.reviewId] : [])));
-    const eligible = (r) => r.viewerCanMinimize === true &&
+    const eligible = (r) => canGenerateGithubMutation(r.viewerCanMinimize, "minimize") &&
         shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames) &&
         !blockedReviewIds.has(r.id);
     // First-look summaries still need one tick to surface their body to the agent,
@@ -36,7 +38,7 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
     if (minimizeApprovals) {
         const surfacedApprovals = [];
         for (const r of approvals) {
-            if (r.viewerCanMinimize === true &&
+            if (canGenerateGithubMutation(r.viewerCanMinimize, "minimize") &&
                 shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames))
                 minimizeIds.push(r.id);
             else
@@ -58,14 +60,24 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
         surfacedApprovals: approvals,
     };
 }
+/**
+ * A durable-state session (event mode or a cloud session) can lose its uncertain-reply records
+ * between ticks. Its generated reply command opts in to adopting a reply GitHub already shows,
+ * so rerunning the same printed command cannot double-post. Direct apply requests never do.
+ */
+function pushAdoptExistingReplies(argv, hasReply) {
+    if (hasReply && durableStateRequested())
+        argv.push("--adopt-existing-replies");
+}
 export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prReference, botUsernames = new Set(), ruleAutoResolveThreadIds = [], viewerAuthorization, authorizationThreads = [], resolveOtherHumanThreads = "none") {
     const allThreads = [...threads, ...resolutionOnlyThreads];
     const routed = buildThreadMutationRouting(allThreads, botUsernames, ruleAutoResolveThreadIds, resolveOtherHumanThreads);
     const canReply = new Set(authorizationThreads
-        .filter((thread) => thread.viewerCanReply === true)
+        .filter((thread) => canGenerateGithubMutation(thread.viewerCanReply, "reply"))
         .map((thread) => thread.id));
     const canResolve = new Set(authorizationThreads
-        .filter((thread) => thread.viewerCanResolve === true)
+        .filter((thread) => thread.isResolved === false &&
+        canGenerateGithubMutation(thread.viewerCanResolve, "resolve"))
         .map((thread) => thread.id));
     const pairedResolveIds = new Set(routed.pairedResolveThreadIds);
     const replyThreadIds = routed.replyThreadIds.filter((id) => canReply.has(id) && (!pairedResolveIds.has(id) || canResolve.has(id)));
@@ -76,7 +88,7 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
     const resolveThreadIds = dedupeIds([...pairedResolveThreadIds, ...standaloneResolveThreadIds]);
     // Bot/non-human CHANGES_REQUESTED reviews are auto-dismissed after the agent pushes a fix.
     // Human reviews are left for the reviewer to re-review or dismiss themselves.
-    const dismissReviewIds = dedupeIds(viewerAuthorization?.viewerCanAdminister === true
+    const dismissReviewIds = dedupeIds(canGenerateGithubMutation(viewerAuthorization?.viewerCanAdminister, "dismiss")
         ? reviews
             .filter((r) => !isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames))
             .map((r) => r.id)
@@ -99,6 +111,7 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
             resolveArgv.push("--resolve-thread-ids", pairedResolveThreadIds.join(","));
         }
         resolveArgv.push("--message", "$DISMISS_MESSAGE");
+        pushAdoptExistingReplies(resolveArgv, hasReply);
         if (hasDismiss) {
             resolveArgv.push("--dismiss-review-ids", dismissReviewIds.join(","));
         }
@@ -139,6 +152,7 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
     if (replyThreadIds.length > 0) {
         argv.push("--reply-thread-ids", replyThreadIds.join(","));
         argv.push("--message", "$DISMISS_MESSAGE");
+        pushAdoptExistingReplies(argv, true);
     }
     if (resolveThreadIds.length > 0) {
         argv.push("--resolve-thread-ids", resolveThreadIds.join(","));

package/bin/commands/iterate/escalate.mjs

@@ -151,9 +151,19 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
             const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
             lines.push(`- thread \`${t.id}\` — ${loc} (${renderEscalateAuthor(t)}):`);
             lines.push("");
-            for (const bodyLine of t.body.split("\n"))
-                lines.push(`  > ${bodyLine}`);
-            lines.push("");
+            if (!t.comments?.length) {
+                for (const bodyLine of t.body.split("\n"))
+                    lines.push(`  > ${bodyLine}`);
+                lines.push("");
+                continue;
+            }
+            // The transcript starts with the root comment, whose body is the thread body.
+            for (const c of t.comments) {
+                lines.push(`  - comment \`${c.id}\` (${renderEscalateAuthor(c)}):`, "");
+                for (const bodyLine of c.body.split("\n"))
+                    lines.push(`    > ${bodyLine}`);
+                lines.push("");
+            }
         }
         for (const r of escalate.changesRequestedReviews) {
             lines.push(`- review \`${r.id}\` (${renderEscalateAuthor(r)}):`);

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

@@ -20,6 +20,7 @@ import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
 import { canRerunWorkflows } from "../../checks/conclusions.mjs";
+import { canGenerateGithubMutation } from "../../github/mutation-policy.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 const EMPTY_RELEASED = new Set();
@@ -87,10 +88,12 @@ export async function handleFixCode(ctx) {
     const routedThreadMutations = buildThreadMutationRouting(allThreads, botUsernames, [...ruleAutoResolveIds], resolveOtherHumanThreads);
     const replyIdSet = new Set(routedThreadMutations.replyThreadIds);
     const resolveIdSet = new Set(routedThreadMutations.resolveThreadIds);
-    const unauthorizedReplies = allThreads.filter((thread) => replyIdSet.has(thread.id) && thread.viewerCanReply !== true);
-    const unauthorizedResolves = allThreads.filter((thread) => resolveIdSet.has(thread.id) && thread.viewerCanResolve !== true);
+    const unauthorizedReplies = allThreads.filter((thread) => replyIdSet.has(thread.id) && !canGenerateGithubMutation(thread.viewerCanReply, "reply"));
+    const unauthorizedResolves = allThreads.filter((thread) => resolveIdSet.has(thread.id) &&
+        (thread.isResolved !== false ||
+            !canGenerateGithubMutation(thread.viewerCanResolve, "resolve")));
     const unauthorizedDismissals = report.changesRequestedReviews.filter((review) => (!isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames)) &&
-        report.viewerAuthorization?.viewerCanAdminister !== true);
+        !canGenerateGithubMutation(report.viewerAuthorization?.viewerCanAdminister, "dismiss"));
     const skippedThreadIds = new Set([...unauthorizedReplies, ...unauthorizedResolves].map((thread) => thread.id));
     const mutationActionableThreads = report.threads.actionable.filter((thread) => !skippedThreadIds.has(thread.id) &&
         ((thread.path !== null && thread.line !== null) ||
@@ -98,6 +101,7 @@ export async function handleFixCode(ctx) {
     const retryableActionableThreads = mutationActionableThreads.filter((thread) => thread.path !== null && thread.line !== null);
     const protectedRuns = [];
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
+    await aliasThreadFixAttempts({ owner: repoOwner, name: repoName }, prNumber, retryableActionableThreads.map(({ id }) => id), stored);
     const countFixCodeAttempt = opts.persistSeen !== false;
     const priorThreadAttempts = previousFixAttempts(stored, retryableActionableThreads);
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, retryableActionableThreads, countFixCodeAttempt);
@@ -154,7 +158,7 @@ export async function handleFixCode(ctx) {
     const threads = report.threads.actionable.map(toAgentThread);
     const resolutionOnlyThreads = report.threads.resolutionOnly;
     const actionableComments = report.comments.actionable.map(toAgentComment);
-    const rerunAuthorized = canRerunWorkflows(report.viewerAuthorization);
+    const rerunAuthorized = canRerunWorkflows(report.viewerAuthorization, report.transport);
     // A workflow run can only be rerun once it has fully completed; a runId still present among
     // in-progress checks (a sibling job from the same run) is not yet eligible.
     const inProgressWorkflowRunIds = new Set(report.checks.inProgress.flatMap((c) => (c.runId !== null ? [c.runId] : [])));
@@ -192,7 +196,7 @@ export async function handleFixCode(ctx) {
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
-    const { behindBaseHint } = loadConfig().iterate;
+    const { behindBaseHint, instructions: configuredInstructions } = loadConfig().iterate;
     // Only surface in-progress runs when a push is plausible — resolution-only and
     // summary-only iterations have no path to a push, so listing runs would prompt
     // unnecessary cancellation.
@@ -301,18 +305,26 @@ export async function handleFixCode(ctx) {
             baseRefOid: report.baseRefOid,
         })
         : [];
-    // Only an upper layer can be dirty against trunk while already containing its parent.
-    const trunkConflict = hasConflicts && stack && headRef && baseLookup.branch !== stack.baseRefName
-        ? await lookupUpperLayerTrunkConflict({
-            owner: repoOwner,
-            name: repoName,
-            pr: prNumber,
-            headRef,
-            trunk: stack.baseRefName,
-        })
+    // A bottom open layer can still retain its merged parent's PR base. Its update starts
+    // at trunk regardless of that base comparison; true upper layers first check the parent.
+    const trunkConflict = hasConflicts && stack && report.stackBottomPr === prNumber
+        ? { trunk: stack.baseRefName, bottomPr: prNumber }
+        : hasConflicts && stack && headRef && baseLookup.branch !== stack.baseRefName
+            ? await lookupUpperLayerTrunkConflict({
+                owner: repoOwner,
+                name: repoName,
+                pr: prNumber,
+                headRef,
+                trunk: stack.baseRefName,
+                bottomPr: report.stackBottomPr,
+            })
+            : undefined;
+    const recovery = buildRemovedQueueRecovery(report, failingAgentChecks, opts.merge);
+    const requeue = recovery && !("unavailable" in recovery) ? recovery : undefined;
+    const acknowledgmentRecovery = buildStackQueueRemovalAcknowledgment(report, failingAgentChecks);
+    const queueRemovalAcknowledgment = acknowledgmentRecovery && !("unavailable" in acknowledgmentRecovery)
+        ? acknowledgmentRecovery
         : undefined;
-    const requeue = buildRemovedQueueRecovery(report, failingAgentChecks, opts.merge);
-    const queueRemovalAcknowledgment = buildStackQueueRemovalAcknowledgment(report, failingAgentChecks);
     const queueEjection = !currentEjectionCommit(report, failingAgentChecks)
         ? undefined
         : requeue
@@ -323,9 +335,13 @@ export async function handleFixCode(ctx) {
     // Conflicts, a behind branch whose rerun already failed, and a queue ejection that may be
     // reproduced on the latest base all print the branch update route.
     const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0) || queueEjection
-        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict)
+        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict, report.stackBottomPr)
         : undefined;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase, queueEjection);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, canGenerateGithubMutation(report.viewerAuthorization?.viewerCanUpdate, "ready"), exhaustedAttempts.length > 0, stackRebase, queueEjection, opts.instructions ?? configuredInstructions);
+    if (recovery && "unavailable" in recovery)
+        instructions.unshift(recovery.unavailable);
+    if (acknowledgmentRecovery && "unavailable" in acknowledgmentRecovery)
+        instructions.unshift(acknowledgmentRecovery.unavailable);
     if (failingAgentChecks.some((check) => releasedCheckNames.has(check.name))) {
         const completion = instructions.pop();
         instructions.push(buildReleasedBlockerInstruction(prNumber));
@@ -336,7 +352,11 @@ export async function handleFixCode(ctx) {
         instructions.unshift(...repairInstructions);
     }
     if (mergedBasePullRequests.length > 0) {
-        instructions.unshift(`Inspect every PR under \`## Merged PRs matching the current base\`. If this PR is the remaining layer intended for a merged parent's base branch, run \`gh pr edit ${prReference} --base <verified-parent-base>\` after replacing \`<verified-parent-base>\` with that parent's shell-quoted base branch, then rerun Shepherd immediately and follow its fresh instructions instead of the remaining steps here. Otherwise keep the current base and follow the remaining conflict-resolution steps.`);
+        // `gh pr edit` goes through GraphQL; REST callers retarget with the pulls PATCH endpoint.
+        const retarget = report.transport === "rest"
+            ? `gh api --method PATCH repos/${report.repo}/pulls/${prNumber} -f base=<verified-parent-base>`
+            : `gh pr edit ${prReference} --base <verified-parent-base>`;
+        instructions.unshift(`Inspect every PR under \`## Merged PRs matching the current base\`. If this PR is the remaining layer intended for a merged parent's base branch, run \`${retarget}\` after replacing \`<verified-parent-base>\` with that parent's shell-quoted base branch, then rerun Shepherd immediately and follow its fresh instructions instead of the remaining steps here. Otherwise keep the current base and follow the remaining conflict-resolution steps.`);
     }
     const checkRunCount = countReportedChecks(report.checks);
     const suitesEmpty = report.headCheckSuitesEmpty === true;
@@ -386,3 +406,4 @@ export async function handleFixCode(ctx) {
     }
     return result;
 }
+import { aliasThreadFixAttempts } from "../../github/rest-identities.mjs";

package/bin/commands/iterate/fix-instruction-threads.d.mts

@@ -4,11 +4,3 @@ export declare function partitionFixThreads(threads: AgentThread[], resolveComma
     unlocatedMutatedThreads: AgentThread[];
     unlocatedThreads: AgentThread[];
 };
-export declare function reviewSectionRefs(input: {
-    hasReviewThreads: boolean;
-    hasUnlocatedSkipThreads: boolean;
-    hasActionableComments: boolean;
-    hasFailingChecks: boolean;
-    hasAnnotations: boolean;
-    hasChangesRequested: boolean;
-}): string[];

package/bin/commands/iterate/fix-instruction-threads.mjs

@@ -14,19 +14,3 @@ export function partitionFixThreads(threads, resolveCommand, resolveOnlyCommand)
         unlocatedThreads: threads.filter((thread) => (thread.path === null || thread.line === null) && !mutatedThreadIds.has(thread.id)),
     };
 }
-export function reviewSectionRefs(input) {
-    const sections = [];
-    if (input.hasReviewThreads)
-        sections.push("`## Review threads`");
-    if (input.hasUnlocatedSkipThreads)
-        sections.push("`## Unlocated review threads (logged once — no mutation)`");
-    if (input.hasActionableComments)
-        sections.push("`## Actionable comments`");
-    if (input.hasFailingChecks)
-        sections.push("`## Failing checks`");
-    if (input.hasAnnotations)
-        sections.push("`## Check annotations`");
-    if (input.hasChangesRequested)
-        sections.push("`## Changes-requested reviews`");
-    return sections;
-}

package/bin/commands/iterate/fix-loop-instruction.d.mts

@@ -0,0 +1,9 @@
+import type { InstructionStyle } from "../../config/load.mts";
+/**
+ * The generic commit/push step and the journal step. Playbook style folds both into one pointer
+ * only when the generic push applies: the "Fix-code loop" playbook tells the caller to push to the
+ * PR head branch, which would conflict with a conflict or queue-recovery push step. Without the
+ * generic push, the journal step stays inline with its citation clause. The rerun
+ * step stays inline because it is the one step a halted loop cannot recover from.
+ */
+export declare function buildPushJournalSteps(style: InstructionStyle, prReference: string | number, genericPush: boolean, wantsJournal: boolean): string[];

package/bin/commands/iterate/fix-loop-instruction.mjs

@@ -0,0 +1,35 @@
+import { renderShellCommand } from "../../cli/runner.mjs";
+import { loadConfig } from "../../config/load.mjs";
+import { buildShepherdJournalCommand, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
+import { playbookPointer } from "../playbook-pointer.mjs";
+const FIX_CODE_LOOP_PLAYBOOK = "Fix-code loop";
+/**
+ * Playbook-style replacement for the invariant commit/push and journal steps. The
+ * procedure text lives in the "Fix-code loop" playbook; only the trigger and the concrete
+ * journal command stay in the per-tick output. `inline` style never calls this.
+ */
+function buildFixLoopInstruction(prReference, journal) {
+    const parts = ["Commit and push any changes."];
+    if (journal)
+        parts.push(`Journal substantial decisions or rejections with \`${buildShepherdJournalCommand(prReference)}\`.`);
+    const cli = renderShellCommand([...loadConfig().cliCommand, "playbook", FIX_CODE_LOOP_PLAYBOOK]);
+    parts.push(`${playbookPointer(FIX_CODE_LOOP_PLAYBOOK)} CLI: \`${cli}\`.`);
+    return parts.join(" ");
+}
+/**
+ * The generic commit/push step and the journal step. Playbook style folds both into one pointer
+ * only when the generic push applies: the "Fix-code loop" playbook tells the caller to push to the
+ * PR head branch, which would conflict with a conflict or queue-recovery push step. Without the
+ * generic push, the journal step stays inline with its citation clause. The rerun
+ * step stays inline because it is the one step a halted loop cannot recover from.
+ */
+export function buildPushJournalSteps(style, prReference, genericPush, wantsJournal) {
+    if (style === "playbook" && genericPush)
+        return [buildFixLoopInstruction(prReference, wantsJournal)];
+    const steps = [];
+    if (genericPush)
+        steps.push("Commit and push any changes.");
+    if (wantsJournal)
+        steps.push(buildShepherdJournalInstruction(prReference));
+    return steps;
+}

package/bin/commands/iterate/helpers.mjs

@@ -23,6 +23,10 @@ export function buildTerminalCancelResult(report) {
     return {
         pr: report.pr,
         repo: report.repo,
+        ...(report.transport && { transport: report.transport }),
+        ...(report.transportUnavailable?.length && {
+            transportUnavailable: report.transportUnavailable,
+        }),
         status: report.status,
         mergeStateStatus: report.mergeStatus.mergeStateStatus,
         mergeStatus: report.mergeStatus.status,
@@ -103,7 +107,12 @@ export function buildActiveChecks(report) {
 }
 export function buildWaitLog(base) {
     const { summary, remainingSeconds } = base;
-    const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
+    // Zero counts are trivial defaults; the line keeps whichever count is non-zero.
+    const counts = [
+        ...(summary.passing > 0 ? [`${summary.passing} passing`] : []),
+        ...(summary.inProgress > 0 ? [`${summary.inProgress} in-progress`] : []),
+    ];
+    const parts = counts.length > 0 ? [counts.join(", ")] : [];
     if ((base.inProgressChecks?.length ?? 0) > 0) {
         parts.push(`active checks: ${base
             .inProgressChecks.slice(0, 5)
@@ -133,7 +142,11 @@ export function buildWaitLog(base) {
     if (remainingSeconds > 0) {
         parts.push(`${remainingSeconds}s until auto-cancel`);
     }
-    return parts.join(" — ");
+    if (parts.length > 0)
+        return `WAIT: ${parts.join(" — ")}`;
+    // Skipped, filtered, or superseded checks still count as reported CI data.
+    const reported = summary.skipped + summary.filtered + summary.superseded > 0;
+    return `WAIT: ${reported ? "no passing or in-progress checks" : "no checks reported"}`;
 }
 export function blockedCancelNote(base) {
     if (base.mergeStatus !== "BLOCKED")

package/bin/commands/iterate/index.mjs

@@ -28,6 +28,8 @@ import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 import { annotateBlockedWait, resolveCheckBlockerGate } from "./check-blocker-gate.mjs";
 import { buildUnreportedFixResult, planUnreportedRequired } from "./unreported-required.mjs";
 import { createCheckExecutionContext } from "../check-execution-context.mjs";
+import { transportReadinessGaps } from "../../github/transport-evidence.mjs";
+import { buildEscalateHumanMessage } from "./escalate.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -194,7 +196,7 @@ async function runIterateCore(opts) {
         });
     }
     if (unreportedRepair.length > 0) {
-        return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, buildUnreportedFixResult(base, report, unreportedRepair), reportForWork, reviewSummaryIds), blockerGate);
+        return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, buildUnreportedFixResult(base, report, unreportedRepair), reportForWork, reviewSummaryIds, opts.stallDeadlineSink), blockerGate);
     }
     const mergeStateResult = await handleActiveMergeState({
         enabled: opts.merge,
@@ -234,6 +236,24 @@ async function runIterateCore(opts) {
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
         !report.mergeStatus.blockingBotReviewInProgress;
+    const gaps = transportReadinessGaps(report, report.mergeStatus.mergeStateStatus);
+    if (gaps.length > 0 &&
+        report.checks.inProgress.length === 0 &&
+        report.mergeStatus.mergeStateStatus !== "UNKNOWN") {
+        await clearReadyReceipt(receiptKey);
+        const escalation = {
+            triggers: ["transport-unsupported"],
+            unresolvedThreads: [],
+            ambiguousComments: [],
+            changesRequestedReviews: [],
+            suggestion: gaps.map(({ field, reason }) => `${field}: ${reason}`).join("; "),
+        };
+        return {
+            ...base,
+            action: "escalate",
+            escalate: { ...escalation, humanMessage: buildEscalateHumanMessage(escalation, report.pr) },
+        };
+    }
     const autoMarkReady = !opts.noAutoMarkReady && config.actions.autoMarkReady;
     const markReadyResult = await markReadyIfAuthorized(canMarkReady && autoMarkReady, base, report);
     if (markReadyResult)
@@ -250,7 +270,7 @@ async function runIterateCore(opts) {
                 shouldCancel: false,
                 log: `WAIT: PR #${base.pr} reached ready-delay but its stack readiness receipt could not be persisted`,
             };
-            return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, receiptWait, reportForWork, reviewSummaryIds), blockerGate);
+            return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, receiptWait, reportForWork, reviewSummaryIds, opts.stallDeadlineSink), blockerGate);
         }
         await clearReadyDelay(report.pr, repoOwner, repoName);
         await clearStallState(stallKey);
@@ -283,14 +303,15 @@ async function runIterateCore(opts) {
         log: buildWaitLog(base),
         ...(hold && { stackDraftHold: hold }),
     };
-    return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, reportForWork, reviewSummaryIds), blockerGate);
+    return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, reportForWork, reviewSummaryIds, opts.stallDeadlineSink), blockerGate);
 }
 async function recordReadyReceipt(key, report, context) {
     if (report.status !== "READY" ||
         report.mergeStatus.state !== "OPEN" ||
         report.mergeStatus.isDraft ||
         !report.headSha ||
-        !report.baseRefOid)
+        !report.baseRefOid ||
+        transportReadinessGaps(report, report.mergeStatus.mergeStateStatus).length > 0)
         return false;
     try {
         const raw = await receiptSummaryForReport(key, report, context);
@@ -357,6 +378,7 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork, context) {
         report.mergeStatus.isDraft ||
         !report.headSha ||
         !report.baseRefOid ||
+        transportReadinessGaps(report, report.mergeStatus.mergeStateStatus).length > 0 ||
         (!retainQueuedReceipt && (report.status !== "READY" || hasReadinessWork))) {
         await clearReadyReceipt(key);
         return false;

package/bin/commands/iterate/mark-ready.mjs

@@ -1,6 +1,14 @@
 import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
+import { rest } from "../../github/http.mjs";
+import { githubOperation, isCcrTransport } from "../../github/transport.mjs";
+import { canGenerateGithubMutation } from "../../github/mutation-policy.mjs";
+import { UnsupportedRestOperationError } from "../../github/unsupported-rest.mjs";
+import { GitHubRequestError } from "../../github/errors.mjs";
+import { isRestSessionRefusal } from "../../github/rest-session-refusal.mjs";
+import { rateLimitKind } from "../../github/rate-limit-kind.mjs";
+import { nonDraftMergeStatus } from "../../merge-status/derive.mjs";
 export async function markReadyIfAuthorized(enabled, base, report) {
     if (!enabled)
         return null;
@@ -12,17 +20,49 @@ export async function markReadyIfAuthorized(enabled, base, report) {
             log: `READY: PR #${report.pr} is ready to mark; refresh required before converting draft`,
         };
     }
-    if (report.viewerAuthorization?.viewerCanUpdate === true) {
-        await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });
-        return {
-            ...base,
-            action: "mark_ready",
-            markedReady: true,
-            log: `MARKED READY: PR #${report.pr} converted from draft to ready for review`,
-        };
+    let unsupported;
+    if (canGenerateGithubMutation(report.viewerAuthorization?.viewerCanUpdate, "ready")) {
+        try {
+            await githubOperation("MarkPrReady", async () => {
+                await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });
+            }, async () => {
+                if (!isCcrTransport())
+                    throw new UnsupportedRestOperationError("markPullRequestReadyForReview", "ready-for-review requires the cloud CCR proxy");
+                const response = await rest("POST", `/repos/${report.repo}/pulls/${report.pr}/ccr/ready_for_review`);
+                if (response?.draft !== false)
+                    throw new Error("CCR ready_for_review did not confirm draft:false; refresh the PR before retrying");
+            }, { mutation: true });
+            // The snapshot predates the conversion; GitHub just confirmed the PR is no longer a draft.
+            // A raw DRAFT merge state has not been recomputed yet, so it becomes UNKNOWN.
+            const mergeStateStatus = base.mergeStateStatus === "DRAFT" ? "UNKNOWN" : base.mergeStateStatus;
+            return {
+                ...base,
+                isDraft: false,
+                mergeStateStatus,
+                ...(base.mergeStatus === "DRAFT" && { mergeStatus: nonDraftMergeStatus(mergeStateStatus) }),
+                action: "mark_ready",
+                markedReady: true,
+                log: `MARKED READY: PR #${report.pr} converted from draft to ready for review`,
+            };
+        }
+        catch (error) {
+            if (error instanceof UnsupportedRestOperationError ||
+                isRestSessionRefusal(error) ||
+                (error instanceof GitHubRequestError && error.status === 404))
+                unsupported = error.message;
+            else if (!(error instanceof GitHubRequestError) ||
+                error.status !== 403 ||
+                rateLimitKind(error) !== null)
+                throw error;
+        }
+    }
+    else if (report.transport === "rest" && report.viewerAuthorization?.viewerCanUpdate !== false) {
+        unsupported = "Ready-for-review requires the cloud CCR proxy";
     }
     const escalation = {
-        triggers: ["authorization-required"],
+        triggers: [
+            unsupported ? "transport-unsupported" : "authorization-required",
+        ],
         unresolvedThreads: [],
         ambiguousComments: [],
         changesRequestedReviews: [],
@@ -33,7 +73,7 @@ export async function markReadyIfAuthorized(enabled, base, report) {
                 reason: "denied-or-unverifiable",
             },
         ],
-        suggestion: buildEscalateSuggestion(["authorization-required"]),
+        suggestion: unsupported ?? buildEscalateSuggestion(["authorization-required"]),
     };
     return {
         ...base,

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;