merge-steward 0.30.0 → 0.30.2

package/README.md

@@ -1,9 +1,11 @@
 # merge-steward
 
-Self-hosted serial 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 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.
 
 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).
+
 ## 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.
@@ -36,17 +38,18 @@ Prerequisites: Node.js 24+, `gh` CLI in `PATH`, `git`.
 ```bash
 pnpm add -g merge-steward
 merge-steward init https://queue.example.com
-merge-steward attach owner/repo --base-branch main
+merge-steward repo attach owner/repo --base-branch main
 merge-steward doctor --repo repo
 merge-steward service status
 merge-steward queue status --repo repo
 ```
 
-- `init` writes config files, a systemd unit, and a generated webhook secret.
-- `attach` discovers the default branch from GitHub and stores a per-repo config.
+- `init` writes config files and a systemd unit, then prints the webhook URL to configure in GitHub.
+- You still need to install `merge-steward-webhook-secret` and `merge-steward-github-app-pem` via systemd credentials, or provide the documented environment/file fallbacks.
+- `repo attach` discovers the default branch from GitHub and stores a per-repo config.
 - Required checks are learned from GitHub branch protection at runtime — the steward does not keep a local copy.
 
-Full setup (GitHub App permissions, secrets, webhook events, systemd, HTTP API): [docs/merge-steward.md](../../docs/merge-steward.md).
+Full setup (GitHub App permissions, secrets, webhook events, systemd, HTTP API): [docs/merge-steward.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/merge-steward.md).
 
 ## Everyday commands
 
@@ -77,7 +80,7 @@ The real gate is:
 - configured required checks are green
 - the steward's speculative integrated branch also passes CI
 
-`review-quill/verdict` only matters if you include it in the repo's required checks. Branch protection is useful as defense in depth, but the steward merges by fast-forwarding `main` to the already-tested speculative SHA — not by pressing GitHub's merge button. Successful merges therefore depend on the steward App being allowed to push to the protected branch. See [docs/merge-steward.md](../../docs/merge-steward.md) for the full App permission set.
+`review-quill/verdict` only matters if you include it in the repo's required checks. Branch protection is useful as defense in depth, but the steward merges by fast-forwarding `main` to the already-tested speculative SHA — not by pressing GitHub's merge button. Successful merges therefore depend on the steward App being allowed to push to the protected branch. See [docs/merge-steward.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/merge-steward.md) for the full App permission set.
 
 **`main`'s own CI is information-only.** The speculative SHA the steward tests *is* the exact tree that becomes `main`, so re-testing `main` after the push adds no signal — it only catches flakiness or out-of-band changes (direct pushes, hotfixes). The queue therefore **ignores `main`'s CI entirely** for advancement: it does not gate landing on `main` being green, does not wait for `main` CI before the next landing, and is never "paused" by a red `main`. A red `main` with a green speculative SHA simply means the red was flaky or is fixed by landing — so the steward lands. Use `main`'s CI as a project-health canary, not a queue control.
 
@@ -94,8 +97,9 @@ Neither service calls the other's API.
 
 ## Reference
 
-- [docs/merge-steward.md](../../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](../../docs/merge-queue.md) — the two-service delivery story
-- [docs/github-queue-contract.md](../../docs/github-queue-contract.md) — shared GitHub artifacts
-- [docs/design-docs/merge-steward.md](../../docs/design-docs/merge-steward.md) — design rationale
-- [../../README.md](../../README.md) — the three-service stack overview
+- [merge-steward: a self-hosted merge queue without the Enterprise gate](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
+- [docs/design-docs/merge-steward.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/design-docs/merge-steward.md) — design rationale
+- [README.md](https://github.com/krasnoperov/patchrelay/blob/main/README.md) — the three-service stack overview

package/dist/cli/commands/pr-status.d.ts

@@ -4,6 +4,19 @@ import { type ResolveCommandRunner } from "../resolve.ts";
 import { type PrGitHubOverview } from "./pr-github.ts";
 export type PrStatusKind = "merged" | "merged_outside_queue" | "queued" | "preparing_head" | "validating" | "merging" | "evicted" | "dequeued" | "closed" | "changes_requested" | "checks_failing" | "checks_pending" | "approved_clean" | "not_queued";
 export type PrStatusSource = "queue" | "github";
+/**
+ * Live position of an entry among the entries actually still in the queue,
+ * ordered the way the reconciler processes them (priority DESC, position
+ * ASC). This is what an operator means by "where am I in line" — unlike the
+ * raw `position`, which is a lifetime admission counter that only ever
+ * grows (every PR ever queued bumps it), so a value like 290 reads as "289
+ * ahead" when in reality only a couple of entries are active.
+ */
+export interface QueueActiveRank {
+    rank: number;
+    activeTotal: number;
+}
+export declare function computeActiveRank(entries: QueueEntry[], target: QueueEntry): QueueActiveRank | undefined;
 export interface PrStatusReport {
     repoId: string;
     repoFullName: string;
@@ -15,6 +28,7 @@ export interface PrStatusReport {
     reason?: string;
     queueEntry?: QueueEntry;
     queueSource?: "service" | "database";
+    queueActiveRank?: QueueActiveRank;
     queueRuntime?: QueueRuntimeStatus;
     queueLatestEvent?: QueueEventSummary;
     github?: PrGitHubOverview;
@@ -32,6 +46,7 @@ export interface BuildReportOptions {
     prNumber: number;
     queueEntry?: QueueEntry | undefined;
     queueSource?: "service" | "database" | undefined;
+    queueActiveRank?: QueueActiveRank | undefined;
     queueRuntime?: QueueRuntimeStatus | undefined;
     queueLatestEvent?: QueueEventSummary | undefined;
     github?: PrGitHubOverview | undefined;

package/dist/cli/commands/pr-status.js

@@ -5,6 +5,18 @@ import { defaultResolveRunner, resolvePrNumber, resolveRepo } from "../resolve.j
 import { parseIntegerFlag } from "../args.js";
 import { fetchPrGitHubOverview } from "./pr-github.js";
 import { formatRuntimeActivity } from "../../runtime-format.js";
+const TERMINAL_QUEUE_STATUSES = new Set(["merged", "evicted", "dequeued"]);
+export function computeActiveRank(entries, target) {
+    if (TERMINAL_QUEUE_STATUSES.has(target.status))
+        return undefined;
+    const active = entries
+        .filter((entry) => !TERMINAL_QUEUE_STATUSES.has(entry.status))
+        .sort((a, b) => (b.priority - a.priority) || (a.position - b.position));
+    const index = active.findIndex((entry) => entry.id === target.id);
+    if (index < 0)
+        return undefined;
+    return { rank: index + 1, activeTotal: active.length };
+}
 export function classifyQueueEntry(entry) {
     switch (entry.status) {
         case "merged": return "merged";
@@ -85,11 +97,13 @@ async function loadQueueEntry(config, prNumber) {
         if (!entry)
             return { kind: "not_found" };
         const latestEvent = latestEventForPr(snapshot, prNumber);
+        const activeRank = computeActiveRank(snapshot.entries, entry);
         return {
             kind: "found",
             entry,
             source: "service",
             runtime: snapshot.runtime,
+            ...(activeRank ? { activeRank } : {}),
             ...(latestEvent ? { latestEvent } : {}),
         };
     }
@@ -99,7 +113,8 @@ async function loadQueueEntry(config, prNumber) {
         }
         const store = new SqliteStore(config.database.path);
         try {
-            const entries = store.listAll(config.repoId).filter((entry) => entry.prNumber === prNumber);
+            const all = store.listAll(config.repoId);
+            const entries = all.filter((entry) => entry.prNumber === prNumber);
             if (entries.length === 0)
                 return { kind: "not_found" };
             entries.sort((left, right) => {
@@ -109,7 +124,9 @@ async function loadQueueEntry(config, prNumber) {
                     return leftTerminal - rightTerminal;
                 return right.position - left.position;
             });
-            return { kind: "found", entry: entries[0], source: "database" };
+            const entry = entries[0];
+            const activeRank = computeActiveRank(all, entry);
+            return { kind: "found", entry, source: "database", ...(activeRank ? { activeRank } : {}) };
         }
         finally {
             store.close();
@@ -138,6 +155,7 @@ export function buildPrStatusReport(options) {
             exitCode: exitCodeForKind(kind),
             queueEntry: options.queueEntry,
             ...(options.queueSource ? { queueSource: options.queueSource } : {}),
+            ...(options.queueActiveRank ? { queueActiveRank: options.queueActiveRank } : {}),
             ...(options.queueRuntime ? { queueRuntime: options.queueRuntime } : {}),
             ...(options.queueLatestEvent ? { queueLatestEvent: options.queueLatestEvent } : {}),
             checkedAt,
@@ -172,7 +190,12 @@ export function formatReportText(report) {
         lines.push(`Reason: ${report.reason}`);
     if (report.queueEntry) {
         const entry = report.queueEntry;
-        lines.push(`Queue position: ${entry.position}`);
+        // Show live rank among active entries — NOT the raw `position`, which is
+        // a lifetime admission counter and reads as a huge phantom backlog.
+        if (report.queueActiveRank) {
+            const { rank, activeTotal } = report.queueActiveRank;
+            lines.push(`Queue position: ${rank} of ${activeTotal} active`);
+        }
         lines.push(`Branch: ${entry.branch}`);
         lines.push(`Head SHA: ${entry.headSha}`);
         if (entry.waitDetail)
@@ -260,6 +283,7 @@ export async function handlePrStatus(options) {
                 prNumber: resolvedPr.prNumber,
                 queueEntry: queueResult.entry,
                 queueSource: queueResult.source,
+                ...(queueResult.activeRank ? { queueActiveRank: queueResult.activeRank } : {}),
                 ...(queueResult.runtime ? { queueRuntime: queueResult.runtime } : {}),
                 ...(queueResult.latestEvent ? { queueLatestEvent: queueResult.latestEvent } : {}),
             });

package/package.json

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