merge-steward 0.35.0 → 0.35.2

package/README.md

@@ -15,6 +15,8 @@ The queue keeps delivery fast without pretending branch CI is always enough. For
 ## How it works
 
 1. A PR becomes eligible when GitHub says it is approved and its required checks are green.
+   If GitHub names no required checks, every observed check on the exact head
+   must be settled without failure; one early green job is not enough.
 2. The steward notices through webhook wakeups or startup reconcile scans, and admits the PR to the queue.
 3. It freezes the approved PR head and resolves the exact future-`main`
    candidate. If the prospective base is its ancestor, that head is the
@@ -22,6 +24,8 @@ The queue keeps delivery fast without pretending branch CI is always enough. For
    `merge-steward/<base>/pr-<number>` as a cumulative integration workspace.
 4. It validates checks on that exact SHA. Only newly-created integration candidates trigger synthetic CI.
 5. Immediately before landing, it refreshes policy, approval, head, checks, and ancestry, then non-force pushes the same immutable SHA to `main`. It never substitutes a mutable branch ref.
+   If the PR head changes, the old admission becomes `superseded`; the new
+   head returns to feature review and branch CI before receiving a new place.
 6. On conflict, the workspace remains at the prospective base; PatchRelay
    derives the missing ancestry and non-force pushes a resolved candidate.
 7. On candidate-CI failure, PatchRelay repairs the candidate rather than the PR

package/dist/cli/commands/pr-status.js

@@ -5,7 +5,7 @@ import { defaultResolveRunner, resolvePrNumber, resolveRepo } from "../resolve.j
 import { parseIntegerFlag } from "../args.js";
 import { fetchPrGitHubOverview } from "./pr-github.js";
 import { formatRuntimeActivity } from "../../runtime-format.js";
-const TERMINAL_QUEUE_STATUSES = new Set(["merged", "evicted", "dequeued"]);
+const TERMINAL_QUEUE_STATUSES = new Set(["merged", "evicted", "dequeued", "superseded"]);
 export function computeActiveRank(entries, target) {
     if (TERMINAL_QUEUE_STATUSES.has(target.status))
         return undefined;
@@ -26,6 +26,7 @@ export function classifyQueueEntry(entry) {
         case "merging": return "merging";
         case "evicted": return "evicted";
         case "dequeued": return "dequeued";
+        case "superseded": return "not_queued";
     }
 }
 function exitCodeForKind(kind) {
@@ -78,7 +79,7 @@ export function classifyGitHubOverview(overview) {
     return { kind: "not_queued", reason: "PR is not admitted to the merge queue" };
 }
 function findEntryForPr(snapshot, prNumber) {
-    const matches = snapshot.entries.filter((entry) => entry.prNumber === prNumber);
+    const matches = snapshot.entries.filter((entry) => entry.prNumber === prNumber && entry.status !== "superseded");
     if (matches.length === 0)
         return undefined;
     matches.sort((left, right) => {
@@ -114,7 +115,7 @@ async function loadQueueEntry(config, prNumber) {
         const store = new SqliteStore(config.database.path);
         try {
             const all = store.listAll(config.repoId);
-            const entries = all.filter((entry) => entry.prNumber === prNumber);
+            const entries = all.filter((entry) => entry.prNumber === prNumber && entry.status !== "superseded");
             if (entries.length === 0)
                 return { kind: "not_found" };
             entries.sort((left, right) => {

package/dist/cli/commands/queue.js

@@ -82,7 +82,7 @@ export function formatQueueStatusText(source, snapshot) {
         ...(githubPolicy.fetchedAt ? [`GitHub policy fetched: ${githubPolicy.fetchedAt}`] : []),
         `Active entries: ${snapshot.summary.active}`,
         `Queued: ${snapshot.summary.queued}  preparing: ${snapshot.summary.preparingHead}  validating: ${snapshot.summary.validating}  merging: ${snapshot.summary.merging}`,
-        `Merged: ${snapshot.summary.merged}  evicted: ${snapshot.summary.evicted}  dequeued: ${snapshot.summary.dequeued}`,
+        `Merged: ${snapshot.summary.merged}  evicted: ${snapshot.summary.evicted}  dequeued: ${snapshot.summary.dequeued}  superseded: ${snapshot.summary.superseded}`,
         snapshot.summary.headPrNumber ? `Head PR: #${snapshot.summary.headPrNumber}` : "Head PR: none",
         ...formatRuntimeActivity(snapshot.runtime),
         ...(snapshot.runtime.lastTickOutcome === "failed"

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/db/schema.js

@@ -6,6 +6,7 @@ export function ensureSchema(connection) {
   `).all();
     if (existingTables.length > 0) {
         assertCurrentSchema(connection);
+        ensureActiveEntryIndex(connection);
         return;
     }
     connection.exec(`
@@ -80,14 +81,27 @@ export function ensureSchema(connection) {
     CREATE INDEX IF NOT EXISTS idx_queue_events_entry
       ON queue_events(entry_id, id)
   `);
-    // Must match TERMINAL_STATUSES in types.ts: merged, evicted, dequeued
-    connection.exec(`
-    CREATE UNIQUE INDEX IF NOT EXISTS idx_one_active_per_pr
-      ON queue_entries(repo_id, pr_number)
-      WHERE status NOT IN ('merged', 'evicted', 'dequeued')
-  `);
+    ensureActiveEntryIndex(connection);
     assertCurrentSchema(connection);
 }
+function ensureActiveEntryIndex(connection) {
+    // Must match TERMINAL_STATUSES in types.ts. Recreate this partial index so
+    // an existing database learns about newly-added terminal states.
+    const current = connection.prepare(`
+    SELECT sql FROM sqlite_master
+    WHERE type = 'index' AND name = 'idx_one_active_per_pr'
+  `).get();
+    if (String(current?.sql ?? "").toLowerCase().includes("'superseded'"))
+        return;
+    connection.transaction(() => {
+        connection.exec(`DROP INDEX IF EXISTS idx_one_active_per_pr`);
+        connection.exec(`
+      CREATE UNIQUE INDEX idx_one_active_per_pr
+        ON queue_entries(repo_id, pr_number)
+        WHERE status NOT IN ('merged', 'evicted', 'dequeued', 'superseded')
+    `);
+    })();
+}
 const QUEUE_ENTRY_COLUMNS = [
     "id", "repo_id", "pr_number", "branch", "head_sha", "base_sha", "status",
     "position", "priority", "generation", "ci_run_id", "ci_retries",

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

@@ -1,5 +1,11 @@
 import type { GitHubPRApi } from "../interfaces.ts";
 import type { CheckResult, PRStatus } from "../types.ts";
+export declare function hasApprovalForHead(reviews: Array<{
+    state?: string;
+    commit?: {
+        oid?: string;
+    };
+}> | undefined, headSha: string): boolean;
 /**
  * GitHub PR operations via gh CLI and REST API.
  *

package/dist/github/pr-client.js

@@ -1,5 +1,8 @@
 import { mapGitHubCheckConclusion } from "../check-policy.js";
 import { exec } from "../exec.js";
+export function hasApprovalForHead(reviews, headSha) {
+    return (reviews ?? []).some((review) => review.state === "APPROVED" && review.commit?.oid === headSha);
+}
 /**
  * GitHub PR operations via gh CLI and REST API.
  *
@@ -26,7 +29,7 @@ export class GitHubPRClient {
             "pr", "view", String(prNumber),
             "--repo", this.repoFullName,
             // The base ref lets admission detect stacked PRs.
-            "--json", "number,title,headRefName,headRefOid,baseRefName,reviewDecision,state,mergeStateStatus",
+            "--json", "number,title,headRefName,headRefOid,baseRefName,reviewDecision,reviews,state,mergeStateStatus",
         ], { githubRepoFullName: this.repoFullName });
         const data = JSON.parse(result.stdout);
         return {
@@ -38,7 +41,8 @@ export class GitHubPRClient {
             mergeable: data.state === "OPEN",
             mergeStateStatus: data.mergeStateStatus,
             reviewDecision: data.reviewDecision,
-            reviewApproved: data.reviewDecision === "APPROVED",
+            reviewApproved: data.reviewDecision === "APPROVED"
+                && hasApprovalForHead(data.reviews, data.headRefOid),
             merged: data.state === "MERGED",
         };
     }

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/reconciler-evict.d.ts

@@ -2,6 +2,8 @@ import type { FailureClass, QueueEntry } from "./types.ts";
 import type { ReconcileContext } from "./reconciler-core.ts";
 export declare function cleanupCandidate(ctx: ReconcileContext, entry: QueueEntry): Promise<void>;
 export declare function invalidateDownstream(ctx: ReconcileContext, allActive: QueueEntry[], afterIndex: number): Promise<void>;
+/** Retire the immutable admission when GitHub exposes a different PR head. */
+export declare function supersedeAdmittedHead(ctx: ReconcileContext, entry: QueueEntry, newHeadSha: string): Promise<void>;
 export declare function evictEntry(ctx: ReconcileContext, entry: QueueEntry, failureClass: FailureClass, extra?: {
     conflictFiles?: string[];
     failedChecks?: Array<{

package/dist/reconciler-evict.js

@@ -17,6 +17,26 @@ export async function invalidateDownstream(ctx, allActive, afterIndex) {
         ctx.store.transition(downstream.id, "preparing_head", INVALIDATION_PATCH, "invalidated: base changed");
     }
 }
+/** Retire the immutable admission when GitHub exposes a different PR head. */
+export async function supersedeAdmittedHead(ctx, entry, newHeadSha) {
+    const allActive = ctx.store.listActive(ctx.repoId);
+    const index = allActive.findIndex((candidate) => candidate.id === entry.id);
+    emit(ctx, entry, "branch_mismatch", {
+        detail: `admitted head ${entry.headSha.slice(0, 12)} superseded by ${newHeadSha.slice(0, 12)}`,
+    });
+    await cleanupCandidate(ctx, entry);
+    ctx.store.transition(entry.id, "superseded", {
+        ...CLEAN_CANDIDATE_REF,
+        candidateKind: null,
+        candidatePolicyFingerprint: null,
+        candidateSha: null,
+        ciRunId: null,
+        ciRetries: 0,
+        waitDetail: null,
+    }, `admitted head ${entry.headSha.slice(0, 12)} superseded by ${newHeadSha.slice(0, 12)}; new head must pass admission`);
+    if (index >= 0)
+        await invalidateDownstream(ctx, allActive, index);
+}
 export async function evictEntry(ctx, entry, failureClass, extra) {
     await cleanupCandidate(ctx, entry);
     let baseSha = entry.baseSha;

package/dist/reconciler-merge.js

@@ -1,5 +1,5 @@
 import { CLEAN_CANDIDATE_REF, CLEAN_CI, CLEAR_CANDIDATE, emit, isBudgetExhausted, ref } from "./reconciler-core.js";
-import { cleanupCandidate, evictEntry, invalidateDownstream } from "./reconciler-evict.js";
+import { cleanupCandidate, evictEntry, invalidateDownstream, supersedeAdmittedHead } 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";
@@ -157,11 +157,7 @@ export async function mergeHead(ctx, entry) {
         return;
     }
     if (prStatus.headSha !== entry.headSha) {
-        emit(ctx, entry, "branch_mismatch", { detail: `PR head: expected ${entry.headSha.slice(0, 8)}, got ${prStatus.headSha.slice(0, 8)}` });
-        const allActive = ctx.store.listActive(ctx.repoId);
-        await cleanupCandidate(ctx, entry);
-        ctx.store.updateHead(entry.id, prStatus.headSha);
-        await invalidateDownstream(ctx, allActive, 0);
+        await supersedeAdmittedHead(ctx, entry, prStatus.headSha);
         return;
     }
     const liveBaseRefName = prStatus.baseRefName ?? ctx.baseBranch;
@@ -243,13 +239,7 @@ export async function mergeHead(ctx, entry) {
             return;
         }
         if (landingPrStatus.headSha !== entry.headSha) {
-            emit(ctx, entry, "branch_mismatch", {
-                detail: `PR head changed during landing: expected ${entry.headSha.slice(0, 8)}, got ${landingPrStatus.headSha.slice(0, 8)}`,
-            });
-            const allActive = ctx.store.listActive(ctx.repoId);
-            await cleanupCandidate(ctx, entry);
-            ctx.store.updateHead(entry.id, landingPrStatus.headSha);
-            await invalidateDownstream(ctx, allActive, 0);
+            await supersedeAdmittedHead(ctx, entry, landingPrStatus.headSha);
             return;
         }
         const landingBaseRefName = landingPrStatus.baseRefName ?? ctx.baseBranch;

package/dist/reconciler-prepare.js

@@ -1,5 +1,5 @@
 import { CLEAN_CI, CLEAR_CANDIDATE, emit, ref, candidateRefName } from "./reconciler-core.js";
-import { evictEntry } from "./reconciler-evict.js";
+import { evictEntry, supersedeAdmittedHead } 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");
@@ -23,8 +23,7 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
     const baseSha = await ctx.git.headSha(base);
     const currentRef = await ctx.git.headSha(ref(ctx, entry.branch));
     if (currentRef !== entry.headSha) {
-        emit(ctx, entry, "branch_mismatch", { detail: `expected ${entry.headSha.slice(0, 8)}, got ${currentRef.slice(0, 8)}` });
-        ctx.store.updateHead(entry.id, currentRef);
+        await supersedeAdmittedHead(ctx, entry, currentRef);
         return;
     }
     if (isHead) {

package/dist/reconciler-sanitize.js

@@ -1,5 +1,5 @@
 import { CLEAN_CANDIDATE_REF, emit } from "./reconciler-core.js";
-import { cleanupCandidate } from "./reconciler-evict.js";
+import { cleanupCandidate, supersedeAdmittedHead } from "./reconciler-evict.js";
 import { verifyPostMergeStatus } from "./reconciler-post-merge.js";
 export async function sanitizeEntry(ctx, entry) {
     const canonical = ctx.store.getEntryByPR(ctx.repoId, entry.prNumber);
@@ -31,6 +31,10 @@ export async function sanitizeEntry(ctx, entry) {
             }, "merged externally (sanitize)");
             return true;
         }
+        if (prStatus.headSha !== entry.headSha) {
+            await supersedeAdmittedHead(ctx, entry, prStatus.headSha);
+            return true;
+        }
         const liveBaseRefName = prStatus.baseRefName ?? ctx.baseBranch;
         const recordedBaseRefName = entry.baseRefName ?? ctx.baseBranch;
         if (liveBaseRefName !== recordedBaseRefName) {

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

@@ -63,7 +63,7 @@ export async function reconcile(ctx) {
         // spec, so our cumulative spec is still valid (speculative consistency).
         if (entry.candidateBasedOn) {
             const dep = ctx.store.getEntry(entry.candidateBasedOn);
-            if (!dep || dep.status === "dequeued" || dep.status === "evicted") {
+            if (!dep || dep.status === "dequeued" || dep.status === "evicted" || dep.status === "superseded") {
                 emit(ctx, entry, "invalidated", {
                     detail: `dependency ${entry.candidateBasedOn} is ${dep?.status ?? "removed"}`,
                 });

package/dist/service-queue.js

@@ -140,6 +140,10 @@ export class MergeStewardQueueCommands {
         }
         try {
             const status = await this.github.getStatus(prNumber);
+            if (status.headSha !== headSha) {
+                this.logger.debug({ prNumber, eventHeadSha: headSha, liveHeadSha: status.headSha }, "Admission wakeup refers to a stale PR head");
+                return false;
+            }
             if (!status.reviewApproved) {
                 this.logger.debug({ prNumber, reviewDecision: status.reviewDecision }, "PR review gate is not satisfied, skipping admission");
                 return false;
@@ -147,42 +151,17 @@ export class MergeStewardQueueCommands {
             // Admission and ordering are derived from review/check/PR truth. Labels
             // remain available for presentation but are not control inputs.
             const priority = 0;
-            const checks = await this.github.listChecks(prNumber);
+            const checks = await this.github.listChecksForRef(status.headSha);
             const requiredCheckRules = this.policy.getRequiredCheckRules();
-            if (requiredCheckRules.length > 0) {
-                const evaluation = evaluateCheckPolicy(requiredCheckRules, false, checks);
-                if (evaluation.status !== "pass") {
-                    this.logger.debug({
-                        prNumber,
-                        checkNames: checks.map((check) => check.name),
-                        requiredChecks: requiredCheckRules.map(formatRequiredCheck),
-                        checkPolicyStatus: evaluation.status,
-                    }, "Required checks not all green");
-                    return false;
-                }
-            }
-            else if (this.policy.shouldRequireAllChecksOnEmptyRequiredSet()) {
-                if (checks.length === 0) {
-                    this.logger.debug({ prNumber }, "GitHub requires checks but none are visible yet, skipping admission");
-                    return false;
-                }
-                const hasPending = checks.some((check) => check.conclusion === "pending");
-                const hasFailures = checks.some((check) => check.conclusion === "failure");
-                if (hasPending || hasFailures) {
-                    this.logger.debug({
-                        prNumber,
-                        checkNames: checks.map((check) => `${check.name}:${check.conclusion}`),
-                    }, "GitHub requires all observed checks to pass before admission");
-                    return false;
-                }
-            }
-            else {
-                const nonSteward = checks.filter((c) => !c.name.startsWith("merge-steward"));
-                const hasGreen = nonSteward.some((c) => c.conclusion === "success");
-                if (!hasGreen) {
-                    this.logger.debug({ prNumber }, "No green CI checks, skipping admission");
-                    return false;
-                }
+            const evaluation = evaluateCheckPolicy(requiredCheckRules, this.policy.shouldRequireAllChecksOnEmptyRequiredSet(), checks);
+            if (evaluation.status !== "pass") {
+                this.logger.debug({
+                    prNumber,
+                    checks: checks.map((check) => `${check.name}:${check.conclusion}`),
+                    requiredChecks: requiredCheckRules.map(formatRequiredCheck),
+                    checkPolicyStatus: evaluation.status,
+                }, "Branch checks are not settled green, skipping admission");
+                return false;
             }
             // A stacked PR waits for its parent queue entry. Monotonic positions
             // guarantee parent-before-child ordering, not strict adjacency.
@@ -228,8 +207,22 @@ export class MergeStewardQueueCommands {
                 this.logger.debug({ prNumber, entryId: entry.id, headSha }, "Ignoring synchronize webhook for unchanged head");
                 return;
             }
-            this.store.updateHead(entry.id, headSha);
-            this.logger.info({ prNumber, entryId: entry.id, headSha }, "PR head updated via webhook");
+            if (entry.candidateRef) {
+                this.specBuilder.deleteSpeculative(entry.candidateRef).catch(() => { });
+            }
+            this.store.transition(entry.id, "superseded", {
+                candidateKind: null,
+                candidatePolicyFingerprint: null,
+                candidateRef: null,
+                candidateSha: null,
+                candidateBasedOn: null,
+                ciRunId: null,
+                ciRetries: 0,
+                waitDetail: null,
+            }, `admitted head ${entry.headSha.slice(0, 12)} superseded by ${headSha.slice(0, 12)}; new head must pass admission`);
+            this.invalidateDownstreamOf(entry);
+            this.clearQueueStateLabels(prNumber).catch(() => { });
+            this.logger.info({ prNumber, entryId: entry.id, previousHeadSha: entry.headSha, headSha }, "PR head changed; admission revoked");
         }
     }
     async acknowledgeExternalMerge(prNumber) {
@@ -275,10 +268,10 @@ export class MergeStewardQueueCommands {
             if (downstream.candidateRef) {
                 this.specBuilder.deleteSpeculative(downstream.candidateRef).catch(() => { });
             }
-            this.store.transition(downstream.id, "preparing_head", INVALIDATION_PATCH, `invalidated: entry ${removedEntry.id.slice(0, 8)} dequeued`);
+            this.store.transition(downstream.id, "preparing_head", INVALIDATION_PATCH, `invalidated: entry ${removedEntry.id.slice(0, 8)} left the train`);
         }
         if (targets.length > 0) {
-            this.logger.info({ removedEntryId: removedEntry.id, invalidated: targets.length }, "Invalidated downstream entries after dequeue");
+            this.logger.info({ removedEntryId: removedEntry.id, invalidated: targets.length }, "Invalidated downstream entries after train removal");
         }
     }
     findAffectedEntriesAfterPriorityChange(before, after) {

package/dist/types.d.ts

@@ -9,9 +9,9 @@
  * Failure: any state → evicted (after retry budget exhausted).
  * Conflict retries are gated on base SHA change (non-spinning).
  *
- * Terminal states: merged, evicted, dequeued.
+ * Terminal states: merged, evicted, dequeued, superseded.
  */
-export type QueueEntryStatus = "queued" | "preparing_head" | "validating" | "merging" | "evicted" | "merged" | "dequeued";
+export type QueueEntryStatus = "queued" | "preparing_head" | "validating" | "merging" | "evicted" | "merged" | "dequeued" | "superseded";
 export declare const TERMINAL_STATUSES: QueueEntryStatus[];
 export type PostMergeStatus = "pending" | "pass" | "fail" | "unknown";
 export type CandidateKind = "head" | "integration" | "integration_repair";
@@ -66,7 +66,7 @@ export interface QueueEntry {
     updatedAt: string;
     /**
      * Set once, when the entry first reaches a terminal status
-     * (merged/evicted/dequeued), and never bumped afterward — unlike
+     * (merged/evicted/dequeued/superseded), and never bumped afterward — unlike
      * updatedAt, which post-merge re-verification keeps moving. Lets the
      * dashboard report an accurate "how long it took" (decidedAt - enqueuedAt)
      * and "how long ago" (now - decidedAt). Null while still in flight.
@@ -185,6 +185,7 @@ export interface QueueStatusSummary {
     merged: number;
     evicted: number;
     dequeued: number;
+    superseded: number;
     headEntryId: string | null;
     headPrNumber: number | null;
 }

package/dist/types.js

@@ -1 +1 @@
-export const TERMINAL_STATUSES = ["merged", "evicted", "dequeued"];
+export const TERMINAL_STATUSES = ["merged", "evicted", "dequeued", "superseded"];

package/dist/watch/dashboard-model.js

@@ -59,6 +59,8 @@ function entryKind(entry) {
             return "error";
         case "dequeued":
             return "cancelled";
+        case "superseded":
+            return "cancelled";
     }
 }
 function entryPhrase(entry, isHead) {
@@ -87,6 +89,8 @@ function entryPhrase(entry, isHead) {
             return "evicted";
         case "dequeued":
             return "dequeued";
+        case "superseded":
+            return "superseded by a newer PR head";
     }
 }
 function entrySummary(entry) {
@@ -130,7 +134,7 @@ function repoEntriesFromSnapshot(snapshot, cutoff, now) {
         const active = isActive(entry.status);
         if (!active && timestamp(entry.updatedAt) < cutoff)
             continue;
-        if (entry.status === "dequeued")
+        if (entry.status === "dequeued" || entry.status === "superseded")
             continue;
         const isHead = head !== null && entry.id === head.id;
         const kind = entryKind(entry);
@@ -325,6 +329,7 @@ export function buildQueueSummary(entries) {
         merged: 0,
         evicted: 0,
         dequeued: 0,
+        superseded: 0,
         headEntryId: null,
         headPrNumber: null,
     };
@@ -357,6 +362,9 @@ export function buildQueueSummary(entries) {
             case "dequeued":
                 summary.dequeued += 1;
                 break;
+            case "superseded":
+                summary.superseded += 1;
+                break;
         }
     }
     return summary;

package/dist/watch/format.js

@@ -72,6 +72,7 @@ export function statusColor(status, entry) {
         case "evicted":
             return "red";
         case "dequeued":
+        case "superseded":
             return "gray";
     }
 }
@@ -99,6 +100,8 @@ export function humanStatus(status, entry) {
             return "needs repair";
         case "dequeued":
             return "removed";
+        case "superseded":
+            return "superseded";
     }
 }
 export function queueProgress(status) {
@@ -113,6 +116,7 @@ export function queueProgress(status) {
         case "merged":
         case "evicted":
         case "dequeued":
+        case "superseded":
             return { current: 4, total: 4 };
     }
 }
@@ -142,6 +146,8 @@ export function nextStepLabel(status, entry) {
             return "needs branch repair before re-admission";
         case "dequeued":
             return "removed from queue";
+        case "superseded":
+            return "new PR head must pass approval and branch CI before admission";
     }
 }
 /** Describe the immutable candidate chain for a queue entry. */
@@ -173,6 +179,7 @@ const STATUS_DISPLAY = {
     merged: "merged",
     evicted: "evicted",
     dequeued: "removed",
+    superseded: "superseded",
 };
 function displayStatus(status) {
     return STATUS_DISPLAY[status] ?? status;
@@ -233,6 +240,9 @@ export function formatEventNarrative(event, options = {}) {
     if (event.toStatus === "dequeued") {
         return withDetail(`${prPrefix}was removed from the queue.`, event.detail);
     }
+    if (event.toStatus === "superseded") {
+        return withDetail(`${prPrefix}left the queue because its admitted head changed.`, event.detail);
+    }
     if (event.toStatus === "queued" && event.fromStatus) {
         return withDetail(`${prPrefix}was re-queued for another attempt.`, event.detail);
     }

package/dist/webhook-handler.js

@@ -129,7 +129,8 @@ export async function processWebhookEvent(event, service, config, logger) {
             break;
         }
         case "pr_synchronize": {
-            // PR was force-pushed. Update head if queued.
+            // A queued admission is immutable. Retire it when the PR head changes;
+            // the new head may re-enter only after its own approval and green CI.
             service.updateHeadByPR(event.prNumber, event.headSha);
             break;
         }

package/package.json

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