pr-shepherd 0.56.4 → 0.56.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.56.4",
+  "version": "0.56.5",
   "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,6 +293,14 @@ export async function handleFixCode(ctx) {
     const firstLookComments = report.comments.firstLook;
     const stack = report.mergeStatus.mergeRequirements?.stack;
     const headRef = report.headSha;
+    const mergedBasePullRequests = hasConflicts && !stack && report.baseRefOid
+        ? await lookupMergedBasePullRequests({
+            owner: repoOwner,
+            repo: repoName,
+            baseRefName: baseLookup.branch,
+            baseRefOid: report.baseRefOid,
+        })
+        : [];
     // Only an upper layer can be dirty against trunk while already containing its parent.
     const trunkConflict = hasConflicts && stack && headRef && baseLookup.branch !== stack.baseRefName
         ? await lookupUpperLayerTrunkConflict({
@@ -326,6 +335,9 @@ export async function handleFixCode(ctx) {
     if (repairInstructions && repairInstructions.length > 0) {
         instructions.unshift(...repairInstructions);
     }
+    if (mergedBasePullRequests.length > 0) {
+        instructions.unshift(`Inspect every PR under \`## Merged PRs matching the current base\`. If this PR is the remaining layer intended for a merged parent's base branch, run \`gh pr edit ${prReference} --base <verified-parent-base>\` after replacing \`<verified-parent-base>\` with that parent's shell-quoted base branch, then rerun Shepherd immediately and follow its fresh instructions instead of the remaining steps here. Otherwise keep the current base and follow the remaining conflict-resolution steps.`);
+    }
     const checkRunCount = countReportedChecks(report.checks);
     const suitesEmpty = report.headCheckSuitesEmpty === true;
     const nowMs = Date.now();
@@ -342,6 +354,7 @@ export async function handleFixCode(ctx) {
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,
+        ...(mergedBasePullRequests.length > 0 && { mergedBasePullRequests }),
         ...(trunkConflict && { stackTrunkConflict: trunkConflict.trunk }),
         action: "fix_code",
         fix: {

package/bin/commands/iterate/index.mjs

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

package/bin/commands/iterate/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/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/queries.d.mts

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

package/bin/github/queries.mjs

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

package/bin/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.5",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

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

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

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

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

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

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