pr-shepherd 0.42.0 → 0.43.0

package/bin/commands/check.mjs

@@ -42,7 +42,22 @@ export async function runCheck(opts) {
         ? []
         : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
-    const classifiedChecks = classifyChecks(allChecks);
+    const classifiedPrChecks = classifyChecks(allChecks);
+    const latestRemoval = batchData.latestMergeQueueRemoval;
+    const headUpdatedAfterRemoval = Boolean(latestRemoval &&
+        latestRemoval.beforeCommitParentOids &&
+        !latestRemoval.beforeCommitParentOids.includes(batchData.headRefOid));
+    const queueRawChecks = batchData.isInMergeQueue
+        ? (batchData.mergeQueueChecks ?? [])
+        : latestRemoval && !headUpdatedAfterRemoval
+            ? (batchData.removedMergeQueueChecks ?? [])
+            : [];
+    // Keep supersession grouping commit-local, but accept merge_group only for the
+    // synthetic queue-commit source.
+    const classifiedQueueChecks = classifyChecks(queueRawChecks, {
+        additionalRelevantEvents: ["merge_group"],
+    });
+    const classifiedChecks = [...classifiedPrChecks, ...classifiedQueueChecks];
     const verdict = getCiVerdict(classifiedChecks);
     const passing = classifiedChecks.filter((c) => c.category === "passed");
     const failing = classifiedChecks.filter((c) => c.category === "failing");
@@ -131,9 +146,17 @@ export async function runCheck(opts) {
         }
     }
     const blockedByFilteredCheck = isBlockedByFilteredCheck(mergeStatus, verdict);
+    const queueCommit = batchData.isInMergeQueue
+        ? batchData.mergeQueueEntry?.headCommitOid
+        : batchData.latestMergeQueueRemoval?.beforeCommitOid;
+    const hasQueueState = Boolean(batchData.isMergeQueueEnabled ||
+        batchData.isInMergeQueue ||
+        batchData.autoMergeRequest ||
+        batchData.latestMergeQueueRemoval);
     return {
         pr: prNumber,
         nodeId: batchData.nodeId,
+        headSha: batchData.headRefOid,
         repo: `${repo.owner}/${repo.name}`,
         status,
         baseBranch: batchData.baseRefName,
@@ -175,6 +198,24 @@ export async function runCheck(opts) {
             : undefined),
         branchProtection: batchData.branchProtection,
         activity: batchData.activity,
+        ...(hasQueueState && {
+            mergeQueue: {
+                enabled: Boolean(batchData.isMergeQueueEnabled),
+                inQueue: Boolean(batchData.isInMergeQueue),
+                ...(batchData.autoMergeRequest && { autoMergeRequest: batchData.autoMergeRequest }),
+                ...(batchData.mergeQueueEntry && { entry: batchData.mergeQueueEntry }),
+                ...(batchData.latestMergeQueueRemoval && {
+                    latestRemoval: batchData.latestMergeQueueRemoval,
+                }),
+                ...(queueCommit && { checkCommitOid: queueCommit }),
+                ...((batchData.isInMergeQueue
+                    ? batchData.mergeQueueChecksIncomplete
+                    : batchData.removedMergeQueueChecksIncomplete) && {
+                    checksIncomplete: true,
+                }),
+                ...(headUpdatedAfterRemoval && { headUpdatedAfterRemoval: true }),
+            },
+        }),
     };
 }
 async function remainingRuleAutoResolveIds(partition, autoMinimizeSuppressed = false) {

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/config/load.d.mts

@@ -43,6 +43,10 @@ interface PrShepherdConfig {
     mergeStatus: {
         blockingReviewerLogins: string[];
     };
+    merge?: {
+        /** Options added to ordinary `gh pr merge` commands. Queue commands never use these. */
+        commandArgs: string[];
+    };
     actions: {
         autoMinimizeSuppressed: boolean;
         autoMarkReady: boolean;

package/bin/config/load.mjs

@@ -5,6 +5,7 @@ import { homedir } from "node:os";
 import { parse } from "yaml";
 import builtins from "../config.json" with { type: "json" };
 import { getEffectiveCwd } from "../execution-context.mjs";
+import { findMergeStrategies } from "./merge-command-args.mjs";
 const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
 const RC_FILENAME = ".pr-shepherdrc.yml";
 /**
@@ -85,6 +86,35 @@ function parseNeverCancelRuns(value) {
     }
     return value;
 }
+const SHEPHERD_OWNED_MERGE_FLAGS = [
+    "--repo",
+    "-R",
+    "--auto",
+    "--disable-auto",
+    "--match-head-commit",
+    "--admin",
+    "--body-file",
+    "-F",
+    "--help",
+    "-h",
+];
+function parseMergeCommandArgs(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new Error("Invalid config: merge.commandArgs must be an array of strings");
+    }
+    for (const arg of value) {
+        if (SHEPHERD_OWNED_MERGE_FLAGS.some((flag) => arg === flag ||
+            arg.startsWith(`${flag}=`) ||
+            (flag.startsWith("-") && !flag.startsWith("--") && arg.startsWith(flag)))) {
+            throw new Error(`Invalid config: merge.commandArgs cannot include Shepherd-owned ${arg}`);
+        }
+    }
+    const strategies = findMergeStrategies(value);
+    if (strategies.length > 1) {
+        throw new Error(`Invalid config: merge.commandArgs includes multiple merge strategies: ${strategies.join(", ")}`);
+    }
+    return strategies.length === 0 ? [...value, "--merge"] : [...value];
+}
 const KNOWN_CONFIG_KEYS = new Set([
     "classify",
     "botUsernames",
@@ -94,6 +124,7 @@ const KNOWN_CONFIG_KEYS = new Set([
     "resolve",
     "checks",
     "mergeStatus",
+    "merge",
     "actions",
 ]);
 const KNOWN_NESTED_KEYS = {
@@ -108,6 +139,7 @@ const KNOWN_NESTED_KEYS = {
     resolve: new Set(["shaPoll"]),
     checks: new Set(["ciTriggerEvents"]),
     mergeStatus: new Set(["blockingReviewerLogins"]),
+    merge: new Set(["commandArgs"]),
     actions: new Set([
         "autoMinimizeSuppressed",
         "autoMarkReady",
@@ -194,6 +226,8 @@ export function loadConfig() {
         config.botUsernames = parseBotUsernames(config.botUsernames);
         config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
         config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
+        if (config.merge)
+            config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
         config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
         configCache.set(cwd, config);
         return config;

package/bin/config/merge-command-args.d.mts

@@ -0,0 +1,2 @@
+/** Return active merge strategies while validating compound strategy syntax. */
+export declare function findMergeStrategies(args: string[]): string[];

package/bin/config/merge-command-args.mjs

@@ -0,0 +1,44 @@
+const MERGE_STRATEGY_FLAGS = new Map([
+    ["--merge", "merge"],
+    ["-m", "merge"],
+    ["--squash", "squash"],
+    ["-s", "squash"],
+    ["--rebase", "rebase"],
+    ["-r", "rebase"],
+]);
+/** Return active merge strategies while validating compound strategy syntax. */
+export function findMergeStrategies(args) {
+    const strategies = [];
+    for (const arg of args) {
+        const exact = MERGE_STRATEGY_FLAGS.get(arg);
+        if (exact) {
+            strategies.push(exact);
+            continue;
+        }
+        const longAssignment = /^(--merge|--squash|--rebase)=(.*)$/.exec(arg);
+        const shortAssignment = /^(-[msr])=(.*)$/.exec(arg);
+        const assignment = longAssignment ?? shortAssignment;
+        if (assignment) {
+            if (assignment[2] !== "true" && assignment[2] !== "false") {
+                throw new Error(`Invalid config: merge.commandArgs strategy ${arg} must use true or false`);
+            }
+            if (assignment[2] === "true") {
+                strategies.push(MERGE_STRATEGY_FLAGS.get(assignment[1]));
+            }
+            continue;
+        }
+        const shortBundle = /^-([dmrs]{2,})$/.exec(arg);
+        if (shortBundle) {
+            for (const flag of shortBundle[1]) {
+                const strategy = MERGE_STRATEGY_FLAGS.get(`-${flag}`);
+                if (strategy)
+                    strategies.push(strategy);
+            }
+            continue;
+        }
+        if (/^-[dmrs].+/.test(arg)) {
+            throw new Error(`Invalid config: merge.commandArgs cannot safely parse compound short option ${arg}; use separate flags or long options`);
+        }
+    }
+    return strategies;
+}

package/bin/config.json

@@ -36,6 +36,9 @@
   "mergeStatus": {
     "blockingReviewerLogins": ["copilot"]
   },
+  "merge": {
+    "commandArgs": []
+  },
   "actions": {
     "autoMinimizeSuppressed": true,
     "autoMarkReady": true,

package/bin/exit-codes.d.mts

@@ -23,6 +23,8 @@ export declare const EXIT: Readonly<{
     readonly ESCALATE: 13;
     /** `cancel` + `closed` — PR closed without merging. */
     readonly CLOSED: 14;
+    /** Agent should run the emitted merge or queue command. */
+    readonly MERGE: 15;
     /** Bad/unknown flag, unknown subcommand, missing required arg, invalid duration. */
     readonly USAGE: 64;
     /** Malformed caller data: bad `--require-sha`, `PRRC_*` IDs, bad repo string. */

package/bin/exit-codes.mjs

@@ -22,6 +22,8 @@ export const EXIT = Object.freeze({
     ESCALATE: 13,
     /** `cancel` + `closed` — PR closed without merging. */
     CLOSED: 14,
+    /** Agent should run the emitted merge or queue command. */
+    MERGE: 15,
     /** Bad/unknown flag, unknown subcommand, missing required arg, invalid duration. */
     USAGE: 64,
     /** Malformed caller data: bad `--require-sha`, `PRRC_*` IDs, bad repo string. */
@@ -65,6 +67,8 @@ export function iterateResultToExitCode(result) {
             return EXIT.FIX_CODE;
         case "escalate":
             return EXIT.ESCALATE;
+        case "merge":
+            return EXIT.MERGE;
     }
 }
 export function errorToExitCode(err) {

package/bin/github/batch-parse-checks.d.mts

@@ -0,0 +1,3 @@
+import type { CheckRun } from "../types.mts";
+import type { RawContextNode } from "./batch-raw-types.mts";
+export declare function parseCheckNodes(nodes: Array<RawContextNode | null> | undefined, mergeCommitOid?: string): CheckRun[];