pr-shepherd 0.42.0 → 0.43.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -9,7 +9,7 @@ An agent finishing a PR should think about code, not reconstruct GitHub state or
 ## What it does
 
 1. **Gather all context for a PR** in one invocation: review threads, comments, replies, summaries, CI, mergeability, merge requirements, first-look / outdated / edited items, and author provenance.
-2. **Provide deterministic actions for the agent**: exactly one of `WAIT`, `MARK_READY`, `FIX_CODE`, `CANCEL`, or `ESCALATE`, plus numbered `## Instructions` and explicit `apply` / `build_suggestion_patches` operations. The agent still decides whether a comment or CI failure needs a code change. Shepherd does not classify signal vs noise and does not mutate git.
+2. **Provide deterministic actions for the agent**: exactly one of `WAIT`, `MARK_READY`, `FIX_CODE`, `MERGE`, `CANCEL`, or `ESCALATE`, plus numbered `## Instructions` and explicit commands. The agent still decides whether a comment or CI failure needs a code change. Shepherd does not classify signal vs noise and does not mutate git.
 
 Highlights:
 
@@ -32,6 +32,7 @@ Each tick returns exactly one action:
 - `WAIT` — no immediate action; continue with the next poll.
 - `MARK_READY` — the CLI converted an eligible draft PR to ready; continue polling.
 - `FIX_CODE` — agent work is required; complete it, then continue polling.
+- `MERGE` — run the emitted auto-merge or merge-queue command, then continue polling.
 - `CANCEL` — stop polling because the PR merged, closed, or completed its ready-delay.
 - `ESCALATE` — stop polling until a human provides direction.
 
@@ -76,7 +77,7 @@ Conversations Resolved: No [Not Required]
 9. `[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.
 ```
 
-See [docs/actions.md](docs/actions.md) for the complete output contract. Iterate/poll PR outcomes use exit codes `0` and `10`–`14`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
+See [docs/actions.md](docs/actions.md) for the complete output contract. Iterate/poll PR outcomes use exit codes `0` and `10`–`15`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
 
 ## Workflow Assumptions
 
@@ -126,6 +127,7 @@ pr-shepherd 42 --quiet-status          # print only changed WAIT status snapshot
 pr-shepherd 42 --until-terminal        # continue through WAIT/MARK_READY until work or terminal state
 pr-shepherd 42 --debounce 5m           # wait 5m after first FIX_CODE, then return one batched tick
 pr-shepherd 42 --ready-delay 15m
+pr-shepherd 42 --merge                  # enable auto-merge or enter an enabled/required merge queue when ready
 pr-shepherd iterate 42                 # single tick
 ```
 
@@ -236,7 +238,10 @@ checks:
   ciTriggerEvents:
     - pull_request
     - pull_request_target
-    - merge_group
+merge:
+  commandArgs:
+    - --squash
+    - --delete-branch
 actions:
   autoMinimizeSuppressed: true
   autoMarkReady: false

package/bin/checks/classify.d.mts

@@ -20,7 +20,9 @@ import type { CheckRun, ClassifiedCheck } from "../types.mts";
  * @param checks Raw check runs from the batch query.
  * @returns Classified checks. "filtered" items were excluded from the tally.
  */
-export declare function classifyChecks(checks: CheckRun[]): ClassifiedCheck[];
+export declare function classifyChecks(checks: CheckRun[], opts?: {
+    additionalRelevantEvents?: string[];
+}): ClassifiedCheck[];
 export interface CiVerdict {
     /** True when all relevant (non-filtered, non-skipped, non-ignored) checks passed. */
     allPassed: boolean;

package/bin/checks/classify.mjs

@@ -22,9 +22,12 @@ import picomatch from "picomatch";
  * @param checks Raw check runs from the batch query.
  * @returns Classified checks. "filtered" items were excluded from the tally.
  */
-export function classifyChecks(checks) {
+export function classifyChecks(checks, opts = {}) {
     const config = loadConfig();
-    const relevantEvents = new Set(config.checks.ciTriggerEvents);
+    const relevantEvents = new Set([
+        ...config.checks.ciTriggerEvents,
+        ...(opts.additionalRelevantEvents ?? []),
+    ]);
     const isIgnored = buildMatcher(config.ignoreChecks ?? []);
     const isProtected = buildMatcher(config.actions.neverCancelRuns ?? []);
     const protectedRunIds = buildProtectedRunIds(checks, isProtected);

package/bin/cli/args.mjs

@@ -30,6 +30,7 @@ const BOOLEAN_FLAGS = new Set([
     "--no-auto-cancel-actionable",
     "--quiet-status",
     "--until-terminal",
+    "--merge",
     "--dry-run",
     "--verbose",
 ]);

package/bin/cli/default-poll.mjs

@@ -16,6 +16,7 @@ const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
     "--no-auto-cancel-actionable",
     "--quiet-status",
     "--until-terminal",
+    "--merge",
 ]);
 export function isDefaultPollInvocation(subcommand) {
     if (subcommand === "--help" || subcommand === "-h")

package/bin/cli/fix-formatter.mjs

@@ -1,10 +1,11 @@
 import { renderResolveCommand } from "../commands/iterate/render.mjs";
-import { joinSections } from "../util/markdown.mjs";
+import { inlineCode, joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
 import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, renderThreadConversation, blockquote, } from "./list-formatters.mjs";
 import { numberInstructions } from "./iterate-instructions.mjs";
 import { renderCheckAnnotation, renderProtectedRun } from "./fix-formatter-extra.mjs";
 import { isFailingAgentCheck } from "../checks/conclusions.mjs";
+import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 export function formatFixCodeResult(header, result) {
     const sections = [header];
     if (result.fix.threads.length > 0) {
@@ -50,7 +51,10 @@ export function formatFixCodeResult(header, result) {
                     ? `external \`${ch.detailsUrl}\``
                     : "(no runId)";
             const conclusionTag = ch.conclusion !== null ? ` [conclusion: ${ch.conclusion}]` : "";
-            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}`];
+            const scopeTag = ch.scope
+                ? ` [scope: ${ch.scope}${ch.commitOid ? `, commit: ${ch.commitOid}` : ""}]`
+                : "";
+            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${scopeTag}`];
             if (ch.conclusion !== "CANCELLED") {
                 if (ch.failedStep)
                     lines.push(`  > ${ch.failedStep}`);
@@ -133,6 +137,12 @@ export function formatFixCodeResult(header, result) {
     if (result.fix.resolveCommand.hasMutations) {
         postFixLines.push(`- apply review: \`${renderResolveCommand(result.fix.resolveCommand)}\``);
     }
+    if (result.fix.requeue) {
+        postFixLines.push(`- requeue: ${inlineCode(renderMergeCommand(result.fix.requeue.command))}`);
+        if (result.fix.requeue.queueApiFallbackCommand) {
+            postFixLines.push(`- requeue API fallback: ${inlineCode(renderMergeCommand(result.fix.requeue.queueApiFallbackCommand))}`);
+        }
+    }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
     sections.push(numberInstructions(result.fix.instructions));

package/bin/cli/handlers.mjs

@@ -124,6 +124,7 @@ export async function handleIterate(args) {
         stallTimeoutSeconds: flags.stallTimeoutSeconds,
         noAutoMarkReady: flags.noAutoMarkReady,
         noAutoCancelActionable: flags.noAutoCancelActionable,
+        merge: flags.merge,
     });
     emitIterateResult(result, {
         format: globalOpts.format,

package/bin/cli/help-command-pages.d.mts

@@ -192,8 +192,8 @@ Flags:
 
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
-    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.

package/bin/cli/help-iterate-poll-pages.d.mts

@@ -1,4 +1,4 @@
-export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-export declare const POLL_USAGE = "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+export declare const POLL_USAGE = "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
 /** Public help page for the default PR polling invocation. */
 export declare const DEFAULT_USAGE: string;

package/bin/cli/help-iterate-poll-pages.mjs

@@ -11,6 +11,7 @@ Iterate flags:
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
@@ -23,6 +24,7 @@ Actions:
   FIX_CODE    Agent action is required; follow the instructions, then continue polling.
   CANCEL      Stop polling: merged/closed or ready-delay elapsed.
   ESCALATE    Stop polling until a human provides direction.
+  MERGE       Run the emitted merge/queue command, then continue monitoring.
 
 Exit codes:
   0   CANCEL (merged or ready-delay elapsed)
@@ -31,6 +33,7 @@ Exit codes:
   12  FIX_CODE
   13  ESCALATE
   14  CANCEL (closed without merging)
+  15  MERGE
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 export const POLL_USAGE = `pr-shepherd poll
 
@@ -39,7 +42,7 @@ final tick to stdout.
 Poll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout
 returns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps
 iterating at --interval, then runs one more tick after the window and returns that result.
-With --until-terminal, poll also continues through MARK_READY.
+With --until-terminal or --merge, poll also continues through MARK_READY.
 
 Usage:
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
@@ -56,6 +59,7 @@ Forwarded iterate flags:
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields and detailed per-tick lines.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
@@ -65,7 +69,7 @@ for --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout);
 an explicit unit (4.5m).
 Each WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
 FIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.
-With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.
+With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.
 
 Exit codes: same as iterate (the final tick's action/reason decides the code).
   0   CANCEL (merged or ready-delay elapsed)
@@ -74,6 +78,7 @@ Exit codes: same as iterate (the final tick's action/reason decides the code).
   12  FIX_CODE
   13  ESCALATE
   14  CANCEL (closed without merging)
+  15  MERGE
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 /** Public help page for the default PR polling invocation. */
 export const DEFAULT_USAGE = POLL_USAGE.replace(/^pr-shepherd poll$/m, "pr-shepherd [PR]").replace(/^ {2}pr-shepherd poll \[PR\]/m, "  pr-shepherd [PR]");

package/bin/cli/help.d.mts

@@ -192,8 +192,8 @@ Flags:
 
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
-    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.

package/bin/cli/iterate-flags.d.mts

@@ -6,6 +6,7 @@ interface IterateFlags {
     stallTimeoutSeconds: number;
     noAutoMarkReady: boolean;
     noAutoCancelActionable: boolean;
+    merge: boolean;
 }
 export declare function parseIterateFlags(extra: string[], cfg: ReturnType<typeof loadConfig>): IterateFlags;
 export {};

package/bin/cli/iterate-flags.mjs

@@ -10,6 +10,7 @@ export function parseIterateFlags(extra, cfg) {
     const readyDelaySeconds = parseDurationToSeconds(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes * 60, MINUTE_FLAG_OPTS);
     const noAutoMarkReady = hasFlag(extra, "--no-auto-mark-ready");
     const noAutoCancelActionable = hasFlag(extra, "--no-auto-cancel-actionable");
+    const merge = hasFlag(extra, "--merge");
     const stallTimeoutStr = getFlag(extra, "--stall-timeout");
     const stallTimeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--stall-timeout", stallTimeoutStr, hasFlag(extra, "--stall-timeout"), MINUTE_FLAG_OPTS);
     const stallTimeoutSeconds = parseDurationToSeconds(stallTimeoutSuffix ?? "", cfg.iterate.stallTimeoutMinutes * 60, MINUTE_FLAG_OPTS);
@@ -20,5 +21,6 @@ export function parseIterateFlags(extra, cfg) {
         stallTimeoutSeconds,
         noAutoMarkReady,
         noAutoCancelActionable,
+        merge,
     };
 }

package/bin/cli/iterate-formatter.mjs

@@ -2,6 +2,7 @@ import { formatFixCodeResult } from "./fix-formatter.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, } from "./iterate-instructions.mjs";
 import { formatMergeRequirementLines } from "../merge-status/requirements-format.mjs";
+import { appendMergeQueueHeader, formatMergeAction } from "./iterate-merge-formatter.mjs";
 function formatActivityLine(result) {
     const activity = result.activity ?? {
         commitCount: 0,
@@ -89,7 +90,6 @@ export function formatIterateResult(result, opts) {
     }
     // Surface an explicit `--ready-delay` override (set only when the user passed the flag)
     // so the active settle window stays visible on every tick. Replaces the rerun command
-    // that previously carried the suffix in the (now removed) recheck instruction.
     if (readyDelaySuffix) {
         summaryLine += ` · **ready-delay** \`${readyDelaySuffix}\` (override)`;
     }
@@ -127,6 +127,7 @@ export function formatIterateResult(result, opts) {
         const names = result.supersededNames.map((n) => "`" + n + "`").join(", ");
         headerLines.push(`**superseded** ${names}`);
     }
+    appendMergeQueueHeader(headerLines, result);
     const activityLine = formatActivityLine(result);
     if (activityLine)
         headerLines.push(activityLine);
@@ -144,6 +145,8 @@ export function formatIterateResult(result, opts) {
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);
+        case "merge":
+            return formatMergeAction(header, result);
         case "cancel": {
             const cancelHeaderLines = [`${heading} — ${result.reason}`, "", baseLine, summaryLine];
             if (result.mergeRequirements) {

package/bin/cli/iterate-instructions.mjs

@@ -1,3 +1,5 @@
+import { renderMergeCommand } from "../commands/iterate/merge.mjs";
+import { inlineCode } from "../util/markdown.mjs";
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "wait":
@@ -8,6 +10,19 @@ export function buildSimpleIterateInstructions(result) {
             return [
                 "The CLI marked the PR ready for review. Iterate again with the same options to continue.",
             ];
+        case "merge": {
+            const instructions = [
+                `Run the \`${result.merge.mode === "queue" ? "merge queue" : "auto-merge"}\` command shown above exactly as printed.`,
+            ];
+            if (result.merge.mode === "queue" && result.merge.queueApiFallbackCommand) {
+                instructions.push(`If the gh CLI says auto-merge is disabled instead of adding the PR to the queue, run the \`queue API fallback\` command: ${inlineCode(renderMergeCommand(result.merge.queueApiFallbackCommand))}.`);
+            }
+            else if (result.merge.fallbackCommand) {
+                instructions.push(`Only if GitHub reports that auto-merge is unavailable, run the \`plain merge fallback\` command: ${inlineCode(renderMergeCommand(result.merge.fallbackCommand))}.`);
+            }
+            instructions.push("Then iterate again with the same options to monitor until the PR merges or needs work.");
+            return instructions;
+        }
         case "cancel":
             return ["Stop — the PR loop is complete. No further polling is needed."];
         case "escalate":

package/bin/cli/iterate-lean.d.mts

@@ -8,5 +8,4 @@ interface IterateProjectionOptions {
  * outside the state where they are meaningful.
  */
 export declare function projectIterateLean(result: IterateResult, opts?: IterateProjectionOptions): unknown;
-export declare function projectIterateVerbose(result: IterateResult, opts?: IterateProjectionOptions): unknown;
-export {};
+export { projectIterateVerbose } from "./iterate-verbose.mts";

package/bin/cli/iterate-lean.mjs

@@ -42,6 +42,7 @@ export function projectIterateLean(result, opts) {
         ...(result.baseBranch && { baseBranch: result.baseBranch }),
         ...(result.branchProtection !== null && { branchProtection: result.branchProtection }),
         ...(result.mergeRequirements && { mergeRequirements: result.mergeRequirements }),
+        ...(result.mergeQueue && { mergeQueue: result.mergeQueue }),
         ...(hasActivity && {
             activity: {
                 commitCount: activity.commitCount,
@@ -85,6 +86,12 @@ export function projectIterateLean(result, opts) {
                 log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };
+        case "merge":
+            return {
+                ...base,
+                merge: result.merge,
+                instructions: simpleInstructions(result),
+            };
         case "fix_code":
             return {
                 ...base,
@@ -122,6 +129,7 @@ export function projectIterateLean(result, opts) {
                     ...(result.fix.protectedRuns.length > 0 && {
                         protectedRuns: result.fix.protectedRuns,
                     }),
+                    ...(result.fix.requeue && { requeue: result.fix.requeue }),
                     ...(result.fix.checks.length > 0 && { checks: result.fix.checks }),
                     ...(result.fix.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.fix.changesRequestedReviews,
@@ -157,6 +165,9 @@ export function projectIterateLean(result, opts) {
                         result.escalate.thrashHistory.length > 0 && {
                         thrashHistory: result.escalate.thrashHistory,
                     }),
+                    ...(result.escalate.mergeQueueRemoval && {
+                        mergeQueueRemoval: result.escalate.mergeQueueRemoval,
+                    }),
                     suggestion: result.escalate.suggestion,
                     humanMessage: result.escalate.humanMessage,
                 },
@@ -164,20 +175,4 @@ export function projectIterateLean(result, opts) {
             };
     }
 }
-export function projectIterateVerbose(result, opts) {
-    const readyDelaySuffix = opts?.readyDelaySuffix;
-    const readyDelayOverride = readyDelaySuffix ? { readyDelayOverride: readyDelaySuffix } : {};
-    if (result.action === "fix_code") {
-        return {
-            ...result,
-            ...readyDelayOverride,
-        };
-    }
-    const log = "log" in result && typeof result.log === "string" ? { log: adaptIterateLog(result.log) } : {};
-    return {
-        ...result,
-        ...log,
-        ...readyDelayOverride,
-        instructions: buildSimpleIterateInstructions(result),
-    };
-}
+export { projectIterateVerbose } from "./iterate-verbose.mjs";

package/bin/cli/iterate-merge-formatter.d.mts

@@ -0,0 +1,3 @@
+import type { IterateResult, IterateResultMerge } from "../types.mts";
+export declare function appendMergeQueueHeader(lines: string[], result: IterateResult): void;
+export declare function formatMergeAction(header: string, result: IterateResultMerge): string;

package/bin/cli/iterate-merge-formatter.mjs

@@ -0,0 +1,52 @@
+import { renderMergeCommand } from "../commands/iterate/merge.mjs";
+import { inlineCode, joinSections } from "../util/markdown.mjs";
+import { buildSimpleIterateInstructions, numberInstructions } from "./iterate-instructions.mjs";
+export function appendMergeQueueHeader(lines, result) {
+    const queue = result.mergeQueue;
+    if (!queue)
+        return;
+    const parts = [`enabled \`${queue.enabled}\``, `inQueue \`${queue.inQueue}\``];
+    if (queue.entry) {
+        parts.push(`state \`${queue.entry.state}\``, `position \`${queue.entry.position}\``);
+        if (queue.entry.estimatedTimeToMerge !== null) {
+            parts.push(`estimatedTimeToMerge \`${queue.entry.estimatedTimeToMerge}\``);
+        }
+        if (queue.entry.enqueuedAtUnix !== undefined) {
+            parts.push(`enqueuedAtUnix \`${queue.entry.enqueuedAtUnix}\``);
+        }
+        if (queue.entry.enqueuer)
+            parts.push(`enqueuer \`@${queue.entry.enqueuer}\``);
+        if (queue.entry.headCommitOid)
+            parts.push(`headCommit \`${queue.entry.headCommitOid}\``);
+    }
+    if (queue.checkCommitOid)
+        parts.push(`checkCommit \`${queue.checkCommitOid}\``);
+    if (queue.checksIncomplete)
+        parts.push("checks incomplete (first 100 shown)");
+    if (queue.headUpdatedAfterRemoval)
+        parts.push("head updated after removal");
+    lines.push(`**merge queue** ${parts.join(" · ")}`);
+    if (queue.autoMergeRequest) {
+        lines.push(`**auto-merge** method \`${queue.autoMergeRequest.mergeMethod}\` · enabledAtUnix \`${queue.autoMergeRequest.enabledAtUnix}\`${queue.autoMergeRequest.enabledBy ? ` · by \`@${queue.autoMergeRequest.enabledBy}\`` : ""}`);
+    }
+    if (queue.latestRemoval) {
+        const removal = queue.latestRemoval;
+        lines.push(`**queue removal** reason \`${removal.reason ?? "not provided"}\` · createdAtUnix \`${removal.createdAtUnix}\`${removal.actor ? ` · actor \`@${removal.actor}\`` : ""}${removal.beforeCommitOid ? ` · commit \`${removal.beforeCommitOid}\`` : ""}${removal.beforeCommitParentOids ? ` · parents \`${removal.beforeCommitParentOids.join(",")}\`` : ""}`);
+    }
+}
+export function formatMergeAction(header, result) {
+    const commandLines = [
+        `- ${result.merge.mode === "queue" ? "merge queue" : "auto-merge"}: ${inlineCode(renderMergeCommand(result.merge.command))}`,
+    ];
+    if (result.merge.fallbackCommand) {
+        commandLines.push(`- plain merge fallback: ${inlineCode(renderMergeCommand(result.merge.fallbackCommand))}`);
+    }
+    if (result.merge.queueApiFallbackCommand) {
+        commandLines.push(`- queue API fallback: ${inlineCode(renderMergeCommand(result.merge.queueApiFallbackCommand))}`);
+    }
+    return joinSections([
+        header,
+        `## Merge command\n\n${commandLines.join("\n")}`,
+        `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
+    ]);
+}

package/bin/cli/iterate-verbose.d.mts

@@ -0,0 +1,6 @@
+import type { IterateResult } from "../types.mts";
+interface IterateProjectionOptions {
+    readyDelaySuffix?: string;
+}
+export declare function projectIterateVerbose(result: IterateResult, opts?: IterateProjectionOptions): unknown;
+export {};

package/bin/cli/iterate-verbose.mjs

@@ -0,0 +1,14 @@
+import { adaptIterateLog, buildSimpleIterateInstructions } from "./iterate-instructions.mjs";
+export function projectIterateVerbose(result, opts) {
+    const readyDelaySuffix = opts?.readyDelaySuffix;
+    const readyDelayOverride = readyDelaySuffix ? { readyDelayOverride: readyDelaySuffix } : {};
+    if (result.action === "fix_code")
+        return { ...result, ...readyDelayOverride };
+    const log = "log" in result && typeof result.log === "string" ? { log: adaptIterateLog(result.log) } : {};
+    return {
+        ...result,
+        ...log,
+        ...readyDelayOverride,
+        instructions: buildSimpleIterateInstructions(result),
+    };
+}

package/bin/cli/poll-handler.mjs

@@ -36,6 +36,7 @@ export async function handlePoll(args) {
         stallTimeoutSeconds: flags.stallTimeoutSeconds,
         noAutoMarkReady: flags.noAutoMarkReady,
         noAutoCancelActionable: flags.noAutoCancelActionable,
+        merge: flags.merge,
         intervalSeconds,
         timeoutSeconds,
         debounceSeconds,

package/bin/cli/runner.mjs

@@ -8,11 +8,12 @@ export function renderShellCommand(argv) {
 function renderShellArg(arg) {
     if (/^\$[A-Z_][A-Z0-9_]*$/.test(arg))
         return `"${arg}"`;
+    const assignment = /^([A-Za-z_][A-Za-z0-9_]*)=(\$[A-Z_][A-Z0-9_]*)$/.exec(arg);
+    if (assignment)
+        return `${assignment[1]}="${assignment[2]}"`;
     if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg))
         return arg;
     if (!/["$`\\]/.test(arg))
         return `"${arg}"`;
-    if (!arg.includes("'"))
-        return `'${arg}'`;
-    throw new Error(`Unexpected character in shell arg: ${JSON.stringify(arg)}`);
+    return `'${arg.replaceAll("'", `'"'"'`)}'`;
 }

package/bin/commands/check-terminal-report.mjs

@@ -2,6 +2,7 @@ export function buildTerminalReport(prNumber, repo, batchData, mergeStatus, stat
     return {
         pr: prNumber,
         nodeId: batchData.nodeId,
+        headSha: batchData.headRefOid,
         repo: `${repo.owner}/${repo.name}`,
         status,
         baseBranch: batchData.baseRefName,