pr-shepherd 1.1.1 → 1.2.0

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[];

package/bin/commands/iterate/render.mjs

@@ -1,9 +1,9 @@
 import { buildPrShepherdCommand, renderShellCommand } from "../../cli/runner.mjs";
-import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildRepeatedWorkflowBranchRecoveryInstructions, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
+import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildRepeatedWorkflowBranchRecoveryInstructions, buildResolveCommandInstruction, buildFixCompletionInstruction, QUEUED_CONFLICT_CONTINUATION, } from "./check-instructions.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 import { partitionFixThreads } from "./fix-instruction-threads.mjs";
-import { buildBranchPushInstruction, buildConflictInstruction } from "./native-stack-rebase.mjs";
+import { buildBranchPushInstruction, buildConflictInstruction, buildQueuedConflictChoice, } from "./native-stack-rebase.mjs";
 import { queueEjectionSteps } from "./queue-recovery-instructions.mjs";
 import { buildPushSteps } from "./triage-loop-instruction.mjs";
 /**
@@ -19,7 +19,8 @@ const REQUIRE_HEAD_SHA = "--require-sha HEAD";
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behind-base-hint — see buildBehindBaseHintInstruction
 isBehind = false, _viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection, // current merge-queue removal with failing queue checks
-instructionStyle = "inline") {
+instructionStyle = "inline", // see iterate.instructions
+dequeueCommand) {
     const instructions = [];
     const { locatedThreads, unlocatedThreads } = partitionFixThreads(threads, resolveCommand, resolveOnlyCommand);
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
@@ -32,18 +33,23 @@ instructionStyle = "inline") {
         changesRequestedReviews.length > 0 ||
         actionableComments.length > 0;
     // Start with interpretation. The agent decides what raw feedback warrants a code change.
+    // A queued conflict offers a wait path that publishes nothing, so fixes, branch updates,
+    // pushes, and review mutations (which must follow a push) become path (a).
+    const pathA = (step) => (dequeueCommand ? `If you chose (a): ${step}` : step);
     if (hasNonConflictHints)
-        instructions.push("Fix each warranted item.");
+        instructions.push(pathA("Fix each warranted item."));
     // A conflicting native stack layer follows the printed gh-stack route, so it omits the hint.
     const branchUpdateHint = buildBehindBaseHintInstruction(baseBranch, behindBaseHint, {
         isBehind,
         hasConflicts: hasConflicts && !stackRebase,
-    });
+    }).map(pathA);
     // The conflict hint belongs with the conflict step; otherwise it precedes the push step.
     const hintWithConflictStep = hasConflicts && !hasRepeatedWorkflowBranchRecovery;
     const branchRecovery = hasConflicts || hasRepeatedWorkflowBranchRecovery;
     if (hintWithConflictStep)
-        instructions.push(buildConflictInstruction(stackRebase), ...branchUpdateHint);
+        instructions.push(buildConflictInstruction(stackRebase, dequeueCommand), ...branchUpdateHint);
+    else if (dequeueCommand && hasRepeatedWorkflowBranchRecovery)
+        instructions.push(`The branch has merge conflicts (see \`**branch**\` above). ${buildQueuedConflictChoice(dequeueCommand, "Follow the steps marked `If you chose (a):` below.", stackRebase !== undefined)}`);
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0)
         instructions.push("Review every item under `## First-look items` before acting.");
@@ -56,12 +62,12 @@ instructionStyle = "inline") {
         instructions.push("Acknowledge each item under `## Unlocated review threads (logged once — no mutation)`. Shepherd cannot route a code fix or review mutation without a path and line; the unchanged item will be skipped on later ticks.");
     const hasSuggestions = locatedThreads.some((t) => t.suggestion);
     if (hasSuggestions)
-        instructions.push(buildCommitSuggestionInstruction(prReference, "## Review threads"));
+        instructions.push(pathA(buildCommitSuggestionInstruction(prReference, "## Review threads")));
     if (resolutionOnlyThreads.length > 0)
         instructions.push("Review the threads under `## Review threads to resolve` before running the generated mutations.");
-    instructions.push(...buildFailingCheckInstructions(failingChecks), ...repeatedWorkflowBranchRecoveryInstructions, ...queueEjectionSteps(queueEjection, stackRebase, branchRecovery));
+    instructions.push(...buildFailingCheckInstructions(failingChecks), ...repeatedWorkflowBranchRecoveryInstructions.map(pathA), ...queueEjectionSteps(queueEjection, stackRebase, branchRecovery));
     if (hasAnnotations)
-        instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.");
+        instructions.push(pathA("Inspect every referenced range under `## Check annotations` and apply any warranted change."));
     // The first step already covers applying changes-requested bodies; only stale CRs add a step.
     const staleClause = buildCrStaleClause(changesRequestedReviews);
     if (staleClause)
@@ -83,11 +89,11 @@ instructionStyle = "inline") {
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     const genericPush = !(branchRecovery || queueEjection) && hasNonConflictHints;
     if (branchRecovery || queueEjection) {
-        instructions.push(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix, !branchRecovery));
+        instructions.push(pathA(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix, !branchRecovery)));
     }
     instructions.push(...buildPushSteps(instructionStyle, genericPush));
     if (resolveOnlyCommand?.hasMutations)
-        instructions.push(`Run: \`${renderResolveCommand(resolveOnlyCommand)}\``);
-    instructions.push(...buildResolveCommandInstruction(resolveCommand, renderResolveCommand(resolveCommand)), buildFixCompletionInstruction());
+        instructions.push(pathA(`Run: \`${renderResolveCommand(resolveOnlyCommand)}\``));
+    instructions.push(...buildResolveCommandInstruction(resolveCommand, renderResolveCommand(resolveCommand)).map(pathA), dequeueCommand ? QUEUED_CONFLICT_CONTINUATION : buildFixCompletionInstruction());
     return instructions;
 }

package/bin/commands/iterate/rerun-command.d.mts

@@ -0,0 +1,7 @@
+import type { IterateResult } from "../../types.mts";
+/**
+ * When the caller passed a qualified PR, name it in the plain `[TRIAGE]` recurrence step, so the
+ * caller reruns the same target instead of shortening it to a bare number that resolves in the
+ * local checkout. A bare target already reruns correctly. The caller owns the mode and flags.
+ */
+export declare function withTriageRerunTarget(result: IterateResult, qualified: boolean): IterateResult;

package/bin/commands/iterate/rerun-command.mjs

@@ -0,0 +1,22 @@
+import { formatPrUrl } from "../../pr-reference.mjs";
+import { TRIAGE_CONTINUATION } from "./check-instructions.mjs";
+/**
+ * When the caller passed a qualified PR, name it in the plain `[TRIAGE]` recurrence step, so the
+ * caller reruns the same target instead of shortening it to a bare number that resolves in the
+ * local checkout. A bare target already reruns correctly. The caller owns the mode and flags.
+ */
+export function withTriageRerunTarget(result, qualified) {
+    if (!qualified || result.action !== "triage")
+        return result;
+    const instructions = result.triage.instructions;
+    if (instructions.at(-1) !== TRIAGE_CONTINUATION)
+        return result;
+    const target = formatPrUrl(result.repo, result.pr);
+    return {
+        ...result,
+        triage: {
+            ...result.triage,
+            instructions: [...instructions.slice(0, -1), `Rerun Shepherd now on \`${target}\`.`],
+        },
+    };
+}

package/bin/commands/iterate/run.mjs

@@ -1,8 +1,9 @@
 import { withApiTelemetryScope } from "../../github/api-telemetry.mjs";
 import { attachApiUsage } from "./api-usage.mjs";
+import { withTriageRerunTarget } from "./rerun-command.mjs";
 export function withIterateApiUsage(opts, runCore) {
     return withApiTelemetryScope(async () => {
         const result = await runCore();
-        return attachApiUsage(result, opts.deferQuotaWarning !== true, false, opts.quotaWarningMinimumPollIntervalMinutes);
+        return attachApiUsage(withTriageRerunTarget(result, opts.targetRepository !== undefined), opts.deferQuotaWarning !== true, false, opts.quotaWarningMinimumPollIntervalMinutes);
     });
 }

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

@@ -1,4 +1,4 @@
-import type { IterateCommandOptions, IterateResult, IterateResultBase, Review, ShepherdReport } from "../../types.mts";
+import type { IterateCommandOptions, IterateDeferredWork, IterateResult, IterateResultBase, Review, ShepherdReport } from "../../types.mts";
 import type { NormalizedBotUsernames } from "../../comments/authors.mts";
 interface HandleTriageContext {
     base: IterateResultBase;
@@ -21,9 +21,13 @@ interface HandleTriageContext {
     botUsernames: NormalizedBotUsernames;
     /** Failing checks whose external blocker has merged or closed. */
     releasedCheckNames?: ReadonlySet<string>;
+    /** Released check name → the blocker that merged or closed, shown on the check. */
+    releasedCheckBlockers?: ReadonlyMap<string, string>;
     ruleAutoResolveThreadIds?: string[];
     /** Verified stack-repair guidance, when ancestry is stale. */
     repairInstructions?: string[];
+    /** Review work a queued conflict holds back until the PR leaves the queue. */
+    deferredWork?: IterateDeferredWork;
 }
 export declare function handleTriage(ctx: HandleTriageContext): Promise<IterateResult>;
 export {};

package/bin/commands/iterate/triage.mjs

@@ -11,12 +11,14 @@ import { hasLogEvidence } from "./check-evidence.mjs";
 import { currentEjectionCommit, } from "./queue-recovery-instructions.mjs";
 import { buildReleasedBlockerInstruction, buildReviewSubsetInstruction, } from "./check-instructions.mjs";
 import { buildNativeStackLayerRebase } from "./native-stack-rebase.mjs";
+import { buildDequeueCommand } from "./merge-plan.mjs";
+import { renderShellCommand } from "../../cli/runner.mjs";
 import { lookupUpperLayerTrunkConflict } from "./stack-trunk-conflict.mjs";
 import { lookupMergedBasePullRequests } from "./merged-base-pull-requests.mjs";
 import { conflictingHeadCiNote, countReportedChecks, insertConflictingHeadCiNote, } from "./conflicting-head-ci.mjs";
 import { conflictingHeadFirstSeenUnix } from "../../state/conflicting-head-seen.mjs";
 import { applyStallGuard } from "./stall.mjs";
-import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
+import { annotationMarkerBody, checksWithActionableAnnotations, isQueuedConflict, } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
 import { canRerunWorkflows } from "../../checks/conclusions.mjs";
@@ -86,7 +88,7 @@ export async function handleTriage(ctx) {
     return { ...result, escalate: { ...result.escalate, reviewItems } };
 }
 async function handleTriageTick(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, releasedCheckNames = EMPTY_RELEASED, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, releasedCheckNames = EMPTY_RELEASED, releasedCheckBlockers, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
     const failingChecks = report.checks.failing;
     const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
@@ -178,8 +180,10 @@ async function handleTriageTick(ctx) {
         : []));
     const initialAttemptRunIds = new Set(failingChecks.flatMap((c) => (c.runId !== null && c.runAttempt === 1 ? [c.runId] : [])));
     const failingAgentChecks = toAgentChecks(failingChecks).map((c) => {
-        if (releasedCheckNames.has(c.name))
-            return c;
+        if (releasedCheckNames.has(c.name)) {
+            const releasedBlocker = releasedCheckBlockers?.get(c.name);
+            return releasedBlocker ? { ...c, releasedBlocker } : c;
+        }
         return rerunAuthorized &&
             // Rerunning queue CI cannot restore a removed entry and overwrites its failure evidence.
             c.scope !== "merge_group" &&
@@ -201,6 +205,7 @@ async function handleTriageTick(ctx) {
     ];
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
+    const queuedConflict = isQueuedConflict(report.mergeQueue?.inQueue, report.mergeStatus.status);
     const isBehind = report.mergeStatus.status === "BEHIND";
     const { "behind-base-hint": behindBaseHint, instructions: configuredInstructions } = loadConfig().iterate;
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
@@ -340,14 +345,26 @@ async function handleTriageTick(ctx) {
     const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0) || queueEjection
         ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict, report.stackBottomPr)
         : undefined;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, canGenerateGithubMutation(report.viewerAuthorization?.viewerCanUpdate, "ready"), exhaustedAttempts.length > 0, stackRebase, queueEjection, opts.instructions ?? configuredInstructions);
+    const dequeueCommand = queuedConflict
+        ? renderShellCommand(buildDequeueCommand(report.nodeId))
+        : undefined;
+    const instructions = buildFixInstructions(threads, actionableComments, checks.filter((check) => !releasedCheckNames.has(check.name)), changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, canGenerateGithubMutation(report.viewerAuthorization?.viewerCanUpdate, "ready"), exhaustedAttempts.length > 0, stackRebase, queueEjection, opts.instructions ?? configuredInstructions, dequeueCommand);
     if (recovery && "unavailable" in recovery)
         instructions.unshift(recovery.unavailable);
     if (acknowledgmentRecovery && "unavailable" in acknowledgmentRecovery)
         instructions.unshift(acknowledgmentRecovery.unavailable);
+    // A queued conflict offers a wait path, so every later branch-mutating step is path (a), and
+    // leading repair steps follow the dequeue-or-wait choice instead of preceding it.
+    const pathA = (step) => (dequeueCommand ? `If you chose (a): ${step}` : step);
+    const prependBranchSteps = (steps) => {
+        if (!dequeueCommand)
+            return void instructions.unshift(...steps);
+        const choice = instructions.findIndex((step) => step.includes(dequeueCommand));
+        instructions.splice(choice + 1, 0, ...steps.map(pathA));
+    };
     if (failingAgentChecks.some((check) => releasedCheckNames.has(check.name))) {
         const completion = instructions.pop();
-        instructions.push(buildReleasedBlockerInstruction(prNumber));
+        instructions.push(pathA(buildReleasedBlockerInstruction(prNumber)));
         if (completion !== undefined)
             instructions.push(completion);
     }
@@ -357,15 +374,16 @@ async function handleTriageTick(ctx) {
         if (completion !== undefined)
             instructions.push(completion);
     }
-    if (repairInstructions && repairInstructions.length > 0) {
-        instructions.unshift(...repairInstructions);
-    }
+    if (repairInstructions && repairInstructions.length > 0)
+        prependBranchSteps(repairInstructions);
     if (mergedBasePullRequests.length > 0) {
         // `gh pr edit` goes through GraphQL; REST callers retarget with the pulls PATCH endpoint.
         const retarget = report.transport === "rest"
             ? `gh api --method PATCH repos/${report.repo}/pulls/${prNumber} -f base=<verified-parent-base>`
             : `gh pr edit ${prReference} --base <verified-parent-base>`;
-        instructions.unshift(`Inspect every PR under \`## Merged PRs matching the current base\`. If this PR is the remaining layer intended for a merged parent's base branch, run \`${retarget}\` after replacing \`<verified-parent-base>\` with that parent's shell-quoted base branch, then rerun Shepherd immediately and follow its fresh instructions instead of the remaining steps here. Otherwise keep the current base and follow the remaining conflict-resolution steps.`);
+        prependBranchSteps([
+            `Inspect every PR under \`## Merged PRs matching the current base\`. If this PR is the remaining layer intended for a merged parent's base branch, run \`${retarget}\` after replacing \`<verified-parent-base>\` with that parent's shell-quoted base branch, then rerun Shepherd immediately and follow its fresh instructions instead of the remaining steps here. Otherwise keep the current base and follow the remaining conflict-resolution steps.`,
+        ]);
     }
     const checkRunCount = countReportedChecks(report.checks);
     const suitesEmpty = report.headCheckSuitesEmpty === true;
@@ -404,12 +422,15 @@ async function handleTriageTick(ctx) {
             firstLookThreads,
             firstLookComments,
             ...(report.reviewItems && { reviewItems: report.reviewItems }),
+            ...(ctx.deferredWork && { deferredWork: ctx.deferredWork }),
         },
     };
     const result = await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds);
     if (result.action === "triage" && opts.persistSeen !== false) {
         await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
-        await Promise.allSettled(result.triage.checks.flatMap((ch) => (ch.annotations ?? []).map((a) => markSeen(stallKey, a.id, annotationMarkerBody(a)))));
+        // A queued conflict's annotation fixes are path (a); waiting keeps them unseen.
+        if (!queuedConflict)
+            await Promise.allSettled(result.triage.checks.flatMap((ch) => (ch.annotations ?? []).map((a) => markSeen(stallKey, a.id, annotationMarkerBody(a)))));
     }
     return result;
 }

package/bin/commands/poll-summary-explicit-instructions.mjs

@@ -35,6 +35,9 @@ export function explicitInstructions(result, rerunCommand) {
         "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
         `3. Run ${again} again after selected work completes; one row's \`ESCALATE\` does not stop work on other rows. ${KEEP_WATCHING}`,
     ];
+    if (result.prs.some((item) => item.action === "escalate") && !isHandedOffSelection(result)) {
+        instructions[0] = `${instructions[0]} Report each \`ESCALATE\` row's reasons to the user now and leave that PR alone; keep working on the other rows.`;
+    }
     if (onlyDraftVerificationSelection(result)) {
         instructions[2] = `3. If every draft verification probe returns \`[CANCEL]\` with reason \`auto-mark-ready-disabled\`, stop this selection and report any \`ESCALATE\` rows; leave the drafts unchanged. If any probe returns \`[ESCALATE]\`, report that handoff and stop after the other probes finish. Otherwise follow the probes' instructions and rerun ${again} when that work completes.`;
     }

package/bin/commands/poll-summary-instructions.mjs

@@ -140,7 +140,7 @@ function planStack(result, mergeRequested, rerunCommand) {
                     action: "cancel",
                     stackMergeable: false,
                     instructions: [
-                        `1. Stop shepherding this stack. Automatic mark-ready is disabled and ${work.held.map((item) => `PR #${item.pr}`).join(", ")} ${work.held.length === 1 ? "is" : "are"} clean but still in draft.`,
+                        `1. Stop shepherding this stack. Automatic mark-ready is disabled and ${work.held.map((item) => `PR #${item.pr}`).join(", ")} ${work.held.length === 1 ? "is" : "are"} clean but still in draft. Leave ${work.held.length === 1 ? "it" : "them"} in draft and end the turn; do not mark ${work.held.length === 1 ? "it" : "them"} ready or suggest doing so, because that is the human's decision.`,
                     ],
                 };
             }

package/bin/comments/resolve.d.mts

@@ -11,6 +11,8 @@ export interface ResolveResult {
     rateLimit?: ResolveRateLimitStop;
     sessionRefusal?: string;
     instructions?: string[];
+    /** IDs GitHub denied (403/404); Shepherd omits them from later commands until edited. */
+    deniedIds?: string[];
     unrepliedThreads?: string[];
     unresolvedThreads?: string[];
     unminimizedComments?: string[];

package/bin/comments/resolve.mjs

@@ -86,6 +86,11 @@ export async function applyResolveOptions(pr, repo, opts, preflight) {
             "Restore GitHub access for this session using the proxy instructions above.",
             "Retry only the pending IDs listed above.",
         ];
+    else if (result.deniedIds?.length)
+        result.instructions = [
+            `GitHub denied ${result.deniedIds.map((id) => `\`${id}\``).join(", ")}. Shepherd omits ${result.deniedIds.length === 1 ? "it" : "them"} from later commands until edited, so do not retry, escalate, or route around ${result.deniedIds.length === 1 ? "it" : "them"}.`,
+            "Rerun Shepherd with the same options and continue from its output.",
+        ];
     return result;
 }
 export async function autoResolveThreads(threadIds) {
@@ -192,6 +197,8 @@ async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dis
         }), { mutation: true });
         if ("restStopped" in resp)
             restStopped = resp.restStopped === true;
+        if ("deniedIds" in resp && Array.isArray(resp.deniedIds) && resp.deniedIds.length)
+            (result.deniedIds ??= []).push(...resp.deniedIds);
         if ("sessionRefusal" in resp && typeof resp.sessionRefusal === "string")
             result.sessionRefusal = resp.sessionRefusal;
         data = resp.data;

package/bin/comments/rest-review-mutations.d.mts

@@ -18,5 +18,6 @@ export declare function applyRestReviewChunk(input: {
     retryAfterSeconds?: number;
     restStopped?: true;
     sessionRefusal?: string;
+    deniedIds?: string[];
 }>;
 export { isAmbiguousMutationError } from "./rest-reply.mts";

package/bin/comments/rest-review-mutations.mjs

@@ -108,8 +108,10 @@ export async function applyRestReviewChunk(input) {
             const message = error instanceof Error ? error.message : String(error);
             result.errors.push({ message, path: [op.alias] });
             const stop = rateLimitFromError(error, message);
-            if (!stop && error instanceof GitHubRequestError && [403, 404].includes(error.status))
+            if (!stop && error instanceof GitHubRequestError && [403, 404].includes(error.status)) {
                 await rememberDenied(input, op.id, op.kind);
+                (result.deniedIds ??= []).push(op.id);
+            }
             if (error instanceof GitHubRequestError) {
                 result.rateLimit = error.rateLimit;
                 result.retryAfterSeconds = error.retryAfterSeconds;

package/bin/github/poll-summary-annotations.d.mts

@@ -4,7 +4,7 @@ import type { RawSummaryPr } from "./poll-summary-raw.mts";
 type Routed = Pick<PollSummaryItem, "action" | "reasons">;
 /**
  * The one-PR check treats unseen annotations on any non-SUCCESS check (failing, skipped,
- * filtered, ignored or neutral) as actionable work. The compact summary only has annotation
+ * filtered or neutral) as actionable work; `checks.ignore` checks never gate, annotations included. The compact summary only has annotation
  * totals, and only for a row that otherwise claims readiness, so it loads them then and reads
  * the annotations of just the non-SUCCESS checks that have any. A row with unseen annotations,
  * or whose annotations cannot be read, goes to its one-PR `pollCommand` instead of

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

@@ -11,7 +11,7 @@ const READY_CLAIMS = new Set([
 ]);
 /**
  * The one-PR check treats unseen annotations on any non-SUCCESS check (failing, skipped,
- * filtered, ignored or neutral) as actionable work. The compact summary only has annotation
+ * filtered or neutral) as actionable work; `checks.ignore` checks never gate, annotations included. The compact summary only has annotation
  * totals, and only for a row that otherwise claims readiness, so it loads them then and reads
  * the annotations of just the non-SUCCESS checks that have any. A row with unseen annotations,
  * or whose annotations cannot be read, goes to its one-PR `pollCommand` instead of
@@ -44,7 +44,7 @@ function nonSuccessCheckTotals(raw, required, totalsKnown) {
     for (const check of classifiedSummaryChecks(raw, required)) {
         if (check.scope || check.id == null || !head.has(check.id))
             continue;
-        if (check.category === "in_progress" || check.category === "superseded")
+        if (["in_progress", "superseded", "ignored"].includes(check.category))
             continue;
         if (check.status !== "COMPLETED" || check.conclusion === "SUCCESS")
             continue;

package/bin/types/iterate.d.mts

@@ -149,6 +149,8 @@ interface TriageDetails {
         shown: number;
         total: number;
     };
+    /** Review work a queued conflicting PR holds back until it leaves the queue. Omitted when empty. */
+    deferredWork?: import("./merge-queue.mts").IterateDeferredWork;
 }
 export interface IterateResultTriage extends IterateResultBase {
     action: "triage";

package/bin/types/report.d.mts

@@ -69,8 +69,6 @@ export interface ShepherdReport {
         skipped: ClassifiedCheck[];
         /** Checks filtered out because they were triggered by a non-PR event (push, schedule, etc.). */
         filtered: ClassifiedCheck[];
-        /** Ignored checks with unseen annotations; omitted when empty. */
-        ignored?: ClassifiedCheck[];
         filteredNames: string[];
         blockedByFilteredCheck: boolean;
         ignoredNames?: string[];
@@ -215,6 +213,8 @@ export interface AgentCheck {
     rerunCommand?: string;
     /** Workflow-run attempt number, surfaced only after the initial attempt. */
     runAttempt?: number;
+    /** `owner/name#number` of a recorded blocker that has merged or closed. */
+    releasedBlocker?: string;
     annotations?: CheckAnnotation[];
     annotationOnly?: true;
     scope?: "merge_group";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -91,7 +91,7 @@
     "husky": "^9.1.7",
     "knip": "^6.14.1",
     "marked": "^18.0.11",
-    "oxfmt": "^0.73.0",
+    "oxfmt": "^0.75.0",
     "oxlint": "^1.60.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"

package/plugins/pr-shepherd/.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/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "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@1.1.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@1.2.0", "pr-shepherd-mcp"]
     }
   }
 }

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

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