merge-steward 0.34.4 → 0.35.0

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).
 
@@ -14,11 +16,19 @@ The queue keeps delivery fast without pretending branch CI is always enough. For
 
 1. A PR becomes eligible when GitHub says it is approved and its required checks are green.
 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.
+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 +36,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 +86,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 +108,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/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/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-prepare.js

@@ -1,9 +1,22 @@
-import { CLEAN_CI, CLEAR_CANDIDATE, emit, isRetryGated, ref, candidateRefName } from "./reconciler-core.js";
+import { CLEAN_CI, CLEAR_CANDIDATE, emit, 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();
+    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;
@@ -33,24 +46,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 +87,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 +110,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-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/service-queue.js

@@ -144,14 +144,9 @@ export class MergeStewardQueueCommands {
                 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;
+            // 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 requiredCheckRules = this.policy.getRequiredCheckRules();
             if (requiredCheckRules.length > 0) {

package/dist/types.d.ts

@@ -14,7 +14,7 @@
 export type QueueEntryStatus = "queued" | "preparing_head" | "validating" | "merging" | "evicted" | "merged" | "dequeued";
 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;
@@ -73,7 +73,7 @@ export interface QueueEntry {
      */
     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;

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": {

package/package.json

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