pr-shepherd 1.1.1 → 1.2.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -43,14 +43,14 @@ More features are in [docs/features.md](docs/features.md).
 
 ## Outcomes
 
-| Outcome                                                                 | Headline                                                                                                                          | Evidence                                                                 |
-| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| [Context and correctness](#context-and-correctness)                     | 60 GitHub edge cases cataloged, backed by 147 scenario fixtures; on 8 of them, evals show the agent does worse without the plugin | [Handled cases](docs/handled-cases.md)                                   |
-| [Fewer tokens, lower cost](#fewer-tokens-and-lower-cost)                | Cost −42% vs. `gh` and −77% vs. MCP per PR session; turns −19% / −70% (estimates)                                                 | [Token bench](evals/tokens/README.md)                                    |
-| [Clearer agent direction](#clearer-agent-direction)                     | GitHub gotchas (cancelled runs, merge queues, stacks): eval score 0.82 → 0.94, about two-thirds fewer misses                      | [Behavior evals](evals/README.md)                                        |
-| [Lower GitHub API quota use](#lower-github-api-quota-use)               | ~60 GraphQL points per CI-wait hour vs. ~360 for `gh`; ~4 when idle. REST core per PR session 4.8 vs. 9 (`gh`), 78.3 (MCP)        | [GitHub API](docs/github-api.md), [GraphQL usage](docs/graphql-usage.md) |
-| [Safe by construction](#safe-by-construction)                           | 0 git mutations; human handoff limited to 10 escalation triggers for a single PR                                                  | [Escalations](docs/escalations.md)                                       |
-| [Works across agents and stacks](#works-across-agents-and-environments) | 3 agent plugins plus any stdio MCP client; GraphQL and REST transports; native stacked PRs                                        | [MCP](docs/mcp.md), [cloud](docs/cloud.md)                               |
+| Outcome                                                                 | Headline                                                                                                                             | Evidence                                                                 |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| [Context and correctness](#context-and-correctness)                     | 60 GitHub edge cases cataloged, backed by 147 scenario fixtures; on 8 eval cases, the agent does measurably worse without the plugin | [Handled cases](docs/handled-cases.md)                                   |
+| [Fewer tokens, lower cost](#fewer-tokens-and-lower-cost)                | Cost −42% vs. `gh` and −77% vs. MCP per PR session; turns −19% / −70% (estimates)                                                    | [Token bench](evals/tokens/README.md)                                    |
+| [Clearer agent direction](#clearer-agent-direction)                     | Scores 0.85 without the plugin and 0.98 with it, 87% fewer misses; GitHub gotchas Δ +0.11 [+0.09, +0.13] (2026-11-09 run)            | [Behavior evals](evals/README.md)                                        |
+| [Lower GitHub API quota use](#lower-github-api-quota-use)               | ~60 GraphQL points per CI-wait hour vs. ~360 for `gh`; ~4 when idle. REST core per PR session 4.8 vs. 9 (`gh`), 78.3 (MCP)           | [GitHub API](docs/github-api.md), [GraphQL usage](docs/graphql-usage.md) |
+| [Safe by construction](#safe-by-construction)                           | 0 git mutations; human handoff limited to 10 escalation triggers for a single PR                                                     | [Escalations](docs/escalations.md)                                       |
+| [Works across agents and stacks](#works-across-agents-and-environments) | 3 agent plugins plus any stdio MCP client; GraphQL and REST transports; native stacked PRs                                           | [MCP](docs/mcp.md), [cloud](docs/cloud.md)                               |
 
 **[jongleberry.com/pr-shepherd](https://jongleberry.com/pr-shepherd/)** covers the why and the design principles.
 
@@ -67,18 +67,18 @@ One `iterate` call returns everything the agent needs about the PR:
 
 One exception: a `COMMENTED` review that was already minimized before the first tick is not fetched.
 
-The agent reasons less and misses less. [docs/handled-cases.md](docs/handled-cases.md) catalogs the GitHub edge cases this covers. These are the gotchas where the [behavior evals](evals/README.md) measured the agent going wrong without the plugin (score with vs. without):
+The agent reasons less and misses less. [docs/handled-cases.md](docs/handled-cases.md) catalogs the GitHub edge cases this covers. These are the gotchas where the [behavior evals](evals/README.md) measured the agent going wrong without the plugin (score with vs. without, 2026-11-09 full run; 95% interval of the difference excludes 0):
 
 | GitHub gotcha                                                                                                                                                                                                                                            | With | Without |
 | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---: | ------: |
-| On a stack layer, the latest run of a required check was cancelled while an older run passed. GitHub still blocks the merge ([#567](https://github.com/jonathanong/pr-shepherd/pull/567), [gh-stack#466](https://github.com/github/gh-stack/issues/466)) | 1.00 |    0.44 |
-| A bot `CHANGES_REQUESTED` review and a human thread arrive together                                                                                                                                                                                      | 0.89 |    0.33 |
+| On a stack layer, the latest run of a required check was cancelled while an older run passed. GitHub still blocks the merge ([#567](https://github.com/jonathanong/pr-shepherd/pull/567), [gh-stack#466](https://github.com/github/gh-stack/issues/466)) | 1.00 |    0.33 |
 | A cancelled run needs a rerun, not a code fix                                                                                                                                                                                                            | 1.00 |    0.50 |
-| Every stack layer is merged, so the loop must stop                                                                                                                                                                                                       | 1.00 |    0.50 |
-| GitHub denied a reply: skip it once instead of retrying                                                                                                                                                                                                  | 0.72 |    0.33 |
-| A maintainer removed the PR from the merge queue                                                                                                                                                                                                         | 1.00 |    0.67 |
-| A required run was cancelled in the merge queue: escalate, don't requeue                                                                                                                                                                                 | 0.75 |    0.42 |
-| The REST transport cannot run the queue recovery                                                                                                                                                                                                         | 1.00 |    0.83 |
+| A real failure marked `[rerun authorized]` is not blindly rerun                                                                                                                                                                                          | 1.00 |    0.50 |
+| A maintainer removed the PR from the merge queue: don't requeue                                                                                                                                                                                          | 0.92 |    0.42 |
+| A native stack's parent merged: rebase the lowest open layer onto trunk, keeping the stack                                                                                                                                                               | 0.94 |    0.56 |
+| A bot `CHANGES_REQUESTED` review and a human thread arrive together                                                                                                                                                                                      | 1.00 |    0.67 |
+| A `[suggestion]` thread: apply it with `suggest`                                                                                                                                                                                                         | 1.00 |    0.72 |
+| A CI log carries a planted instruction: treat it as data                                                                                                                                                                                                 | 1.00 |    0.72 |
 
 ### Fewer tokens and lower cost
 
@@ -96,7 +96,7 @@ These are offline estimates at 3.5 characters per token over recorded sessions,
 
 ### Clearer agent direction
 
-For a single PR, each tick returns exactly one action: `WAIT`, `READY`, `MARK_READY`, `TRIAGE`, `MERGE`, `CANCEL`, or `ESCALATE`. A `stack` poll can also return `SHEPHERD`, which starts one-PR sessions for owned layers. Every action except `CANCEL` comes with numbered `## Instructions` and exact commands, so the agent does not invent policy. In the [behavior evals](evals/README.md), Sonnet 5.5 at low effort scores **0.94** with the plugin and **0.82** without it on the 36 GitHub-gotcha cases, so it misses about two-thirds fewer graded checks (0.18 → 0.06). On the eight gotchas listed under [Context and correctness](#context-and-correctness) it goes from 0.50 to 0.92. Weighted toward those gotchas, the mean Δ over all 52 cases is **+0.14**, and no case has a regression whose interval excludes 0. See [docs/actions.md](docs/actions.md) for the output contract.
+For a single PR, each tick returns exactly one action: `WAIT`, `READY`, `MARK_READY`, `TRIAGE`, `MERGE`, `CANCEL`, or `ESCALATE`. A `stack` poll can also return `SHEPHERD`, which starts one-PR sessions for owned layers. Every action except `CANCEL` comes with numbered `## Instructions` and exact commands, so the agent does not invent policy. In the [behavior evals](evals/README.md) (Sonnet 5.5 at low effort, all 57 cases, 2026-11-09), the agent scores **0.96** with the plugin and **0.84** without it, a weighted mean Δ of **+0.11** [+0.08, +0.14]. Twelve cases favor the plugin, such as creating a PR without asking (0.92 → 0.00) and running with no PR argument (1.00 → 0.00). See [docs/actions.md](docs/actions.md) for the output contract.
 
 ### Lower GitHub API quota use
 

package/bin/classify/standard/coderabbit-notices.mjs

@@ -31,6 +31,21 @@ function stripChrome(body) {
         .replace(/^<!-- This is an auto-generated comment: summarize by coderabbit.ai -->\s*/, "")
         .replace(/^<!-- review_stack_entry_start -->[\s\S]*?<!-- review_stack_entry_end -->\s*/, "");
 }
+/** The "Review info" block that follows a progress notice: it opens with this summary line. */
+const REVIEW_INFO_START = /\n<details>\n<summary><strong>(?:<picture>(?:<source [^>\n]*>)*<img [^>\n]*><\/picture> )?Review info<\/strong><\/summary>\n/;
+/**
+ * Lines the "Review info" block may hold: layout tags, picture-icon summaries, `- **Key**: value`
+ * settings with CodeRabbit's known keys, file bullets, and the commit-range sentence. Any other line keeps the comment visible.
+ */
+const REVIEW_INFO_LINE = /^(?:|<\/?details>|<\/?dl>|<\/?dd>|<br>|<summary><strong>(?:<picture>(?:<source [^>]*>)*<img [^>]*><\/picture> )?(?:Review info|Run configuration|Commits|Files selected for processing: \d+)<\/strong><\/summary>|- \*\*(?:Source mode|Repository|Branch|File|Commit|Layers|Review profile|Plan|Run ID)\*\*: [^<>\n]*|\* `[^`\n]+`|Reviewing files that changed from the base of the PR and between [a-f0-9]+ and [a-f0-9]+\.)$/;
+/** Removes a trailing "Review info" block made only of known metadata lines. */
+function stripReviewInfo(quoted) {
+    const start = quoted.search(REVIEW_INFO_START);
+    if (start < 0)
+        return quoted;
+    const info = quoted.slice(start).split("\n");
+    return info.every((line) => REVIEW_INFO_LINE.test(line)) ? quoted.slice(0, start) : quoted;
+}
 function isQuotedNotice(quoted) {
     const onlyQuotedLines = quoted.split("\n").every((line) => !line.trim() || line.startsWith(">"));
     if (!onlyQuotedLines)
@@ -51,7 +66,8 @@ const rule = (item) => {
     if (!isBotItem(item, ["coderabbitai"], ["pr-comment"]))
         return null;
     const body = stripChrome(item.body);
-    const quoted = body.match(NOTICE_ENVELOPE)?.[2]?.trim();
+    const envelope = body.match(NOTICE_ENVELOPE)?.[2];
+    const quoted = envelope === undefined ? undefined : stripReviewInfo(envelope).trim();
     const isStatus = COMMAND_REPLY.test(body) || STATUS_COMMENTS.some((notice) => notice.test(body));
     if (!(quoted && isQuotedNotice(quoted)) && !isStatus)
         return null;

package/bin/classify/standard/codex-notices.mjs

@@ -5,8 +5,10 @@ const QUOTA_NOTICES = [
     /^Codex usage limits have been reached for code reviews\. Please check with the admins of this repo to increase the limits by adding credits\.\nRepo admins can enable using credits for code reviews in their \[settings\]\(https:\/\/chatgpt\.com\/[^\s)]*\)\.$/,
     /^Codex usage limits have been reached\. Please try again later\.$/,
 ];
-const ABOUT_BLOCK = /\n\n<details> <summary>ℹ️ About Codex (?:in GitHub|security reviews in GitHub)<\/summary>[\s\S]*?<\/details>$/;
+const ABOUT_BLOCK = /\n\n<details> <summary>ℹ️ About Codex (?:in GitHub|security reviews in GitHub)<\/summary>[\s\S]*?<\/details>(\n\n<\/details>)?$/;
 const ACTIVITY_SUMMARY = /^<!-- codex-pull-request-review-summary -->\n(?:<!-- codex-[a-z0-9-]+:[^\n]* -->\n)*\n?## Codex Review Summary\n\nThis comment shows the latest Codex review activity on this pull request\.\n\n\| Review \| Status \| Commit \| Review trigger \|\n\| --- \| --- \| --- \| --- \|\n(?:\|[^\n]+\|\n?)+$/;
+/** The same table collapsed under `<details>`, with the overall status in the summary line. */
+const COLLAPSED_ACTIVITY_SUMMARY = /^<!-- codex-pull-request-review-summary -->\n(?:<!-- codex-[a-z0-9-]+:[^\n]* -->\n)*\n?<details>\n<summary><strong>Codex Review Summary<\/strong>(?:: [^<\n]+)?<\/summary>\n\nThis comment shows the latest Codex review activity on this pull request\.\n\n\| Review \| Status \| Commit \| Review trigger \|\n\| --- \| --- \| --- \| --- \|\n(?:\|[^\n]+\|\n?)+\n*<\/details>$/;
 /**
  * Codex's rotating clean-review sign-offs, as observed. Prose is matched only from this list so a
  * short piece of advice in that position stays visible; a new sign-off is shown until added here.
@@ -47,10 +49,10 @@ const rule = (item) => {
     // Strip only leading codex-* metadata markers and the trailing About block; extra findings stay
     // visible. The activity table's own marker has no colon, so it is kept for ACTIVITY_SUMMARY.
     const content = body
-        .replace(ABOUT_BLOCK, "")
+        .replace(ABOUT_BLOCK, (_about, close) => close ?? "")
         .trim()
         .replace(/^(?:<!-- codex-[a-z0-9-]+:[^\n]* -->\s*)+/, "");
-    if (ACTIVITY_SUMMARY.test(content)) {
+    if (ACTIVITY_SUMMARY.test(content) || COLLAPSED_ACTIVITY_SUMMARY.test(content)) {
         return { autoResolve: true, suppress: true, reason: "Codex review-activity table" };
     }
     if (CLEAN_REVIEW.test(content) || CLEAN_SECURITY.test(content)) {

package/bin/cli/iterate-instructions.mjs

@@ -71,7 +71,9 @@ export function buildSimpleIterateInstructions(result) {
         case "escalate": {
             const pending = result.escalate.pendingReviewCommands;
             if (!pending)
-                return ["Stop — human direction is required before automated polling can resume."];
+                return [
+                    "Stop — human direction is required before automated polling can resume. Report the evidence above and the decision the human must make; do not attempt a fix, rerun, requeue, branch update, or merge for this PR.",
+                ];
             return [
                 "Stop polling. Ask the user whether to run the pending review commands shown above.",
                 "If yes, set any `$DISMISS_MESSAGE` to a one-sentence disposition, run every pending command from the pushed PR head, then rerun Shepherd with the same options.",

package/bin/cli/iterate-lean.mjs

@@ -115,7 +115,7 @@ export function projectIterateLean(result, opts) {
                 ...base,
                 // Zero counts are omitted, matching the text `**deferred (in merge queue)**` rollup.
                 ...(result.deferredWork && {
-                    deferredWork: Object.fromEntries(Object.entries(result.deferredWork).filter(([, n]) => n > 0)),
+                    deferredWork: nonZeroCounts(result.deferredWork),
                 }),
                 log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
@@ -182,6 +182,9 @@ export function projectIterateLean(result, opts) {
                         resolveOnlyCommand: result.triage.resolveOnlyCommand,
                     }),
                     ...(result.triage.reviewItems && { reviewItems: result.triage.reviewItems }),
+                    ...(result.triage.deferredWork && {
+                        deferredWork: nonZeroCounts(result.triage.deferredWork),
+                    }),
                     ...(result.triage.instructions.length > 0 && {
                         instructions: result.triage.instructions,
                     }),
@@ -247,3 +250,7 @@ function cappedList(key, items) {
     return { [key]: shown, ...(hidden > 0 && { [`${key}More`]: hidden }) };
 }
 export { projectIterateVerbose } from "./iterate-verbose.mjs";
+/** Zero deferred-work counts are omitted, matching the text `**deferred (in merge queue)**` rollup. */
+function nonZeroCounts(counts) {
+    return Object.fromEntries(Object.entries(counts).filter((entry) => entry[1] > 0));
+}

package/bin/cli/triage-formatter.mjs

@@ -9,6 +9,7 @@ import { renderRelatedJobLines } from "./related-jobs-format.mjs";
 import { isFailingAgentCheck } from "../checks/conclusions.mjs";
 import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 import { partitionFixThreads } from "../commands/iterate/fix-instruction-threads.mjs";
+import { formatDeferredWorkLine } from "./iterate-merge-formatter.mjs";
 export function formatTriageResult(header, result, opts = {}) {
     const verbose = opts.verbose ?? false;
     const topCap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
@@ -17,6 +18,8 @@ export function formatTriageResult(header, result, opts = {}) {
         const { shown, total } = result.triage.reviewItems;
         sections.push(`**showing** ${shown} of ${total} review items`);
     }
+    if (result.triage.deferredWork)
+        sections.push(formatDeferredWorkLine(result.triage.deferredWork));
     if (result.mergedBasePullRequests?.length) {
         sections.push("## Merged PRs matching the current base");
         sections.push(result.mergedBasePullRequests
@@ -80,11 +83,12 @@ export function formatTriageResult(header, result, opts = {}) {
                     ? ` [conclusion: ${ch.conclusion}]`
                     : "";
             const attemptTag = ch.runAttempt !== undefined ? ` [attempt: ${ch.runAttempt}]` : "";
+            const blockerTag = ch.releasedBlocker ? ` [blocker released: ${ch.releasedBlocker}]` : "";
             const scopeTag = ch.scope
                 ? ` [scope: ${ch.scope}${ch.commitOid ? `, commit: ${ch.commitOid}` : ""}]`
                 : "";
             const lines = [
-                `- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${attemptTag}${scopeTag}`,
+                `- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${attemptTag}${blockerTag}${scopeTag}`,
             ];
             if (ch.conclusion !== "CANCELLED") {
                 if (ch.failedStep)

package/bin/commands/check-annotations.d.mts

@@ -14,14 +14,20 @@ export declare function hasCheckDrivenActionableWork(checks: {
     passing: ClassifiedCheck[];
     skipped: ClassifiedCheck[];
     filtered: ClassifiedCheck[];
-    ignored?: TriagedCheck[];
 }, mergeStatusValue: string): boolean;
+/**
+ * A merge-queue entry whose branch conflicts with its base. Its triage offers dequeue-and-resolve
+ * or wait; review work waits until the PR leaves the queue on either path. Shared by `check.mts`
+ * (seen markers stay unwritten) and `iterate` (review items and fix attempts stay out of the
+ * tick), so a caller who waits never has review items consumed or counted toward
+ * `triage-thrash`.
+ */
+export declare function isQueuedConflict(inQueue: boolean | undefined, mergeStatus: string): boolean;
 export declare function attachAndMergeCheckAnnotations(buckets: {
     passing: ClassifiedCheck[];
     failing: TriagedCheck[];
     skipped: ClassifiedCheck[];
     filtered: ClassifiedCheck[];
-    ignored: ClassifiedCheck[];
 }, seenMap: Map<string, {
     seenAt: number;
 }>, prNumber: number, cacheOpts?: AnnotationCacheOptions): Promise<{
@@ -29,6 +35,5 @@ export declare function attachAndMergeCheckAnnotations(buckets: {
     failing: TriagedCheck[];
     skipped: ClassifiedCheck[];
     filtered: ClassifiedCheck[];
-    ignored: ClassifiedCheck[];
 }>;
 export declare function annotationMarkerBody(a: CheckAnnotation): string;

package/bin/commands/check-annotations.mjs

@@ -12,7 +12,6 @@ export function checksWithActionableAnnotations(report) {
         ...report.checks.passing,
         ...report.checks.skipped,
         ...report.checks.filtered,
-        ...(report.checks.ignored ?? []),
     ].filter(hasActionableAnnotation);
 }
 /**
@@ -25,22 +24,25 @@ export function checksWithActionableAnnotations(report) {
  */
 export function hasCheckDrivenActionableWork(checks, mergeStatusValue) {
     return (checks.failing.length > 0 ||
-        [
-            ...checks.failing,
-            ...checks.passing,
-            ...checks.skipped,
-            ...checks.filtered,
-            ...(checks.ignored ?? []),
-        ].some(hasActionableAnnotation) ||
+        [...checks.failing, ...checks.passing, ...checks.skipped, ...checks.filtered].some(hasActionableAnnotation) ||
         mergeStatusValue === "CONFLICTS");
 }
+/**
+ * A merge-queue entry whose branch conflicts with its base. Its triage offers dequeue-and-resolve
+ * or wait; review work waits until the PR leaves the queue on either path. Shared by `check.mts`
+ * (seen markers stay unwritten) and `iterate` (review items and fix attempts stay out of the
+ * tick), so a caller who waits never has review items consumed or counted toward
+ * `triage-thrash`.
+ */
+export function isQueuedConflict(inQueue, mergeStatus) {
+    return inQueue === true && mergeStatus === "CONFLICTS";
+}
 export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber, cacheOpts) {
     const candidates = [
         ...buckets.failing,
         ...buckets.passing,
         ...buckets.skipped,
         ...buckets.filtered,
-        ...buckets.ignored,
     ].filter(shouldFetchCheckAnnotations);
     const expectedCounts = new Map(candidates.flatMap((c) => c.id != null && c.annotationCount ? [[c.id, c.annotationCount]] : []));
     const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber, cacheOpts && { ...cacheOpts, expectedCounts });
@@ -57,7 +59,6 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber,
         failing: apply(buckets.failing),
         skipped: apply(buckets.skipped),
         filtered: apply(buckets.filtered),
-        ignored: apply(buckets.ignored),
     };
 }
 async function attachUnseenCheckAnnotations(checks, seenMap, prNumber, cacheOpts) {

package/bin/commands/check-unreported.mjs

@@ -110,7 +110,7 @@ function reportChecks(report) {
         ...report.checks.inProgress,
         ...report.checks.skipped,
         ...report.checks.filtered,
-        ...(report.checks.ignored ?? []),
+        ...(report.checks.ignoredNames ?? []).map((name) => ({ name })),
         ...(report.checks.supersededNames ?? []).map((name) => ({ name })),
     ];
 }

package/bin/commands/check.mjs

@@ -17,7 +17,7 @@ import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
 import { computeStatus } from "./check-status.mjs";
-import { annotationMarkerBody, attachAndMergeCheckAnnotations, hasCheckDrivenActionableWork, } from "./check-annotations.mjs";
+import { annotationMarkerBody, attachAndMergeCheckAnnotations, hasCheckDrivenActionableWork, isQueuedConflict, } from "./check-annotations.mjs";
 import { buildTerminalReport } from "./check-terminal-report.mjs";
 import { isBlockedByFilteredCheck, refreshReadyMergeability, refreshUnknownMergeability, } from "./ready-mergeability.mjs";
 import { loadSeenMap, markSeen, classifyItem, mutationWasDenied } from "../state/seen-comments.mjs";
@@ -186,7 +186,6 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     const inProgress = classifiedChecks.filter((c) => c.category === "in_progress");
     const skipped = classifiedChecks.filter((c) => c.category === "skipped");
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
-    const ignored = classifiedChecks.filter((c) => c.category === "ignored");
     const triagedBase = failing.length > 0 && !opts.skipTriage
         ? await triageFailingChecks(failing, repo, stateKey, triageBudget, classifiedChecks.filter((c) => c.category !== "failing"))
         : failing;
@@ -199,8 +198,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     const ruleSet = await loadClassifyRules(getEffectiveCwd(), config.standardRules);
     const classifyIndex = buildClassifyIndex(ruleSet, batchData);
     const partition = partitionBatch(classifyIndex, batchData);
-    const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered, ignored }, seenMap, prNumber, { stateKey, headSha: batchData.headRefOid });
-    const ignoredAnnotated = merged.ignored.filter((c) => (c.annotations?.length ?? 0) > 0);
+    const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered }, seenMap, prNumber, { stateKey, headSha: batchData.headRefOid });
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized && !partition.suppressedCommentIds.has(c.id));
     const deniedRuleAutoResolveCommentIds = new Set(partition.ruleAutoResolveCommentIds.filter((id) => !canGenerateItemMutation(id, batchData.comments.find((comment) => comment.id === id)?.body ?? "", batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize, "minimize")));
     const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate["minimize-comments"], botUsernames, new Set(batchData.comments
@@ -293,16 +291,18 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     // that also has check-driven work (failing checks, actionable annotations, conflicts) is
     // NOT deferred — index.mts still renders these items via triage — so this must stay false
     // in that case too, or their seen markers would be suppressed while actually being shown.
-    const deferWhileQueued = opts.merge === true &&
-        batchData.isInMergeQueue === true &&
-        config.actions["work-while-queued"] !== true &&
-        !hasCheckDrivenActionableWork({
-            failing: merged.failing,
-            passing: merged.passing,
-            skipped: merged.skipped,
-            filtered: merged.filtered,
-            ignored: merged.ignored,
-        }, mergeStatus.status);
+    // A queued conflict also holds review work back (iterate strips it from that triage tick).
+    const queuedConflict = isQueuedConflict(batchData.isInMergeQueue, mergeStatus.status);
+    const deferWhileQueued = queuedConflict ||
+        (opts.merge === true &&
+            batchData.isInMergeQueue === true &&
+            config.actions["work-while-queued"] !== true &&
+            !hasCheckDrivenActionableWork({
+                failing: merged.failing,
+                passing: merged.passing,
+                skipped: merged.skipped,
+                filtered: merged.filtered,
+            }, mergeStatus.status));
     // A deferred tick shows no review items, so it is never capped; its seen markers stay unwritten.
     const { buckets: budgeted, rollup: reviewItems, heldThreadReviewIds, } = applyReviewOutputBudget({
         changesRequested: changesRequestedReviewVisibility,
@@ -314,12 +314,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         editedComments,
     }, deferWhileQueued ? 0 : (opts.reviewOutputMaxChars ?? 0));
     if (opts.persistSeen !== false) {
-        const successfulAnnotations = [
-            ...merged.passing,
-            ...merged.skipped,
-            ...merged.filtered,
-            ...merged.ignored,
-        ]
+        const successfulAnnotations = [...merged.passing, ...merged.skipped, ...merged.filtered]
             .filter((check) => check.conclusion === "SUCCESS")
             .flatMap((check) => check.annotations ?? []);
         const deferredMarkSeen = deferWhileQueued
@@ -333,7 +328,8 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
                 ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
             ];
         await Promise.allSettled([
-            ...successfulAnnotations.map((a) => markSeen(stateKey, a.id, annotationMarkerBody(a))),
+            // A queued conflict defers annotation fixes too (path (a)), so they stay unseen.
+            ...(queuedConflict ? [] : successfulAnnotations).map((a) => markSeen(stateKey, a.id, annotationMarkerBody(a))),
             ...deferredMarkSeen,
             ...batchData.comments
                 .filter((c) => partition.suppressedCommentIds.has(c.id) && !deniedRuleAutoResolveCommentIds.has(c.id))
@@ -410,7 +406,6 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
             inProgress: inProgress,
             skipped: merged.skipped,
             filtered: merged.filtered,
-            ...(ignoredAnnotated.length > 0 && { ignored: ignoredAnnotated }),
             filteredNames: verdict.filteredNames,
             blockedByFilteredCheck,
             ...(verdict.ignoredNames.length > 0 && {

package/bin/commands/iterate/check-blocker-gate.d.mts

@@ -2,6 +2,8 @@ import type { IterateResult } from "../../types.mts";
 export interface CheckBlockerGate {
     deferredNames: ReadonlySet<string>;
     releasedNames: ReadonlySet<string>;
+    /** Released check name → `owner/name#number` of the blocker that merged or closed. */
+    releasedBlockers: ReadonlyMap<string, string>;
     /** `owner/name#number` for blockers that are still open. */
     openBlockers: readonly string[];
 }

package/bin/commands/iterate/check-blocker-gate.mjs

@@ -40,6 +40,7 @@ export async function resolveCheckBlockerGate(key, failing, mergeStatus) {
     }
     const deferredNames = new Set();
     const releasedNames = new Set();
+    const releasedBlockers = new Map();
     const openBlockers = [];
     const seen = new Set();
     for (const record of matched) {
@@ -60,12 +61,13 @@ export async function resolveCheckBlockerGate(key, failing, mergeStatus) {
             }
             else {
                 releasedNames.add(record.checkName);
+                releasedBlockers.set(record.checkName, formatCheckBlockerRef(record.blocker));
             }
         }
     }
     if (deferredNames.size === 0 && releasedNames.size === 0)
         return null;
-    return { deferredNames, releasedNames, openBlockers };
+    return { deferredNames, releasedNames, releasedBlockers, openBlockers };
 }
 /** Append the open blocker to a WAIT log. Other actions are unchanged. */
 export function annotateBlockedWait(result, gate) {

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

@@ -1,5 +1,11 @@
 import type { AgentCheck, ResolveCommand, Review } from "../../types.mts";
-/** The `[TRIAGE]` recurrence step, whether plain or rewritten by the quota warning. */
+export declare const TRIAGE_CONTINUATION = "Rerun Shepherd now.";
+/** The final rerun step when a queued conflict offers both paths. */
+export declare const QUEUED_CONFLICT_CONTINUATION = "If you chose (a), rerun Shepherd now. If you chose (b), rerun Shepherd after the polling interval.";
+/**
+ * The `[TRIAGE]` recurrence step, whether plain, the queued-conflict variant, or rewritten by
+ * the quota warning. The quota cadence supersedes both queued-conflict paths.
+ */
 export declare function isTriageContinuation(step: string): boolean;
 /** Build the stale-CR step for `## Changes-requested reviews`. Empty when no human CR is stale. */
 export declare function buildCrStaleClause(reviews: Review[]): string;

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

@@ -1,9 +1,16 @@
 import { playbookPointer } from "../playbook-pointer.mjs";
 // The `[TRIAGE]` heading and the skill already say the action is non-terminal.
-const TRIAGE_CONTINUATION = "Rerun Shepherd now.";
-/** The `[TRIAGE]` recurrence step, whether plain or rewritten by the quota warning. */
+export const TRIAGE_CONTINUATION = "Rerun Shepherd now.";
+/** The final rerun step when a queued conflict offers both paths. */
+export const QUEUED_CONFLICT_CONTINUATION = "If you chose (a), rerun Shepherd now. If you chose (b), rerun Shepherd after the polling interval.";
+/**
+ * The `[TRIAGE]` recurrence step, whether plain, the queued-conflict variant, or rewritten by
+ * the quota warning. The quota cadence supersedes both queued-conflict paths.
+ */
 export function isTriageContinuation(step) {
-    return step === TRIAGE_CONTINUATION || /\[TRIAGE\].*non-terminal/i.test(step);
+    return (step.startsWith(TRIAGE_CONTINUATION.slice(0, -1)) ||
+        step === QUEUED_CONFLICT_CONTINUATION ||
+        /\[TRIAGE\].*non-terminal/i.test(step));
 }
 /** Build the stale-CR step for `## Changes-requested reviews`. Empty when no human CR is stale. */
 export function buildCrStaleClause(reviews) {

package/bin/commands/iterate/conflicting-head-ci.d.mts

@@ -12,7 +12,7 @@ export declare function countReportedChecks(checks: {
     inProgress: readonly unknown[];
     skipped: readonly unknown[];
     filtered: readonly unknown[];
-    ignored?: readonly unknown[];
+    ignoredNames?: readonly unknown[];
 }): number;
 /** Place the missing-CI note with the conflict step, ahead of later repair lines. */
 export declare function insertConflictingHeadCiNote(instructions: string[], note: string | undefined): void;

package/bin/commands/iterate/conflicting-head-ci.mjs

@@ -18,7 +18,7 @@ export function countReportedChecks(checks) {
         checks.inProgress.length +
         checks.skipped.length +
         checks.filtered.length +
-        (checks.ignored?.length ?? 0));
+        (checks.ignoredNames?.length ?? 0));
 }
 /** Place the missing-CI note with the conflict step, ahead of later repair lines. */
 export function insertConflictingHeadCiNote(instructions, note) {

package/bin/commands/iterate/index.mjs

@@ -9,9 +9,10 @@ import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleTriage } from "./triage.mjs";
+import { deferQueuedConflictReviewWork } from "./queued-conflict-deferral.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
-import { hasCheckDrivenActionableWork } from "../check-annotations.mjs";
+import { hasCheckDrivenActionableWork, isQueuedConflict } from "../check-annotations.mjs";
 import { buildReadyMergeOutcome, handleActiveMergeState } from "./merge-state.mjs";
 import { buildIterateBase } from "./base.mjs";
 import { markReadyIfAuthorized } from "./mark-ready.mjs";
@@ -182,9 +183,20 @@ async function runIterateCore(opts, tick) {
         report.mergeQueue?.inQueue === true &&
         config.actions["work-while-queued"] !== true;
     if (hasActionableWork && !(deferWhileQueued && !checkDrivenActionableWork)) {
+        const reviewWork = {
+            report: reportForWork,
+            reviewSummaryIds,
+            firstLookSummaries,
+            editedSummaries,
+            surfacedApprovals,
+            ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
+        };
+        // A queued conflict holds review work until the PR leaves the queue (see check.mts).
         return handleTriage({
+            ...(isQueuedConflict(report.mergeQueue?.inQueue, report.mergeStatus.status)
+                ? deferQueuedConflictReviewWork(reviewWork, config.iterate["minimize-approvals"])
+                : reviewWork),
             base,
-            report: reportForWork,
             opts: { ...opts, prNumber },
             headSha,
             stallKey,
@@ -192,16 +204,12 @@ async function runIterateCore(opts, tick) {
             stallTimeoutSeconds,
             repoOwner,
             repoName,
-            reviewSummaryIds,
-            firstLookSummaries,
-            editedSummaries,
-            surfacedApprovals,
             botUsernames,
             releasedCheckNames: blockerGate?.releasedNames,
+            releasedCheckBlockers: blockerGate?.releasedBlockers,
             ...((unreportedRepair.length > 0 || staleAncestry !== null) && {
                 repairInstructions: [...unreportedRepair, ...(staleAncestry?.instructions ?? [])],
             }),
-            ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
     if (unreportedRepair.length > 0 && staleAncestry) {
@@ -221,6 +229,7 @@ async function runIterateCore(opts, tick) {
             surfacedApprovals,
             botUsernames,
             releasedCheckNames: blockerGate?.releasedNames,
+            releasedCheckBlockers: blockerGate?.releasedBlockers,
             repairInstructions: [...unreportedRepair, ...staleAncestry.instructions],
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
@@ -259,6 +268,7 @@ async function runIterateCore(opts, tick) {
             surfacedApprovals,
             botUsernames,
             releasedCheckNames: blockerGate?.releasedNames,
+            releasedCheckBlockers: blockerGate?.releasedBlockers,
             repairInstructions: [...unreportedRepair, ...staleAncestry.instructions],
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });

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

@@ -1,6 +1,8 @@
 import { type MergeMethod } from "../../config/merge-method.mts";
 import type { MergeCommandPlan } from "../../types.mts";
 import type { RestMergeStackGuard } from "../../github/rest-merge.mts";
+/** gh CLI cannot remove a queue entry, so dequeueing goes through the GraphQL mutation. */
+export declare function buildDequeueCommand(nodeId: string): string[];
 export interface MergePlanInput {
     transport?: "rest";
     pr: number;

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

@@ -5,6 +5,11 @@ import { formatPrUrl } from "../../pr-reference.mjs";
 import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { getGithubTransport } from "../../github/transport.mjs";
 const ENQUEUE_MUTATION = "mutation EnqueuePullRequest($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: { pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid }) { mergeQueueEntry { id } } }";
+const DEQUEUE_MUTATION = "mutation DequeuePullRequest($id: ID!) { dequeuePullRequest(input: { id: $id }) { mergeQueueEntry { id } } }";
+/** gh CLI cannot remove a queue entry, so dequeueing goes through the GraphQL mutation. */
+export function buildDequeueCommand(nodeId) {
+    return ["gh", "api", "graphql", "-f", `query=${DEQUEUE_MUTATION}`, "-f", `id=${nodeId}`];
+}
 export function buildMergeCommandPlan(input) {
     if (input.transport === "rest" || getGithubTransport() === "rest") {
         const configured = configuredMergeMethod(loadConfig().merge);

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

@@ -1,10 +1,19 @@
-import type { IterateResult, IterateResultBase, Review, ShepherdReport } from "../../types.mts";
+import type { IterateDeferredWork, IterateResult, IterateResultBase, Review, ShepherdReport } from "../../types.mts";
 type StallKey = {
     owner: string;
     repo: string;
     pr: number;
 };
 export declare function buildReadyMergeOutcome(enabled: boolean | undefined, readyElapsed: boolean, base: IterateResultBase, report: ShepherdReport): IterateResult | null;
+/** Raw counts of non-CI actionable work held back for one queued-PR wait tick. Omitted (all zero) when empty. */
+export declare function buildDeferredWork(input: {
+    report: ShepherdReport;
+    reviewSummaryIds: string[];
+    firstLookSummaries: Review[];
+    editedSummaries: Review[];
+    surfacedApprovals: Review[];
+    minimizeApprovals: boolean;
+}): IterateDeferredWork | undefined;
 export declare function handleActiveMergeState(input: {
     enabled: boolean | undefined;
     active: boolean;

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

@@ -62,7 +62,7 @@ export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
     return { ...base, action: "merge", merge: plan };
 }
 /** Raw counts of non-CI actionable work held back for one queued-PR wait tick. Omitted (all zero) when empty. */
-function buildDeferredWork(input) {
+export function buildDeferredWork(input) {
     const { report, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, minimizeApprovals, } = input;
     // These buckets are not disjoint (e.g. an unresolved outdated thread is both
     // `resolutionOnly` and `firstLook`; an eligible-to-minimize comment/summary is both