pr-shepherd 0.53.1 → 0.54.1

package/bin/commands/check-annotations.mjs

@@ -1,4 +1,5 @@
-import { fetchCheckRunAnnotations, } from "../github/check-annotations.mjs";
+import { fetchCheckRunAnnotationsBatch } from "../github/check-annotations-batch.mjs";
+import { pollRateLimitRetryAfterMs } from "./poll-quota.mjs";
 function shouldFetchCheckAnnotations(check) {
     return check.id != null && check.status === "COMPLETED" && check.hasAnnotations === true;
 }
@@ -58,30 +59,39 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber,
     };
 }
 async function attachUnseenCheckAnnotations(checks, seenMap, prNumber, cacheOpts) {
-    const checksWithAnnotations = [];
-    for (const check of checks) {
-        // eslint-disable-next-line no-await-in-loop
-        checksWithAnnotations.push(await attachForCheck(check, seenMap, prNumber, cacheOpts));
-    }
-    return checksWithAnnotations;
-}
-async function attachForCheck(check, seenMap, prNumber, cacheOpts) {
-    if (check.id == null)
-        return check;
-    let annotations;
+    if (checks.length === 0)
+        return checks;
+    const ids = checks.flatMap((check) => (check.id == null ? [] : [check.id]));
+    let batch;
     try {
-        annotations = await fetchCheckRunAnnotations(check.id, cacheOpts);
+        batch = await fetchCheckRunAnnotationsBatch(ids, cacheOpts);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`pr-shepherd: annotation fetch failed for PR #${prNumber} check "${check.name}" (ignored): ${msg}\n`);
-        return check;
+        if (pollRateLimitRetryAfterMs(err) !== null)
+            throw err;
+        writeAnnotationFailureSummary(prNumber, ids.length, err);
+        return checks;
     }
-    const unseen = annotations.filter((a) => !seenMap.has(a.id));
+    const firstFailure = batch.failures[0];
+    if (firstFailure !== undefined) {
+        writeAnnotationFailureSummary(prNumber, batch.failures.length, firstFailure.error);
+    }
+    return checks.map((check) => withUnseenAnnotations(check, batch.annotations, seenMap));
+}
+function withUnseenAnnotations(check, annotations, seenMap) {
+    const fetched = check.id == null ? undefined : annotations.get(check.id);
+    if (fetched === undefined)
+        return check;
+    const unseen = fetched.filter((annotation) => !seenMap.has(annotation.id));
     if (unseen.length === 0)
         return check;
     return { ...check, annotations: unseen };
 }
+function writeAnnotationFailureSummary(prNumber, count, err) {
+    const noun = count === 1 ? "check" : "checks";
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`pr-shepherd: annotation fetch failed for ${count} ${noun} on PR #${prNumber} (ignored): ${message}\n`);
+}
 export function annotationMarkerBody(a) {
     return JSON.stringify({
         path: a.path,

package/bin/commands/check-blocker-ref.d.mts

@@ -0,0 +1,3 @@
+import type { CheckBlockerRef } from "../state/check-blockers.mts";
+/** Parse `--blocked-by`. Returns null for anything other than the four accepted forms. */
+export declare function parseBlockedByRef(raw: string): CheckBlockerRef | null;

package/bin/commands/check-blocker-ref.mjs

@@ -0,0 +1,50 @@
+const NAME = /^[A-Za-z0-9_.-]+$/;
+const SHORTHAND = /^(?:(issue):)?([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)#([1-9]\d*)$/;
+/** Parse `--blocked-by`. Returns null for anything other than the four accepted forms. */
+export function parseBlockedByRef(raw) {
+    const text = raw.trim();
+    const short = SHORTHAND.exec(text);
+    if (short?.[2] && short[3] && short[4]) {
+        const number = Number(short[4]);
+        if (!Number.isSafeInteger(number))
+            return null;
+        return {
+            owner: short[2],
+            name: short[3],
+            number,
+            kind: short[1] === "issue" ? "issue" : "pull",
+        };
+    }
+    return parseUrl(text);
+}
+function parseUrl(text) {
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return null;
+    if (url.hostname !== "github.com" && url.hostname !== "www.github.com")
+        return null;
+    if (url.search !== "" || url.hash !== "")
+        return null;
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (parts.length !== 4)
+        return null;
+    const [owner, name, type, num] = parts;
+    if (!owner || !name || !num || !NAME.test(owner) || !NAME.test(name))
+        return null;
+    if (!/^[1-9]\d*$/.test(num))
+        return null;
+    const number = Number(num);
+    if (!Number.isSafeInteger(number))
+        return null;
+    if (type === "pull")
+        return { owner, name, number, kind: "pull" };
+    if (type === "issues")
+        return { owner, name, number, kind: "issue" };
+    return null;
+}

package/bin/commands/check.mjs

@@ -259,6 +259,7 @@ export async function runCheck(opts) {
         status,
         baseBranch: batchData.baseRefName,
         ...(batchData.baseRefOid && { baseRefOid: batchData.baseRefOid }),
+        ...(result.headCheckSuitesEmpty && { headCheckSuitesEmpty: true }),
         mergeStatus,
         checks: {
             passing: merged.passing,

package/bin/commands/iterate/check-blocker-gate.d.mts

@@ -0,0 +1,18 @@
+import type { IterateResult } from "../../types.mts";
+export interface CheckBlockerGate {
+    deferredNames: ReadonlySet<string>;
+    releasedNames: ReadonlySet<string>;
+    /** `owner/name#number` for blockers that are still open. */
+    openBlockers: readonly string[];
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export declare function resolveCheckBlockerGate(key: StateKey, failing: readonly {
+    name: string;
+}[], mergeStatus?: string): Promise<CheckBlockerGate | null>;
+/** Append the open blocker to a WAIT log. Other actions are unchanged. */
+export declare function annotateBlockedWait(result: IterateResult, gate: CheckBlockerGate | null): IterateResult;
+export {};

package/bin/commands/iterate/check-blocker-gate.mjs

@@ -0,0 +1,115 @@
+import { graphql } from "../../github/client.mjs";
+import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
+import { clearCheckBlocker, formatCheckBlockerRef, readCheckBlockers, } from "../../state/check-blockers.mjs";
+const RATE_LIMIT = "cost limit nodeCount remaining resetAt used";
+const PULL_QUERY = `query CheckBlockerPull($owner: String!, $name: String!, $number: Int!) {
+  _shepherdRateLimit: rateLimit { ${RATE_LIMIT} }
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) { state merged }
+  }
+}`;
+const ISSUE_QUERY = `query CheckBlockerIssue($owner: String!, $name: String!, $number: Int!) {
+  _shepherdRateLimit: rateLimit { ${RATE_LIMIT} }
+  repository(owner: $owner, name: $name) {
+    issue(number: $number) { state }
+  }
+}`;
+/**
+ * Match failing checks to stored blockers. No records, or none of them name a
+ * failing check, skips GitHub. Rate-limit errors propagate; other lookup
+ * failures leave that check as a normal failure.
+ */
+/** Behind or conflicting branches still need the update-branch instruction. */
+const KEEP_RELEASED_STATUS = new Set(["BEHIND", "CONFLICTS", "DIRTY", "UNKNOWN"]);
+export async function resolveCheckBlockerGate(key, failing, mergeStatus) {
+    const records = await readCheckBlockers(key);
+    if (records.length === 0 || failing.length === 0)
+        return null;
+    const failingNames = new Set(failing.map((check) => check.name));
+    const matched = records.filter((record) => failingNames.has(record.checkName));
+    if (matched.length === 0)
+        return null;
+    const lookups = new Map();
+    for (const record of matched) {
+        const id = blockerKey(record.blocker);
+        if (lookups.has(id))
+            continue;
+        lookups.set(id, await lookupBlocker(record.blocker));
+    }
+    const deferredNames = new Set();
+    const releasedNames = new Set();
+    const openBlockers = [];
+    const seen = new Set();
+    for (const record of matched) {
+        const status = lookups.get(blockerKey(record.blocker));
+        if (status === "deferred") {
+            deferredNames.add(record.checkName);
+            const label = formatCheckBlockerRef(record.blocker);
+            if (!seen.has(label)) {
+                seen.add(label);
+                openBlockers.push(label);
+            }
+        }
+        else if (status === "released") {
+            if (mergeStatus !== undefined && !KEEP_RELEASED_STATUS.has(mergeStatus)) {
+                // The branch is already current, so update-branch would no-op and a
+                // later unrelated failure must be a normal check again.
+                await clearCheckBlocker(key, record.checkName);
+            }
+            else {
+                releasedNames.add(record.checkName);
+            }
+        }
+    }
+    if (deferredNames.size === 0 && releasedNames.size === 0)
+        return null;
+    return { deferredNames, releasedNames, openBlockers };
+}
+/** Append the open blocker to a WAIT log. Other actions are unchanged. */
+export function annotateBlockedWait(result, gate) {
+    if (result.action !== "wait" || gate === null || gate.openBlockers.length === 0)
+        return result;
+    const note = `blocked by ${gate.openBlockers.join(", ")}`;
+    if (result.log.includes(note))
+        return result;
+    return { ...result, log: `${result.log} — ${note}` };
+}
+async function lookupBlocker(blocker) {
+    try {
+        const vars = { owner: blocker.owner, name: blocker.name, number: blocker.number };
+        if (blocker.kind === "issue") {
+            const { data } = await graphql(ISSUE_QUERY, vars);
+            const issue = data.repository?.issue;
+            if (!issue)
+                return ignore(blocker, "not found");
+            if (issue.state === "OPEN")
+                return "deferred";
+            if (issue.state === "CLOSED")
+                return "released";
+            return ignore(blocker, `unexpected state ${issue.state}`);
+        }
+        const { data } = await graphql(PULL_QUERY, vars);
+        const pull = data.repository?.pullRequest;
+        if (!pull)
+            return ignore(blocker, "not found");
+        if (pull.state === "OPEN" && pull.merged !== true)
+            return "deferred";
+        if (pull.state === "MERGED" || pull.state === "CLOSED" || pull.merged === true) {
+            return "released";
+        }
+        return ignore(blocker, `unexpected state ${pull.state}`);
+    }
+    catch (err) {
+        if (pollRateLimitRetryAfterMs(err) !== null)
+            throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        return ignore(blocker, message);
+    }
+}
+function ignore(blocker, message) {
+    process.stderr.write(`pr-shepherd: check blocker lookup failed for ${formatCheckBlockerRef(blocker)} (ignored): ${message}\n`);
+    return "ignored";
+}
+function blockerKey(blocker) {
+    return `${blocker.kind}:${formatCheckBlockerRef(blocker)}`;
+}

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

@@ -33,4 +33,6 @@ export declare function buildRepeatedWorkflowBranchRecoveryInstructions(baseBran
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
 /** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
+/** Update the PR branch after an external blocker merges or closes. Never rerun that job. */
+export declare function buildReleasedBlockerInstruction(prNumber: number): string;
 export declare function buildFixCompletionInstruction(checks: AgentCheck[], hasConflicts?: boolean, hasShaGatedReviewMutations?: boolean, pushesRewrittenStack?: boolean): string;

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

@@ -80,6 +80,10 @@ export function buildFailingCheckInstructions(checks) {
     }
     return instructions;
 }
+/** Update the PR branch after an external blocker merges or closes. Never rerun that job. */
+export function buildReleasedBlockerInstruction(prNumber) {
+    return `Update this PR branch from its base with \`gh pr update-branch ${prNumber} --rebase\`. Do not rerun the job; a rerun retests the old merge ref.`;
+}
 export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false, pushesRewrittenStack = false) {
     const push = pushesRewrittenStack
         ? "push the rewritten stack with `gh stack push`"

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/fix-code.d.mts

@@ -19,6 +19,8 @@ interface HandleFixCodeContext {
     editedSummaries: Review[];
     surfacedApprovals: Review[];
     botUsernames: NormalizedBotUsernames;
+    /** Failing checks whose external blocker has merged or closed. */
+    releasedCheckNames?: ReadonlySet<string>;
     ruleAutoResolveThreadIds?: string[];
     /** Verified stack-repair guidance, when ancestry is stale. */
     repairInstructions?: string[];

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

@@ -6,7 +6,11 @@ import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, bui
 import { buildResolveCommand } from "./classify.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./thread-mutation-routing.mjs";
 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";
@@ -14,6 +18,7 @@ import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs
 import { canRerunWorkflows } from "../../checks/conclusions.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
+const EMPTY_RELEASED = new Set();
 function checkRequiresHumanFollowUp(check) {
     if (check.rerunCommand)
         return false;
@@ -68,7 +73,7 @@ function pendingReviewCommands(resolveCommand, resolveOnlyCommand) {
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, releasedCheckNames = EMPTY_RELEASED, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
     const failingChecks = report.checks.failing;
     const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
@@ -158,18 +163,22 @@ export async function handleFixCode(ctx) {
         ? [c.runId]
         : []));
     const initialAttemptRunIds = new Set(failingChecks.flatMap((c) => (c.runId !== null && c.runAttempt === 1 ? [c.runId] : [])));
-    const failingAgentChecks = toAgentChecks(failingChecks).map((c) => rerunAuthorized &&
-        c.runId &&
-        actionsRunIds.has(c.runId) &&
-        // GitHub increments run_attempt after every rerun. Recommend at most one rerun by limiting
-        // the command to the original attempt; missing attempt metadata is denied conservatively.
-        initialAttemptRunIds.has(c.runId) &&
-        // ACTION_REQUIRED means the run is paused pending manual workflow approval; rerunning does
-        // not grant that approval, so no rerun command applies.
-        c.conclusion !== "ACTION_REQUIRED" &&
-        !inProgressWorkflowRunIds.has(c.runId)
-        ? { ...c, rerunCommand: `gh run rerun ${c.runId} -R ${report.repo}` }
-        : c);
+    const failingAgentChecks = toAgentChecks(failingChecks).map((c) => {
+        if (releasedCheckNames.has(c.name))
+            return c;
+        return rerunAuthorized &&
+            c.runId &&
+            actionsRunIds.has(c.runId) &&
+            // GitHub increments run_attempt after every rerun. Recommend at most one rerun by limiting
+            // the command to the original attempt; missing attempt metadata is denied conservatively.
+            initialAttemptRunIds.has(c.runId) &&
+            // ACTION_REQUIRED means the run is paused pending manual workflow approval; rerunning does
+            // not grant that approval, so no rerun command applies.
+            c.conclusion !== "ACTION_REQUIRED" &&
+            !inProgressWorkflowRunIds.has(c.runId)
+            ? { ...c, rerunCommand: `gh run rerun ${c.runId} -R ${report.repo}` }
+            : c;
+    });
     const checks = [
         ...failingAgentChecks,
         ...toAgentChecks(annotatedExtra).map((c) => ({ ...c, annotationOnly: true })),
@@ -184,7 +193,9 @@ export async function handleFixCode(ctx) {
     const inProgressRunIds = [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
-    const manualFollowUpChecks = failingAgentChecks.filter((check) => !belongsToActiveWorkflowRun(check) && checkRequiresHumanFollowUp(check));
+    const manualFollowUpChecks = failingAgentChecks.filter((check) => !releasedCheckNames.has(check.name) &&
+        !belongsToActiveWorkflowRun(check) &&
+        checkRequiresHumanFollowUp(check));
     const exhaustedAttempts = failingAgentChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
     const manualExhaustedAttempts = exhaustedAttempts.filter((check) => manualFollowUpChecks.includes(check));
     const hasBehindBaseRecovery = isBehind && manualExhaustedAttempts.length > 0;
@@ -201,7 +212,9 @@ export async function handleFixCode(ctx) {
         report.threads.firstLook.length > 0 ||
         report.comments.firstLook.length > 0 ||
         checks.some((check) => (check.annotations?.length ?? 0) > 0) ||
-        failingAgentChecks.some((check) => belongsToActiveWorkflowRun(check) || !checkRequiresHumanFollowUp(check));
+        failingAgentChecks.some((check) => releasedCheckNames.has(check.name) ||
+            belongsToActiveWorkflowRun(check) ||
+            !checkRequiresHumanFollowUp(check));
     if (manualFollowUpChecks.length > 0 && !hasAutonomousWork) {
         const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
         const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
@@ -272,17 +285,49 @@ 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))) {
+        const completion = instructions.pop();
+        instructions.push(buildReleasedBlockerInstruction(prNumber));
+        if (completion !== undefined)
+            instructions.push(completion);
+    }
     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

@@ -24,6 +24,7 @@ import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
 import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyReceipt, } from "../../state/ready-receipts.mjs";
 import { stackDraftHold } from "./parent-first.mjs";
 import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
+import { annotateBlockedWait, resolveCheckBlockerGate } from "./check-blocker-gate.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -58,6 +59,17 @@ async function runIterateCore(opts) {
         await clearStallState(stallKey);
         return buildTerminalCancelResult(report);
     }
+    const blockerGate = await resolveCheckBlockerGate({ owner: repoOwner, repo: repoName, pr: prNumber }, report.checks.failing, report.mergeStatus.status);
+    const deferredNames = blockerGate?.deferredNames;
+    const reportForWork = deferredNames === undefined || deferredNames.size === 0
+        ? report
+        : {
+            ...report,
+            checks: {
+                ...report.checks,
+                failing: report.checks.failing.filter((check) => !deferredNames.has(check.name)),
+            },
+        };
     const { minimizeIds, selfMinimizeIds, firstLookSummaries, editedSummaries, surfacedApprovals } = classifyReviewSummaries({
         firstLook: report.firstLookSummaries,
         seen: report.reviewSummaries,
@@ -86,7 +98,7 @@ async function runIterateCore(opts) {
         report.comments.actionable.length > 0 ||
         (report.comments.minimizeIds?.length ?? 0) > 0 ||
         report.changesRequestedReviews.length > 0 ||
-        hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status) ||
+        hasCheckDrivenActionableWork(reportForWork.checks, report.mergeStatus.status) ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
         editedSummaries.length > 0 ||
@@ -109,20 +121,20 @@ async function runIterateCore(opts) {
     // current already proves the delay elapsed for this exact head, base, and
     // 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(report, readyState);
+    const base = buildIterateBase(reportForWork, readyState);
     // 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/
     // changes-requested reviews/review summaries — the categories that would otherwise cause a
     // Shepherd-initiated push while the PR sits safely in the queue — are eligible for deferral.
-    const checkDrivenActionableWork = hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status);
+    const checkDrivenActionableWork = hasCheckDrivenActionableWork(reportForWork.checks, report.mergeStatus.status);
     const deferWhileQueued = opts.merge === true &&
         report.mergeQueue?.inQueue === true &&
         config.actions.workWhileQueued !== true;
     if (hasActionableWork && !(deferWhileQueued && !checkDrivenActionableWork)) {
         return handleFixCode({
             base,
-            report,
+            report: reportForWork,
             opts: { ...opts, prNumber, neverCancelRuns },
             headSha,
             stallKey,
@@ -135,6 +147,7 @@ async function runIterateCore(opts) {
             editedSummaries,
             surfacedApprovals,
             botUsernames,
+            releasedCheckNames: blockerGate?.releasedNames,
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
@@ -151,11 +164,11 @@ async function runIterateCore(opts) {
         minimizeApprovals: config.iterate.minimizeApprovals,
     });
     if (mergeStateResult)
-        return mergeStateResult;
+        return annotateBlockedWait(mergeStateResult, blockerGate);
     if (staleAncestry) {
         return handleFixCode({
             base,
-            report,
+            report: reportForWork,
             opts: { ...opts, prNumber, neverCancelRuns },
             headSha,
             stallKey,
@@ -168,6 +181,7 @@ async function runIterateCore(opts) {
             editedSummaries,
             surfacedApprovals,
             botUsernames,
+            releasedCheckNames: blockerGate?.releasedNames,
             repairInstructions: staleAncestry.instructions,
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
@@ -191,7 +205,7 @@ async function runIterateCore(opts) {
                 shouldCancel: false,
                 log: `WAIT: PR #${base.pr} reached ready-delay but its stack readiness receipt could not be persisted`,
             };
-            return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, receiptWait, report, reviewSummaryIds);
+            return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, receiptWait, reportForWork, reviewSummaryIds), blockerGate);
         }
         await clearReadyDelay(report.pr, repoOwner, repoName);
         await clearStallState(stallKey);
@@ -213,7 +227,7 @@ async function runIterateCore(opts) {
         log: buildWaitLog(base),
         ...(hold && { stackDraftHold: hold }),
     };
-    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, report, reviewSummaryIds);
+    return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, reportForWork, reviewSummaryIds), blockerGate);
 }
 async function recordReadyReceipt(key, report) {
     if (report.status !== "READY" ||

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) {