merge-steward 0.35.2 → 0.35.4

package/dist/github/pr-client.d.ts

@@ -31,7 +31,15 @@ export declare class GitHubPRClient implements GitHubPRApi {
         number: number;
         branch: string;
         headSha: string;
+        baseBranch: string;
     }>>;
+    listOpenPRsByBase(baseBranch: string): Promise<Array<{
+        number: number;
+        branch: string;
+        headSha: string;
+        baseBranch: string;
+    }>>;
+    setBaseBranch(prNumber: number, baseBranch: string): Promise<void>;
     deleteBranch(prNumber: number): Promise<void>;
     findPRByBranch(branch: string): Promise<number | null>;
     listLabels(prNumber: number): Promise<string[]>;

package/dist/github/pr-client.js

@@ -98,7 +98,7 @@ export class GitHubPRClient {
             "pr", "list",
             "--repo", this.repoFullName,
             "--state", "open",
-            "--json", "number,headRefName,headRefOid",
+            "--json", "number,headRefName,headRefOid,baseRefName",
             "--limit", "1000",
         ], { allowNonZero: true, githubRepoFullName: this.repoFullName });
         if (result.exitCode !== 0) {
@@ -106,12 +106,46 @@ export class GitHubPRClient {
         }
         try {
             const data = JSON.parse(result.stdout);
-            return data.map((pr) => ({ number: pr.number, branch: pr.headRefName, headSha: pr.headRefOid }));
+            return data.map((pr) => ({
+                number: pr.number,
+                branch: pr.headRefName,
+                headSha: pr.headRefOid,
+                baseBranch: pr.baseRefName,
+            }));
         }
         catch (error) {
             throw new Error("GitHub returned malformed open PR data", { cause: error });
         }
     }
+    async listOpenPRsByBase(baseBranch) {
+        const result = await exec("gh", [
+            "api", "--method", "GET",
+            `repos/${this.repoFullName}/pulls`,
+            "-f", "state=open",
+            "-f", `base=${baseBranch}`,
+            "-f", "per_page=100",
+            "--paginate", "--slurp",
+        ], { githubRepoFullName: this.repoFullName });
+        try {
+            const pages = JSON.parse(result.stdout);
+            return pages.flat().map((pr) => ({
+                number: pr.number,
+                branch: pr.head.ref,
+                headSha: pr.head.sha,
+                baseBranch: pr.base.ref,
+            }));
+        }
+        catch (error) {
+            throw new Error("GitHub returned malformed stack child PR data", { cause: error });
+        }
+    }
+    async setBaseBranch(prNumber, baseBranch) {
+        await exec("gh", [
+            "api", "--method", "PATCH",
+            `repos/${this.repoFullName}/pulls/${prNumber}`,
+            "-f", `base=${baseBranch}`,
+        ], { githubRepoFullName: this.repoFullName });
+    }
     async deleteBranch(prNumber) {
         const status = await this.getStatus(prNumber);
         await exec("gh", [

package/dist/interfaces.d.ts

@@ -55,9 +55,19 @@ export interface GitHubPRApi {
         number: number;
         branch: string;
         headSha: string;
+        baseBranch: string;
+    }>>;
+    /** List every open PR whose current base is the given branch. */
+    listOpenPRsByBase(baseBranch: string): Promise<Array<{
+        number: number;
+        branch: string;
+        headSha: string;
+        baseBranch: string;
     }>>;
     /** Find the open PR number for a branch, or null if none exists. */
     findPRByBranch(branch: string): Promise<number | null>;
+    /** Retarget a PR before deleting a branch used as its current base. */
+    setBaseBranch(prNumber: number, baseBranch: string): Promise<void>;
     /** Delete the PR's head branch from the remote (best-effort cleanup). */
     deleteBranch(prNumber: number): Promise<void>;
     /** List open PRs with a specific label (for startup scan). */

package/dist/open-pr-ancestry.d.ts

@@ -13,11 +13,21 @@ export interface OpenPrAncestor {
  * captures that shared history. If it is absent from current main, landing the
  * candidate can bypass the other PR's review gates. Explicit stacks become
  * valid only after their shared parent history has landed in main.
+ *
+ * The danger is one-directional. A stack child's candidate carries its
+ * parent's commits, which GitHub reviewed against the parent's branch rather
+ * than against main, so the child must wait. A parent's candidate carries only
+ * its own commits: the history it shares with its child is the parent's own,
+ * it is in the parent's diff, and it was reviewed there. So a child never
+ * blocks its parent, and saying so takes the declared base — after the parent
+ * advances past the commit the child sits on, ancestry alone can no longer
+ * tell a stack child from an unrelated PR holding the same unlanded history.
  */
 export declare function findUnlandedOpenPrAncestors(params: {
     github: GitHubPRApi;
     git: GitOperations;
     currentPrNumber: number;
+    currentBranch: string;
     prHeadSha: string;
     candidateSha: string;
     baseSha: string;

package/dist/open-pr-ancestry.js

@@ -6,6 +6,15 @@
  * captures that shared history. If it is absent from current main, landing the
  * candidate can bypass the other PR's review gates. Explicit stacks become
  * valid only after their shared parent history has landed in main.
+ *
+ * The danger is one-directional. A stack child's candidate carries its
+ * parent's commits, which GitHub reviewed against the parent's branch rather
+ * than against main, so the child must wait. A parent's candidate carries only
+ * its own commits: the history it shares with its child is the parent's own,
+ * it is in the parent's diff, and it was reviewed there. So a child never
+ * blocks its parent, and saying so takes the declared base — after the parent
+ * advances past the commit the child sits on, ancestry alone can no longer
+ * tell a stack child from an unrelated PR holding the same unlanded history.
  */
 export async function findUnlandedOpenPrAncestors(params) {
     const openPrs = await params.github.listOpenPRs();
@@ -13,6 +22,11 @@ export async function findUnlandedOpenPrAncestors(params) {
     for (const openPr of openPrs) {
         if (openPr.number === params.currentPrNumber)
             continue;
+        // Declared onto this PR's branch: a child, whatever its head has done since.
+        // Both names must be present: a missing base must never read as a match,
+        // or an API that stopped returning one would disable this check in silence.
+        if (params.currentBranch !== "" && openPr.baseBranch === params.currentBranch)
+            continue;
         if (openPr.headSha !== params.prHeadSha
             && await params.git.isAncestor(params.prHeadSha, openPr.headSha))
             continue;

package/dist/reconciler-merge.js

@@ -285,6 +285,7 @@ export async function mergeHead(ctx, entry) {
             github: ctx.github,
             git: ctx.git,
             currentPrNumber: entry.prNumber,
+            currentBranch: entry.branch,
             prHeadSha: entry.headSha,
             candidateSha: landingSha,
             baseSha: currentBase,
@@ -417,15 +418,35 @@ export async function deletePrBranchAfterGitHubMarksMerged(ctx, entry, options =
     const attempts = options.attempts ?? DEFAULT_PR_MERGED_POLL_ATTEMPTS;
     const delayMs = options.delayMs ?? DEFAULT_PR_MERGED_POLL_DELAY_MS;
     for (let attempt = 0; attempt < attempts; attempt++) {
-        let merged = false;
+        let mergedStatus = null;
         try {
-            merged = (await ctx.github.getStatus(entry.prNumber)).merged;
+            const status = await ctx.github.getStatus(entry.prNumber);
+            if (status.merged)
+                mergedStatus = status;
         }
         catch {
             // Keep polling briefly. If GitHub is unavailable, branch cleanup is
             // cosmetic; preserving correct PR merge classification matters more.
         }
-        if (merged) {
+        if (mergedStatus) {
+            let children;
+            try {
+                children = await ctx.github.listOpenPRsByBase(mergedStatus.branch);
+                for (const child of children) {
+                    await ctx.github.setBaseBranch(child.number, ctx.baseBranch);
+                }
+            }
+            catch {
+                emit(ctx, entry, "pr_branch_cleanup_deferred", {
+                    detail: "preserving the merged PR branch because stacked children could not be safely retargeted",
+                });
+                return;
+            }
+            if (children.length > 0) {
+                emit(ctx, entry, "stack_children_retargeted", {
+                    detail: `retargeted child PR ${children.map((child) => `#${child.number}`).join(", ")} to ${ctx.baseBranch} before deleting ${mergedStatus.branch}`,
+                });
+            }
             try {
                 await ctx.github.deleteBranch(entry.prNumber);
             }

package/dist/reconciler-prepare.js

@@ -31,6 +31,7 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
             github: ctx.github,
             git: ctx.git,
             currentPrNumber: entry.prNumber,
+            currentBranch: entry.branch,
             prHeadSha: entry.headSha,
             candidateSha: entry.headSha,
             baseSha,

package/dist/service-queue.d.ts

@@ -23,12 +23,25 @@ export declare class MergeStewardQueueCommands {
         baseRefName?: string;
     }): QueueEntry | undefined;
     scanStartupAdmissions(): Promise<void>;
-    scanEligibleOpenPrs(): Promise<{
+    /**
+     * A full re-read of what is admissible.
+     *
+     * This runs both periodically and on startup. Only the startup caller asks
+     * to re-read environmental evictions, because that is when the admission
+     * policy can have changed under an entry that a previous version evicted.
+     */
+    scanEligibleOpenPrs(options?: {
+        rereadEnvironmentalEvictions?: boolean;
+    }): Promise<{
         scanned: number;
         admitted: number;
     }>;
     updatePriorityByPR(prNumber: number, priority: number): boolean;
-    tryAdmit(prNumber: number, branch: string, headSha: string): Promise<boolean>;
+    /** Whether this entry's eviction was about the world rather than the head. */
+    private evictedOnEnvironment;
+    tryAdmit(prNumber: number, branch: string, headSha: string, options?: {
+        rereadEnvironmentalEvictions?: boolean;
+    }): Promise<boolean>;
     dequeueByPR(prNumber: number): void;
     updateHeadByPR(prNumber: number, headSha: string): void;
     acknowledgeExternalMerge(prNumber: number): Promise<void>;

package/dist/service-queue.js

@@ -5,6 +5,18 @@ function matchGlob(pattern, value) {
     const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
     return regex.test(value);
 }
+/**
+ * Evictions the same head can recover from, because what blocked it was the
+ * state around the PR rather than anything about the PR.
+ *
+ * Every other class is a fact about this head — it conflicts, its checks fail,
+ * its branch is broken — and re-admitting it unchanged would only reproduce
+ * the eviction. `policy_blocked` is the exception: it says another open PR's
+ * unlanded history is in the way, which the head cannot fix and which stops
+ * being true when that PR lands, closes, retargets, or when the admission
+ * policy itself changes. Those are re-read on the next startup scan.
+ */
+const ENVIRONMENTAL_FAILURES = new Set(["policy_blocked"]);
 function getLatestEvictedEntry(entries, prNumber) {
     const evicted = entries.filter((entry) => entry.prNumber === prNumber && entry.status === "evicted");
     evicted.sort((left, right) => {
@@ -89,7 +101,7 @@ export class MergeStewardQueueCommands {
     async scanStartupAdmissions() {
         this.logger.info({ repoId: this.config.repoId }, "Scanning startup admissions");
         try {
-            const { scanned, admitted } = await this.scanEligibleOpenPrs();
+            const { scanned, admitted } = await this.scanEligibleOpenPrs({ rereadEnvironmentalEvictions: true });
             if (scanned > 0) {
                 this.logger.info({ scanned, admitted }, "Startup scan for eligible open PRs complete");
             }
@@ -98,12 +110,20 @@ export class MergeStewardQueueCommands {
             this.logger.warn({ err: error }, "Startup scan for eligible open PRs failed");
         }
     }
-    async scanEligibleOpenPrs() {
+    /**
+     * A full re-read of what is admissible.
+     *
+     * This runs both periodically and on startup. Only the startup caller asks
+     * to re-read environmental evictions, because that is when the admission
+     * policy can have changed under an entry that a previous version evicted.
+     */
+    async scanEligibleOpenPrs(options) {
         const open = await this.github.listOpenPRs();
         let admitted = 0;
         for (const pr of open) {
-            if (await this.tryAdmit(pr.number, pr.branch, pr.headSha))
+            if (await this.tryAdmit(pr.number, pr.branch, pr.headSha, options)) {
                 admitted += 1;
+            }
         }
         return { scanned: open.length, admitted };
     }
@@ -123,7 +143,13 @@ export class MergeStewardQueueCommands {
         this.logger.info({ prNumber, entryId: entry.id, priority }, "Updated queued PR priority");
         return true;
     }
-    async tryAdmit(prNumber, branch, headSha) {
+    /** Whether this entry's eviction was about the world rather than the head. */
+    evictedOnEnvironment(entry) {
+        const incidents = this.store.listIncidents(entry.id);
+        const latest = incidents[incidents.length - 1];
+        return latest !== undefined && ENVIRONMENTAL_FAILURES.has(latest.failureClass);
+    }
+    async tryAdmit(prNumber, branch, headSha, options) {
         if (this.config.excludeBranches.some((pattern) => matchGlob(pattern, branch))) {
             this.logger.debug({ prNumber, branch }, "Branch excluded from admission");
             return false;
@@ -135,8 +161,13 @@ export class MergeStewardQueueCommands {
         }
         const latestEvicted = getLatestEvictedEntry(this.store.listAll(this.config.repoId), prNumber);
         if (latestEvicted?.headSha === headSha) {
-            this.logger.debug({ prNumber, headSha, evictedEntryId: latestEvicted.id }, "PR head matches latest evicted entry, skipping admission until a new push");
-            return false;
+            const rereadable = options?.rereadEnvironmentalEvictions === true
+                && this.evictedOnEnvironment(latestEvicted);
+            if (!rereadable) {
+                this.logger.debug({ prNumber, headSha, evictedEntryId: latestEvicted.id }, "PR head matches latest evicted entry, skipping admission until a new push");
+                return false;
+            }
+            this.logger.info({ prNumber, headSha, evictedEntryId: latestEvicted.id }, "Re-admitting a head evicted on environment; the blocking condition is re-read from scratch");
         }
         try {
             const status = await this.github.getStatus(prNumber);

package/dist/types.d.ts

@@ -243,7 +243,7 @@ export interface QueueConfig {
     flakyRetries: number;
     pollIntervalMs: number;
 }
-export type ReconcileAction = "promoted" | "fetch_started" | "main_broken" | "branch_mismatch" | "candidate_selected" | "integration_build_started" | "integration_build_succeeded" | "integration_build_conflict" | "ci_triggered" | "ci_pending" | "ci_passed" | "ci_failed" | "ci_flaky_retry" | "merge_revalidating" | "head_candidate_landed" | "merge_succeeded" | "merge_rejected" | "merge_external" | "policy_changed" | "evicted" | "invalidated" | "retry_gated" | "budget_exhausted" | "merge_waiting_approval" | "open_pr_ancestry_blocked" | "stack_dependency_waiting" | "merge_waiting_recognition" | "merge_waiting_main" | "main_pending_bypassed" | "pr_branch_cleanup_deferred" | "pr_branch_cleanup_failed" | "sanitized_closed" | "sanitized_duplicate" | "post_merge_verification_started" | "post_merge_verification_completed" | "queue_label_synced" | "branch_unreachable";
+export type ReconcileAction = "promoted" | "fetch_started" | "main_broken" | "branch_mismatch" | "candidate_selected" | "integration_build_started" | "integration_build_succeeded" | "integration_build_conflict" | "ci_triggered" | "ci_pending" | "ci_passed" | "ci_failed" | "ci_flaky_retry" | "merge_revalidating" | "head_candidate_landed" | "merge_succeeded" | "merge_rejected" | "merge_external" | "policy_changed" | "evicted" | "invalidated" | "retry_gated" | "budget_exhausted" | "merge_waiting_approval" | "open_pr_ancestry_blocked" | "stack_dependency_waiting" | "merge_waiting_recognition" | "merge_waiting_main" | "main_pending_bypassed" | "pr_branch_cleanup_deferred" | "pr_branch_cleanup_failed" | "stack_children_retargeted" | "sanitized_closed" | "sanitized_duplicate" | "post_merge_verification_started" | "post_merge_verification_completed" | "queue_label_synced" | "branch_unreachable";
 export interface ReconcileEvent {
     at: string;
     entryId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "merge-steward",
-  "version": "0.35.2",
+  "version": "0.35.4",
   "description": "Serial merge queue for GitHub — rebase, CI-gate, and merge PRs one at a time",
   "type": "module",
   "repository": {