merge-steward 0.24.0 → 0.26.0

package/dist/db/schema.js

@@ -76,6 +76,11 @@ 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");
     connection.exec(`
     UPDATE queue_entries
        SET post_merge_status = 'pending'

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

@@ -12,9 +12,17 @@ export declare class SqliteStore implements QueueStore {
     listActive(repoId: string): QueueEntry[];
     listAll(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">>, detail?: string): 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;
     updateHead(entryId: string, newHeadSha: string): void;
+    rebuildSpecHeadEquivalent(entryId: string, patch: {
+        headSha: string;
+        specSha: string;
+        specBranch: string;
+        headPatchId: string;
+        specTreeId: string;
+        ciRunId: string | null;
+    }, detail?: string): void;
     updatePriority(entryId: string, priority: number, detail?: string): void;
     insertIncident(incident: IncidentRecord): void;
     listIncidents(entryId: string): IncidentRecord[];

package/dist/db/sqlite-store.js

@@ -30,6 +30,9 @@ 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),
         updatedAt: String(row.updated_at),
     };
@@ -126,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);
         })();
     }
@@ -199,6 +202,14 @@ export class SqliteStore {
                 sets.push("post_merge_checked_at = ?");
                 values.push(patch.postMergeCheckedAt);
             }
+            if (patch?.headPatchId !== undefined) {
+                sets.push("head_patch_id = ?");
+                values.push(patch.headPatchId);
+            }
+            if (patch?.specTreeId !== undefined) {
+                sets.push("spec_tree_id = ?");
+                values.push(patch.specTreeId);
+            }
             this.conn.prepare(`UPDATE queue_entries SET ${sets.join(", ")} WHERE id = ?`).run(...values, entryId);
             this.writeEvent(entryId, from, to, detail);
         })();
@@ -222,11 +233,34 @@ export class SqliteStore {
           spec_branch = NULL, spec_sha = NULL, spec_based_on = NULL,
           wait_detail = NULL,
           post_merge_status = NULL, post_merge_sha = NULL, post_merge_summary = NULL, post_merge_checked_at = NULL,
+          head_patch_id = NULL, spec_tree_id = NULL,
           updated_at = ?
          WHERE id = ?`).run(newHeadSha, newGen, isoNow(), entryId);
             this.writeEvent(entryId, from, "queued", `updateHead: generation ${newGen}`);
         })();
     }
+    rebuildSpecHeadEquivalent(entryId, patch, detail) {
+        this.conn.transaction(() => {
+            const current = this.conn.prepare("SELECT status, generation FROM queue_entries WHERE id = ?").get(entryId);
+            if (!current)
+                return;
+            const from = String(current.status);
+            if (TERMINAL_STATUSES.includes(from))
+                return;
+            const newGen = Number(current.generation) + 1;
+            this.conn.prepare(`UPDATE queue_entries SET
+          head_sha = ?, status = 'validating', generation = ?,
+          ci_run_id = ?, ci_retries = 0, retry_attempts = 0,
+          last_failed_base_sha = NULL,
+          spec_branch = ?, spec_sha = ?,
+          head_patch_id = ?, spec_tree_id = ?,
+          wait_detail = NULL,
+          post_merge_status = NULL, post_merge_sha = NULL, post_merge_summary = NULL, post_merge_checked_at = NULL,
+          updated_at = ?
+         WHERE id = ?`).run(patch.headSha, newGen, patch.ciRunId, patch.specBranch, patch.specSha, patch.headPatchId, patch.specTreeId, isoNow(), entryId);
+            this.writeEvent(entryId, from, "validating", detail ?? `patch-id-equivalent rebuild: generation ${newGen}`);
+        })();
+    }
     updatePriority(entryId, priority, detail) {
         this.conn.transaction(() => {
             const current = this.conn.prepare("SELECT status, priority FROM queue_entries WHERE id = ?").get(entryId);

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/github/shell-git.d.ts

@@ -25,6 +25,11 @@ export declare class ShellGitOperations implements GitOperations, SpeculativeBra
     headSha(branch: string): Promise<string>;
     isAncestor(ancestor: string, descendant: string): Promise<boolean>;
     push(branch: string, force?: boolean, targetBranch?: string): Promise<void>;
+    patchIdAgainst(base: string, headSha: string): Promise<string | undefined>;
+    integrationTreeId(base: string, headSha: string): Promise<string | undefined>;
+    treeId(commitSha: string): Promise<string | undefined>;
+    commitTree(tree: string, parents: string[], message: string): Promise<string | undefined>;
+    pushCommit(commitSha: string, branch: string): Promise<void>;
     /**
      * Build a speculative merge branch using an isolated git worktree.
      * Each call gets its own working directory — no shared mutable state.

package/dist/github/shell-git.js

@@ -1,6 +1,10 @@
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { exec } from "../exec.js";
+/** Shell-quote a string for sh -c invocation (single-quote, escape inner quotes). */
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
 /** Extract conflict file names from git merge stderr. */
 function parseConflicts(stderr) {
     const files = stderr
@@ -90,6 +94,64 @@ export class ShellGitOperations {
         args.push("origin", refspec);
         await this.git(args, { timeoutMs: 60_000 });
     }
+    // Plan §5.3: identity primitives for patch-id-aware updateHead.
+    async patchIdAgainst(base, headSha) {
+        // `git diff base..head | git patch-id --stable` — invoke as one
+        // pipeline through a shell so we don't have to plumb stdin/stdout.
+        const result = await exec("sh", ["-c", `${this.gitBin} -C ${shellQuote(this.clonePath)} diff ${shellQuote(base)}..${shellQuote(headSha)} | ${this.gitBin} patch-id --stable`], {
+            timeoutMs: 30_000,
+            allowNonZero: true,
+            githubRepoFullName: this.repoFullName,
+        });
+        if (result.exitCode !== 0)
+            return undefined;
+        const first = result.stdout.split(/\s+/, 1)[0]?.trim();
+        return first ? first : undefined;
+    }
+    async integrationTreeId(base, headSha) {
+        const result = await this.git(["merge-tree", "--write-tree", "--no-messages", base, headSha], { allowNonZero: true, timeoutMs: 60_000 });
+        if (result.exitCode !== 0)
+            return undefined;
+        const tree = result.stdout.trim().split(/\s+/, 1)[0];
+        return tree || undefined;
+    }
+    async treeId(commitSha) {
+        const result = await this.git(["rev-parse", `${commitSha}^{tree}`], { allowNonZero: true });
+        if (result.exitCode !== 0)
+            return undefined;
+        const tree = result.stdout.trim();
+        return tree || undefined;
+    }
+    async commitTree(tree, parents, message) {
+        const args = ["commit-tree", tree];
+        for (const parent of parents) {
+            args.push("-p", parent);
+        }
+        args.push("-m", message);
+        const env = {};
+        if (this.botIdentity) {
+            env.GIT_AUTHOR_NAME = this.botIdentity.name;
+            env.GIT_AUTHOR_EMAIL = this.botIdentity.email;
+            env.GIT_COMMITTER_NAME = this.botIdentity.name;
+            env.GIT_COMMITTER_EMAIL = this.botIdentity.email;
+        }
+        const result = await exec(this.gitBin, ["-C", this.clonePath, ...args], {
+            timeoutMs: 30_000,
+            allowNonZero: true,
+            githubRepoFullName: this.repoFullName,
+            ...(Object.keys(env).length > 0 ? { env } : {}),
+        });
+        if (result.exitCode !== 0)
+            return undefined;
+        const sha = result.stdout.trim();
+        return sha || undefined;
+    }
+    async pushCommit(commitSha, branch) {
+        // Force-update the named branch on origin to a known commit
+        // SHA. Used by the patch-id-aware rebuild path which writes a
+        // synthetic commit-tree result without checking it out.
+        await this.git(["push", "--force", "origin", `${commitSha}:refs/heads/${branch}`], { timeoutMs: 60_000 });
+    }
     // ─── SpeculativeBranchBuilder ───────────────────────────────
     /**
      * Build a speculative merge branch using an isolated git worktree.

package/dist/interfaces.d.ts

@@ -8,6 +8,16 @@ export interface GitOperations {
     headSha(branch: string): Promise<string>;
     isAncestor(ancestor: string, descendant: string): Promise<boolean>;
     push(branch: string, force?: boolean, targetBranch?: string): Promise<void>;
+    /** Stable patch-id of head's diff against base. Returns undefined on git error. */
+    patchIdAgainst?(base: string, headSha: string): Promise<string | undefined>;
+    /** `git merge-tree --write-tree base headSha` — returns tree-id, or undefined on conflict/error. */
+    integrationTreeId?(base: string, headSha: string): Promise<string | undefined>;
+    /** Tree id of a commit (`commit^{tree}`). */
+    treeId?(commitSha: string): Promise<string | undefined>;
+    /** `git commit-tree tree -p p1 -p p2 -m message`. Returns the new commit SHA. */
+    commitTree?(tree: string, parents: string[], message: string): Promise<string | undefined>;
+    /** Force-push a known commit SHA to a branch (overrides the target ref directly). */
+    pushCommit?(commitSha: string, branch: string): Promise<void>;
 }
 /**
  * Builds and manages speculative cumulative branches.

package/dist/reconciler-prepare.js

@@ -41,6 +41,18 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
     const currentRef = await ctx.git.headSha(ref(ctx, entry.branch));
     if (currentRef !== entry.headSha) {
         emit(ctx, entry, "branch_mismatch", { detail: `expected ${entry.headSha.slice(0, 8)}, got ${currentRef.slice(0, 8)}` });
+        // Plan §5.3: patch-id-aware short-circuit. If the new head is
+        // patch-id-equivalent to the prior head AND the freshly merged
+        // tree matches the cached spec tree, rebuild the spec commit
+        // with the new head as its second parent so GitHub still marks
+        // the PR merged after the lander's fast-forward — but skip the
+        // prepare cycle. CI must re-run on the new spec SHA (check_runs
+        // are SHA-anchored). Falls back to the standard `updateHead`
+        // path if the git plumbing is unavailable or if the identities
+        // don't match.
+        const shortCircuited = await tryPatchIdEquivalentRebuild(ctx, entry, base, currentRef);
+        if (shortCircuited)
+            return;
         ctx.store.updateHead(entry.id, currentRef);
         return;
     }
@@ -170,6 +182,16 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
     }
     const runId = await ctx.ci.triggerRun(specName, specSha);
     emit(ctx, entry, "ci_triggered", { ciRunId: runId, specBranch: specName });
+    // Plan §5.3: cache identity for the patch-id-aware short-circuit
+    // on subsequent updateHead detections. Best-effort — if the git
+    // primitives are missing the cached identity stays null and the
+    // short-circuit never fires (existing behavior).
+    const headPatchId = ctx.git.patchIdAgainst
+        ? await ctx.git.patchIdAgainst(base, entry.headSha).catch(() => undefined)
+        : undefined;
+    const specTreeId = ctx.git.treeId
+        ? await ctx.git.treeId(specSha).catch(() => undefined)
+        : undefined;
     ctx.store.transition(entry.id, "validating", {
         baseSha,
         ciRunId: runId,
@@ -177,5 +199,84 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
         specBranch: specName,
         specSha,
         specBasedOn: isHead ? null : prevEntry.id,
+        ...(headPatchId !== undefined ? { headPatchId } : {}),
+        ...(specTreeId !== undefined ? { specTreeId } : {}),
     }, `spec ready, CI ${runId.slice(0, 12)}`);
 }
+async function tryPatchIdEquivalentRebuild(ctx, entry, base, newHead) {
+    // Need the cached identity *and* the git primitives required to
+    // verify the equivalence and rebuild the spec commit. If any
+    // piece is missing, fall back.
+    if (!entry.headPatchId || !entry.specTreeId || !entry.specBranch || !entry.specSha) {
+        return false;
+    }
+    const git = ctx.git;
+    if (!git.patchIdAgainst || !git.integrationTreeId || !git.commitTree || !git.pushCommit) {
+        return false;
+    }
+    let newPatchId;
+    let newTreeId;
+    let baseSha;
+    try {
+        [newPatchId, newTreeId, baseSha] = await Promise.all([
+            git.patchIdAgainst(base, newHead),
+            git.integrationTreeId(base, newHead),
+            git.headSha(base),
+        ]);
+    }
+    catch {
+        return false;
+    }
+    if (!newPatchId || !newTreeId || !baseSha)
+        return false;
+    if (newPatchId !== entry.headPatchId)
+        return false;
+    if (newTreeId !== entry.specTreeId)
+        return false;
+    // Tree-equivalent. Rebuild spec commit with the new head as the
+    // second parent so post-merge PR detection still works.
+    const branchSuffix = entry.branch.replace(/^.*\//, "").replace(/-/g, " ");
+    const message = `Merge PR #${entry.prNumber}: ${branchSuffix} (rebased)`;
+    let newSpecSha;
+    try {
+        newSpecSha = await git.commitTree(entry.specTreeId, [baseSha, newHead], message);
+    }
+    catch {
+        return false;
+    }
+    if (!newSpecSha)
+        return false;
+    try {
+        await git.pushCommit(newSpecSha, entry.specBranch);
+    }
+    catch {
+        return false;
+    }
+    emit(ctx, entry, "spec_build_succeeded", {
+        specBranch: entry.specBranch,
+        detail: "patch-id-equivalent rebuild",
+    });
+    // Plan §5.2: re-announce spec availability on the new head.
+    if (ctx.eviction.reportSpecReady) {
+        await ctx.eviction.reportSpecReady(entry, entry.specBranch, newSpecSha).catch(() => undefined);
+    }
+    let runId = null;
+    try {
+        runId = await ctx.ci.triggerRun(entry.specBranch, newSpecSha);
+        emit(ctx, entry, "ci_triggered", { ciRunId: runId, specBranch: entry.specBranch });
+    }
+    catch {
+        runId = null;
+    }
+    ctx.store.rebuildSpecHeadEquivalent(entry.id, {
+        headSha: newHead,
+        specSha: newSpecSha,
+        specBranch: entry.specBranch,
+        headPatchId: newPatchId,
+        specTreeId: newTreeId,
+        ciRunId: runId,
+    }, runId
+        ? `patch-id-equivalent rebuild, CI ${runId.slice(0, 12)}`
+        : "patch-id-equivalent rebuild (CI trigger pending)");
+    return true;
+}

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

@@ -63,7 +63,10 @@ export class MergeStewardQueueCommands {
             postMergeSha: null,
             postMergeSummary: null,
             postMergeCheckedAt: null,
+            headPatchId: null,
+            specTreeId: null,
             prTitle: params.prTitle ?? null,
+            baseRefName: params.baseRefName ?? null,
             enqueuedAt: new Date().toISOString(),
             updatedAt: new Date().toISOString(),
         };
@@ -183,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;
         }
@@ -277,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/store.d.ts

@@ -11,9 +11,27 @@ export interface QueueStore {
     listActive(repoId: string): QueueEntry[];
     listAll(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">>, detail?: string): 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;
     updateHead(entryId: string, newHeadSha: string): void;
+    /**
+     * Plan §5.3: patch-id-aware short-circuit. The new head is
+     * patch-id-equivalent to the cached identity AND the freshly
+     * computed merge tree matches the cached spec tree. We rebuild the
+     * spec commit with the new head as its second parent (so GitHub
+     * marks the PR merged after fast-forward) but do not blow away the
+     * spec branch or restart the prepare cycle. CI must re-run on the
+     * new spec SHA — check_runs are SHA-anchored and there is no API
+     * to reuse a passing verdict.
+     */
+    rebuildSpecHeadEquivalent(entryId: string, patch: {
+        headSha: string;
+        specSha: string;
+        specBranch: string;
+        headPatchId: string;
+        specTreeId: string;
+        ciRunId: string | null;
+    }, detail?: string): void;
     updatePriority(entryId: string, priority: number, detail?: string): void;
     insertIncident(incident: IncidentRecord): void;
     listIncidents(entryId: string): IncidentRecord[];

package/dist/types.d.ts

@@ -50,6 +50,28 @@ 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
+     * build time so the prepare path can short-circuit on
+     * patch-id-equivalent updateHeads without re-running the merge.
+     * Null until the spec is first built.
+     */
+    headPatchId: string | null;
+    /**
+     * Plan §5.3: tree id of `specSha` (i.e. `git rev-parse specSha^{tree}`).
+     * Cached at spec build time so we can compare against a freshly
+     * computed `merge-tree --write-tree` for the new head and decide
+     * whether the merged tree is unchanged.
+     */
+    specTreeId: string | null;
     enqueuedAt: string;
     updatedAt: string;
 }
@@ -183,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;

package/package.json

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