merge-steward 0.5.6 → 0.7.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

@@ -64,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,135 +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;
         }
     }
 }
-// ─── Head entry: fetch + gate + branch refresh ──────────────────
-async function prepareHead(ctx, entry) {
+// ─── 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;
+}
+// ─── 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" });
-        try {
-            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 (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");
         }
-        catch {
-            // Best-effort check. If GitHub status is unavailable, preserve the non-spinning wait.
+        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)) {
@@ -166,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;
@@ -265,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}`);
@@ -291,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) {
@@ -303,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");
@@ -340,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) {
@@ -361,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.
         });
@@ -369,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 {
@@ -379,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).
  *
@@ -170,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/dist/watch/DetailView.js

@@ -18,5 +18,5 @@ export function DetailView({ detail, isHead, activeIndex, activeCount, headPrNum
         queueBlock,
     });
     const pipeline = queueProgress(entry.status);
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { gap: 2, children: [_jsxs(Text, { bold: true, children: ["#", entry.prNumber] }), entry.issueKey ? _jsx(Text, { children: entry.issueKey }) : null, _jsx(Text, { color: statusColor(entry.status), children: humanStatus(entry.status) }), _jsxs(Text, { dimColor: true, children: ["pos ", entry.position] }), _jsxs(Text, { dimColor: true, children: ["generation ", entry.generation] }), _jsxs(Text, { dimColor: true, children: ["retry ", entry.retryAttempts, "/", entry.maxRetries] })] }), _jsx(Text, { children: entry.branch }), _jsxs(Box, { gap: 2, children: [_jsxs(Text, { dimColor: true, children: ["head ", shortSha(entry.headSha)] }), _jsxs(Text, { dimColor: true, children: ["base ", shortSha(entry.baseSha)] }), entry.issueKey && _jsx(Text, { dimColor: true, children: entry.issueKey })] }), _jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "progress" }), _jsx(Text, { children: progressBar(pipeline.current, pipeline.total, 12) }), _jsx(Text, { dimColor: true, children: nextStepLabel(entry.status) })] }), isHead && queueBlock && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", summarizeQueueBlock(queueBlock) ?? "main branch is unhealthy", "."] }), _jsxs(Text, { dimColor: true, children: [queueBlock.baseBranch, queueBlock.baseSha ? ` @ ${shortSha(queueBlock.baseSha)}` : ""] }), _jsxs(Text, { dimColor: true, children: ["Head PR #", queueBlock.headPrNumber ?? entry.prNumber, " will resume automatically once main recovers."] })] })), entry.maxRetries > 0 && (_jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "retry" }), _jsx(Text, { children: progressBar(entry.retryAttempts, entry.maxRetries, 10) }), _jsxs(Text, { dimColor: true, children: [entry.retryAttempts, "/", entry.maxRetries] })] })), _jsx(EntryStateGraph, { main: graph.main, exits: graph.exits }), _jsx(ExternalRepairObservation, { observations: observations }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Incidents" }), incidents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No incidents." })) : (incidents.map((incident) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(incident.at).padStart(4, " ") }), _jsx(Text, { color: "red", children: incident.failureClass }), _jsx(Text, { dimColor: true, children: incident.outcome })] }, incident.id))))] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Events" }), events.length === 0 ? (_jsx(Text, { dimColor: true, children: "No events yet." })) : (events.slice(-16).map((event) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(event.at).padStart(4, " ") }), _jsx(Text, { children: formatEntryEvent(event) })] }, event.id ?? `${event.entryId}-${event.at}`))))] })] }));
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { gap: 2, children: [_jsxs(Text, { bold: true, children: ["#", entry.prNumber] }), entry.issueKey ? _jsx(Text, { children: entry.issueKey }) : null, _jsx(Text, { color: statusColor(entry.status), children: humanStatus(entry.status, entry) }), _jsxs(Text, { dimColor: true, children: ["pos ", entry.position] }), _jsxs(Text, { dimColor: true, children: ["retry ", entry.retryAttempts, "/", entry.maxRetries] })] }), _jsx(Text, { children: entry.branch }), _jsxs(Box, { gap: 2, children: [_jsxs(Text, { dimColor: true, children: ["head ", shortSha(entry.headSha)] }), _jsxs(Text, { dimColor: true, children: ["base ", shortSha(entry.baseSha)] })] }), entry.specBranch && (_jsxs(Box, { gap: 2, children: [_jsx(Text, { dimColor: true, children: "spec" }), _jsx(Text, { children: entry.specBranch }), _jsx(Text, { dimColor: true, children: shortSha(entry.specSha) }), _jsx(Text, { dimColor: true, children: "\u2190" }), _jsx(Text, { dimColor: true, children: entry.specBasedOn ? `entry ${shortSha(entry.specBasedOn)}` : "main" })] })), _jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "progress" }), _jsx(Text, { children: progressBar(pipeline.current, pipeline.total, 12) }), _jsx(Text, { dimColor: true, children: nextStepLabel(entry.status, entry) })] }), isHead && queueBlock && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", summarizeQueueBlock(queueBlock) ?? "main branch is unhealthy", "."] }), _jsxs(Text, { dimColor: true, children: [queueBlock.baseBranch, queueBlock.baseSha ? ` @ ${shortSha(queueBlock.baseSha)}` : ""] }), _jsxs(Text, { dimColor: true, children: ["Head PR #", queueBlock.headPrNumber ?? entry.prNumber, " will resume automatically once main recovers."] })] })), entry.maxRetries > 0 && (_jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "retry" }), _jsx(Text, { children: progressBar(entry.retryAttempts, entry.maxRetries, 10) }), _jsxs(Text, { dimColor: true, children: [entry.retryAttempts, "/", entry.maxRetries] })] })), _jsx(EntryStateGraph, { main: graph.main, exits: graph.exits }), _jsx(ExternalRepairObservation, { observations: observations }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Incidents" }), incidents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No incidents." })) : (incidents.map((incident) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(incident.at).padStart(4, " ") }), _jsx(Text, { color: "red", children: incident.failureClass }), _jsx(Text, { dimColor: true, children: incident.outcome })] }, incident.id))))] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Events" }), events.length === 0 ? (_jsx(Text, { dimColor: true, children: "No events yet." })) : (events.slice(-16).map((event) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(event.at).padStart(4, " ") }), _jsx(Text, { children: formatEntryEvent(event) })] }, event.id ?? `${event.entryId}-${event.at}`))))] })] }));
 }

package/dist/watch/QueueListView.js

@@ -1,21 +1,26 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { Box, Text, useStdout } from "ink";
-import { formatEventSummary, humanStatus, nextStepLabel, progressBar, queueProgress, relativeTime, statusColor, summarizeQueueBlock, truncate } from "./format.js";
+import { formatEventSummary, humanStatus, nextStepLabel, progressBar, queueProgress, relativeTime, specChainLabel, statusColor, summarizeQueueBlock, truncate } from "./format.js";
 const ENTRY_ROW_HEIGHT = 2;
 const CHROME_ROWS = 13;
-function QueueRow({ entry, selected, infoWidth, isHead, queueBlock, }) {
+function QueueRow({ entry, selected, infoWidth, isHead, queueBlock, allEntries, }) {
     const retryText = `${entry.retryAttempts}/${entry.maxRetries}`;
     const ciText = entry.ciRetries > 0 ? `CI retries ${entry.ciRetries}` : null;
     const blockedOnMain = isHead && queueBlock?.reason === "main_broken" && queueBlock.headPrNumber === entry.prNumber;
-    const renderedStatus = blockedOnMain ? "blocked by broken main" : humanStatus(entry.status);
-    const renderedColor = blockedOnMain ? "red" : statusColor(entry.status);
+    const renderedStatus = blockedOnMain ? "blocked by broken main" : humanStatus(entry.status, entry);
+    const renderedColor = blockedOnMain
+        ? "red"
+        : entry.status === "preparing_head" && entry.lastFailedBaseSha ? "yellow"
+            : statusColor(entry.status);
     const progress = queueProgress(entry.status);
-    const branchLabel = truncate(entry.branch, Math.max(12, infoWidth - 34));
+    const specLabel = entry.specBranch
+        ? specChainLabel(entry, allEntries)
+        : truncate(entry.branch, Math.max(12, infoWidth - 34));
     const nextStep = blockedOnMain
         ? summarizeQueueBlock(queueBlock) ?? "waiting for main to recover"
-        : nextStepLabel(entry.status);
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: selected ? "cyan" : "gray", children: selected ? "›" : " " }), _jsx(Text, { color: blockedOnMain ? "red" : isHead ? "green" : "gray", children: blockedOnMain ? "!" : isHead ? "#" : " " }), _jsx(Text, { bold: true, children: ` #${entry.prNumber}` }), entry.issueKey ? _jsx(Text, { children: ` ${entry.issueKey}` }) : null, _jsx(Text, { dimColor: true, children: `  pos ${entry.position}` }), _jsx(Text, { dimColor: true, children: `  ${relativeTime(entry.updatedAt)}` }), _jsx(Text, { children: `  ` }), _jsx(Text, { color: renderedColor, children: renderedStatus })] }), _jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: progressBar(progress.current, progress.total, 8) }), _jsx(Text, { dimColor: true, children: branchLabel }), _jsx(Text, { dimColor: true, children: "|" }), _jsx(Text, { dimColor: true, children: nextStep }), _jsx(Text, { dimColor: true, children: ` | retry ${retryText}` }), ciText ? (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: "|" }), _jsx(Text, { dimColor: true, children: ciText })] })) : null] })] }));
+        : nextStepLabel(entry.status, entry);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: selected ? "cyan" : "gray", children: selected ? "›" : " " }), _jsx(Text, { color: blockedOnMain ? "red" : isHead ? "green" : "gray", children: blockedOnMain ? "!" : isHead ? "#" : " " }), _jsx(Text, { bold: true, children: ` #${entry.prNumber}` }), entry.issueKey ? _jsx(Text, { children: ` ${entry.issueKey}` }) : null, _jsx(Text, { dimColor: true, children: `  pos ${entry.position}` }), _jsx(Text, { dimColor: true, children: `  ${relativeTime(entry.updatedAt)}` }), _jsx(Text, { children: `  ` }), _jsx(Text, { color: renderedColor, children: renderedStatus })] }), _jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: progressBar(progress.current, progress.total, 8) }), _jsx(Text, { dimColor: true, children: specLabel }), _jsx(Text, { dimColor: true, children: "|" }), _jsx(Text, { dimColor: true, children: nextStep }), _jsx(Text, { dimColor: true, children: ` | retry ${retryText}` }), ciText ? (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: "|" }), _jsx(Text, { dimColor: true, children: ciText })] })) : null] })] }));
 }
 export function QueueListView({ entries, selectedEntryId, recentEvents, headEntryId, queueBlock, }) {
     const { stdout } = useStdout();
@@ -25,5 +30,5 @@ export function QueueListView({ entries, selectedEntryId, recentEvents, headEntr
     const eventRows = Math.min(8, Math.max(4, rows - (entries.length * ENTRY_ROW_HEIGHT) - CHROME_ROWS));
     const displayedEvents = useMemo(() => recentEvents.slice(-eventRows), [eventRows, recentEvents]);
     const queueBlockLabel = summarizeQueueBlock(queueBlock);
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [queueBlock && (_jsxs(Box, { marginBottom: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", queueBlockLabel ?? "main is unhealthy", queueBlock.baseSha ? ` at ${truncate(queueBlock.baseSha, 10)}` : "", "."] }), _jsxs(Text, { dimColor: true, children: ["Head PR #", queueBlock.headPrNumber ?? "?", " will resume automatically once main recovers."] })] })), entries.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue entries in this filter." })) : (entries.map((entry) => (_jsx(QueueRow, { entry: entry, selected: entry.id === selectedEntryId, infoWidth: infoWidth, isHead: entry.id === headEntryId, queueBlock: queueBlock }, entry.id)))), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Recent Events" }), displayedEvents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue events yet." })) : (displayedEvents.map((event) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(event.at).padStart(4, " ") }), _jsx(Text, { children: formatEventSummary(event) })] }, event.id ?? `${event.entryId}-${event.at}`))))] })] }));
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [queueBlock && (_jsxs(Box, { marginBottom: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", queueBlockLabel ?? "main is unhealthy", queueBlock.baseSha ? ` at ${truncate(queueBlock.baseSha, 10)}` : "", "."] }), _jsxs(Text, { dimColor: true, children: ["Head PR #", queueBlock.headPrNumber ?? "?", " will resume automatically once main recovers."] })] })), entries.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue entries in this filter." })) : (entries.map((entry) => (_jsx(QueueRow, { entry: entry, selected: entry.id === selectedEntryId, infoWidth: infoWidth, isHead: entry.id === headEntryId, queueBlock: queueBlock, allEntries: entries }, entry.id)))), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Recent Events" }), displayedEvents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue events yet." })) : (displayedEvents.map((event) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(event.at).padStart(4, " ") }), _jsx(Text, { children: formatEventSummary(event) })] }, event.id ?? `${event.entryId}-${event.at}`))))] })] }));
 }

package/dist/watch/format.d.ts

@@ -2,12 +2,28 @@ import type { CheckResult, QueueBlockState, QueueEntryStatus, QueueEventRecord,
 export declare function shortSha(value: string | null | undefined): string;
 export declare function relativeTime(iso: string | null | undefined): string;
 export declare function statusColor(status: QueueEntryStatus): "yellow" | "cyan" | "green" | "red" | "gray";
-export declare function humanStatus(status: QueueEntryStatus): string;
+export declare function humanStatus(status: QueueEntryStatus, entry?: {
+    lastFailedBaseSha: string | null;
+    specBranch: string | null;
+}): string;
 export declare function queueProgress(status: QueueEntryStatus): {
     current: number;
     total: number;
 };
-export declare function nextStepLabel(status: QueueEntryStatus): string;
+export declare function nextStepLabel(status: QueueEntryStatus, entry?: {
+    lastFailedBaseSha: string | null;
+    specBasedOn: string | null;
+}): string;
+/** Describe the spec chain for a queue entry. */
+export declare function specChainLabel(entry: {
+    specBranch: string | null;
+    specBasedOn: string | null;
+    specSha: string | null;
+}, allEntries: Array<{
+    id: string;
+    prNumber: number;
+    specBranch: string | null;
+}>): string;
 export declare function runtimeLabel(runtime: QueueRuntimeStatus): string;
 export declare function formatEventSummary(event: QueueEventSummary): string;
 export declare function formatEntryEvent(event: QueueEventRecord): string;

package/dist/watch/format.js

@@ -38,12 +38,14 @@ export function statusColor(status) {
             return "gray";
     }
 }
-export function humanStatus(status) {
+export function humanStatus(status, entry) {
     switch (status) {
         case "queued":
             return "queued";
         case "preparing_head":
-            return "refreshing branch";
+            if (entry?.lastFailedBaseSha)
+                return "retry-gated";
+            return "building spec";
         case "validating":
             return "running CI";
         case "merging":
@@ -71,16 +73,18 @@ export function queueProgress(status) {
             return { current: 4, total: 4 };
     }
 }
-export function nextStepLabel(status) {
+export function nextStepLabel(status, entry) {
     switch (status) {
         case "queued":
             return "waiting for head-of-line turn";
         case "preparing_head":
-            return "refreshing branch with latest main";
+            if (entry?.lastFailedBaseSha)
+                return "waiting for base to advance";
+            return "building cumulative spec branch";
         case "validating":
-            return "waiting for CI result";
+            return "waiting for CI on spec branch";
         case "merging":
-            return "final GitHub merge";
+            return "pushing spec to main";
         case "merged":
             return "landed on main";
         case "evicted":
@@ -89,6 +93,18 @@ export function nextStepLabel(status) {
             return "removed manually";
     }
 }
+/** Describe the spec chain for a queue entry. */
+export function specChainLabel(entry, allEntries) {
+    if (!entry.specBranch)
+        return "no spec yet";
+    const parent = entry.specBasedOn
+        ? allEntries.find((e) => e.id === entry.specBasedOn)
+        : null;
+    const base = parent
+        ? `#${parent.prNumber}`
+        : "main";
+    return `${shortSha(entry.specSha)} \u2190 ${base}`;
+}
 export function runtimeLabel(runtime) {
     if (runtime.tickInProgress) {
         return "running";

package/dist/watch/state-visualization.js

@@ -96,19 +96,25 @@ export function buildExternalRepairObservations(detail, options) {
     if (entry.lastFailedBaseSha) {
         observations.push({
             tone: "warn",
-            text: `Waiting for ${entry.lastFailedBaseSha.slice(0, 7)} on base to change before retrying rebase.`,
+            text: `Retry-gated: conflict on base ${entry.lastFailedBaseSha.slice(0, 7)}. Waiting for base to advance before rebuilding spec.`,
         });
     }
     else if (entry.status === "validating") {
+        const specNote = entry.specBranch
+            ? `CI running on spec branch ${entry.specBranch}.`
+            : "Waiting on CI for the spec branch.";
+        const cascadeNote = entry.specBasedOn
+            ? " Will merge automatically when head clears (cascade)."
+            : "";
         observations.push({
             tone: "info",
-            text: "Waiting on validation CI for the refreshed head branch.",
+            text: `${specNote}${cascadeNote}`,
         });
     }
     else if (entry.status === "merging") {
         observations.push({
             tone: "info",
-            text: "Validation passed; steward is attempting the GitHub merge.",
+            text: "CI passed; pushing spec branch to main (fast-forward).",
         });
     }
     if (entry.generation > 0) {

package/package.json

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