merge-steward 0.30.2 → 0.31.0

package/README.md

@@ -1,14 +1,14 @@
 # merge-steward
 
-Self-hosted serial speculative merge queue for bot-managed and human-managed GitHub pull requests. Admits approved PRs whose required checks are green, builds speculative branches on top of the latest `main`, waits for CI on those integrated SHAs, and fast-forwards `main` to the tested result.
+Self-hosted merge queue for bot-managed and human-managed GitHub pull requests. Merge Steward turns reviewed PRs into a tested landing train: it runs CI on the exact future `main` SHAs, validates several PRs in parallel, and fast-forwards through the green sequence as soon as it is safe.
 
 Independent of PatchRelay. Communicates through GitHub only — PRs, reviews, checks, labels, branches. Pairs with `review-quill`; neither requires the other.
 
-For the background story and design trade-offs, read [merge-steward: a self-hosted merge queue without the Enterprise gate](https://blog.krasnoperov.me/posts/merge-steward).
+For the background story and design trade-offs, read [merge-steward: speculative integration, parallel validation, fast-forward landing](https://blog.krasnoperov.me/posts/merge-steward).
 
 ## Why this matters
 
-PRs delivered through the queue are tested against `main` as it was at admission time, and re-validated if `main` advances during validation. No more "CI was green yesterday, breaks on merge today" — the queue catches the integration bug before `main` ever sees it.
+The queue keeps delivery fast without pretending branch CI is enough. Each speculative branch is the cumulative queue order on top of the latest base: `main + A`, then `main + A + B`, then `main + A + B + C`. No more "CI was green yesterday, breaks on merge today" — the integration bug is caught before `main` ever sees it.
 
 ## How it works
 
@@ -97,7 +97,7 @@ Neither service calls the other's API.
 
 ## Reference
 
-- [merge-steward: a self-hosted merge queue without the Enterprise gate](https://blog.krasnoperov.me/posts/merge-steward) — background essay and design trade-offs
+- [merge-steward: speculative integration, parallel validation, fast-forward landing](https://blog.krasnoperov.me/posts/merge-steward) — background essay and design trade-offs
 - [docs/merge-steward.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/merge-steward.md) — operator reference: GitHub App permissions, secrets, webhook, repo config, full CLI, HTTP API, queue state machine, systemd, troubleshooting
 - [docs/merge-queue.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/merge-queue.md) — the two-service delivery story
 - [docs/github-queue-contract.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/github-queue-contract.md) — shared GitHub artifacts

package/dist/db/sqlite-store.d.ts

@@ -11,6 +11,7 @@ export declare class SqliteStore implements QueueStore {
     getEntryByPR(repoId: string, prNumber: number): QueueEntry | undefined;
     listActive(repoId: string): QueueEntry[];
     listAll(repoId: string): QueueEntry[];
+    listPostMergePending(repoId: string): QueueEntry[];
     insert(entry: QueueEntry): void;
     transition(entryId: string, to: QueueEntryStatus, patch?: Partial<Pick<QueueEntry, "headSha" | "baseSha" | "ciRunId" | "ciRetries" | "retryAttempts" | "lastFailedBaseSha" | "specBranch" | "specSha" | "specBasedOn" | "waitDetail" | "postMergeStatus" | "postMergeSha" | "postMergeSummary" | "postMergeCheckedAt" | "headPatchId" | "specTreeId">>, detail?: string): void;
     dequeue(entryId: string): void;

package/dist/db/sqlite-store.js

@@ -122,6 +122,13 @@ export class SqliteStore {
         const rows = this.conn.prepare("SELECT * FROM queue_entries WHERE repo_id = ? ORDER BY priority DESC, position ASC").all(repoId);
         return rows.map(mapEntry);
     }
+    listPostMergePending(repoId) {
+        const rows = this.conn.prepare(`SELECT * FROM queue_entries
+       WHERE repo_id = ? AND status = 'merged'
+         AND (post_merge_status IS NULL OR post_merge_status NOT IN ('pass', 'fail'))
+       ORDER BY position ASC`).all(repoId);
+        return rows.map(mapEntry);
+    }
     insert(entry) {
         this.conn.transaction(() => {
             this.conn.prepare(`INSERT INTO queue_entries

package/dist/reconciler.js

@@ -11,8 +11,10 @@ import { syncQueueStateLabels } from "./reconciler-queue-labels.js";
 // ─── Main reconcile loop ────────────────────────────────────────
 export async function reconcile(ctx) {
     const allActive = ctx.store.listActive(ctx.repoId);
-    if (allActive.length === 0)
-        return;
+    // Note: do NOT early-return when the active queue is empty. A drained queue
+    // can still hold merged entries whose post-merge verification is unresolved
+    // (e.g. an externally-merged PR), and verifyMergedEntriesPostPush below is
+    // the only thing that advances them. depth=0 simply skips the active loop.
     // 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);
@@ -91,10 +93,10 @@ export async function reconcile(ctx) {
     await verifyMergedEntriesPostPush(ctx);
 }
 async function verifyMergedEntriesPostPush(ctx) {
-    const mergedEntries = ctx.store.listAll(ctx.repoId).filter((entry) => entry.status === "merged");
+    // Targeted query (not listAll) so an idle repo with a large merged history
+    // doesn't scan every terminal row each tick — only the unresolved ones.
+    const mergedEntries = ctx.store.listPostMergePending(ctx.repoId);
     for (const entry of mergedEntries) {
-        if (entry.postMergeStatus === "pass" || entry.postMergeStatus === "fail")
-            continue;
         const postMergeSha = entry.postMergeSha ?? entry.specSha ?? entry.headSha;
         if (!postMergeSha) {
             continue;

package/dist/store.d.ts

@@ -10,6 +10,8 @@ export interface QueueStore {
     getEntryByPR(repoId: string, prNumber: number): QueueEntry | undefined;
     listActive(repoId: string): QueueEntry[];
     listAll(repoId: string): QueueEntry[];
+    /** Merged entries whose post-merge verification is unresolved (not pass/fail). */
+    listPostMergePending(repoId: string): QueueEntry[];
     insert(entry: QueueEntry): void;
     transition(entryId: string, to: QueueEntryStatus, patch?: Partial<Pick<QueueEntry, "headSha" | "baseSha" | "ciRunId" | "ciRetries" | "retryAttempts" | "lastFailedBaseSha" | "specBranch" | "specSha" | "specBasedOn" | "waitDetail" | "postMergeStatus" | "postMergeSha" | "postMergeSummary" | "postMergeCheckedAt" | "headPatchId" | "specTreeId">>, detail?: string): void;
     dequeue(entryId: string): void;

package/dist/watch/ProjectDetailView.d.ts

@@ -11,6 +11,9 @@ type ContentLine = {
 } | {
     kind: "entry-header";
     entry: DashboardPrEntry;
+} | {
+    kind: "stack-line";
+    text: string;
 } | {
     kind: "summary-line";
     text: string;

package/dist/watch/ProjectDetailView.js

@@ -20,6 +20,9 @@ export function buildContentLines(repo, width) {
         if (index > 0)
             lines.push({ kind: "blank" });
         lines.push({ kind: "entry-header", entry });
+        if (entry.stackedOnPr != null) {
+            lines.push({ kind: "stack-line", text: `↳ stacked on #${entry.stackedOnPr} (merges after it)` });
+        }
         if (entry.summary) {
             const summaryText = clipSummary(entry.summary, {
                 maxLines: 3,
@@ -45,6 +48,9 @@ function EntryHeaderRow({ entry, width }) {
 function renderLine(line, key, width) {
     if (line.kind === "blank")
         return _jsx(Box, { children: _jsx(Text, { children: " " }) }, key);
+    if (line.kind === "stack-line") {
+        return (_jsxs(Box, { children: [_jsx(Text, { children: " ".repeat(SUMMARY_INDENT) }), _jsx(Text, { color: "gray", children: line.text })] }, key));
+    }
     if (line.kind === "summary-line") {
         return (_jsxs(Box, { children: [_jsx(Text, { children: " ".repeat(SUMMARY_INDENT) }), _jsx(Text, { dimColor: true, children: line.text })] }, key));
     }

package/dist/watch/dashboard-model.d.ts

@@ -20,6 +20,12 @@ export interface DashboardToken {
     color: DashboardTokenColor;
     kind: DashboardTokenKind;
     eventAt: number;
+    /** Queue position; active entries are ordered by this so the stack/queue order shows. */
+    position: number;
+    /** Whether the entry is still in flight (not merged/evicted/dequeued). */
+    active: boolean;
+    /** PR number this entry's speculative spec is stacked on, when that parent is still active. */
+    stackedOnPr: number | null;
 }
 export interface DashboardPrEntry extends DashboardToken {
     phrase: string;

package/dist/watch/dashboard-model.js

@@ -127,6 +127,13 @@ function repoEntriesFromSnapshot(snapshot, cutoff) {
         .filter((entry) => isActive(entry.status))
         .sort((a, b) => a.position - b.position)[0] ?? null;
     const queueBlocked = queueBlockMatchesEntry(snapshot.queueBlock, head);
+    // Resolve speculative stacking: an entry's spec can be built on top of
+    // another entry's spec (specBasedOn -> that entry's id). Map ids to PR
+    // numbers so the views can show "stacked on #N". Only surface the link
+    // when the parent is still active, since a merged parent collapses the stack.
+    const idToEntry = new Map();
+    for (const entry of latest)
+        idToEntry.set(entry.id, entry);
     const byPr = new Map();
     for (const entry of latest) {
         const active = isActive(entry.status);
@@ -140,6 +147,8 @@ function repoEntriesFromSnapshot(snapshot, cutoff) {
         const glyph = GLYPH[kind];
         const color = COLOR[kind];
         const phrase = entryPhrase(entry, { isHead, queueBlocked });
+        const parent = entry.specBasedOn ? idToEntry.get(entry.specBasedOn) ?? null : null;
+        const stackedOnPr = parent && isActive(parent.status) ? parent.prNumber : null;
         const item = {
             prNumber: entry.prNumber,
             glyph,
@@ -147,6 +156,9 @@ function repoEntriesFromSnapshot(snapshot, cutoff) {
             kind,
             phrase,
             eventAt: timestamp(entry.updatedAt),
+            position: entry.position,
+            active,
+            stackedOnPr,
         };
         const summary = entrySummary(entry);
         if (summary)
@@ -156,7 +168,16 @@ function repoEntriesFromSnapshot(snapshot, cutoff) {
             item.title = title;
         byPr.set(entry.prNumber, item);
     }
+    // Active entries first, in queue/stack order (by position, head first) so
+    // speculative stacks read top-to-bottom; decided entries follow, newest-first.
     return [...byPr.values()].sort((left, right) => {
+        if (left.active !== right.active)
+            return left.active ? -1 : 1;
+        if (left.active) {
+            if (left.position !== right.position)
+                return left.position - right.position;
+            return left.prNumber - right.prNumber;
+        }
         const leftOrder = tokenSortOrder(left.kind);
         const rightOrder = tokenSortOrder(right.kind);
         if (leftOrder !== rightOrder)
@@ -193,7 +214,7 @@ export function buildDashboard(repos, opts = {}) {
         return {
             repoId: repo.repoId,
             repoFullName: repo.repoFullName,
-            tokens: entries.map(({ prNumber, glyph, color, kind, eventAt }) => ({ prNumber, glyph, color, kind, eventAt })),
+            tokens: entries.map(({ prNumber, glyph, color, kind, eventAt, position, active, stackedOnPr }) => ({ prNumber, glyph, color, kind, eventAt, position, active, stackedOnPr })),
             entries,
             latestActivityAt,
             hasActivity: entries.length > 0,

package/dist/watch/format.d.ts

@@ -11,6 +11,7 @@ export declare function formatRepoTokenText(token: {
     prNumber: number;
     glyph: string;
     eventAt: number;
+    stackedOnPr?: number | null;
 }): string;
 export declare function mergeWaitState(entry: {
     status: QueueEntryStatus;

package/dist/watch/format.js

@@ -49,7 +49,10 @@ export function formatTokenAge(eventAt) {
     return relativeTime(eventAt).padStart(4, " ");
 }
 export function formatRepoTokenText(token) {
-    return `#${token.prNumber} ${token.glyph} ${relativeTime(token.eventAt)}`;
+    // A leading connector marks an entry whose spec is speculatively stacked on
+    // the PR shown just before it, so the queue order reads as a stack.
+    const stackMark = token.stackedOnPr != null ? "↳" : "";
+    return `${stackMark}#${token.prNumber} ${token.glyph} ${relativeTime(token.eventAt)}`;
 }
 export function mergeWaitState(entry) {
     if (!entry || entry.status !== "merging" || !entry.waitDetail) {

package/package.json

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