@bridge_gpt/mcp-server 0.2.9 → 0.2.12

package/build/conductor/epic-state.js

@@ -1,44 +1,93 @@
 /**
  * Pure, deterministic observed-state rebuild + ready-set computation for the
- * Epic Supervisor (BAPI-408).
+ * Epic Supervisor (BAPI-408, BAPI-436).
  *
  * This module has NO I/O, NO timers, and NO LLM calls. Every time-dependent
  * function takes an explicit `now` (epoch ms) so tests are wall-clock
  * independent. Truth precedence: raw local ledger events override non-terminal
  * Postgres states.
+ *
+ * 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)
+ *   merge.succeeded → done            (merged; dependents may now dispatch)
+ *   ci.failed     → blocked           (unchanged)
  */
 // ---------------------------------------------------------------------------
 // Status sets (module-private)
 // ---------------------------------------------------------------------------
 const NOT_STARTED_STATUS = "planned";
 const DONE_STATUSES = new Set(["done"]);
+// "blocked" is intentionally non-terminal: a merge.succeeded arriving in a
+// subsequent tick (cross-tick) can still advance a blocked ticket to done.
+// This is the expected path when an operator merges a PR despite failed CI.
+// Contrast with the same-tick case: ci.failed wins over merge.succeeded in
+// the same ledger batch (first-signal-wins; see the foldedTicketKeys guard).
 const NON_TERMINAL_STATUSES = new Set([
     "planned",
     "ready",
     "dispatched",
     "running",
     "blocked",
+    "ready_for_review",
+    // BAPI-445: mid-flight pre-implementation spec re-review. Non-terminal so a
+    // review verdict / completion signal can still advance it on a later tick, but
+    // deliberately NOT a status computeReadySet returns for normal dispatch — a
+    // reviewing ticket is mid-flight, not ready. Stranded reviewing tickets are
+    // re-driven by reconcile's dedicated reviewing re-entry branch.
+    "reviewing",
 ]);
 const TERMINAL_SIGNAL_TYPES = new Set([
     "gate.met",
     "merge.succeeded",
     "ci.failed",
     "run.stopped",
+    "review.changes_requested",
+    // BAPI-445: pre-implementation spec re-review verdicts, scoped to review runs.
+    "spec_review.passed",
+    "spec_review.changes_requested",
 ]);
 function isNonTerminal(status) {
     return NON_TERMINAL_STATUSES.has(status);
 }
-function signalToNextStatus(signalType) {
+/**
+ * Map a terminal ledger signal to the next ticket status.
+ *
+ * `isReviewRun` marks signals correlated to a `:review`-suffixed dispatch
+ * (BAPI-445 Obstacle 2). The spec re-review verdicts fold explicitly:
+ *   - `spec_review.passed`            → `ready`   (verdict: proceed to implementation)
+ *   - `spec_review.changes_requested` → `blocked` (verdict: reject; reconcile escalates)
+ *
+ * FAIL-SAFE (BAPI-445): a review run's INCIDENTAL terminals (`run.stopped`,
+ * `gate.met`, …) are filtered out of folding entirely by `rebuildObservedState`
+ * BEFORE this function is called — a review session merely *ending* must never
+ * advance a `reviewing` ticket, or implementation would proceed regardless of
+ * the review's outcome (fail-open). So for a review run this is only ever called
+ * with a `spec_review.*` verdict; `isReviewRun` is retained for caller clarity.
+ * For implementation runs the BAPI-436 mapping is unchanged.
+ */
+export function signalToNextStatus(signalType, isReviewRun = false) {
+    void isReviewRun; // review-run incidental terminals are filtered before this call
+    if (signalType === "spec_review.passed")
+        return "ready";
+    if (signalType === "spec_review.changes_requested")
+        return "blocked";
     if (signalType === "ci.failed")
         return "blocked";
-    return "done";
+    if (signalType === "review.changes_requested")
+        return "blocked";
+    if (signalType === "merge.succeeded")
+        return "done";
+    return "ready_for_review"; // gate.met and (implementation) run.stopped: awaiting merge
 }
 // ---------------------------------------------------------------------------
 // computeReadySet
 // ---------------------------------------------------------------------------
 /**
  * Pure deterministic ready-set computation. Returns ticket keys that:
- *   1. Have status "planned" (not yet started), AND
+ *   1. Have status "planned" (not yet started) or "ready" (crash-recovery —
+ *      a ticket already advanced to ready on a prior tick that crashed before
+ *      dispatch must not be silently dropped), AND
  *   2. Whose full `depends_on` list is satisfied (all deps have "done" status).
  *
  * Never calls an LLM or performs I/O. Goal 8 invariant.
@@ -47,7 +96,7 @@ export function computeReadySet(plan, ticketStatuses) {
     const ready = [];
     for (const ticket of plan.tickets) {
         const currentStatus = ticketStatuses.get(ticket.ticket_key) ?? "planned";
-        if (currentStatus !== NOT_STARTED_STATUS)
+        if (currentStatus !== NOT_STARTED_STATUS && currentStatus !== "ready")
             continue;
         const allDepsResolved = ticket.depends_on.every((dep) => DONE_STATUSES.has(ticketStatuses.get(dep) ?? "planned"));
         if (allDepsResolved)
@@ -55,6 +104,53 @@ export function computeReadySet(plan, ticketStatuses) {
     }
     return ready;
 }
+/**
+ * Default ceiling for spec re-review dispatch attempts on a stranded `reviewing`
+ * ticket (BAPI-445). Counts the initial review dispatch plus liveness-recovery
+ * re-dispatches; once reached, the reviewing recovery branch escalates instead
+ * of re-dispatching. Deliberately independent of the BAPI-441 remediation budget.
+ */
+export const DEFAULT_MAX_SPEC_REVIEW_ATTEMPTS = 3;
+/**
+ * Pure, deterministic remediation decision (no I/O, no clock). Given the current
+ * budget counters, the ledger-derived worker liveness, and the configured
+ * ceilings, decide whether to NUDGE (worker still alive), RE-DISPATCH (worker
+ * gone, budget remaining), or ESCALATE (budget exhausted).
+ *
+ * Budget exhaustion is checked FIRST so an at-ceiling ticket always escalates
+ * regardless of liveness. A counter at-or-above its ceiling exhausts the budget.
+ */
+export function decideRemediation(attempts, noProgressAttempts, alive, config) {
+    if (attempts >= config.max_remediation_attempts ||
+        noProgressAttempts >= config.max_remediation_no_progress_attempts) {
+        return "escalate";
+    }
+    return alive ? "nudge" : "redispatch";
+}
+/**
+ * Pure liveness extraction (no I/O, explicit `nowMs`). Finds the most recent
+ * `message.delivered`/`message.acked` heartbeat event for `runId` and reports
+ * the worker alive when that heartbeat's age is within
+ * `windowSeconds`. An empty ledger (no heartbeat for the run) defaults to
+ * `{ alive: false, workerId: null }` (fail-closed: never misjudge a worker
+ * alive without evidence).
+ */
+export function extractWorkerLiveness(events, runId, nowMs, windowSeconds) {
+    let latest = null;
+    for (const ev of events) {
+        if (ev.run_id !== runId)
+            continue;
+        if (ev.type !== "message.delivered" && ev.type !== "message.acked")
+            continue;
+        if (!latest || new Date(ev.time).getTime() > new Date(latest.time).getTime()) {
+            latest = ev;
+        }
+    }
+    if (!latest)
+        return { alive: false, workerId: null };
+    const age = nowMs - new Date(latest.time).getTime();
+    return { alive: age <= windowSeconds * 1000, workerId: latest.worker_id ?? null };
+}
 // ---------------------------------------------------------------------------
 // rebuildObservedState
 // ---------------------------------------------------------------------------
@@ -65,42 +161,117 @@ export function computeReadySet(plan, ticketStatuses) {
  */
 export function rebuildObservedState(postgresState, events, _now) {
     const { epic_run, ticket_statuses, dispatches } = postgresState;
-    // Build run_id → ticket_key lookup from dispatch records
+    // Build run_id → {ticket_key, isReview} lookup from dispatch records.
+    // BAPI-445 (Obstacle 2): a review run's dispatch_key carries a ":review"
+    // suffix, so the same run_id map can distinguish a pre-implementation
+    // spec-review run from the implementation run. This is correctness-critical:
+    // it lets the fold below route a review run's run.stopped to "ready" (review
+    // complete → proceed) instead of mis-folding it as implementation completion
+    // ("ready_for_review", awaiting merge), which would skip implementation.
     const runIdToTicketKey = new Map();
     for (const dispatch of dispatches) {
         if (dispatch.run_id) {
-            runIdToTicketKey.set(dispatch.run_id, dispatch.ticket_key);
+            runIdToTicketKey.set(dispatch.run_id, {
+                ticketKey: dispatch.ticket_key,
+                isReview: dispatch.dispatch_key.endsWith(":review"),
+            });
         }
     }
     // Populate base maps from Postgres
     const ticketStatusMap = new Map();
     const ticketRowVersionMap = new Map();
+    const ticketRemediationMap = new Map();
     for (const ts of ticket_statuses) {
         ticketStatusMap.set(ts.ticket_key, ts.status);
         ticketRowVersionMap.set(ts.ticket_key, ts.row_version);
+        ticketRemediationMap.set(ts.ticket_key, {
+            attempts: ts.remediation_attempts ?? 0,
+            no_progress: ts.remediation_no_progress_attempts ?? 0,
+        });
     }
     const unfoldedSignals = [];
     const pendingMergeEvents = [];
     // Track which tickets already have a folded signal (one override per ticket)
     const foldedTicketKeys = new Set();
+    // 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();
     for (const event of events) {
         if (!TERMINAL_SIGNAL_TYPES.has(event.type))
             continue;
-        // Map event → ticket via run_id
+        // Map event → ticket via run_id, resolving the dispatch role (review vs.
+        // implementation) so the fold can treat review-run terminals distinctly.
         const runId = typeof event.run_id === "string" ? event.run_id : null;
-        const ticketKey = runId ? runIdToTicketKey.get(runId) : undefined;
-        if (!ticketKey)
+        const mapped = runId ? runIdToTicketKey.get(runId) : undefined;
+        if (!mapped)
             continue;
-        if (event.type === "gate.met") {
-            pendingMergeEvents.push(event);
+        const ticketKey = mapped.ticketKey;
+        const isReview = mapped.isReview;
+        // BAPI-445 FAIL-SAFE: a review run's INCIDENTAL terminals (run.stopped,
+        // gate.met, …) must never advance a `reviewing` ticket — ONLY an explicit
+        // spec_review.* verdict does. A review session merely ending must not fold
+        // reviewing → ready and dispatch implementation regardless of whether the
+        // review requested changes (that would be fail-OPEN). When the verdict is
+        // not (yet) emitted, the ticket stays in `reviewing` and the reconcile
+        // liveness-recovery / escalation path surfaces it for operator attention —
+        // implementation never silently proceeds without a pass verdict.
+        const isSpecVerdict = event.type === "spec_review.passed" ||
+            event.type === "spec_review.changes_requested";
+        if (isReview && !isSpecVerdict)
+            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);
+        }
+        else if (event.type === "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");
         }
         const postgresStatus = ticketStatusMap.get(ticketKey) ?? "planned";
         if (!isNonTerminal(postgresStatus))
             continue;
-        if (foldedTicketKeys.has(ticketKey))
-            continue;
+        // Only queue for merge actioning if this ticket hasn't already been folded
+        // this tick. Without this guard, two gate.met events for the same ticket
+        // would both enqueue, and a ci.failed → gate.met sequence would enqueue a
+        // merge action for a ticket whose effective status is "blocked".
+        if (event.type === "gate.met" && !foldedTicketKeys.has(ticketKey)) {
+            pendingMergeEvents.push(event);
+        }
         const signalType = event.type;
-        const nextStatus = signalToNextStatus(signalType);
+        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);
+                }
+            }
+            continue;
+        }
         const rowVersion = ticketRowVersionMap.get(ticketKey) ?? 0;
         unfoldedSignals.push({
             ticket_key: ticketKey,
@@ -119,6 +290,8 @@ export function rebuildObservedState(postgresState, events, _now) {
         plan_version: epic_run.current_plan_version,
         ticket_statuses: ticketStatusMap,
         ticket_row_versions: ticketRowVersionMap,
+        ticket_remediation_counters: ticketRemediationMap,
+        ticket_blocked_reasons: ticketBlockedReasons,
         unfolded_terminal_signals: unfoldedSignals,
         pending_merge_events: pendingMergeEvents,
     };

package/build/conductor/errors.js

@@ -64,6 +64,18 @@ function isSqliteBusyError(error) {
  *     the raw error text, stack, and any secret material are discarded.
  */
 export function toConductorErrorEnvelope(error) {
+    // Optional-native-binding degradation (BAPI-451): the conductor `store.ts`
+    // throws ConductorPersistenceUnavailableError when `better-sqlite3` could not be
+    // loaded. Detected by name (not instanceof) to avoid an import cycle with
+    // store.ts. Surfaced as a retryable-shaped 503 with a fixed, secret-free message
+    // so the caller learns persistence is unavailable instead of getting an opaque 500.
+    if (error instanceof Error && error.name === "ConductorPersistenceUnavailableError") {
+        return {
+            error: "PERSISTENCE_UNAVAILABLE",
+            status: 503,
+            message: "Conductor persistence is unavailable (the optional better-sqlite3 native module is not loaded). Conductor coordination features are disabled; core tools are unaffected.",
+        };
+    }
     if (error instanceof ConductorValidationError) {
         // Validation messages are conductor-authored and name the offending field,
         // never its value — but redact defensively so an adversarial/secret-bearing

package/build/conductor/git-ci-types.js

@@ -25,8 +25,24 @@ export const GIT_CI_PRODUCER = "git-pr-ci-producer";
 export const GIT_HOOK_PRODUCER = "git-hook";
 /** The single v1 done-gate condition type. */
 export const REQUIRED_CI_CHECKS_GREEN = "required_ci_checks_green";
+/** The v2 review-state done-gate condition type. */
+export const REVIEW_STATE = "review_state";
 /** Default gate name surfaced in `gate.met` event data. */
 export const DEFAULT_GATE_NAME = "done";
+/** Event type emitted when the configured review source is satisfied. */
+export const REVIEW_PASSED = "review.passed";
+/** Event type emitted when a reviewer requests changes. */
+export const REVIEW_CHANGES_REQUESTED = "review.changes_requested";
+/**
+ * BAPI-445 pre-implementation SPEC re-review verdict event types. Emitted by the
+ * spec re-review run (``/review-ticket --auto``), correlated to that review run,
+ * and kept distinct from the PR-review {@link REVIEW_PASSED} /
+ * {@link REVIEW_CHANGES_REQUESTED} verdicts so a spec-review outcome is never
+ * folded as the implementation PR's review state.
+ */
+export const SPEC_REVIEW_PASSED = "spec_review.passed";
+/** Event type emitted when a spec re-review requests changes. */
+export const SPEC_REVIEW_CHANGES_REQUESTED = "spec_review.changes_requested";
 /** Matches ASCII control characters (C0 range plus DEL). */
 const CONTROL_CHAR_RE = /[\u0000-\u001F\u007F]/;
 /** Matches a 40- or 64-character hex string (git SHA-1 / SHA-256 object ids). */

package/build/conductor/git-producer.js

@@ -79,7 +79,7 @@ export function buildWorktreeChangedEventInput(context, updates, phase) {
  * dedupe by `repo + commit_sha`, and emit best-effort. Returns a
  * success-compatible result for every failure mode so the commit is never blocked.
  */
-export function runPostCommitHookProducer(deps = {}) {
+export async function runPostCommitHookProducer(deps = {}) {
     const getContext = deps.getContext ?? getGitWorktreeContext;
     const readMetadata = deps.readMetadata ?? readHeadCommitMetadata;
     const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
@@ -90,7 +90,7 @@ export function runPostCommitHookProducer(deps = {}) {
             return { ok: true, emitted: false, reason: "no-head-commit" };
         }
         const input = buildCommitCreatedEventInput(context, metadata);
-        const decision = emitIfNew(input, {
+        const decision = await emitIfNew(input, {
             event_type: "git.commit_created",
             repo: context.repo,
             commit_sha: metadata.sha,
@@ -109,7 +109,7 @@ export function runPostCommitHookProducer(deps = {}) {
  * success-compatible result for every failure mode so the ref update is never
  * blocked.
  */
-export function runReferenceTransactionHookProducer(args, deps = {}) {
+export async function runReferenceTransactionHookProducer(args, deps = {}) {
     const getContext = deps.getContext ?? getGitWorktreeContext;
     const parseUpdates = deps.parseUpdates ?? parseReferenceTransactionUpdates;
     const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
@@ -124,7 +124,7 @@ export function runReferenceTransactionHookProducer(args, deps = {}) {
         const context = getContext({ cwd: deps.cwd, env: deps.env });
         const input = buildWorktreeChangedEventInput(context, updates, args.phase);
         const refUpdatesHash = stableJsonHash({ phase: args.phase, updates });
-        const decision = emitIfNew(input, {
+        const decision = await emitIfNew(input, {
             event_type: "worktree.changed",
             repo: context.repo,
             ref_updates_hash: refUpdatesHash,

package/build/conductor/merge-ledger.js

@@ -103,9 +103,9 @@ export function makeMergeEventId(eventType, actionKey) {
     const h = createHash("sha256").update(`${eventType}:${actionKey}`).digest("hex");
     return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
 }
-function lookupMergeEventByActionKey(eventType, actionKey, deps) {
+async function lookupMergeEventByActionKey(eventType, actionKey, deps) {
     const openDb = deps.openDb ?? (() => openReadonlyConductorDatabaseIfExists());
-    const db = openDb();
+    const db = await openDb();
     if (!db)
         return false;
     try {
@@ -126,7 +126,7 @@ function lookupMergeEventByActionKey(eventType, actionKey, deps) {
  * the action key. Only `merge.succeeded` is terminal — `merge.failed` and
  * `merge.dry_run` are never terminal.
  */
-export function hasTerminalMergeSucceeded(actionKey, deps = {}) {
+export async function hasTerminalMergeSucceeded(actionKey, deps = {}) {
     return lookupMergeEventByActionKey("merge.succeeded", actionKey, deps);
 }
 /**
@@ -134,7 +134,7 @@ export function hasTerminalMergeSucceeded(actionKey, deps = {}) {
  * Dry-run is audit/hygiene only and is NEVER treated as terminal — a later real
  * merge for the same PR/head/gate may still proceed if the repo flag is enabled.
  */
-export function hasMergeDryRun(actionKey, deps = {}) {
+export async function hasMergeDryRun(actionKey, deps = {}) {
     return lookupMergeEventByActionKey("merge.dry_run", actionKey, deps);
 }
 /**
@@ -142,7 +142,7 @@ export function hasMergeDryRun(actionKey, deps = {}) {
  * action key. Pending approval is NEVER terminal — the supervisor must re-dispatch
  * until the backend reports approval (returning `merge.attempted` + `merge.succeeded`).
  */
-export function hasMergePendingApproval(actionKey, deps = {}) {
+export async function hasMergePendingApproval(actionKey, deps = {}) {
     return lookupMergeEventByActionKey("merge.pending_approval", actionKey, deps);
 }
 /** Heuristically detect a SQLite duplicate-id / UNIQUE constraint failure. */
@@ -167,7 +167,7 @@ function isDuplicateConstraintError(error) {
  * outcome fields live under `details`). A duplicate UNIQUE-constraint failure is
  * classified as `{ emitted: false, reason: "duplicate" }` rather than thrown.
  */
-export function emitMergeLedgerEventIfNew(input, deps = {}) {
+export async function emitMergeLedgerEventIfNew(input, deps = {}) {
     const emitEvent = deps.emitEvent ?? emitConductorEvent;
     const eventId = makeMergeEventId(input.type, input.action_key);
     const event = {
@@ -186,7 +186,7 @@ export function emitMergeLedgerEventIfNew(input, deps = {}) {
         },
     };
     try {
-        const result = emitEvent(event);
+        const result = await emitEvent(event);
         return { emitted: true, event_id: eventId, event: result.event };
     }
     catch (error) {