pr-shepherd 0.41.0 → 0.43.0

package/bin/cli/help-top-page.mjs

@@ -10,7 +10,7 @@ Usage:
   pr-shepherd apply review [PR] [review-flags]
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
-  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG [flags]
+  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]
   pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]
   pr-shepherd admin log-file [--format text|json]
 
@@ -20,8 +20,8 @@ Commands:
   apply review         Apply review-state mutations after fixes.
   apply files          Mark changed files as viewed in GitHub.
   apply journal        Append a list item to the Shepherd Journal details block of a PR body.
-  build-suggestion-patch
-                       Convert one GitHub suggestion thread into a patch and commit instructions.
+  build-suggestion-patches
+                       Convert ordered GitHub suggestion threads into patches and commit instructions.
   admin clean          Remove pr-shepherd state files.
   admin log-file       Print the per-worktree debug log path.
 

package/bin/cli/help.d.mts

@@ -61,11 +61,27 @@ PR may be a number or GitHub pull request URL. An item must start with '- ' foll
 Use --file to read an item from a file, or --file - to read it from stdin. Exactly one item source
 is required. --dry-run previews the resulting body without writing it.
 --help, -h                      Print this help and exit before GitHub I/O.`;
-    readonly "build-suggestion-patch": `pr-shepherd build-suggestion-patch
+    readonly "build-suggestion-patches": `pr-shepherd build-suggestion-patches
 
-Build a patch and commit instructions for one GitHub review thread containing a suggestion block.
+Build an ordered list of patches and commit instructions from GitHub review suggestions.
 The command does not edit files or mutate git history.
 
+Usage:
+  pr-shepherd build-suggestion-patches [PR]
+    --thread-id ID --message MSG [--description DESC]
+    [--thread-id ID --message MSG [--description DESC] ...]
+    [--format text|json]
+
+Each --thread-id starts a suggestion group. Its following --message and optional --description
+belong to that suggestion. Groups are validated and returned in command-line order.
+
+The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head;
+every generated patch is dry-run in order with git apply --check before output.
+--help, -h                      Print this help and exit before GitHub, git, config, or log I/O.`;
+    readonly "build-suggestion-patch": `pr-shepherd build-suggestion-patch
+
+Deprecated one-suggestion adapter. Use build-suggestion-patches.
+
 Usage:
   pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG
                                       [--description DESC] [--format text|json]
@@ -76,7 +92,7 @@ Flags:
   --description <text>   Optional longer commit body.
   --format text|json     Output format. Default: text.
 
-The current branch must match the PR head ref and local HEAD must match the PR head SHA.
+The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head.
 --help, -h                      Print this help and exit before GitHub, git, config, or log I/O.`;
     readonly admin: `pr-shepherd admin
 
@@ -149,7 +165,7 @@ Flags:
   --help, -h             Print this help and exit before GitHub, git, config, or log I/O.
 
 Preconditions:
-  The current branch must match the PR head ref, and local HEAD must match the PR head SHA.
+  The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head.
 
 Exit codes:
   0   suggestion patch and instructions produced
@@ -176,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.
@@ -228,7 +244,7 @@ Flags:
 
 Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly "log-file": "pr-shepherd log-file\n\nPrint the per-worktree append-only debug log path for the current repository.\nThe log is created by the first non-help pr-shepherd command that initializes logging.\n\nUsage:\n  pr-shepherd log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
-    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark changed files as viewed in GitHub.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\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\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap 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\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\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)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
+    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark changed files as viewed in GitHub.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\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\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap 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\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\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)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
 };
 /** Resolve help keys for nested public commands before any command I/O. */
 export declare function helpKeyForArgs(args: string[]): keyof typeof USAGE;

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/cli/suggestion-patch-flags.d.mts

@@ -0,0 +1,11 @@
+import type { SuggestionPatchRequest } from "../commands/suggestion-patch-item.mts";
+type ParseFailure = {
+    ok: false;
+    error: string;
+};
+type ParseResult = {
+    ok: true;
+    suggestions: SuggestionPatchRequest[];
+} | ParseFailure;
+export declare function parseSuggestionPatchGroups(args: readonly string[]): ParseResult;
+export {};

package/bin/cli/suggestion-patch-flags.mjs

@@ -0,0 +1,83 @@
+export function parseSuggestionPatchGroups(args) {
+    const parsed = parseFlags(args);
+    if (!parsed.ok)
+        return parsed;
+    return groupFlags(parsed.flags);
+}
+function parseFlags(args) {
+    const flags = [];
+    for (let index = 0; index < args.length;) {
+        const parsed = parseFlag(args, index);
+        if (!parsed)
+            return { ok: false, error: `Unknown argument: ${args[index]}` };
+        flags.push(parsed);
+        index += parsed.consumed;
+    }
+    return { ok: true, flags };
+}
+function groupFlags(flags) {
+    const suggestions = [];
+    let current = null;
+    for (const flag of flags) {
+        if (flag.name === "--thread-id") {
+            const finalized = finalize(current);
+            if (!finalized.ok)
+                return finalized;
+            if (finalized.suggestion)
+                suggestions.push(finalized.suggestion);
+            current = { threadId: flag.value };
+            continue;
+        }
+        const updated = setMetadata(current, flag);
+        if (!updated.ok)
+            return updated;
+        current = updated.current;
+    }
+    const finalized = finalize(current);
+    if (!finalized.ok)
+        return finalized;
+    if (finalized.suggestion)
+        suggestions.push(finalized.suggestion);
+    if (suggestions.length === 0)
+        return { ok: false, error: "At least one --thread-id is required." };
+    return { ok: true, suggestions };
+}
+function setMetadata(current, flag) {
+    if (!current)
+        return { ok: false, error: `${flag.name} must follow --thread-id.` };
+    const property = flag.name === "--message" ? "message" : "description";
+    if (current[property] !== undefined) {
+        return { ok: false, error: `${flag.name} may appear only once per suggestion.` };
+    }
+    return { ok: true, current: { ...current, [property]: flag.value } };
+}
+function parseFlag(args, index) {
+    const arg = args[index];
+    for (const name of ["--thread-id", "--message", "--description"]) {
+        if (arg.startsWith(`${name}=`)) {
+            return { name, value: arg.slice(name.length + 1), consumed: 1 };
+        }
+        if (arg === name && index + 1 < args.length) {
+            return { name, value: args[index + 1], consumed: 2 };
+        }
+    }
+    return null;
+}
+function finalize(current) {
+    if (!current)
+        return { ok: true, suggestion: null };
+    if (!current.threadId || current.threadId.trim() === "") {
+        return { ok: false, error: "--thread-id must be non-empty." };
+    }
+    if (!current.message || current.message.trim() === "") {
+        return { ok: false, error: `--message is required for thread ${current.threadId}.` };
+    }
+    return {
+        ok: true,
+        suggestion: {
+            threadId: current.threadId,
+            message: current.message,
+            ...(current.description !== undefined && { description: current.description }),
+        },
+    };
+}

package/bin/cli-parser.mjs

@@ -8,7 +8,7 @@ import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
 import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
-import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
+import { handleClean, handleCommitSuggestion, handleSuggestionPatches, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
@@ -54,7 +54,8 @@ export async function main(argv) {
         resolve: "apply review",
         "mark-files-as-viewed": "apply files",
         journal: "apply journal",
-        "commit-suggestion": "build-suggestion-patch",
+        "build-suggestion-patch": "build-suggestion-patches",
+        "commit-suggestion": "build-suggestion-patches",
     };
     if (subcommand !== undefined && legacyReplacement[subcommand] !== undefined) {
         warnLegacyAlias(subcommand, legacyReplacement[subcommand]);
@@ -71,6 +72,9 @@ export async function main(argv) {
         case "apply":
             await handleApply(args.slice(1));
             break;
+        case "build-suggestion-patches":
+            await handleSuggestionPatches(args.slice(1));
+            break;
         case "build-suggestion-patch":
             await handleCommitSuggestion(args.slice(1));
             break;

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,

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/commit-suggestion-instruction.d.mts

@@ -1,5 +1,5 @@
 /**
- * Build the `build-suggestion-patch` instruction step for agent consumers.
+ * Build the `build-suggestion-patches` instruction step for agent consumers.
  * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
  * only the trigger and the concrete command; refusal/drift handling is invariant across
  * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook

package/bin/commands/commit-suggestion-instruction.mjs

@@ -1,6 +1,6 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
- * Build the `build-suggestion-patch` instruction step for agent consumers.
+ * Build the `build-suggestion-patches` instruction step for agent consumers.
  * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
  * only the trigger and the concrete command; refusal/drift handling is invariant across
  * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook
@@ -11,7 +11,7 @@ import { buildPrShepherdCommand } from "../cli/runner.mjs";
  */
 export function buildCommitSuggestionInstruction(prNumber, sectionName) {
     const command = buildPrShepherdCommand([
-        "build-suggestion-patch",
+        "build-suggestion-patches",
         String(prNumber),
         "--thread-id",
         "<id>",
@@ -19,5 +19,5 @@ export function buildCommitSuggestionInstruction(prNumber, sectionName) {
         "<one-sentence headline>",
         "--format=json",
     ]).text;
-    return `For each thread marked \`[suggestion]\` under \`${sectionName}\`, run \`${command}\` and apply the returned patch. See "Suggestion patches" in the pr-shepherd skill for refusals and drift.`;
+    return `For all threads marked \`[suggestion]\` under \`${sectionName}\`, run one \`${command}\` command, repeating the \`--thread-id <id> --message <one-sentence headline>\` group in displayed order, then apply the returned patches in order. See "Suggestion patches" in the pr-shepherd skill for refusals and drift.`;
 }

package/bin/commands/commit-suggestion.d.mts

@@ -4,5 +4,5 @@ export interface CommitSuggestionOptions extends GlobalOptions {
     message: string;
     description?: string;
 }
-/** @deprecated Hidden implementation for `commit-suggestion`; use `build-suggestion-patch`. */
+/** @deprecated Use runSuggestionPatches. */
 export declare function runCommitSuggestion(opts: CommitSuggestionOptions): Promise<CommitSuggestionResult>;