pr-shepherd 0.54.0 → 0.55.0

package/bin/commands/check.mjs

@@ -2,6 +2,7 @@ import { fetchPrBatch } from "../github/batch.mjs";
 import { queueRemovalAppliesToHead } from "../github/queue-removal-freshness.mjs";
 import { storePrFingerprint } from "../state/pr-fingerprint.mjs";
 import { tryReuseFingerprintReport } from "./check-fingerprint.mjs";
+import { collectUnreportedRequired, refreshCachedUnreported } from "./check-unreported.mjs";
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
@@ -17,7 +18,7 @@ import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs"
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, } from "../comments/review-visibility.mjs";
-import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
+import { applySuppressedRuleAutoResolve } from "./rule-auto-resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./iterate/thread-mutation-routing.mjs";
@@ -37,7 +38,7 @@ export async function runCheck(opts) {
     if (reuseFingerprint) {
         const cached = await tryReuseFingerprintReport(prNumber, repo, stateKey, config);
         if (cached)
-            return cached;
+            return refreshCachedUnreported(cached, repo);
     }
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
     const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
@@ -67,8 +68,10 @@ export async function runCheck(opts) {
     // 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 the head's committer time is later than the removal. The raw removal fields still
-    // render in the merge-queue header regardless of this flag.
+    // 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;
     const headUpdatedAfterRemoval = Boolean(latestRemoval &&
         !queueRemovalAppliesToHead({
@@ -76,6 +79,9 @@ export async function runCheck(opts) {
             headOid: batchData.headRefOid,
             ...(headCommittedAtUnix !== undefined &&
                 headCommittedAtUnix !== null && { headCommittedAtUnix }),
+            ...(batchData.headPushedAtUnix !== undefined && {
+                headPushedAtUnix: batchData.headPushedAtUnix,
+            }),
             removedAtUnix: latestRemoval.createdAtUnix,
         }));
     const queueRawChecks = batchData.isInMergeQueue
@@ -154,14 +160,23 @@ export async function runCheck(opts) {
             visibleChangesRequestedIds.has(review.id));
     }).length;
     const approvedReviews = approvedReviewVisibility.visible;
-    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
+    const unreported = await collectUnreportedRequired({
+        batchData,
+        checks: allChecks,
+        suites: result.headWorkflowSuites ?? [],
+        owner: repo.owner,
+        name: repo.name,
+        pr: prNumber,
+        relevantEvents: config.checks.ciTriggerEvents,
+    });
+    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount, unreported.hasUnreportedRequired);
     // Resolve any pending mergeability refresh (and the resulting MERGED/CLOSED short-circuit)
     // before deciding what to persist below — deferWhileQueued must see the same final,
     // possibly-refreshed mergeStatus that commands/iterate/index.mts acts on, not the pre-refresh
     // snapshot. A conflict newly discovered by this REST read is exactly the kind of check-driven
     // signal that keeps a queued PR out of the deferral path.
     if (status === "READY" && !didRefreshMergeability) {
-        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount);
+        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount, unreported.hasUnreportedRequired);
         batchData = refreshed.batchData;
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
@@ -236,7 +251,13 @@ export async function runCheck(opts) {
         ruleAutoResolveCommentIds: partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize === true),
         ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize === true),
     };
-    const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(authorizedPartition, opts.autoMinimizeSuppressed);
+    const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, autoResolved, autoMinimized, autoResolveErrors, errorReasons, } = await applySuppressedRuleAutoResolve({
+        enabled: opts.autoMinimizeSuppressed === true,
+        partition: authorizedPartition,
+        batch: batchData,
+        prNumber,
+        repo,
+    });
     const visibleMutationThreadIds = new Set([...threadVisibility.activeThreads, ...threadVisibility.resolutionOnlyThreads].map((thread) => thread.id));
     const ruleAutoResolveThreadIds = [
         ...authorizedRuleAutoResolveThreadIds,
@@ -254,11 +275,13 @@ export async function runCheck(opts) {
         pr: prNumber,
         nodeId: batchData.nodeId,
         headSha: batchData.headRefOid,
+        headRefName: unreported.headRefName,
         repo: `${repo.owner}/${repo.name}`,
         ...(batchData.viewerAuthorization && { viewerAuthorization: batchData.viewerAuthorization }),
         status,
         baseBranch: batchData.baseRefName,
         ...(batchData.baseRefOid && { baseRefOid: batchData.baseRefOid }),
+        ...(result.headCheckSuitesEmpty && { headCheckSuitesEmpty: true }),
         mergeStatus,
         checks: {
             passing: merged.passing,
@@ -275,8 +298,9 @@ export async function runCheck(opts) {
         threads: {
             actionable: threadVisibility.activeThreads,
             resolutionOnly: threadVisibility.resolutionOnlyThreads,
-            autoResolved: [],
-            autoResolveErrors: [],
+            autoResolved,
+            autoResolveErrors,
+            ...(errorReasons.length > 0 && { autoResolveErrorReasons: errorReasons }),
             firstLook: threadVisibility.firstLookThreads,
             ...(ruleAutoResolveThreadIds.length > 0
                 ? { ruleAutoResolveIds: ruleAutoResolveThreadIds }
@@ -286,6 +310,7 @@ export async function runCheck(opts) {
             actionable: visibleCommentClassification.actionable,
             minimizeIds: [...visibleCommentClassification.minimizeIds, ...ruleAutoResolveCommentIds],
             firstLook: firstLookComments,
+            ...(autoMinimized.length > 0 && { autoMinimized }),
         },
         changesRequestedReviews,
         reviewSummaries: seenSummaries,
@@ -296,6 +321,9 @@ export async function runCheck(opts) {
             ? { ruleAutoResolveReviewSummaryIds }
             : undefined),
         branchProtection: batchData.branchProtection,
+        ...(batchData.allowedMergeMethods && {
+            allowedMergeMethods: batchData.allowedMergeMethods,
+        }),
         activity: batchData.activity,
         ...(hasQueueState && {
             mergeQueue: {
@@ -315,38 +343,17 @@ export async function runCheck(opts) {
                 ...(headUpdatedAfterRemoval && { headUpdatedAfterRemoval: true }),
             },
         }),
+        ...(unreported.unreportedRequiredChecks && {
+            unreportedRequiredChecks: unreported.unreportedRequiredChecks,
+        }),
+        ...(unreported.trunkBehindBy !== undefined && { trunkBehindBy: unreported.trunkBehindBy }),
+        ...(unreported.actionsWorkflowInProgress && {
+            actionsWorkflowInProgress: true,
+        }),
+        ...(unreported.stackBottomPr !== undefined && { stackBottomPr: unreported.stackBottomPr }),
     };
     if (result.fingerprint) {
         await storePrFingerprint(stateKey, result.fingerprint, report, config);
     }
     return report;
 }
-async function remainingRuleAutoResolveIds(partition, autoMinimizeSuppressed = false) {
-    const consumedIds = autoMinimizeSuppressed
-        ? await selfApplySuppressedRuleAutoResolve(partition)
-        : { minimized: new Set(), resolvedThreads: new Set() };
-    return {
-        threadIds: partition.ruleAutoResolveThreadIds.filter((id) => !consumedIds.resolvedThreads.has(id)),
-        commentIds: partition.ruleAutoResolveCommentIds.filter((id) => !consumedIds.minimized.has(id)),
-        reviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => !consumedIds.minimized.has(id)),
-    };
-}
-async function selfApplySuppressedRuleAutoResolve(partition) {
-    const minimizeIds = [
-        ...partition.ruleAutoResolveCommentIds.filter((id) => partition.suppressedCommentIds.has(id)),
-        ...partition.ruleAutoResolveReviewSummaryIds.filter((id) => partition.suppressedReviewSummaryIds.has(id)),
-    ];
-    const threadIds = partition.ruleAutoResolveThreadIds.filter((id) => partition.suppressedThreadIds.has(id));
-    const [minimized, resolved] = await Promise.all([
-        minimizeIds.length > 0
-            ? autoMinimizeComments(minimizeIds)
-            : Promise.resolve({ minimized: [], errors: [] }),
-        threadIds.length > 0
-            ? autoResolveThreads(threadIds)
-            : Promise.resolve({ resolved: [], errors: [] }),
-    ]);
-    return {
-        minimized: new Set(minimized.minimized),
-        resolvedThreads: new Set(resolved.resolved),
-    };
-}

package/bin/commands/iterate/base.mjs

@@ -1,5 +1,7 @@
+import { ruleAutoResolveFromReport } from "../rule-auto-resolve-format.mjs";
 import { buildActiveChecks, buildRelevantChecks, buildSummary, buildSuppressedCheckFields, } from "./helpers.mjs";
 export function buildIterateBase(report, readyState) {
+    const ruleAutoResolve = ruleAutoResolveFromReport(report);
     return {
         pr: report.pr,
         repo: report.repo,
@@ -21,6 +23,13 @@ export function buildIterateBase(report, readyState) {
         ...buildSuppressedCheckFields(report),
         activity: report.activity,
         mergeQueue: report.mergeQueue,
+        ...(report.unreportedRequiredChecks &&
+            report.unreportedRequiredChecks.length > 0 && {
+            unreportedRequiredChecks: report.unreportedRequiredChecks,
+        }),
+        ...(report.trunkBehindBy !== undefined &&
+            report.trunkBehindBy > 0 && { trunkBehindBy: report.trunkBehindBy }),
         ...(report.fingerprintReused === true && { fingerprintReused: true }),
+        ...(ruleAutoResolve && { ruleAutoResolve }),
     };
 }

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

@@ -0,0 +1,18 @@
+export declare function conflictingHeadCiNote(input: {
+    hasConflicts: boolean;
+    headCheckSuitesEmpty: boolean;
+    checkRunCount: number;
+    /** Unix seconds when Shepherd first saw this head. Omit when that time is unknown. */
+    firstSeenAtUnix: number | null | undefined;
+    nowMs: number;
+}): string | undefined;
+export declare function countReportedChecks(checks: {
+    passing: readonly unknown[];
+    failing: readonly unknown[];
+    inProgress: readonly unknown[];
+    skipped: readonly unknown[];
+    filtered: readonly unknown[];
+    ignored?: readonly unknown[];
+}): number;
+/** Place the missing-CI note with the conflict step, ahead of later repair lines. */
+export declare function insertConflictingHeadCiNote(instructions: string[], note: string | undefined): void;

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

@@ -0,0 +1,32 @@
+/** How long a conflicting head may sit with no CI before Shepherd says none will start. */
+const CONFLICTING_HEAD_CI_GRACE_MS = 2 * 60 * 1000;
+const NO_CI_NOTE = "GitHub did not start pull_request workflows for this conflicting head: no check suites or workflow runs have appeared for at least 2 minutes. Missing CI is a consequence of the conflict, not an outage, and pushing this same head again will not start them.";
+export function conflictingHeadCiNote(input) {
+    if (!input.hasConflicts || !input.headCheckSuitesEmpty || input.checkRunCount > 0) {
+        return undefined;
+    }
+    if (typeof input.firstSeenAtUnix !== "number")
+        return undefined;
+    const ageMs = input.nowMs - input.firstSeenAtUnix * 1000;
+    if (!Number.isFinite(ageMs) || ageMs < CONFLICTING_HEAD_CI_GRACE_MS)
+        return undefined;
+    return NO_CI_NOTE;
+}
+export function countReportedChecks(checks) {
+    return (checks.passing.length +
+        checks.failing.length +
+        checks.inProgress.length +
+        checks.skipped.length +
+        checks.filtered.length +
+        (checks.ignored?.length ?? 0));
+}
+/** Place the missing-CI note with the conflict step, ahead of later repair lines. */
+export function insertConflictingHeadCiNote(instructions, note) {
+    if (!note)
+        return;
+    const conflictAt = instructions.findIndex((step) => step.includes("merge conflicts"));
+    if (conflictAt >= 0)
+        instructions.splice(conflictAt + 1, 0, note);
+    else
+        instructions.unshift(note);
+}

package/bin/commands/iterate/escalate.mjs

@@ -240,6 +240,10 @@ export function buildEscalateSuggestion(triggers, detail) {
         const duration = detail ?? "60 minutes";
         return `No progress detected for ${duration} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
     }
+    if (triggers.includes("required-checks-unreported")) {
+        const names = detail ? ` (${detail})` : "";
+        return `Required checks are still unreported after one close/reopen of this head${names}. Another reopen will not create a job the workflow does not emit. Path filters are the usual cause.`;
+    }
     if (triggers.includes("stall-state-unavailable")) {
         const reason = detail ?? "unknown error";
         return `The stall timer could not be saved (${reason}). Fix PR_SHEPHERD_STATE_DIR or the directory permissions, then resume. Automated polling is paused because a stuck loop would not be detected.`;

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

@@ -8,6 +8,9 @@ import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./thre
 import { buildFixInstructions } from "./render.mjs";
 import { buildReleasedBlockerInstruction } from "./check-instructions.mjs";
 import { buildNativeStackLayerRebase } from "./native-stack-rebase.mjs";
+import { lookupUpperLayerTrunkConflict } from "./stack-trunk-conflict.mjs";
+import { conflictingHeadCiNote, countReportedChecks, insertConflictingHeadCiNote, } from "./conflicting-head-ci.mjs";
+import { conflictingHeadFirstSeenUnix } from "../../state/conflicting-head-seen.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
@@ -282,9 +285,21 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    const headRef = report.headSha;
+    // 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({
+            owner: repoOwner,
+            name: repoName,
+            pr: prNumber,
+            headRef,
+            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 }, report.mergeStatus.mergeRequirements?.stack)
+        ? 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);
     if (failingAgentChecks.some((check) => releasedCheckNames.has(check.name))) {
@@ -296,9 +311,23 @@ export async function handleFixCode(ctx) {
     if (repairInstructions && repairInstructions.length > 0) {
         instructions.unshift(...repairInstructions);
     }
+    const checkRunCount = countReportedChecks(report.checks);
+    const suitesEmpty = report.headCheckSuitesEmpty === true;
+    const nowMs = Date.now();
+    const firstSeenAtUnix = hasConflicts && suitesEmpty && checkRunCount === 0 && report.headSha
+        ? await conflictingHeadFirstSeenUnix({ owner: repoOwner, repo: repoName, pr: prNumber }, report.headSha, nowMs)
+        : undefined;
+    insertConflictingHeadCiNote(instructions, conflictingHeadCiNote({
+        hasConflicts,
+        headCheckSuitesEmpty: suitesEmpty,
+        checkRunCount,
+        firstSeenAtUnix,
+        nowMs,
+    }));
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,
+        ...(trunkConflict && { stackTrunkConflict: trunkConflict.trunk }),
         action: "fix_code",
         fix: {
             threads,

package/bin/commands/iterate/index.mjs

@@ -18,6 +18,7 @@ import { markReadyIfAuthorized } from "./mark-ready.mjs";
 import { withIterateApiUsage } from "./run.mjs";
 import { fetchRawSummaryPr } from "../../github/poll-summary.mjs";
 import { summarizePollSummaryPr } from "../../github/poll-summary-projector.mjs";
+import { annotationProbeUnavailable } from "../../github/poll-summary-annotation-probe.mjs";
 import { fingerprintRawSummaryPr } from "../../github/poll-summary-fingerprint.mjs";
 import { currentQueueRemovalEvent } from "../../github/poll-summary-queue-removal.mjs";
 import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
@@ -25,6 +26,7 @@ import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyR
 import { stackDraftHold } from "./parent-first.mjs";
 import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 import { annotateBlockedWait, resolveCheckBlockerGate } from "./check-blocker-gate.mjs";
+import { buildUnreportedFixResult, planUnreportedRequired } from "./unreported-required.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -122,6 +124,16 @@ async function runIterateCore(opts) {
     // readiness evidence, so a rerun (e.g. with --merge) does not wait again.
     const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName, { headSha, alreadyElapsed: receiptCurrent });
     const base = buildIterateBase(reportForWork, readyState);
+    const unreportedPlan = await planUnreportedRequired({
+        report,
+        base,
+        stateKey: stallKey,
+        headSha,
+        otherAutonomousWork: hasActionableWork || staleAncestry !== null,
+    });
+    if (unreportedPlan.escalate)
+        return unreportedPlan.escalate;
+    const unreportedRepair = unreportedPlan.repairInstructions ?? [];
     // Checks (including merge-queue synthetic-commit checks) and hard conflicts are signals
     // GitHub itself is already acting on — the queue will eject the PR for these regardless of
     // what Shepherd does, so they always surface immediately. Only review threads/comments/
@@ -148,9 +160,36 @@ async function runIterateCore(opts) {
             surfacedApprovals,
             botUsernames,
             releasedCheckNames: blockerGate?.releasedNames,
+            ...((unreportedRepair.length > 0 || staleAncestry !== null) && {
+                repairInstructions: [...unreportedRepair, ...(staleAncestry?.instructions ?? [])],
+            }),
+            ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
+        });
+    }
+    if (unreportedRepair.length > 0 && staleAncestry) {
+        return handleFixCode({
+            base,
+            report: reportForWork,
+            opts: { ...opts, prNumber, neverCancelRuns },
+            headSha,
+            stallKey,
+            prNumber,
+            stallTimeoutSeconds,
+            repoOwner,
+            repoName,
+            reviewSummaryIds,
+            firstLookSummaries,
+            editedSummaries,
+            surfacedApprovals,
+            botUsernames,
+            releasedCheckNames: blockerGate?.releasedNames,
+            repairInstructions: [...unreportedRepair, ...staleAncestry.instructions],
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
+    if (unreportedRepair.length > 0) {
+        return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, buildUnreportedFixResult(base, report, unreportedRepair), reportForWork, reviewSummaryIds), blockerGate);
+    }
     const mergeStateResult = await handleActiveMergeState({
         enabled: opts.merge,
         active: activeMerge,
@@ -182,7 +221,7 @@ async function runIterateCore(opts) {
             surfacedApprovals,
             botUsernames,
             releasedCheckNames: blockerGate?.releasedNames,
-            repairInstructions: staleAncestry.instructions,
+            repairInstructions: [...unreportedRepair, ...staleAncestry.instructions],
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
@@ -220,6 +259,17 @@ async function runIterateCore(opts) {
             log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
         };
     }
+    if (isCleanReadyState &&
+        readyState.isReady &&
+        !readyState.shouldCancel &&
+        readyState.remainingSeconds > 0) {
+        await clearStallState(stallKey);
+        return {
+            ...base,
+            action: "ready",
+            log: `READY: PR #${base.pr} is ready — ${readyState.remainingSeconds}s of ready-delay remaining — ${buildWaitLog(base).slice("WAIT: ".length)}`,
+        };
+    }
     const hold = stackDraftHold(report, autoMarkReady);
     const wait = {
         ...base,
@@ -238,14 +288,19 @@ async function recordReadyReceipt(key, report) {
         return false;
     try {
         const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
-        const fingerprint = fingerprintRawSummaryPr(raw);
-        if (fingerprint === null ||
+        if (fingerprintRawSummaryPr(raw) === null ||
             raw.state !== "OPEN" ||
             raw.isDraft ||
             raw.headRefOid !== report.headSha ||
             raw.baseRefOid !== report.baseRefOid)
             return false;
+        // Summarize hydrates annotation totals onto the snapshot before the stored hash.
         const summary = await summarizePollSummaryPr(raw, { owner: key.owner, name: key.repo }, { stackPrNumber: report.pr });
+        if (annotationProbeUnavailable(raw))
+            return false;
+        const fingerprint = fingerprintRawSummaryPr(raw);
+        if (fingerprint === null)
+            return false;
         if (!isCurrentSummaryReady(raw, summary.checks ?? {}, summary.review ?? {}))
             return false;
         const removalEvent = currentQueueRemovalEvent(raw);
@@ -290,6 +345,17 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork) {
     }
     try {
         const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        const summary = await summarizePollSummaryPr(raw, { owner: key.owner, name: key.repo }, { stackPrNumber: report.pr });
+        if (annotationProbeUnavailable(raw)) {
+            const sameHead = raw.headRefOid === report.headSha;
+            const sameBase = retainQueuedReceipt || raw.baseRefOid === report.baseRefOid;
+            const stillReady = isCurrentSummaryReady(raw, summary.checks ?? {}, summary.review ?? {});
+            if (!sameHead || !sameBase || !stillReady) {
+                await clearReadyReceipt(key);
+                return false;
+            }
+            return true;
+        }
         // Queue predecessors can advance the target branch without changing this
         // PR's source. Compare against the receipt's base only while both fresh
         // views still place the PR in the queue.

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

@@ -1,6 +1,6 @@
 import { clearStallState } from "../../state/iterate-stall.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
-import { buildMergeCommandPlan } from "./merge.mjs";
+import { buildMergeCommandPlan, unavailableMergeResult } from "./merge.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { inlineCode } from "../../util/markdown.mjs";
@@ -49,17 +49,17 @@ export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
         return buildStackedRouteResult(base, report, stack);
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
-    return {
-        ...base,
-        action: "merge",
-        merge: buildMergeCommandPlan({
-            pr: report.pr,
-            repo: report.repo,
-            nodeId: report.nodeId,
-            headSha: report.headSha ?? "unknown",
-            queue,
-        }),
-    };
+    const plan = buildMergeCommandPlan({
+        pr: report.pr,
+        repo: report.repo,
+        nodeId: report.nodeId,
+        headSha: report.headSha ?? "unknown",
+        queue,
+        ...(report.allowedMergeMethods && { allowedMergeMethods: report.allowedMergeMethods }),
+    });
+    if ("unavailable" in plan)
+        return unavailableMergeResult(base, report, plan.unavailable);
+    return { ...base, action: "merge", merge: plan };
 }
 /** Raw counts of non-CI actionable work held back for one queued-PR wait tick. Omitted (all zero) when empty. */
 function buildDeferredWork(input) {

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

@@ -1,13 +1,23 @@
-import type { MergeCommandPlan } from "../../types.mts";
+import { type MergeMethod } from "../../config/merge-method.mts";
+import type { IterateResult, IterateResultBase, MergeCommandPlan } from "../../types.mts";
 interface MergePlanInput {
     pr: number;
     repo: string;
     nodeId: string;
     headSha: string;
     queue: boolean;
+    /** Omitted when the batch did not select repository merge settings. */
+    allowedMergeMethods?: readonly MergeMethod[];
 }
-export declare function buildMergeCommandPlan(input: MergePlanInput): MergeCommandPlan;
+export interface MergeMethodUnavailable {
+    unavailable: string;
+}
+export declare function buildMergeCommandPlan(input: MergePlanInput): MergeCommandPlan | MergeMethodUnavailable;
 export declare function renderMergeCommand(command: {
     argv: string[];
 }): string;
+export declare function unavailableMergeResult(base: IterateResultBase, report: {
+    pr: number;
+    repo: string;
+}, unavailable: string): IterateResult;
 export {};

package/bin/commands/iterate/merge.mjs

@@ -1,6 +1,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 { 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) {
     const base = [
@@ -32,9 +35,17 @@ export function buildMergeCommandPlan(input) {
             },
         };
     }
-    const configuredArgs = loadConfig().merge?.commandArgs ?? [];
+    const mergeConfig = loadConfig().merge;
+    const configuredArgs = mergeConfig?.commandArgs ?? [];
+    const decision = chooseMergeMethod({
+        allowed: input.allowedMergeMethods,
+        configured: configuredMergeMethod(mergeConfig ?? {}),
+        fallback: "merge",
+    });
+    if ("unavailable" in decision)
+        return decision;
     const hasStrategy = findMergeStrategies(configuredArgs).length > 0;
-    const commandArgs = hasStrategy ? configuredArgs : [...configuredArgs, "--merge"];
+    const commandArgs = hasStrategy ? configuredArgs : [...configuredArgs, `--${decision.method}`];
     return {
         mode: "auto",
         command: { argv: [...base, "--auto", ...commandArgs] },
@@ -44,3 +55,22 @@ export function buildMergeCommandPlan(input) {
 export function renderMergeCommand(command) {
     return renderShellCommand(command.argv);
 }
+export function unavailableMergeResult(base, report, unavailable) {
+    const escalateBase = {
+        triggers: ["merge-method-unavailable"],
+        unresolvedThreads: [],
+        ambiguousComments: [],
+        changesRequestedReviews: [],
+        suggestion: unavailable,
+    };
+    return {
+        ...base,
+        action: "escalate",
+        escalate: {
+            ...escalateBase,
+            humanMessage: buildEscalateHumanMessage(escalateBase, formatPrUrl(report.repo, report.pr), {
+                merge: true,
+            }),
+        },
+    };
+}

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

@@ -7,6 +7,8 @@ export type NativeStackRebaseStart = {
     parentBranch: string;
 } | {
     bottomPr: number;
+} | {
+    trunk: string;
 };
 /**
  * One gh-stack rebase step. A native stack layer must not be rebased or merged from its base
@@ -22,12 +24,16 @@ export declare function buildNativeStackRebaseInstruction(repo: string, stackNum
  * workflow keeps failing); undefined outside a stack.
  * A layer whose PR targets the stack's trunk (`stack.baseRefName`) is the bottom open layer —
  * position 1, or a higher layer GitHub retargeted after every layer below it merged. Any other
- * layer is an upper layer whose parent is its own PR base branch.
+ * layer is an upper layer whose parent is its own PR base branch. `trunkConflict` means that
+ * upper layer already contains its parent, so the rebase starts at the bottom open layer.
  */
 export declare function buildNativeStackLayerRebase(repo: string, pr: {
     number: number;
     baseBranch: string;
-}, stack: StackStatus | undefined): string | undefined;
+}, stack: StackStatus | undefined, trunkConflict?: {
+    trunk: string;
+    bottomPr?: number;
+}): string | undefined;
 /** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
 export declare function buildConflictInstruction(stackRebase: string | undefined): string;
 /** Push a conflict resolution or branch refresh: one branch, or the whole rewritten native stack. */

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

@@ -12,7 +12,9 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
             `check out the parent stack branch \`${start.parentBranch}\``,
             "gh stack rebase --upstack --no-trunk",
         ]
-        : [`check out the head branch of PR #${start.bottomPr}`, "gh stack rebase"];
+        : "bottomPr" in start
+            ? [`check out the head branch of PR #${start.bottomPr}`, "gh stack rebase"]
+            : [`check out the bottom open layer whose base is \`${start.trunk}\``, "gh stack rebase"];
     const prepare = `if \`gh stack\` does not track stack #${stackNumber} locally, import it with \`gh stack checkout ${stackNumber}\`, then confirm every layer's local branch is at its PR's head commit — a stale local layer would overwrite that PR's newer commits on push`;
     return `From a clean checkout of \`${repo}\`, ${prepare}. Then ${checkout} and run \`${command}\`; if it stops on a conflict, resolve it and run \`gh stack rebase --continue\`.`;
 }
@@ -21,12 +23,20 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
  * workflow keeps failing); undefined outside a stack.
  * A layer whose PR targets the stack's trunk (`stack.baseRefName`) is the bottom open layer —
  * position 1, or a higher layer GitHub retargeted after every layer below it merged. Any other
- * layer is an upper layer whose parent is its own PR base branch.
+ * layer is an upper layer whose parent is its own PR base branch. `trunkConflict` means that
+ * upper layer already contains its parent, so the rebase starts at the bottom open layer.
  */
-export function buildNativeStackLayerRebase(repo, pr, stack) {
+export function buildNativeStackLayerRebase(repo, pr, stack, trunkConflict) {
     if (!stack)
         return undefined;
-    return buildNativeStackRebaseInstruction(repo, stack.number, pr.baseBranch === stack.baseRefName ? { bottomPr: pr.number } : { parentBranch: pr.baseBranch });
+    const start = trunkConflict
+        ? trunkConflict.bottomPr !== undefined
+            ? { bottomPr: trunkConflict.bottomPr }
+            : { trunk: trunkConflict.trunk }
+        : pr.baseBranch === stack.baseRefName
+            ? { bottomPr: pr.number }
+            : { parentBranch: pr.baseBranch };
+    return buildNativeStackRebaseInstruction(repo, stack.number, start);
 }
 /** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
 export function buildConflictInstruction(stackRebase) {

package/bin/commands/iterate/stack-trunk-conflict.d.mts

@@ -0,0 +1,13 @@
+/** An upper layer already contains its parent, so the dirty state is against trunk. */
+export interface UpperLayerTrunkConflict {
+    trunk: string;
+    /** Open layer whose PR base is the trunk. Omitted when that layer is not on this page. */
+    bottomPr?: number;
+}
+export declare function lookupUpperLayerTrunkConflict(input: {
+    owner: string;
+    name: string;
+    pr: number;
+    headRef: string;
+    trunk: string;
+}): Promise<UpperLayerTrunkConflict | undefined>;