merge-steward 0.25.0 → 0.26.1

package/dist/db/schema.js

@@ -76,6 +76,8 @@ export function ensureSchema(connection) {
     ensureColumn(connection, "queue_entries", "post_merge_checked_at", "TEXT");
     ensureColumn(connection, "queue_entries", "wait_detail", "TEXT");
     ensureColumn(connection, "queue_entries", "pr_title", "TEXT");
+    // Plan §8.4: stack-aware admission ordering needs the PR's base ref.
+    ensureColumn(connection, "queue_entries", "base_ref_name", "TEXT");
     // Plan §5.3: cached identity for patch-id-aware updateHead.
     ensureColumn(connection, "queue_entries", "head_patch_id", "TEXT");
     ensureColumn(connection, "queue_entries", "spec_tree_id", "TEXT");

package/dist/db/sqlite-store.js

@@ -30,6 +30,7 @@ function mapEntry(row) {
         postMergeSummary: row.post_merge_summary === null || row.post_merge_summary === undefined ? null : String(row.post_merge_summary),
         postMergeCheckedAt: row.post_merge_checked_at === null || row.post_merge_checked_at === undefined ? null : String(row.post_merge_checked_at),
         prTitle: row.pr_title === null || row.pr_title === undefined ? null : String(row.pr_title),
+        baseRefName: row.base_ref_name === null || row.base_ref_name === undefined ? null : String(row.base_ref_name),
         headPatchId: row.head_patch_id === null || row.head_patch_id === undefined ? null : String(row.head_patch_id),
         specTreeId: row.spec_tree_id === null || row.spec_tree_id === undefined ? null : String(row.spec_tree_id),
         enqueuedAt: String(row.enqueued_at),
@@ -128,9 +129,9 @@ export class SqliteStore {
           priority, generation, ci_run_id, ci_retries, retry_attempts,
           max_retries, last_failed_base_sha, issue_key, wait_detail,
           post_merge_status, post_merge_sha, post_merge_summary, post_merge_checked_at,
-          pr_title,
+          pr_title, base_ref_name,
           enqueued_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(entry.id, entry.repoId, entry.prNumber, entry.branch, entry.headSha, entry.baseSha, entry.status, entry.position, entry.priority, entry.generation, entry.ciRunId, entry.ciRetries, entry.retryAttempts, entry.maxRetries, entry.lastFailedBaseSha, entry.issueKey ?? null, entry.waitDetail ?? null, entry.postMergeStatus ?? null, entry.postMergeSha ?? null, entry.postMergeSummary ?? null, entry.postMergeCheckedAt ?? null, entry.prTitle ?? null, entry.enqueuedAt, entry.updatedAt);
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(entry.id, entry.repoId, entry.prNumber, entry.branch, entry.headSha, entry.baseSha, entry.status, entry.position, entry.priority, entry.generation, entry.ciRunId, entry.ciRetries, entry.retryAttempts, entry.maxRetries, entry.lastFailedBaseSha, entry.issueKey ?? null, entry.waitDetail ?? null, entry.postMergeStatus ?? null, entry.postMergeSha ?? null, entry.postMergeSummary ?? null, entry.postMergeCheckedAt ?? null, entry.prTitle ?? null, entry.baseRefName ?? null, entry.enqueuedAt, entry.updatedAt);
             this.writeEvent(entry.id, null, entry.status);
         })();
     }

package/dist/github/pr-client.js

@@ -24,7 +24,9 @@ export class GitHubPRClient {
         const result = await exec("gh", [
             "pr", "view", String(prNumber),
             "--repo", this.repoFullName,
-            "--json", "number,title,headRefName,headRefOid,reviewDecision,state,mergeStateStatus",
+            // Plan §8.4 change 3a: include baseRefName so the queue can
+            // detect stacked PRs at admission time.
+            "--json", "number,title,headRefName,headRefOid,baseRefName,reviewDecision,state,mergeStateStatus",
         ], { githubRepoFullName: this.repoFullName });
         const data = JSON.parse(result.stdout);
         return {
@@ -32,6 +34,7 @@ export class GitHubPRClient {
             branch: data.headRefName,
             headSha: data.headRefOid,
             ...(data.title ? { title: data.title } : {}),
+            ...(data.baseRefName ? { baseRefName: data.baseRefName } : {}),
             mergeable: data.state === "OPEN",
             mergeStateStatus: data.mergeStateStatus,
             reviewDecision: data.reviewDecision,

package/dist/reconciler-merge.d.ts

@@ -1,3 +1,7 @@
 import type { QueueEntry } from "./types.ts";
 import type { ReconcileContext } from "./reconciler-core.ts";
 export declare function mergeHead(ctx: ReconcileContext, entry: QueueEntry): Promise<void>;
+export declare function deletePrBranchAfterGitHubMarksMerged(ctx: ReconcileContext, entry: QueueEntry, options?: {
+    attempts?: number;
+    delayMs?: number;
+}): Promise<void>;

package/dist/reconciler-merge.js

@@ -2,6 +2,11 @@ import { CLEAN_CI, CLEAN_SPEC, emit, isBudgetExhausted, ref } from "./reconciler
 import { cleanupSpec, evictEntry, invalidateDownstream } from "./reconciler-evict.js";
 import { verifyPostMergeStatus } from "./reconciler-post-merge.js";
 import { getEffectiveMainStatus } from "./reconciler-main-status.js";
+const DEFAULT_PR_MERGED_POLL_ATTEMPTS = 6;
+const DEFAULT_PR_MERGED_POLL_DELAY_MS = 2_000;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export async function mergeHead(ctx, entry) {
     emit(ctx, entry, "merge_revalidating");
     const prStatus = await ctx.github.getStatus(entry.prNumber);
@@ -133,10 +138,36 @@ export async function mergeHead(ctx, entry) {
         postMergeCheckedAt: new Date().toISOString(),
     }, `spec pushed to main; ${verificationResult.postMergeSummary}`);
     await cleanupSpec(ctx, entry);
-    try {
-        await ctx.github.deleteBranch(entry.prNumber);
-    }
-    catch {
-        /* cosmetic */
+    await deletePrBranchAfterGitHubMarksMerged(ctx, entry);
+}
+export async function deletePrBranchAfterGitHubMarksMerged(ctx, entry, options = {}) {
+    const attempts = options.attempts ?? DEFAULT_PR_MERGED_POLL_ATTEMPTS;
+    const delayMs = options.delayMs ?? DEFAULT_PR_MERGED_POLL_DELAY_MS;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        let merged = false;
+        try {
+            merged = (await ctx.github.getStatus(entry.prNumber)).merged;
+        }
+        catch {
+            // Keep polling briefly. If GitHub is unavailable, branch cleanup is
+            // cosmetic; preserving correct PR merge classification matters more.
+        }
+        if (merged) {
+            try {
+                await ctx.github.deleteBranch(entry.prNumber);
+            }
+            catch {
+                emit(ctx, entry, "pr_branch_cleanup_failed", {
+                    detail: "GitHub marked the PR merged, but deleting the head branch failed",
+                });
+            }
+            return;
+        }
+        if (attempt < attempts - 1 && delayMs > 0) {
+            await delay(delayMs);
+        }
     }
+    emit(ctx, entry, "pr_branch_cleanup_deferred", {
+        detail: "waiting for GitHub to classify the fast-forwarded PR as merged before deleting the head branch",
+    });
 }

package/dist/service-queue.d.ts

@@ -19,6 +19,12 @@ export declare class MergeStewardQueueCommands {
         issueKey?: string;
         priority?: number;
         prTitle?: string;
+        /**
+         * Plan §8.4: PR's base ref. When this matches another open PR's
+         * `branch` (head ref), the entry is stacked and admission orders
+         * it immediately behind the parent.
+         */
+        baseRefName?: string;
     }): QueueEntry | undefined;
     scanStartupAdmissions(): Promise<void>;
     scanEligibleOpenPrs(): Promise<{
@@ -34,4 +40,5 @@ export declare class MergeStewardQueueCommands {
     private findAffectedEntriesAfterPriorityChange;
     private requeueAffectedEntries;
     private nextPosition;
+    private findActiveEntryByBranch;
 }

package/dist/service-queue.js

@@ -66,6 +66,7 @@ export class MergeStewardQueueCommands {
             headPatchId: null,
             specTreeId: null,
             prTitle: params.prTitle ?? null,
+            baseRefName: params.baseRefName ?? null,
             enqueuedAt: new Date().toISOString(),
             updatedAt: new Date().toISOString(),
         };
@@ -185,12 +186,36 @@ export class MergeStewardQueueCommands {
                     return false;
                 }
             }
+            // Plan §8.4: stack-aware admission. When the PR's base ref
+            // names another open PR's branch (head ref), the entry is
+            // stacked. Enqueue it only when the parent is already in the
+            // queue — otherwise the child's spec would build against the
+            // unmerged parent's pre-spec content. Positions are monotonic
+            // (`nextPosition`), so the child's position is always greater
+            // than the parent's; sibling PRs admitted between the parent's
+            // enqueue and the child's tryAdmit can sit between them. That's
+            // fine: queue head selection orders by (priority, position), so
+            // the parent is still processed before the child. The functional
+            // guarantee is "parent before child", not strict adjacency.
+            const baseRefName = status.baseRefName ?? null;
+            if (baseRefName && baseRefName !== this.config.baseBranch) {
+                const parentEntry = this.findActiveEntryByBranch(baseRefName);
+                if (!parentEntry) {
+                    this.logger.debug({
+                        prNumber,
+                        baseRefName,
+                        repoBaseBranch: this.config.baseBranch,
+                    }, "Deferring admission for stacked PR — parent branch is not in the queue yet");
+                    return false;
+                }
+            }
             this.enqueue({
                 prNumber,
                 branch,
                 headSha,
                 priority,
                 ...(status.title ? { prTitle: status.title } : {}),
+                ...(baseRefName ? { baseRefName } : {}),
             });
             return true;
         }
@@ -279,4 +304,10 @@ export class MergeStewardQueueCommands {
         }
         return next;
     }
+    // Plan §8.4: lookup helper used by stack-aware admission. Returns
+    // the active queue entry whose `branch` (head ref) matches `name`,
+    // or undefined when no such entry is in the queue.
+    findActiveEntryByBranch(name) {
+        return this.store.listActive(this.config.repoId).find((entry) => entry.branch === name);
+    }
 }

package/dist/types.d.ts

@@ -50,6 +50,13 @@ export interface QueueEntry {
     postMergeSummary: string | null;
     /** Timestamp of the most recent post-merge verification attempt. */
     postMergeCheckedAt: string | null;
+    /**
+     * Plan §8.4: PR's base ref captured at admission. When this names
+     * another open PR's `branch` (head ref), the entry is stacked and
+     * the queue holds it behind the parent until the parent is itself
+     * admitted. `null` when the PR was opened against the repo default.
+     */
+    baseRefName: string | null;
     /**
      * Plan §5.3: stable patch-id (`git patch-id --stable`) of the
      * current `headSha` against the entry's `baseSha`. Cached at spec
@@ -198,6 +205,12 @@ export interface PRStatus {
     branch: string;
     headSha: string;
     title?: string | undefined;
+    /**
+     * Plan §8.4: PR's base ref. When this names another open PR's
+     * `branch` (head ref), the PR is stacked and admission must defer
+     * until the parent is in the queue.
+     */
+    baseRefName?: string | undefined;
     mergeable: boolean;
     mergeStateStatus?: string | undefined;
     reviewDecision?: string | undefined;
@@ -211,7 +224,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" | "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" | "branch_unreachable";
 export interface ReconcileEvent {
     at: string;
     entryId: string;

package/package.json

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