merge-steward 0.5.5 → 0.6.0

package/dist/db/sqlite-store.js

@@ -97,6 +97,7 @@ export class SqliteStore {
     getEntryByPR(repoId, prNumber) {
         const row = this.conn.prepare(`SELECT * FROM queue_entries
        WHERE repo_id = ? AND pr_number = ? AND status NOT IN (${NOT_TERMINAL_SQL})
+       ORDER BY position ASC
        LIMIT 1`).get(repoId, prNumber, ...TERMINAL_STATUSES);
         return row ? mapEntry(row) : undefined;
     }

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

@@ -16,6 +16,7 @@ export declare class GitHubPRClient implements GitHubPRApi {
     getStatus(prNumber: number): Promise<PRStatus>;
     listChecks(prNumber: number): Promise<CheckResult[]>;
     listChecksForRef(ref: string): Promise<CheckResult[]>;
+    deleteBranch(prNumber: number): Promise<void>;
     findPRByBranch(branch: string): Promise<number | null>;
     listLabels(prNumber: number): Promise<string[]>;
 }

package/dist/github/pr-client.js

@@ -24,7 +24,7 @@ export class GitHubPRClient {
         const result = await exec("gh", [
             "pr", "view", String(prNumber),
             "--repo", this.repoFullName,
-            "--json", "number,headRefName,headRefOid,reviewDecision,state",
+            "--json", "number,headRefName,headRefOid,reviewDecision,state,mergeStateStatus",
         ], { githubRepoFullName: this.repoFullName });
         const data = JSON.parse(result.stdout);
         return {
@@ -32,6 +32,7 @@ export class GitHubPRClient {
             branch: data.headRefName,
             headSha: data.headRefOid,
             mergeable: data.state === "OPEN",
+            mergeStateStatus: data.mergeStateStatus,
             reviewApproved: data.reviewDecision === "APPROVED",
             merged: data.state === "MERGED",
         };
@@ -63,6 +64,13 @@ export class GitHubPRClient {
             return [];
         }
     }
+    async deleteBranch(prNumber) {
+        const status = await this.getStatus(prNumber);
+        await exec("gh", [
+            "api", "--method", "DELETE",
+            `repos/${this.repoFullName}/git/refs/heads/${status.branch}`,
+        ], { allowNonZero: true, githubRepoFullName: this.repoFullName });
+    }
     async findPRByBranch(branch) {
         const result = await exec("gh", [
             "pr", "list",

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

@@ -10,7 +10,7 @@ export declare class ShellGitOperations implements GitOperations, SpeculativeBra
     headSha(branch: string): Promise<string>;
     isAncestor(ancestor: string, descendant: string): Promise<boolean>;
     mergeBaseInto(branch: string, base: string): Promise<MergeResult>;
-    push(branch: string, force?: boolean): Promise<void>;
+    push(branch: string, force?: boolean, targetBranch?: string): Promise<void>;
     buildSpeculative(prBranch: string, baseBranch: string, specName: string): Promise<MergeResult>;
     deleteSpeculative(specName: string): Promise<void>;
 }

package/dist/github/shell-git.js

@@ -58,11 +58,12 @@ export class ShellGitOperations {
         const newSha = await this.headSha("HEAD");
         return { success: true, sha: newSha };
     }
-    async push(branch, force = false) {
+    async push(branch, force = false, targetBranch) {
         const args = ["push"];
         if (force)
             args.push("--force-with-lease");
-        args.push("origin", branch);
+        const refspec = targetBranch ? `${branch}:${targetBranch}` : branch;
+        args.push("origin", refspec);
         await this.git(args, { timeoutMs: 60_000 });
     }
     // ─── SpeculativeBranchBuilder ───────────────────────────────

package/dist/http-multi.js

@@ -143,6 +143,8 @@ export async function buildMultiRepoHttpServer(options) {
             if (body.priority !== undefined)
                 params.priority = body.priority;
             const entry = inst.service.enqueue(params);
+            if (!entry)
+                return reply.status(409).send({ ok: false, error: "Failed to enqueue PR" });
             return reply.status(201).send({ ok: true, entryId: entry.id });
         }
         catch (err) {

package/dist/interfaces.d.ts

@@ -8,7 +8,7 @@ export interface GitOperations {
     headSha(branch: string): Promise<string>;
     isAncestor(ancestor: string, descendant: string): Promise<boolean>;
     mergeBaseInto(branch: string, base: string): Promise<MergeResult>;
-    push(branch: string, force?: boolean): Promise<void>;
+    push(branch: string, force?: boolean, targetBranch?: string): Promise<void>;
 }
 /**
  * Builds and manages speculative cumulative branches.
@@ -43,6 +43,8 @@ export interface GitHubPRApi {
     listLabels(prNumber: number): Promise<string[]>;
     /** Find the open PR number for a branch, or null if none exists. */
     findPRByBranch(branch: string): Promise<number | null>;
+    /** Delete the PR's head branch from the remote (best-effort cleanup). */
+    deleteBranch(prNumber: number): Promise<void>;
 }
 /**
  * Reports evictions to external systems. The production implementation

package/dist/reconciler.d.ts

@@ -10,7 +10,7 @@ export interface ReconcileContext {
     ci: CIRunner;
     github: GitHubPRApi;
     eviction: EvictionReporter;
-    specBuilder: SpeculativeBranchBuilder | null;
+    specBuilder: SpeculativeBranchBuilder;
     speculativeDepth: number;
     flakyRetries: number;
     onEvent: (event: ReconcileEvent) => void;

package/dist/reconciler.js

@@ -22,122 +22,180 @@ function isBudgetExhausted(entry) {
 function isRetryGated(entry, currentBaseSha) {
     return entry.lastFailedBaseSha === currentBaseSha;
 }
-/** The branch and SHA to use for CI — spec branch if available, else PR branch. */
-function ciTarget(entry) {
-    return {
-        branch: entry.specBranch ?? entry.branch,
-        sha: entry.specSha ?? entry.headSha,
-    };
-}
 // ─── Main reconcile loop ────────────────────────────────────────
 export async function reconcile(ctx) {
     const allActive = ctx.store.listActive(ctx.repoId);
     if (allActive.length === 0)
         return;
-    const depth = ctx.specBuilder ? Math.min(ctx.speculativeDepth, allActive.length) : 1;
+    // Process up to speculativeDepth entries. GitHub truth checks are
+    // bounded by this window — we never scan the full queue.
+    const depth = Math.min(ctx.speculativeDepth, allActive.length);
     for (let i = 0; i < depth; i++) {
         const entryId = allActive[i].id;
         const entry = ctx.store.getEntry(entryId);
         if (!entry || TERMINAL_STATUSES.includes(entry.status))
             continue;
+        // Truth guard: verify entry against GitHub before processing.
+        if (await sanitizeEntry(ctx, entry))
+            continue;
         const isHead = i === 0;
-        const prevEntry = i > 0 ? ctx.store.getEntry(allActive[i - 1].id) : null;
-        switch (entry.status) {
-            case "queued":
-                emit(ctx, entry, "promoted");
-                ctx.store.transition(entry.id, "preparing_head", undefined, "promoted to head");
-                break;
-            case "preparing_head":
-                if (isHead) {
-                    await prepareHead(ctx, entry);
-                }
-                else if (ctx.specBuilder && prevEntry) {
-                    await prepareSpeculative(ctx, entry, prevEntry);
+        const prevEntry = i > 0 ? ctx.store.getEntry(allActive[i - 1].id) ?? null : null;
+        const phase = entry.status;
+        try {
+            switch (phase) {
+                case "queued":
+                    emit(ctx, entry, "promoted");
+                    ctx.store.transition(entry.id, "preparing_head", undefined, "promoted");
+                    break;
+                case "preparing_head":
+                    await prepareEntry(ctx, entry, isHead, prevEntry);
+                    break;
+                case "validating": {
+                    const freshActive = ctx.store.listActive(ctx.repoId);
+                    const freshIdx = freshActive.findIndex((e) => e.id === entry.id);
+                    await checkValidation(ctx, entry, freshActive, freshIdx >= 0 ? freshIdx : i);
+                    break;
                 }
-                break;
-            case "validating": {
-                const freshActive = ctx.store.listActive(ctx.repoId);
-                const freshIdx = freshActive.findIndex((e) => e.id === entry.id);
-                await checkValidation(ctx, entry, freshActive, freshIdx >= 0 ? freshIdx : i);
-                break;
+                case "merging":
+                    if (isHead) {
+                        await mergeHead(ctx, entry);
+                    }
+                    break;
+                default:
+                    break;
             }
-            case "merging":
-                if (isHead) {
-                    await mergeHead(ctx, entry, ctx.store.listActive(ctx.repoId));
-                }
-                break;
-            default:
-                break;
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            const wrapped = new Error(`[PR #${entry.prNumber} ${entry.id} phase=${phase}] ${msg}`);
+            if (error instanceof Error && error.stack)
+                wrapped.stack = error.stack;
+            throw wrapped;
+        }
+    }
+}
+// ─── Truth guard ────────────────────────────────────────────────
+async function sanitizeEntry(ctx, entry) {
+    const canonical = ctx.store.getEntryByPR(ctx.repoId, entry.prNumber);
+    if (canonical && canonical.id !== entry.id) {
+        emit(ctx, entry, "sanitized_duplicate", {
+            detail: `superseded by entry ${canonical.id}`,
+        });
+        await cleanupSpec(ctx, entry);
+        ctx.store.dequeue(entry.id);
+        return true;
+    }
+    try {
+        const prStatus = await ctx.github.getStatus(entry.prNumber);
+        if (prStatus.merged) {
+            emit(ctx, entry, "merge_external", {
+                detail: `PR #${entry.prNumber} already merged on GitHub (detected in sanitize)`,
+            });
+            await cleanupSpec(ctx, entry);
+            ctx.store.transition(entry.id, "merged", CLEAN_SPEC, "merged externally (sanitize)");
+            return true;
+        }
+        if (!prStatus.mergeable && !prStatus.merged) {
+            emit(ctx, entry, "sanitized_closed", {
+                detail: `PR #${entry.prNumber} is closed on GitHub`,
+            });
+            await cleanupSpec(ctx, entry);
+            ctx.store.dequeue(entry.id);
+            return true;
         }
     }
+    catch {
+        // GitHub probe failed — don't block the tick.
+    }
+    return false;
 }
-// ─── Head entry: fetch + gate + branch refresh ──────────────────
-async function prepareHead(ctx, entry) {
+// ─── Entry preparation (unified for head and non-head) ──────────
+async function prepareEntry(ctx, entry, isHead, prevEntry) {
     emit(ctx, entry, "fetch_started");
     await ctx.git.fetch();
-    const baseSha = await ctx.git.headSha(ref(ctx, ctx.baseBranch));
-    // Gate: main CI must be green.
-    if (ctx.ci.getMainStatus) {
-        const mainStatus = await ctx.ci.getMainStatus(ctx.baseBranch);
-        if (mainStatus === "fail") {
-            let mainChecks = [];
+    // Determine base: head merges onto main, non-head onto prev entry's spec.
+    const base = isHead ? ref(ctx, ctx.baseBranch) : prevEntry?.specBranch ?? null;
+    if (!base)
+        return; // Non-head: prev hasn't built its spec yet, wait.
+    const baseSha = await ctx.git.headSha(base);
+    // ── Head-only gates ───────────────────────────────────────────
+    if (isHead) {
+        // Gate: main CI must be green.
+        if (ctx.ci.getMainStatus) {
+            const mainStatus = await ctx.ci.getMainStatus(ctx.baseBranch);
+            if (mainStatus === "fail") {
+                let mainChecks = [];
+                try {
+                    mainChecks = await ctx.github.listChecksForRef(ref(ctx, ctx.baseBranch));
+                }
+                catch {
+                    mainChecks = [];
+                }
+                const failingChecks = mainChecks.filter((check) => check.conclusion === "failure");
+                const pendingChecks = mainChecks.filter((check) => check.conclusion === "pending");
+                emit(ctx, entry, "main_broken", {
+                    baseSha,
+                    failingChecks,
+                    pendingChecks,
+                    detail: describeMainBroken(failingChecks, pendingChecks),
+                });
+                return;
+            }
+        }
+        // Gate: detect external pushes to the PR branch.
+        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);
+            return;
+        }
+        // Gate: budget exhausted after previous conflict.
+        if (isBudgetExhausted(entry) && entry.lastFailedBaseSha !== null) {
+            emit(ctx, entry, "budget_exhausted", { baseSha });
+            await evictEntry(ctx, entry, "integration_conflict");
+            return;
+        }
+        // Gate: non-spinning — skip if base hasn't changed since last conflict.
+        if (isRetryGated(entry, baseSha)) {
+            emit(ctx, entry, "retry_gated", { baseSha, detail: "base unchanged since last conflict" });
             try {
-                mainChecks = await ctx.github.listChecksForRef(ref(ctx, ctx.baseBranch));
+                const prStatus = await ctx.github.getStatus(entry.prNumber);
+                if (prStatus.mergeStateStatus === "DIRTY") {
+                    emit(ctx, entry, "budget_exhausted", {
+                        baseSha,
+                        detail: "retry gated and GitHub still reports merge conflict",
+                    });
+                    await evictEntry(ctx, entry, "integration_conflict");
+                }
             }
             catch {
-                mainChecks = [];
+                // Best-effort check.
             }
-            const failingChecks = mainChecks.filter((check) => check.conclusion === "failure");
-            const pendingChecks = mainChecks.filter((check) => check.conclusion === "pending");
-            emit(ctx, entry, "main_broken", {
-                baseSha,
-                failingChecks,
-                pendingChecks,
-                detail: describeMainBroken(failingChecks, pendingChecks),
-            });
             return;
         }
     }
-    // Gate: branch must match expected SHA (detect external pushes).
-    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);
-        return;
-    }
-    // Gate: budget exhausted after previous conflict.
-    if (isBudgetExhausted(entry) && entry.lastFailedBaseSha !== null) {
-        emit(ctx, entry, "budget_exhausted", { baseSha });
-        await evictEntry(ctx, entry, "integration_conflict");
-        return;
+    // ── Build spec branch: merge PR into base ─────────────────────
+    const specName = specBranchName(entry.id);
+    emit(ctx, entry, "spec_build_started", { specBranch: specName, baseSha, ...(prevEntry ? { dependsOn: prevEntry.id } : {}) });
+    let result;
+    try {
+        result = await ctx.specBuilder.buildSpeculative(entry.branch, base, specName);
     }
-    // Gate: non-spinning — skip if base hasn't changed since last conflict.
-    if (isRetryGated(entry, baseSha)) {
-        emit(ctx, entry, "retry_gated", { baseSha, detail: "base unchanged since last conflict" });
+    catch (err) {
+        if (isHead) {
+            // Branch gone or unreachable.
+            const detail = `git error during spec build: ${err instanceof Error ? err.message : String(err)}`;
+            emit(ctx, entry, "branch_unreachable", { baseSha, detail });
+            await evictEntry(ctx, entry, "branch_local");
+        }
+        else {
+            // Stale spec from prev entry — reset both.
+            emit(ctx, entry, "invalidated", { detail: "stale spec branch, rebuilding" });
+            ctx.store.transition(prevEntry.id, "preparing_head", { ...CLEAN_CI, ...CLEAN_SPEC }, "spec branch missing, rebuilding");
+            ctx.store.transition(entry.id, "preparing_head", { ...CLEAN_CI, ...CLEAN_SPEC }, "stale dependency, rebuilding");
+        }
         return;
     }
-    await performBranchRefresh(ctx, entry, baseSha);
-}
-function describeMainBroken(failingChecks, pendingChecks) {
-    const parts = [];
-    if (failingChecks.length > 0) {
-        parts.push(`failing ${summarizeCheckNames(failingChecks)}`);
-    }
-    if (pendingChecks.length > 0) {
-        parts.push(`pending ${summarizeCheckNames(pendingChecks)}`);
-    }
-    return parts.length > 0 ? `main checks unhealthy: ${parts.join("; ")}` : "main checks unhealthy";
-}
-function summarizeCheckNames(checks, limit = 3) {
-    const names = [...new Set(checks.map((check) => check.name))];
-    if (names.length <= limit) {
-        return names.join(", ");
-    }
-    return `${names.slice(0, limit).join(", ")} +${names.length - limit} more`;
-}
-async function performBranchRefresh(ctx, entry, baseSha) {
-    emit(ctx, entry, "rebase_started", { baseSha, detail: `refreshing ${entry.branch} with ${ctx.baseBranch}` });
-    const result = await ctx.git.mergeBaseInto(entry.branch, ref(ctx, ctx.baseBranch));
     if (!result.success) {
         emit(ctx, entry, "rebase_conflict", { baseSha, conflictFiles: result.conflictFiles });
         if (isBudgetExhausted(entry)) {
@@ -153,85 +211,39 @@ async function performBranchRefresh(ctx, entry, baseSha) {
         }
         return;
     }
-    const headSha = result.sha ?? entry.headSha;
-    await ctx.git.fetch();
-    const latestRemoteHead = await ctx.git.headSha(ref(ctx, entry.branch));
-    if (latestRemoteHead !== entry.headSha) {
-        const detail = `remote advanced during refresh: expected ${entry.headSha.slice(0, 8)}, ` +
-            `latest ${latestRemoteHead.slice(0, 8)}, candidate ${headSha.slice(0, 8)}`;
-        emit(ctx, entry, "branch_mismatch", { detail });
-        ctx.store.updateHead(entry.id, latestRemoteHead);
-        return;
-    }
-    await ctx.git.push(entry.branch, false);
-    emit(ctx, entry, "rebase_succeeded", { baseSha, detail: `refreshed ${entry.branch} with ${ctx.baseBranch}` });
-    // Build speculative branch for downstream entries.
-    let specBranch = null;
-    let specSha = null;
-    if (ctx.specBuilder) {
-        specBranch = specBranchName(entry.id);
-        emit(ctx, entry, "spec_build_started", { specBranch, baseSha });
-        const specResult = await ctx.specBuilder.buildSpeculative(entry.branch, ref(ctx, ctx.baseBranch), specBranch);
-        if (specResult.success) {
-            specSha = specResult.sha ?? headSha;
-            emit(ctx, entry, "spec_build_succeeded", { specBranch });
-        }
-        else {
-            emit(ctx, entry, "spec_build_conflict", { specBranch });
-            specBranch = null;
-        }
-    }
-    const runId = await ctx.ci.triggerRun(entry.branch, headSha);
-    emit(ctx, entry, "ci_triggered", { ciRunId: runId });
+    const specSha = result.sha ?? entry.headSha;
+    emit(ctx, entry, "spec_build_succeeded", { specBranch: specName, ...(prevEntry ? { dependsOn: prevEntry.id } : {}) });
+    // Trigger CI on the spec branch.
+    const runId = await ctx.ci.triggerRun(specName, specSha);
+    emit(ctx, entry, "ci_triggered", { ciRunId: runId, specBranch: specName });
     ctx.store.transition(entry.id, "validating", {
-        headSha, baseSha, ciRunId: runId, lastFailedBaseSha: null,
-        specBranch, specSha, specBasedOn: null,
-    }, `refreshed with ${ctx.baseBranch} @ ${baseSha.slice(0, 8)}, CI ${runId}`);
+        baseSha, ciRunId: runId, lastFailedBaseSha: null,
+        specBranch: specName, specSha, specBasedOn: isHead ? null : prevEntry.id,
+    }, `spec ${specName} ready, CI ${runId}`);
 }
-// ─── Non-head entry: speculative branch ─────────────────────────
-async function prepareSpeculative(ctx, entry, prevEntry) {
-    if (!ctx.specBuilder || !prevEntry.specBranch)
-        return;
-    const specName = specBranchName(entry.id);
-    emit(ctx, entry, "spec_build_started", { specBranch: specName, dependsOn: prevEntry.id });
-    let result;
-    try {
-        result = await ctx.specBuilder.buildSpeculative(entry.branch, prevEntry.specBranch, specName);
-    }
-    catch {
-        // Stale spec branch — the previous entry's branch doesn't exist
-        // (e.g., after restart with fresh clone). Reset both entries.
-        emit(ctx, entry, "invalidated", { detail: "stale spec branch, rebuilding" });
-        ctx.store.transition(prevEntry.id, "preparing_head", { ...CLEAN_CI, ...CLEAN_SPEC }, "spec branch missing, rebuilding");
-        ctx.store.transition(entry.id, "preparing_head", { ...CLEAN_CI, ...CLEAN_SPEC }, "stale dependency, rebuilding");
-        return;
+function describeMainBroken(failingChecks, pendingChecks) {
+    const parts = [];
+    if (failingChecks.length > 0) {
+        parts.push(`failing ${summarizeCheckNames(failingChecks)}`);
     }
-    if (result.success) {
-        const specSha = result.sha ?? entry.headSha;
-        emit(ctx, entry, "spec_build_succeeded", { specBranch: specName, dependsOn: prevEntry.id });
-        const runId = await ctx.ci.triggerRun(specName, specSha);
-        emit(ctx, entry, "ci_triggered", { ciRunId: runId, specBranch: specName });
-        ctx.store.transition(entry.id, "validating", {
-            ciRunId: runId, specBranch: specName, specSha, specBasedOn: prevEntry.id,
-        }, `spec ${specName} based on ${prevEntry.id}, CI ${runId}`);
+    if (pendingChecks.length > 0) {
+        parts.push(`pending ${summarizeCheckNames(pendingChecks)}`);
     }
-    else {
-        emit(ctx, entry, "spec_build_conflict", { specBranch: specName, dependsOn: prevEntry.id });
-        if (!isBudgetExhausted(entry)) {
-            ctx.store.transition(entry.id, "preparing_head", {
-                retryAttempts: entry.retryAttempts + 1, lastFailedBaseSha: prevEntry.specSha,
-            }, `spec conflict, retry ${entry.retryAttempts + 1}/${entry.maxRetries}`);
-        }
-        else {
-            await evictEntry(ctx, entry, "integration_conflict");
-        }
+    return parts.length > 0 ? `main checks unhealthy: ${parts.join("; ")}` : "main checks unhealthy";
+}
+function summarizeCheckNames(checks, limit = 3) {
+    const names = [...new Set(checks.map((check) => check.name))];
+    if (names.length <= limit) {
+        return names.join(", ");
     }
+    return `${names.slice(0, limit).join(", ")} +${names.length - limit} more`;
 }
 // ─── CI validation ──────────────────────────────────────────────
 async function checkValidation(ctx, entry, allActive, index) {
     if (!entry.ciRunId) {
-        const target = ciTarget(entry);
-        const runId = await ctx.ci.triggerRun(target.branch, target.sha);
+        const branch = entry.specBranch ?? entry.branch;
+        const sha = entry.specSha ?? entry.headSha;
+        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}`);
         return;
@@ -252,8 +264,9 @@ async function checkValidation(ctx, entry, allActive, index) {
             emit(ctx, entry, "ci_failed", { ciRunId: entry.ciRunId });
             if (entry.ciRetries < ctx.flakyRetries) {
                 emit(ctx, entry, "ci_flaky_retry", { detail: `retry ${entry.ciRetries + 1}/${ctx.flakyRetries}` });
-                const target = ciTarget(entry);
-                const runId = await ctx.ci.triggerRun(target.branch, target.sha);
+                const branch = entry.specBranch ?? entry.branch;
+                const sha = entry.specSha ?? entry.headSha;
+                const runId = await ctx.ci.triggerRun(branch, sha);
                 ctx.store.transition(entry.id, "validating", {
                     ciRunId: runId, ciRetries: entry.ciRetries + 1,
                 }, `flaky retry ${entry.ciRetries + 1}/${ctx.flakyRetries}`);
@@ -278,8 +291,8 @@ async function checkValidation(ctx, entry, allActive, index) {
         }
     }
 }
-// ─── Merge (head only) ──────────────────────────────────────────
-async function mergeHead(ctx, entry, allActive) {
+// ─── Merge: push spec branch to main (head only) ───────────────
+async function mergeHead(ctx, entry) {
     emit(ctx, entry, "merge_revalidating");
     const prStatus = await ctx.github.getStatus(entry.prNumber);
     if (prStatus.merged) {
@@ -290,36 +303,46 @@ async function mergeHead(ctx, entry, allActive) {
     }
     if (!prStatus.reviewApproved) {
         emit(ctx, entry, "merge_rejected", { detail: "approval withdrawn" });
+        const allActive = ctx.store.listActive(ctx.repoId);
         await evictEntry(ctx, entry, "policy_blocked");
         await invalidateDownstream(ctx, allActive, 0);
         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);
         ctx.store.updateHead(entry.id, prStatus.headSha);
         await invalidateDownstream(ctx, allActive, 0);
         return;
     }
-    // Check if base branch moved since validation — if so, re-prepare.
-    if (entry.baseSha) {
-        try {
-            const currentBase = await ctx.git.headSha(ref(ctx, ctx.baseBranch));
-            if (currentBase !== entry.baseSha) {
-                emit(ctx, entry, "branch_mismatch", { detail: `base: expected ${entry.baseSha.slice(0, 8)}, got ${currentBase.slice(0, 8)}` });
-                ctx.store.transition(entry.id, "preparing_head", { ...CLEAN_CI, ...CLEAN_SPEC }, "base moved, re-prepare");
-                await invalidateDownstream(ctx, allActive, 0);
-                return;
-            }
-        }
-        catch {
-            // Can't resolve base — proceed and let GitHub enforce.
+    if (!entry.specBranch || !entry.specSha) {
+        ctx.store.transition(entry.id, "preparing_head", { ...CLEAN_CI, ...CLEAN_SPEC }, "no spec branch, re-prepare");
+        return;
+    }
+    // Guard: verify our spec is a fast-forward from current main.
+    // If someone pushed directly to main outside the queue, this catches it.
+    try {
+        await ctx.git.fetch();
+        const currentBase = await ctx.git.headSha(ref(ctx, ctx.baseBranch));
+        const isFF = await ctx.git.isAncestor(currentBase, entry.specSha);
+        if (!isFF) {
+            emit(ctx, entry, "branch_mismatch", { detail: `spec is not a fast-forward from main (${currentBase.slice(0, 8)})` });
+            const allActive = ctx.store.listActive(ctx.repoId);
+            ctx.store.transition(entry.id, "preparing_head", { ...CLEAN_CI, ...CLEAN_SPEC }, "main diverged, re-prepare");
+            await invalidateDownstream(ctx, allActive, 0);
+            return;
         }
     }
+    catch {
+        // Can't verify — proceed and let push fail if needed.
+    }
+    // Push the spec branch to main (fast-forward).
     try {
-        await ctx.github.mergePR(entry.prNumber);
+        await ctx.git.push(entry.specBranch, false, ctx.baseBranch);
     }
     catch {
-        emit(ctx, entry, "merge_rejected", { detail: "GitHub API rejected merge" });
+        emit(ctx, entry, "merge_rejected", { detail: "push to main failed" });
+        const allActive = ctx.store.listActive(ctx.repoId);
         if (isBudgetExhausted(entry)) {
             emit(ctx, entry, "budget_exhausted");
             await evictEntry(ctx, entry, "integration_conflict");
@@ -327,14 +350,21 @@ async function mergeHead(ctx, entry, allActive) {
         else {
             ctx.store.transition(entry.id, "preparing_head", {
                 retryAttempts: entry.retryAttempts + 1, ...CLEAN_CI, ...CLEAN_SPEC,
-            }, `merge rejected, retry ${entry.retryAttempts + 1}/${entry.maxRetries}`);
+            }, `push failed, retry ${entry.retryAttempts + 1}/${entry.maxRetries}`);
         }
+        // Head is rebuilding — downstream specs are stale (they were built
+        // on the old head spec which will change after re-preparation).
         await invalidateDownstream(ctx, allActive, 0);
         return;
     }
     emit(ctx, entry, "merge_succeeded");
-    ctx.store.transition(entry.id, "merged", CLEAN_SPEC, "merged to main");
+    ctx.store.transition(entry.id, "merged", CLEAN_SPEC, "spec pushed to main");
     await cleanupSpec(ctx, entry);
+    // Best-effort: delete the PR branch from remote.
+    try {
+        await ctx.github.deleteBranch(entry.prNumber);
+    }
+    catch { /* cosmetic */ }
 }
 // ─── Invalidation + eviction ────────────────────────────────────
 async function invalidateDownstream(ctx, allActive, afterIndex) {
@@ -348,7 +378,7 @@ async function invalidateDownstream(ctx, allActive, afterIndex) {
     }
 }
 async function cleanupSpec(ctx, entry) {
-    if (entry.specBranch && ctx.specBuilder) {
+    if (entry.specBranch) {
         await ctx.specBuilder.deleteSpeculative(entry.specBranch).catch(() => {
             // Best-effort cleanup — branch may not exist.
         });
@@ -356,7 +386,6 @@ async function cleanupSpec(ctx, entry) {
 }
 async function evictEntry(ctx, entry, failureClass, extra) {
     await cleanupSpec(ctx, entry);
-    // Use recorded baseSha if available, else resolve current base.
     let baseSha = entry.baseSha;
     if (!baseSha) {
         try {
@@ -366,7 +395,6 @@ async function evictEntry(ctx, entry, failureClass, extra) {
             baseSha = "unknown";
         }
     }
-    // Build retry history from queue events (each event snapshots baseSha at transition time).
     const events = ctx.store.listEvents(entry.id);
     const retryHistory = [];
     for (const event of events) {

package/dist/server.js

@@ -25,8 +25,7 @@ async function createRepoInstance(config, logger) {
     const ci = new GitHubActionsRunner(config.repoFullName, config.requiredChecks);
     const github = new GitHubPRClient(config.repoFullName);
     const eviction = new GitHubCheckRunReporter(config.repoFullName, config.server.bind, config.server.port, config.server.publicBaseUrl, config.admissionLabel, config.mergeQueueCheckName);
-    const specBuilder = config.speculativeDepth > 1 ? git : null;
-    const service = new MergeStewardService(config, store, git, ci, github, eviction, specBuilder, logger);
+    const service = new MergeStewardService(config, store, git, ci, github, eviction, git, logger);
     return { config, service, store };
 }
 export async function startMultiServer() {

package/dist/service.d.ts

@@ -24,7 +24,7 @@ export declare class MergeStewardService {
     private lastTickOutcome;
     private lastTickError;
     private currentQueueBlock;
-    constructor(config: StewardConfig, store: QueueStore, git: GitOperations, ci: CIRunner, github: GitHubPRApi, eviction: EvictionReporter, specBuilder: import("./interfaces.ts").SpeculativeBranchBuilder | null, logger: Logger);
+    constructor(config: StewardConfig, store: QueueStore, git: GitOperations, ci: CIRunner, github: GitHubPRApi, eviction: EvictionReporter, specBuilder: import("./interfaces.ts").SpeculativeBranchBuilder, logger: Logger);
     /** Expose the GitHub client for webhook handler branch→PR lookups. */
     get githubApi(): GitHubPRApi;
     start(): void;
@@ -35,7 +35,7 @@ export declare class MergeStewardService {
         headSha: string;
         issueKey?: string;
         priority?: number;
-    }): QueueEntry;
+    }): QueueEntry | undefined;
     dequeueEntry(entryId: string): boolean;
     updateEntryHead(entryId: string, headSha: string): boolean;
     getStatus(): QueueEntry[];

package/dist/service.js

@@ -58,6 +58,15 @@ export class MergeStewardService {
         this.logger.info("Steward service stopped");
     }
     enqueue(params) {
+        // Pre-check: if an active entry already exists for this PR, don't
+        // attempt the insert. This is also enforced by the UNIQUE partial
+        // index (idx_one_active_per_pr), but handling it here gives a clear
+        // log message instead of a raw constraint error.
+        const existing = this.store.getEntryByPR(this.config.repoId, params.prNumber);
+        if (existing) {
+            this.logger.warn({ prNumber: params.prNumber, existingEntryId: existing.id }, "Duplicate enqueue rejected: active entry already exists for PR");
+            return existing;
+        }
         const entry = {
             id: randomUUID(),
             repoId: this.config.repoId,
@@ -81,7 +90,19 @@ export class MergeStewardService {
             enqueuedAt: new Date().toISOString(),
             updatedAt: new Date().toISOString(),
         };
-        this.store.insert(entry);
+        try {
+            this.store.insert(entry);
+        }
+        catch (err) {
+            // UNIQUE constraint race: another entry was inserted between our
+            // pre-check and the insert. Return the existing entry.
+            const raced = this.store.getEntryByPR(this.config.repoId, params.prNumber);
+            if (raced) {
+                this.logger.warn({ prNumber: params.prNumber, existingEntryId: raced.id }, "Duplicate enqueue caught by constraint: returning existing entry");
+                return raced;
+            }
+            throw err; // Not a duplicate constraint — re-throw the real error.
+        }
         this.logger.info({ prNumber: params.prNumber, entryId: entry.id }, "PR enqueued");
         return entry;
     }
@@ -277,8 +298,12 @@ export class MergeStewardService {
         }
         catch (error) {
             this.lastTickOutcome = "failed";
-            this.lastTickError = error instanceof Error ? error.message : String(error);
-            this.logger.error({ error }, "Reconcile tick failed");
+            // Preserve stack + message for the watch API. The reconciler wraps
+            // per-entry errors with [PR #N entryId phase=X] context.
+            this.lastTickError = error instanceof Error
+                ? `${error.message}${error.stack ? `\n${error.stack}` : ""}`
+                : String(error);
+            this.logger.error({ err: error instanceof Error ? { message: error.message, stack: error.stack } : error }, "Reconcile tick failed");
         }
         finally {
             this.tickInProgress = false;

package/dist/types.d.ts

@@ -3,6 +3,9 @@
  *
  * queued → preparing_head → validating → merging → merged
  *
+ * Every entry builds a cumulative spec branch and runs CI on it.
+ * Head entry pushes its spec to main on merge (fast-forward).
+ *
  * Failure: any state → evicted (after retry budget exhausted).
  * Conflict retries are gated on base SHA change (non-spinning).
  *
@@ -158,6 +161,7 @@ export interface PRStatus {
     branch: string;
     headSha: string;
     mergeable: boolean;
+    mergeStateStatus?: string | undefined;
     reviewApproved: boolean;
     merged: boolean;
 }
@@ -169,7 +173,7 @@ export interface QueueConfig {
     pollIntervalMs: number;
     requiredChecks: string[];
 }
-export type ReconcileAction = "promoted" | "fetch_started" | "main_broken" | "branch_mismatch" | "rebase_started" | "rebase_succeeded" | "rebase_conflict" | "spec_build_started" | "spec_build_succeeded" | "spec_build_conflict" | "ci_triggered" | "ci_pending" | "ci_passed" | "ci_failed" | "ci_flaky_retry" | "merge_revalidating" | "merge_succeeded" | "merge_rejected" | "merge_external" | "evicted" | "invalidated" | "retry_gated" | "budget_exhausted";
+export type ReconcileAction = "promoted" | "fetch_started" | "main_broken" | "branch_mismatch" | "rebase_started" | "rebase_succeeded" | "rebase_conflict" | "spec_build_started" | "spec_build_succeeded" | "spec_build_conflict" | "ci_triggered" | "ci_pending" | "ci_passed" | "ci_failed" | "ci_flaky_retry" | "merge_revalidating" | "merge_succeeded" | "merge_rejected" | "merge_external" | "evicted" | "invalidated" | "retry_gated" | "budget_exhausted" | "sanitized_closed" | "sanitized_duplicate" | "branch_unreachable";
 export interface ReconcileEvent {
     at: string;
     entryId: string;

package/package.json

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