pr-shepherd 0.56.0 → 0.56.2

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

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

package/bin/commands/check-fingerprint.mjs

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

package/bin/commands/check.mjs

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

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

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

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

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

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

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

package/bin/commands/iterate/index.mjs

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

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

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

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

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

package/bin/commands/iterate/merge.mjs

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

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

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

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

@@ -0,0 +1,11 @@
+import { type RepoInfo } from "./client.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/**
+ * Overlay REST mergeability onto an open summary PR whose GraphQL snapshot is `UNKNOWN`, in place.
+ *
+ * GraphQL keeps reporting `UNKNOWN` while GitHub recomputes mergeability after the
+ * base moves; REST `GET /pulls/{n}` triggers that computation and usually answers
+ * `dirty` at once. Without this, a layer that just gained a conflict routes as
+ * pending until a later tick, matching `iterate`'s `refreshUnknownMergeability`.
+ */
+export declare function refreshUnknownSummaryMergeability(raw: RawSummaryPr, repo: RepoInfo): Promise<void>;

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

@@ -0,0 +1,23 @@
+import { getMergeableState } from "./client.mjs";
+/**
+ * Overlay REST mergeability onto an open summary PR whose GraphQL snapshot is `UNKNOWN`, in place.
+ *
+ * GraphQL keeps reporting `UNKNOWN` while GitHub recomputes mergeability after the
+ * base moves; REST `GET /pulls/{n}` triggers that computation and usually answers
+ * `dirty` at once. Without this, a layer that just gained a conflict routes as
+ * pending until a later tick, matching `iterate`'s `refreshUnknownMergeability`.
+ */
+export async function refreshUnknownSummaryMergeability(raw, repo) {
+    if (raw.state !== "OPEN")
+        return;
+    if (raw.mergeable !== "UNKNOWN" && raw.mergeStateStatus !== "UNKNOWN")
+        return;
+    const rest = await getMergeableState(raw.number, repo.owner, repo.name);
+    // REST can still be computing; keep a field GraphQL already knew rather than erase it.
+    if (rest.mergeable !== "UNKNOWN")
+        raw.mergeable = rest.mergeable;
+    if (rest.mergeStateStatus !== "UNKNOWN")
+        raw.mergeStateStatus = rest.mergeStateStatus;
+    if (rest.state !== undefined)
+        raw.state = rest.state;
+}

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

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

package/bin/github/poll-summary.mjs

@@ -2,6 +2,7 @@ import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { GitHubRequestError, isRetryableGraphQlResourceLimit, missingRepositoryError, } from "./errors.mjs";
 import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
+import { refreshUnknownSummaryMergeability } from "./poll-summary-mergeability.mjs";
 import { summarizePollSummaryPr } from "./poll-summary-projector.mjs";
 import { trunkRequiredContexts } from "./poll-summary-unreported.mjs";
 import { POLL_STACK_SUMMARY_QUERY, POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
@@ -52,8 +53,10 @@ async function fetchExplicitChunk(prs, repo) {
             throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
         return raw;
     });
-    for (const raw of rawPrs)
+    for (const raw of rawPrs) {
         await hydratePollSummaryChecks(raw, repo);
+        await refreshUnknownSummaryMergeability(raw, repo);
+    }
     return { prs: rawPrs, viewerCanAdminister: result.data.repository.viewerCanAdminister };
 }
 /**
@@ -64,8 +67,10 @@ async function fetchStackSummary(opts, repo) {
     const anchor = opts.stackPrNumber;
     const topology = await readStackTopology(anchor, repo);
     const { stackNumber, stackSize, viewerLogin, viewerCanAdminister, ordered, allowedMergeMethods } = await readStackSummary(anchor, repo, topology.stackSize);
-    for (const pr of ordered)
+    for (const pr of ordered) {
         await hydratePollSummaryChecks(pr, repo);
+        await refreshUnknownSummaryMergeability(pr, repo);
+    }
     const stackAncestry = stackAncestryGaps(ordered);
     const required = trunkRequiredContexts(ordered);
     return {

package/bin/mcp/server.mjs

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

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

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

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

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

package/bin/types/iterate.d.mts

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

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

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

package/package.json

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

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

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

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

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

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

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

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

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

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

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