pr-shepherd 1.1.2 → 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.2",
+  "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

@@ -15,6 +15,14 @@ export declare function hasCheckDrivenActionableWork(checks: {
     skipped: ClassifiedCheck[];
     filtered: ClassifiedCheck[];
 }, 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[];

package/bin/commands/check-annotations.mjs

@@ -27,6 +27,16 @@ export function hasCheckDrivenActionableWork(checks, mergeStatusValue) {
         [...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,

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";
@@ -291,15 +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,
-        }, 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,
@@ -325,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))

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/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

package/bin/commands/iterate/native-stack-rebase.d.mts

@@ -35,8 +35,19 @@ export declare function buildNativeStackLayerRebase(repo: string, pr: {
     trunk: string;
     bottomPr?: number;
 }, stackBottomPr?: number): string | undefined;
-/** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
-export declare function buildConflictInstruction(stackRebase: string | undefined): string;
+/**
+ * Point at the conflicts, and at the stack rebase when the PR is a native stack layer. A queued
+ * conflicting entry cannot form a merge group, so GitHub removes it once the queue reaches it.
+ * Pulling it out early (dequeue, then resolve) or waiting for that removal is the caller's
+ * call, so a queued PR gets both paths without a recommendation. `dequeueCommand` is the
+ * rendered dequeue mutation; it is present only while the PR is a queue entry.
+ */
+export declare function buildConflictInstruction(stackRebase: string | undefined, dequeueCommand?: string): string;
+/**
+ * The two paths for a conflicting PR that is still a queue entry. `resolve` is the branch
+ * update route; on a native stack, dequeueing a layer can also take queued layers above it out.
+ */
+export declare function buildQueuedConflictChoice(dequeueCommand: string, resolve: string, stack: boolean): string;
 /**
  * Push a conflict resolution or branch refresh: one branch, or the whole rewritten native stack.
  * After a merge-queue ejection update, push only when the update or a fix changed the head.

package/bin/commands/iterate/native-stack-rebase.mjs

@@ -54,10 +54,30 @@ export function buildNativeStackLayerRebase(repo, pr, stack, trunkConflict, stac
             : { parentBranch: pr.baseBranch };
     return buildNativeStackRebaseInstruction(repo, stack.number, start);
 }
-/** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
-export function buildConflictInstruction(stackRebase) {
+/**
+ * Point at the conflicts, and at the stack rebase when the PR is a native stack layer. A queued
+ * conflicting entry cannot form a merge group, so GitHub removes it once the queue reaches it.
+ * Pulling it out early (dequeue, then resolve) or waiting for that removal is the caller's
+ * call, so a queued PR gets both paths without a recommendation. `dequeueCommand` is the
+ * rendered dequeue mutation; it is present only while the PR is a queue entry.
+ */
+export function buildConflictInstruction(stackRebase, dequeueCommand) {
     const pointer = "The branch has merge conflicts (see `**branch**` above).";
-    return stackRebase ? `${pointer} ${stackRebase}` : `${pointer} Resolve them before committing.`;
+    const resolve = stackRebase ?? "Resolve them before committing.";
+    if (!dequeueCommand)
+        return `${pointer} ${resolve}`;
+    return `${pointer} ${buildQueuedConflictChoice(dequeueCommand, resolve, stackRebase !== undefined)}`;
+}
+/**
+ * The two paths for a conflicting PR that is still a queue entry. `resolve` is the branch
+ * update route; on a native stack, dequeueing a layer can also take queued layers above it out.
+ */
+export function buildQueuedConflictChoice(dequeueCommand, resolve, stack) {
+    const leaves = stack
+        ? "this PR leaves the queue, and so may any queued layers above it in this stack; other entries stay queued"
+        : "only this PR leaves the queue and the other entries stay queued";
+    const requeue = stack ? "enqueue it and any removed layers again" : "enqueue it again";
+    return `The PR is still in the merge queue, but GitHub cannot merge it until the conflicts are resolved. Choose one path: (a) pull it from the queue and resolve now — first run \`${dequeueCommand}\` (\`gh pr\` cannot remove a queue entry); ${leaves}; then: ${resolve} Once the PR is ready again, ${requeue} (with \`--merge\`, Shepherd prints the enqueue command). Or (b) wait — skip the dequeue and every step marked \`If you chose (a):\`, and rerun Shepherd after the polling interval instead of immediately, until GitHub removes the entry itself; this step repeats until then, and an unchanged conflict escalates through \`stall-timeout\`. On either path, review items stay deferred until the PR leaves the queue.`;
 }
 /**
  * Push a conflict resolution or branch refresh: one branch, or the whole rewritten native stack.

package/bin/commands/iterate/queued-conflict-deferral.d.mts

@@ -0,0 +1,15 @@
+import type { IterateDeferredWork, Review, ShepherdReport } from "../../types.mts";
+/** Review work for one triage tick; see `isQueuedConflict` in check-annotations.mts. */
+interface ReviewWork {
+    report: ShepherdReport;
+    reviewSummaryIds: string[];
+    firstLookSummaries: Review[];
+    editedSummaries: Review[];
+    surfacedApprovals: Review[];
+    ruleAutoResolveThreadIds?: string[];
+}
+/** Strip review work from a queued-conflict tick and count what was held back. */
+export declare function deferQueuedConflictReviewWork(work: ReviewWork, minimizeApprovals: boolean): Omit<ReviewWork, "ruleAutoResolveThreadIds"> & {
+    deferredWork?: IterateDeferredWork;
+};
+export {};

package/bin/commands/iterate/queued-conflict-deferral.mjs

@@ -0,0 +1,20 @@
+import { buildDeferredWork } from "./merge-state.mjs";
+/** Strip review work from a queued-conflict tick and count what was held back. */
+export function deferQueuedConflictReviewWork(work, minimizeApprovals) {
+    const deferredWork = buildDeferredWork({ ...work, minimizeApprovals });
+    const { reviewItems: _held, ...report } = work.report;
+    const { ruleAutoResolveIds: _rule, ...threads } = report.threads;
+    return {
+        report: {
+            ...report,
+            threads: { ...threads, actionable: [], resolutionOnly: [], firstLook: [] },
+            comments: { ...report.comments, actionable: [], minimizeIds: [], firstLook: [] },
+            changesRequestedReviews: [],
+        },
+        reviewSummaryIds: [],
+        firstLookSummaries: [],
+        editedSummaries: [],
+        surfacedApprovals: [],
+        ...(deferredWork && { deferredWork }),
+    };
+}

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

@@ -10,4 +10,5 @@ export declare function renderResolveCommand(rc: ResolveCommand): string;
 export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behind-base-hint — see buildBehindBaseHintInstruction
 isBehind?: boolean, _viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection?: QueueEjectionRecovery, // current merge-queue removal with failing queue checks
-instructionStyle?: InstructionStyle): string[];
+instructionStyle?: InstructionStyle, // see iterate.instructions
+dequeueCommand?: string): string[];