@bridge_gpt/mcp-server 0.2.16 → 0.2.19

package/build/conductor/github-mergeability.js

@@ -0,0 +1,85 @@
+/**
+ * Shared GitHub PR mergeability normalization + conflict classification (BAPI-494).
+ *
+ * The conductor gained ZERO mergeability awareness before this ticket: a sibling
+ * PR left `CONFLICTING`/`DIRTY` by an overlapping merge would sit at
+ * `ready_for_review` forever (catalog A4 / run-report F3). This module is the
+ * single, dependency-light source of truth for reading GitHub's
+ * `mergeable`/`mergeStateStatus` fields and deciding whether a PR is un-mergeable,
+ * so PR discovery, the done-gate binding resolution, and the local merge executor
+ * all classify a conflict the SAME way.
+ *
+ * Every helper is PURE, NON-THROWING, and FAIL-CLOSED: an unknown/missing/malformed
+ * mergeability value is treated as non-conflicting/unknown, never as a conflict, and
+ * raw `gh` process output is only ever matched against sanitized text — it is never
+ * returned, logged, or copied into event data.
+ */
+/**
+ * Normalize a raw GitHub mergeability field. Returns a trimmed, uppercased string
+ * for a non-empty string value, and `null` for every other shape (missing, empty,
+ * whitespace-only, non-string). Never throws.
+ */
+export function normalizeGhMergeabilityValue(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    return trimmed.toUpperCase();
+}
+/**
+ * Read `mergeable` and `mergeStateStatus` from an already-parsed `gh pr view`
+ * JSON record and return a normalized {@link GhPrMergeability}. Unknown/malformed
+ * fields become `null` (fail-closed) so a valid PR with an unreadable mergeability
+ * value is never mistaken for a conflict.
+ */
+export function parseGhPrMergeabilityFields(record) {
+    return {
+        mergeable: normalizeGhMergeabilityValue(record.mergeable),
+        mergeStateStatus: normalizeGhMergeabilityValue(record.mergeStateStatus),
+    };
+}
+/**
+ * True only for the two authoritative conflict signals GitHub exposes:
+ * `mergeable === "CONFLICTING"` or `mergeStateStatus === "DIRTY"`. Every other
+ * combination — mergeable/clean, unknown, or null — is NOT a conflict. Fail-closed.
+ */
+export function isPrMergeConflict(mergeability) {
+    return mergeability.mergeable === "CONFLICTING" || mergeability.mergeStateStatus === "DIRTY";
+}
+/**
+ * Sanitized signatures that a `gh pr merge` failure was caused by a merge
+ * conflict / non-fast-forward condition (rather than an auth, rate-limit, network,
+ * or not-found failure). Matched case-insensitively against the sanitized failure
+ * text; the raw output itself is never returned or logged.
+ */
+const MERGE_CONFLICT_OUTPUT_SIGNATURES = [
+    "merge conflict",
+    "merge conflicts",
+    "conflicting",
+    "conflict with the base branch",
+    "not possible to fast-forward",
+    "non-fast-forward",
+    "not mergeable",
+    "is not mergeable",
+    "cannot be cleanly created",
+    "would create a merge conflict",
+];
+/**
+ * Classify raw `gh pr merge` failure output as a LIKELY merge-conflict /
+ * non-fast-forward failure. Reads only `stdout`/`stderr` text for defensive
+ * substring matching and returns a boolean — it never returns, logs, or otherwise
+ * exposes the raw process output. Returns `false` for unrelated failures
+ * (authentication, rate limit, network timeout, repository not found, generic
+ * GraphQL errors).
+ */
+export function isLikelyGhMergeConflictOutput(output) {
+    if (!output)
+        return false;
+    const stdout = typeof output.stdout === "string" ? output.stdout : "";
+    const stderr = typeof output.stderr === "string" ? output.stderr : "";
+    const haystack = `${stdout}\n${stderr}`.toLowerCase();
+    if (haystack.trim().length === 0)
+        return false;
+    return MERGE_CONFLICT_OUTPUT_SIGNATURES.some((sig) => haystack.includes(sig));
+}

package/build/conductor/local-merge.js

@@ -18,6 +18,7 @@
  */
 import { spawnSync } from "child_process";
 import { pollCiChecksForCommit, } from "./bridge-api-client.js";
+import { isLikelyGhMergeConflictOutput, isPrMergeConflict, parseGhPrMergeabilityFields, } from "./github-mergeability.js";
 const MERGE_METHODS = new Set(["squash", "merge", "rebase"]);
 /**
  * Hard wall-clock cap on every `gh` subprocess. The epic-tick runs in a single
@@ -180,7 +181,52 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
         // 4. Provider merge.
         const merge = run("gh", ["pr", "merge", String(pr), `--${method}`, "--match-head-commit", expectedSha], ghEnv);
         if (merge.status !== 0) {
-            const mergeFailReason = merge.timedOut ? "gh_merge_timeout" : "gh_merge_failed";
+            // A hung `gh` (killed by the wall-clock timeout) is operationally distinct
+            // from a permission/conflict failure — keep it mapped to gh_merge_timeout.
+            if (merge.timedOut) {
+                const reason = "gh_merge_timeout";
+                return buildResponse(request, "failed", reason, false, [
+                    { type: "merge.attempted", status: "attempted", details: baseDetails },
+                    { type: "merge.failed", status: "failed", reason, details: baseDetails },
+                ]);
+            }
+            // BAPI-494: classify a conflict / non-fast-forward failure distinctly so it
+            // folds to `blocked` and remediates instead of hiding behind gh_merge_failed.
+            // First match the sanitized failure output; if inconclusive, do ONE follow-up
+            // mergeability re-read (only AFTER a merge failure — never before a successful
+            // or guarded merge) and check it. Raw stdout/stderr is used only for defensive
+            // classification and is never copied into event data or logs.
+            let mergeability = { mergeable: null, mergeStateStatus: null };
+            let isConflict = isLikelyGhMergeConflictOutput(merge);
+            if (!isConflict) {
+                const recheck = run("gh", ["pr", "view", String(pr), "--json", "mergeable,mergeStateStatus"], ghEnv);
+                if (recheck.status === 0) {
+                    try {
+                        mergeability = parseGhPrMergeabilityFields(JSON.parse(recheck.stdout));
+                        isConflict = isPrMergeConflict(mergeability);
+                    }
+                    catch {
+                        /* best-effort classification only */
+                    }
+                }
+            }
+            if (isConflict) {
+                const reason = "gh_merge_conflict";
+                // Head-scoped to the attempted head SHA so the fold blocks the exact head; a
+                // later rebase clears it via the stale-head logic. mergeable/mergeStateStatus
+                // are included only when known.
+                const conflictDetails = {
+                    ...baseDetails,
+                    head_sha: expectedSha,
+                    ...(mergeability.mergeable ? { mergeable: mergeability.mergeable } : {}),
+                    ...(mergeability.mergeStateStatus ? { mergeStateStatus: mergeability.mergeStateStatus } : {}),
+                };
+                return buildResponse(request, "failed", reason, false, [
+                    { type: "merge.attempted", status: "attempted", details: baseDetails },
+                    { type: "merge.conflict", status: "failed", reason, details: conflictDetails },
+                ]);
+            }
+            const mergeFailReason = "gh_merge_failed";
             return buildResponse(request, "failed", mergeFailReason, false, [
                 { type: "merge.attempted", status: "attempted", details: baseDetails },
                 { type: "merge.failed", status: "failed", reason: mergeFailReason, details: baseDetails },

package/build/conductor/merge-identity.js

@@ -0,0 +1,41 @@
+/**
+ * Low-level merge-identity primitives (BAPI-493).
+ *
+ * Extracted from `merge-ledger.ts` so the typed event-accessor layer
+ * (`event-accessors.ts`) can build a canonical {@link MergeActionIdentity}
+ * without importing the merge-ledger store/emit surface (which would create an
+ * import cycle: merge-ledger → event-accessors → merge-ledger).
+ *
+ * This module depends ONLY on the pure boundary validators in `git-ci-types.ts`.
+ * It performs no I/O and holds no VCS write credentials. The deterministic action
+ * key `merge:{repo}:{pr}:{head_sha}:{gate}` is kept in lock-step with the Python
+ * `build_merge_action_key`; the gate-identity segment mirrors the Python
+ * `normalize_gate_identity`.
+ */
+import { normalizePrNumber, normalizeRepoName, normalizeSha } from "./git-ci-types.js";
+/**
+ * Compose the stable gate-identity segment, mirroring the Python
+ * `normalize_gate_identity`: `{name}@{config_hash}` when a hash is present
+ * (lower-cased), otherwise just the gate name.
+ */
+export function buildGateIdentity(gateName, configHash) {
+    const name = gateName.trim();
+    const hash = typeof configHash === "string" ? configHash.trim() : "";
+    return hash ? `${name}@${hash.toLowerCase()}` : name;
+}
+/**
+ * Build the deterministic action key. Normalizes repo / PR / head SHA exactly as
+ * the Python side does (lower-cased SHA, trimmed repo, positive integer PR) so the
+ * conductor-computed key and the API-recomputed key are byte-identical. Throws on
+ * any invalid component. The branch name is never part of the key.
+ */
+export function makeMergeActionKey(repo, prNumber, headSha, gateIdentity) {
+    const r = normalizeRepoName(repo);
+    const pr = normalizePrNumber(prNumber);
+    const sha = normalizeSha(headSha);
+    const gate = (gateIdentity ?? "").trim();
+    if (r === null || pr === null || sha === null || gate.length === 0) {
+        throw new Error("invalid merge action key component");
+    }
+    return `merge:${r}:${pr}:${sha}:${gate}`;
+}

package/build/conductor/merge-ledger.js

@@ -16,82 +16,29 @@
  * It performs NO privileged action and never handles VCS write credentials.
  */
 import { createHash } from "node:crypto";
-import { normalizePrNumber, normalizeRepoName, normalizeSha } from "./git-ci-types.js";
+import { getMergeIdentity } from "./event-accessors.js";
+import { buildGateIdentity, makeMergeActionKey, } from "./merge-identity.js";
 import { emitConductorEvent, openReadonlyConductorDatabaseIfExists, } from "./store.js";
+// BAPI-493: the merge-identity primitives now live in the dependency-light
+// `merge-identity.ts` module (so the typed event-accessor layer can build a
+// MergeActionIdentity without an import cycle). They are re-exported here so
+// existing importers (`supervisor-merge.ts`, tests) keep a stable API surface.
+export { buildGateIdentity, makeMergeActionKey };
 /**
- * Compose the stable gate-identity segment, mirroring the Python
- * `normalize_gate_identity`: `{name}@{config_hash}` when a hash is present
- * (lower-cased), otherwise just the gate name.
- */
-export function buildGateIdentity(gateName, configHash) {
-    const name = gateName.trim();
-    const hash = typeof configHash === "string" ? configHash.trim() : "";
-    return hash ? `${name}@${hash.toLowerCase()}` : name;
-}
-/**
- * Build the deterministic action key. Normalizes repo / PR / head SHA exactly as
- * the Python side does (lower-cased SHA, trimmed repo, positive integer PR) so the
- * conductor-computed key and the API-recomputed key are byte-identical. Throws on
- * any invalid component. The branch name is never part of the key.
- */
-export function makeMergeActionKey(repo, prNumber, headSha, gateIdentity) {
-    const r = normalizeRepoName(repo);
-    const pr = normalizePrNumber(prNumber);
-    const sha = normalizeSha(headSha);
-    const gate = (gateIdentity ?? "").trim();
-    if (r === null || pr === null || sha === null || gate.length === 0) {
-        throw new Error("invalid merge action key component");
-    }
-    return `merge:${r}:${pr}:${sha}:${gate}`;
-}
-/**
- * Resolve the immutable merge identity from a `gate.met` event. Returns `null`
- * unless the event is a worker-scoped `gate.met` carrying a complete PR binding
- * (repo, pr_number, head_sha, gate_name). Run-level or incomplete events yield
- * `null`. Branch-name fields, if present, are ignored.
+ * Resolve the immutable merge identity from a `gate.met` event. Returns a non-null
+ * identity for any complete PR-bound `gate.met` (repo, pr_number, head_sha,
+ * gate_name), regardless of worker attribution — `worker_id` is attribution
+ * metadata only and is not required for merge identity extraction (BAPI-525
+ * Change A). Incomplete PR bindings remain fail-closed and yield `null`.
+ * Branch-name fields, if present, are ignored.
+ *
+ * BAPI-493: canonical parsing now lives in the typed accessor layer — this is a
+ * thin compatibility wrapper over {@link getMergeIdentity} so `supervisor-merge.ts`
+ * and other callers keep an unchanged call site while the hand-rolled
+ * `data.details` reader is retired.
  */
 export function extractMergeActionIdentityFromGateEvent(event) {
-    if (event.type !== "gate.met")
-        return null;
-    // Worker scope is required — a run-level gate.met never binds a specific worker.
-    if (typeof event.worker_id !== "string" || event.worker_id.trim().length === 0) {
-        return null;
-    }
-    const data = event.data ?? {};
-    const details = data.details;
-    if (!details || typeof details !== "object")
-        return null;
-    const d = details;
-    const repo = normalizeRepoName(d.repo);
-    const prNumber = normalizePrNumber(d.pr_number);
-    const headSha = normalizeSha(d.head_sha);
-    const gateName = typeof d.gate_name === "string" ? d.gate_name.trim() : "";
-    if (repo === null || prNumber === null || headSha === null || gateName.length === 0) {
-        return null;
-    }
-    const configHash = typeof d.config_hash === "string" && d.config_hash.trim().length > 0
-        ? d.config_hash.trim()
-        : null;
-    const requiredChecks = Array.isArray(d.required_checks)
-        ? d.required_checks.filter((c) => typeof c === "string" && c.trim().length > 0)
-        : [];
-    const gateIdentity = buildGateIdentity(gateName, configHash);
-    const actionKey = makeMergeActionKey(repo, prNumber, headSha, gateIdentity);
-    return {
-        repo,
-        pr_number: prNumber,
-        head_sha: headSha,
-        gate_name: gateName,
-        config_hash: configHash,
-        required_checks: requiredChecks,
-        gate_identity: gateIdentity,
-        action_key: actionKey,
-        gate_event: {
-            id: typeof event.id === "string" ? event.id : undefined,
-            seq: typeof event.seq === "number" ? event.seq : undefined,
-            time: typeof event.time === "string" ? event.time : undefined,
-        },
-    };
+    return getMergeIdentity(event);
 }
 /**
  * Derive a deterministic, UUID-shaped event id from the event type plus action

package/build/conductor/plan.js

@@ -31,12 +31,16 @@ import { stableJsonHash } from "./git-ci-types.js";
  *
  *   - Trims outer whitespace from every `ticket_key` (nodes and edges).
  *   - Sorts each node's `depends_on` array alphabetically.
+ *   - Sorts each node's `touched_files` array alphabetically, when present.
  *   - Sorts `nodes` lexicographically by normalized `ticket_key`.
  *   - Sorts `edges` lexicographically by `from` then `to`.
+ *   - Sorts each edge's `overlap_files` array alphabetically, when present.
  *
  * The canonical form is fed to {@link hashPlan} / `stableJsonHash`, which
  * additionally sorts object keys recursively, so two independently constructed
- * equal plans always produce a byte-identical SHA-256 digest.
+ * equal plans always produce a byte-identical SHA-256 digest. Only fields
+ * already present on the input are normalized — canonicalization never
+ * derives new data from filesystem, git, network, or LLM state.
  */
 export function canonicalizePlanDAG(plan) {
     const nodes = plan.nodes
@@ -44,10 +48,16 @@ export function canonicalizePlanDAG(plan) {
         ...node,
         ticket_key: node.ticket_key.trim(),
         depends_on: [...node.depends_on].map((k) => k.trim()).sort(),
+        ...(node.touched_files ? { touched_files: [...node.touched_files].sort() } : {}),
     }))
         .sort((a, b) => a.ticket_key.localeCompare(b.ticket_key));
     const edges = [...plan.edges]
-        .map((e) => ({ from: e.from.trim(), to: e.to.trim() }))
+        .map((e) => ({
+        from: e.from.trim(),
+        to: e.to.trim(),
+        ...(e.kind ? { kind: e.kind } : {}),
+        ...(e.overlap_files ? { overlap_files: [...e.overlap_files].sort() } : {}),
+    }))
         .sort((a, b) => {
         const cmp = a.from.localeCompare(b.from);
         return cmp !== 0 ? cmp : a.to.localeCompare(b.to);

package/build/conductor/pr-ci-producer.js

@@ -23,6 +23,11 @@ async function _fetchGateConfigDefault(access) {
 }
 import { resolvePrHeadBinding } from "./pr-discovery.js";
 import { emitConductorEventIfNew } from "./producer-ledger.js";
+// In-process ledger writer — the DEFAULT emit sink for conductor-OWNED paths
+// (the CLI/supervisor/epic runtimes that legitimately own the better-sqlite3
+// load). The worker `wait_for_done_gate` MCP path injects a CLI-subprocess emitter
+// instead (BAPI-527) so the worker Node never loads the native binary.
+import { emitConductorEvent as emitConductorEventInProcess } from "./store.js";
 const PRODUCER_OBSERVED_VIA = "pr-ci-producer";
 /** Bounded wait constants, consistent with the existing wait_for_event pattern. */
 export const WAIT_FOR_GATE_TIMEOUT_MAX_MS = 120_000;
@@ -124,7 +129,15 @@ function defaultSleep(ms) {
  * resolved exactly once by the caller.
  */
 async function observeWithResolved(binding, access, gateConfig, deps) {
-    const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
+    // The event-WRITE sink defaults to the in-process store; the worker gate path
+    // injects a CLI-subprocess emitter (BAPI-527). When a caller supplies its own
+    // `emitIfNew` (e.g. unit tests / conductor-owned callers), that fully overrides
+    // this and the injected write sink is not consulted.
+    const emitConductorEventFn = deps.emitConductorEvent ?? emitConductorEventInProcess;
+    const emitIfNew = deps.emitIfNew ??
+        ((input, dimensions) => emitConductorEventIfNew(input, dimensions, {
+            emitEvent: emitConductorEventFn,
+        }));
     const pollCi = deps.pollCi ?? pollCiChecksForCommit;
     const now = deps.now ?? (() => new Date().toISOString());
     // Resolve run_id/worker_id for attribution. Env takes precedence; fall back
@@ -193,7 +206,9 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
     let reviewSnapshot = null;
     try {
         const reviewObservation = await observeReviewWithResolved(binding, access, gateConfig, {
-            emitIfNew: deps.emitIfNew ?? emitConductorEventIfNew,
+            // Reuse the resolved `emitIfNew` so review-state events emitted alongside CI
+            // route through the SAME (possibly CLI-subprocess) write sink (BAPI-527).
+            emitIfNew,
             env: deps.env,
         });
         reviewSnapshot = reviewObservation.snapshot;

package/build/conductor/pr-discovery.js

@@ -11,6 +11,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { normalizePrNumber, normalizeRepoName, normalizeSha } from "./git-ci-types.js";
+import { parseGhPrMergeabilityFields } from "./github-mergeability.js";
 import { getGitWorktreeContext } from "./git-inspection.js";
 /** Bounded timeout for the one-shot `gh` lookup. */
 export const GH_COMMAND_TIMEOUT_MS = 5_000;
@@ -30,7 +31,13 @@ export function runGhCommand(args, options = {}) {
         return { ok: false, stdout: "" };
     }
 }
-const GH_PR_VIEW_ARGS = ["pr", "view", "--json", "number,headRefOid,headRefName,url,state"];
+const GH_PR_VIEW_ARGS = [
+    "pr",
+    "view",
+    "--json",
+    // BAPI-494: mergeability fields added to the SAME one-shot call — no new gh process.
+    "number,headRefOid,headRefName,url,state,mergeable,mergeStateStatus",
+];
 /**
  * Perform a one-shot `gh pr view` lookup for the current branch's PR. Returns a
  * normalized {@link DiscoveredPr} or `null` when gh is unavailable, there is no
@@ -55,10 +62,13 @@ export function discoverPrWithGhCli(options = {}, deps = {}) {
     const state = typeof record.state === "string" ? record.state : "";
     if (number === null || state.length === 0)
         return null;
+    const mergeability = parseGhPrMergeabilityFields(record);
     const discovered = {
         number,
         head_sha: normalizeSha(record.headRefOid),
         state,
+        mergeable: mergeability.mergeable,
+        mergeStateStatus: mergeability.mergeStateStatus,
     };
     if (typeof record.headRefName === "string" && record.headRefName.trim().length > 0) {
         discovered.head_ref = record.headRefName.trim();

package/build/conductor/producer-ledger.js

@@ -37,7 +37,7 @@ export function makeStableProducerEventId(dedupeKey) {
     return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
 }
 /** Heuristically detect a SQLite duplicate-id / UNIQUE constraint failure. */
-function isDuplicateConstraintError(error) {
+export function isDuplicateConstraintError(error) {
     if (!error || typeof error !== "object")
         return false;
     const code = error.code;

package/build/conductor/store.js

@@ -38,6 +38,68 @@ export class ConductorPersistenceUnavailableError extends Error {
         this.name = "ConductorPersistenceUnavailableError";
     }
 }
+/** The native module whose load status this store owns. */
+const LEDGER_NATIVE_MODULE_NAME = "better-sqlite3";
+/**
+ * Thrown when `better-sqlite3` is present but fails to LOAD for this Node runtime
+ * (ABI/`NODE_MODULE_VERSION` mismatch or a generic `dlopen` failure) — distinct
+ * from "module simply not installed", which stays on the base
+ * {@link ConductorPersistenceUnavailableError} (503) path. Subclassing the base
+ * keeps existing `instanceof`/name-based degradation working while carrying the
+ * structured, secret-free {@link ConductorNativeModuleLoadDetails}. The raw
+ * caught error, stack, path, and message are deliberately NOT stored on the
+ * public instance.
+ */
+export class ConductorNativeModuleLoadError extends ConductorPersistenceUnavailableError {
+    details;
+    failureKind;
+    constructor(failureKind, details) {
+        super("Conductor ledger native module failed to load for this Node runtime.");
+        this.name = "ConductorNativeModuleLoadError";
+        this.failureKind = failureKind;
+        this.details = details;
+    }
+}
+/** Build the allowlisted runtime details for the CURRENT process. */
+export function buildNativeModuleLoadDetails() {
+    return {
+        node_version: process.version,
+        node_modules_abi: process.versions.modules ?? "unknown",
+        module: LEDGER_NATIVE_MODULE_NAME,
+    };
+}
+/**
+ * Classify a caught `better-sqlite3` load failure. Inspects ONLY the error `code`
+ * and `message` locally; the raw text never leaves this helper.
+ *
+ *   - `MODULE_NOT_FOUND` / `ERR_MODULE_NOT_FOUND` -> base
+ *     {@link ConductorPersistenceUnavailableError} ("not installed", 503).
+ *   - `NODE_MODULE_VERSION` / "compiled against a different Node.js version" /
+ *     "module version mismatch" -> native-load `abi_mismatch`.
+ *   - `ERR_DLOPEN_FAILED` / generic `dlopen` -> native-load `dlopen_failed`.
+ *   - Anything else -> base {@link ConductorPersistenceUnavailableError}.
+ */
+export function classifyDatabaseModuleLoadFailure(error) {
+    const code = error && typeof error === "object" ? error.code : undefined;
+    const rawMessage = error && typeof error === "object" && typeof error.message === "string"
+        ? (error.message)
+        : "";
+    const lowered = rawMessage.toLowerCase();
+    if (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") {
+        return new ConductorPersistenceUnavailableError();
+    }
+    const isAbiMismatch = lowered.includes("node_module_version") ||
+        lowered.includes("compiled against a different node.js version") ||
+        lowered.includes("module version mismatch");
+    if (isAbiMismatch) {
+        return new ConductorNativeModuleLoadError("abi_mismatch", buildNativeModuleLoadDetails());
+    }
+    const isDlopen = code === "ERR_DLOPEN_FAILED" || lowered.includes("dlopen");
+    if (isDlopen) {
+        return new ConductorNativeModuleLoadError("dlopen_failed", buildNativeModuleLoadDetails());
+    }
+    return new ConductorPersistenceUnavailableError();
+}
 /**
  * Cached, concurrency-safe async loader for the optional `better-sqlite3` module.
  *
@@ -50,13 +112,21 @@ export class ConductorPersistenceUnavailableError extends Error {
  * warning is emitted exactly once and every subsequent call throws
  * {@link ConductorPersistenceUnavailableError} immediately, without re-attempting the
  * failing import on every Conductor operation.
+ *
+ * BAPI-526: the caught error is CLASSIFIED (not swallowed) into a TYPED failure —
+ * ABI/dlopen mismatches become {@link ConductorNativeModuleLoadError} carrying
+ * `node_version`/`node_modules_abi`, while "module not installed" stays the base
+ * {@link ConductorPersistenceUnavailableError}. That typed failure is cached and
+ * re-thrown on every later call so the classification is never lost.
  */
 let databaseModulePromise = null;
-let dbLoadDegraded = false;
+let dbLoadFailure = null;
+let dbLoadDiagnosticEmitted = false;
 async function getDatabaseModule() {
-    // Cached degraded state: never re-attempt a known-failing native import.
-    if (dbLoadDegraded) {
-        throw new ConductorPersistenceUnavailableError();
+    // Cached typed failure: never re-attempt a known-failing native import, and
+    // preserve the ABI/dlopen classification across every subsequent call.
+    if (dbLoadFailure) {
+        throw dbLoadFailure;
     }
     if (databaseModulePromise)
         return databaseModulePromise;
@@ -67,13 +137,25 @@ async function getDatabaseModule() {
             const ctor = (mod.default ?? mod);
             return ctor;
         }
-        catch {
-            if (!dbLoadDegraded) {
-                dbLoadDegraded = true;
-                console.error("[conductor] Conductor persistence is unavailable: the optional 'better-sqlite3' native module could not be loaded. " +
+        catch (err) {
+            const classified = classifyDatabaseModuleLoadFailure(err);
+            dbLoadFailure = classified;
+            // Drop the rejected promise so the typed `dbLoadFailure` above is the sole
+            // cached state (the rejected promise itself must not be the only record).
+            databaseModulePromise = null;
+            if (!dbLoadDiagnosticEmitted) {
+                dbLoadDiagnosticEmitted = true;
+                // Fixed, path-free, secret-free diagnostic: module name, current Node
+                // version, current ABI, and coarse failure kind ONLY. Never the raw
+                // dlopen path, stack, or caught message.
+                const kind = classified instanceof ConductorNativeModuleLoadError
+                    ? classified.failureKind
+                    : "unavailable";
+                console.error(`[conductor] ${LEDGER_NATIVE_MODULE_NAME} native module could not be loaded ` +
+                    `(node=${process.version} abi=${process.versions.modules ?? "unknown"} kind=${kind}). ` +
                     "Conductor coordination features are disabled for this session; core MCP tools are unaffected.");
             }
-            throw new ConductorPersistenceUnavailableError();
+            throw classified;
         }
     })();
     return databaseModulePromise;
@@ -183,11 +265,15 @@ export function resolveConductorStoreConfig(env = process.env) {
  * CHECK vocabulary. Bumped to 7 because the durable parse-after-merge fold adds
  * the `parse.triggered` event type to the same `events.type` CHECK vocabulary
  * (replacing the in-memory parse-wait map so stateless epic-tick invocations can
- * fold a merged ticket to `done`). Older ledgers stamped at a lower version are
- * rebuilt by {@link migrateConductorSchemaIfNeeded} so their CHECK clause accepts
- * the current taxonomy.
+ * fold a merged ticket to `done`). Bumped to 8 in BAPI-527 because the durable
+ * parse-after-merge TERMINAL fold adds the `parse.succeeded` and `parse.failed`
+ * event types to the same `events.type` CHECK vocabulary (so the stateless
+ * epic-tick can fold a merged ticket to `done` on terminal parse success and
+ * `blocked` on permanent parse failure directly from the ledger). Older ledgers
+ * stamped at a lower version are rebuilt by {@link migrateConductorSchemaIfNeeded}
+ * so their CHECK clause accepts the current taxonomy.
  */
-export const CURRENT_CONDUCTOR_SCHEMA_VERSION = 7;
+export const CURRENT_CONDUCTOR_SCHEMA_VERSION = 8;
 /** Render the taxonomy `CHECK (type IN (...))` clause from the single source of truth. */
 function buildTypeCheckClause() {
     const list = SEMANTIC_EVENT_TYPES.map((t) => `'${t}'`).join(", ");
@@ -327,15 +413,15 @@ export function migrateConductorSchemaIfNeeded(db) {
         return;
     }
     const migrate = db.transaction(() => {
-        // Scratch table named for the current schema version (v4, BAPI-398) so the
-        // migration rebuild never reads as a stale pre-merge-taxonomy artifact.
-        db.exec(buildEventsTableSql("events_migrated_v5"));
-        db.exec(`INSERT INTO events_migrated_v5
+        // Scratch table named for the current schema version (v8, BAPI-527) so the
+        // migration rebuild never reads as a stale pre-parse-terminal-taxonomy artifact.
+        db.exec(buildEventsTableSql("events_migrated_v8"));
+        db.exec(`INSERT INTO events_migrated_v8
          (seq, id, source, type, subject, run_id, worker_id, producer, schema_version, time, data_json, confidence, observed_via, created_at)
        SELECT seq, id, source, type, subject, run_id, worker_id, producer, schema_version, time, data_json, confidence, observed_via, created_at
        FROM events`);
         db.exec("DROP TABLE events");
-        db.exec("ALTER TABLE events_migrated_v5 RENAME TO events");
+        db.exec("ALTER TABLE events_migrated_v8 RENAME TO events");
         db.exec(buildEventsIndexesSql());
         // Ensure auxiliary tables and their relay indexes exist on older ledgers too.
         db.exec(buildAuxiliaryTablesSql());
@@ -818,6 +904,56 @@ export async function upsertSupervisorProjection(input, config = resolveConducto
  * and network-home degradation. Never creates the DB, inserts a diagnostic
  * event, or mutates WAL/schema state.
  */
+/**
+ * Read-only probe of whether the ledger native binding actually loads for this
+ * Node runtime (BAPI-526). Reuses the lazy loader so it reflects the REAL load
+ * outcome, and NEVER opens the SQLite database, runs migrations, creates files,
+ * or emits events. On success reports `loads: true`; on a native-load failure
+ * reports the coarse `failure_kind` and marks the host degraded. All returned
+ * fields are secret-free and path-free.
+ */
+export async function inspectConductorLedgerNativeModuleLoad() {
+    const details = buildNativeModuleLoadDetails();
+    try {
+        await getDatabaseModule();
+        return {
+            module: details.module,
+            node_version: details.node_version,
+            node_modules_abi: details.node_modules_abi,
+            loads: true,
+            failure_kind: "none",
+            degraded: false,
+            warning: null,
+        };
+    }
+    catch (err) {
+        if (err instanceof ConductorNativeModuleLoadError) {
+            return {
+                ...err.details,
+                loads: false,
+                failure_kind: err.failureKind,
+                degraded: true,
+                warning: "better-sqlite3 failed to load for this Node runtime; conductor ledger operations are degraded.",
+            };
+        }
+        if (err instanceof ConductorPersistenceUnavailableError) {
+            return {
+                ...details,
+                loads: false,
+                failure_kind: "module_not_found",
+                degraded: true,
+                warning: "better-sqlite3 is not installed; conductor ledger operations are unavailable.",
+            };
+        }
+        return {
+            ...details,
+            loads: false,
+            failure_kind: "unknown",
+            degraded: true,
+            warning: "better-sqlite3 could not be loaded; conductor ledger operations are degraded.",
+        };
+    }
+}
 export async function doctorConductorLedger(config = resolveConductorStoreConfig()) {
     const health = getConductorPathHealth();
     const network = detectNetworkMountedHome();
@@ -825,6 +961,12 @@ export async function doctorConductorLedger(config = resolveConductorStoreConfig
     if (network.network_mounted && network.warning) {
         warnings.push(network.warning);
     }
+    // Read-only native-binding load probe (BAPI-526). Reflects the real lazy-loader
+    // outcome; never opens/creates/migrates the ledger.
+    const native_load = await inspectConductorLedgerNativeModuleLoad();
+    if (native_load.degraded && native_load.warning) {
+        warnings.push(native_load.warning);
+    }
     let schemaPresent = false;
     let journalMode = null;
     let eventCount = null;
@@ -873,6 +1015,7 @@ export async function doctorConductorLedger(config = resolveConductorStoreConfig
         message_relay: {
             message_cooldown_ms: config.message_cooldown_ms,
         },
+        native_load,
         degraded: network.network_mounted,
         warnings,
     };