pr-shepherd 0.56.3 → 0.56.5

package/.claude-plugin/plugin.json

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

package/README.md

@@ -164,7 +164,7 @@ receipts, and whose bottom open layer GitHub has retargeted onto the stack base,
 with `gh stack merge <that PR number> --yes` and the allowed method flag (`--squash` unless config or the repository selects another). That lands the named layer and every
 unmerged layer below it. When the base uses a merge queue, the same command queues the prefix
 together and GitHub evaluates each layer from the bottom; a failure ejects that layer and those
-above it. If the evidence shows an unrelated failure and no source changes or other blockers remain, the one-PR session emits a head-, queue-commit-, and timestamp-pinned local acknowledgment command. Fresh source checks and a new READY receipt then let the aggregate selector recover the eligible prefix. Manual or stale removals cannot use this path. Layers above the prefix keep their one-PR sessions. After the merge, GitHub retargets
+above it. For a `failed_checks` removal on the layer's first ejection, the one-PR session emits a head-, queue-commit-, and timestamp-pinned local acknowledgment command; run it only when the failure does not reproduce after updating from the latest base, the head did not change, and no source changes or other blockers remain. Fresh source checks and a new READY receipt then let the aggregate selector recover the eligible prefix. Manual or stale removals cannot use this path. Layers above the prefix keep their one-PR sessions. After the merge, GitHub retargets
 the next layer, so the rerun continues until the stack returns `CANCEL`. API and MCP aggregate
 calls perform one summary tick and leave recurrence to the caller.
 

package/bin/cli/fix-formatter.mjs

@@ -14,6 +14,12 @@ export function formatFixCodeResult(header, result, opts = {}) {
     const verbose = opts.verbose ?? false;
     const topCap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
     const sections = [header];
+    if (result.mergedBasePullRequests?.length) {
+        sections.push("## Merged PRs matching the current base");
+        sections.push(result.mergedBasePullRequests
+            .map((pr) => `- [#${pr.number}](${pr.url}) · state \`${pr.state}\` · head \`${pr.headRefName}\` at \`${pr.headRefOid}\` · base \`${pr.baseRefName}\` · mergedAt \`${pr.mergedAt}\` · headRepository \`${pr.headRepository.nameWithOwner}\``)
+            .join("\n"));
+    }
     const renderThreads = (heading, threads) => {
         if (threads.length === 0)
             return;

package/bin/cli/iterate-lean.mjs

@@ -43,6 +43,9 @@ export function projectIterateLean(result, opts) {
         }),
         ...(result.baseBranch && { baseBranch: result.baseBranch }),
         ...(result.stackTrunkConflict && { stackTrunkConflict: result.stackTrunkConflict }),
+        ...((result.mergedBasePullRequests?.length ?? 0) > 0 && {
+            mergedBasePullRequests: result.mergedBasePullRequests,
+        }),
         ...(result.branchProtection !== null && { branchProtection: result.branchProtection }),
         ...(result.mergeRequirements && { mergeRequirements: result.mergeRequirements }),
         ...(result.mergeQueue && { mergeQueue: result.mergeQueue }),

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

@@ -40,6 +40,8 @@ export function appendMergeQueueHeader(lines, result) {
         parts.push("checks incomplete (first 100 shown)");
     if (queue.headUpdatedAfterRemoval)
         parts.push("head updated after removal");
+    if (queue.removalsOnHead)
+        parts.push(`removals on this head \`${queue.removalsOnHead}\``);
     if (queue.removalAcknowledged)
         parts.push("removal acknowledged");
     lines.push(`**merge queue** ${parts.join(" · ")}`);

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

@@ -24,10 +24,9 @@ export async function applyQueueRemovalAck(input) {
         !queueRemovalAppliesToHead({
             parentOids: removal.beforeCommitParentOids,
             headOid: data.headRefOid,
-            ...(data.activity?.latestCommitCommittedAtUnix != null && {
-                headCommittedAtUnix: data.activity.latestCommitCommittedAtUnix,
-            }),
-            ...(data.headPushedAtUnix !== undefined && { headPushedAtUnix: data.headPushedAtUnix }),
+            headCommittedAtUnix: data.activity?.latestCommitCommittedAtUnix,
+            headPushedAtUnix: data.headPushedAtUnix,
+            headForcePushedAtUnix: data.headForcePushedAtUnix,
             removedAtUnix: removal.createdAtUnix,
         })) {
         throw new ShepherdError("The supplied queue-removal evidence is stale or is not a current CI-driven removal for this native-stack PR.", EXIT.UNAVAILABLE);

package/bin/commands/check.mjs

@@ -1,5 +1,5 @@
 import { fetchPrBatch } from "../github/batch.mjs";
-import { queueRemovalAppliesToHead } from "../github/queue-removal-freshness.mjs";
+import { headArrivalUnix, queueRemovalAppliesToHead } from "../github/queue-removal-freshness.mjs";
 import { readQueueRemovalAcknowledgment, matchesQueueRemovalAcknowledgment, isCiQueueRemovalReason, } from "../state/queue-removal-ack.mjs";
 import { storePrFingerprint } from "../state/pr-fingerprint.mjs";
 import { tryReuseFingerprintReport } from "./check-fingerprint.mjs";
@@ -76,22 +76,25 @@ export async function runCheck(opts, context) {
     // it as stale/updated rather than as still current, so Shepherd doesn't escalate
     // `merge-queue-removed` permanently on data it can no longer check. A squash or rebase
     // queue commit has one parent and does not list the PR head; that removal stays current
-    // until this head reached the PR after it. The push time is the earliest pull_request
-    // check on the head, with committer time as the fallback when no check time is
-    // available. The raw removal fields still render in the merge-queue header regardless
-    // of this flag.
-    const headCommittedAtUnix = batchData.activity?.latestCommitCommittedAtUnix;
+    // until this head reached the PR after it (`headArrivalUnix`). The raw removal fields
+    // still render in the merge-queue header regardless of this flag.
+    const headTimes = {
+        headCommittedAtUnix: batchData.activity?.latestCommitCommittedAtUnix,
+        headPushedAtUnix: batchData.headPushedAtUnix,
+        headForcePushedAtUnix: batchData.headForcePushedAtUnix,
+    };
     const headUpdatedAfterRemoval = Boolean(latestRemoval &&
         !queueRemovalAppliesToHead({
+            ...headTimes,
             parentOids: latestRemoval.beforeCommitParentOids,
             headOid: batchData.headRefOid,
-            ...(headCommittedAtUnix !== undefined &&
-                headCommittedAtUnix !== null && { headCommittedAtUnix }),
-            ...(batchData.headPushedAtUnix !== undefined && {
-                headPushedAtUnix: batchData.headPushedAtUnix,
-            }),
             removedAtUnix: latestRemoval.createdAtUnix,
         }));
+    // Repeat ejections of this head: removals after it reached the PR.
+    const headSinceUnix = headArrivalUnix(headTimes);
+    const removalsOnHead = latestRemoval && !headUpdatedAfterRemoval && headSinceUnix !== undefined
+        ? (batchData.mergeQueueRemovalTimesUnix ?? []).filter((t) => t >= headSinceUnix).length
+        : 0;
     const removalAcknowledged = Boolean(batchData.stack &&
         latestRemoval?.beforeCommitOid &&
         isCiQueueRemovalReason(latestRemoval.reason) &&
@@ -367,6 +370,7 @@ export async function runCheck(opts, context) {
                     checksIncomplete: true,
                 }),
                 ...(headUpdatedAfterRemoval && { headUpdatedAfterRemoval: true }),
+                ...(removalsOnHead > 1 && { removalsOnHead }),
                 ...(removalAcknowledged && { removalAcknowledged: true }),
             },
         }),

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

@@ -8,9 +8,11 @@ import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./thre
 import { buildFixInstructions } from "./render.mjs";
 import { buildRemovedQueueRecovery, buildStackQueueRemovalAcknowledgment } from "./merge.mjs";
 import { hasLogEvidence } from "./check-evidence.mjs";
+import { currentEjectionCommit, } from "./queue-recovery-instructions.mjs";
 import { buildReleasedBlockerInstruction } from "./check-instructions.mjs";
 import { buildNativeStackLayerRebase } from "./native-stack-rebase.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";
@@ -291,6 +293,14 @@ export async function handleFixCode(ctx) {
     const firstLookComments = report.comments.firstLook;
     const stack = report.mergeStatus.mergeRequirements?.stack;
     const headRef = report.headSha;
+    const mergedBasePullRequests = hasConflicts && !stack && report.baseRefOid
+        ? await lookupMergedBasePullRequests({
+            owner: repoOwner,
+            repo: repoName,
+            baseRefName: baseLookup.branch,
+            baseRefOid: report.baseRefOid,
+        })
+        : [];
     // Only an upper layer can be dirty against trunk while already containing its parent.
     const trunkConflict = hasConflicts && stack && headRef && baseLookup.branch !== stack.baseRefName
         ? await lookupUpperLayerTrunkConflict({
@@ -301,25 +311,21 @@ export async function handleFixCode(ctx) {
             trunk: stack.baseRefName,
         })
         : undefined;
-    // Conflicts, and a behind branch whose rerun already failed, both ask for a branch update.
-    const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0)
-        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict)
-        : undefined;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase);
     const requeue = buildRemovedQueueRecovery(report, failingAgentChecks, opts.merge);
     const queueRemovalAcknowledgment = buildStackQueueRemovalAcknowledgment(report, failingAgentChecks);
-    if (queueRemovalAcknowledgment) {
-        const completion = instructions.pop();
-        instructions.push("If the merge-group failure belongs to this PR, fix and push its head, then iterate. Otherwise, if no code changed and no other blocker remains, run `acknowledge queue removal:` exactly as printed. This records only the disposition of that removed queue commit; finish this one-PR session to validate current source CI and record its READY receipt, then return to the aggregate `--stack` selector with its original options. In merge mode it verifies lower-layer readiness before merging. Do not enqueue or merge this layer directly.");
-        if (completion !== undefined)
-            instructions.push(completion);
-    }
-    if (requeue) {
-        const completion = instructions.pop();
-        instructions.push("If the merge-group failure belongs to this PR, fix and push the PR head, then iterate. Otherwise, if no code changed and no other blocker remains, run the `requeue:` command exactly as printed. If gh reports auto-merge is disabled instead of adding the PR to the queue, run the `requeue API fallback:` command. Both commands require the observed PR head SHA; if the head changed, iterate for a fresh command.");
-        if (completion !== undefined)
-            instructions.push(completion);
-    }
+    const queueEjection = !currentEjectionCommit(report, failingAgentChecks)
+        ? undefined
+        : requeue
+            ? "requeue"
+            : queueRemovalAcknowledgment
+                ? "acknowledge"
+                : "none";
+    // Conflicts, a behind branch whose rerun already failed, and a queue ejection that may be
+    // reproduced on the latest base all print the branch update route.
+    const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0) || queueEjection
+        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict)
+        : undefined;
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase, queueEjection);
     if (failingAgentChecks.some((check) => releasedCheckNames.has(check.name))) {
         const completion = instructions.pop();
         instructions.push(buildReleasedBlockerInstruction(prNumber));
@@ -329,6 +335,9 @@ export async function handleFixCode(ctx) {
     if (repairInstructions && repairInstructions.length > 0) {
         instructions.unshift(...repairInstructions);
     }
+    if (mergedBasePullRequests.length > 0) {
+        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 \`gh pr edit ${prReference} --base <verified-parent-base>\` 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;
     const nowMs = Date.now();
@@ -345,6 +354,7 @@ export async function handleFixCode(ctx) {
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,
+        ...(mergedBasePullRequests.length > 0 && { mergedBasePullRequests }),
         ...(trunkConflict && { stackTrunkConflict: trunkConflict.trunk }),
         action: "fix_code",
         fix: {

package/bin/commands/iterate/index.mjs

@@ -135,6 +135,7 @@ async function runIterateCore(opts) {
         stateKey: stallKey,
         headSha,
         otherAutonomousWork: hasActionableWork || staleAncestry !== null,
+        persistState: opts.persistSeen !== false,
     });
     if (unreportedPlan.escalate)
         return unreportedPlan.escalate;

package/bin/commands/iterate/merge.mjs

@@ -99,6 +99,9 @@ function removedQueueRecoveryAvailable(report, checks, merge) {
         !queue?.enabled ||
         queue.inQueue ||
         queue.headUpdatedAfterRemoval ||
+        // A repeat ejection of the same head is not retried blindly; a conflict forces a new head.
+        (queue.removalsOnHead ?? 1) > 1 ||
+        report.mergeStatus.status === "CONFLICTS" ||
         // GitHub exposes a raw string, not a capability to reverse a human's queue removal.
         // Only known CI-driven reasons authorize offering automated recovery.
         !isCiQueueRemovalReason(queue.latestRemoval?.reason) ||

package/bin/commands/iterate/merged-base-pull-requests.d.mts

@@ -0,0 +1,8 @@
+import type { MergedBasePullRequest } from "../../types.mts";
+/** A bounded, best-effort lookup; matching OIDs and repository prevent branch-name reuse false positives. */
+export declare function lookupMergedBasePullRequests(input: {
+    owner: string;
+    repo: string;
+    baseRefName: string;
+    baseRefOid: string;
+}): Promise<MergedBasePullRequest[]>;

package/bin/commands/iterate/merged-base-pull-requests.mjs

@@ -0,0 +1,24 @@
+import { graphql } from "../../github/client.mjs";
+import { MERGED_BASE_PULL_REQUESTS_QUERY } from "../../github/queries.mjs";
+import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
+/** A bounded, best-effort lookup; matching OIDs and repository prevent branch-name reuse false positives. */
+export async function lookupMergedBasePullRequests(input) {
+    try {
+        const { data } = await graphql(MERGED_BASE_PULL_REQUESTS_QUERY, {
+            owner: input.owner,
+            repo: input.repo,
+            branch: input.baseRefName,
+        });
+        return (data.repository?.pullRequests.nodes ?? []).filter((candidate) => candidate !== null &&
+            candidate.state === "MERGED" &&
+            candidate.headRefName === input.baseRefName &&
+            candidate.headRefOid === input.baseRefOid &&
+            candidate.headRepository?.nameWithOwner === `${input.owner}/${input.repo}`);
+    }
+    catch (error) {
+        if (pollRateLimitRetryAfterMs(error) !== null)
+            throw error;
+        process.stderr.write(`pr-shepherd: merged-base PR lookup unavailable (ignored): ${error instanceof Error ? error.message : String(error)}\n`);
+        return [];
+    }
+}

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

@@ -36,5 +36,8 @@ export declare function buildNativeStackLayerRebase(repo: string, pr: {
 }): 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;
-/** Push a conflict resolution or branch refresh: one branch, or the whole rewritten native stack. */
-export declare function buildBranchPushInstruction(stackRebase: string | undefined, hasConflicts: boolean, mutationSuffix: string): 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.
+ */
+export declare function buildBranchPushInstruction(stackRebase: string | undefined, hasConflicts: boolean, mutationSuffix: string, ejectionUpdate?: boolean): string;

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

@@ -44,8 +44,17 @@ export function buildConflictInstruction(stackRebase) {
     const pointer = "The branch has merge conflicts (see `**branch**` above).";
     return stackRebase ? `${pointer} ${stackRebase}` : `${pointer} Resolve them before committing.`;
 }
-/** Push a conflict resolution or branch refresh: one branch, or the whole rewritten native stack. */
-export function buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix) {
+/**
+ * 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.
+ */
+export function buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix, ejectionUpdate = false) {
+    if (ejectionUpdate) {
+        const push = stackRebase
+            ? "commit any remaining changes on the PR head branch and push the rewritten stack with `gh stack push`"
+            : "commit any remaining changes and push to the PR head branch";
+        return `If the base update or a fix changed the head, ${push}${mutationSuffix}. If neither did, do not push.`;
+    }
     if (stackRebase)
         return `Commit any remaining changes on the PR head branch and push the rewritten stack with \`gh stack push\`${mutationSuffix}.`;
     return hasConflicts

package/bin/commands/iterate/queue-recovery-instructions.d.mts

@@ -0,0 +1,8 @@
+/** Instruction text for a PR that GitHub removed from the merge queue after failed checks. */
+import type { AgentCheck, ShepherdReport } from "../../types.mts";
+/** Which recovery command, if any, Shepherd printed for a failure that does not reproduce. */
+export type QueueEjectionRecovery = "requeue" | "acknowledge" | "none";
+/** The removed queue commit whose failed checks this tick surfaces, if the removal is current. */
+export declare function currentEjectionCommit(report: ShepherdReport, checks: AgentCheck[]): string | undefined;
+/** The ejection step after failing-check triage; points at a stack route already printed. */
+export declare function queueEjectionSteps(recovery: QueueEjectionRecovery | undefined, stackRebase: string | undefined, routePrinted: boolean): string[];

package/bin/commands/iterate/queue-recovery-instructions.mjs

@@ -0,0 +1,38 @@
+/** Instruction text for a PR that GitHub removed from the merge queue after failed checks. */
+import { playbookPointer } from "../playbook-pointer.mjs";
+/** The removed queue commit whose failed checks this tick surfaces, if the removal is current. */
+export function currentEjectionCommit(report, checks) {
+    const queue = report.mergeQueue;
+    const commit = queue?.latestRemoval?.beforeCommitOid;
+    if (!commit || queue.inQueue || queue.headUpdatedAfterRemoval)
+        return undefined;
+    return checks.some((check) => check.scope === "merge_group" && check.commitOid === commit)
+        ? commit
+        : undefined;
+}
+/** The ejection step after failing-check triage; points at a stack route already printed. */
+export function queueEjectionSteps(recovery, stackRebase, routePrinted) {
+    if (!recovery)
+        return [];
+    const route = stackRebase && routePrinted ? "use the stack route printed above." : stackRebase;
+    return [buildQueueEjectionInstruction(recovery, route)];
+}
+/**
+ * The trigger, update route, and command guard; the fixed procedure lives in the playbook.
+ * A printed command implies a `failed_checks` removal. Without one, the agent reads the raw
+ * removal reason, since a person's dequeue must not be undone by a branch update.
+ */
+function buildQueueEjectionInstruction(recovery, stackRoute) {
+    const target = stackRoute ? "the stack" : "the PR head";
+    const route = stackRoute ? `: ${stackRoute}` : ".";
+    const update = recovery === "none"
+        ? `If the \`**queue removal**\` reason shows GitHub removed the entry itself, update ${target} from the latest base first${route} If a person may have dequeued the PR, skip that update unless a conflict step above requires it.`
+        : `Update ${target} from the latest base first${route}`;
+    const reproduce = "only if the failure does not reproduce on the updated head, neither the update nor a code change altered the head, and no other blocker remains.";
+    const guard = recovery === "requeue"
+        ? `Run \`requeue:\` ${reproduce} If gh reports auto-merge is disabled, run \`requeue API fallback:\` instead.`
+        : recovery === "acknowledge"
+            ? `Run \`acknowledge queue removal:\` ${reproduce}`
+            : "Shepherd printed no queue command for this session, so do not enqueue the PR.";
+    return `Triage the merge-queue ejection before any requeue. ${update} ${guard} ${playbookPointer("Merge queue ejection")}`;
+}

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

@@ -1,5 +1,7 @@
 import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, FirstLookThread, FirstLookComment, ReviewThread } from "../../types.mts";
+import { type QueueEjectionRecovery } from "./queue-recovery-instructions.mts";
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 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, _cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], _inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind?: boolean, viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string): string[];
+isBehind?: boolean, viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string, // native stack layers rebase with gh-stack, not branch by branch
+queueEjection?: QueueEjectionRecovery): string[];

package/bin/commands/iterate/render.mjs

@@ -5,6 +5,7 @@ import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 import { partitionFixThreads, reviewSectionRefs } from "./fix-instruction-threads.mjs";
 import { buildBranchPushInstruction, buildConflictInstruction } from "./native-stack-rebase.mjs";
+import { queueEjectionSteps } from "./queue-recovery-instructions.mjs";
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export function renderResolveCommand(rc) {
     const parts = [...rc.argv];
@@ -13,7 +14,8 @@ export function renderResolveCommand(rc) {
     return renderShellCommand(parts);
 }
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, _cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], _inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase) {
+isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase, // native stack layers rebase with gh-stack, not branch by branch
+queueEjection) {
     const instructions = [];
     const { locatedThreads, unlocatedMutatedThreads, unlocatedThreads } = partitionFixThreads(threads, resolveCommand, resolveOnlyCommand);
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
@@ -45,25 +47,22 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, st
     });
     // The conflict hint belongs with the conflict step; otherwise it precedes the push step.
     const hintWithConflictStep = hasConflicts && !hasRepeatedWorkflowBranchRecovery;
-    if (hintWithConflictStep) {
+    const branchRecovery = hasConflicts || hasRepeatedWorkflowBranchRecovery;
+    if (hintWithConflictStep)
         instructions.push(buildConflictInstruction(stackRebase), ...branchUpdateHint);
-    }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
-    if (firstLookTotal > 0) {
+    if (firstLookTotal > 0)
         instructions.push("Review every item under `## First-look items` before acting.");
-    }
     if (firstLookSummaries.length > 0 && viewerCanUpdate)
         instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
     const editedTotal = editedSummaries.length +
         actionableComments.filter((c) => c.edited).length +
         firstLookThreads.filter((t) => t.edited).length +
         firstLookComments.filter((c) => c.edited).length;
-    if (editedTotal > 0) {
+    if (editedTotal > 0)
         instructions.push("Read every item marked `[edited since first look]`, including edited summaries and edited first-look bullets, before deciding whether to resolve a matching thread.");
-    }
-    if (unlocatedThreads.length > 0) {
+    if (unlocatedThreads.length > 0)
         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"));
@@ -73,13 +72,11 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, st
         const filesRef = locatedThreads.length > 0 ? "each file referenced above" : "the relevant files";
         instructions.push(`Apply every warranted review fix in ${filesRef}.`);
     }
-    if (resolutionOnlyThreads.length > 0) {
+    if (resolutionOnlyThreads.length > 0)
         instructions.push("Review the threads under `## Review threads to resolve` before running the generated mutations.");
-    }
-    instructions.push(...buildFailingCheckInstructions(failingChecks), ...repeatedWorkflowBranchRecoveryInstructions);
-    if (hasAnnotations) {
+    instructions.push(...buildFailingCheckInstructions(failingChecks), ...repeatedWorkflowBranchRecoveryInstructions, ...queueEjectionSteps(queueEjection, stackRebase, branchRecovery));
+    if (hasAnnotations)
         instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.");
-    }
     if (changesRequestedReviews.length > 0) {
         const staleClause = buildCrStaleClause(changesRequestedReviews);
         instructions.push(`Read every body under \`## Changes-requested reviews\` and apply any warranted change.${staleClause}`);
@@ -88,8 +85,8 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, st
         instructions.push(...branchUpdateHint);
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
-    if (hasConflicts || hasRepeatedWorkflowBranchRecovery) {
-        instructions.push(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix));
+    if (branchRecovery || queueEjection) {
+        instructions.push(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix, !branchRecovery));
     }
     else if (hasNonConflictHints) {
         instructions.push("If you changed code, commit any remaining changes and push to the PR head branch. If you did not, do not commit.");

package/bin/commands/iterate/stall.mjs

@@ -50,6 +50,8 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
         state: base.state,
         isDraft: base.isDraft,
         checks,
+        // A requeued head ejected again gets its own triage window.
+        queueRemovalCommit: report.mergeQueue?.latestRemoval?.beforeCommitOid,
         threads,
         resolutionOnlyThreads,
         ruleAutoResolveThreads,

package/bin/commands/iterate/unreported-required.d.mts

@@ -13,6 +13,8 @@ export declare function planUnreportedRequired(input: {
     };
     headSha: string;
     otherAutonomousWork: boolean;
+    /** Internal preview ticks must not consume the one-time reopen opportunity. */
+    persistState?: boolean;
 }): Promise<UnreportedPlan>;
 export declare function buildUnreportedFixResult(base: IterateResultBase, report: ShepherdReport, instructions: string[]): IterateResult;
 export {};

package/bin/commands/iterate/unreported-required.mjs

@@ -72,7 +72,7 @@ export async function planUnreportedRequired(input) {
         trunk: (input.report.trunkBehindBy ?? 0) > 0,
         ...(rebase && { stackRebase: rebase }),
     });
-    if (decision === "reopen") {
+    if (decision === "reopen" && input.persistState !== false) {
         await writeCiRetrigger(input.stateKey, { headSha: input.headSha, contexts: names });
     }
     return { repairInstructions: instructions };

package/bin/github/batch-parsers.mjs

@@ -118,6 +118,12 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         reviewDecision: (raw.reviewDecision ?? null),
         headRefOid: raw.headRefOid,
         ...(headPushedAtUnix !== undefined && { headPushedAtUnix }),
+        ...(raw.headRefForcePushes?.nodes[0] && {
+            headForcePushedAtUnix: Math.floor(Date.parse(raw.headRefForcePushes.nodes[0].createdAt) / 1000),
+        }),
+        ...(raw.mergeQueueRemovalTimes && {
+            mergeQueueRemovalTimesUnix: raw.mergeQueueRemovalTimes.nodes.map((node) => Math.floor(Date.parse(node.createdAt) / 1000)),
+        }),
         headRefName: raw.headRefName,
         headRepoWithOwner: raw.headRepository?.nameWithOwner ?? null,
         viewerAuthorization: {

package/bin/github/batch-raw-rules.d.mts

@@ -101,6 +101,18 @@ export interface RawPrMergeFields {
             createdAt: string;
         }>;
     } | null;
+    /** Timestamps of the last 10 queue removals; counts repeat ejections of one head. */
+    mergeQueueRemovalTimes?: {
+        nodes: Array<{
+            createdAt: string;
+        }>;
+    } | null;
+    /** The latest force-push, which dates a head whose commit time predates its push. */
+    headRefForcePushes?: {
+        nodes: Array<{
+            createdAt: string;
+        }>;
+    } | null;
     stack?: RawStack | null;
     stackEntry?: {
         position: number;

package/bin/github/gql/batch-pr.gql

@@ -88,6 +88,20 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           }
         }
       }
+      mergeQueueRemovalTimes: timelineItems(last: 10, itemTypes: [REMOVED_FROM_MERGE_QUEUE_EVENT]) {
+        nodes {
+          ... on RemovedFromMergeQueueEvent {
+            createdAt
+          }
+        }
+      }
+      headRefForcePushes: timelineItems(last: 1, itemTypes: [HEAD_REF_FORCE_PUSHED_EVENT]) {
+        nodes {
+          ... on HeadRefForcePushedEvent {
+            createdAt
+          }
+        }
+      }
       stack {
         number
         size

package/bin/github/gql/merged-base-pull-requests.gql

@@ -0,0 +1,31 @@
+query MergedBasePullRequests($owner: String!, $repo: String!, $branch: String!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  repository(owner: $owner, name: $repo) {
+    pullRequests(
+      headRefName: $branch
+      states: MERGED
+      first: 20
+      orderBy: { field: UPDATED_AT, direction: DESC }
+    ) {
+      nodes {
+        number
+        url
+        state
+        headRefName
+        headRefOid
+        baseRefName
+        mergedAt
+        headRepository {
+          nameWithOwner
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/poll-summary-fragment.gql

@@ -93,6 +93,13 @@ fragment PollSummaryPr on PullRequest {
       }
     }
   }
+  headRefForcePushes: timelineItems(last: 1, itemTypes: [HEAD_REF_FORCE_PUSHED_EVENT]) {
+    nodes {
+      ... on HeadRefForcePushedEvent {
+        createdAt
+      }
+    }
+  }
   mergeQueueEntry {
     headCommit {
       oid

package/bin/github/merge-queue-checks.mjs

@@ -1,7 +1,7 @@
 import { parseCreatedAt } from "./batch-parser-helpers.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { GitHubRequestError } from "./errors.mjs";
-import { headPushUnixFromCheckNodes, queueRemovalAppliesToHead, } from "./queue-removal-freshness.mjs";
+import { forcePushUnix, headPushUnixFromCheckNodes, queueRemovalAppliesToHead, } from "./queue-removal-freshness.mjs";
 import { requireContextNodes } from "./batch-response.mjs";
 import { COMMIT_CHECK_CONTEXTS_QUERY } from "./queries.mjs";
 function omittedCursorError(oid) {
@@ -79,6 +79,7 @@ function currentRemovalCommit(raw) {
             headCommittedAtUnix: parseCreatedAt(headCommit.committedDate),
         }),
         ...(headPushedAtUnix !== undefined && { headPushedAtUnix }),
+        headForcePushedAtUnix: forcePushUnix(raw.headRefForcePushes),
         removedAtUnix: Math.floor(Date.parse(removal.createdAt) / 1000),
     })) {
         return undefined;

package/bin/github/poll-summary-queue-removal.mjs

@@ -1,4 +1,4 @@
-import { headPushUnixFromCheckNodes, queueRemovalAppliesToHead, } from "./queue-removal-freshness.mjs";
+import { forcePushUnix, headPushUnixFromCheckNodes, queueRemovalAppliesToHead, } from "./queue-removal-freshness.mjs";
 import { parseCreatedAt } from "./batch-parser-helpers.mjs";
 /** Latest queue removal that still applies to this PR head, not an older attempt. */
 export function currentQueueRemovalEvent(raw) {
@@ -21,6 +21,7 @@ export function currentQueueRemovalEvent(raw) {
             headCommittedAtUnix: parseCreatedAt(headCommit.committedDate),
         }),
         ...(headPushedAtUnix !== undefined && { headPushedAtUnix }),
+        headForcePushedAtUnix: forcePushUnix(raw.headRefForcePushes),
         removedAtUnix: Math.floor(removalTime / 1000),
     })) {
         return null;

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

@@ -138,6 +138,12 @@ export interface RawSummaryPr {
     mergeQueueEntry: {
         headCommit: RawSummaryCommit | null;
     } | null;
+    /** The latest force-push, which dates a head whose commit and check times predate its push. */
+    headRefForcePushes?: {
+        nodes: Array<{
+            createdAt: string;
+        }>;
+    } | null;
     stack: {
         number: number;
         size: number;

package/bin/github/queries.d.mts

@@ -39,6 +39,8 @@ export declare const POLL_STACK_TOPOLOGY_QUERY: string;
  * the open stack entries needed to name the bottom layer. Not part of BatchPr.
  */
 export declare const UPPER_LAYER_CONFLICT_TARGET_QUERY: string;
+/** Merged PRs whose head may be the stale base of a non-stack conflict. */
+export declare const MERGED_BASE_PULL_REQUESTS_QUERY: string;
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/github/queries.mjs

@@ -44,6 +44,8 @@ export const POLL_STACK_TOPOLOGY_QUERY = gql("poll-stack-topology.gql");
  * the open stack entries needed to name the bottom layer. Not part of BatchPr.
  */
 export const UPPER_LAYER_CONFLICT_TARGET_QUERY = gql("upper-layer-conflict-target.gql");
+/** Merged PRs whose head may be the stale base of a non-stack conflict. */
+export const MERGED_BASE_PULL_REQUESTS_QUERY = gql("merged-base-pull-requests.gql");
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/github/queue-removal-freshness.d.mts

@@ -15,17 +15,35 @@ type PushCheckNode = {
  * build a one-parent commit on the base, so parent identity cannot show a
  * later push. Missing parents are unverifiable: GitHub keeps returning the
  * latest removal after the synthetic commit is gone. A one-parent removal is
- * stale once this head reached the PR after the removal. That time is the
- * earliest pull_request check on the head, with the head's committer time as
- * the fallback when no check time is available.
+ * stale once this head reached the PR after the removal (see `headArrivalUnix`).
+ * A force-push after the removal makes any removal stale, even one whose
+ * parents list the head: that SHA was pushed back for a new attempt.
  */
-export declare function queueRemovalAppliesToHead(input: {
+export declare function queueRemovalAppliesToHead(input: HeadTimes & {
     parentOids: readonly string[] | null | undefined;
     headOid: string;
-    headCommittedAtUnix?: number;
-    headPushedAtUnix?: number;
     removedAtUnix?: number;
 }): boolean;
+type HeadTimes = {
+    headCommittedAtUnix?: number | null;
+    headPushedAtUnix?: number;
+    headForcePushedAtUnix?: number;
+};
+/**
+ * When the current head reached the PR. The earliest pull_request check on the
+ * head is its push time, but it can come from an earlier tenure of a commit
+ * that was later force-pushed back, so the latest force-push wins when it is
+ * later. Without a check time, the committer time is the fallback, again
+ * superseded by a later force-push. A committer clock that runs ahead only
+ * matters in that fallback.
+ */
+export declare function headArrivalUnix(input: HeadTimes): number | undefined;
+/** Latest head-ref force-push time from a `headRefForcePushes` timeline field. */
+export declare function forcePushUnix(field: {
+    nodes: Array<{
+        createdAt: string;
+    }>;
+} | null | undefined): number | undefined;
 /** Earliest pull_request check-suite time on the head commit, when one exists. */
 export declare function headPushUnixFromCheckNodes(nodes: readonly (PushCheckNode | null)[] | null | undefined): number | undefined;
 export {};

package/bin/github/queue-removal-freshness.mjs

@@ -7,28 +7,50 @@ const PULL_REQUEST_EVENTS = new Set(["pull_request", "pull_request_target"]);
  * build a one-parent commit on the base, so parent identity cannot show a
  * later push. Missing parents are unverifiable: GitHub keeps returning the
  * latest removal after the synthetic commit is gone. A one-parent removal is
- * stale once this head reached the PR after the removal. That time is the
- * earliest pull_request check on the head, with the head's committer time as
- * the fallback when no check time is available.
+ * stale once this head reached the PR after the removal (see `headArrivalUnix`).
+ * A force-push after the removal makes any removal stale, even one whose
+ * parents list the head: that SHA was pushed back for a new attempt.
  */
 export function queueRemovalAppliesToHead(input) {
     const parents = input.parentOids ?? [];
     if (parents.length === 0)
         return false;
+    const removedAt = positive(input.removedAtUnix);
+    const forcePushedAt = positive(input.headForcePushedAtUnix);
+    // The same SHA force-pushed back after the removal starts a new tenure.
+    if (removedAt !== undefined && forcePushedAt !== undefined && forcePushedAt > removedAt)
+        return false;
     if (parents.includes(input.headOid))
         return true;
     if (parents.length > 1)
         return false;
-    const removedAt = input.removedAtUnix;
-    if (removedAt === undefined || removedAt <= 0)
+    if (removedAt === undefined)
         return true;
-    const pushedAt = input.headPushedAtUnix;
-    if (pushedAt !== undefined && pushedAt > 0)
-        return pushedAt <= removedAt;
-    const committedAt = input.headCommittedAtUnix;
-    if (committedAt !== undefined && committedAt > removedAt)
-        return false;
-    return true;
+    const arrivedAt = headArrivalUnix(input);
+    return arrivedAt === undefined || arrivedAt <= removedAt;
+}
+/**
+ * When the current head reached the PR. The earliest pull_request check on the
+ * head is its push time, but it can come from an earlier tenure of a commit
+ * that was later force-pushed back, so the latest force-push wins when it is
+ * later. Without a check time, the committer time is the fallback, again
+ * superseded by a later force-push. A committer clock that runs ahead only
+ * matters in that fallback.
+ */
+export function headArrivalUnix(input) {
+    const pushedAt = positive(input.headPushedAtUnix) ?? positive(input.headCommittedAtUnix);
+    const forcePushedAt = positive(input.headForcePushedAtUnix);
+    if (pushedAt === undefined)
+        return forcePushedAt;
+    return forcePushedAt === undefined ? pushedAt : Math.max(pushedAt, forcePushedAt);
+}
+function positive(value) {
+    return value !== undefined && value !== null && value > 0 ? value : undefined;
+}
+/** Latest head-ref force-push time from a `headRefForcePushes` timeline field. */
+export function forcePushUnix(field) {
+    const raw = field?.nodes[0]?.createdAt;
+    return raw ? positive(parseCreatedAt(raw)) : undefined;
 }
 /** Earliest pull_request check-suite time on the head commit, when one exists. */
 export function headPushUnixFromCheckNodes(nodes) {

package/bin/state/ci-retrigger.d.mts

@@ -1,8 +1,10 @@
 /**
- * One close/reopen of a head that was missing required checks.
+ * One presented close/reopen instruction for a head that was missing required checks.
  *
  * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/ci-retrigger.json`
- * Reopening does not change the head SHA, so the next tick must not close the PR again.
+ * This records that Shepherd returned the instruction, not that the caller executed it.
+ * Reopening does not change the head SHA, so the next presented tick must not offer it again.
+ * Internal debounce preview ticks do not write this marker.
  */
 interface Retrigger {
     headSha: string;
@@ -14,12 +16,12 @@ export declare function readCiRetrigger(key: {
     repo: string;
     pr: number;
 }): Promise<Retrigger | undefined>;
-/** Remember that this head was already closed and reopened for these contexts. */
+/** Remember that the one close/reopen instruction was returned for this head and context set. */
 export declare function writeCiRetrigger(key: {
     owner: string;
     repo: string;
     pr: number;
 }, record: Retrigger): Promise<void>;
-/** True when this head was already retriggered for the same required contexts. */
+/** True when the one close/reopen instruction was already returned for this head and contexts. */
 export declare function sameCiRetrigger(record: Retrigger | undefined, headSha: string, contexts: readonly string[]): boolean;
 export {};

package/bin/state/ci-retrigger.mjs

@@ -1,8 +1,10 @@
 /**
- * One close/reopen of a head that was missing required checks.
+ * One presented close/reopen instruction for a head that was missing required checks.
  *
  * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/ci-retrigger.json`
- * Reopening does not change the head SHA, so the next tick must not close the PR again.
+ * This records that Shepherd returned the instruction, not that the caller executed it.
+ * Reopening does not change the head SHA, so the next presented tick must not offer it again.
+ * Internal debounce preview ticks do not write this marker.
  */
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -11,7 +13,7 @@ import { resolvePrStatePath } from "./base.mjs";
 export async function readCiRetrigger(key) {
     return readRetrigger(resolvePrStatePath(key, "ci-retrigger.json"));
 }
-/** Remember that this head was already closed and reopened for these contexts. */
+/** Remember that the one close/reopen instruction was returned for this head and context set. */
 export async function writeCiRetrigger(key, record) {
     const path = resolvePrStatePath(key, "ci-retrigger.json");
     await mkdir(dirname(path), { recursive: true });
@@ -21,7 +23,7 @@ export async function writeCiRetrigger(key, record) {
     };
     await writeFile(path, JSON.stringify(next));
 }
-/** True when this head was already retriggered for the same required contexts. */
+/** True when the one close/reopen instruction was already returned for this head and contexts. */
 export function sameCiRetrigger(record, headSha, contexts) {
     if (!record || record.headSha !== headSha)
         return false;

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

@@ -9,7 +9,11 @@ type StateKey = {
     repo: string;
     pr: number;
 };
-/** The only removal reasons that indicate a CI-driven queue ejection. */
+/**
+ * The only removal reason that indicates a CI-driven queue ejection. GitHub sends lowercase raw
+ * strings; observed values also include `merged`, `merge_conflict`, `invalid_merge_commit`, and
+ * `stack_invalidated`, none of which a requeue can recover.
+ */
 export declare function isCiQueueRemovalReason(reason: string | null | undefined): boolean;
 /** Missing, unreadable, or malformed acknowledgment state is treated as absent. */
 export declare function readQueueRemovalAcknowledgment(key: StateKey): Promise<QueueRemovalAcknowledgment | null>;

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

@@ -4,9 +4,13 @@ import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 import { resolvePrStatePath } from "./base.mjs";
 const FILE = "queue-removal-ack.json";
-/** The only removal reasons that indicate a CI-driven queue ejection. */
+/**
+ * The only removal reason that indicates a CI-driven queue ejection. GitHub sends lowercase raw
+ * strings; observed values also include `merged`, `merge_conflict`, `invalid_merge_commit`, and
+ * `stack_invalidated`, none of which a requeue can recover.
+ */
 export function isCiQueueRemovalReason(reason) {
-    return reason === "CI_FAILURE" || reason === "MERGE_QUEUE_POLICY_CHECK_FAILURE";
+    return reason === "failed_checks";
 }
 /** Missing, unreadable, or malformed acknowledgment state is treated as absent. */
 export async function readQueueRemovalAcknowledgment(key) {

package/bin/types/github.d.mts

@@ -6,6 +6,19 @@ export type CheckStatus = "COMPLETED" | "IN_PROGRESS" | "PENDING" | "QUEUED" | "
 export type MergeableState = "CONFLICTING" | "MERGEABLE" | "UNKNOWN";
 export type MergeStateStatus = "BEHIND" | "BLOCKED" | "CLEAN" | "DIRTY" | "DRAFT" | "HAS_HOOKS" | "UNKNOWN" | "UNSTABLE";
 export type ReviewDecision = "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | null;
+/** Raw GitHub fields for a merged PR whose head is this PR's current base. */
+export interface MergedBasePullRequest {
+    number: number;
+    url: string;
+    state: "MERGED";
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    mergedAt: string;
+    headRepository: {
+        nameWithOwner: string;
+    };
+}
 export type AuthorType = "User" | "Bot" | "Unknown";
 type RepositoryPermission = "NONE" | "READ" | "TRIAGE" | "WRITE" | "MAINTAIN" | "ADMIN";
 /** Raw GitHub viewer fields used to gate remote actions. */
@@ -146,6 +159,10 @@ export interface BatchPrData extends BatchPrMergeFields {
      * that signal is unavailable; queue-removal freshness then uses committer time.
      */
     headPushedAtUnix?: number;
+    /** Unix times of the last 10 merge-queue removals, oldest first. */
+    mergeQueueRemovalTimesUnix?: number[];
+    /** Unix time of the latest head-ref force-push, when GitHub reports one. */
+    headForcePushedAtUnix?: number;
     headRefName: string;
     /** `"owner/name"` of the head repository; null when the fork has been deleted. */
     headRepoWithOwner: string | null;

package/bin/types/iterate.d.mts

@@ -1,6 +1,6 @@
 import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment, RuleAutoResolveReport } from "./report.mts";
 import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
-import type { BranchProtection, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
+import type { BranchProtection, MergeStateStatus, MergedBasePullRequest, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
 import type { MergeRequirements, StackDraftHold } from "./merge-requirements.mts";
 import type { EscalateDetails } from "./escalate.mts";
 import type { MergeCommandPlan } from "./merge-action.mts";
@@ -34,6 +34,8 @@ export interface IterateResultBase {
      * PR base, so the dirty state is against the stack trunk rather than that base.
      */
     stackTrunkConflict?: string;
+    /** Merged PRs whose exact head commit and repository match this conflicting PR's base. */
+    mergedBasePullRequests?: MergedBasePullRequest[];
     /** Null when no classic protection rule exists or the base ref is unavailable. */
     branchProtection: BranchProtection | null;
     mergeRequirements?: MergeRequirements;

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

@@ -10,6 +10,8 @@ export interface MergeQueueReport {
     checksIncomplete?: true;
     /** The current PR head is not a parent of the removed synthetic queue commit. */
     headUpdatedAfterRemoval?: true;
+    /** Queue removals since the current head reached the PR; emitted only when above 1. */
+    removalsOnHead?: number;
     /** The caller acknowledged this exact native-stack removal on the current head. */
     removalAcknowledged?: true;
 }

package/package.json

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

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

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

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

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

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

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

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

@@ -73,3 +73,4 @@ When a step says `Playbook: "<name>"`, read that file once and apply it before t
 - [Shepherd Journal](references/journal.md)
 - [Branch update](references/branch-update.md)
 - [Stack merge](references/stack-merge.md)
+- [Merge queue ejection](references/merge-queue-ejection.md)

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

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

package/plugins/pr-shepherd/skills/pr-shepherd/references/merge-queue-ejection.md

@@ -0,0 +1,17 @@
+# Merge queue ejection
+
+Apply when a step says `Playbook: "Merge queue ejection"`. The `**queue removal**` header names the queue commit. That commit combined the PR head with the base and any entries queued ahead of it, so a failure there may come from this PR, the base, another entry, or a flake. Do not requeue without triage. After triage, continue with the remaining numbered steps; iterate only at the final step.
+
+1. Update the PR head from the latest base following the repository's branch-update convention. On a native stack, use the printed stack update route instead. Reproduce the failing step on the updated head.
+2. If the failure belongs to this PR, fix it. The printed push step commits and pushes the fix.
+3. If the failure does not reproduce and the update changed the head, the printed push step pushes it (`gh stack push` on a native stack). Never run a printed `requeue:` or `acknowledge queue removal:` command after a push. Shepherd prints a fresh queue command once the new head is READY.
+4. If the failure comes from the base itself, do not requeue or acknowledge it. If a Shepherd Journal step is printed, record the finding with it. Make no change. The unchanged failure escalates through the stall timeout.
+5. If the removal reason suggests a person dequeued the PR, skip the step 1 update unless a conflict step requires it. Fix a failure that belongs to this PR; otherwise make no change. Never enqueue.
+6. If the step says no queue command was printed, never enqueue. A failure that does not reproduce follows step 4. Shepherd prints no queue command once the same head was already removed before (`removals on this head` in the header), so a flaky failure is not retried indefinitely.
+7. Otherwise, run the printed `requeue:` or `acknowledge queue removal:` command exactly as printed, and only if all of these hold:
+   - the head did not change;
+   - no code changed;
+   - no other blocker remains;
+   - the logs or the check's details page show a transient failure, or a failure caused by another entry in the same queue group.
+8. If gh reports auto-merge is disabled instead of adding the PR to the queue, run the `requeue API fallback:` command. Both requeue commands require the observed PR head SHA. If the head changed, iterate for a fresh command.
+9. After `acknowledge queue removal:`, finish this one-PR session so it validates current source CI and records its READY receipt. Then return to the aggregate `--stack` selector with its original options. In merge mode it verifies lower-layer readiness before merging. Never enqueue or merge a stack layer directly.