merge-steward 0.29.0 → 0.30.0

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.0",
   "description": "Serial merge queue for GitHub — rebase, CI-gate, and merge PRs one at a time",
   "type": "module",
   "repository": {