pr-shepherd 0.56.4 → 0.56.6

package/.claude-plugin/plugin.json

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

package/bin/cli/fix-formatter.mjs

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

package/bin/cli/iterate-lean.mjs

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

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

@@ -12,6 +12,7 @@ import { currentEjectionCommit, } from "./queue-recovery-instructions.mjs";
 import { buildReleasedBlockerInstruction } from "./check-instructions.mjs";
 import { buildNativeStackLayerRebase } from "./native-stack-rebase.mjs";
 import { lookupUpperLayerTrunkConflict } from "./stack-trunk-conflict.mjs";
+import { lookupMergedBasePullRequests } from "./merged-base-pull-requests.mjs";
 import { conflictingHeadCiNote, countReportedChecks, insertConflictingHeadCiNote, } from "./conflicting-head-ci.mjs";
 import { conflictingHeadFirstSeenUnix } from "../../state/conflicting-head-seen.mjs";
 import { applyStallGuard } from "./stall.mjs";
@@ -292,16 +293,28 @@ export async function handleFixCode(ctx) {
     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({
+    const mergedBasePullRequests = hasConflicts && !stack && report.baseRefOid
+        ? await lookupMergedBasePullRequests({
             owner: repoOwner,
-            name: repoName,
-            pr: prNumber,
-            headRef,
-            trunk: stack.baseRefName,
+            repo: repoName,
+            baseRefName: baseLookup.branch,
+            baseRefOid: report.baseRefOid,
         })
-        : undefined;
+        : [];
+    // A bottom open layer can still retain its merged parent's PR base. Its update starts
+    // at trunk regardless of that base comparison; true upper layers first check the parent.
+    const trunkConflict = hasConflicts && stack && report.stackBottomPr === prNumber
+        ? { trunk: stack.baseRefName, bottomPr: prNumber }
+        : hasConflicts && stack && headRef && baseLookup.branch !== stack.baseRefName
+            ? await lookupUpperLayerTrunkConflict({
+                owner: repoOwner,
+                name: repoName,
+                pr: prNumber,
+                headRef,
+                trunk: stack.baseRefName,
+                bottomPr: report.stackBottomPr,
+            })
+            : undefined;
     const requeue = buildRemovedQueueRecovery(report, failingAgentChecks, opts.merge);
     const queueRemovalAcknowledgment = buildStackQueueRemovalAcknowledgment(report, failingAgentChecks);
     const queueEjection = !currentEjectionCommit(report, failingAgentChecks)
@@ -314,7 +327,7 @@ export async function handleFixCode(ctx) {
     // Conflicts, a behind branch whose rerun already failed, and a queue ejection that may be
     // reproduced on the latest base all print the branch update route.
     const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0) || queueEjection
-        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict)
+        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict, report.stackBottomPr)
         : undefined;
     const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase, queueEjection);
     if (failingAgentChecks.some((check) => releasedCheckNames.has(check.name))) {
@@ -326,6 +339,9 @@ export async function handleFixCode(ctx) {
     if (repairInstructions && repairInstructions.length > 0) {
         instructions.unshift(...repairInstructions);
     }
+    if (mergedBasePullRequests.length > 0) {
+        instructions.unshift(`Inspect every PR under \`## Merged PRs matching the current base\`. If this PR is the remaining layer intended for a merged parent's base branch, run \`gh pr edit ${prReference} --base <verified-parent-base>\` after replacing \`<verified-parent-base>\` with that parent's shell-quoted base branch, then rerun Shepherd immediately and follow its fresh instructions instead of the remaining steps here. Otherwise keep the current base and follow the remaining conflict-resolution steps.`);
+    }
     const checkRunCount = countReportedChecks(report.checks);
     const suitesEmpty = report.headCheckSuitesEmpty === true;
     const nowMs = Date.now();
@@ -342,6 +358,7 @@ export async function handleFixCode(ctx) {
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,
+        ...(mergedBasePullRequests.length > 0 && { mergedBasePullRequests }),
         ...(trunkConflict && { stackTrunkConflict: trunkConflict.trunk }),
         action: "fix_code",
         fix: {

package/bin/commands/iterate/index.mjs

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

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

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

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

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

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

@@ -22,10 +22,11 @@ export declare function buildNativeStackRebaseInstruction(repo: string, stackNum
 /**
  * The stack-aware branch update for a native stack layer (a conflict, or a behind branch whose
  * 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. `trunkConflict` means that
- * upper layer already contains its parent, so the rebase starts at the bottom open layer.
+ * The first open layer in validated stack order is the bottom open layer, even when GitHub
+ * retains its merged parent's branch as its PR base. Without that topology, a PR base matching
+ * the stack trunk also identifies a bottom layer. Other layers rebase from their PR base.
+ * `trunkConflict` means an upper layer already contains its parent, so the rebase starts
+ * at the bottom open layer.
  */
 export declare function buildNativeStackLayerRebase(repo: string, pr: {
     number: number;
@@ -33,7 +34,7 @@ export declare function buildNativeStackLayerRebase(repo: string, pr: {
 }, stack: StackStatus | undefined, trunkConflict?: {
     trunk: string;
     bottomPr?: number;
-}): string | undefined;
+}, stackBottomPr?: number): string | undefined;
 /** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
 export declare function buildConflictInstruction(stackRebase: string | undefined): string;
 /**

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

@@ -15,26 +15,32 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
         ]
         : "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"];
+            : [
+                `check out the bottom open layer of the stack to rebase onto \`${start.trunk}\``,
+                "gh stack rebase",
+            ];
     const prepare = `if \`gh stack\` does not track stack #${stackNumber} locally, import it with \`gh stack checkout ${stackNumber}\``;
     return `From a clean checkout of \`${repo}\`, ${prepare}. Then ${checkout} and run \`${command}\`. ${playbookPointer("Branch update")}`;
 }
 /**
  * The stack-aware branch update for a native stack layer (a conflict, or a behind branch whose
  * 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. `trunkConflict` means that
- * upper layer already contains its parent, so the rebase starts at the bottom open layer.
+ * The first open layer in validated stack order is the bottom open layer, even when GitHub
+ * retains its merged parent's branch as its PR base. Without that topology, a PR base matching
+ * the stack trunk also identifies a bottom layer. Other layers rebase from their PR base.
+ * `trunkConflict` means an upper layer already contains its parent, so the rebase starts
+ * at the bottom open layer.
  */
-export function buildNativeStackLayerRebase(repo, pr, stack, trunkConflict) {
+export function buildNativeStackLayerRebase(repo, pr, stack, trunkConflict, stackBottomPr) {
     if (!stack)
         return undefined;
     const start = trunkConflict
         ? trunkConflict.bottomPr !== undefined
             ? { bottomPr: trunkConflict.bottomPr }
             : { trunk: trunkConflict.trunk }
-        : pr.baseBranch === stack.baseRefName
+        : (stackBottomPr !== undefined
+            ? pr.number === stackBottomPr
+            : pr.baseBranch === stack.baseRefName)
             ? { bottomPr: pr.number }
             : { parentBranch: pr.baseBranch };
     return buildNativeStackRebaseInstruction(repo, stack.number, start);

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

@@ -1,7 +1,7 @@
-/** An upper layer already contains its parent, so the dirty state is against trunk. */
+/** A bottom open layer, or an upper layer that already contains its parent, updates from trunk. */
 export interface UpperLayerTrunkConflict {
     trunk: string;
-    /** Open layer whose PR base is the trunk. Omitted when that layer is not on this page. */
+    /** First open layer after a verified merged prefix. Omitted when topology is unavailable. */
     bottomPr?: number;
 }
 export declare function lookupUpperLayerTrunkConflict(input: {
@@ -10,4 +10,6 @@ export declare function lookupUpperLayerTrunkConflict(input: {
     pr: number;
     headRef: string;
     trunk: string;
+    /** Reuse the bottom layer already resolved for the report, avoiding a topology fetch. */
+    bottomPr?: number;
 }): Promise<UpperLayerTrunkConflict | undefined>;

package/bin/commands/iterate/stack-trunk-conflict.mjs

@@ -1,18 +1,34 @@
 import { graphql } from "../../github/client.mjs";
+import { readStackTopology, verifiedBottomOpenLayer } from "../../github/stack-read.mjs";
 import { UPPER_LAYER_CONFLICT_TARGET_QUERY } from "../../github/queries.mjs";
 import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
-/** Lowest-position open layer whose base is the stack trunk, if this page contains one. */
-function selectBottomOpenLayer(nodes, trunk) {
-    const onTrunk = nodes.flatMap((node) => {
-        const pull = node?.pullRequest;
-        if (!node || !pull || pull.state !== "OPEN" || pull.baseRefName !== trunk)
-            return [];
-        return [{ position: node.position, number: pull.number }];
-    });
-    onTrunk.sort((a, b) => a.position - b.position);
-    return onTrunk[0]?.number;
-}
 export async function lookupUpperLayerTrunkConflict(input) {
+    let bottomPr = input.bottomPr;
+    if (bottomPr === undefined) {
+        let topology;
+        try {
+            topology = await readStackTopology(input.pr, { owner: input.owner, name: input.name });
+        }
+        catch (err) {
+            if (pollRateLimitRetryAfterMs(err) !== null)
+                throw err;
+            ignore(input.pr, err instanceof Error ? err.message : String(err));
+        }
+        if (topology) {
+            try {
+                bottomPr = verifiedBottomOpenLayer(topology.ordered, input.pr).number;
+            }
+            catch (err) {
+                ignore(input.pr, err instanceof Error ? err.message : String(err));
+                // A base comparison cannot prove that a closed or unverified predecessor merged.
+                return undefined;
+            }
+        }
+    }
+    // Merged lower layers need not cause GitHub to retarget this PR to trunk. Even when its
+    // head is behind that old parent branch, the first open layer rebases the stack onto trunk.
+    if (bottomPr === input.pr)
+        return { trunk: input.trunk, bottomPr };
     let data;
     try {
         ({ data } = await graphql(UPPER_LAYER_CONFLICT_TARGET_QUERY, {
@@ -37,13 +53,6 @@ export async function lookupUpperLayerTrunkConflict(input) {
     // behindBy > 0: the layer is still behind its parent. Keep the parent rebase.
     if (behindBy !== 0)
         return undefined;
-    const entries = pull.stack?.entries;
-    const bottomPr = entries ? selectBottomOpenLayer(entries.nodes, input.trunk) : undefined;
-    if (bottomPr === undefined) {
-        ignore(input.pr, entries?.pageInfo.hasNextPage
-            ? "stack entry page truncated before the trunk layer"
-            : "bottom open layer not found");
-    }
     return { trunk: input.trunk, ...(bottomPr !== undefined && { bottomPr }) };
 }
 function ignore(pr, message) {

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

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

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

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

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

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

package/bin/github/gql/upper-layer-conflict-target.gql

@@ -16,21 +16,6 @@ query UpperLayerConflictTarget($owner: String!, $name: String!, $number: Int!, $
           behindBy
         }
       }
-      stack {
-        entries(first: 100) {
-          pageInfo {
-            hasNextPage
-          }
-          nodes {
-            position
-            pullRequest {
-              number
-              state
-              baseRefName
-            }
-          }
-        }
-      }
     }
   }
 }

package/bin/github/merge-target-rules.d.mts

@@ -27,3 +27,7 @@ export declare function loadMergeTargetStatus(input: {
  * is also open, so this compare is the behind count that status hides.
  */
 export declare function loadBaseBehindBy(owner: string, name: string, baseRefName: string, headRef: string): Promise<number>;
+export declare function loadRefRules(owner: string, name: string, qualifiedName: string, headRef: string): Promise<{
+    contexts: string[];
+    behindBy: number;
+}>;

package/bin/github/merge-target-rules.mjs

@@ -3,7 +3,7 @@ import { parseBranchRules } from "./batch-parsers-rules.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { missingRepositoryError } from "./errors.mjs";
 import { BASE_BEHIND_QUERY, REF_RULES_QUERY } from "./queries.mjs";
-import { readStackTopology } from "./stack-read.mjs";
+import { readStackTopology, verifiedBottomOpenLayer } from "./stack-read.mjs";
 /**
  * Required status contexts for the branch GitHub actually merges into.
  * A native stack uses the trunk ref, and `behindBy` is that trunk against the bottom open layer.
@@ -15,24 +15,22 @@ export async function loadMergeTargetStatus(input, context) {
     let headRef = input.headRefName;
     let stackBottomPr = input.pr;
     if (trunk !== input.baseRefName) {
-        const bottom = await bottomOpenLayer(input.pr, { owner: input.owner, name: input.name }, trunk, context);
-        headRef = bottom.headRefName;
+        const bottom = await bottomOpenLayer(input.pr, { owner: input.owner, name: input.name }, context);
+        headRef = bottom.headRefOid;
         stackBottomPr = bottom.number;
     }
-    const loaded = await fetchRefRules(input.owner, input.name, `refs/heads/${trunk}`, headRef);
+    const loaded = await loadRefRules(input.owner, input.name, `refs/heads/${trunk}`, headRef);
     return {
         contexts: loaded.contexts,
         ...(loaded.behindBy > 0 && { trunkBehindBy: loaded.behindBy }),
         stackBottomPr,
     };
 }
-async function bottomOpenLayer(pr, repo, trunk, context) {
+async function bottomOpenLayer(pr, repo, context) {
     const topology = await (context?.readStackTopology(pr, repo) ?? readStackTopology(pr, repo));
-    const bottom = topology.ordered.find((member) => member.state === "OPEN" && member.baseRefName === trunk);
-    if (!bottom) {
-        throw new ShepherdError(`Native stack for PR #${pr} has no open layer based on ${trunk}`, EXIT.TEMPFAIL);
-    }
-    return bottom;
+    // GitHub can retain a merged parent's branch as the lowest open layer's
+    // base. Stack order, rather than retargeting, determines the review target.
+    return verifiedBottomOpenLayer(topology.ordered, pr);
 }
 /**
  * Commits on the PR base that `headRef` does not contain.
@@ -57,7 +55,7 @@ export async function loadBaseBehindBy(owner, name, baseRefName, headRef) {
     }
     return ref.compare?.behindBy ?? 0;
 }
-async function fetchRefRules(owner, name, qualifiedName, headRef) {
+export async function loadRefRules(owner, name, qualifiedName, headRef) {
     const { data } = await graphqlWithRateLimit(REF_RULES_QUERY, {
         owner,
         repo: name,

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

@@ -1,6 +1,7 @@
+import type { RepoInfo } from "./client.mts";
 import type { PollSummaryChecks } from "../types.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
-/** Required contexts from the open layer whose base is the stack trunk. */
-export declare function trunkRequiredContexts(ordered: readonly RawSummaryPr[]): string[] | undefined;
+/** Current trunk rules may remain available on a merged layer's base ref. */
+export declare function trunkRequiredContexts(ordered: readonly RawSummaryPr[], repo: RepoInfo): Promise<string[] | undefined>;
 /** Record missing required contexts. A running Actions workflow does not clear the names. */
 export declare function applyUnreportedRequiredChecks(raw: RawSummaryPr, checks: PollSummaryChecks, mergeTargetContexts: readonly string[] | undefined): void;

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

@@ -1,15 +1,20 @@
 import { loadConfig } from "../config/load.mjs";
 import { actionsWorkflowInProgress, selectMergeTargetContexts, unreportedRequiredContexts, } from "../checks/unreported-required.mjs";
 import { parseBranchRules } from "./batch-parsers-rules.mjs";
-/** Required contexts from the open layer whose base is the stack trunk. */
-export function trunkRequiredContexts(ordered) {
+import { loadRefRules } from "./merge-target-rules.mjs";
+/** Current trunk rules may remain available on a merged layer's base ref. */
+export async function trunkRequiredContexts(ordered, repo) {
     const trunk = ordered.find((pr) => pr.stack)?.stack?.baseRefName;
     if (!trunk)
         return undefined;
-    const bottom = ordered.find((pr) => pr.state === "OPEN" && pr.baseRefName === trunk);
+    const bottom = ordered.find((pr) => pr.state === "OPEN");
     if (!bottom)
         return undefined;
-    return parseBranchRules(bottom.baseRef).requiredStatusCheckContexts;
+    const trunkLayer = ordered.find((pr) => pr.baseRefName === trunk && pr.baseRef != null);
+    if (trunkLayer)
+        return parseBranchRules(trunkLayer.baseRef).requiredStatusCheckContexts;
+    const loaded = await loadRefRules(repo.owner, repo.name, `refs/heads/${trunk}`, bottom.headRefOid);
+    return loaded.contexts;
 }
 /** Record missing required contexts. A running Actions workflow does not clear the names. */
 export function applyUnreportedRequiredChecks(raw, checks, mergeTargetContexts) {

package/bin/github/poll-summary.mjs

@@ -72,7 +72,7 @@ async function fetchStackSummary(opts, repo) {
         await refreshUnknownSummaryMergeability(pr, repo);
     }
     const stackAncestry = stackAncestryGaps(ordered);
-    const required = trunkRequiredContexts(ordered);
+    const required = await trunkRequiredContexts(ordered, repo);
     return {
         selection: { kind: "stack", anchor, stackNumber, stackSize },
         prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister, required, viewerLogin))),

package/bin/github/queries.d.mts

@@ -35,10 +35,12 @@ export declare const POLL_STACK_SUMMARY_QUERY: string;
 /** Reads only native-stack membership and the refs that link adjacent entries. */
 export declare const POLL_STACK_TOPOLOGY_QUERY: string;
 /**
- * Whether a conflicting upper stack layer already contains its PR base, plus
- * the open stack entries needed to name the bottom layer. Not part of BatchPr.
+ * Whether a conflicting upper stack layer already contains its PR base.
+ * Bottom-layer identity comes from the validated stack topology. Not part of BatchPr.
  */
 export declare const UPPER_LAYER_CONFLICT_TARGET_QUERY: string;
+/** Merged PRs whose head may be the stale base of a non-stack conflict. */
+export declare const MERGED_BASE_PULL_REQUESTS_QUERY: string;
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/github/queries.mjs

@@ -40,10 +40,12 @@ export const POLL_STACK_SUMMARY_QUERY = `${POLL_SUMMARY_FRAGMENT}\n${gql("poll-s
 /** Reads only native-stack membership and the refs that link adjacent entries. */
 export const POLL_STACK_TOPOLOGY_QUERY = gql("poll-stack-topology.gql");
 /**
- * Whether a conflicting upper stack layer already contains its PR base, plus
- * the open stack entries needed to name the bottom layer. Not part of BatchPr.
+ * Whether a conflicting upper stack layer already contains its PR base.
+ * Bottom-layer identity comes from the validated stack topology. Not part of BatchPr.
  */
 export const UPPER_LAYER_CONFLICT_TARGET_QUERY = gql("upper-layer-conflict-target.gql");
+/** Merged PRs whose head may be the stale base of a non-stack conflict. */
+export const MERGED_BASE_PULL_REQUESTS_QUERY = gql("merged-base-pull-requests.gql");
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/github/stack-read.d.mts

@@ -31,6 +31,8 @@ export interface StackRead<Pr extends StackMemberRefs> {
 export declare function readStack<Pr extends StackMemberRefs>(query: string, anchor: number, repo: RepoInfo, variables?: Record<string, unknown>): Promise<StackRead<Pr>>;
 /** Membership and linking refs only — no per-PR CI or review hydration. */
 export declare function readStackTopology(anchor: number, repo: RepoInfo): Promise<StackRead<StackMemberRefs>>;
+/** The first open member can replace merged lower layers only after a fully merged prefix. */
+export declare function verifiedBottomOpenLayer<Pr extends StackMemberRefs>(ordered: readonly Pr[], anchor: number): Pr;
 /**
  * Adjacent entries, both open, whose child base no longer matches the parent
  * head. Both sides come from the same read, so each gap was observed together.

package/bin/github/stack-read.mjs

@@ -77,6 +77,19 @@ export async function readStack(query, anchor, repo, variables = {}) {
 export function readStackTopology(anchor, repo) {
     return readStack(POLL_STACK_TOPOLOGY_QUERY, anchor, repo);
 }
+/** The first open member can replace merged lower layers only after a fully merged prefix. */
+export function verifiedBottomOpenLayer(ordered, anchor) {
+    const index = ordered.findIndex((member) => member.state === "OPEN");
+    const bottom = ordered[index];
+    if (!bottom) {
+        throw new ShepherdError(`Native stack for PR #${anchor} has no open layer`, EXIT.TEMPFAIL);
+    }
+    const predecessor = ordered.slice(0, index).find((member) => member.state !== "MERGED");
+    if (predecessor) {
+        throw new ShepherdError(`Native stack for PR #${anchor} has PR #${predecessor.number} in state ${predecessor.state} before open PR #${bottom.number}; cannot verify the bottom open layer`, EXIT.TEMPFAIL);
+    }
+    return bottom;
+}
 /**
  * Adjacent entries, both open, whose child base no longer matches the parent
  * head. Both sides come from the same read, so each gap was observed together.

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

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

package/bin/state/ci-retrigger.mjs

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

package/bin/types/github.d.mts

@@ -6,6 +6,19 @@ export type CheckStatus = "COMPLETED" | "IN_PROGRESS" | "PENDING" | "QUEUED" | "
 export type MergeableState = "CONFLICTING" | "MERGEABLE" | "UNKNOWN";
 export type MergeStateStatus = "BEHIND" | "BLOCKED" | "CLEAN" | "DIRTY" | "DRAFT" | "HAS_HOOKS" | "UNKNOWN" | "UNSTABLE";
 export type ReviewDecision = "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | null;
+/** Raw GitHub fields for a merged PR whose head is this PR's current base. */
+export interface MergedBasePullRequest {
+    number: number;
+    url: string;
+    state: "MERGED";
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    mergedAt: string;
+    headRepository: {
+        nameWithOwner: string;
+    };
+}
 export type AuthorType = "User" | "Bot" | "Unknown";
 type RepositoryPermission = "NONE" | "READ" | "TRIAGE" | "WRITE" | "MAINTAIN" | "ADMIN";
 /** Raw GitHub viewer fields used to gate remote actions. */

package/bin/types/iterate.d.mts

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

package/package.json

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

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

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