merge-steward 0.29.0 → 0.30.1

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/dist/config.d.ts

@@ -30,6 +30,8 @@ export declare const stewardConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     admissionLabel: z.ZodDefault<z.ZodString>;
     priorityQueueLabel: z.ZodDefault<z.ZodString>;
+    queueTestingLabel: z.ZodDefault<z.ZodString>;
+    queueMergingLabel: z.ZodDefault<z.ZodString>;
     mergeQueueCheckName: z.ZodDefault<z.ZodString>;
     evictionCheckName: z.ZodDefault<z.ZodString>;
     specReadyCheckName: z.ZodDefault<z.ZodString>;

package/dist/config.js

@@ -31,6 +31,12 @@ export const stewardConfigSchema = z.object({
     }).default({ level: "info" }),
     admissionLabel: z.string().default("queue"),
     priorityQueueLabel: z.string().default("queue:priority"),
+    // Queue sub-state labels — applied/cleared by the reconciler so a PR's
+    // live position in the merge queue is visible on GitHub and readable by
+    // patchrelay for its Linear "In Merge Queue" status. `queue:testing` =
+    // spec CI validating; `queue:merging` = head, merge in progress.
+    queueTestingLabel: z.string().default("queue:testing"),
+    queueMergingLabel: z.string().default("queue:merging"),
     mergeQueueCheckName: z.string().default(DEFAULT_MERGE_QUEUE_CHECK_NAME),
     // Plan §2.4 — bus-contract artifact names exposed for cross-service
     // alignment. Defaults preserve current behavior. The steward writes

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

@@ -29,4 +29,8 @@ export declare class GitHubPRClient implements GitHubPRApi {
     deleteBranch(prNumber: number): Promise<void>;
     findPRByBranch(branch: string): Promise<number | null>;
     listLabels(prNumber: number): Promise<string[]>;
+    setLabels(prNumber: number, opts: {
+        add?: string[];
+        remove?: string[];
+    }): Promise<void>;
 }

package/dist/github/pr-client.js

@@ -146,6 +146,17 @@ export class GitHubPRClient {
             return [];
         }
     }
+    async setLabels(prNumber, opts) {
+        const args = ["pr", "edit", String(prNumber), "--repo", this.repoFullName];
+        for (const label of opts.add ?? [])
+            args.push("--add-label", label);
+        for (const label of opts.remove ?? [])
+            args.push("--remove-label", label);
+        // Nothing to change beyond the base args — skip the call.
+        if (args.length === 5)
+            return;
+        await exec("gh", args, { allowNonZero: true, githubRepoFullName: this.repoFullName });
+    }
 }
 /** Map GitHub REST API check-run status/conclusion to our union. */
 function mapRestConclusion(status, conclusion) {

package/dist/interfaces.d.ts

@@ -50,6 +50,11 @@ export interface GitHubPRApi {
     listChecks(prNumber: number): Promise<CheckResult[]>;
     listChecksForRef(ref: string): Promise<CheckResult[]>;
     listLabels(prNumber: number): Promise<string[]>;
+    /** Add and/or remove labels on a PR in a single edit. */
+    setLabels(prNumber: number, opts: {
+        add?: string[];
+        remove?: string[];
+    }): Promise<void>;
     /** List open PRs for restart-time eligibility scans. */
     listOpenPRs(): Promise<Array<{
         number: number;

package/dist/reconciler-core.d.ts

@@ -15,6 +15,13 @@ export interface ReconcileContext {
     speculativeDepth: number;
     flakyRetries: number;
     policy: GitHubPolicyCache;
+    /** Queue sub-state label names. When set, the reconciler keeps the
+     * `testing`/`merging` labels on each PR in sync with its phase so the
+     * queue position is visible on GitHub. Omit to disable label sync. */
+    queueStateLabels?: {
+        testing: string;
+        merging: string;
+    };
     onEvent: (event: ReconcileEvent) => void;
 }
 export declare const SPEC_BRANCH_PREFIX = "mq-spec-";

package/dist/reconciler-queue-labels.d.ts

@@ -0,0 +1,18 @@
+import type { ReconcileContext } from "./reconciler-core.ts";
+import type { QueueEntry } from "./types.ts";
+/**
+ * Edge-triggered GitHub label sync for queue sub-state.
+ *
+ * The label is a pure function of the entry's phase, so a PR's live
+ * position in the merge queue is obvious from GitHub — and readable by
+ * patchrelay to drive its Linear "In Merge Queue" status:
+ *
+ *   validating → testing label  (spec CI is running / awaiting turn)
+ *   merging    → merging label  (head of queue, merge in progress)
+ *   everything else (queued, preparing_head, merged, evicted, …) → neither
+ *
+ * Idempotent: reads the PR's current labels and only edits the delta, so
+ * it is safe to call every tick and after a restart. Cosmetic-only — any
+ * GitHub error is swallowed so it can never break the reconcile loop.
+ */
+export declare function syncQueueStateLabels(ctx: ReconcileContext, entry: QueueEntry): Promise<void>;

package/dist/reconciler-queue-labels.js

@@ -0,0 +1,48 @@
+import { emit } from "./reconciler-core.js";
+/**
+ * Edge-triggered GitHub label sync for queue sub-state.
+ *
+ * The label is a pure function of the entry's phase, so a PR's live
+ * position in the merge queue is obvious from GitHub — and readable by
+ * patchrelay to drive its Linear "In Merge Queue" status:
+ *
+ *   validating → testing label  (spec CI is running / awaiting turn)
+ *   merging    → merging label  (head of queue, merge in progress)
+ *   everything else (queued, preparing_head, merged, evicted, …) → neither
+ *
+ * Idempotent: reads the PR's current labels and only edits the delta, so
+ * it is safe to call every tick and after a restart. Cosmetic-only — any
+ * GitHub error is swallowed so it can never break the reconcile loop.
+ */
+export async function syncQueueStateLabels(ctx, entry) {
+    const labels = ctx.queueStateLabels;
+    if (!labels)
+        return;
+    const managed = [labels.testing, labels.merging];
+    const desired = entry.status === "validating" ? labels.testing
+        : entry.status === "merging" ? labels.merging
+            : null;
+    let current;
+    try {
+        current = await ctx.github.listLabels(entry.prNumber);
+    }
+    catch {
+        return;
+    }
+    const add = desired && !current.includes(desired) ? [desired] : [];
+    const remove = managed.filter((l) => l !== desired && current.includes(l));
+    if (add.length === 0 && remove.length === 0)
+        return;
+    try {
+        await ctx.github.setLabels(entry.prNumber, { add, remove });
+        const parts = [];
+        if (add.length)
+            parts.push(`+${add.join(",")}`);
+        if (remove.length)
+            parts.push(`-${remove.join(",")}`);
+        emit(ctx, entry, "queue_label_synced", { detail: `${entry.status}: ${parts.join(" ")}` });
+    }
+    catch {
+        // best-effort; the next tick retries
+    }
+}

package/dist/reconciler.js

@@ -7,6 +7,7 @@ import { mergeHead } from "./reconciler-merge.js";
 import { cleanupSpec } from "./reconciler-evict.js";
 import { INVALIDATION_PATCH } from "./invalidation.js";
 import { verifyPostMergeStatus } from "./reconciler-post-merge.js";
+import { syncQueueStateLabels } from "./reconciler-queue-labels.js";
 // ─── Main reconcile loop ────────────────────────────────────────
 export async function reconcile(ctx) {
     const allActive = ctx.store.listActive(ctx.repoId);
@@ -21,8 +22,14 @@ export async function reconcile(ctx) {
         if (!entry || TERMINAL_STATUSES.includes(entry.status))
             continue;
         // Truth guard: verify entry against GitHub before processing.
-        if (await sanitizeEntry(ctx, entry))
+        if (await sanitizeEntry(ctx, entry)) {
+            // Entry may have been terminalized (closed/duplicate) — clear any
+            // stale queue sub-state label it still carries.
+            const sanitized = ctx.store.getEntry(entry.id);
+            if (sanitized)
+                await syncQueueStateLabels(ctx, sanitized);
             continue;
+        }
         // Stale dependency guard: if this entry's spec was built on top of
         // another entry that was dequeued or evicted (without downstream
         // invalidation), the spec is contaminated with the removed entry's
@@ -74,6 +81,12 @@ export async function reconcile(ctx) {
                 wrapped.stack = error.stack;
             throw wrapped;
         }
+        // Sync the GitHub queue sub-state label to the (possibly just
+        // transitioned) phase: queue:testing while validating, queue:merging
+        // while merging, cleared once merged/preparing/terminal.
+        const post = ctx.store.getEntry(entry.id);
+        if (post)
+            await syncQueueStateLabels(ctx, post);
     }
     await verifyMergedEntriesPostPush(ctx);
 }

package/dist/service-runtime.js

@@ -138,6 +138,10 @@ export class MergeStewardRuntime {
                 eviction: this.eviction,
                 flakyRetries: this.config.flakyRetries,
                 policy: this.policy,
+                queueStateLabels: {
+                    testing: this.config.queueTestingLabel,
+                    merging: this.config.queueMergingLabel,
+                },
                 onEvent: (event) => {
                     this.lastReconcileEvent = summarizeReconcileEvent(event);
                     const isWarn = event.action === "evicted" || event.action === "spec_build_conflict"

package/dist/types.d.ts

@@ -242,7 +242,7 @@ export interface QueueConfig {
     flakyRetries: number;
     pollIntervalMs: number;
 }
-export type ReconcileAction = "promoted" | "fetch_started" | "main_broken" | "branch_mismatch" | "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" | "policy_changed" | "evicted" | "invalidated" | "retry_gated" | "budget_exhausted" | "merge_waiting_approval" | "merge_waiting_main" | "main_pending_bypassed" | "pr_branch_cleanup_deferred" | "pr_branch_cleanup_failed" | "sanitized_closed" | "sanitized_duplicate" | "post_merge_verification_started" | "post_merge_verification_completed" | "branch_unreachable";
+export type ReconcileAction = "promoted" | "fetch_started" | "main_broken" | "branch_mismatch" | "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" | "policy_changed" | "evicted" | "invalidated" | "retry_gated" | "budget_exhausted" | "merge_waiting_approval" | "merge_waiting_main" | "main_pending_bypassed" | "pr_branch_cleanup_deferred" | "pr_branch_cleanup_failed" | "sanitized_closed" | "sanitized_duplicate" | "post_merge_verification_started" | "post_merge_verification_completed" | "queue_label_synced" | "branch_unreachable";
 export interface ReconcileEvent {
     at: string;
     entryId: string;

package/package.json

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