pr-shepherd 0.56.1 → 0.56.2

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.56.1",
+  "version": "0.56.2",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -35,7 +35,7 @@ Each tick returns exactly one action:
 - `MARK_READY` — the CLI converted an eligible draft PR to ready; continue polling.
 - `FIX_CODE` — agent work is required; complete it, push when needed, then continue polling. Push access to the PR head branch is a usage precondition.
 - `MERGE` — run the emitted head-pinned auto-merge or queue command. Ordinary merges include a plain-merge fallback; queue merges include a GraphQL enqueue fallback. GitHub is authoritative for the result and reports any authorization failure.
-- `CANCEL` — stop polling because the PR merged, closed, or completed its ready-delay.
+- `CANCEL` — stop polling this pull request because it merged, closed, or completed its ready-delay. Continue any remaining pull requests or issues from the original request.
 - `ESCALATE` — stop polling until a human provides direction. Native stacks reach this only after their autonomous one-PR sessions are exhausted.
 
 Native-stack summaries additionally use stack-level `SHEPHERD`: run the listed one-PR sessions,
@@ -122,7 +122,7 @@ Grok:
 /pr-shepherd 42
 ```
 
-MCP clients call `iterate` once per tick, then use `apply` for review/file/journal mutations and `build_suggestion_patches` for anchored suggestions. To read journal entries, call `extract_journal` with a body already in hand or `get_journal` with a repository-qualified PR reference. `iterate` returns the same structured action data as the CLI, including its review mutation arguments. The client owns recurrence, so this works consistently in Codex, Claude Code, Grok, and any other stdio MCP client.
+MCP clients call `iterate` once per tick, then use `apply` for review/file/journal mutations and validated queue-removal acknowledgments and `build_suggestion_patches` for anchored suggestions. To read journal entries, call `extract_journal` with a body already in hand or `get_journal` with a repository-qualified PR reference. `iterate` returns the same structured action data as the CLI, including its review mutation arguments. The client owns recurrence, so this works consistently in Codex, Claude Code, Grok, and any other stdio MCP client.
 
 The CLI remains useful for shell workflows. Its canonical polling form is:
 
@@ -141,6 +141,9 @@ pr-shepherd 42 43 44                   # summarize an explicit same-repository s
 pr-shepherd --stack 43                 # summarize every PR in a native GitHub stack
 ```
 
+A user-supplied `--merge` authorizes the agent to run the emitted merge/enqueue commands for the
+selected PRs or stack without another conversational confirmation. Host permission checks still apply.
+
 Multi-PR and `--stack` polling use compact, read-only GraphQL summaries. They return when work is
 needed, every selected PR is complete, the bounded timeout expires, or `--until-terminal` crosses a
 configured GraphQL quota-warning band. Explicit PR sets give each actionable row an exact single-PR
@@ -161,7 +164,7 @@ receipts, and whose bottom open layer GitHub has retargeted onto the stack base,
 with `gh stack merge <that PR number> --yes` and the allowed method flag (`--squash` unless config or the repository selects another). That lands the named layer and every
 unmerged layer below it. When the base uses a merge queue, the same command queues the prefix
 together and GitHub evaluates each layer from the bottom; a failure ejects that layer and those
-above it. Layers above the prefix keep their one-PR sessions. After the merge, GitHub retargets
+above it. If the evidence shows an unrelated failure and no source changes or other blockers remain, the one-PR session emits a head-, queue-commit-, and timestamp-pinned local acknowledgment command. Fresh source checks and a new READY receipt then let the aggregate selector recover the eligible prefix. Manual or stale removals cannot use this path. Layers above the prefix keep their one-PR sessions. After the merge, GitHub retargets
 the next layer, so the rerun continues until the stack returns `CANCEL`. API and MCP aggregate
 calls perform one summary tick and leave recurrence to the caller.
 
@@ -169,7 +172,7 @@ Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSecon
 
 ### Apply Review And Journal Changes, Or Select Files
 
-Use `apply` with ordered operations to reply/resolve/minimize/dismiss review items, mark selected changed files as viewed, or append an idempotent Shepherd Journal item. Explicit operations are attempted and surface GitHub's per-operation results; generated iterate guidance remains capability-filtered. Use `build_suggestion_patches` to turn ordered review suggestions into checked patches and commit metadata; it never changes the worktree or git history.
+Use `apply` with ordered operations to reply/resolve/minimize/dismiss review items, mark selected changed files as viewed, append an idempotent Shepherd Journal item, or record a validated native-stack CI queue-removal acknowledgment. Explicit operations are attempted and surface GitHub's per-operation results; generated iterate guidance remains capability-filtered. Use `build_suggestion_patches` to turn ordered review suggestions into checked patches and commit metadata; it never changes the worktree or git history.
 
 ### Extract Shepherd Journal Entries
 

package/bin/api.d.mts

@@ -1,5 +1,6 @@
 import { type JournalResult } from "./commands/journal/index.mts";
 import { type MarkFilesAsViewedResult } from "./commands/mark-files-as-viewed.mts";
+import { type ApplyQueueRemovalResult } from "./commands/apply-queue-removal.mts";
 import type { ResolveResult } from "./comments/resolve.mts";
 import type { BuildSuggestionPatchesResult, CommitSuggestionResult, IterateCommandOptions, IterateResult, PollSummaryResult } from "./types.mts";
 import { type ShepherdJournalExtraction } from "./journal/index.mts";
@@ -47,8 +48,14 @@ export interface AppendJournalOperation {
     item: string;
     dryRun?: boolean;
 }
+export interface AcknowledgeQueueRemovalOperation {
+    type: "acknowledge_queue_removal";
+    requireSha: string;
+    queueCommitOid: string;
+    removedAtUnix: number;
+}
 /** Operations run in this exact list order after validation. */
-export type ApplyOperation = ReviewMutationsOperation | MarkFilesViewedOperation | AppendJournalOperation;
+export type ApplyOperation = ReviewMutationsOperation | MarkFilesViewedOperation | AppendJournalOperation | AcknowledgeQueueRemovalOperation;
 export interface ApplyInput {
     /** PR shared by every operation in this ordered apply request. */
     pr?: PrReference;
@@ -63,6 +70,9 @@ export type ApplyOperationResult = {
 } | {
     type: "append_journal";
     result: JournalResult;
+} | {
+    type: "acknowledge_queue_removal";
+    result: ApplyQueueRemovalResult;
 };
 export interface ApplyResult {
     operations: ApplyOperationResult[];

package/bin/api.mjs

@@ -8,6 +8,7 @@ import { runJournal } from "./commands/journal/index.mjs";
 import { validateJournalItem } from "./commands/journal/transform.mjs";
 import { runMarkFilesAsViewed, } from "./commands/mark-files-as-viewed.mjs";
 import { runResolveMutate } from "./commands/resolve-mutate.mjs";
+import { applyQueueRemovalAck, } from "./commands/apply-queue-removal.mjs";
 import { runWithExecutionCwd } from "./execution-context.mjs";
 import { parsePrReference, normalizeRepositoryIdentity, resolveParsedPrTarget, } from "./pr-reference.mjs";
 import { getPullRequestBody, getRepoInfo } from "./github/client.mjs";
@@ -104,6 +105,17 @@ export function createPrShepherd(options = {}) {
                                 results.push({ type: operation.type, result });
                                 break;
                             }
+                            case "acknowledge_queue_removal": {
+                                const result = await applyQueueRemovalAck({
+                                    prNumber,
+                                    targetRepository,
+                                    headSha: operation.requireSha,
+                                    queueCommitOid: operation.queueCommitOid,
+                                    removedAtUnix: operation.removedAtUnix,
+                                });
+                                results.push({ type: operation.type, result });
+                                break;
+                            }
                         }
                     }
                     catch (error) {
@@ -206,6 +218,19 @@ function validateOperation(operation) {
                     throw new PrShepherdValidationError(validation.error);
             }
             return;
+        case "acknowledge_queue_removal":
+            if (typeof operation.requireSha !== "string" ||
+                !/^[0-9a-f]{40}$/.test(operation.requireSha)) {
+                throw new PrShepherdValidationError("acknowledge_queue_removal.requireSha must be a full 40-character lowercase hex SHA");
+            }
+            if (typeof operation.queueCommitOid !== "string" ||
+                !/^[0-9a-f]{40}$/.test(operation.queueCommitOid)) {
+                throw new PrShepherdValidationError("acknowledge_queue_removal.queueCommitOid must be a full 40-character lowercase hex SHA");
+            }
+            if (!Number.isSafeInteger(operation.removedAtUnix) || operation.removedAtUnix <= 0) {
+                throw new PrShepherdValidationError("acknowledge_queue_removal.removedAtUnix must be a positive Unix timestamp in seconds");
+            }
+            return;
         default:
             throw new PrShepherdValidationError(`Unsupported apply operation: ${JSON.stringify(operation.type)}`);
     }

package/bin/cli/args.mjs

@@ -23,6 +23,9 @@ const FLAGS_WITH_VALUES = new Set([
     "--match",
     "--check",
     "--blocked-by",
+    "--require-sha",
+    "--queue-commit",
+    "--removed-at",
 ]);
 // Boolean flags that do NOT consume the next argument. Any --flag not in this
 // set and not in FLAGS_WITH_VALUES is treated conservatively as value-taking

package/bin/cli/fix-formatter.mjs

@@ -191,6 +191,9 @@ export function formatFixCodeResult(header, result, opts = {}) {
             postFixLines.push(`- requeue API fallback: ${inlineCode(renderMergeCommand(result.fix.requeue.queueApiFallbackCommand))}`);
         }
     }
+    if (result.fix.queueRemovalAcknowledgment) {
+        postFixLines.push(`- acknowledge queue removal: ${inlineCode(renderMergeCommand(result.fix.queueRemovalAcknowledgment))}`);
+    }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
     sections.push(numberInstructions(result.fix.instructions));

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

@@ -11,8 +11,9 @@ Usage:
   pr-shepherd apply journal [PR] --file <path> [--dry-run] [--format text|json]
   pr-shepherd apply check-blocker [PR] --check <name> --blocked-by <ref>
   pr-shepherd apply check-blocker [PR] --check <name> --clear
+  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>
 
-Run 'pr-shepherd apply <review|files|journal|check-blocker> --help' for command-specific details.
+Run 'pr-shepherd apply <review|files|journal|check-blocker|queue-removal> --help' for command-specific details.
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply review": `pr-shepherd apply review
 
@@ -80,6 +81,20 @@ Usage:
 
 \`--clear\` removes that check's record and leaves other checks alone.
 --help, -h                      Print this help and exit before any I/O.`;
+    readonly "apply queue-removal": `pr-shepherd apply queue-removal
+
+Acknowledge one current CI-driven merge-queue removal for a native-stack PR.
+This writes local state only after a fresh GitHub read confirms the supplied head,
+queue commit, and removal timestamp still identify the current removal.
+
+Usage:
+  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>
+
+--require-sha <sha>       Full 40-character lowercase PR head SHA observed with the failure.
+--queue-commit <sha>      Full 40-character lowercase synthetic merge-group commit SHA.
+--removed-at <unix>       Removal time in Unix seconds.
+--format text|json        Output format. Default: text.
+--help, -h                Print this help and exit before any I/O.`;
     readonly "build-suggestion-patches": `pr-shepherd build-suggestion-patches
 
 Build an ordered list of patches and commit instructions from GitHub review suggestions.
@@ -212,7 +227,7 @@ 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    Legacy no-op; workflow runs are never cancelled.\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  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\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 or READY\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 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    Legacy no-op; workflow runs are never cancelled.\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  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling this pull request: merged/closed or ready-delay elapsed. Continue remaining work from the original request.\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 or READY\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 one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns READY, MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 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  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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    Legacy no-op; workflow runs are never cancelled.\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 a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, 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 READY, 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 or READY (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  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 

package/bin/cli/help-command-pages.mjs

@@ -14,8 +14,9 @@ Usage:
   pr-shepherd apply journal [PR] --file <path> [--dry-run] [--format text|json]
   pr-shepherd apply check-blocker [PR] --check <name> --blocked-by <ref>
   pr-shepherd apply check-blocker [PR] --check <name> --clear
+  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>
 
-Run 'pr-shepherd apply <review|files|journal|check-blocker> --help' for command-specific details.
+Run 'pr-shepherd apply <review|files|journal|check-blocker|queue-removal> --help' for command-specific details.
 --help, -h                      Print this help and exit before GitHub I/O.`,
     "apply review": `pr-shepherd apply review
 
@@ -83,6 +84,20 @@ Usage:
 
 \`--clear\` removes that check's record and leaves other checks alone.
 --help, -h                      Print this help and exit before any I/O.`,
+    "apply queue-removal": `pr-shepherd apply queue-removal
+
+Acknowledge one current CI-driven merge-queue removal for a native-stack PR.
+This writes local state only after a fresh GitHub read confirms the supplied head,
+queue commit, and removal timestamp still identify the current removal.
+
+Usage:
+  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>
+
+--require-sha <sha>       Full 40-character lowercase PR head SHA observed with the failure.
+--queue-commit <sha>      Full 40-character lowercase synthetic merge-group commit SHA.
+--removed-at <unix>       Removal time in Unix seconds.
+--format text|json        Output format. Default: text.
+--help, -h                Print this help and exit before any I/O.`,
     "build-suggestion-patches": `pr-shepherd build-suggestion-patches
 
 Build an ordered list of patches and commit instructions from GitHub review suggestions.

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    Legacy no-op; workflow runs are never cancelled.\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  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\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 or READY\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 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    Legacy no-op; workflow runs are never cancelled.\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  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling this pull request: merged/closed or ready-delay elapsed. Continue remaining work from the original request.\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 or READY\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 one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns READY, MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 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  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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    Legacy no-op; workflow runs are never cancelled.\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 a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, 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 READY, 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 or READY (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  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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

@@ -23,7 +23,7 @@ Actions:
   MARK_READY  Draft PR was marked ready; continue with the next poll.
   READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.
   FIX_CODE    Agent action is required; follow the instructions, then continue polling.
-  CANCEL      Stop polling: merged/closed or ready-delay elapsed.
+  CANCEL      Stop polling this pull request: merged/closed or ready-delay elapsed. Continue remaining work from the original request.
   ESCALATE    Stop polling until a human provides direction.
   MERGE       Run the emitted merge/queue command, then continue monitoring.
 

package/bin/cli/help-top-page.d.mts

@@ -1 +1 @@
-export declare const TOP_USAGE = "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 --stack 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 apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)\n  pr-shepherd journal extract --body-file <path>\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 one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  apply check-blocker  Record that a failing check is blocked on an external PR or issue.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\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, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\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    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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 or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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.";
+export declare const TOP_USAGE = "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 --stack 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 apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)\n  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>\n  pr-shepherd journal extract --body-file <path>\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 one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  apply check-blocker  Record that a failing check is blocked on an external PR or issue.\n  apply queue-removal  Acknowledge one current CI-driven native-stack queue removal.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\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, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\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    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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 or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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.";

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

@@ -12,6 +12,7 @@ Usage:
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
   pr-shepherd apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)
+  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>
   pr-shepherd journal extract --body-file <path>
   pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]
   pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]
@@ -24,6 +25,7 @@ Commands:
   apply files          Mark selected changed files as viewed.
   apply journal        Append a list item to the Shepherd Journal details block of a PR body.
   apply check-blocker  Record that a failing check is blocked on an external PR or issue.
+  apply queue-removal  Acknowledge one current CI-driven native-stack queue removal.
   journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.
   build-suggestion-patches
                        Convert ordered GitHub suggestion threads into patches and commit instructions.

package/bin/cli/help.d.mts

@@ -11,8 +11,9 @@ Usage:
   pr-shepherd apply journal [PR] --file <path> [--dry-run] [--format text|json]
   pr-shepherd apply check-blocker [PR] --check <name> --blocked-by <ref>
   pr-shepherd apply check-blocker [PR] --check <name> --clear
+  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>
 
-Run 'pr-shepherd apply <review|files|journal|check-blocker> --help' for command-specific details.
+Run 'pr-shepherd apply <review|files|journal|check-blocker|queue-removal> --help' for command-specific details.
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply review": `pr-shepherd apply review
 
@@ -80,6 +81,20 @@ Usage:
 
 \`--clear\` removes that check's record and leaves other checks alone.
 --help, -h                      Print this help and exit before any I/O.`;
+    readonly "apply queue-removal": `pr-shepherd apply queue-removal
+
+Acknowledge one current CI-driven merge-queue removal for a native-stack PR.
+This writes local state only after a fresh GitHub read confirms the supplied head,
+queue commit, and removal timestamp still identify the current removal.
+
+Usage:
+  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>
+
+--require-sha <sha>       Full 40-character lowercase PR head SHA observed with the failure.
+--queue-commit <sha>      Full 40-character lowercase synthetic merge-group commit SHA.
+--removed-at <unix>       Removal time in Unix seconds.
+--format text|json        Output format. Default: text.
+--help, -h                Print this help and exit before any I/O.`;
     readonly "build-suggestion-patches": `pr-shepherd build-suggestion-patches
 
 Build an ordered list of patches and commit instructions from GitHub review suggestions.
@@ -212,7 +227,7 @@ 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    Legacy no-op; workflow runs are never cancelled.\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  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\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 or READY\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 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    Legacy no-op; workflow runs are never cancelled.\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  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling this pull request: merged/closed or ready-delay elapsed. Continue remaining work from the original request.\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 or READY\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 one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns READY, MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 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  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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    Legacy no-op; workflow runs are never cancelled.\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 a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, 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 READY, 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 or READY (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  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 
@@ -277,7 +292,7 @@ On POSIX, the final body-file path entry must be a readable regular file in a tr
 symlinks, FIFOs, devices, and unreadable paths exit 66. Unsupported platforms fail closed with exit 66.
 --help, -h                      Print this help and exit before any I/O.`;
     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 --stack 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 apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)\n  pr-shepherd journal extract --body-file <path>\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 one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  apply check-blocker  Record that a failing check is blocked on an external PR or issue.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\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, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\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    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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 or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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 --stack 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 apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)\n  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>\n  pr-shepherd journal extract --body-file <path>\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 one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  apply check-blocker  Record that a failing check is blocked on an external PR or issue.\n  apply queue-removal  Acknowledge one current CI-driven native-stack queue removal.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\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, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\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    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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 or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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/help.mjs

@@ -15,6 +15,8 @@ export function helpKeyForArgs(args) {
         return "apply journal";
     if (args[0] === "apply" && args[1] === "check-blocker")
         return "apply check-blocker";
+    if (args[0] === "apply" && args[1] === "queue-removal")
+        return "apply queue-removal";
     if (args[0] === "journal" && args[1] === "extract")
         return "journal extract";
     if (args[0] === "admin" && args[1] === "clean")

package/bin/cli/iterate-instructions.mjs

@@ -48,7 +48,10 @@ export function buildSimpleIterateInstructions(result) {
             return instructions;
         }
         case "cancel":
-            return ["Stop — the PR loop is complete. No further polling is needed."];
+            return [
+                "Stop polling this pull request — its poll is complete.",
+                "Continue any remaining pull requests or issues from the original request.",
+            ];
         case "escalate": {
             const pending = result.escalate.pendingReviewCommands;
             if (!pending)

package/bin/cli/iterate-lean.mjs

@@ -152,6 +152,9 @@ export function projectIterateLean(result, opts) {
                         protectedRuns: result.fix.protectedRuns,
                     }),
                     ...(result.fix.requeue && { requeue: result.fix.requeue }),
+                    ...(result.fix.queueRemovalAcknowledgment && {
+                        queueRemovalAcknowledgment: result.fix.queueRemovalAcknowledgment,
+                    }),
                     ...(result.fix.checks.length > 0 && { checks: result.fix.checks }),
                     ...(result.fix.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.fix.changesRequestedReviews,

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

@@ -40,6 +40,8 @@ export function appendMergeQueueHeader(lines, result) {
         parts.push("checks incomplete (first 100 shown)");
     if (queue.headUpdatedAfterRemoval)
         parts.push("head updated after removal");
+    if (queue.removalAcknowledged)
+        parts.push("removal acknowledged");
     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}\`` : ""}`);

package/bin/cli/queue-removal-handler.d.mts

@@ -0,0 +1,2 @@
+/** `apply queue-removal`; help exits before argument validation and GitHub I/O. */
+export declare function handleQueueRemoval(args: string[]): Promise<void>;

package/bin/cli/queue-removal-handler.mjs

@@ -0,0 +1,86 @@
+import { EXIT, errorToExitCode } from "../exit-codes.mjs";
+import { applyQueueRemovalAck } from "../commands/apply-queue-removal.mjs";
+import { getFlag, parseCommonArgs } from "./args.mjs";
+import { maybePrintHelp, USAGE } from "./help.mjs";
+const FLAGS = new Set(["--require-sha", "--queue-commit", "--removed-at"]);
+/** `apply queue-removal`; help exits before argument validation and GitHub I/O. */
+export async function handleQueueRemoval(args) {
+    if (maybePrintHelp(args, "apply queue-removal"))
+        return;
+    const { prNumber, global, extra } = parseCommonArgs(args);
+    const flagError = validateFlags(extra);
+    if (flagError) {
+        usage(flagError);
+        return;
+    }
+    const headSha = getFlag(extra, "--require-sha");
+    const queueCommitOid = getFlag(extra, "--queue-commit");
+    const removedAtText = getFlag(extra, "--removed-at");
+    if (headSha === null || !/^[0-9a-f]{40}$/.test(headSha)) {
+        usage("--require-sha must be a full 40-character lowercase hex SHA.", EXIT.DATAERR);
+        return;
+    }
+    if (queueCommitOid === null || !/^[0-9a-f]{40}$/.test(queueCommitOid)) {
+        usage("--queue-commit must be a full 40-character lowercase hex SHA.", EXIT.DATAERR);
+        return;
+    }
+    if (removedAtText === null || !/^[1-9]\d*$/.test(removedAtText)) {
+        usage("--removed-at must be a positive Unix timestamp in seconds.", EXIT.DATAERR);
+        return;
+    }
+    const removedAtUnix = Number(removedAtText);
+    if (!Number.isSafeInteger(removedAtUnix)) {
+        usage("--removed-at must be a positive Unix timestamp in seconds.", EXIT.DATAERR);
+        return;
+    }
+    try {
+        const result = await applyQueueRemovalAck({
+            prNumber,
+            targetRepository: global.targetRepository,
+            headSha,
+            queueCommitOid,
+            removedAtUnix,
+        });
+        const body = global.format === "json"
+            ? JSON.stringify(result, null, 2)
+            : [
+                `PR: ${result.repo}#${result.pr}`,
+                `headSha: ${result.acknowledgment.headSha}`,
+                `queueCommitOid: ${result.acknowledgment.queueCommitOid}`,
+                `removedAtUnix: ${result.acknowledgment.removedAtUnix}`,
+            ].join("\n");
+        process.stdout.write(`${body}\n`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`pr-shepherd: apply queue-removal: ${message}\n`);
+        process.exitCode = errorToExitCode(err);
+    }
+}
+function validateFlags(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (!arg.startsWith("--"))
+            return `unexpected argument: "${arg}"`;
+        const eq = arg.indexOf("=");
+        const name = eq === -1 ? arg : arg.slice(0, eq);
+        if (!FLAGS.has(name))
+            return `unknown flag: "${name}"`;
+        if (eq !== -1) {
+            if (arg.slice(eq + 1) === "")
+                return `${name} requires a value.`;
+            continue;
+        }
+        const value = args[i + 1];
+        if (value === undefined || value.startsWith("--"))
+            return `${name} requires a value.`;
+        i += 1;
+    }
+    return null;
+}
+function usage(message, exitCode = EXIT.USAGE) {
+    process.stderr.write(`pr-shepherd: apply queue-removal: ${message}\n`);
+    if (exitCode === EXIT.USAGE)
+        process.stderr.write(`${USAGE["apply queue-removal"]}\n`);
+    process.exitCode = exitCode;
+}

package/bin/cli-parser.mjs

@@ -14,6 +14,7 @@ import { handleJournalExtract } from "./cli/journal-extract-handler.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
 import { handleCheckBlocker } from "./cli/check-blocker-handler.mjs";
+import { handleQueueRemoval } from "./cli/queue-removal-handler.mjs";
 import { setupLog } from "./log/setup.mjs";
 // ---------------------------------------------------------------------------
 // Entry
@@ -135,6 +136,9 @@ async function handleApply(args) {
         case "check-blocker":
             await handleCheckBlocker(args.slice(1));
             return;
+        case "queue-removal":
+            await handleQueueRemoval(args.slice(1));
+            return;
         default:
             process.stderr.write(`Unknown apply action: ${action ?? "(none)"}\n`);
             process.stderr.write(`${USAGE.apply}\n`);

package/bin/commands/apply-queue-removal.d.mts

@@ -0,0 +1,18 @@
+import { type QueueRemovalAcknowledgment } from "../state/queue-removal-ack.mts";
+export interface ApplyQueueRemovalInput {
+    prNumber?: number;
+    targetRepository?: {
+        owner: string;
+        name: string;
+    };
+    headSha: string;
+    queueCommitOid: string;
+    removedAtUnix: number;
+}
+export interface ApplyQueueRemovalResult {
+    pr: number;
+    repo: string;
+    acknowledgment: QueueRemovalAcknowledgment;
+}
+/** Validate an observed native-stack CI queue removal before recording the caller's acknowledgment. */
+export declare function applyQueueRemovalAck(input: ApplyQueueRemovalInput): Promise<ApplyQueueRemovalResult>;

package/bin/commands/apply-queue-removal.mjs

@@ -0,0 +1,44 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { fetchPrBatch } from "../github/batch.mjs";
+import { queueRemovalAppliesToHead } from "../github/queue-removal-freshness.mjs";
+import { getCurrentPrNumber, getRepoInfo } from "../github/client.mjs";
+import { isCiQueueRemovalReason, writeQueueRemovalAcknowledgment, } from "../state/queue-removal-ack.mjs";
+/** Validate an observed native-stack CI queue removal before recording the caller's acknowledgment. */
+export async function applyQueueRemovalAck(input) {
+    const repo = input.targetRepository ?? (await getRepoInfo());
+    const pr = input.prNumber ?? (await getCurrentPrNumber());
+    if (pr === null) {
+        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
+    }
+    const { data } = await fetchPrBatch(pr, repo);
+    const removal = data.latestMergeQueueRemoval;
+    if (data.state !== "OPEN" ||
+        !data.stack ||
+        data.isMergeQueueEnabled !== true ||
+        data.isInMergeQueue === true ||
+        !removal ||
+        !isCiQueueRemovalReason(removal.reason) ||
+        data.headRefOid !== input.headSha ||
+        removal.beforeCommitOid !== input.queueCommitOid ||
+        removal.createdAtUnix !== input.removedAtUnix ||
+        !queueRemovalAppliesToHead({
+            parentOids: removal.beforeCommitParentOids,
+            headOid: data.headRefOid,
+            ...(data.activity?.latestCommitCommittedAtUnix != null && {
+                headCommittedAtUnix: data.activity.latestCommitCommittedAtUnix,
+            }),
+            ...(data.headPushedAtUnix !== undefined && { headPushedAtUnix: data.headPushedAtUnix }),
+            removedAtUnix: removal.createdAtUnix,
+        })) {
+        throw new ShepherdError("The supplied queue-removal evidence is stale or is not a current CI-driven removal for this native-stack PR.", EXIT.UNAVAILABLE);
+    }
+    const acknowledgment = {
+        headSha: input.headSha,
+        queueCommitOid: input.queueCommitOid,
+        removedAtUnix: input.removedAtUnix,
+    };
+    if (!(await writeQueueRemovalAcknowledgment({ owner: repo.owner, repo: repo.name, pr }, acknowledgment))) {
+        throw new ShepherdError("Could not write queue-removal acknowledgment state.", EXIT.UNAVAILABLE);
+    }
+    return { pr, repo: `${repo.owner}/${repo.name}`, acknowledgment };
+}

package/bin/commands/check-fingerprint.mjs

@@ -10,6 +10,8 @@ function reportAllowsFingerprintSkip(report) {
         return false;
     if (report.mergeQueue?.inQueue === true)
         return false;
+    if (report.mergeQueue?.removalAcknowledged === true)
+        return false;
     return (report.threads.actionable.length === 0 &&
         report.threads.resolutionOnly.length === 0 &&
         report.threads.firstLook.length === 0 &&

package/bin/commands/check.mjs

@@ -1,5 +1,6 @@
 import { fetchPrBatch } from "../github/batch.mjs";
 import { queueRemovalAppliesToHead } from "../github/queue-removal-freshness.mjs";
+import { readQueueRemovalAcknowledgment, matchesQueueRemovalAcknowledgment, isCiQueueRemovalReason, } from "../state/queue-removal-ack.mjs";
 import { storePrFingerprint } from "../state/pr-fingerprint.mjs";
 import { tryReuseFingerprintReport } from "./check-fingerprint.mjs";
 import { collectUnreportedRequired, refreshCachedUnreported } from "./check-unreported.mjs";
@@ -91,9 +92,19 @@ export async function runCheck(opts, context) {
             }),
             removedAtUnix: latestRemoval.createdAtUnix,
         }));
+    const removalAcknowledged = Boolean(batchData.stack &&
+        latestRemoval?.beforeCommitOid &&
+        isCiQueueRemovalReason(latestRemoval.reason) &&
+        !batchData.isInMergeQueue &&
+        !headUpdatedAfterRemoval &&
+        matchesQueueRemovalAcknowledgment(await readQueueRemovalAcknowledgment(stateKey), {
+            headSha: batchData.headRefOid,
+            queueCommitOid: latestRemoval.beforeCommitOid,
+            removedAtUnix: latestRemoval.createdAtUnix,
+        }));
     const queueRawChecks = batchData.isInMergeQueue
         ? (batchData.mergeQueueChecks ?? [])
-        : latestRemoval && !headUpdatedAfterRemoval
+        : latestRemoval && !headUpdatedAfterRemoval && !removalAcknowledged
             ? (batchData.removedMergeQueueChecks ?? [])
             : [];
     // Keep supersession grouping commit-local, but accept merge_group only for the
@@ -356,6 +367,7 @@ export async function runCheck(opts, context) {
                     checksIncomplete: true,
                 }),
                 ...(headUpdatedAfterRemoval && { headUpdatedAfterRemoval: true }),
+                ...(removalAcknowledged && { removalAcknowledged: true }),
             },
         }),
         ...(unreported.unreportedRequiredChecks && {

package/bin/commands/iterate/check-evidence.d.mts

@@ -0,0 +1,4 @@
+import type { AgentCheck } from "../../types.mts";
+export declare function hasLogEvidence(check: AgentCheck): boolean;
+/** An external provider link is inspectable even when Actions log downloads are unavailable. */
+export declare function hasQueueRecoveryEvidence(check: AgentCheck): boolean;

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

@@ -0,0 +1,8 @@
+export function hasLogEvidence(check) {
+    return (Boolean(check.logExcerpt?.trim()) ||
+        (check.relatedJobs ?? []).some((job) => Boolean(job.logExcerpt?.trim())));
+}
+/** An external provider link is inspectable even when Actions log downloads are unavailable. */
+export function hasQueueRecoveryEvidence(check) {
+    return hasLogEvidence(check) || (check.runId === null && Boolean(check.detailsUrl?.trim()));
+}

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

@@ -6,6 +6,8 @@ import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, bui
 import { buildResolveCommand } from "./classify.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./thread-mutation-routing.mjs";
 import { buildFixInstructions } from "./render.mjs";
+import { buildRemovedQueueRecovery, buildStackQueueRemovalAcknowledgment } from "./merge.mjs";
+import { hasLogEvidence } from "./check-evidence.mjs";
 import { buildReleasedBlockerInstruction } from "./check-instructions.mjs";
 import { buildNativeStackLayerRebase } from "./native-stack-rebase.mjs";
 import { lookupUpperLayerTrunkConflict } from "./stack-trunk-conflict.mjs";
@@ -19,10 +21,6 @@ import { canRerunWorkflows } from "../../checks/conclusions.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 const EMPTY_RELEASED = new Set();
-function hasLogEvidence(check) {
-    return (Boolean(check.logExcerpt?.trim()) ||
-        (check.relatedJobs ?? []).some((job) => Boolean(job.logExcerpt?.trim())));
-}
 function checkRequiresHumanFollowUp(check) {
     if (check.rerunCommand)
         return false;
@@ -171,6 +169,8 @@ export async function handleFixCode(ctx) {
         if (releasedCheckNames.has(c.name))
             return c;
         return rerunAuthorized &&
+            // Rerunning queue CI cannot restore a removed entry and overwrites its failure evidence.
+            c.scope !== "merge_group" &&
             c.runId &&
             actionsRunIds.has(c.runId) &&
             // GitHub increments run_attempt after every rerun. Recommend at most one rerun by limiting
@@ -306,6 +306,20 @@ export async function handleFixCode(ctx) {
         ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict)
         : undefined;
     const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase);
+    const requeue = buildRemovedQueueRecovery(report, failingAgentChecks, opts.merge);
+    const queueRemovalAcknowledgment = buildStackQueueRemovalAcknowledgment(report, failingAgentChecks);
+    if (queueRemovalAcknowledgment) {
+        const completion = instructions.pop();
+        instructions.push("If the merge-group failure belongs to this PR, fix and push its head, then iterate. Otherwise, if no code changed and no other blocker remains, run `acknowledge queue removal:` exactly as printed. This records only the disposition of that removed queue commit; finish this one-PR session to validate current source CI and record its READY receipt, then return to the aggregate `--stack` selector with its original options. In merge mode it verifies lower-layer readiness before merging. Do not enqueue or merge this layer directly.");
+        if (completion !== undefined)
+            instructions.push(completion);
+    }
+    if (requeue) {
+        const completion = instructions.pop();
+        instructions.push("If the merge-group failure belongs to this PR, fix and push the PR head, then iterate. Otherwise, if no code changed and no other blocker remains, run the `requeue:` command exactly as printed. If gh reports auto-merge is disabled instead of adding the PR to the queue, run the `requeue API fallback:` command. Both commands require the observed PR head SHA; if the head changed, iterate for a fresh command.");
+        if (completion !== undefined)
+            instructions.push(completion);
+    }
     if (failingAgentChecks.some((check) => releasedCheckNames.has(check.name))) {
         const completion = instructions.pop();
         instructions.push(buildReleasedBlockerInstruction(prNumber));
@@ -342,6 +356,8 @@ export async function handleFixCode(ctx) {
             editedSummaries,
             surfacedApprovals,
             checks,
+            ...(requeue && { requeue }),
+            ...(queueRemovalAcknowledgment && { queueRemovalAcknowledgment }),
             changesRequestedReviews,
             resolveCommand,
             ...(resolveOnlyCommand !== undefined ? { resolveOnlyCommand } : undefined),

package/bin/commands/iterate/index.mjs

@@ -109,7 +109,9 @@ async function runIterateCore(opts) {
         editedSummaries.length > 0 ||
         (config.iterate.minimizeApprovals && surfacedApprovals.length > 0);
     const hasActionableWork = hasReadinessWork || report.comments.firstLook.length > 0;
-    const activeMerge = Boolean(opts.merge && (report.mergeQueue?.inQueue || report.mergeQueue?.autoMergeRequest));
+    const activeMerge = Boolean(opts.merge &&
+        (report.mergeQueue?.inQueue ||
+            (report.mergeQueue?.autoMergeRequest && !report.mergeQueue.removalAcknowledged)));
     const staleAncestry = await findStaleNativeStackAncestry(report, {
         owner: repoOwner,
         name: repoName,
@@ -307,6 +309,18 @@ async function recordReadyReceipt(key, report, context) {
         if (!isCurrentSummaryReady(raw, summary.checks ?? {}, summary.review ?? {}))
             return false;
         const removalEvent = currentQueueRemovalEvent(raw);
+        // Bind recovery to the exact evidence the one-PR check accepted. A new ejection
+        // between that check and this fresh snapshot must get its own acknowledgment.
+        if (report.mergeQueue?.removalAcknowledged) {
+            const accepted = report.mergeQueue.latestRemoval;
+            if (raw.isInMergeQueue ||
+                !accepted ||
+                !removalEvent ||
+                removalEvent.beforeCommit?.oid !== accepted.beforeCommitOid ||
+                Math.floor(Date.parse(removalEvent.createdAt) / 1000) !== accepted.createdAtUnix ||
+                removalEvent.reason !== accepted.reason)
+                return false;
+        }
         await writeReadyReceipt({
             version: 1,
             ...key,

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

@@ -115,7 +115,10 @@ export async function handleActiveMergeState(input) {
         };
     }
     const removal = report.mergeQueue?.latestRemoval;
-    if (!enabled || !removal || report.mergeQueue?.headUpdatedAfterRemoval)
+    if (!enabled ||
+        !removal ||
+        report.mergeQueue?.headUpdatedAfterRemoval ||
+        report.mergeQueue?.removalAcknowledged)
         return null;
     await clearStallState(stallKey);
     const escalateBase = {

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

@@ -1,5 +1,5 @@
 import { type MergeMethod } from "../../config/merge-method.mts";
-import type { IterateResult, IterateResultBase, MergeCommandPlan } from "../../types.mts";
+import type { AgentCheck, IterateResult, IterateResultBase, MergeCommandPlan, ShepherdReport } from "../../types.mts";
 interface MergePlanInput {
     pr: number;
     repo: string;
@@ -16,6 +16,12 @@ export declare function buildMergeCommandPlan(input: MergePlanInput): MergeComma
 export declare function renderMergeCommand(command: {
     argv: string[];
 }): string;
+/** Offer a guarded queue command; the caller decides whether the failure warrants a PR fix. */
+export declare function buildRemovedQueueRecovery(report: ShepherdReport, checks: AgentCheck[], merge: boolean | undefined): MergeCommandPlan | undefined;
+/** Bind a caller's disposition to one removed stack queue commit, without submitting a merge. */
+export declare function buildStackQueueRemovalAcknowledgment(report: ShepherdReport, checks: AgentCheck[]): {
+    argv: string[];
+} | undefined;
 export declare function unavailableMergeResult(base: IterateResultBase, report: {
     pr: number;
     repo: string;

package/bin/commands/iterate/merge.mjs

@@ -2,7 +2,9 @@ import { loadConfig } from "../../config/load.mjs";
 import { findMergeStrategies } from "../../config/merge-command-args.mjs";
 import { chooseMergeMethod, configuredMergeMethod, } from "../../config/merge-method.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
-import { renderShellCommand } from "../../cli/runner.mjs";
+import { renderShellCommand, buildPrShepherdCommand } from "../../cli/runner.mjs";
+import { hasQueueRecoveryEvidence } from "./check-evidence.mjs";
+import { isCiQueueRemovalReason } from "../../state/queue-removal-ack.mjs";
 import { buildEscalateHumanMessage } from "./escalate.mjs";
 const ENQUEUE_MUTATION = "mutation EnqueuePullRequest($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: { pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid }) { mergeQueueEntry { id } } }";
 export function buildMergeCommandPlan(input) {
@@ -55,6 +57,62 @@ export function buildMergeCommandPlan(input) {
 export function renderMergeCommand(command) {
     return renderShellCommand(command.argv);
 }
+/** Offer a guarded queue command; the caller decides whether the failure warrants a PR fix. */
+export function buildRemovedQueueRecovery(report, checks, merge) {
+    if (report.mergeStatus.mergeRequirements?.stack)
+        return undefined;
+    if (!removedQueueRecoveryAvailable(report, checks, merge))
+        return undefined;
+    const plan = buildMergeCommandPlan({
+        pr: report.pr,
+        repo: report.repo,
+        nodeId: report.nodeId,
+        headSha: report.headSha,
+        queue: true,
+    });
+    return "unavailable" in plan ? undefined : plan;
+}
+/** Bind a caller's disposition to one removed stack queue commit, without submitting a merge. */
+export function buildStackQueueRemovalAcknowledgment(report, checks) {
+    if (!report.mergeStatus.mergeRequirements?.stack)
+        return undefined;
+    // This records a local disposition, without enqueueing; aggregate child sessions omit --merge.
+    if (!removedQueueRecoveryAvailable(report, checks, true))
+        return undefined;
+    const removal = report.mergeQueue.latestRemoval;
+    return buildPrShepherdCommand([
+        "apply",
+        "queue-removal",
+        formatPrUrl(report.repo, report.pr),
+        "--require-sha",
+        report.headSha,
+        "--queue-commit",
+        removal.beforeCommitOid,
+        "--removed-at",
+        String(removal.createdAtUnix),
+    ]);
+}
+function removedQueueRecoveryAvailable(report, checks, merge) {
+    const queue = report.mergeQueue;
+    const removedCommit = queue?.latestRemoval?.beforeCommitOid;
+    if (!merge ||
+        !queue?.enabled ||
+        queue.inQueue ||
+        queue.headUpdatedAfterRemoval ||
+        // GitHub exposes a raw string, not a capability to reverse a human's queue removal.
+        // Only known CI-driven reasons authorize offering automated recovery.
+        !isCiQueueRemovalReason(queue.latestRemoval?.reason) ||
+        !queue.latestRemoval ||
+        queue.latestRemoval.createdAtUnix <= 0 ||
+        !removedCommit ||
+        !report.headSha ||
+        !report.nodeId ||
+        !checks.some((check) => check.scope === "merge_group" && check.commitOid === removedCommit))
+        return false;
+    return checks
+        .filter((check) => check.scope === "merge_group" && check.commitOid === removedCommit)
+        .every(hasQueueRecoveryEvidence);
+}
 export function unavailableMergeResult(base, report, unavailable) {
     const escalateBase = {
         triggers: ["merge-method-unavailable"],

package/bin/github/poll-summary-fingerprint.mjs

@@ -8,6 +8,10 @@ import { createHash } from "node:crypto";
 export function fingerprintRawSummaryPr(raw) {
     if (!raw.updatedAt || !raw.headRefOid || !raw.baseRefOid)
         return null;
+    const reviewTruncated = raw.comments.pageInfo.hasPreviousPage ||
+        raw.reviews.pageInfo.hasPreviousPage ||
+        raw.reviewThreads.pageInfo.hasPreviousPage ||
+        raw.reviewThreads.nodes.some((thread) => thread.comments.pageInfo.hasPreviousPage);
     const evidence = {
         number: raw.number,
         state: raw.state,
@@ -19,6 +23,9 @@ export function fingerprintRawSummaryPr(raw) {
         reviewDecision: raw.reviewDecision,
         reviewRequests: raw.reviewRequests,
         latestReviews: raw.latestReviews,
+        // Omitted bodies cannot participate in the hash. Bind truncated evidence
+        // to the PR revision instead, so updates require a fresh full review poll.
+        ...(reviewTruncated && { reviewUpdatedAt: raw.updatedAt }),
         comments: hideBodies(raw.comments),
         reviews: hideBodies(raw.reviews),
         reviewThreads: {

package/bin/github/poll-summary-readiness.mjs

@@ -1,4 +1,6 @@
 import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
+import { parseBranchRules } from "./batch-parsers-rules.mjs";
+import { rulesComplete } from "./fingerprint-fields.mjs";
 /** Fresh compact evidence required before a READY receipt can be used. */
 export function isCurrentSummaryReady(raw, checks, review, options = {}) {
     const queued = options.allowQueuedProgress === true && raw.isInMergeQueue;
@@ -8,9 +10,17 @@ export function isCurrentSummaryReady(raw, checks, review, options = {}) {
     const sourceChecks = queued
         ? summarizePollSummaryChecks({ ...raw, mergeQueueEntry: null })
         : checks;
+    // The full one-PR check already surfaces review feedback. Certification
+    // need not reread historical conversations unless their resolution is a
+    // merge requirement. GitHub's CLEAN state proves that requirement is
+    // satisfied. BLOCKED is not conversation-specific, and queue progress
+    // alone is not that proof.
+    const requiresConversationResolution = parseBranchRules(raw.baseRef).requiresConversationResolution;
     return (checks.incomplete !== true &&
         sourceChecks.incomplete !== true &&
-        review.incomplete !== true &&
+        (review.incomplete !== true ||
+            raw.mergeStateStatus === "CLEAN" ||
+            (rulesComplete(raw.baseRef) && !requiresConversationResolution)) &&
         raw.state === "OPEN" &&
         !raw.isDraft &&
         raw.mergeable !== "CONFLICTING" &&

package/bin/mcp/server.mjs

@@ -60,6 +60,12 @@ const appendJournalOperationSchema = z.object({
     item: z.string(),
     dryRun: z.boolean().optional(),
 });
+const acknowledgeQueueRemovalOperationSchema = z.object({
+    type: z.literal("acknowledge_queue_removal"),
+    requireSha: z.string().regex(/^[0-9a-f]{40}$/),
+    queueCommitOid: z.string().regex(/^[0-9a-f]{40}$/),
+    removedAtUnix: z.number().int().positive().safe(),
+});
 const applyInputSchema = z.object({
     pr,
     operations: z
@@ -67,6 +73,7 @@ const applyInputSchema = z.object({
         reviewMutationsOperationSchema,
         markFilesViewedOperationSchema,
         appendJournalOperationSchema,
+        acknowledgeQueueRemovalOperationSchema,
     ]))
         .min(1),
 });
@@ -234,6 +241,17 @@ function formatApplyResult(result) {
                 return `${heading}\n\n${formatMarkFilesAsViewedResult(operation.result)}`;
             case "append_journal":
                 return `${heading}\n\n${formatJournalResult(operation.result)}`;
+            case "acknowledge_queue_removal": {
+                const result = operation.result;
+                return [
+                    heading,
+                    "",
+                    `PR: ${result.repo}#${result.pr}`,
+                    `headSha: ${result.acknowledgment.headSha}`,
+                    `queueCommitOid: ${result.acknowledgment.queueCommitOid}`,
+                    `removedAtUnix: ${result.acknowledgment.removedAtUnix}`,
+                ].join("\n");
+            }
         }
     })
         .join("\n\n");

package/bin/state/queue-removal-ack.d.mts

@@ -0,0 +1,19 @@
+/** A caller's acknowledgment of one observed CI-driven native-stack queue removal. */
+export interface QueueRemovalAcknowledgment {
+    headSha: string;
+    queueCommitOid: string;
+    removedAtUnix: number;
+}
+type StateKey = {
+    owner: string;
+    repo: string;
+    pr: number;
+};
+/** The only removal reasons that indicate a CI-driven queue ejection. */
+export declare function isCiQueueRemovalReason(reason: string | null | undefined): boolean;
+/** Missing, unreadable, or malformed acknowledgment state is treated as absent. */
+export declare function readQueueRemovalAcknowledgment(key: StateKey): Promise<QueueRemovalAcknowledgment | null>;
+/** Atomically store one acknowledgment. */
+export declare function writeQueueRemovalAcknowledgment(key: StateKey, acknowledgment: QueueRemovalAcknowledgment): Promise<boolean>;
+export declare function matchesQueueRemovalAcknowledgment(acknowledgment: QueueRemovalAcknowledgment | null, expected: Pick<QueueRemovalAcknowledgment, "headSha" | "queueCommitOid" | "removedAtUnix">): acknowledgment is QueueRemovalAcknowledgment;
+export {};

package/bin/state/queue-removal-ack.mjs

@@ -0,0 +1,66 @@
+/** A caller's acknowledgment of one observed CI-driven native-stack queue removal. */
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+const FILE = "queue-removal-ack.json";
+/** The only removal reasons that indicate a CI-driven queue ejection. */
+export function isCiQueueRemovalReason(reason) {
+    return reason === "CI_FAILURE" || reason === "MERGE_QUEUE_POLICY_CHECK_FAILURE";
+}
+/** Missing, unreadable, or malformed acknowledgment state is treated as absent. */
+export async function readQueueRemovalAcknowledgment(key) {
+    try {
+        const parsed = JSON.parse(await readFile(resolvePrStatePath(key, FILE), "utf8"));
+        return isAcknowledgment(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomically store one acknowledgment. */
+export async function writeQueueRemovalAcknowledgment(key, acknowledgment) {
+    if (!isAcknowledgment(acknowledgment))
+        return false;
+    let tmp;
+    try {
+        const path = resolvePrStatePath(key, FILE);
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(tmp, `${JSON.stringify(acknowledgment)}\n`, "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // A failed write may not have created the temporary file.
+            }
+        }
+    }
+}
+export function matchesQueueRemovalAcknowledgment(acknowledgment, expected) {
+    return (acknowledgment !== null &&
+        acknowledgment.headSha === expected.headSha &&
+        acknowledgment.queueCommitOid === expected.queueCommitOid &&
+        acknowledgment.removedAtUnix === expected.removedAtUnix);
+}
+function isAcknowledgment(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.headSha === "string" &&
+        /^[0-9a-f]{40}$/.test(candidate.headSha) &&
+        typeof candidate.queueCommitOid === "string" &&
+        /^[0-9a-f]{40}$/.test(candidate.queueCommitOid) &&
+        typeof candidate.removedAtUnix === "number" &&
+        Number.isSafeInteger(candidate.removedAtUnix) &&
+        candidate.removedAtUnix > 0);
+}

package/bin/types/iterate.d.mts

@@ -124,6 +124,10 @@ interface FixRebaseAndPush {
     protectedRuns: ProtectedRun[];
     /** Requeue command emitted after merge-group remediation. */
     requeue?: MergeCommandPlan;
+    /** Acknowledge an unrelated native-stack queue failure before fresh READY validation. */
+    queueRemovalAcknowledgment?: {
+        argv: string[];
+    };
     /** First-look threads — previously hidden, surfaced for acknowledgment only. */
     firstLookThreads: FirstLookThread[];
     /** First-look comments — previously hidden, surfaced for acknowledgment only. */

package/bin/types/merge-queue.d.mts

@@ -10,6 +10,8 @@ export interface MergeQueueReport {
     checksIncomplete?: true;
     /** The current PR head is not a parent of the removed synthetic queue commit. */
     headUpdatedAfterRemoval?: true;
+    /** The caller acknowledged this exact native-stack removal on the current head. */
+    removalAcknowledged?: true;
 }
 /**
  * Raw counts of actionable work held back while the PR sits in the merge queue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.56.1",
+  "version": "0.56.2",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.56.1",
+  "version": "0.56.2",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.56.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.56.2", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.56.1", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.56.2", "pr-shepherd-mcp"]
   }
 }

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob", "Edit", "Write"]
 
 # pr-shepherd
 
-Poll with the CLI. Use MCP `iterate` only when the CLI is unavailable. Stop at `[CANCEL]` or `[ESCALATE]`.
+Poll with the CLI. Use MCP `iterate` only when the CLI is unavailable. Stop polling the selected pull request at `[CANCEL]` or `[ESCALATE]`.
 
 ## Create a PR
 
@@ -21,7 +21,8 @@ Poll with the CLI. Use MCP `iterate` only when the CLI is unavailable. Stop at `
 ## Dispatch
 
 - Parse `$ARGUMENTS` for PR numbers, `owner/repo#N`, GitHub PR URLs, one `--stack PR`, and an optional `--merge`. Reject any other argument.
-- A request to merge, land, or enqueue the selected PR or stack sets `--merge`. Creating or opening a PR does not.
+- A user-supplied `--merge` explicitly authorizes merging or enqueueing the selected PR or stack. Run the emitted merge/enqueue commands without asking for another conversational confirmation; request runtime escalation when the host requires it.
+- A request to merge, land, or enqueue the selected PR or stack also sets `--merge`. Creating or opening a PR without merge intent leaves merge mode off.
 - A request to shepherd or merge a native stack, with an anchor PR and no literal `--stack`, uses that PR as the `--stack` selector. Otherwise infer the current branch PR.
 - Follow the target repository's `AGENTS.md` while editing.
 - CLI: turn `owner/repo#N` into `https://github.com/owner/repo/pull/N`. Pass other URLs and bare numbers through.

package/plugins/pr-shepherd/skills/pr-shepherd/references/ci-failure-triage.md

@@ -6,6 +6,7 @@ Apply when a step says `Playbook: "CI failure triage"`. For a GitHub Actions row
 - `[rerun authorized]` plus a `rerun:` command means the viewer can rerun Actions (WRITE+) and this is the original attempt. Shepherd checked `repositoryPermission` and `run_attempt`.
 - Run that printed command at most once. An `[attempt: N]` check never gets another rerun. A log excerpt on a later attempt is still investigation work. A later attempt with no usable evidence escalates when nothing else remains.
 - A run in progress, `[conclusion: ACTION_REQUIRED]`, a check whose run id is not a GitHub Actions workflow, or a run with no attempt metadata never gets `[rerun authorized]`.
+- A check with `scope: merge_group` never gets a rerun command. Rerunning cannot restore a removed queue entry and overwrites the failure evidence. If the failure belongs to this PR, fix the PR head. If it does not, follow the printed requeue instruction when a plan is present. Without `--merge`, report the failure without enqueueing. For native stacks, child sessions omit `--merge` and may still record the printed local acknowledgment after inspecting logs or an external provider URL. Complete fresh one-PR READY validation before returning to the aggregate selector with its original options; never enqueue a stack layer directly.
 - Do not invent a handoff from `[FIX_CODE]`. Shepherd returns `[ESCALATE]` when no autonomous follow-up remains.
 - Several bullets can share one run id (matrix jobs). The `rerun:` command is printed once, on the first bullet. Run it once.