@bridge_gpt/mcp-server 0.2.16 → 0.2.18

package/build/conductor/epic-state.js

@@ -9,10 +9,20 @@
  *
  * Status mapping (BAPI-436 — merge-gated dependent dispatch):
  *   gate.met      → ready_for_review  (implementation done; awaiting merge)
- *   run.stopped   → ready_for_review  (worker session ended; awaiting merge)
+ *   run.stopped   → ready_for_review  (PR-BOUND / session-terminal fold — see below)
  *   merge.succeeded → done            (merged; dependents may now dispatch)
  *   ci.failed     → blocked           (unchanged)
+ *
+ * BAPI-507 (N-1): `run.stopped → ready_for_review` is a PR-BOUND fold, not a
+ * generic turn-boundary fold. Claude Code's `Stop`/`SubagentStop` hooks fire on
+ * every assistant turn / subagent completion — long before a branch is pushed or
+ * a PR opened — so an implementation-run `run.stopped` only folds a ticket to
+ * `ready_for_review` when that ticket already has a PR binding in the same event
+ * batch (`git.pr_opened` / `gate.met` / `merge.succeeded`). Without a binding the
+ * ticket keeps its prior non-review status, matching the done-gate's own
+ * PR-binding requirement.
  */
+import { getHeadSha } from "./event-accessors.js";
 // ---------------------------------------------------------------------------
 // Status sets (module-private)
 // ---------------------------------------------------------------------------
@@ -43,6 +53,8 @@ const TERMINAL_SIGNAL_TYPES = new Set([
     "ci.failed",
     "run.stopped",
     "review.changes_requested",
+    // BAPI-494: an un-mergeable PR folds to `blocked`, head-scoped to the conflict head.
+    "merge.conflict",
     // BAPI-445: pre-implementation spec re-review verdicts, scoped to review runs.
     "spec_review.passed",
     "spec_review.changes_requested",
@@ -50,6 +62,14 @@ const TERMINAL_SIGNAL_TYPES = new Set([
 function isNonTerminal(status) {
     return NON_TERMINAL_STATUSES.has(status);
 }
+const HEAD_SCOPED_BLOCKING_SIGNALS = new Set([
+    "ci.failed",
+    "review.changes_requested",
+    "merge.conflict",
+]);
+function isHeadScopedBlockingSignal(type) {
+    return HEAD_SCOPED_BLOCKING_SIGNALS.has(type);
+}
 /**
  * Map a terminal ledger signal to the next ticket status.
  *
@@ -76,6 +96,8 @@ export function signalToNextStatus(signalType, isReviewRun = false) {
         return "blocked";
     if (signalType === "review.changes_requested")
         return "blocked";
+    if (signalType === "merge.conflict")
+        return "blocked"; // BAPI-494
     if (signalType === "merge.succeeded")
         return "done";
     return "ready_for_review"; // gate.met and (implementation) run.stopped: awaiting merge
@@ -91,6 +113,13 @@ export function signalToNextStatus(signalType, isReviewRun = false) {
  *   2. Whose full `depends_on` list is satisfied (all deps have "done" status).
  *
  * Never calls an LLM or performs I/O. Goal 8 invariant.
+ *
+ * Planner file-overlap serialization (BAPI-495) is encoded upstream as
+ * explicit `depends_on` entries in the stored plan DAG (see
+ * `apply_file_overlap_serialization` in `api/library/db/epic_runs.py`) —
+ * sibling tickets with overlapping predicted touched files are serialized
+ * before this function ever sees the plan. This function deliberately takes
+ * no file-prediction input and adds no overlap-guard logic of its own.
  */
 export function computeReadySet(plan, ticketStatuses) {
     const ready = [];
@@ -152,8 +181,226 @@ export function extractWorkerLiveness(events, runId, nowMs, windowSeconds) {
     return { alive: age <= windowSeconds * 1000, workerId: latest.worker_id ?? null };
 }
 // ---------------------------------------------------------------------------
+// Head-scoped blocking (BAPI-487)
+// ---------------------------------------------------------------------------
+// BAPI-493: PR head SHA extraction now lives in the typed accessor layer
+// (`event-accessors.getHeadSha`), which reads ONLY the canonical head path under a
+// ledger event's details and fails closed exactly as the retired local
+// `extractEventHeadSha` did (trimmed 7–40 char hex, lowercased). Every head read in
+// this module goes through `getHeadSha(event)` — there is no hand-rolled details
+// head cast in this file anymore.
+/**
+ * Event types that carry an observable implementation-PR head SHA for a ticket
+ * (BAPI-487). Used to compute the latest observed head per ticket so a blocking
+ * signal emitted for a superseded head can be detected and cleared. Includes the
+ * blocking types (`ci.failed`/`review.changes_requested`) as head observations,
+ * but staleness is anchored on a `gate.met` for a DIFFERENT head so a delayed
+ * old-head rejection cannot masquerade as the current head. `review.passed` /
+ * `ci.passed` are head observations only and are deliberately NOT added to
+ * {@link TERMINAL_SIGNAL_TYPES} — they never fold a ticket status.
+ *
+ * BAPI-493: the literal list is statically constrained with
+ * `satisfies readonly HeadBearingSemanticEventType[]` so it can never drift from
+ * the payload model's head-bearing set — every member here declares `head_sha` in
+ * its `EventDetailsByType` payload, so replacing the ad-hoc head reader with the
+ * typed `getHeadSha` accessor cannot silently break BAPI-487 stale-block clearing.
+ */
+const HEAD_OBSERVATION_TYPE_LIST = [
+    "git.pr_opened",
+    "ci.passed",
+    "ci.failed",
+    "review.passed",
+    "review.changes_requested",
+    "gate.met",
+    "merge.succeeded",
+    // BAPI-494: merge.conflict carries a details head SHA, so it is a head
+    // observation (its head can supersede a stale block and be superseded by a rebase).
+    "merge.conflict",
+];
+const HEAD_OBSERVATION_TYPES = new Set(HEAD_OBSERVATION_TYPE_LIST);
+/**
+ * Classify a terminal signal's head scope (BAPI-493). Uses `getHeadSha(event)` as
+ * the only head source. Centralizes the stale/current/clear-gate head comparisons
+ * the old ad-hoc `staleBlockedTickets`/`staleClearHead` checks performed inline.
+ */
+export function classifyTerminalHeadScope(ctx) {
+    const { signalType, eventHeadSha, ticketKey, staleBlockedTickets, staleClearHead } = ctx;
+    // BAPI-494: merge.conflict joins ci.failed/review.changes_requested as a head-scoped
+    // blocking signal — same stale-on-superseded-head classification.
+    if (isHeadScopedBlockingSignal(signalType)) {
+        if (eventHeadSha !== null && staleBlockedTickets.has(ticketKey)) {
+            const clearHead = staleClearHead(ticketKey);
+            if (clearHead !== null && clearHead !== eventHeadSha)
+                return "stale_blocking_signal";
+        }
+        return "current_or_unproven";
+    }
+    if (signalType === "gate.met") {
+        if (eventHeadSha !== null && staleBlockedTickets.has(ticketKey)) {
+            const clearHead = staleClearHead(ticketKey);
+            if (clearHead !== null && clearHead === eventHeadSha)
+                return "stale_block_clear_gate";
+        }
+        return "current_or_unproven";
+    }
+    return "not_head_scoped";
+}
+/**
+ * Single exhaustive terminal-signal precedence table (BAPI-493), replacing the five
+ * ad-hoc same-tick fold-upgrade booleans that previously lived inline in
+ * `rebuildObservedState` (merge upgrade, spec-review reject, review reject, ci-failed
+ * re-block, and stale-head clear). `satisfies Record<TerminalSignalType, ...>` makes
+ * adding a new terminal signal a compile error until its precedence is defined here.
+ *
+ * `foldExists` is true when the ticket already has a same-tick fold. When false the
+ * signal is the FIRST fold of the tick and selects normally (the earlier
+ * postgres-non-terminal + review-role + stale-skip guards already filtered out the
+ * signals that must not fold at all). When true, only a dominating signal may
+ * replace the existing fold; everything else is explicitly dropped.
+ */
+const TERMINAL_PRECEDENCE = {
+    "gate.met": ({ foldExists, headScope, currentLocalStatus }) => {
+        if (!foldExists)
+            return { action: "select" };
+        // A later gate.met on the ticket's newer (passed) head clears a block that a
+        // superseded old head created earlier in the same batch (BAPI-487).
+        if (headScope === "stale_block_clear_gate" && currentLocalStatus === "blocked") {
+            return { action: "replace", reason: "stale-block-clear gate on the current head" };
+        }
+        return { action: "drop", reason: "gate.met does not override an existing same-tick fold" };
+    },
+    "merge.succeeded": ({ foldExists, currentLocalStatus }) => {
+        if (!foldExists)
+            return { action: "select" };
+        // ready_for_review → done when merge.succeeded arrives after gate.met/run.stopped
+        // in the same batch. Never overrides a same-tick `blocked` fold.
+        if (currentLocalStatus === "ready_for_review") {
+            return { action: "replace", reason: "merge.succeeded upgrades ready_for_review to done" };
+        }
+        return { action: "drop", reason: "merge.succeeded does not override a non-ready_for_review fold" };
+    },
+    "ci.failed": ({ foldExists, headScope, currentLocalStatus }) => {
+        if (headScope === "stale_blocking_signal") {
+            return { action: "drop", reason: "stale ci.failed on a superseded head" };
+        }
+        if (!foldExists)
+            return { action: "select" };
+        // A current/unprovable ci.failed re-blocks a prior gate.met/run.stopped fold so
+        // the current failure is not silently dropped (starving remediation).
+        if (currentLocalStatus !== "blocked") {
+            return { action: "replace", reason: "current-head ci.failed dominates a prior non-blocked fold" };
+        }
+        return { action: "drop", reason: "ticket already blocked this tick" };
+    },
+    "review.changes_requested": ({ foldExists, headScope, currentLocalStatus }) => {
+        if (headScope === "stale_blocking_signal") {
+            return { action: "drop", reason: "stale review.changes_requested on a superseded head" };
+        }
+        if (!foldExists)
+            return { action: "select" };
+        if (currentLocalStatus !== "blocked") {
+            return { action: "replace", reason: "current-head review.changes_requested dominates a prior non-blocked fold" };
+        }
+        return { action: "drop", reason: "ticket already blocked this tick" };
+    },
+    "merge.conflict": ({ foldExists, headScope, currentLocalStatus }) => {
+        // BAPI-494: same head-scoped precedence as ci.failed/review.changes_requested. A
+        // stale conflict on a superseded head is dropped; a current conflict dominates a
+        // prior gate.met/run.stopped fold in the SAME batch (else the conflict is silently
+        // dropped and the ticket strands at ready_for_review).
+        if (headScope === "stale_blocking_signal") {
+            return { action: "drop", reason: "stale merge.conflict on a superseded head" };
+        }
+        if (!foldExists)
+            return { action: "select" };
+        if (currentLocalStatus !== "blocked") {
+            return { action: "replace", reason: "current-head merge.conflict dominates a prior non-blocked fold" };
+        }
+        return { action: "drop", reason: "ticket already blocked this tick" };
+    },
+    "spec_review.changes_requested": ({ foldExists, currentLocalStatus }) => {
+        if (!foldExists)
+            return { action: "select" };
+        // A spec-review rejection dominates plain review completion so a changes-requested
+        // verdict is never lost to event ordering.
+        if (currentLocalStatus !== "blocked") {
+            return { action: "replace", reason: "spec-review rejection dominates a prior non-blocked review fold" };
+        }
+        return { action: "drop", reason: "ticket already blocked this tick" };
+    },
+    "spec_review.passed": ({ foldExists }) => {
+        if (!foldExists)
+            return { action: "select" };
+        return { action: "drop", reason: "spec_review.passed does not override an existing same-tick fold" };
+    },
+    "run.stopped": ({ foldExists }) => {
+        if (!foldExists)
+            return { action: "select" };
+        return { action: "drop", reason: "run.stopped does not override an existing same-tick fold" };
+    },
+};
+/**
+ * Resolve the fold decision for a terminal signal via {@link TERMINAL_PRECEDENCE}.
+ * Every terminal signal is explicitly classified as `select`, `replace`, or `drop`
+ * — there is no implicit fall-through or unclassified terminal.
+ */
+export function resolveTerminalFoldDecision(table, signalType, headScope, foldExists, currentLocalStatus, nextStatus) {
+    const rule = table[signalType];
+    return rule({ headScope, foldExists, currentLocalStatus, nextStatus });
+}
+// ---------------------------------------------------------------------------
 // rebuildObservedState
 // ---------------------------------------------------------------------------
+/**
+ * BAPI-507 (N-1): event types that PROVE an implementation ticket has a bound PR
+ * — the precondition for folding a per-turn `run.stopped` to `ready_for_review`.
+ */
+const PR_BINDING_EVENT_TYPES = new Set([
+    "git.pr_opened",
+    "gate.met",
+    "merge.succeeded",
+]);
+/**
+ * BAPI-507 (N-1): does this event prove a PR binding exists for its ticket? True
+ * only for an implementation-run `git.pr_opened` / `gate.met` / `merge.succeeded`
+ * carrying observable PR/head details (a normalized head SHA, or a `pr_number` in
+ * the event details). Never true for a bare `run.stopped`, which is what this
+ * gate is protecting against.
+ */
+export function eventCarriesPrBinding(event) {
+    if (!PR_BINDING_EVENT_TYPES.has(event.type))
+        return false;
+    if (getHeadSha(event) !== null)
+        return true;
+    // Canonical details location is `event.data.details` (same path getHeadSha
+    // reads), NOT a top-level `event.details` — which ConductorEventFull never has.
+    const details = event.data?.details;
+    if (details && typeof details === "object") {
+        const pr = details.pr_number;
+        if (typeof pr === "number" && Number.isFinite(pr))
+            return true;
+    }
+    return false;
+}
+/**
+ * BAPI-507 (N-1): pre-scan an event batch and return the set of IMPLEMENTATION
+ * ticket keys that have a PR binding somewhere in the batch (order-independent).
+ * Review-run events are excluded so a review dispatch never binds an
+ * implementation ticket. This is what gates the `run.stopped` fold below.
+ */
+export function buildPrBoundTickets(events, runIdToTicketKey) {
+    const bound = new Set();
+    for (const event of events) {
+        if (!eventCarriesPrBinding(event))
+            continue;
+        const runId = typeof event.run_id === "string" ? event.run_id : null;
+        const mapped = runId ? runIdToTicketKey.get(runId) : undefined;
+        if (!mapped || mapped.isReview)
+            continue;
+        bound.add(mapped.ticketKey);
+    }
+    return bound;
+}
 /**
  * Rebuild the merged observed state from the durable Postgres desired state
  * and raw local ledger events. Local sticky terminal signals override
@@ -177,6 +424,10 @@ export function rebuildObservedState(postgresState, events, _now) {
             });
         }
     }
+    // BAPI-507 (N-1): implementation tickets that have a PR binding in this event
+    // batch. Order-independent pre-scan so a `run.stopped` appearing before its
+    // `git.pr_opened` still folds. Gates the run.stopped fold in the loop below.
+    const prBoundTickets = buildPrBoundTickets(events, runIdToTicketKey);
     // Populate base maps from Postgres
     const ticketStatusMap = new Map();
     const ticketRowVersionMap = new Map();
@@ -191,20 +442,145 @@ export function rebuildObservedState(postgresState, events, _now) {
     }
     const unfoldedSignals = [];
     const pendingMergeEvents = [];
+    // BAPI-500: predicted per-ticket row version AFTER a same-pass fold CAS. Only
+    // the first-fold ("select") path records it (tick-start snapshot + 1), keyed by
+    // ticket to preserve the one-CAS-per-ticket invariant. reconcileEpic later
+    // confirms it from the real CAS response (or clears it on conflict/throw), so
+    // the follow-on remediation CAS in the same pass CASes against snapshot+1.
+    const ticketPostFoldRowVersionMap = new Map();
     // Track which tickets already have a folded signal (one override per ticket)
     const foldedTicketKeys = new Set();
-    // Track which tickets already have a gate.met queued for merge this tick, so a
-    // second gate.met for the same ticket never double-enqueues. Distinct from
-    // foldedTicketKeys: a prior run.stopped fold (→ ready_for_review) must NOT
-    // suppress a later gate.met's merge enqueue (both map to ready_for_review;
-    // only gate.met enqueues a merge, and the worker frequently emits run.stopped
-    // BEFORE a post-hoc gate.met). Only a fold to a non-mergeable status (blocked)
-    // suppresses the merge — handled via the effective-status check below.
-    const mergeQueuedTicketKeys = new Set();
+    // BAPI-493 (A2/F6): merge-enqueue dedupe is keyed by `(ticket, head_sha)`, NOT by
+    // ticket alone. A stale-head gate.met can no longer claim the single per-ticket
+    // merge slot and suppress the current-head gate.met — only the LATEST gated head
+    // for a ticket is eligible to enqueue (see the enqueue guard below), and the
+    // composite key prevents the same selected head from being enqueued twice.
+    // Distinct from foldedTicketKeys: a prior run.stopped fold (→ ready_for_review)
+    // must NOT suppress a later gate.met's merge enqueue (both map to
+    // ready_for_review; only gate.met enqueues a merge, and the worker frequently
+    // emits run.stopped BEFORE a post-hoc gate.met). Only a fold to a non-mergeable
+    // status (blocked) suppresses the merge — handled via the effective-status check
+    // below.
+    const mergeQueuedTicketHeadKeys = new Set();
+    /** Deterministic composite merge-queue key: `(ticket, head_sha)`. */
+    const mergeQueueKey = (ticketKey, headSha) => `${ticketKey}${headSha}`;
     // BAPI-441: per-ticket latest blocking reason (ci.failed / review.changes_requested),
     // tracked across the full ledger so an already-blocked ticket still carries a
     // reason for the remediation pass to frame the nudge.
     const ticketBlockedReasons = new Map();
+    // BAPI-487: head-scoped block detection. Pre-scan the full ledger once (before
+    // the fold loop) to find, per IMPLEMENTATION ticket:
+    //   - the latest head-bearing observation (HEAD_OBSERVATION_TYPES),
+    //   - the latest `gate.met` head (the definitive "good, passed" head), and
+    //   - the latest blocking-signal head (ci.failed / review.changes_requested).
+    // A blocking signal on a head that a newer gate.met (or a strictly-later
+    // observation of a different head) has superseded must no longer hold the
+    // ticket `blocked`. Review-role dispatches (pre-implementation spec re-review)
+    // are excluded so their heads never clear an implementation PR block.
+    const latestObservedHeadByTicket = new Map();
+    // BAPI-493 (E-25): the gated-head prescan retains the FULL event reference (not
+    // just { headSha, seq }) so the A2/F6 merge-enqueue below can push the exact
+    // event `processGateMetMerge` needs to extract the full merge identity from.
+    const latestGatedHeadByTicket = new Map();
+    const latestBlockingHeadByTicket = new Map();
+    for (const event of events) {
+        const runId = typeof event.run_id === "string" ? event.run_id : null;
+        const mapped = runId ? runIdToTicketKey.get(runId) : undefined;
+        if (!mapped || mapped.isReview)
+            continue;
+        const headSha = getHeadSha(event);
+        if (!headSha)
+            continue;
+        const ticketKey = mapped.ticketKey;
+        if (HEAD_OBSERVATION_TYPES.has(event.type)) {
+            const prev = latestObservedHeadByTicket.get(ticketKey);
+            if (!prev || event.seq >= prev.seq) {
+                latestObservedHeadByTicket.set(ticketKey, { headSha, seq: event.seq });
+            }
+        }
+        if (event.type === "gate.met") {
+            const prev = latestGatedHeadByTicket.get(ticketKey);
+            if (!prev || event.seq >= prev.seq) {
+                latestGatedHeadByTicket.set(ticketKey, { headSha, seq: event.seq, event });
+            }
+        }
+        if (isHeadScopedBlockingSignal(event.type)) {
+            const prev = latestBlockingHeadByTicket.get(ticketKey);
+            if (!prev || event.seq >= prev.seq) {
+                latestBlockingHeadByTicket.set(ticketKey, {
+                    headSha,
+                    seq: event.seq,
+                    reason: event.type,
+                });
+            }
+        }
+    }
+    // Head_sha of the latest blocking signal per ticket (paired with
+    // ticketBlockedReasons). Absent when the blocking event carried no valid head.
+    const ticketBlockedHeads = new Map();
+    for (const [ticketKey, blocking] of latestBlockingHeadByTicket) {
+        ticketBlockedHeads.set(ticketKey, blocking.headSha);
+    }
+    // A ticket is stale-blocked when its latest blocking head has been superseded
+    // by a CAUSALLY-LATER observation of a DIFFERENT head:
+    //   (a) a gate.met AFTER the blocking event, on a different head, or
+    //   (b) any head observation AFTER the blocking event, on a different head.
+    // Both require `> blocking.seq`: a gate.met/observation that PRECEDES the
+    // blocking event proves nothing about staleness — an old gate.met on head A
+    // followed by a genuinely newer ci.failed on head B (B never gated) must leave
+    // B's failure in force, or the current failure would be silently dropped by the
+    // fold-skip below and the ticket starved of remediation. When staleness cannot
+    // be proven from the ledger (e.g. a delayed old-head rejection whose head was
+    // never observed earlier), the reducer conservatively KEEPS the block; the
+    // live done-gate re-evaluation pass (runConductorDoneGatePass), which resolves
+    // the real current PR head via gh, is the backstop that clears a truly stale
+    // block once the head has provably advanced.
+    const staleBlockedTickets = new Set();
+    for (const [ticketKey, blocking] of latestBlockingHeadByTicket) {
+        const gated = latestGatedHeadByTicket.get(ticketKey);
+        const observed = latestObservedHeadByTicket.get(ticketKey);
+        const gatedSupersedes = gated !== undefined &&
+            gated.seq > blocking.seq &&
+            gated.headSha !== blocking.headSha;
+        const observedSupersedes = observed !== undefined &&
+            observed.seq > blocking.seq &&
+            observed.headSha !== blocking.headSha;
+        if (gatedSupersedes || observedSupersedes) {
+            staleBlockedTickets.add(ticketKey);
+            // If the durable base status is `blocked` on this superseded head, clear it
+            // locally to ready_for_review BEFORE the fold loop so this tick's
+            // remediation/merge logic does not re-act on the stale head.
+            if (ticketStatusMap.get(ticketKey) === "blocked") {
+                ticketStatusMap.set(ticketKey, "ready_for_review");
+            }
+        }
+    }
+    // The head that clears a stale block for a ticket: the passed gate.met head,
+    // falling back to the latest observed head.
+    const staleClearHead = (ticketKey) => latestGatedHeadByTicket.get(ticketKey)?.headSha ??
+        latestObservedHeadByTicket.get(ticketKey)?.headSha ??
+        null;
+    // Remove EVERY pending merge event previously queued for a ticket once a current
+    // (non-stale) blocking signal folds it to `blocked` this tick (BAPI-493). A blocked
+    // ticket must have no pending merge — including the case where the block lands on a
+    // DIFFERENT, non-stale head than the earlier-selected gate.met (e.g. gate on head A
+    // enqueued, then a genuinely newer ci.failed on head B blocks the ticket): the
+    // stale-head gate must not still be merged. Provably-stale blocks are dropped
+    // earlier and never reach here, so this only fires for real blocks. Also drops the
+    // composite dedupe keys so a later current-head gate can re-enqueue.
+    const dropPendingMergesForTicket = (ticketKey) => {
+        for (let i = pendingMergeEvents.length - 1; i >= 0; i--) {
+            const pending = pendingMergeEvents[i];
+            const pendingRunId = typeof pending.run_id === "string" ? pending.run_id : null;
+            const pendingTicket = pendingRunId ? runIdToTicketKey.get(pendingRunId)?.ticketKey : undefined;
+            if (pendingTicket !== ticketKey)
+                continue;
+            const pendingHead = getHeadSha(pending);
+            if (pendingHead)
+                mergeQueuedTicketHeadKeys.delete(mergeQueueKey(ticketKey, pendingHead));
+            pendingMergeEvents.splice(i, 1);
+        }
+    };
     for (const event of events) {
         if (!TERMINAL_SIGNAL_TYPES.has(event.type))
             continue;
@@ -228,12 +604,44 @@ export function rebuildObservedState(postgresState, events, _now) {
             event.type === "spec_review.changes_requested";
         if (isReview && !isSpecVerdict)
             continue;
+        const signalType = event.type;
+        // BAPI-507 (N-1): an implementation-run `run.stopped` only folds a ticket to
+        // `ready_for_review` when a PR binding for that ticket exists in this batch.
+        // Claude Code's Stop/SubagentStop hooks fire on every turn/subagent — long
+        // before a branch is pushed — so an unbound run.stopped must NOT persist the
+        // ticket as ready_for_review. Review-run terminals are already filtered above.
+        if (signalType === "run.stopped" &&
+            !isReview &&
+            !prBoundTickets.has(ticketKey)) {
+            continue;
+        }
+        const nextStatus = signalToNextStatus(signalType, isReview);
+        // BAPI-493: head reads and stale/current/clear-gate classification flow through
+        // the typed accessor + single head-scope classifier — no ad-hoc head casts.
+        const eventHeadSha = getHeadSha(event);
+        const headScope = classifyTerminalHeadScope({
+            ticketKey,
+            signalType,
+            nextStatus,
+            currentLocalStatus: ticketStatusMap.get(ticketKey),
+            eventHeadSha,
+            staleBlockedTickets,
+            staleClearHead,
+        });
+        // BAPI-487: a PROVABLY-stale blocking signal (ci.failed / review.changes_requested
+        // on a head a newer gate/observation superseded) is dropped entirely — it neither
+        // records a blocked reason nor folds. A missing/invalid head or a not-provably-stale
+        // ticket falls through and folds normally (fail-closed / backward compatible); the
+        // live done-gate re-evaluation is the backstop for staleness the ledger can't prove.
+        if (headScope === "stale_blocking_signal")
+            continue;
         // Record the blocking reason (latest wins; events are seq-ordered) regardless
         // of fold state, so a ticket blocked on a prior tick still resolves a reason.
-        if (event.type === "ci.failed" || event.type === "review.changes_requested") {
-            ticketBlockedReasons.set(ticketKey, event.type);
+        if (isHeadScopedBlockingSignal(signalType)) {
+            // BAPI-494: ci.failed / review.changes_requested / merge.conflict.
+            ticketBlockedReasons.set(ticketKey, signalType);
         }
-        else if (event.type === "spec_review.changes_requested") {
+        else if (signalType === "spec_review.changes_requested") {
             // BAPI-445: spec-review rejection. Tagged distinctly so reconcile escalates
             // it without spending the BAPI-441 implementation remediation budget.
             ticketBlockedReasons.set(ticketKey, "spec_review.changes_requested");
@@ -241,63 +649,107 @@ export function rebuildObservedState(postgresState, events, _now) {
         const postgresStatus = ticketStatusMap.get(ticketKey) ?? "planned";
         if (!isNonTerminal(postgresStatus))
             continue;
-        // Queue gate.met for merge actioning unless (a) this ticket's effective
-        // status this tick is non-mergeable ("blocked" — e.g. a ci.failed that
-        // folded earlier in the same batch, or a Postgres-blocked ticket whose
-        // ci.failed re-folds every tick), or (b) a gate.met for it is already
-        // queued. `postgresStatus` already reflects same-tick folds (the loop
-        // mutates `ticketStatusMap`), so a prior run.stopped fold leaves it
-        // "ready_for_review" and the merge proceeds — fixing the deadlock where a
-        // worker's run.stopped (lower seq) suppressed a later operator/CI gate.met.
-        if (event.type === "gate.met" &&
-            postgresStatus !== "blocked" &&
-            !mergeQueuedTicketKeys.has(ticketKey)) {
-            pendingMergeEvents.push(event);
-            mergeQueuedTicketKeys.add(ticketKey);
-        }
-        const signalType = event.type;
-        const nextStatus = signalToNextStatus(signalType, isReview);
-        if (foldedTicketKeys.has(ticketKey)) {
-            // Allow a bounded same-tick upgrade of an already-folded ticket:
-            //   1. ready_for_review → done when merge.succeeded arrives after gate.met
-            //      in the same ledger batch.
-            //   2. (BAPI-445) <any review fold> → blocked when a review run's
-            //      spec_review.changes_requested arrives after its run.stopped in the
-            //      same batch. A spec-review rejection must dominate plain completion
-            //      so a changes-requested verdict is never lost to event ordering.
-            // First-signal-wins for everything else: if ci.failed arrived first,
-            // currentLocalStatus is "blocked" (not "ready_for_review"), so the
-            // upgrade guard below is false and merge.succeeded is intentionally
-            // dropped — a failed-CI ticket must not be silently advanced to done.
-            const currentLocalStatus = ticketStatusMap.get(ticketKey);
-            const mergeUpgrade = currentLocalStatus === "ready_for_review" && nextStatus === "done";
-            const specRejectUpgrade = signalType === "spec_review.changes_requested" &&
-                currentLocalStatus !== "blocked";
-            if (mergeUpgrade || specRejectUpgrade) {
-                const existingIdx = unfoldedSignals.findIndex((s) => s.ticket_key === ticketKey);
-                if (existingIdx >= 0) {
-                    unfoldedSignals[existingIdx] = {
-                        ...unfoldedSignals[existingIdx],
-                        next_status: nextStatus,
-                        signal_type: signalType,
-                        event,
-                    };
-                    ticketStatusMap.set(ticketKey, nextStatus);
+        // BAPI-493 (A2/F6): enqueue the LATEST-head gate.met for merge, deduped by
+        // `(ticket, head_sha)`. The event must BE the latest gated head for its ticket
+        // (reference-equal to the prescan's retained event) so a stale-head gate.met can
+        // no longer claim the per-ticket slot and suppress the current-head one. Fail
+        // closed on a missing head. `postgresStatus` already reflects same-tick folds, so
+        // a prior run.stopped fold leaves it "ready_for_review" and the merge proceeds;
+        // BAPI-487: a stale-block-clearing gate on the newer head may enqueue even when
+        // the base status was `blocked`.
+        if (signalType === "gate.met" && eventHeadSha !== null) {
+            const latestGate = latestGatedHeadByTicket.get(ticketKey);
+            const isLatestGatedEvent = latestGate !== undefined && latestGate.event === event;
+            const gateMetClearsStale = headScope === "stale_block_clear_gate";
+            if (isLatestGatedEvent &&
+                (postgresStatus !== "blocked" || gateMetClearsStale)) {
+                const key = mergeQueueKey(ticketKey, eventHeadSha);
+                if (!mergeQueuedTicketHeadKeys.has(key)) {
+                    pendingMergeEvents.push(event);
+                    mergeQueuedTicketHeadKeys.add(key);
                 }
             }
+        }
+        // BAPI-493 (D-2, subsumes A3/F7): one exhaustive head-scoped precedence model
+        // replaces the five ad-hoc upgrade booleans. Every terminal signal resolves to
+        // exactly one of select / replace / drop.
+        const foldExists = foldedTicketKeys.has(ticketKey);
+        const currentLocalStatus = ticketStatusMap.get(ticketKey);
+        const decision = resolveTerminalFoldDecision(TERMINAL_PRECEDENCE, signalType, headScope, foldExists, currentLocalStatus, nextStatus);
+        if (decision.action === "drop")
+            continue;
+        if (decision.action === "select") {
+            // BAPI-500: skip a redundant blocked→blocked fold. When the ticket's
+            // effective status this tick is already `blocked` and this signal would
+            // only re-fold it to `blocked`, a status CAS persists no new status and
+            // only churns `row_version` (and re-logs the fold every tick). Skip ONLY
+            // the unfolded-signal push (the thing that drives the CAS) and the
+            // post-fold prediction — but still mark the ticket folded this tick so
+            // same-tick fold precedence is preserved: a later `gate.met`/`merge.succeeded`
+            // in the SAME batch is still dropped (upholding the documented
+            // ci.failed-wins invariant), exactly as when the redundant fold was pushed.
+            // The blocking reason/head side maps above are already populated, so the
+            // remediation pass still frames the blocked ticket correctly; and because
+            // no post-fold version is recorded, remediation CASes against the tick-start
+            // snapshot, which for an un-refolded durable block IS the current version.
+            // (Stale old-head blocks were cleared to `ready_for_review` before the fold
+            // loop, so a genuinely stale block never reaches this guard.) `foldedTicketKeys`
+            // is rebuilt per tick, so this does not affect the cross-tick path where a
+            // later `merge.succeeded` advances an already-blocked ticket to `done`.
+            if (nextStatus === "blocked" && currentLocalStatus === "blocked") {
+                foldedTicketKeys.add(ticketKey);
+                continue;
+            }
+            const rowVersion = ticketRowVersionMap.get(ticketKey) ?? 0;
+            // BAPI-500: predict the post-fold row version (snapshot + 1) so a follow-on
+            // remediation CAS this same pass uses the version the block CAS will write.
+            ticketPostFoldRowVersionMap.set(ticketKey, rowVersion + 1);
+            unfoldedSignals.push({
+                ticket_key: ticketKey,
+                postgres_row_version: rowVersion,
+                next_status: nextStatus,
+                signal_type: signalType,
+                event,
+            });
+            ticketStatusMap.set(ticketKey, nextStatus);
+            foldedTicketKeys.add(ticketKey);
             continue;
         }
-        const rowVersion = ticketRowVersionMap.get(ticketKey) ?? 0;
-        unfoldedSignals.push({
-            ticket_key: ticketKey,
-            postgres_row_version: rowVersion,
-            next_status: nextStatus,
-            signal_type: signalType,
-            event,
-        });
-        // Apply override locally so the effective status map reflects the change
+        // decision.action === "replace": a dominating signal overrides a same-tick fold.
+        // Preserve the one-CAS-per-ticket invariant (at most one unfolded signal each).
+        const existingIdx = unfoldedSignals.findIndex((s) => s.ticket_key === ticketKey);
+        if (existingIdx >= 0) {
+            unfoldedSignals[existingIdx] = {
+                ...unfoldedSignals[existingIdx],
+                next_status: nextStatus,
+                signal_type: signalType,
+                event,
+            };
+        }
+        else {
+            // A3/F7: a ticket already PERSISTED at ready_for_review with a later
+            // merge.succeeded (and no unfolded signal created earlier this tick) must
+            // still produce a fresh unfolded signal to `done` rather than silently
+            // dropping the transition. Use the current row version for the CAS guard.
+            const rowVersion = ticketRowVersionMap.get(ticketKey) ?? 0;
+            unfoldedSignals.push({
+                ticket_key: ticketKey,
+                postgres_row_version: rowVersion,
+                next_status: nextStatus,
+                signal_type: signalType,
+                event,
+            });
+        }
         ticketStatusMap.set(ticketKey, nextStatus);
         foldedTicketKeys.add(ticketKey);
+        // BAPI-493/BAPI-494: a current (non-stale) blocking signal — ci.failed,
+        // review.changes_requested, or merge.conflict — that just folded the ticket to
+        // `blocked` must evict ANY pending merge queued for that ticket this tick —
+        // regardless of whether the block's head matches the queued gate's head — or a
+        // now-superseded gate could still be merged despite the block winning the fold.
+        if (isHeadScopedBlockingSignal(signalType)) {
+            dropPendingMergesForTicket(ticketKey);
+        }
     }
     return {
         epic_key: epic_run.epic_key,
@@ -305,8 +757,10 @@ export function rebuildObservedState(postgresState, events, _now) {
         plan_version: epic_run.current_plan_version,
         ticket_statuses: ticketStatusMap,
         ticket_row_versions: ticketRowVersionMap,
+        ticket_post_fold_row_versions: ticketPostFoldRowVersionMap,
         ticket_remediation_counters: ticketRemediationMap,
         ticket_blocked_reasons: ticketBlockedReasons,
+        ticket_blocked_heads: ticketBlockedHeads,
         unfolded_terminal_signals: unfoldedSignals,
         pending_merge_events: pendingMergeEvents,
     };