merge-steward 0.32.6 → 0.33.0

package/README.md

@@ -8,18 +8,22 @@ For the background story and design trade-offs, read [merge-steward: speculative
 
 ## Why this matters
 
-The queue keeps delivery fast without pretending branch CI is enough. Each speculative branch is the cumulative queue order on top of the latest base: `main + A`, then `main + A + B`, then `main + A + B + C`. No more "CI was green yesterday, breaks on merge today" — the integration bug is caught before `main` ever sees it.
+The queue keeps delivery fast without pretending branch CI is always enough. For each dependency-ready PR it resolves one immutable candidate: the exact PR head when it already contains the prospective base, or an integration commit when it does not. Downstream candidates are cumulative: `main + A`, then `main + A + B`, then `main + A + B + C`.
 
 ## How it works
 
 1. A PR becomes eligible when GitHub says it is approved and its required checks are green.
 2. The steward notices through webhook wakeups or startup reconcile scans, and admits the PR to the queue.
-3. It builds a speculative branch — `main + PR` at the head, cumulative downstream (`main + A + B`, `main + A + B + C`).
-4. CI runs on that speculative SHA.
-5. Once the speculative SHA's checks are green and it is still a fast-forward from current `main`, the steward pushes that SHA to `main` immediately. It does **not** wait for `main`'s own CI to settle, and **never** pauses the queue because `main` is red — the green speculative SHA *is* the next `main`.
+3. It resolves the exact future-`main` candidate. If the prospective base is an ancestor of the PR head, the candidate is that already-tested head SHA. Otherwise it builds a cumulative integration commit.
+4. It validates checks on that exact SHA. Only newly-created integration candidates trigger synthetic CI.
+5. Immediately before landing, it refreshes policy, approval, head, checks, and ancestry, then non-force pushes the same immutable SHA to `main`. It never substitutes a mutable branch ref.
 6. On CI failure: retry (gated on base SHA change), then evict with a durable incident record and GitHub check run.
 7. PatchRelay, the `ship-pr` skill, or any agent sees the check run failure and fixes the branch; when CI passes again the PR can be re-admitted.
 
+This is structural, not an optional fast path. An exact head is safe precisely
+when it already contains the prospective base; if it does not, Merge Steward
+creates and tests the integration candidate. Checks never move between SHAs.
+
 ## Use with your own agent
 
 For an agent that drives PRs through the queue and reacts to evictions / failing checks without running PatchRelay's full harness, install the [`ship-pr`](https://github.com/krasnoperov/patchrelay-agents) skill from the companion Claude Code marketplace:
@@ -78,11 +82,12 @@ The real gate is:
 
 - GitHub says the PR review state is approved
 - configured required checks are green
-- the steward's speculative integrated branch also passes CI
+- the exact landing candidate is green under the current check policy
+- current `main` is an ancestor of that same immutable candidate SHA
 
-`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.
+`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 candidate 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.
+**`main`'s own CI is information-only.** The candidate SHA the steward validates is exactly what becomes `main`, so re-testing it after the push adds no eligibility signal. Use `main` CI as a project-health canary, not a queue control.
 
 ## Interaction with PatchRelay
 

package/dist/check-policy.d.ts

@@ -0,0 +1,11 @@
+import type { CheckResult, RequiredCheck } from "./types.ts";
+export interface CheckPolicyEvaluation {
+    status: "pass" | "pending" | "fail";
+    missing: RequiredCheck[];
+    failing: CheckResult[];
+    pending: CheckResult[];
+}
+export declare function mapGitHubCheckConclusion(status: string | undefined, conclusion: string | null): CheckResult["conclusion"];
+/** Evaluate the exact check runs against the current GitHub policy identity. */
+export declare function evaluateCheckPolicy(requiredChecks: RequiredCheck[], requireAllChecksOnEmptyRequiredSet: boolean, checks: CheckResult[]): CheckPolicyEvaluation;
+export declare function formatRequiredCheck(check: RequiredCheck): string;

package/dist/check-policy.js

@@ -0,0 +1,88 @@
+function normalizeName(name) {
+    return name.trim().toLowerCase();
+}
+function matchesRule(check, rule) {
+    return normalizeName(check.name) === normalizeName(rule.name)
+        && (rule.appId === null || check.appId === rule.appId);
+}
+function selectLatestRerun(checks) {
+    if (checks.length <= 1)
+        return checks;
+    if (checks.some((check) => check.runId === undefined))
+        return checks;
+    const ids = checks.map((check) => check.runId);
+    if (new Set(ids).size !== ids.length)
+        return checks;
+    return [checks.reduce((latest, check) => check.runId > latest.runId ? check : latest)];
+}
+function coalesceReruns(checks) {
+    const groups = new Map();
+    for (const check of checks) {
+        const key = `${normalizeName(check.name)}\0${check.appId ?? "any"}`;
+        const group = groups.get(key) ?? [];
+        group.push(check);
+        groups.set(key, group);
+    }
+    return [...groups.values()].flatMap(selectLatestRerun);
+}
+export function mapGitHubCheckConclusion(status, conclusion) {
+    if (status !== "completed" || conclusion === null)
+        return "pending";
+    switch (conclusion) {
+        case "success": return "success";
+        case "neutral": return "neutral";
+        case "skipped": return "skipped";
+        case "failure":
+        case "cancelled":
+        case "timed_out":
+        case "stale":
+        case "action_required":
+            return "failure";
+        default:
+            return "pending";
+    }
+}
+/** Evaluate the exact check runs against the current GitHub policy identity. */
+export function evaluateCheckPolicy(requiredChecks, requireAllChecksOnEmptyRequiredSet, checks) {
+    if (requiredChecks.length > 0) {
+        const missing = [];
+        const failing = [];
+        const pending = [];
+        for (const required of requiredChecks) {
+            const matching = selectLatestRerun(checks.filter((check) => matchesRule(check, required)));
+            if (matching.length === 0) {
+                missing.push(required);
+                continue;
+            }
+            // A named required job that was skipped did not validate this
+            // candidate. Neutral is explicitly accepted by GitHub.
+            failing.push(...matching.filter((check) => check.conclusion === "failure" || check.conclusion === "skipped"));
+            pending.push(...matching.filter((check) => check.conclusion === "pending"));
+        }
+        return {
+            status: failing.length > 0 ? "fail" : missing.length > 0 || pending.length > 0 ? "pending" : "pass",
+            missing,
+            failing,
+            pending,
+        };
+    }
+    if (checks.length === 0) {
+        return { status: "pending", missing: [], failing: [], pending: [] };
+    }
+    // With no named required set, skipped conditional jobs are non-applicable.
+    const currentChecks = coalesceReruns(checks);
+    const failing = currentChecks.filter((check) => check.conclusion === "failure");
+    const pending = currentChecks.filter((check) => check.conclusion === "pending");
+    if (requireAllChecksOnEmptyRequiredSet || requiredChecks.length === 0) {
+        return {
+            status: failing.length > 0 ? "fail" : pending.length > 0 ? "pending" : "pass",
+            missing: [],
+            failing,
+            pending,
+        };
+    }
+    return { status: "pass", missing: [], failing: [], pending: [] };
+}
+export function formatRequiredCheck(check) {
+    return check.appId === null ? check.name : `${check.name} (app ${check.appId})`;
+}

package/dist/config.d.ts

@@ -34,8 +34,6 @@ export declare const stewardConfigSchema: z.ZodObject<{
     queueMergingLabel: z.ZodDefault<z.ZodString>;
     mergeQueueCheckName: z.ZodDefault<z.ZodString>;
     evictionCheckName: z.ZodDefault<z.ZodString>;
-    specReadyCheckName: z.ZodDefault<z.ZodString>;
-    specBranchPrefix: z.ZodDefault<z.ZodString>;
     excludeBranches: z.ZodDefault<z.ZodArray<z.ZodString>>;
     autoResolvePatterns: z.ZodDefault<z.ZodArray<z.ZodObject<{
         glob: z.ZodString;

package/dist/config.js

@@ -34,25 +34,14 @@ export const stewardConfigSchema = z.object({
     // 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.
+    // candidate checks validating; `queue:merging` = head, landing 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
-    // `evictionCheckName` (today: same as mergeQueueCheckName, kept for
-    // contract clarity) and `specReadyCheckName`; consumers read them.
     /** Eviction check run name. Synonym for mergeQueueCheckName, surfaced
      * under the bus-contract name so consumer code can be naming-aligned
      * with patchrelay's resolver. */
     evictionCheckName: z.string().default(DEFAULT_MERGE_QUEUE_CHECK_NAME),
-    /** Spec-ready check run name (default: "merge-steward/spec-ready").
-     * Read by review-quill in integration_tree mode (plan §3.5). */
-    specReadyCheckName: z.string().default("merge-steward/spec-ready"),
-    /** Prefix for spec branch names (default: "mq-spec-"); matches the
-     * existing SPEC_BRANCH_PREFIX in reconciler-core.ts. The pattern
-     * review-quill matches against is `${prefix}*`. */
-    specBranchPrefix: z.string().default("mq-spec-"),
     /** Branch name patterns to exclude from admission (glob-style). */
     excludeBranches: z.array(z.string()).default([]),
     /**

package/dist/db/schema.d.ts

@@ -1,6 +1,7 @@
 import type { DatabaseConnection } from "./shared.ts";
 /**
- * Create the steward's SQLite schema. Idempotent — safe to call on every startup.
- * No migration path: this is the final shape. There are no legacy installations.
+ * Create and upgrade the steward's SQLite schema. Idempotent — safe to call
+ * on every startup. Migrations preserve active queue state, then remove
+ * obsolete columns so the runtime has one candidate model.
  */
 export declare function ensureSchema(connection: DatabaseConnection): void;

package/dist/db/schema.js

@@ -1,6 +1,7 @@
 /**
- * Create the steward's SQLite schema. Idempotent — safe to call on every startup.
- * No migration path: this is the final shape. There are no legacy installations.
+ * Create and upgrade the steward's SQLite schema. Idempotent — safe to call
+ * on every startup. Migrations preserve active queue state, then remove
+ * obsolete columns so the runtime has one candidate model.
  */
 export function ensureSchema(connection) {
     connection.exec(`
@@ -21,9 +22,11 @@ export function ensureSchema(connection) {
       max_retries INTEGER NOT NULL DEFAULT 3,
       last_failed_base_sha TEXT,
       issue_key TEXT,
-      spec_branch TEXT,
-      spec_sha TEXT,
-      spec_based_on TEXT,
+      candidate_kind TEXT,
+      candidate_policy_fingerprint TEXT,
+      candidate_ref TEXT,
+      candidate_sha TEXT,
+      candidate_based_on TEXT,
       wait_detail TEXT,
       post_merge_status TEXT,
       post_merge_sha TEXT,
@@ -77,12 +80,25 @@ 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", "candidate_kind", "TEXT");
+    ensureColumn(connection, "queue_entries", "candidate_policy_fingerprint", "TEXT");
+    ensureColumn(connection, "queue_entries", "candidate_ref", "TEXT");
+    ensureColumn(connection, "queue_entries", "candidate_sha", "TEXT");
+    ensureColumn(connection, "queue_entries", "candidate_based_on", "TEXT");
     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");
     ensureColumn(connection, "queue_entries", "decided_at", "TEXT");
+    migrateLegacyCandidateColumns(connection);
+    // Retire patch-equivalence caches from older installations. Candidate
+    // validity is SHA-bound; preserving these columns would imply otherwise.
+    dropColumnIfPresent(connection, "queue_entries", "head_patch_id");
+    dropColumnIfPresent(connection, "queue_entries", "spec_tree_id");
+    connection.exec(`
+    UPDATE queue_entries
+       SET candidate_kind = 'integration'
+     WHERE candidate_kind IS NULL
+       AND candidate_sha IS NOT NULL
+       AND candidate_ref IS NOT NULL
+  `);
     connection.exec(`
     UPDATE queue_entries
        SET post_merge_status = 'pending'
@@ -104,6 +120,37 @@ export function ensureSchema(connection) {
       WHERE status NOT IN ('merged', 'evicted', 'dequeued')
   `);
 }
+function migrateLegacyCandidateColumns(connection) {
+    const legacyColumns = [
+        ["spec_branch", "candidate_ref"],
+        ["spec_sha", "candidate_sha"],
+        ["spec_based_on", "candidate_based_on"],
+    ];
+    for (const [legacy, candidate] of legacyColumns) {
+        if (!hasColumn(connection, "queue_entries", legacy))
+            continue;
+        connection.exec(`
+      UPDATE queue_entries
+         SET ${candidate} = ${legacy}
+       WHERE ${candidate} IS NULL
+         AND ${legacy} IS NOT NULL
+    `);
+    }
+    // Derive kind while the legacy ref is still available, then remove all
+    // old candidate representations in this same startup migration.
+    connection.exec(`
+    UPDATE queue_entries
+       SET candidate_kind = CASE
+         WHEN candidate_sha = head_sha AND candidate_ref IS NULL THEN 'head'
+         WHEN candidate_sha IS NOT NULL THEN 'integration'
+         ELSE NULL
+       END
+     WHERE candidate_kind IS NULL
+  `);
+    for (const [legacy] of legacyColumns) {
+        dropColumnIfPresent(connection, "queue_entries", legacy);
+    }
+}
 function hasColumn(connection, table, column) {
     const rows = connection.prepare(`PRAGMA table_info(${table})`).all();
     for (const row of rows) {
@@ -119,3 +166,9 @@ function ensureColumn(connection, table, column, type) {
     }
     connection.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
 }
+function dropColumnIfPresent(connection, table, column) {
+    if (!hasColumn(connection, table, column)) {
+        return;
+    }
+    connection.exec(`ALTER TABLE ${table} DROP COLUMN ${column}`);
+}

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

@@ -12,18 +12,12 @@ export declare class SqliteStore implements QueueStore {
     listActive(repoId: string): QueueEntry[];
     listAll(repoId: string): QueueEntry[];
     listPostMergePending(repoId: string): QueueEntry[];
+    listRecentTerminal(repoId: string, limit?: number): 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" | "headPatchId" | "specTreeId">>, detail?: string): void;
+    transition(entryId: string, to: QueueEntryStatus, patch?: Partial<Pick<QueueEntry, "headSha" | "baseSha" | "ciRunId" | "ciRetries" | "retryAttempts" | "lastFailedBaseSha" | "candidateRef" | "candidateSha" | "candidateBasedOn" | "waitDetail" | "candidateKind" | "candidatePolicyFingerprint" | "postMergeStatus" | "postMergeSha" | "postMergeSummary" | "postMergeCheckedAt">>, 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;
+    updateBaseRef(entryId: string, baseRefName: 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

@@ -1,6 +1,7 @@
 import { TERMINAL_STATUSES } from "../types.js";
 import { SqliteConnection, isoNow } from "./shared.js";
 import { ensureSchema } from "./schema.js";
+import { orderActiveQueue } from "../queue-order.js";
 function mapEntry(row) {
     return {
         id: String(row.id),
@@ -19,9 +20,15 @@ function mapEntry(row) {
         maxRetries: Number(row.max_retries),
         lastFailedBaseSha: row.last_failed_base_sha === null ? null : String(row.last_failed_base_sha),
         issueKey: row.issue_key === null ? null : String(row.issue_key),
-        specBranch: row.spec_branch === null || row.spec_branch === undefined ? null : String(row.spec_branch),
-        specSha: row.spec_sha === null || row.spec_sha === undefined ? null : String(row.spec_sha),
-        specBasedOn: row.spec_based_on === null || row.spec_based_on === undefined ? null : String(row.spec_based_on),
+        candidateKind: row.candidate_kind === null || row.candidate_kind === undefined
+            ? null
+            : String(row.candidate_kind),
+        candidatePolicyFingerprint: row.candidate_policy_fingerprint === null || row.candidate_policy_fingerprint === undefined
+            ? null
+            : String(row.candidate_policy_fingerprint),
+        candidateRef: row.candidate_ref === null || row.candidate_ref === undefined ? null : String(row.candidate_ref),
+        candidateSha: row.candidate_sha === null || row.candidate_sha === undefined ? null : String(row.candidate_sha),
+        candidateBasedOn: row.candidate_based_on === null || row.candidate_based_on === undefined ? null : String(row.candidate_based_on),
         waitDetail: row.wait_detail === null || row.wait_detail === undefined ? null : String(row.wait_detail),
         postMergeStatus: row.post_merge_status === null || row.post_merge_status === undefined
             ? null
@@ -31,8 +38,6 @@ function mapEntry(row) {
         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),
         decidedAt: row.decided_at === null || row.decided_at === undefined ? null : String(row.decided_at),
         enqueuedAt: String(row.enqueued_at),
         updatedAt: String(row.updated_at),
@@ -97,10 +102,7 @@ export class SqliteStore {
         }
     }
     getHead(repoId) {
-        const row = this.conn.prepare(`SELECT * FROM queue_entries
-       WHERE repo_id = ? AND status NOT IN (${NOT_TERMINAL_SQL})
-       ORDER BY priority DESC, position ASC LIMIT 1`).get(repoId, ...TERMINAL_STATUSES);
-        return row ? mapEntry(row) : undefined;
+        return this.listActive(repoId)[0];
     }
     getEntry(entryId) {
         const row = this.conn.prepare("SELECT * FROM queue_entries WHERE id = ?").get(entryId);
@@ -116,8 +118,8 @@ export class SqliteStore {
     listActive(repoId) {
         const rows = this.conn.prepare(`SELECT * FROM queue_entries
        WHERE repo_id = ? AND status NOT IN (${NOT_TERMINAL_SQL})
-       ORDER BY priority DESC, position ASC`).all(repoId, ...TERMINAL_STATUSES);
-        return rows.map(mapEntry);
+       ORDER BY position ASC`).all(repoId, ...TERMINAL_STATUSES);
+        return orderActiveQueue(rows.map(mapEntry));
     }
     listAll(repoId) {
         const rows = this.conn.prepare("SELECT * FROM queue_entries WHERE repo_id = ? ORDER BY priority DESC, position ASC").all(repoId);
@@ -130,16 +132,25 @@ export class SqliteStore {
        ORDER BY position ASC`).all(repoId);
         return rows.map(mapEntry);
     }
+    listRecentTerminal(repoId, limit = 3) {
+        const rows = this.conn.prepare(`SELECT * FROM queue_entries
+       WHERE repo_id = ? AND status IN (${TERMINAL_STATUSES.map(() => "?").join(", ")})
+       ORDER BY COALESCE(decided_at, updated_at) DESC
+       LIMIT ?`).all(repoId, ...TERMINAL_STATUSES, limit);
+        return rows.map(mapEntry);
+    }
     insert(entry) {
         this.conn.transaction(() => {
             this.conn.prepare(`INSERT INTO queue_entries
          (id, repo_id, pr_number, branch, head_sha, base_sha, status, position,
           priority, generation, ci_run_id, ci_retries, retry_attempts,
-          max_retries, last_failed_base_sha, issue_key, wait_detail,
+          max_retries, last_failed_base_sha, issue_key,
+          candidate_kind, candidate_policy_fingerprint,
+          candidate_ref, candidate_sha, candidate_based_on, wait_detail,
           post_merge_status, post_merge_sha, post_merge_summary, post_merge_checked_at,
           pr_title, base_ref_name, decided_at,
           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.baseRefName ?? null, entry.decidedAt ?? 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.candidateKind ?? null, entry.candidatePolicyFingerprint ?? null, entry.candidateRef ?? null, entry.candidateSha ?? null, entry.candidateBasedOn ?? null, entry.waitDetail ?? null, entry.postMergeStatus ?? null, entry.postMergeSha ?? null, entry.postMergeSummary ?? null, entry.postMergeCheckedAt ?? null, entry.prTitle ?? null, entry.baseRefName ?? null, entry.decidedAt ?? null, entry.enqueuedAt, entry.updatedAt);
             this.writeEvent(entry.id, null, entry.status);
         })();
     }
@@ -182,17 +193,25 @@ export class SqliteStore {
                 sets.push("last_failed_base_sha = ?");
                 values.push(patch.lastFailedBaseSha);
             }
-            if (patch?.specBranch !== undefined) {
-                sets.push("spec_branch = ?");
-                values.push(patch.specBranch);
+            if (patch?.candidateKind !== undefined) {
+                sets.push("candidate_kind = ?");
+                values.push(patch.candidateKind);
+            }
+            if (patch?.candidatePolicyFingerprint !== undefined) {
+                sets.push("candidate_policy_fingerprint = ?");
+                values.push(patch.candidatePolicyFingerprint);
             }
-            if (patch?.specSha !== undefined) {
-                sets.push("spec_sha = ?");
-                values.push(patch.specSha);
+            if (patch?.candidateRef !== undefined) {
+                sets.push("candidate_ref = ?");
+                values.push(patch.candidateRef);
             }
-            if (patch?.specBasedOn !== undefined) {
-                sets.push("spec_based_on = ?");
-                values.push(patch.specBasedOn);
+            if (patch?.candidateSha !== undefined) {
+                sets.push("candidate_sha = ?");
+                values.push(patch.candidateSha);
+            }
+            if (patch?.candidateBasedOn !== undefined) {
+                sets.push("candidate_based_on = ?");
+                values.push(patch.candidateBasedOn);
             }
             if (patch?.waitDetail !== undefined) {
                 sets.push("wait_detail = ?");
@@ -217,14 +236,6 @@ 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);
         })();
@@ -245,35 +256,35 @@ export class SqliteStore {
           head_sha = ?, status = 'queued', generation = ?,
           ci_run_id = NULL, ci_retries = 0, retry_attempts = 0,
           last_failed_base_sha = NULL,
-          spec_branch = NULL, spec_sha = NULL, spec_based_on = NULL,
+          candidate_kind = NULL, candidate_policy_fingerprint = NULL,
+          candidate_ref = NULL, candidate_sha = NULL, candidate_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) {
+    updateBaseRef(entryId, baseRefName, detail) {
         this.conn.transaction(() => {
-            const current = this.conn.prepare("SELECT status, generation FROM queue_entries WHERE id = ?").get(entryId);
+            const current = this.conn.prepare("SELECT status, base_ref_name 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;
+            const currentBaseRef = current.base_ref_name === null ? null : String(current.base_ref_name);
+            if (currentBaseRef === baseRefName)
+                return;
             this.conn.prepare(`UPDATE queue_entries SET
-          head_sha = ?, status = 'validating', generation = ?,
-          ci_run_id = ?, ci_retries = 0, retry_attempts = 0,
+          base_ref_name = ?, status = 'queued',
+          ci_run_id = NULL, 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}`);
+          candidate_kind = NULL, candidate_policy_fingerprint = NULL,
+          candidate_ref = NULL, candidate_sha = NULL, candidate_based_on = NULL,
+          wait_detail = NULL, updated_at = ?
+         WHERE id = ?`).run(baseRefName, isoNow(), entryId);
+            this.writeEvent(entryId, from, "queued", detail ?? `base ref changed to ${baseRefName ?? "(default)"}`);
         })();
     }
     updatePriority(entryId, priority, detail) {

package/dist/github/actions-runner.d.ts

@@ -1,5 +1,5 @@
 import type { CIRunner } from "../interfaces.ts";
-import type { CIStatus } from "../types.ts";
+import type { CIStatus, RequiredCheck } from "../types.ts";
 /**
  * CI runner that polls GitHub Actions via the gh CLI.
  * triggerRun is a no-op — force-pushing the branch triggers CI automatically.
@@ -9,9 +9,13 @@ import type { CIStatus } from "../types.ts";
 export declare class GitHubActionsRunner implements CIRunner {
     private readonly repoFullName;
     private readonly getRequiredChecks;
-    constructor(repoFullName: string, getRequiredChecks?: () => string[], _shouldRequireAllChecksOnEmptyRequiredSet?: () => boolean);
+    private readonly shouldRequireAllChecksOnEmptyRequiredSet;
+    constructor(repoFullName: string, getRequiredChecks?: () => Array<string | RequiredCheck>, shouldRequireAllChecksOnEmptyRequiredSet?: () => boolean);
     triggerRun(_branch: string, sha: string): Promise<string>;
+    rerunRun(_runId: string, _branch: string, sha: string): Promise<string>;
     getStatus(runId: string): Promise<CIStatus>;
+    private listCheckRuns;
+    private evaluate;
     cancelRun(_runId: string): Promise<void>;
     getMainStatus(baseBranch: string): Promise<CIStatus>;
 }