claude-flow 3.47.1 → 3.48.0

package/v3/@claude-flow/cli/dist/src/memory/memory-bridge.js

@@ -16,9 +16,13 @@
  *
  * @module v3/cli/memory-bridge
  */
+import { liveMemoryRowSql } from './live-memory-row.js';
 import * as path from 'path';
 import * as crypto from 'crypto';
+import { realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { validateFeedbackPatterns } from './feedback-patterns.js';
 // ===== Lazy registry cache, keyed by database path =====
 /**
  * #3196: this cache is keyed by resolved database path, and that is the whole
@@ -37,6 +41,33 @@ import { createRequire } from 'node:module';
  */
 const registryPromises = new Map();
 const registryInstances = new Map();
+// One lease spans an entire bridge operation, including its awaited controller
+// effects and nested bridge calls. Initializer ownership alone is insufficient:
+// a ReasoningBank write can still be pending after its registry has opened.
+const operationContext = new AsyncLocalStorage();
+let activeOperations = 0;
+let drained = null;
+let shutdownPromise = null;
+async function withBridgeOperation(operation) {
+    if (operationContext.getStore()?.active)
+        return operation();
+    // New calls belong to the next lifecycle once retirement starts. A loop
+    // also handles another shutdown requested before a queued call resumes.
+    while (shutdownPromise)
+        await shutdownPromise;
+    const lease = { active: true };
+    activeOperations++;
+    try {
+        return await operationContext.run(lease, operation);
+    }
+    finally {
+        lease.active = false;
+        if (--activeOperations === 0) {
+            drained?.();
+            drained = null;
+        }
+    }
+}
 /**
  * Test seam: when set, every path resolves to this registry.
  *
@@ -46,22 +77,36 @@ const registryInstances = new Map();
  * pass the same path the seam guessed, which is how #2968's fixture broke.
  */
 let testRegistryOverride = null;
-let bridgeAvailable = null;
+let testRegistryFactory = null;
 // #2652/#2120: rows created before the status column existed receive NULL
 // during migration. They are live rows, not tombstones. Every user-facing
 // read/delete path must agree with list() about their visibility.
 const ACTIVE_MEMORY_ROW_SQL = `(status = 'active' OR status IS NULL)`;
 /**
- * Why the bridge is unavailable, when it is.
- *
- * `bridgeAvailable = false` latches for the life of the process, so a single
- * transient init failure (a slow Xenova/ONNX fetch, a locked db) routes every
- * later write to the sql.js whole-image fallback — which then refuses whenever
- * -wal/-shm sidecars are present. Without this, that refusal is the only
- * symptom the caller ever sees, and it names a cause ("restore the native
- * better-sqlite3 bridge") the caller has no way to check.
+ * A failed open must only affect its own database. A process can serve several
+ * projects, and an error from one must not disable the native bridge for all.
  */
-let bridgeFailureReason = null;
+const bridgeFailureReasons = new Map();
+/** Resolve aliases even when the database file or some parent dirs do not exist yet. */
+function canonicalDbPath(dbPath) {
+    const resolved = dbPath === ':memory:' ? ':memory:' : path.resolve(dbPath ?? getAgentDbPath());
+    if (resolved === ':memory:')
+        return resolved;
+    let ancestor = resolved;
+    const suffix = [];
+    for (;;) {
+        try {
+            return path.join(realpathSync(ancestor), ...suffix);
+        }
+        catch {
+            const parent = path.dirname(ancestor);
+            if (parent === ancestor)
+                return resolved;
+            suffix.unshift(path.basename(ancestor));
+            ancestor = parent;
+        }
+    }
+}
 /**
  * #3024: AgentDB's optional native controller stack can abort the whole Node
  * process on Windows during registry initialization (a Rust allocation panic),
@@ -190,29 +235,24 @@ export function shouldSuppressInitLog(msg) {
  * Returns null if @claude-flow/memory is not available.
  */
 async function getRegistry(dbPath) {
-    if (shouldDisableNativeBridge()) {
-        bridgeFailureReason = process.platform === 'win32'
-            ? 'AgentDB native bridge disabled on Windows after #3024; set CLAUDE_FLOW_ENABLE_NATIVE_BRIDGE_ON_WINDOWS=1 to opt in'
-            : 'AgentDB native bridge disabled by CLAUDE_FLOW_DISABLE_BRIDGE=1';
+    if (shouldDisableNativeBridge())
         return null;
-    }
     if (testRegistryOverride)
         return testRegistryOverride;
-    if (bridgeAvailable === false)
-        return null;
-    // Resolve first, then cache on the resolved value: `undefined`, a relative
-    // path and its absolute form must not become three different registries over
-    // the same file.
-    const resolvedPath = dbPath ? path.resolve(dbPath) : getAgentDbPath();
+    // Resolve before caching: relative, absolute and symlink paths to one file
+    // must not open multiple native handles to the same database.
+    const resolvedPath = canonicalDbPath(dbPath);
     const cached = registryInstances.get(resolvedPath);
     if (cached)
         return cached;
     let registryPromise = registryPromises.get(resolvedPath);
     if (!registryPromise) {
         registryPromise = (async () => {
+            let registry;
             try {
-                const { ControllerRegistry } = await import('@claude-flow/memory');
-                const registry = new ControllerRegistry();
+                registry = testRegistryFactory
+                    ? testRegistryFactory()
+                    : new (await import('@claude-flow/memory')).ControllerRegistry();
                 // Suppress noisy console.log during init — but never suppress a
                 // DEGRADATION notice (see shouldSuppressInitLog).
                 const origLog = console.log;
@@ -289,11 +329,13 @@ async function getRegistry(dbPath) {
                         catch {
                             return; /* AgentDB not available */
                         }
-                        // SkillLibrary (no db required)
+                        // SkillLibrary requires the same database and passage embedder as AgentDB.
                         try {
                             const SkillCtor = agentdb.SkillLibrary;
-                            if (SkillCtor && !reg.get('skills')) {
-                                const sk = new SkillCtor();
+                            const backing = reg.getAgentDB?.();
+                            if (SkillCtor && !reg.get('skills') && backing?.database
+                                && typeof backing.embedder?.embedPassage === 'function') {
+                                const sk = new SkillCtor(backing.database, backing.embedder);
                                 if (typeof reg.set === 'function')
                                     reg.set('skills', sk);
                                 else
@@ -473,17 +515,18 @@ async function getRegistry(dbPath) {
                     // Top-level catch — registry stays usable even if post-init wiring fails wholesale.
                 }
                 registryInstances.set(resolvedPath, registry);
-                bridgeAvailable = true;
-                bridgeFailureReason = null;
+                bridgeFailureReasons.delete(resolvedPath);
                 return registry;
             }
             catch (err) {
-                // Record WHY. This latches for the process lifetime (see the
-                // bridgeFailureReason doc comment), so discarding the error here
-                // makes the resulting sql.js-fallback refusal undiagnosable.
-                bridgeFailureReason = err instanceof Error ? err.message : String(err);
-                bridgeAvailable = false;
-                registryPromises.delete(resolvedPath);
+                // initialize() may have opened a native handle before it failed.
+                try {
+                    await registry?.shutdown();
+                }
+                catch { /* best-effort cleanup */ }
+                // Keep the failed promise for this path only. Other databases can
+                // still initialize; shutdownBridge() clears the latch for a retry.
+                bridgeFailureReasons.set(resolvedPath, err instanceof Error ? err.message : String(err));
                 return null;
             }
         })();
@@ -496,8 +539,12 @@ export function _resetRegistryCacheForTest() {
     registryPromises.clear();
     registryInstances.clear();
     testRegistryOverride = null;
-    bridgeAvailable = null;
-    bridgeFailureReason = null;
+    testRegistryFactory = null;
+    bridgeFailureReasons.clear();
+}
+/** Inject registry construction without requiring the optional native package in tests. */
+export function __setMemoryBridgeRegistryFactoryForTests(factory) {
+    testRegistryFactory = factory;
 }
 /** #3196: the sibling store AgentDB owns next to a given sql.js database. */
 export function siblingAgentDbPath(dbPath) {
@@ -550,6 +597,10 @@ function computeTermDocFreqs(queryTerms, docs) {
     return { termDocFreqs, avgDocLength: docs.length > 0 ? totalLength / docs.length : 1 };
 }
 // ===== Phase 2: TieredCache helpers =====
+/** Preserve the exact namespace/key tuple; punctuation is valid memory data. */
+function entryCacheKey(namespace, key) {
+    return `entry:${JSON.stringify([namespace, key])}`;
+}
 /**
  * Try to read from TieredCache before hitting DB.
  * Returns cached value or null if cache miss.
@@ -774,6 +825,15 @@ export function ensureBridgeSchema(db) {
                 throw err;
             }
         }
+        // Reads now enforce TTL, including on stores created before expires_at
+        // existed. A missing expiration means the legacy row does not expire.
+        try {
+            db.exec('ALTER TABLE memory_entries ADD COLUMN expires_at INTEGER');
+        }
+        catch (error) {
+            if (!/duplicate column name:\s*expires_at/i.test(error instanceof Error ? error.message : String(error)))
+                throw error;
+        }
         db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_ns ON memory_entries(namespace)`);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_key ON memory_entries(key)`);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_status ON memory_entries(status)`);
@@ -884,6 +944,11 @@ async function rescueAgentdbEmbedder(agentdb) {
     emb.__ruvectorRescued = true;
     _embedderPatched = true;
 }
+/** AgentDB uses a null pipeline while its transformer failed and it serves mock vectors. */
+function isMockAgentdbEmbedder(embedder) {
+    return embedder?.isMock === true || embedder?.backend === 'mock'
+        || (embedder?.pipeline === null && embedder.__ruvectorRescued !== true);
+}
 /**
  * #3325: embed text for a bridge row or query.
  *
@@ -899,7 +964,9 @@ async function embedForBridge(agentdb, text) {
     const embedder = agentdb?.embedder;
     // Same mock signal bridgeGenerateEmbedding honours (AUDIT #3): the rescue
     // tags a degraded embedder backend='mock' when it cannot replace it.
-    const agentdbIsMock = embedder?.isMock === true || embedder?.backend === 'mock';
+    // The rescue launched by getDb() is fire-and-forget. Do not persist mock
+    // vectors during that window just because they happen to be 384-dimension.
+    const agentdbIsMock = isMockAgentdbEmbedder(embedder);
     if (agentdbIsMock) {
         agentdbProblem = 'agentdb embedder is serving mock vectors';
     }
@@ -937,6 +1004,8 @@ async function embedForBridge(agentdb, text) {
  * Returns null to signal fallback to sql.js.
  */
 export async function bridgeStoreEntry(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeStoreEntry(options));
     // ADR-323 — validated once in storeEntry() before this is reached on that
     // path, but bridgeStoreEntry() also has direct internal callers, so check
     // again here rather than trust every call site.
@@ -1058,7 +1127,7 @@ export async function bridgeStoreEntry(options) {
         // A completed native write proves the bridge is currently healthy. Do not
         // retain a diagnostic from an earlier transient failure and append it to a
         // later, unrelated sql.js fallback refusal.
-        bridgeFailureReason = null;
+        bridgeFailureReasons.delete(canonicalDbPath(options.dbPath));
         // #2775: strict insert against an ACTIVE existing row → changes === 0
         // (the ON CONFLICT WHERE clause above suppressed the update). Surface
         // this as a typed data-level error rather than a bridge failure —
@@ -1123,9 +1192,7 @@ export async function bridgeStoreEntry(options) {
         // next `bridgeGetEntry` to load the authoritative row (which correctly
         // parses tags/metadata from the JSON columns) and repopulate the cache
         // from that full shape.
-        const safeNs = String(namespace).replace(/:/g, '_');
-        const safeKey = String(key).replace(/:/g, '_');
-        const cacheKey = `entry:${safeNs}:${safeKey}`;
+        const cacheKey = entryCacheKey(namespace, key);
         await cacheInvalidate(registry, cacheKey);
         // Phase 4: AttestationLog write audit
         await logAttestation(registry, 'store', id, { key, namespace, hasEmbedding: !!embeddingJson });
@@ -1164,7 +1231,7 @@ export async function bridgeStoreEntry(options) {
         // whose WAL-sidecar guard then reports a cause that has nothing to do with
         // what actually went wrong here. Record the real error so it can be
         // surfaced alongside that guard's message.
-        bridgeFailureReason = msg;
+        bridgeFailureReasons.set(canonicalDbPath(options.dbPath), msg);
         return null;
     }
 }
@@ -1174,6 +1241,8 @@ export async function bridgeStoreEntry(options) {
  * Combines cosine similarity (semantic) with BM25 (lexical) via reciprocal rank fusion.
  */
 export async function bridgeSearchEntries(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeSearchEntries(options));
     if (options.provenanceFilter?.length) {
         const invalid = options.provenanceFilter.filter(p => !isValidProvenanceType(p));
         if (invalid.length > 0)
@@ -1217,7 +1286,7 @@ export async function bridgeSearchEntries(options) {
             const stmt = ctx.db.prepare(`
         SELECT id, key, namespace, content, embedding, provenance_type
         FROM memory_entries
-        WHERE ${ACTIVE_MEMORY_ROW_SQL} ${whereExtra}
+        WHERE ${liveMemoryRowSql()} ${whereExtra}
         ORDER BY updated_at DESC
         LIMIT 1000
       `);
@@ -1309,6 +1378,8 @@ export async function bridgeSearchEntries(options) {
  * List entries via AgentDB v3.
  */
 export async function bridgeListEntries(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeListEntries(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -1338,7 +1409,7 @@ export async function bridgeListEntries(options) {
         // the `status = 'active'` filter matched zero. Treat NULL as
         // "legacy-active" — the safe default for any entry that predates the
         // status column.
-        const statusFilter = ACTIVE_MEMORY_ROW_SQL;
+        const statusFilter = liveMemoryRowSql();
         // Count
         let total = 0;
         try {
@@ -1394,6 +1465,8 @@ export async function bridgeListEntries(options) {
  * Phase 2: TieredCache consulted before DB hit.
  */
 export async function bridgeGetEntry(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeGetEntry(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -1403,12 +1476,10 @@ export async function bridgeGetEntry(options) {
     try {
         const { key, namespace = 'default' } = options;
         // Phase 2: Check TieredCache first
-        const safeNs = String(namespace).replace(/:/g, '_');
-        const safeKey = String(key).replace(/:/g, '_');
-        const cacheKey = `entry:${safeNs}:${safeKey}`;
+        const cacheKey = entryCacheKey(namespace, key);
         dropCacheIfDbChangedElsewhere(registry, ctx);
         const cached = await cacheGet(registry, cacheKey);
-        if (cached && cached.content) {
+        if (cached && cached.content && (cached.expiresAt == null || cached.expiresAt > Date.now())) {
             return {
                 success: true,
                 found: true,
@@ -1432,9 +1503,9 @@ export async function bridgeGetEntry(options) {
         let row;
         try {
             const stmt = ctx.db.prepare(`
-        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, tags
+        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, tags, expires_at
         FROM memory_entries
-        WHERE ${ACTIVE_MEMORY_ROW_SQL} AND key = ? AND namespace = ?
+        WHERE ${liveMemoryRowSql()} AND key = ? AND namespace = ?
         LIMIT 1
       `);
             row = stmt.get(key, namespace);
@@ -1471,7 +1542,7 @@ export async function bridgeGetEntry(options) {
             tags,
         };
         // Phase 2: Populate cache for next read
-        await cacheSet(registry, cacheKey, entry);
+        await cacheSet(registry, cacheKey, { ...entry, expiresAt: row.expires_at });
         return { success: true, found: true, cacheHit: false, entry };
     }
     catch {
@@ -1483,6 +1554,8 @@ export async function bridgeGetEntry(options) {
  * Phase 5: MutationGuard validation, cache invalidation, attestation logging.
  */
 export async function bridgeDeleteEntry(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeDeleteEntry(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -1525,9 +1598,7 @@ export async function bridgeDeleteEntry(options) {
         }
         catch { /* non-WAL, busy, or unsupported — non-fatal */ }
         // Phase 2: Invalidate cache
-        const safeNs = String(namespace).replace(/:/g, '_');
-        const safeKey = String(key).replace(/:/g, '_');
-        await cacheInvalidate(registry, `entry:${safeNs}:${safeKey}`);
+        await cacheInvalidate(registry, entryCacheKey(namespace, key));
         // Phase 4: AttestationLog delete audit
         if (changes > 0) {
             await logAttestation(registry, 'delete', key, { namespace });
@@ -1560,6 +1631,8 @@ export async function bridgeDeleteEntry(options) {
 // step) that need a namespace to be genuinely empty rather than tombstoned.
 // Irreversible — callers must gate this behind an explicit confirmation.
 export async function bridgePurgeNamespace(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgePurgeNamespace(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -1580,8 +1653,15 @@ export async function bridgePurgeNamespace(options) {
         catch (e) {
             return { success: false, deletedCount: 0, remainingEntries: 0, error: e instanceof Error ? e.message : String(e) };
         }
-        const safeNs = String(namespace).replace(/:/g, '_');
-        await cacheInvalidate(registry, `namespace:${safeNs}`);
+        // Entries are cached individually, not under a namespace sentinel.
+        // SQLite data_version does not change for writes on this connection, so
+        // the cross-process freshness check cannot invalidate this purge for us.
+        try {
+            const cache = registry.get('tieredCache');
+            if (cache && typeof cache.clear === 'function')
+                await cache.clear();
+        }
+        catch { /* cache cleanup is best-effort */ }
         if (deletedCount > 0) {
             await logAttestation(registry, 'purge', namespace, { namespace, deletedCount });
         }
@@ -1610,13 +1690,15 @@ export async function bridgePurgeNamespace(options) {
  * Returns null if bridge unavailable — caller falls back to own ONNX/hash.
  */
 export async function bridgeGenerateEmbedding(text, dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeGenerateEmbedding(text, dbPath));
     const registry = await getRegistry(dbPath);
     if (!registry)
         return null;
     try {
         const agentdb = registry.getAgentDB();
         const embedder = agentdb?.embedder;
-        if (!embedder)
+        if (!embedder || isMockAgentdbEmbedder(embedder))
             return null;
         const emb = await embedder.embed(text);
         if (!emb)
@@ -1653,6 +1735,8 @@ export async function bridgeGenerateEmbedding(text, dbPath) {
  * Returns null if unavailable.
  */
 export async function bridgeLoadEmbeddingModel(dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeLoadEmbeddingModel(dbPath));
     const startTime = Date.now();
     const registry = await getRegistry(dbPath);
     if (!registry)
@@ -1660,7 +1744,7 @@ export async function bridgeLoadEmbeddingModel(dbPath) {
     try {
         const agentdb = registry.getAgentDB();
         const embedder = agentdb?.embedder;
-        if (!embedder)
+        if (!embedder || isMockAgentdbEmbedder(embedder))
             return null;
         // Verify embedder works by generating a test embedding
         const test = await embedder.embed('test');
@@ -1690,6 +1774,8 @@ export async function bridgeLoadEmbeddingModel(dbPath) {
  * search works" for "vector search is HNSW-accelerated".
  */
 export async function bridgeGetVectorSearchStatus(dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeGetVectorSearchStatus(dbPath));
     const registry = await getRegistry(dbPath);
     if (!registry)
         return null;
@@ -1724,6 +1810,8 @@ export async function bridgeGetVectorSearchStatus(dbPath) {
  * null if unavailable.
  */
 export async function bridgeSearchBruteForceCosine(queryEmbedding, options, dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeSearchBruteForceCosine(queryEmbedding, options, dbPath));
     const registry = await getRegistry(dbPath);
     if (!registry)
         return null;
@@ -1744,7 +1832,7 @@ export async function bridgeSearchBruteForceCosine(queryEmbedding, options, dbPa
             const stmt = ctx.db.prepare(`
         SELECT id, key, namespace, content, embedding
         FROM memory_entries
-        WHERE status = 'active' AND embedding IS NOT NULL ${nsFilter}
+        WHERE ${liveMemoryRowSql()} AND embedding IS NOT NULL ${nsFilter}
         ORDER BY updated_at DESC
         LIMIT 10000
       `);
@@ -1790,6 +1878,8 @@ export async function bridgeSearchBruteForceCosine(queryEmbedding, options, dbPa
  * brute-force scan. Returns null if unavailable.
  */
 export async function bridgeAddEmbedding(id, embedding, entry, dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeAddEmbedding(id, embedding, entry, dbPath));
     const registry = await getRegistry(dbPath);
     if (!registry)
         return null;
@@ -1828,9 +1918,12 @@ export async function bridgeAddEmbedding(id, embedding, entry, dbPath) {
 // ===== Phase 4: Controller access =====
 /**
  * Get a named controller from AgentDB v3 via ControllerRegistry.
+ * This borrowed handle must not be retained across shutdownBridge().
  * Returns null if unavailable.
  */
 export async function bridgeGetController(name, dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeGetController(name, dbPath));
     const registry = await getRegistry(dbPath);
     if (!registry)
         return null;
@@ -1845,6 +1938,8 @@ export async function bridgeGetController(name, dbPath) {
  * Check if a controller is available.
  */
 export async function bridgeHasController(name, dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeHasController(name, dbPath));
     const registry = await getRegistry(dbPath);
     if (!registry)
         return false;
@@ -1860,6 +1955,8 @@ export async function bridgeHasController(name, dbPath) {
  * List all controllers and their status.
  */
 export async function bridgeListControllers(dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeListControllers(dbPath));
     const registry = await getRegistry(dbPath);
     if (!registry)
         return null;
@@ -1874,22 +1971,26 @@ export async function bridgeListControllers(dbPath) {
  * Check if the AgentDB v3 bridge is available.
  */
 export async function isBridgeAvailable(dbPath) {
-    if (bridgeAvailable !== null)
-        return bridgeAvailable;
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => isBridgeAvailable(dbPath));
     const registry = await getRegistry(dbPath);
     return registry !== null;
 }
 /**
  * Get the ControllerRegistry instance (for advanced consumers).
+ * This is a borrowed handle, valid only until shutdownBridge(). Callers must
+ * finish using it before requesting shutdown; bridge operations own their own
+ * leases. Prefer bridgeListControllers() for status inspection.
  */
 export async function getControllerRegistry(dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => getControllerRegistry(dbPath));
     return getRegistry(dbPath);
 }
 /**
  * Why the bridge last declined a write, or null when it has not.
  *
- * Deliberately NOT gated on `bridgeAvailable === false`. A bridge that
- * initialised fine can still fail every write — a schema mismatch throws
+ * A bridge that initialised fine can still fail every write — a schema mismatch throws
  * per-operation while the registry stays healthy — and that case is exactly
  * the one worth reporting, since the caller then demotes to a fallback whose
  * error message describes something else entirely.
@@ -1897,8 +1998,13 @@ export async function getControllerRegistry(dbPath) {
  * Callers that surface a degraded-path error should include this so the
  * operator learns the cause instead of only the symptom.
  */
-export function getBridgeFailureReason() {
-    return bridgeFailureReason;
+export function getBridgeFailureReason(dbPath) {
+    if (shouldDisableNativeBridge()) {
+        return process.platform === 'win32'
+            ? 'AgentDB native bridge disabled on Windows after #3024; set CLAUDE_FLOW_ENABLE_NATIVE_BRIDGE_ON_WINDOWS=1 to opt in'
+            : 'AgentDB native bridge disabled by CLAUDE_FLOW_DISABLE_BRIDGE=1';
+    }
+    return bridgeFailureReasons.get(canonicalDbPath(dbPath)) ?? null;
 }
 /**
  * Install a pre-initialized registry for deterministic bridge tests.
@@ -1913,34 +2019,37 @@ export function __setMemoryBridgeRegistryForTests(registry) {
     registryPromises.clear();
     registryInstances.clear();
     testRegistryOverride = registry;
-    bridgeAvailable = registry ? true : null;
-    bridgeFailureReason = null;
+    testRegistryFactory = null;
+    bridgeFailureReasons.clear();
 }
 /**
  * Shutdown the bridge and release resources.
  *
  * The cached state is cleared unconditionally. Previously the reset lived
- * inside `if (registryInstance)`, so it could not clear a FAILED init — the
- * one state that actually needs clearing, since `registryInstance` is null
- * precisely when init failed. A process that latched `bridgeAvailable = false`
- * therefore had no recovery path short of a restart.
+ * inside `if (registryInstance)`, so it could not clear a FAILED init. This
+ * also clears per-path failed promises, allowing a later retry.
  */
-export async function shutdownBridge() {
-    // #3196: every cached registry owns an open database handle, so shutting down
-    // one of several would leave the rest holding files open.
-    for (const registry of registryInstances.values()) {
-        try {
-            await registry.shutdown();
-        }
-        catch {
-            // Best-effort
-        }
-    }
-    registryInstances.clear();
-    registryPromises.clear();
-    testRegistryOverride = null;
-    bridgeAvailable = null;
-    bridgeFailureReason = null;
+export function shutdownBridge() {
+    if (shutdownPromise)
+        return shutdownPromise;
+    // Publish the barrier before any await: no later operation can join the
+    // retiring lifecycle. Concurrent callers share the same retirement promise.
+    shutdownPromise = (async () => {
+        if (activeOperations > 0)
+            await new Promise(resolve => { drained = resolve; });
+        await Promise.allSettled([...registryPromises.values()]);
+        for (const registry of new Set(registryInstances.values())) {
+            try {
+                await registry.shutdown();
+            }
+            catch { /* best-effort cleanup */ }
+        }
+        registryInstances.clear();
+        registryPromises.clear();
+        testRegistryOverride = null;
+        bridgeFailureReasons.clear();
+    })().finally(() => { shutdownPromise = null; });
+    return shutdownPromise;
 }
 // ===== Phase 3: ReasoningBank pattern operations =====
 /**
@@ -1948,6 +2057,8 @@ export async function shutdownBridge() {
  * Falls back to raw SQL if ReasoningBank unavailable.
  */
 export async function bridgeStorePattern(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeStorePattern(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2028,7 +2139,7 @@ export async function bridgeStorePattern(options) {
         // discarded and the caller saw an ordinary fallback, indistinguishable
         // from "no controller registered". Record it so `agentdb_health` and the
         // degraded `reason` can name the real cause instead of guessing.
-        bridgeFailureReason = err instanceof Error ? err.message : String(err);
+        bridgeFailureReasons.set(canonicalDbPath(options.dbPath), err instanceof Error ? err.message : String(err));
         return null;
     }
 }
@@ -2036,6 +2147,8 @@ export async function bridgeStorePattern(options) {
  * Search patterns via ReasoningBank controller.
  */
 export async function bridgeSearchPatterns(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeSearchPatterns(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2120,7 +2233,7 @@ export async function bridgeSearchPatterns(options) {
         // function` died here silently, which is why search reported
         // `reasoningBank-unavailable:registry-null` (a null return) even though
         // the registry was present and the controller was reported enabled.
-        bridgeFailureReason = err instanceof Error ? err.message : String(err);
+        bridgeFailureReasons.set(canonicalDbPath(options.dbPath), err instanceof Error ? err.message : String(err));
         return null;
     }
 }
@@ -2130,6 +2243,9 @@ export async function bridgeSearchPatterns(options) {
  * Wired into hooks_post-task handler.
  */
 export async function bridgeRecordFeedback(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeRecordFeedback(options));
+    const patterns = validateFeedbackPatterns(options.patterns);
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2182,8 +2298,8 @@ export async function bridgeRecordFeedback(options) {
         // add them to LocalReasoningBank via its real `.store()` method (the
         // one method that DOES exist on the class).
         const reasoningBank = registry.get('reasoningBank');
-        if (reasoningBank && Array.isArray(options.patterns) && options.patterns.length) {
-            for (const pattern of options.patterns) {
+        if (reasoningBank && Array.isArray(patterns) && patterns.length) {
+            for (const pattern of patterns) {
                 try {
                     if (typeof reasoningBank.store === 'function') {
                         reasoningBank.store({
@@ -2203,18 +2319,29 @@ export async function bridgeRecordFeedback(options) {
             else if (updated > 0 && controller === 'none')
                 controller = 'reasoningBank';
         }
-        // Phase 4: SkillLibrary promotion for high-quality patterns
-        if (options.success && options.quality >= 0.9 && options.patterns?.length) {
+        // SkillLibrary's public API is createSkill(Skill), not promote().
+        if (options.success && options.quality >= 0.9 && patterns?.length) {
             const skills = registry.get('skills');
-            if (skills && typeof skills.promote === 'function') {
-                for (const pattern of options.patterns) {
+            let created = 0;
+            if (skills && typeof skills.createSkill === 'function') {
+                for (const [index, pattern] of patterns.entries()) {
                     try {
-                        await skills.promote(pattern, options.quality);
+                        await skills.createSkill({
+                            name: `feedback-${options.taskId}-${index}`,
+                            description: pattern,
+                            successRate: 1,
+                            uses: 1,
+                            avgReward: options.quality,
+                            avgLatencyMs: options.duration,
+                            metadata: { taskId: options.taskId, task: options.task, agent: options.agent, source: 'bridge-feedback' },
+                        });
                         updated++;
+                        created++;
                     }
-                    catch { /* skip */ }
+                    catch { /* failed promotion must not count as an update */ }
                 }
-                controller += '+skills';
+                if (created > 0)
+                    controller = controller === 'none' ? 'skills' : `${controller}+skills`;
             }
         }
         // Always store feedback as a memory entry for retrieval (ensures it persists)
@@ -2240,6 +2367,8 @@ export async function bridgeRecordFeedback(options) {
  * Record a causal edge between two entries (e.g., task → result).
  */
 export async function bridgeRecordCausalEdge(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeRecordCausalEdge(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2287,6 +2416,8 @@ export async function bridgeRecordCausalEdge(options) {
  * limitation honestly instead of silently returning success.
  */
 export async function bridgeDeleteHierarchical(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeDeleteHierarchical(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2378,6 +2509,8 @@ export async function bridgeDeleteHierarchical(options) {
  * surface that explicitly via controller: 'native-unsupported'.
  */
 export async function bridgeDeleteCausalEdge(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeDeleteCausalEdge(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2451,6 +2584,8 @@ export async function bridgeDeleteCausalEdge(options) {
  * memory_entries row) and every edge whose key contains the nodeId.
  */
 export async function bridgeDeleteCausalNode(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeDeleteCausalNode(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2530,6 +2665,8 @@ export async function bridgeDeleteCausalNode(options) {
  * Loads relevant past session patterns for the new session.
  */
 export async function bridgeSessionStart(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeSessionStart(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2568,6 +2705,8 @@ export async function bridgeSessionStart(options) {
  * End a session and persist episodic summary to ReflexionMemory.
  */
 export async function bridgeSessionEnd(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeSessionEnd(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2624,6 +2763,8 @@ export async function bridgeSessionEnd(options) {
  * Returns null to fall back to local ruvector router.
  */
 export async function bridgeRouteTask(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeRouteTask(options));
     const registry = await getRegistry(options.dbPath);
     if (!registry)
         return null;
@@ -2665,6 +2806,8 @@ export async function bridgeRouteTask(options) {
  * Get comprehensive bridge health including all controller statuses.
  */
 export async function bridgeHealthCheck(dbPath) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeHealthCheck(dbPath));
     const registry = await getRegistry(dbPath);
     if (!registry)
         return null;
@@ -2748,6 +2891,8 @@ function getHierarchicalFallback(registry) {
         : null;
 }
 export async function bridgeHierarchicalStore(params) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeHierarchicalStore(params));
     const registry = await getRegistry();
     if (!registry)
         return null;
@@ -2818,6 +2963,8 @@ export async function bridgeHierarchicalStore(params) {
  *   recall(query: string, topK: number) → synchronous array
  */
 export async function bridgeHierarchicalRecall(params) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeHierarchicalRecall(params));
     const registry = await getRegistry();
     if (!registry)
         return null;
@@ -2873,16 +3020,15 @@ export async function bridgeHierarchicalRecall(params) {
         return { results: [], error: e.message };
     }
 }
-/**
- * Run memory consolidation.
- *
- * Real MemoryConsolidation API (agentdb alpha.10+):
- *   consolidate() → Promise<ConsolidationReport>
- *   ConsolidationReport = { episodicProcessed, semanticCreated, memoriesForgotten, ... }
- * Stub API (fallback):
- *   consolidate() → { promoted, pruned, timestamp }
- */
+/** Run consolidation when a real controller is available. */
 export async function bridgeConsolidate(params) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeConsolidate(params));
+    // No installed consolidation API accepts these historical options. Reject
+    // them explicitly rather than silently claiming their limits were applied.
+    if (params.minAge !== undefined || params.maxEntries !== undefined) {
+        return { success: false, status: 'unsupported', error: 'minAge and maxEntries are not supported by the consolidation controller' };
+    }
     const registry = await getRegistry();
     if (!registry)
         return null;
@@ -2891,6 +3037,9 @@ export async function bridgeConsolidate(params) {
         if (!mc)
             return { success: false, error: 'MemoryConsolidation not available' };
         const result = await mc.consolidate();
+        if (result?.source === 'stub') {
+            return { success: false, status: 'unsupported', error: 'Memory consolidation is unavailable; no consolidation ran', consolidated: result };
+        }
         return { success: true, consolidated: result };
     }
     catch (e) {
@@ -2904,6 +3053,8 @@ export async function bridgeConsolidate(params) {
  * - update: calls bulkUpdate(table, updates, conditions) on episodes table
  */
 export async function bridgeBatchOperation(params) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeBatchOperation(params));
     const registry = await getRegistry();
     if (!registry)
         return null;
@@ -2957,45 +3108,102 @@ export async function bridgeBatchOperation(params) {
         return { success: false, error: e.message };
     }
 }
-/**
- * Synthesize context from memories.
- * ContextSynthesizer.synthesize is a static method that takes MemoryPattern[] (not a string).
- */
+function contextEpisodeFrom(value) {
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const owns = (key) => Object.prototype.hasOwnProperty.call(record, key);
+    if (!owns('task') || !owns('reward') || !owns('success')
+        || typeof record.task !== 'string' || !record.task.trim()
+        || typeof record.reward !== 'number' || !Number.isFinite(record.reward)
+        || typeof record.success !== 'boolean')
+        return null;
+    const episode = {
+        task: record.task.trim(),
+        reward: record.reward,
+        success: record.success,
+    };
+    for (const field of ['critique', 'input', 'output']) {
+        if (owns(field)) {
+            if (typeof record[field] !== 'string')
+                return null;
+            episode[field] = record[field];
+        }
+    }
+    return episode;
+}
+function contextEpisodeFromRecall(row) {
+    if (!row || typeof row !== 'object' || Array.isArray(row))
+        return null;
+    const record = row;
+    for (const field of [null, 'metadata', 'value', 'content']) {
+        const candidate = field === null ? record
+            : Object.prototype.hasOwnProperty.call(record, field) ? record[field] : undefined;
+        const episode = contextEpisodeFrom(candidate);
+        if (episode)
+            return episode;
+    }
+    return null;
+}
 export async function bridgeContextSynthesize(params) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeContextSynthesize(params));
     const registry = await getRegistry();
     if (!registry)
         return null;
     try {
         const CS = registry.get('contextSynthesizer');
         if (!CS || typeof CS.synthesize !== 'function') {
-            return { success: false, error: 'ContextSynthesizer not available' };
+            return { success: false, reason: 'synthesizer-unavailable', error: 'ContextSynthesizer not available' };
         }
-        // Gather memory patterns from hierarchical memory as input
         const hm = registry.get('hierarchicalMemory');
-        let memories = [];
-        if (hm && typeof hm.recall === 'function') {
-            // Detect real HierarchicalMemory (MemoryQuery object) vs stub (string, number)
-            let recalled;
-            if (typeof hm.promote === 'function') {
-                // Real agentdb HierarchicalMemory
-                recalled = await hm.recall({ query: params.query, k: params.maxEntries || 10 });
-            }
-            else {
-                // Stub
-                recalled = hm.recall(params.query, params.maxEntries || 10);
+        if (!hm || typeof hm.recall !== 'function') {
+            return { success: false, reason: 'memory-unavailable', error: 'HierarchicalMemory not available' };
+        }
+        let recalled;
+        try {
+            // Native HierarchicalMemory accepts a query object; the tiered fallback
+            // accepts positional arguments. Either implementation may be async.
+            recalled = typeof hm.promote === 'function'
+                ? await hm.recall({ query: params.query, k: params.maxEntries || 10 })
+                : await hm.recall(params.query, params.maxEntries || 10);
+        }
+        catch (e) {
+            return { success: false, reason: 'recall-failed', error: e.message };
+        }
+        if (!Array.isArray(recalled)) {
+            return { success: false, reason: 'invalid-recall-result', error: 'HierarchicalMemory recall did not return an array' };
+        }
+        const recalledCount = recalled.length;
+        if (recalledCount === 0) {
+            return { success: false, reason: 'no-memories', error: 'No memories matched the query', recalled: 0, eligible: 0, skipped: 0 };
+        }
+        const memories = recalled.map(contextEpisodeFromRecall).filter((episode) => episode !== null);
+        const counts = { recalled: recalledCount, eligible: memories.length, skipped: recalledCount - memories.length };
+        if (memories.length === 0) {
+            return { success: false, reason: 'no-eligible-episodes', error: 'Recalled memories have no validated task outcomes', ...counts };
+        }
+        try {
+            const result = await CS.synthesize(memories, { includeRecommendations: true });
+            if (!result || typeof result !== 'object') {
+                return { success: false, reason: 'invalid-synthesis', error: 'ContextSynthesizer returned no result', ...counts };
             }
-            memories = (recalled || []).map((r) => ({
-                content: r.value || r.content || '',
-                key: r.key || r.id || '',
-                reward: 1,
-                verdict: 'success',
-            }));
+            return { success: true, synthesis: result, ...counts };
+        }
+        catch (e) {
+            return { success: false, reason: 'synthesizer-failed', error: e.message, ...counts };
         }
-        const result = CS.synthesize(memories, { includeRecommendations: true });
-        return { success: true, synthesis: result };
     }
     catch (e) {
-        return { success: false, error: e.message };
+        return { success: false, reason: 'bridge-error', error: e.message };
     }
 }
 /**
@@ -3004,6 +3212,8 @@ export async function bridgeContextSynthesize(params) {
  * semantic matching with keyword fallback.
  */
 export async function bridgeSemanticRoute(params) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeSemanticRoute(params));
     const registry = await getRegistry();
     if (!registry)
         return null;
@@ -3034,6 +3244,8 @@ export async function bridgeSemanticRoute(params) {
  * Returns null if bridge is unavailable (caller falls back to sql.js).
  */
 export async function bridgeGetAllEmbeddings(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeGetAllEmbeddings(options));
     const registry = await getRegistry(options?.dbPath);
     if (!registry)
         return null;
@@ -3046,7 +3258,7 @@ export async function bridgeGetAllEmbeddings(options) {
         const rows = ctx.db.prepare(`
       SELECT id, key, namespace, embedding
       FROM memory_entries
-      WHERE status = 'active' AND embedding IS NOT NULL
+      WHERE ${liveMemoryRowSql()} AND embedding IS NOT NULL
       LIMIT ?
     `).all(maxRows);
         const results = [];
@@ -3094,6 +3306,8 @@ function cosineSim(a, b) {
  * stores honestly. (#2245 follow-up.)
  */
 export async function getMemoryBridgeStats(options = {}) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => getMemoryBridgeStats(options));
     const namespaces = options.namespaces ?? [
         'default', 'patterns', 'claude-memories', 'auto-memory',
         'tasks', 'feedback', 'pretrain', 'trajectories',