merge-steward 0.33.0 → 0.33.2

package/dist/github/check-run-reporter.js

@@ -88,7 +88,9 @@ function formatTitle(incident) {
         case "main_broken":
             return "Queue eviction: main branch CI failing";
         case "policy_blocked":
-            return "Queue eviction: approval withdrawn";
+            return incident.context.openPrAncestors?.length
+                ? "Queue eviction: candidate shares unlanded history with another open PR"
+                : "Queue eviction: approval withdrawn";
         default:
             return "Queue eviction";
     }
@@ -114,6 +116,12 @@ function formatSummary(entry, incident) {
             lines.push(`- ${c.name} (${c.conclusion})`);
         }
     }
+    if (incident.context.openPrAncestors?.length) {
+        lines.push(``, `**Unlanded open PR ancestry:**`);
+        for (const blocker of incident.context.openPrAncestors) {
+            lines.push(`- #${blocker.prNumber} ${blocker.branch} (head ${blocker.headSha}; shared unlanded ancestor ${blocker.sharedAncestorSha})`);
+        }
+    }
     lines.push(``, `**Incident ID:** ${incident.id}`);
     return lines.join("\n");
 }

package/dist/github/pr-client.js

@@ -96,15 +96,17 @@ export class GitHubPRClient {
             "--repo", this.repoFullName,
             "--state", "open",
             "--json", "number,headRefName,headRefOid",
+            "--limit", "1000",
         ], { allowNonZero: true, githubRepoFullName: this.repoFullName });
-        if (result.exitCode !== 0)
-            return [];
+        if (result.exitCode !== 0) {
+            throw new Error(`Failed to list open PRs: ${result.stderr.trim() || `exit ${result.exitCode}`}`);
+        }
         try {
             const data = JSON.parse(result.stdout);
             return data.map((pr) => ({ number: pr.number, branch: pr.headRefName, headSha: pr.headRefOid }));
         }
-        catch {
-            return [];
+        catch (error) {
+            throw new Error("GitHub returned malformed open PR data", { cause: error });
         }
     }
     async deleteBranch(prNumber) {

package/dist/github/shell-git.d.ts

@@ -23,6 +23,7 @@ export declare class ShellGitOperations implements GitOperations, SpeculativeBra
     private gitIn;
     fetch(remote?: string): Promise<void>;
     headSha(branch: string): Promise<string>;
+    mergeBase(left: string, right: string): Promise<string>;
     isAncestor(ancestor: string, descendant: string): Promise<boolean>;
     push(branch: string, force?: boolean, targetBranch?: string): Promise<void>;
     /**

package/dist/github/shell-git.js

@@ -74,6 +74,13 @@ export class ShellGitOperations {
         const result = await this.git(["rev-parse", branch]);
         return result.stdout.trim();
     }
+    async mergeBase(left, right) {
+        const result = await this.git(["merge-base", left, right]);
+        const sha = result.stdout.trim();
+        if (!sha)
+            throw new Error(`git merge-base returned no commit for ${left} and ${right}`);
+        return sha;
+    }
     async isAncestor(ancestor, descendant) {
         const result = await this.git(["merge-base", "--is-ancestor", ancestor, descendant], { allowNonZero: true });
         if (result.exitCode === 0)

package/dist/install.js

@@ -3,23 +3,12 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { DEFAULT_MERGE_QUEUE_CHECK_NAME, parseConfig } from "./config.js";
-import { getBuiltCliEntryPath, getDefaultConfigPath, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getDefaultStateDir, getMergeStewardPathLayout, getRepoConfigPath, getSystemdUnitPath, readBundledAsset } from "./runtime-paths.js";
+import { getDefaultConfigPath, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getDefaultStateDir, getMergeStewardPathLayout, getRepoConfigPath, getSystemdUnitPath, readBundledAsset } from "./runtime-paths.js";
 import { parseHomeConfigObject, stringifyJson } from "./steward-home.js";
 function renderTemplate(template, replacements) {
     const home = homedir();
     const user = basename(home);
     const layout = getMergeStewardPathLayout();
-    // When running from source (e.g. during tests or `npm run dev`) the dist/
-    // entrypoint isn't built yet.  Fall back to the PATH-resolved binary so the
-    // systemd template still renders — the ExecStart will need `merge-steward`
-    // on PATH at service start, which is true for any normal install.
-    let cliEntry;
-    try {
-        cliEntry = getBuiltCliEntryPath();
-    }
-    catch {
-        cliEntry = "/usr/bin/env merge-steward";
-    }
     let rendered = template
         .replaceAll("/home/your-user", home)
         .replaceAll("your-user", user)
@@ -29,8 +18,7 @@ function renderTemplate(template, replacements) {
         .replaceAll("/home/your-user/.config/merge-steward/merge-steward.json", layout.configPath)
         .replaceAll("/home/your-user/.config/merge-steward/repos", layout.repoConfigDir)
         .replaceAll("/home/your-user/.local/state/merge-steward", layout.stateDir)
-        .replaceAll("/home/your-user/.local/share/merge-steward", layout.dataDir)
-        .replaceAll("/usr/bin/env merge-steward", cliEntry);
+        .replaceAll("/home/your-user/.local/share/merge-steward", layout.dataDir);
     if (replacements?.publicBaseUrl) {
         rendered = rendered.replaceAll("https://queue.example.com", replacements.publicBaseUrl);
     }

package/dist/interfaces.d.ts

@@ -6,6 +6,7 @@ import type { CIStatus, CheckResult, IncidentRecord, MergeResult, PRStatus, Queu
 export interface GitOperations {
     fetch(remote?: string): Promise<void>;
     headSha(branch: string): Promise<string>;
+    mergeBase(left: string, right: string): Promise<string>;
     isAncestor(ancestor: string, descendant: string): Promise<boolean>;
     push(branch: string, force?: boolean, targetBranch?: string): Promise<void>;
 }

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

@@ -0,0 +1,25 @@
+import type { GitHubPRApi, GitOperations } from "./interfaces.ts";
+export interface OpenPrAncestor {
+    prNumber: number;
+    branch: string;
+    headSha: string;
+    sharedAncestorSha: string;
+}
+/**
+ * Find ancestry shared with open PRs outside the current base.
+ *
+ * Testing only the other PR's current head is insufficient: a parent may have
+ * advanced after the child copied its earlier blocked head. The merge base
+ * 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.
+ */
+export declare function findUnlandedOpenPrAncestors(params: {
+    github: GitHubPRApi;
+    git: GitOperations;
+    currentPrNumber: number;
+    prHeadSha: string;
+    candidateSha: string;
+    baseSha: string;
+}): Promise<OpenPrAncestor[]>;
+export declare function describeOpenPrAncestors(blockers: OpenPrAncestor[]): string;

package/dist/open-pr-ancestry.js

@@ -0,0 +1,33 @@
+/**
+ * Find ancestry shared with open PRs outside the current base.
+ *
+ * Testing only the other PR's current head is insufficient: a parent may have
+ * advanced after the child copied its earlier blocked head. The merge base
+ * 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.
+ */
+export async function findUnlandedOpenPrAncestors(params) {
+    const openPrs = await params.github.listOpenPRs();
+    const blockers = [];
+    for (const openPr of openPrs) {
+        if (openPr.number === params.currentPrNumber)
+            continue;
+        if (openPr.headSha !== params.prHeadSha
+            && await params.git.isAncestor(params.prHeadSha, openPr.headSha))
+            continue;
+        const sharedAncestorSha = await params.git.mergeBase(openPr.headSha, params.candidateSha);
+        if (await params.git.isAncestor(sharedAncestorSha, params.baseSha))
+            continue;
+        blockers.push({
+            prNumber: openPr.number,
+            branch: openPr.branch,
+            headSha: openPr.headSha,
+            sharedAncestorSha,
+        });
+    }
+    return blockers;
+}
+export function describeOpenPrAncestors(blockers) {
+    return `candidate shares unlanded history with open PR ${blockers.map((blocker) => `#${blocker.prNumber} (${blocker.sharedAncestorSha.slice(0, 12)})`).join(", ")}`;
+}

package/dist/reconciler-evict.d.ts

@@ -9,4 +9,10 @@ export declare function evictEntry(ctx: ReconcileContext, entry: QueueEntry, fai
         conclusion: string;
         url?: string;
     }>;
+    openPrAncestors?: Array<{
+        prNumber: number;
+        branch: string;
+        headSha: string;
+        sharedAncestorSha: string;
+    }>;
 }): Promise<void>;

package/dist/reconciler-evict.js

@@ -59,6 +59,7 @@ export async function evictEntry(ctx, entry, failureClass, extra) {
         queuePosition: entry.position,
         conflictFiles: extra?.conflictFiles,
         failedChecks: extra?.failedChecks,
+        openPrAncestors: extra?.openPrAncestors,
         baseBranch: ctx.baseBranch,
         branch: entry.branch,
         issueKey: entry.issueKey,

package/dist/reconciler-merge.js

@@ -2,6 +2,7 @@ import { CLEAN_CANDIDATE_REF, CLEAN_CI, CLEAR_CANDIDATE, emit, isBudgetExhausted
 import { cleanupCandidate, evictEntry, invalidateDownstream } from "./reconciler-evict.js";
 import { verifyPostMergeStatus } from "./reconciler-post-merge.js";
 import { evaluateCheckPolicy, formatRequiredCheck } from "./check-policy.js";
+import { describeOpenPrAncestors, findUnlandedOpenPrAncestors } from "./open-pr-ancestry.js";
 const DEFAULT_PR_MERGED_POLL_ATTEMPTS = 6;
 const DEFAULT_PR_MERGED_POLL_DELAY_MS = 2_000;
 function delay(ms) {
@@ -276,6 +277,38 @@ export async function mergeHead(ctx, entry) {
                 candidatePolicyFingerprint: currentPolicyFingerprint,
             }, `candidate revalidated under policy ${currentPolicyFingerprint.slice(0, 12)}`);
         }
+        // Ancestry is the last remote truth read before the immutable push. Fetch
+        // main again because check and PR revalidation above can take long enough
+        // for either main or the open-PR set to change.
+        await ctx.git.fetch();
+        currentBase = await ctx.git.headSha(ref(ctx, ctx.baseBranch));
+        if (!await ctx.git.isAncestor(currentBase, landingSha)) {
+            emit(ctx, entry, "branch_mismatch", {
+                detail: `candidate is not a fast-forward from final main (${currentBase.slice(0, 8)})`,
+            });
+            const allActive = ctx.store.listActive(ctx.repoId);
+            ctx.store.transition(entry.id, "preparing_head", { ...CLEAN_CI, ...CLEAR_CANDIDATE }, "main changed during landing, re-prepare");
+            await invalidateDownstream(ctx, allActive, 0);
+            return;
+        }
+        const ancestryBlockers = await findUnlandedOpenPrAncestors({
+            github: ctx.github,
+            git: ctx.git,
+            currentPrNumber: entry.prNumber,
+            prHeadSha: entry.headSha,
+            candidateSha: landingSha,
+            baseSha: currentBase,
+        });
+        if (ancestryBlockers.length > 0) {
+            const detail = describeOpenPrAncestors(ancestryBlockers);
+            emit(ctx, entry, "open_pr_ancestry_blocked", { baseSha: currentBase, detail });
+            const allActive = ctx.store.listActive(ctx.repoId);
+            const entryIndex = allActive.findIndex((candidate) => candidate.id === entry.id);
+            await evictEntry(ctx, entry, "policy_blocked", { openPrAncestors: ancestryBlockers });
+            if (entryIndex >= 0)
+                await invalidateDownstream(ctx, allActive, entryIndex);
+            return;
+        }
     }
     catch (error) {
         const detail = `candidate revalidation unavailable: ${describeError(error)}`;

package/dist/reconciler-prepare.js

@@ -1,5 +1,6 @@
 import { CLEAN_CI, CLEAR_CANDIDATE, emit, isRetryGated, ref, candidateRefName } from "./reconciler-core.js";
 import { evictEntry } from "./reconciler-evict.js";
+import { describeOpenPrAncestors, findUnlandedOpenPrAncestors } from "./open-pr-ancestry.js";
 export async function prepareEntry(ctx, entry, isHead, prevEntry) {
     emit(ctx, entry, "fetch_started");
     await ctx.git.fetch();
@@ -13,6 +14,22 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
         ctx.store.updateHead(entry.id, currentRef);
         return;
     }
+    if (isHead) {
+        const blockers = await findUnlandedOpenPrAncestors({
+            github: ctx.github,
+            git: ctx.git,
+            currentPrNumber: entry.prNumber,
+            prHeadSha: entry.headSha,
+            candidateSha: entry.headSha,
+            baseSha,
+        });
+        if (blockers.length > 0) {
+            const detail = describeOpenPrAncestors(blockers);
+            emit(ctx, entry, "open_pr_ancestry_blocked", { baseSha, detail });
+            await evictEntry(ctx, entry, "policy_blocked", { openPrAncestors: blockers });
+            return;
+        }
+    }
     // Preparing/validating the head never waits on main's CI. The exact
     // candidate includes current main and is gated solely by its own checks.
     //
@@ -34,6 +51,23 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
         }
         return;
     }
+    // A remote merge can advance main before GitHub's PR API reports `merged`.
+    // The PR head is then already contained in main, so building and testing an
+    // "integration" candidate would only reproduce the current main commit.
+    // Hold the entry until sanitizeEntry observes GitHub's terminal truth.
+    if (baseSha !== entry.headSha && await ctx.git.isAncestor(entry.headSha, baseSha)) {
+        const detail = `PR head ${entry.headSha.slice(0, 12)} is already contained in main ${baseSha.slice(0, 12)}; waiting for GitHub merge recognition`;
+        if (entry.waitDetail !== detail) {
+            emit(ctx, entry, "merge_waiting_recognition", { baseSha, detail });
+            ctx.store.transition(entry.id, "preparing_head", {
+                baseSha,
+                ...CLEAN_CI,
+                ...CLEAR_CANDIDATE,
+                waitDetail: detail,
+            }, detail);
+        }
+        return;
+    }
     // Candidate selection is structural, not a separate fast-forward workflow.
     // If the prospective base is already an ancestor of the PR head, that exact
     // immutable head is the future main candidate and its existing SHA-bound

package/dist/reconciler.js

@@ -48,11 +48,12 @@ export async function reconcile(ctx) {
         // Truth guard: verify entry against GitHub before processing.
         if (await sanitizeEntry(ctx, entry)) {
             // Entry may have been terminalized (closed/duplicate) — clear any
-            // stale queue sub-state label it still carries.
+            // stale queue sub-state label it still carries. Stop this snapshot:
+            // later entries were ordered against topology that has now changed.
             const sanitized = ctx.store.getEntry(entry.id);
             if (sanitized)
                 await syncQueueStateLabels(ctx, sanitized);
-            continue;
+            break;
         }
         // Stale dependency guard: if this entry's spec was built on top of
         // another entry that was dequeued or evicted (without downstream
@@ -112,6 +113,12 @@ export async function reconcile(ctx) {
         const post = ctx.store.getEntry(entry.id);
         if (post)
             await syncQueueStateLabels(ctx, post);
+        if (post && (post.status === "evicted" || post.status === "dequeued")) {
+            // Dependency readiness was computed before this terminal transition.
+            // Re-enter on the next tick so an independent root cannot reuse or
+            // rebuild through a child that just became blocked by its parent.
+            break;
+        }
     }
     await verifyMergedEntriesPostPush(ctx);
 }

package/dist/types.d.ts

@@ -103,6 +103,12 @@ export interface EvictionContext {
         conclusion: string;
         url?: string;
     }> | undefined;
+    openPrAncestors?: Array<{
+        prNumber: number;
+        branch: string;
+        headSha: string;
+        sharedAncestorSha: string;
+    }> | undefined;
     baseSha: string;
     prHeadSha: string;
     queuePosition: number;
@@ -240,7 +246,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" | "stack_dependency_waiting" | "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" | "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.33.0",
+  "version": "0.33.2",
   "description": "Serial merge queue for GitHub — rebase, CI-gate, and merge PRs one at a time",
   "type": "module",
   "repository": {