merge-steward 0.35.1 → 0.35.3

package/dist/config.js

@@ -14,7 +14,7 @@ export const stewardConfigSchema = z.object({
     maxRetries: z.number().int().min(0).default(2),
     flakyRetries: z.number().int().min(0).default(1),
     /** Max speculative branches to maintain in parallel. 1 = serial mode. */
-    speculativeDepth: z.number().int().min(1).default(10),
+    speculativeDepth: z.number().int().min(1).default(3),
     pollIntervalMs: z.number().int().min(1000).default(30_000),
     reconcileStaleAfterMs: z.number().int().min(1000).default(5 * 60_000),
     server: z.object({

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

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

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,7 +106,12 @@ 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 });

package/dist/install.js

@@ -163,7 +163,7 @@ export async function upsertRepoConfig(options) {
         gitBin: existing?.gitBin ?? "git",
         maxRetries: existing?.maxRetries ?? 2,
         flakyRetries: existing?.flakyRetries ?? 1,
-        speculativeDepth: existing?.speculativeDepth ?? 10,
+        speculativeDepth: existing?.speculativeDepth ?? 3,
         pollIntervalMs: existing?.pollIntervalMs ?? 30_000,
         server: {
             bind: existing?.server.bind ?? (homeConfig.server?.bind ?? "127.0.0.1"),

package/dist/interfaces.d.ts

@@ -55,6 +55,7 @@ export interface GitHubPRApi {
         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>;

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,

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/reconciler-validate.js

@@ -13,7 +13,9 @@ async function holdForIntegrationRepair(ctx, entry, allActive, index, checks) {
         .map((check) => check.name)
         .join(", ");
     ctx.store.transition(entry.id, "validating", {
-        candidateKind: "integration",
+        // A failed repaired candidate is still a repaired candidate. Preserve the
+        // provenance so a same-SHA rerun remains gated by integration review.
+        candidateKind: entry.candidateKind === "integration_repair" ? "integration_repair" : "integration",
         ciRunId: entry.ciRunId ?? `head:${entry.candidateSha ?? entry.headSha}`,
         candidateRef,
         candidateSha: entry.candidateSha ?? entry.headSha,
@@ -142,9 +144,21 @@ export async function checkValidation(ctx, entry, allActive, index, isLandingHea
     if (entry.candidateRef && !await ctx.git.isAncestor(entry.headSha, entry.candidateSha)) {
         return;
     }
-    if (entry.candidateRef && entry.candidateKind === "integration" && entry.lastFailedBaseSha && entry.ciRunId) {
-        // The same failed SHA is intentionally quiescent until PatchRelay moves
-        // the workspace ref. Do not manufacture another CI run on every wakeup.
+    if (entry.candidateRef && entry.lastFailedBaseSha && entry.ciRunId) {
+        // Do not manufacture another CI run on every wakeup, but do re-read the
+        // exact SHA: an operator or GitHub may have rerun the failed workflow in
+        // place. A green rerun must resume the queue without a no-op commit.
+        const checks = (await ctx.github.listChecksForRef(entry.candidateSha))
+            .filter((check) => check.name.toLowerCase() !== INTEGRATION_REVIEW_CHECK);
+        const evaluation = evaluateCheckPolicy(ctx.policy.getRequiredCheckRules(), ctx.policy.shouldRequireAllChecksOnEmptyRequiredSet(), checks);
+        if (evaluation.status === "pass") {
+            await acceptPassingIntegrationCandidate(ctx, entry, allActive, index, isLandingHead, entry.ciRunId);
+        }
+        else if (evaluation.status === "pending") {
+            ctx.store.transition(entry.id, "validating", {
+                waitDetail: "waiting for exact-candidate rerun",
+            }, "exact-candidate rerun pending");
+        }
         return;
     }
     if (entry.candidateKind === "head") {

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/package.json

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