pr-shepherd 0.41.0 → 0.43.0

package/bin/commands/commit-suggestion.mjs

@@ -1,143 +1,24 @@
-import { execFile as execFileCb } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
-import { promisify } from "node:util";
-import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/client.mjs";
-import { fetchSuggestionThread } from "../github/suggestion-thread.mjs";
-import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
-import { buildUnifiedDiff } from "../suggestions/patch.mjs";
-import { getUnsafeSuggestionRangeReason } from "../suggestions/range.mjs";
-import { EXIT, ShepherdError } from "../exit-codes.mjs";
-import { buildPrShepherdCommand } from "../cli/runner.mjs";
-import { getEffectiveCwd, getExecutionCwd } from "../execution-context.mjs";
-const execFile = promisify(execFileCb);
-/** @deprecated Hidden implementation for `commit-suggestion`; use `build-suggestion-patch`. */
+import { buildSingularInstructions } from "./suggestion-patch-item.mjs";
+import { runSuggestionPatches } from "./suggestion-patches.mjs";
+/** @deprecated Use runSuggestionPatches. */
 export async function runCommitSuggestion(opts) {
-    if (!opts.threadId) {
-        throw new ShepherdError("--thread-id is required", EXIT.USAGE);
-    }
-    if (!opts.message || opts.message.trim() === "") {
-        throw new ShepherdError("--message is required and must be non-empty", EXIT.USAGE);
-    }
-    const repo = await getRepoInfo();
-    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
-    if (prNumber === null) {
-        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
-    }
-    const currentBranch = await getCurrentBranch();
-    const { stdout: localHeadOut } = await execFile("git", ["rev-parse", "HEAD"], {
-        cwd: getExecutionCwd(),
+    const result = await runSuggestionPatches({
+        prNumber: opts.prNumber,
+        format: opts.format,
+        verbose: opts.verbose,
+        suggestions: [
+            {
+                threadId: opts.threadId,
+                message: opts.message,
+                ...(opts.description !== undefined && { description: opts.description }),
+            },
+        ],
     });
-    const localHeadSha = localHeadOut.trim();
-    const data = await fetchSuggestionThread(prNumber, repo, opts.threadId);
-    if (!data.headRepoWithOwner) {
-        throw new ShepherdError(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`, EXIT.UNAVAILABLE);
-    }
-    if (currentBranch !== data.headRefName) {
-        throw new ShepherdError(`Current branch "${currentBranch}" does not match PR head branch "${data.headRefName}". ` +
-            `Check out "${data.headRefName}" before applying suggestions.`, EXIT.UNAVAILABLE);
-    }
-    if (localHeadSha !== data.headRefOid) {
-        throw new ShepherdError(`Local HEAD ${localHeadSha} does not match PR head ${data.headRefOid}. ` +
-            `Pull/rebase "${data.headRefName}" to the latest PR head and try again.`, EXIT.UNAVAILABLE);
-    }
-    const thread = data.thread;
-    if (!thread) {
-        throw new ShepherdError(`Thread ${opts.threadId} not found on PR #${prNumber}.`, EXIT.UNAVAILABLE);
-    }
-    if (thread.isResolved) {
-        throw new ShepherdError(`Thread ${opts.threadId} is already resolved.`, EXIT.UNAVAILABLE);
-    }
-    if (thread.isOutdated) {
-        throw new ShepherdError(`Thread ${opts.threadId} is outdated.`, EXIT.UNAVAILABLE);
-    }
-    if (thread.isMinimized) {
-        throw new ShepherdError(`Thread ${opts.threadId} is minimized.`, EXIT.UNAVAILABLE);
-    }
-    if (!thread.path || thread.line === null) {
-        throw new ShepherdError(`Thread ${opts.threadId} has no file/line anchor.`, EXIT.UNAVAILABLE);
-    }
-    // Validate the target file is clean before generating the patch, so the emitted
-    // `git add -- <file>` instruction cannot accidentally stage unrelated local edits.
-    const { stdout: fileStatus } = await execFile("git", ["status", "--porcelain", "--", thread.path], { cwd: getExecutionCwd() });
-    if (fileStatus.trim() !== "") {
-        throw new ShepherdError(`${thread.path} has uncommitted changes. Commit or stash them before running build-suggestion-patch.`, EXIT.UNAVAILABLE);
-    }
-    const parsed = parseSuggestion(thread.body);
-    if (!parsed) {
-        throw new ShepherdError(`Thread ${opts.threadId} has no suggestion block in the comment body.`, EXIT.UNAVAILABLE);
-    }
-    if (!isCommittableSuggestion(parsed)) {
-        throw new ShepherdError(`Thread ${opts.threadId}'s suggestion body contains nested suggestion fencing or unbalanced ` +
-            `3+ backtick fences — refusing to apply (could silently truncate).`, EXIT.UNAVAILABLE);
-    }
-    const startLine = thread.startLine ?? thread.line;
-    const endLine = thread.line;
-    const filePath = thread.path;
-    const cwd = getEffectiveCwd();
-    const resolvedPath = resolve(cwd, filePath);
-    const rel = relative(cwd, resolvedPath);
-    if (rel.startsWith("..") || rel === "") {
-        throw new ShepherdError(`Thread ${opts.threadId} path escapes the working tree.`, EXIT.UNAVAILABLE);
-    }
-    const originalContent = await readFile(resolvedPath, "utf8");
-    const unsafeRangeReason = getUnsafeSuggestionRangeReason({
-        originalContent,
-        startLine,
-        endLine,
-        replacementLines: parsed.lines,
-    });
-    if (unsafeRangeReason) {
-        const range = startLine === endLine ? `${startLine}` : `${startLine}-${endLine}`;
-        throw new ShepherdError(`Thread ${opts.threadId}'s suggestion does not safely fit GitHub's anchored range ` +
-            `${filePath}:${range}: ${unsafeRangeReason} Refusing to build a patch; inspect the surrounding ` +
-            `source and reviewer intent, then apply the change manually.`, EXIT.UNAVAILABLE);
-    }
-    const patch = buildUnifiedDiff({
-        path: filePath,
-        originalContent,
-        startLine,
-        endLine,
-        replacementLines: parsed.lines,
-    });
-    const coAuthor = `Co-authored-by: ${thread.author} <${thread.author}@users.noreply.github.com>`;
-    const commitBody = opts.description ? `${opts.description}\n\n${coAuthor}` : coAuthor;
-    const commitMessageArg = opts.message;
-    const commitBodyArg = commitBody;
-    const quotedPath = `'${filePath.replace(/'/g, "'\\''")}'`;
-    const range = startLine === endLine ? `line ${startLine}` : `lines ${startLine}–${endLine}`;
-    const sq = (s) => `'${s.replace(/'/g, "'\\''")}'`;
-    const commitCmd = [
-        "git commit",
-        `-m ${sq(commitMessageArg)}`,
-        ...commitBodyArg.split("\n\n").map((p) => `-m ${sq(p)}`),
-    ].join(" ");
-    const resolveCommand = buildPrShepherdCommand([
-        "apply",
-        "review",
-        String(prNumber),
-        "--resolve-thread-ids",
-        opts.threadId,
-    ]).text;
-    const postActionInstructions = [
-        `Apply the patch to \`${filePath}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
-        `Stage the file: \`git add -- ${quotedPath}\``,
-        `Commit: \`${commitCmd}\``,
-        `Resolve the thread on GitHub: \`${resolveCommand}\``,
-        `Push when ready: \`git push\` (or \`git push --force-with-lease\` after rebasing).`,
-    ];
+    const patch = result.patches[0];
     return {
-        pr: prNumber,
-        repo: `${repo.owner}/${repo.name}`,
-        threadId: opts.threadId,
-        path: filePath,
-        startLine,
-        endLine,
-        author: thread.author,
-        patch,
-        commitMessage: commitMessageArg,
-        commitBody: commitBodyArg,
-        filesToStage: [filePath],
-        postActionInstructions,
+        ...patch,
+        pr: result.pr,
+        repo: result.repo,
+        postActionInstructions: buildSingularInstructions(patch, result.pr),
     };
 }

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

@@ -0,0 +1,5 @@
+import type { IterateResultBase, ShepherdReport } from "../../types.mts";
+export declare function buildIterateBase(report: ShepherdReport, readyState: {
+    shouldCancel: boolean;
+    remainingSeconds: number;
+}): IterateResultBase;

package/bin/commands/iterate/base.mjs

@@ -0,0 +1,25 @@
+import { buildActiveChecks, buildRelevantChecks, buildSummary, buildSuppressedCheckFields, } from "./helpers.mjs";
+export function buildIterateBase(report, readyState) {
+    return {
+        pr: report.pr,
+        repo: report.repo,
+        status: report.status,
+        state: report.mergeStatus.state,
+        mergeStateStatus: report.mergeStatus.mergeStateStatus,
+        mergeStatus: report.mergeStatus.status,
+        reviewDecision: report.mergeStatus.reviewDecision,
+        blockingBotReviewInProgress: report.mergeStatus.blockingBotReviewInProgress,
+        isDraft: report.mergeStatus.isDraft,
+        shouldCancel: readyState.shouldCancel,
+        remainingSeconds: readyState.remainingSeconds,
+        summary: buildSummary(report),
+        baseBranch: report.baseBranch,
+        branchProtection: report.branchProtection,
+        mergeRequirements: report.mergeStatus.mergeRequirements,
+        checks: buildRelevantChecks(report),
+        inProgressChecks: buildActiveChecks(report),
+        ...buildSuppressedCheckFields(report),
+        activity: report.activity,
+        mergeQueue: report.mergeQueue,
+    };
+}

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

@@ -26,6 +26,8 @@ interface BaseBranchLookup {
  */
 export declare function formatDurationApprox(seconds: number): string;
 export declare function validateBaseBranch(raw: string): BaseBranchLookup;
-export declare function buildEscalateHumanMessage(escalate: Omit<EscalateDetails, "humanMessage">, pr: number): string;
+export declare function buildEscalateHumanMessage(escalate: Omit<EscalateDetails, "humanMessage">, pr: number, opts?: {
+    merge?: boolean;
+}): string;
 export declare function buildEscalateSuggestion(triggers: EscalateTrigger[], detail?: string): string;
 export {};

package/bin/commands/iterate/escalate.mjs

@@ -59,7 +59,7 @@ export function validateBaseBranch(raw) {
     }
     return { branch: trimmed, isFallback: false };
 }
-export function buildEscalateHumanMessage(escalate, pr) {
+export function buildEscalateHumanMessage(escalate, pr, opts) {
     const lines = [];
     lines.push("⚠️ /pr-shepherd:pr-shepherd paused — manual intervention required");
     lines.push("");
@@ -109,6 +109,18 @@ export function buildEscalateHumanMessage(escalate, pr) {
             lines.push("");
         }
     }
+    if (escalate.mergeQueueRemoval) {
+        const removal = escalate.mergeQueueRemoval;
+        lines.push("");
+        lines.push("## Merge queue removal");
+        lines.push("");
+        lines.push(`- reason: \`${removal.reason ?? "not provided"}\``);
+        if (removal.actor)
+            lines.push(`- actor: \`@${removal.actor}\``);
+        lines.push(`- createdAtUnix: \`${removal.createdAtUnix}\``);
+        if (removal.beforeCommitOid)
+            lines.push(`- queue commit: \`${removal.beforeCommitOid}\``);
+    }
     if (escalate.thrashHistory && escalate.thrashHistory.length > 0) {
         lines.push("");
         lines.push("## Fix attempts");
@@ -120,10 +132,14 @@ export function buildEscalateHumanMessage(escalate, pr) {
     lines.push("");
     lines.push("---");
     lines.push("");
-    lines.push(`After completing manual fixes (and pushing if required), rerun \`/pr-shepherd:pr-shepherd ${pr}\` to resume.`);
+    lines.push(`After completing manual fixes (and pushing if required), rerun \`/pr-shepherd:pr-shepherd ${pr}${opts?.merge ? " --merge" : ""}\` to resume.`);
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
+    if (triggers.includes("merge-queue-removed")) {
+        const reason = detail ? ` GitHub reason: ${detail}.` : "";
+        return `The PR left the merge queue without an actionable check failure.${reason} Confirm the removal was not intentional before adding it again.`;
+    }
     if (triggers.includes("stall-timeout")) {
         const duration = detail ?? "60 minutes";
         return `No progress detected for ${duration} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;

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

@@ -12,6 +12,7 @@ import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
 import { loadConfig } from "../../config/load.mjs";
+import { buildMergeCommandPlan } from "./merge.mjs";
 function nextFixAttempts(stored, headSha, threads) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};
     const threadBodyHashes = stored?.threadBodyHashes
@@ -148,6 +149,20 @@ export async function handleFixCode(ctx) {
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
     const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind);
+    const hasMergeGroupFailure = failingChecks.some((check) => check.scope === "merge_group");
+    const needsRequeue = Boolean(hasMergeGroupFailure || report.mergeQueue?.inQueue || report.mergeQueue?.latestRemoval);
+    const requeue = opts.merge && needsRequeue
+        ? buildMergeCommandPlan({
+            pr: report.pr,
+            repo: report.repo,
+            nodeId: report.nodeId,
+            headSha: "$HEAD_SHA",
+            queue: true,
+        })
+        : undefined;
+    if (requeue) {
+        instructions.splice(Math.max(0, instructions.length - 1), 0, "After all fixes and review mutations, replace `$HEAD_SHA` in the requeue commands with the full pushed PR-head SHA (or `$(git rev-parse HEAD)`). If GitHub no longer reports the PR in the merge queue, run the `requeue:` command shown above; if the gh CLI reports that auto-merge is disabled, run `requeue API fallback:` instead.");
+    }
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,
@@ -169,6 +184,7 @@ export async function handleFixCode(ctx) {
             firstLookComments,
             inProgressRunIds,
             protectedRuns,
+            ...(requeue && { requeue }),
         },
         cancelled,
     };

package/bin/commands/iterate/helpers.mjs

@@ -65,6 +65,8 @@ export function buildRelevantChecks(report) {
                 runId: c.runId,
                 detailsUrl: c.detailsUrl || null,
                 ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
+                ...(c.scope !== undefined && { scope: c.scope }),
+                ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
                 summary: c.summary,
             },
         ];
@@ -85,6 +87,8 @@ export function buildRelevantChecks(report) {
                 ...(c.summary !== undefined && { summary: c.summary }),
                 ...(c.logExcerpt !== undefined && { logExcerpt: c.logExcerpt }),
                 ...(c.annotations !== undefined && { annotations: c.annotations }),
+                ...(c.scope !== undefined && { scope: c.scope }),
+                ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
             },
         ];
     });
@@ -98,9 +102,10 @@ export function buildActiveChecks(report) {
         detailsUrl: c.detailsUrl || null,
         ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
         ...(c.summary !== undefined && { summary: c.summary }),
+        ...(c.scope !== undefined && { scope: c.scope }),
+        ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
     }));
 }
-// Best-effort: cancelling a completed run is a no-op, not an error.
 export async function tryCancelRun(runId, owner, repo) {
     try {
         await rest("POST", `/repos/${owner}/${repo}/actions/runs/${runId}/cancel`);
@@ -108,7 +113,6 @@ export async function tryCancelRun(runId, owner, repo) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        // GitHub returns 409 when the run reached a terminal state — expected, not worth logging.
         if (/409|already completed|cannot cancel a workflow run that is completed/i.test(msg))
             return null;
         process.stderr.write(`pr-shepherd: cancel run ${runId} failed (ignored): ${msg}\n`);

package/bin/commands/iterate/index.mjs

@@ -5,7 +5,7 @@ import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { EXIT, ShepherdError } from "../../exit-codes.mjs";
-import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, buildSuppressedCheckFields, buildTerminalCancelResult, blockedCancelNote, } from "./helpers.mjs";
+import { getCurrentHeadSha, buildWaitLog, buildTerminalCancelResult, blockedCancelNote, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
@@ -13,6 +13,8 @@ import { handleFixCode } from "./fix-code.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
 import { checksWithActionableAnnotations } from "../check-annotations.mjs";
+import { buildReadyMergeResult, handleActiveMergeState } from "./merge-state.mjs";
+import { buildIterateBase } from "./base.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
@@ -75,39 +77,10 @@ export async function runIterate(opts) {
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
         editedSummaries.length > 0;
-    const isCleanReadyHandoff = report.status === "READY" && !hasActionableWork;
+    const activeMerge = Boolean(opts.merge && (report.mergeQueue?.inQueue || report.mergeQueue?.autoMergeRequest));
+    const isCleanReadyHandoff = report.status === "READY" && !hasActionableWork && !activeMerge;
     const readyState = await updateReadyDelay(report.pr, isCleanReadyHandoff, readyDelaySeconds, repoOwner, repoName);
-    const base = {
-        pr: report.pr,
-        repo: report.repo,
-        status: report.status,
-        state: report.mergeStatus.state,
-        mergeStateStatus: report.mergeStatus.mergeStateStatus,
-        mergeStatus: report.mergeStatus.status,
-        reviewDecision: report.mergeStatus.reviewDecision,
-        blockingBotReviewInProgress: report.mergeStatus.blockingBotReviewInProgress,
-        isDraft: report.mergeStatus.isDraft,
-        shouldCancel: readyState.shouldCancel,
-        remainingSeconds: readyState.remainingSeconds,
-        summary: buildSummary(report),
-        baseBranch: report.baseBranch,
-        branchProtection: report.branchProtection,
-        mergeRequirements: report.mergeStatus.mergeRequirements,
-        checks: buildRelevantChecks(report),
-        inProgressChecks: buildActiveChecks(report),
-        ...buildSuppressedCheckFields(report),
-        activity: report.activity,
-    };
-    if (readyState.shouldCancel) {
-        await clearStallState(stallKey);
-        const cancelNote = blockedCancelNote(base);
-        return {
-            ...base,
-            action: "cancel",
-            reason: "ready-delay-elapsed",
-            log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
-        };
-    }
+    const base = buildIterateBase(report, readyState);
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     if (hasActionableWork) {
         return handleFixCode({
@@ -128,10 +101,18 @@ export async function runIterate(opts) {
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
+    const mergeStateResult = await handleActiveMergeState({
+        enabled: opts.merge,
+        active: activeMerge,
+        base,
+        report,
+        stallKey,
+    });
+    if (mergeStateResult)
+        return mergeStateResult;
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
-        !report.mergeStatus.blockingBotReviewInProgress &&
-        !readyState.shouldCancel;
+        !report.mergeStatus.blockingBotReviewInProgress;
     if (canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady) {
         await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });
         return {
@@ -141,5 +122,18 @@ export async function runIterate(opts) {
             log: `MARKED READY: PR #${report.pr} converted from draft to ready for review`,
         };
     }
+    if (readyState.shouldCancel) {
+        await clearStallState(stallKey);
+        const mergeResult = buildReadyMergeResult(opts.merge, true, base, report);
+        if (mergeResult)
+            return mergeResult;
+        const cancelNote = blockedCancelNote(base);
+        return {
+            ...base,
+            action: "cancel",
+            reason: "ready-delay-elapsed",
+            log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
+        };
+    }
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, { ...base, action: "wait", log: buildWaitLog(base) }, report, reviewSummaryIds);
 }

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

@@ -0,0 +1,15 @@
+import type { IterateResult, IterateResultBase, ShepherdReport } from "../../types.mts";
+type StallKey = {
+    owner: string;
+    repo: string;
+    pr: number;
+};
+export declare function buildReadyMergeResult(enabled: boolean | undefined, readyElapsed: boolean, base: IterateResultBase, report: ShepherdReport): IterateResult | null;
+export declare function handleActiveMergeState(input: {
+    enabled: boolean | undefined;
+    active: boolean;
+    base: IterateResultBase;
+    report: ShepherdReport;
+    stallKey: StallKey;
+}): Promise<IterateResult | null>;
+export {};

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

@@ -0,0 +1,53 @@
+import { clearStallState } from "../../state/iterate-stall.mjs";
+import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
+import { buildMergeCommandPlan } from "./merge.mjs";
+export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
+    if (!enabled || !readyElapsed || report.mergeStatus.isDraft)
+        return null;
+    const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
+        report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
+    return {
+        ...base,
+        action: "merge",
+        merge: buildMergeCommandPlan({
+            pr: report.pr,
+            repo: report.repo,
+            nodeId: report.nodeId,
+            headSha: report.headSha ?? "unknown",
+            queue,
+        }),
+    };
+}
+export async function handleActiveMergeState(input) {
+    const { enabled, active, base, report, stallKey } = input;
+    if (enabled && active) {
+        await clearStallState(stallKey);
+        return {
+            ...base,
+            action: "wait",
+            log: report.mergeQueue?.inQueue
+                ? `WAIT: PR #${report.pr} is in the merge queue`
+                : `WAIT: PR #${report.pr} has auto-merge enabled`,
+        };
+    }
+    const removal = report.mergeQueue?.latestRemoval;
+    if (!enabled || !removal || report.mergeQueue?.headUpdatedAfterRemoval)
+        return null;
+    await clearStallState(stallKey);
+    const escalateBase = {
+        triggers: ["merge-queue-removed"],
+        unresolvedThreads: [],
+        ambiguousComments: [],
+        changesRequestedReviews: [],
+        mergeQueueRemoval: removal,
+        suggestion: buildEscalateSuggestion(["merge-queue-removed"], removal.reason ?? "GitHub did not provide a reason"),
+    };
+    return {
+        ...base,
+        action: "escalate",
+        escalate: {
+            ...escalateBase,
+            humanMessage: buildEscalateHumanMessage(escalateBase, report.pr, { merge: true }),
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { MergeCommandPlan } from "../../types.mts";
+interface MergePlanInput {
+    pr: number;
+    repo: string;
+    nodeId: string;
+    headSha: string;
+    queue: boolean;
+}
+export declare function buildMergeCommandPlan(input: MergePlanInput): MergeCommandPlan;
+export declare function renderMergeCommand(command: {
+    argv: string[];
+}): string;
+export {};

package/bin/commands/iterate/merge.mjs

@@ -0,0 +1,46 @@
+import { loadConfig } from "../../config/load.mjs";
+import { findMergeStrategies } from "../../config/merge-command-args.mjs";
+import { renderShellCommand } from "../../cli/runner.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 configuredArgs = loadConfig().merge?.commandArgs ?? [];
+    const hasStrategy = findMergeStrategies(configuredArgs).length > 0;
+    const commandArgs = hasStrategy ? configuredArgs : [...configuredArgs, "--merge"];
+    return {
+        mode: "auto",
+        command: { argv: [...base, "--auto", ...commandArgs] },
+        fallbackCommand: { argv: [...base, ...commandArgs] },
+    };
+}
+export function renderMergeCommand(command) {
+    return renderShellCommand(command.argv);
+}

package/bin/commands/poll.mjs

@@ -112,7 +112,9 @@ export async function runPoll(opts) {
             await sleep(intervalMs);
             continue;
         }
-        if (untilTerminal && lastResult.action === "mark_ready" && !pastDebounce) {
+        if ((untilTerminal || iterateOpts.merge) &&
+            lastResult.action === "mark_ready" &&
+            !pastDebounce) {
             debounceUntil = null;
             await sleep(intervalMs);
             continue;

package/bin/commands/suggestion-patch-git.d.mts

@@ -0,0 +1,6 @@
+export declare function getLocalHeadSha(): Promise<string>;
+export declare function isAncestor(ancestor: string, descendant: string): Promise<boolean>;
+export declare function readPrHeadFile(headSha: string, path: string): Promise<string>;
+export declare function getPathsStatus(paths: readonly string[]): Promise<string>;
+/** Dry-run an ordered patch stream against the current worktree. */
+export declare function checkPatchesApply(patches: readonly string[]): Promise<void>;

package/bin/commands/suggestion-patch-git.mjs

@@ -0,0 +1,54 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { getExecutionCwd } from "../execution-context.mjs";
+const execFile = promisify(execFileCb);
+export async function getLocalHeadSha() {
+    const { stdout } = await execFile("git", ["rev-parse", "HEAD"], {
+        cwd: getExecutionCwd(),
+    });
+    return stdout.trim();
+}
+export async function isAncestor(ancestor, descendant) {
+    try {
+        await execFile("git", ["merge-base", "--is-ancestor", ancestor, descendant], {
+            cwd: getExecutionCwd(),
+        });
+        return true;
+    }
+    catch (error) {
+        if (isExitCode(error, 1) || isExitCode(error, 128))
+            return false;
+        throw error;
+    }
+}
+export async function readPrHeadFile(headSha, path) {
+    const { stdout } = await execFile("git", ["show", `${headSha}:${path}`], {
+        cwd: getExecutionCwd(),
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    return stdout;
+}
+export async function getPathsStatus(paths) {
+    const { stdout } = await execFile("git", ["status", "--porcelain", "--", ...paths], {
+        cwd: getExecutionCwd(),
+    });
+    return stdout.trim();
+}
+/** Dry-run an ordered patch stream against the current worktree. */
+export function checkPatchesApply(patches) {
+    const input = patches.join("\n");
+    return new Promise((resolve, reject) => {
+        const child = execFileCb("git", // NOSONAR -- resolve git through PATH consistently with all CLI git helpers.
+        ["apply", "--check"], { cwd: getExecutionCwd() }, (error, _stdout, stderr) => {
+            if (!error) {
+                resolve();
+                return;
+            }
+            reject(new Error(stderr.trim() || error.message));
+        });
+        child.stdin.end(input);
+    });
+}
+function isExitCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}

package/bin/commands/suggestion-patch-item.d.mts

@@ -0,0 +1,15 @@
+import type { ReviewThread, SuggestionPatchResult } from "../types.mts";
+export interface SuggestionPatchRequest {
+    threadId: string;
+    message: string;
+    description?: string;
+}
+export declare function validateSuggestionThread(thread: ReviewThread | null, request: SuggestionPatchRequest): ReviewThread;
+export declare function buildSuggestionPatchItem({ thread, request, originalContent, }: {
+    thread: ReviewThread;
+    request: SuggestionPatchRequest;
+    originalContent: string;
+}): SuggestionPatchResult;
+export declare function buildSingularInstructions(patch: SuggestionPatchResult, prNumber: number): string[];
+export declare function buildCommitCommand(patch: SuggestionPatchResult): string;
+export declare function quotePath(path: string): string;