merge-steward 0.34.4 → 0.35.1

package/README.md

@@ -2,7 +2,9 @@
 
 Self-hosted merge queue for bot-managed and human-managed GitHub pull requests. Merge Steward turns reviewed PRs into a tested landing train: it runs CI on the exact future `main` SHAs, validates several PRs in parallel, and fast-forwards through the green sequence as soon as it is safe.
 
-Independent of PatchRelay. Communicates through GitHub only — PRs, reviews, checks, labels, branches. Pairs with `review-quill`; neither requires the other.
+Independent of PatchRelay. Communicates through GitHub state only — PRs,
+reviews, candidate refs, ancestry, and checks. Labels and comments are not
+control messages. Pairs with `review-quill`; neither requires the other.
 
 For the background story and design trade-offs, read [merge-steward: speculative integration, parallel validation, fast-forward landing](https://blog.krasnoperov.me/posts/merge-steward).
 
@@ -13,12 +15,24 @@ 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 resolves the exact future-`main` candidate. If the prospective base is an ancestor of the PR head, the candidate is that already-tested head SHA. Otherwise it builds a cumulative integration commit.
+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
+   candidate. Otherwise it publishes
+   `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.
-6. On CI failure: retry (gated on base SHA change), then evict with a durable incident record and GitHub check run.
-7. PatchRelay, the `ship-pr` skill, or any agent sees the check run failure and fixes the branch; when CI passes again the PR can be re-admitted.
+   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
+   branch. Review Quill verifies only that an agent repair preserved the
+   approved feature.
+8. Ordinary integration failures retain queue position. Feature implementation
+   reopens only when integration review proves the feature must change.
 
 This is structural, not an optional fast path. An exact head is safe precisely
 when it already contains the prospective base; if it does not, Merge Steward
@@ -26,7 +40,10 @@ creates and tests the integration candidate. Checks never move between SHAs.
 
 ## Use with your own agent
 
-For an agent that drives PRs through the queue and reacts to evictions / failing checks without running PatchRelay's full harness, install the [`ship-pr`](https://github.com/krasnoperov/patchrelay-agents) skill from the companion Claude Code marketplace:
+For an agent that drives PRs through the queue and reacts to candidate state and
+failing checks without running PatchRelay's full harness, install the
+[`ship-pr`](https://github.com/krasnoperov/patchrelay-agents) skill from the
+companion Claude Code marketplace:
 
 ```
 /plugin marketplace add krasnoperov/patchrelay-agents
@@ -73,7 +90,7 @@ Each repository reconcile tick is bounded by `reconcileStaleAfterMs` (five minut
 | Code | Meaning |
 |-|-|
 | 0 | merged / approved with green required checks |
-| 2 | changes_requested / failing required checks / evicted / closed |
+| 2 | changes_requested / integration review requires feature rework / policy failure / closed |
 | 3 | still in flight (queued, preparing, validating, merging, pending) |
 | 4 | `--wait` timed out |
 | 1 | usage or configuration error |
@@ -95,10 +112,14 @@ The real gate is:
 
 Independent services, GitHub as the shared bus:
 
-1. PatchRelay moves an issue to `awaiting_queue` when the linked PR is approved and green, and may add the configured queue label as an admission nudge.
-2. The steward admits from fresh GitHub truth, lands the PR, or evicts and creates the eviction check run (default `merge-steward/queue`).
-3. PatchRelay watches for that check run failure and triggers `queue_repair`.
-4. After repair, PatchRelay pushes a new head; the steward re-admits only after the new head is approved and green.
+1. The steward admits an open PR when GitHub shows an approved head and green
+   branch checks; no label is required.
+2. It publishes a self-describing candidate ref. Missing approved-head ancestry
+   means conflict repair; settled red candidate checks mean test repair.
+3. PatchRelay derives either condition from GitHub and non-force pushes only the
+   candidate ref.
+4. Review Quill publishes `review-quill/integration` when PatchRelay changed the
+   candidate. The steward lands the exact green SHA when that check is satisfied.
 
 Neither service calls the other's API.
 

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/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/check-run-reporter.js

@@ -87,6 +87,8 @@ function formatTitle(incident) {
             return "Queue eviction: CI failure (branch-specific)";
         case "main_broken":
             return "Queue eviction: main branch CI failing";
+        case "feature_changed":
+            return "Queue eviction: integration repair changed the approved feature";
         case "policy_blocked":
             return incident.context.openPrAncestors?.length
                 ? "Queue eviction: candidate shares unlanded history with another open PR"

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/github/shell-git.d.ts

@@ -26,6 +26,7 @@ export declare class ShellGitOperations implements GitOperations, SpeculativeBra
     mergeBase(left: string, right: string): Promise<string>;
     isAncestor(ancestor: string, descendant: string): Promise<boolean>;
     push(branch: string, force?: boolean, targetBranch?: string): Promise<void>;
+    createWorkspace(specName: string, baseBranch: string): Promise<string>;
     /**
      * Build a speculative merge branch using an isolated git worktree.
      * Each call gets its own working directory — no shared mutable state.

package/dist/github/shell-git.js

@@ -1,5 +1,5 @@
 import { mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { exec } from "../exec.js";
 /** Extract conflict file names from git merge stderr. */
 function parseConflicts(stderr) {
@@ -98,6 +98,17 @@ export class ShellGitOperations {
         await this.git(args, { timeoutMs: 60_000 });
     }
     // ─── SpeculativeBranchBuilder ───────────────────────────────
+    async createWorkspace(specName, baseBranch) {
+        const wtPath = join(this.worktreeBase, specName);
+        await this.git(["worktree", "remove", "--force", wtPath], { allowNonZero: true });
+        await this.git(["branch", "-D", specName], { allowNonZero: true });
+        await this.git(["worktree", "prune"], { allowNonZero: true });
+        mkdirSync(dirname(wtPath), { recursive: true });
+        await this.git(["worktree", "add", "-B", specName, wtPath, baseBranch]);
+        const sha = (await this.gitIn(wtPath, ["rev-parse", "HEAD"])).stdout.trim();
+        await this.git(["worktree", "remove", "--force", wtPath], { allowNonZero: true });
+        return sha;
+    }
     /**
      * Build a speculative merge branch using an isolated git worktree.
      * Each call gets its own working directory — no shared mutable state.
@@ -111,7 +122,7 @@ export class ShellGitOperations {
         await this.git(["branch", "-D", specName], { allowNonZero: true });
         await this.git(["worktree", "prune"], { allowNonZero: true });
         // Create isolated worktree with spec branch starting at baseBranch.
-        mkdirSync(this.worktreeBase, { recursive: true });
+        mkdirSync(dirname(wtPath), { recursive: true });
         await this.git(["worktree", "add", "-B", specName, wtPath, baseBranch]);
         // Override git identity so merge commits are attributed to the steward, not the clone owner.
         if (this.botIdentity) {
@@ -137,7 +148,9 @@ export class ShellGitOperations {
             }
             await this.gitIn(wtPath, ["merge", "--abort"], { allowNonZero: true });
             await this.git(["worktree", "remove", "--force", wtPath], { allowNonZero: true });
-            await this.git(["branch", "-D", specName], { allowNonZero: true });
+            // Keep the workspace branch at the prospective base. Publishing this
+            // ref is the cross-service repair signal: it exists, but does not yet
+            // contain the approved PR head.
             return { success: false, conflictFiles };
         }
         const sha = (await this.gitIn(wtPath, ["rev-parse", "HEAD"])).stdout.trim();

package/dist/interfaces.d.ts

@@ -15,6 +15,8 @@ export interface GitOperations {
  * Separate from GitOperations to keep the core interface minimal.
  */
 export interface SpeculativeBranchBuilder {
+    /** Create/reset a candidate workspace at an exact base commit. */
+    createWorkspace(specName: string, baseBranch: string): Promise<string>;
     /** Merge prBranch into baseBranch, store result as specName. */
     buildSpeculative(prBranch: string, baseBranch: string, specName: string, mergeMessage?: string): Promise<MergeResult>;
     /** Delete a speculative branch (cleanup after merge/eviction). */

package/dist/reconciler-core.d.ts

@@ -24,7 +24,8 @@ export interface ReconcileContext {
     };
     onEvent: (event: ReconcileEvent) => void;
 }
-export declare const CANDIDATE_REF_PREFIX = "mq-spec-";
+export declare const CANDIDATE_REF_PREFIX = "merge-steward";
+export declare const INTEGRATION_REVIEW_CHECK = "review-quill/integration";
 export declare const FAILED_CONCLUSIONS: Set<string>;
 export declare const CLEAR_CANDIDATE: {
     readonly candidateKind: null;
@@ -44,6 +45,6 @@ export declare const CLEAN_CI: {
 };
 export declare function emit(ctx: ReconcileContext, entry: QueueEntry, action: ReconcileAction, extra?: Partial<ReconcileEvent>): void;
 export declare function ref(ctx: ReconcileContext, name: string): string;
-export declare function candidateRefName(entryId: string): string;
+export declare function candidateRefName(baseBranch: string, prNumber: number): string;
 export declare function isBudgetExhausted(entry: QueueEntry): boolean;
 export declare function isRetryGated(entry: QueueEntry, currentBaseSha: string): boolean;

package/dist/reconciler-core.js

@@ -1,4 +1,5 @@
-export const CANDIDATE_REF_PREFIX = "mq-spec-";
+export const CANDIDATE_REF_PREFIX = "merge-steward";
+export const INTEGRATION_REVIEW_CHECK = "review-quill/integration";
 export const FAILED_CONCLUSIONS = new Set(["failure"]);
 export const CLEAR_CANDIDATE = {
     candidateKind: null,
@@ -16,8 +17,8 @@ export function emit(ctx, entry, action, extra) {
 export function ref(ctx, name) {
     return ctx.remotePrefix + name;
 }
-export function candidateRefName(entryId) {
-    return `${CANDIDATE_REF_PREFIX}${entryId}`;
+export function candidateRefName(baseBranch, prNumber) {
+    return `${CANDIDATE_REF_PREFIX}/${baseBranch}/pr-${prNumber}`;
 }
 export function isBudgetExhausted(entry) {
     return entry.retryAttempts >= entry.maxRetries;

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,17 +1,29 @@
-import { CLEAN_CI, CLEAR_CANDIDATE, emit, isRetryGated, ref, candidateRefName } from "./reconciler-core.js";
-import { evictEntry } from "./reconciler-evict.js";
+import { CLEAN_CI, CLEAR_CANDIDATE, emit, ref, candidateRefName } from "./reconciler-core.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");
     await ctx.git.fetch();
+    const predecessorNeedsRepair = prevEntry?.lastFailedBaseSha !== null
+        && prevEntry?.lastFailedBaseSha !== undefined
+        && prevEntry?.ciRunId !== null
+        && prevEntry?.ciRunId !== undefined;
+    if (prevEntry?.candidateSha && (predecessorNeedsRepair
+        || !await ctx.git.isAncestor(prevEntry.headSha, prevEntry.candidateSha))) {
+        const detail = `predecessor PR #${prevEntry.prNumber} is awaiting integration repair`;
+        if (entry.waitDetail !== detail) {
+            emit(ctx, entry, "stack_dependency_waiting", { detail });
+            ctx.store.transition(entry.id, "preparing_head", { waitDetail: detail }, detail);
+        }
+        return;
+    }
     const base = isHead ? ref(ctx, ctx.baseBranch) : prevEntry?.candidateSha ?? null;
     if (!base)
         return;
     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) {
@@ -33,24 +45,6 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
     // Preparing/validating the head never waits on main's CI. The exact
     // candidate includes current main and is gated solely by its own checks.
     //
-    // The conflict cache applies at every lookahead depth. A downstream child
-    // otherwise rebuilds the same impossible merge on every reconcile tick
-    // while its predecessor is still validating.
-    if (isRetryGated(entry, baseSha)) {
-        emit(ctx, entry, "retry_gated", {
-            baseSha,
-            detail: "same base and head already produced a deterministic conflict",
-        });
-        if (isHead) {
-            await evictEntry(ctx, entry, "integration_conflict");
-        }
-        else if (entry.waitDetail !== "deterministic conflict; waiting for prospective base to change") {
-            ctx.store.transition(entry.id, "preparing_head", {
-                waitDetail: "deterministic conflict; waiting for prospective base to change",
-            }, "deterministic conflict cached; waiting for prospective base to change");
-        }
-        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.
@@ -92,7 +86,7 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
         }, `head candidate ${entry.headSha.slice(0, 12)} selected on ${baseSha.slice(0, 12)}`);
         return;
     }
-    const specName = candidateRefName(entry.id);
+    const specName = candidateRefName(ctx.baseBranch, entry.prNumber);
     emit(ctx, entry, "integration_build_started", { candidateRef: specName, baseSha, ...(prevEntry ? { dependsOn: prevEntry.id } : {}) });
     const branchSuffix = entry.branch.replace(/^.*\//, "").replace(/-/g, " ");
     const mergeMessage = `Merge PR #${entry.prNumber}: ${branchSuffix}`;
@@ -115,17 +109,21 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
     }
     if (!result.success) {
         emit(ctx, entry, "integration_build_conflict", { baseSha, conflictFiles: result.conflictFiles });
-        if (isHead) {
-            await evictEntry(ctx, entry, "integration_conflict", result.conflictFiles ? { conflictFiles: result.conflictFiles } : undefined);
-        }
-        else {
-            ctx.store.transition(entry.id, "preparing_head", {
-                baseSha,
-                lastFailedBaseSha: baseSha,
-                ...CLEAN_CI,
-                ...CLEAR_CANDIDATE,
-            }, `deterministic conflict cached for ${baseSha.slice(0, 8)} and head ${entry.headSha.slice(0, 8)}`);
-        }
+        // buildSpeculative deliberately leaves the local workspace ref at the
+        // prospective base. Publish it so PatchRelay can derive the repair from
+        // GitHub ancestry alone and add a merge commit with a non-force push.
+        await ctx.git.push(specName, true);
+        ctx.store.transition(entry.id, "validating", {
+            baseSha,
+            ...CLEAN_CI,
+            candidateKind: "integration",
+            candidatePolicyFingerprint: ctx.policy.getFingerprint(),
+            candidateRef: specName,
+            candidateSha: baseSha,
+            candidateBasedOn: isHead ? null : prevEntry.id,
+            lastFailedBaseSha: baseSha,
+            waitDetail: `integration conflict; workspace awaits repair${result.conflictFiles?.length ? ` in ${result.conflictFiles.join(", ")}` : ""}`,
+        }, `integration workspace published at ${baseSha.slice(0, 12)} for conflict repair`);
         return;
     }
     const candidateSha = result.sha ?? entry.headSha;

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

@@ -1,22 +1,104 @@
-import { emit, ref } from "./reconciler-core.js";
-import { classifyFailure } from "./classify.js";
+import { CLEAN_CI, CLEAR_CANDIDATE, INTEGRATION_REVIEW_CHECK, candidateRefName, emit, ref } from "./reconciler-core.js";
 import { evictEntry, invalidateDownstream } from "./reconciler-evict.js";
 import { evaluateCheckPolicy, formatRequiredCheck } from "./check-policy.js";
-async function evictFailedCandidate(ctx, entry, allActive, index, checks) {
-    const failedChecks = checks
+async function holdForIntegrationRepair(ctx, entry, allActive, index, checks) {
+    let candidateRef = entry.candidateRef;
+    if (!candidateRef) {
+        candidateRef = candidateRefName(ctx.baseBranch, entry.prNumber);
+        await ctx.specBuilder.createWorkspace(candidateRef, entry.candidateSha ?? entry.headSha);
+        await ctx.git.push(candidateRef, true);
+    }
+    const failed = checks
         .filter((check) => check.conclusion === "failure" || check.conclusion === "skipped")
-        .map((check) => ({
-        name: check.name,
-        conclusion: check.conclusion,
-        ...(check.url ? { url: check.url } : {}),
-    }));
-    const mainChecks = await ctx.github.listChecksForRef(ref(ctx, ctx.baseBranch));
-    const failureClass = checks.some((check) => check.conclusion === "skipped")
-        ? "policy_blocked"
-        : classifyFailure(checks, mainChecks);
-    await evictEntry(ctx, entry, failureClass, { failedChecks });
-    if (index >= 0) {
+        .map((check) => check.name)
+        .join(", ");
+    ctx.store.transition(entry.id, "validating", {
+        candidateKind: "integration",
+        ciRunId: entry.ciRunId ?? `head:${entry.candidateSha ?? entry.headSha}`,
+        candidateRef,
+        candidateSha: entry.candidateSha ?? entry.headSha,
+        candidateBasedOn: entry.candidateBasedOn,
+        lastFailedBaseSha: entry.baseSha,
+        waitDetail: `candidate CI failed; integration workspace awaits repair${failed ? ` (${failed})` : ""}`,
+    }, "candidate retained for integration repair");
+    if (index >= 0)
         await invalidateDownstream(ctx, allActive, index);
+}
+async function refreshIntegrationWorkspace(ctx, entry, allActive, index) {
+    if (!entry.candidateRef)
+        return entry;
+    await ctx.git.fetch();
+    const liveSha = await ctx.git.headSha(ref(ctx, entry.candidateRef));
+    const dependency = entry.candidateBasedOn ? ctx.store.getEntry(entry.candidateBasedOn) : null;
+    const expectedBaseSha = dependency && dependency.status !== "merged"
+        ? dependency.candidateSha
+        : await ctx.git.headSha(ref(ctx, ctx.baseBranch));
+    if (!expectedBaseSha || !await ctx.git.isAncestor(expectedBaseSha, liveSha)) {
+        emit(ctx, entry, "invalidated", { detail: "integration workspace no longer descends from its prospective base" });
+        ctx.store.transition(entry.id, "preparing_head", { ...CLEAN_CI, ...CLEAR_CANDIDATE }, "stale integration workspace; rebuilding");
+        if (index >= 0)
+            await invalidateDownstream(ctx, allActive, index);
+        return null;
+    }
+    if (liveSha !== entry.candidateSha) {
+        emit(ctx, entry, "candidate_selected", {
+            candidateRef: entry.candidateRef,
+            candidateKind: "integration_repair",
+            candidateSha: liveSha,
+            baseSha: expectedBaseSha,
+            detail: "external non-force integration repair detected",
+        });
+        ctx.store.transition(entry.id, "validating", {
+            baseSha: expectedBaseSha,
+            ...CLEAN_CI,
+            candidateKind: "integration_repair",
+            candidatePolicyFingerprint: ctx.policy.getFingerprint(),
+            candidateRef: entry.candidateRef,
+            candidateSha: liveSha,
+            candidateBasedOn: entry.candidateBasedOn,
+            lastFailedBaseSha: entry.lastFailedBaseSha ?? entry.baseSha,
+            waitDetail: "integration repair detected; validating exact candidate",
+        }, `integration workspace advanced to ${liveSha.slice(0, 12)}`);
+        if (index >= 0)
+            await invalidateDownstream(ctx, allActive, index);
+        return ctx.store.getEntry(entry.id) ?? null;
+    }
+    return entry;
+}
+async function integrationReviewStatus(ctx, entry) {
+    if (entry.candidateKind !== "integration_repair")
+        return "pass";
+    const checks = await ctx.github.listChecksForRef(entry.candidateSha);
+    return evaluateCheckPolicy([{ name: INTEGRATION_REVIEW_CHECK, appId: null }], false, checks).status;
+}
+async function acceptPassingIntegrationCandidate(ctx, entry, allActive, index, isLandingHead, ciRunId) {
+    const reviewStatus = await integrationReviewStatus(ctx, entry);
+    if (reviewStatus === "pending") {
+        ctx.store.transition(entry.id, "validating", {
+            waitDetail: `waiting for ${INTEGRATION_REVIEW_CHECK} on repaired candidate`,
+        }, `waiting for ${INTEGRATION_REVIEW_CHECK}`);
+        return;
+    }
+    if (reviewStatus === "fail") {
+        await evictEntry(ctx, entry, "feature_changed");
+        if (index >= 0)
+            await invalidateDownstream(ctx, allActive, index);
+        return;
+    }
+    emit(ctx, entry, "ci_passed", {
+        ciRunId,
+        candidateKind: entry.candidateKind ?? undefined,
+        candidateSha: entry.candidateSha ?? undefined,
+        policyFingerprint: entry.candidatePolicyFingerprint ?? undefined,
+    });
+    if (isLandingHead) {
+        ctx.store.transition(entry.id, "merging", { lastFailedBaseSha: null, waitDetail: null }, "CI and integration review passed, ready to merge");
+    }
+    else if (entry.lastFailedBaseSha) {
+        ctx.store.transition(entry.id, "validating", {
+            lastFailedBaseSha: null,
+            waitDetail: null,
+        }, "integration repair validated for speculative descendants");
     }
 }
 async function requestBoundedRerun(ctx, entry, params) {
@@ -41,7 +123,7 @@ async function requestBoundedRerun(ctx, entry, params) {
             detail: `candidate rerun unavailable (${attempt}/${ctx.flakyRetries}): ${detail}`,
         });
         if (attempt >= ctx.flakyRetries) {
-            await evictFailedCandidate(ctx, entry, params.allActive, params.index, params.checks);
+            await holdForIntegrationRepair(ctx, entry, params.allActive, params.index, params.checks);
         }
         else {
             ctx.store.transition(entry.id, "validating", {
@@ -53,6 +135,18 @@ async function requestBoundedRerun(ctx, entry, params) {
     }
 }
 export async function checkValidation(ctx, entry, allActive, index, isLandingHead) {
+    const refreshed = await refreshIntegrationWorkspace(ctx, entry, allActive, index);
+    if (!refreshed)
+        return;
+    entry = refreshed;
+    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.
+        return;
+    }
     if (entry.candidateKind === "head") {
         const checks = await ctx.github.listChecksForRef(entry.candidateSha ?? entry.headSha);
         const evaluation = evaluateCheckPolicy(ctx.policy.getRequiredCheckRules(), ctx.policy.shouldRequireAllChecksOnEmptyRequiredSet(), checks);
@@ -83,7 +177,7 @@ export async function checkValidation(ctx, entry, allActive, index, isLandingHea
                 });
                 return;
             }
-            await evictFailedCandidate(ctx, entry, allActive, index, checks);
+            await holdForIntegrationRepair(ctx, entry, allActive, index, checks);
             return;
         }
         emit(ctx, entry, "ci_passed", {
@@ -100,6 +194,21 @@ export async function checkValidation(ctx, entry, allActive, index, isLandingHea
     if (!entry.ciRunId) {
         const branch = entry.candidateRef ?? entry.branch;
         const sha = entry.candidateSha ?? entry.headSha;
+        const existingChecks = (await ctx.github.listChecksForRef(sha))
+            .filter((check) => check.name.toLowerCase() !== INTEGRATION_REVIEW_CHECK);
+        if (existingChecks.length > 0) {
+            const evaluation = evaluateCheckPolicy(ctx.policy.getRequiredCheckRules(), ctx.policy.shouldRequireAllChecksOnEmptyRequiredSet(), existingChecks);
+            if (evaluation.status === "pass") {
+                await acceptPassingIntegrationCandidate(ctx, entry, allActive, index, isLandingHead, `checks:${sha}`);
+            }
+            else if (evaluation.status === "pending") {
+                emit(ctx, entry, "ci_pending", { detail: "existing exact-SHA checks pending" });
+            }
+            else {
+                await holdForIntegrationRepair(ctx, entry, allActive, index, existingChecks);
+            }
+            return;
+        }
         const runId = await ctx.ci.triggerRun(branch, sha);
         emit(ctx, entry, "ci_triggered", { ciRunId: runId });
         ctx.store.transition(entry.id, "validating", { ciRunId: runId }, `CI triggered: ${runId.slice(0, 12)}`);
@@ -111,15 +220,7 @@ export async function checkValidation(ctx, entry, allActive, index, isLandingHea
             emit(ctx, entry, "ci_pending", { ciRunId: entry.ciRunId });
             break;
         case "pass":
-            emit(ctx, entry, "ci_passed", {
-                ciRunId: entry.ciRunId,
-                candidateKind: entry.candidateKind ?? undefined,
-                candidateSha: entry.candidateSha ?? undefined,
-                policyFingerprint: entry.candidatePolicyFingerprint ?? undefined,
-            });
-            if (isLandingHead) {
-                ctx.store.transition(entry.id, "merging", undefined, "CI passed, ready to merge");
-            }
+            await acceptPassingIntegrationCandidate(ctx, entry, allActive, index, isLandingHead, entry.ciRunId);
             break;
         case "fail": {
             emit(ctx, entry, "ci_failed", { ciRunId: entry.ciRunId });
@@ -140,7 +241,7 @@ export async function checkValidation(ctx, entry, allActive, index, isLandingHea
             else {
                 const sha = entry.candidateSha ?? entry.headSha;
                 const checks = await ctx.github.listChecksForRef(sha);
-                await evictFailedCandidate(ctx, entry, allActive, index, checks);
+                await holdForIntegrationRepair(ctx, entry, allActive, index, checks);
             }
             break;
         }

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,54 +140,28 @@ 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;
             }
-            let labels = [];
-            try {
-                labels = await this.github.listLabels(prNumber);
-            }
-            catch (error) {
-                this.logger.debug({ prNumber, err: error }, "Could not read labels for priority detection; continuing without priority label");
-            }
-            const priority = labels.includes(this.config.priorityQueueLabel) ? 1 : 0;
-            const checks = await this.github.listChecks(prNumber);
+            // 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.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.
@@ -233,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) {
@@ -280,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,12 +9,12 @@
  * 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";
+export type CandidateKind = "head" | "integration" | "integration_repair";
 export interface QueueEntry {
     id: string;
     repoId: string;
@@ -66,14 +66,14 @@ 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.
      */
     decidedAt: string | null;
 }
-export type FailureClass = "main_broken" | "branch_local" | "integration_conflict" | "policy_blocked";
+export type FailureClass = "main_broken" | "branch_local" | "integration_conflict" | "feature_changed" | "policy_blocked";
 export type CheckConclusion = "success" | "failure" | "pending" | "neutral" | "skipped";
 export interface CheckResult {
     name: string;
@@ -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

@@ -109,22 +109,15 @@ export async function processWebhookEvent(event, service, config, logger) {
         case "pr_labeled": {
             if (event.label !== config.admissionLabel && event.label !== config.priorityQueueLabel)
                 return;
-            logger.info({ prNumber: event.prNumber, label: event.label }, "Queue label added, checking eligibility");
-            if (event.label === config.priorityQueueLabel && service.updatePriorityByPR(event.prNumber, 1)) {
-                break;
-            }
+            logger.info({ prNumber: event.prNumber, label: event.label }, "Presentation label changed, reconciling eligibility");
             await service.tryAdmit(event.prNumber, event.branch, event.headSha);
             break;
         }
         case "pr_unlabeled": {
-            if (event.label === config.priorityQueueLabel) {
-                service.updatePriorityByPR(event.prNumber, 0);
-                break;
-            }
-            if (event.label !== config.admissionLabel)
+            // Labels are presentation-only. Losing one must not dequeue, reorder,
+            // admit, or otherwise control the queue.
+            if (event.label !== config.admissionLabel && event.label !== config.priorityQueueLabel)
                 return;
-            // Label removed — dequeue if active.
-            service.dequeueByPR(event.prNumber);
             break;
         }
         case "pr_merged": {
@@ -136,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.34.4",
+  "version": "0.35.1",
   "description": "Serial merge queue for GitHub — rebase, CI-gate, and merge PRs one at a time",
   "type": "module",
   "repository": {