claude-flow 3.47.1 → 3.48.0

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

@@ -9,7 +9,7 @@
  *
  * @module v3/cli/mcp-tools/memory-tools
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join, resolve } from 'path';
 import { createHash } from 'crypto';
@@ -273,11 +273,11 @@ const MEMORY_STATS_MAX_PAGES = 200;
  * breakdown and embedding coverage computed from a prefix, and a listing
  * that reported `success: false` was read as an empty one.
  */
-async function collectAllEntries(listEntries) {
+async function collectAllEntries(listEntries, dbPath) {
     const entries = [];
     let total = 0;
     for (let page = 0; page < MEMORY_STATS_MAX_PAGES; page++) {
-        const result = await listEntries({ limit: MEMORY_STATS_PAGE, offset: entries.length });
+        const result = await listEntries({ limit: MEMORY_STATS_PAGE, offset: entries.length, dbPath });
         if (!result.success) {
             return { success: false, entries, total: result.total ?? total, error: result.error };
         }
@@ -300,10 +300,10 @@ function memoryStatsUnavailable(error) {
  * WAL frames, so it is allowed to fail without that meaning the store is
  * missing — which is exactly the conflation #3311 reports.
  */
-async function readMemoryStatusLabels() {
+async function readMemoryStatusLabels(dbPath) {
     try {
         const { checkMemoryInitialization } = await getMemoryFunctions();
-        const status = await checkMemoryInitialization();
+        const status = await checkMemoryInitialization(dbPath);
         return { version: status.version, features: status.features };
     }
     catch {
@@ -315,37 +315,43 @@ async function readMemoryStatusLabels() {
  * #1606: Wrapped in try/catch to prevent process-level crashes that kill
  * the stdio MCP transport on Windows/Codex.
  */
-async function ensureInitialized() {
+async function ensureInitialized(dbPath) {
     try {
         const { initializeMemoryDatabase, checkMemoryInitialization, storeEntry } = await getMemoryFunctions();
         // Check if already initialized
-        const status = await checkMemoryInitialization();
+        const status = await checkMemoryInitialization(dbPath);
         if (!status.initialized) {
-            await initializeMemoryDatabase({ force: false, verbose: false });
+            await initializeMemoryDatabase({ force: false, verbose: false, dbPath });
         }
         // Migrate legacy JSON data if exists (from old .claude-flow/memory/ location)
+        // A custom import target must not consume the one-time migration marker
+        // for the project's normal memory store.
         if (hasLegacyStore()) {
-            const legacyStore = loadLegacyStore();
-            if (legacyStore && Object.keys(legacyStore.entries).length > 0) {
-                console.error('[MCP Memory] Migrating legacy JSON store to sql.js...');
-                let migrated = 0;
-                for (const [key, entry] of Object.entries(legacyStore.entries)) {
-                    try {
-                        const value = typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value);
-                        await storeEntry({
-                            key,
-                            value,
-                            namespace: 'default',
-                            generateEmbeddingFlag: true,
-                        });
-                        migrated++;
-                    }
-                    catch (e) {
-                        console.error(`[MCP Memory] Failed to migrate key "${key}":`, e);
+            const { resolveDbPath } = await import('../memory/memory-initializer.js');
+            if (!dbPath || dbPath === resolveDbPath()) {
+                const legacyStore = loadLegacyStore();
+                if (legacyStore && Object.keys(legacyStore.entries).length > 0) {
+                    console.error('[MCP Memory] Migrating legacy JSON store to sql.js...');
+                    let migrated = 0;
+                    for (const [key, entry] of Object.entries(legacyStore.entries)) {
+                        try {
+                            const value = typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value);
+                            await storeEntry({
+                                key,
+                                value,
+                                namespace: 'default',
+                                generateEmbeddingFlag: true,
+                                dbPath,
+                            });
+                            migrated++;
+                        }
+                        catch (e) {
+                            console.error(`[MCP Memory] Failed to migrate key "${key}":`, e);
+                        }
                     }
+                    console.error(`[MCP Memory] Migrated ${migrated}/${Object.keys(legacyStore.entries).length} entries`);
+                    markMigrationComplete();
                 }
-                console.error(`[MCP Memory] Migrated ${migrated}/${Object.keys(legacyStore.entries).length} entries`);
-                markMigrationComplete();
             }
         }
     }
@@ -792,10 +798,18 @@ export const memoryTools = [
         category: 'memory',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                dbPath: { type: 'string', description: 'Database file to inspect; omitted uses the MCP store default' },
+            },
         },
-        handler: async () => {
-            await ensureInitialized();
+        handler: async (input) => {
+            if (input.dbPath !== undefined && (typeof input.dbPath !== 'string' || !input.dbPath.trim())) {
+                return memoryStatsUnavailable('dbPath must be a non-empty string');
+            }
+            const dbPath = typeof input.dbPath === 'string' ? resolve(input.dbPath) : undefined;
+            // An explicit read must not initialize or migrate the unrelated default store.
+            if (!dbPath)
+                await ensureInitialized();
             const { listEntries } = await getMemoryFunctions();
             // #3311: the store's own listing decides whether memory is there.
             // `checkMemoryInitialization` opens a whole-image sql.js snapshot of
@@ -806,7 +820,7 @@ export const memoryTools = [
             // but it no longer gets to overrule a working store.
             let listing;
             try {
-                listing = await collectAllEntries(listEntries);
+                listing = await collectAllEntries(listEntries, dbPath);
             }
             catch (error) {
                 return memoryStatsUnavailable(error instanceof Error ? error.message : 'Unknown error');
@@ -822,16 +836,49 @@ export const memoryTools = [
             // from the breakdown while still being counted in the total.
             const namespaces = Object.create(null);
             let withEmbeddings = 0;
+            let oldest = Infinity;
+            let newest = -Infinity;
             for (const entry of listing.entries) {
                 namespaces[entry.namespace] = (namespaces[entry.namespace] || 0) + 1;
                 if (entry.hasEmbedding)
                     withEmbeddings++;
+                // AgentDB returns INTEGER epoch milliseconds; legacy sql.js rows
+                // may expose ISO strings or numeric strings from SQLite TEXT affinity.
+                const rawCreated = entry.createdAt;
+                const millis = typeof rawCreated === 'number'
+                    ? rawCreated
+                    : typeof rawCreated === 'string' && /^-?\d+$/.test(rawCreated)
+                        ? Number(rawCreated)
+                        : Date.parse(rawCreated ?? '');
+                const created = new Date(millis).getTime();
+                if (Number.isFinite(created)) {
+                    oldest = Math.min(oldest, created);
+                    newest = Math.max(newest, created);
+                }
             }
             const counted = listing.entries.length;
-            const status = await readMemoryStatusLabels();
+            const status = await readMemoryStatusLabels(dbPath);
+            let totalSize = null;
+            if (dbPath) {
+                try {
+                    let bytes = statSync(dbPath).size;
+                    try {
+                        bytes += statSync(dbPath + '-wal').size;
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                    totalSize = `${bytes} B`;
+                }
+                catch { /* unavailable file metadata is unknown, not zero */ }
+            }
             return {
                 initialized: true,
                 totalEntries: listing.total,
+                ...(dbPath ? { location: dbPath, totalSize } : {}),
+                oldestEntry: counted >= listing.total && Number.isFinite(oldest) ? new Date(oldest).toISOString() : null,
+                newestEntry: counted >= listing.total && Number.isFinite(newest) ? new Date(newest).toISOString() : null,
                 entriesCounted: counted,
                 // The breakdown below covers `entriesCounted` rows, which is every
                 // row unless the listing was truncated; say so rather than letting
@@ -1484,11 +1531,15 @@ export const memoryTools = [
                 inputPath: { type: 'string', description: 'Path to the JSON export file' },
                 merge: { type: 'boolean', description: 'Merge into existing entries (upsert) vs. fail on conflict (default true)' },
                 namespace: { type: 'string', description: 'Override the namespace for all imported entries' },
+                dbPath: { type: 'string', description: 'Database file to import into (defaults to the MCP memory store)' },
             },
             required: ['inputPath'],
         },
         handler: async (input) => {
-            await ensureInitialized();
+            const dbPath = typeof input.dbPath === 'string' && input.dbPath.trim()
+                ? resolve(input.dbPath)
+                : undefined;
+            await ensureInitialized(dbPath);
             const { storeEntry } = await getMemoryFunctions();
             const t0 = Date.now();
             const inputPath = String(input.inputPath ?? '');
@@ -1517,8 +1568,11 @@ export const memoryTools = [
                 }
                 const value = typeof e.value === 'string' ? e.value : JSON.stringify(e.value ?? null);
                 try {
-                    await storeEntry({ key: e.key, value, namespace: nsOverride ?? e.namespace ?? 'default', upsert: input.merge !== false });
-                    imported++;
+                    const result = await storeEntry({ key: e.key, value, namespace: nsOverride ?? e.namespace ?? 'default', upsert: input.merge !== false, dbPath });
+                    if (result.success)
+                        imported++;
+                    else
+                        skipped++;
                 }
                 catch {
                     skipped++;

package/v3/@claude-flow/cli/dist/src/mcp-tools/policy-enforcer.d.ts

@@ -62,6 +62,12 @@ export interface McpPolicy {
     harnessId?: string;
     defaultDeny?: boolean;
     auditLog?: boolean;
+    /** Explicit destination; takes precedence over the environment and project default. */
+    auditLogPath?: string;
+    /** Maximum bytes per audit segment. Default 10 MiB; oversized records fail closed. */
+    auditLogMaxBytes?: number;
+    /** Rotated segments retained in addition to the active log. Default 5, maximum 100. */
+    auditLogMaxFiles?: number;
     requireApprovalForDangerous?: boolean;
     toolTimeoutMs?: number;
     /**
@@ -103,10 +109,11 @@ export interface AuditLogEntry {
     toolName: string;
     allowed: boolean;
     reason?: string;
+    projectPath?: string;
 }
 /** Test-only: redirect the audit log to a temp file instead of the default path. */
 export declare function setAuditLogPathForTesting(p: string | null): void;
-export declare function getAuditLogPath(): string;
+export declare function getAuditLogPath(options?: Pick<McpPolicy, 'auditLogPath'>): string;
 /**
  * Appends one JSONL audit record. Returns `true` if `policy.auditLog` is not
  * set (nothing was required) or the write succeeded; `false` only when

package/v3/@claude-flow/cli/dist/src/mcp-tools/policy-enforcer.js

@@ -58,7 +58,6 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 export function isPolicyEnforcementEnabled(env = process.env) {
     const v = env.RUFLO_MCP_ENFORCE_POLICY;
     return v === '1' || (v ?? '').toLowerCase() === 'true';
@@ -118,11 +117,18 @@ let auditLogPathOverride = null;
 export function setAuditLogPathForTesting(p) {
     auditLogPathOverride = p;
 }
-function defaultAuditLogPath() {
-    return path.join(os.tmpdir(), 'ruflo-mcp-audit.jsonl');
-}
-export function getAuditLogPath() {
-    return auditLogPathOverride ?? defaultAuditLogPath();
+export function getAuditLogPath(options = {}) {
+    if (auditLogPathOverride !== null)
+        return auditLogPathOverride;
+    if (options.auditLogPath !== undefined &&
+        (typeof options.auditLogPath !== 'string' || options.auditLogPath.trim().length === 0)) {
+        throw new Error('auditLogPath must be a non-empty string');
+    }
+    // Precedence: explicit caller/policy destination, environment, project default.
+    const configured = options.auditLogPath ?? process.env.RUFLO_MCP_AUDIT_LOG_PATH;
+    return configured
+        ? path.resolve(process.cwd(), configured)
+        : path.join(process.cwd(), '.claude-flow', 'logs', 'mcp-audit.jsonl');
 }
 /**
  * Appends one JSONL audit record. Returns `true` if `policy.auditLog` is not
@@ -135,8 +141,74 @@ export function appendAuditLog(policy, entry) {
     if (!policy.auditLog)
         return true;
     try {
-        fs.appendFileSync(getAuditLogPath(), `${JSON.stringify(entry)}\n`, 'utf-8');
-        return true;
+        const maxBytes = policy.auditLogMaxBytes ?? 10 * 1024 * 1024;
+        const maxFiles = policy.auditLogMaxFiles ?? 5;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 ||
+            !Number.isSafeInteger(maxFiles) || maxFiles < 1 || maxFiles > 100)
+            return false;
+        const line = `${JSON.stringify({ ...entry, projectPath: path.resolve(process.cwd()) })}\n`;
+        const bytes = Buffer.byteLength(line, 'utf8');
+        if (bytes > maxBytes)
+            return false;
+        const logPath = getAuditLogPath(policy);
+        fs.mkdirSync(path.dirname(logPath), { recursive: true, mode: 0o700 });
+        // All writers of a configured path serialize rotation AND append. On
+        // contention (or a stale lock after a crash), deny rather than lose audit
+        // evidence by racing a rename. Only the lock owner removes its lock.
+        const lockPath = `${logPath}.lock`;
+        const lock = fs.openSync(lockPath, 'wx', 0o600);
+        try {
+            let size = 0;
+            try {
+                const stat = fs.lstatSync(logPath);
+                if (!stat.isFile())
+                    throw new Error('Audit log is not a regular file');
+                size = stat.size;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if (size + bytes > maxBytes) {
+                // Validate the entire chain before moving or expiring any evidence.
+                for (let index = 1; index <= maxFiles; index++) {
+                    try {
+                        if (!fs.lstatSync(`${logPath}.${index}`).isFile())
+                            throw new Error('Audit segment is not a regular file');
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+                for (let index = maxFiles; index >= 1; index--) {
+                    const source = index === 1 ? logPath : `${logPath}.${index - 1}`;
+                    const target = `${logPath}.${index}`;
+                    if (index === maxFiles) {
+                        try {
+                            fs.unlinkSync(target);
+                        }
+                        catch (error) {
+                            if (error.code !== 'ENOENT')
+                                throw error;
+                        }
+                    }
+                    try {
+                        fs.renameSync(source, target);
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+            }
+            fs.appendFileSync(logPath, line, { encoding: 'utf8', mode: 0o600 });
+            return true;
+        }
+        finally {
+            fs.closeSync(lock);
+            fs.unlinkSync(lockPath);
+        }
     }
     catch {
         return false;

package/v3/@claude-flow/cli/dist/src/mcp-tools/session-tools.js

@@ -4,6 +4,7 @@
  * Tool definitions for session management with file persistence.
  */
 import { existsSync, readFileSync, readdirSync, unlinkSync, statSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { getProjectCwd } from './types.js';
 import { mkdirRestricted, readFileMaybeEncrypted, writeFileRestricted, } from '../fs-secure.js';
@@ -126,7 +127,7 @@ export const sessionTools = [
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
-            const sessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const sessionId = `session-${Date.now()}-${randomUUID().slice(0, 8)}`;
             // Load related data based on options
             const data = loadRelatedStores({
                 includeMemory: input.includeMemory,
@@ -170,6 +171,9 @@ export const sessionTools = [
             properties: {
                 sessionId: { type: 'string', description: 'Session ID to restore' },
                 name: { type: 'string', description: 'Session name to restore' },
+                restoreMemory: { type: 'boolean', description: 'Restore memory (default true)' },
+                restoreTasks: { type: 'boolean', description: 'Restore tasks (default true)' },
+                restoreAgents: { type: 'boolean', description: 'Restore agents (default true)' },
             },
         },
         handler: async (input) => {
@@ -205,7 +209,7 @@ export const sessionTools = [
             if (session) {
                 // Restore data to respective stores (legacy JSON for backward compat).
                 // audit_1776853149979: tighten perms on the restored stores too.
-                if (session.data?.memory) {
+                if (input.restoreMemory !== false && session.data?.memory) {
                     const memoryDir = join(getProjectCwd(), STORAGE_DIR, 'memory');
                     if (!existsSync(memoryDir))
                         mkdirRestricted(memoryDir);
@@ -233,13 +237,13 @@ export const sessionTools = [
                         // Legacy JSON restore is the fallback -- sql.js import may not be available
                     }
                 }
-                if (session.data?.tasks) {
+                if (input.restoreTasks !== false && session.data?.tasks) {
                     const taskDir = join(getProjectCwd(), STORAGE_DIR, 'tasks');
                     if (!existsSync(taskDir))
                         mkdirRestricted(taskDir);
                     writeFileRestricted(join(taskDir, 'store.json'), JSON.stringify(session.data.tasks, null, 2));
                 }
-                if (session.data?.agents) {
+                if (input.restoreAgents !== false && session.data?.agents) {
                     const agentDir = join(getProjectCwd(), STORAGE_DIR, 'agents');
                     if (!existsSync(agentDir))
                         mkdirRestricted(agentDir);
@@ -249,6 +253,11 @@ export const sessionTools = [
                     sessionId: session.sessionId,
                     name: session.name,
                     restored: true,
+                    restoredComponents: {
+                        memory: input.restoreMemory !== false && !!session.data?.memory,
+                        tasks: input.restoreTasks !== false && !!session.data?.tasks,
+                        agents: input.restoreAgents !== false && !!session.data?.agents,
+                    },
                     restoredAt: new Date().toISOString(),
                     stats: session.stats,
                 };
@@ -437,7 +446,7 @@ export const sessionTools = [
             properties: {
                 sessionId: { type: 'string', description: 'Session ID to export' },
                 outputPath: { type: 'string', description: 'File path to write the export to (optional)' },
-                includeMemory: { type: 'boolean', description: 'Include the memory snapshot (advisory — already in the saved record)' },
+                includeMemory: { type: 'boolean', description: 'Include the memory snapshot (default true)' },
             },
             required: ['sessionId'],
         },
@@ -449,6 +458,14 @@ export const sessionTools = [
             const session = loadSession(sessionId);
             if (!session)
                 return { sessionId, error: 'Session not found' };
+            // Apply the explicit exclusion before either returning or writing the
+            // snapshot. The saved source remains intact for a later full restore.
+            if (input.includeMemory === false) {
+                if (session.data)
+                    delete session.data.memory;
+                session.stats = { ...session.stats, memoryEntries: 0, totalSize: 0 };
+                session.stats.totalSize = Buffer.byteLength(JSON.stringify(session), 'utf-8');
+            }
             let path = null;
             const outputPath = input.outputPath ? String(input.outputPath) : null;
             if (outputPath) {
@@ -474,7 +491,7 @@ export const sessionTools = [
             properties: {
                 inputPath: { type: 'string', description: 'Path to the session JSON file to import' },
                 name: { type: 'string', description: 'Override the imported session name' },
-                activate: { type: 'boolean', description: 'Make the imported session the current one (advisory)' },
+                activate: { type: 'boolean', description: 'Restore the imported session into the active stores' },
             },
             required: ['inputPath'],
         },
@@ -489,7 +506,7 @@ export const sessionTools = [
             catch (e) {
                 return { error: `Invalid session JSON: ${e.message}` };
             }
-            const newId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const newId = `session-${Date.now()}-${randomUUID().slice(0, 8)}`;
             const stats = parsed.stats || { tasks: 0, agents: 0, memoryEntries: 0, totalSize: 0 };
             const session = {
                 sessionId: newId,
@@ -500,6 +517,15 @@ export const sessionTools = [
                 data: parsed.data,
             };
             saveSession(session);
+            let activated = false;
+            if (input.activate === true) {
+                const restore = sessionTools.find(tool => tool.name === 'session_restore');
+                const result = await restore.handler({ sessionId: newId });
+                if (result.restored !== true) {
+                    return { sessionId: newId, activated: false, error: result.error || 'Imported session could not be restored' };
+                }
+                activated = true;
+            }
             return {
                 sessionId: newId,
                 name: session.name,
@@ -509,7 +535,7 @@ export const sessionTools = [
                     tasksImported: stats.tasks,
                     memoryEntriesImported: stats.memoryEntries,
                 },
-                activated: input.activate === true,
+                activated,
             };
         },
     },

package/v3/@claude-flow/cli/dist/src/memory/feedback-patterns.d.ts

@@ -0,0 +1,13 @@
+/** Shared input contract for learned patterns supplied by feedback callers. */
+export declare const feedbackPatternsSchema: {
+    type: string;
+    items: {
+        type: string;
+        minLength: number;
+        maxLength: number;
+    };
+    maxItems: number;
+    description: string;
+};
+export declare function validateFeedbackPatterns(value: unknown): string[] | undefined;
+//# sourceMappingURL=feedback-patterns.d.ts.map

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

@@ -0,0 +1,14 @@
+/** Shared input contract for learned patterns supplied by feedback callers. */
+export const feedbackPatternsSchema = {
+    type: 'array', items: { type: 'string', minLength: 1, maxLength: 10_000 }, maxItems: 100,
+    description: 'Learned patterns to retain; successful tasks with quality >= 0.9 may create reusable skills',
+};
+export function validateFeedbackPatterns(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length > 100 || value.some(item => typeof item !== 'string' || !item.trim() || item.length > 10_000)) {
+        throw new Error('patterns must be an array of at most 100 non-empty strings (maximum 10000 characters each)');
+    }
+    return value;
+}
+//# sourceMappingURL=feedback-patterns.js.map

package/v3/@claude-flow/cli/dist/src/memory/live-memory-row.d.ts

@@ -0,0 +1,3 @@
+/** TTL is a read-time visibility rule, independent of background cleanup. */
+export declare function liveMemoryRowSql(): string;
+//# sourceMappingURL=live-memory-row.d.ts.map

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

@@ -0,0 +1,5 @@
+/** TTL is a read-time visibility rule, independent of background cleanup. */
+export function liveMemoryRowSql() {
+    return `(status = 'active' OR status IS NULL) AND (expires_at IS NULL OR expires_at > ${Date.now()})`;
+}
+//# sourceMappingURL=live-memory-row.js.map

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

@@ -36,6 +36,8 @@ export declare function shouldDisableNativeBridge(platform?: NodeJS.Platform, en
 export declare function shouldSuppressInitLog(msg: string): boolean;
 /** Test seam: forget cached registries so a test can exercise a fresh open. */
 export declare function _resetRegistryCacheForTest(): void;
+/** Inject registry construction without requiring the optional native package in tests. */
+export declare function __setMemoryBridgeRegistryFactoryForTests(factory: (() => any) | null): void;
 /** #3196: the sibling store AgentDB owns next to a given sql.js database. */
 export declare function siblingAgentDbPath(dbPath: string): string | null;
 /**
@@ -271,6 +273,7 @@ export declare function bridgeAddEmbedding(id: string, embedding: number[], entr
 }, dbPath?: string): Promise<boolean | null>;
 /**
  * Get a named controller from AgentDB v3 via ControllerRegistry.
+ * This borrowed handle must not be retained across shutdownBridge().
  * Returns null if unavailable.
  */
 export declare function bridgeGetController(name: string, dbPath?: string): Promise<any | null>;
@@ -292,13 +295,15 @@ export declare function bridgeListControllers(dbPath?: string): Promise<Array<{
 export declare function isBridgeAvailable(dbPath?: string): Promise<boolean>;
 /**
  * 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 declare function getControllerRegistry(dbPath?: string): Promise<any | null>;
 /**
  * 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.
@@ -306,7 +311,7 @@ export declare function getControllerRegistry(dbPath?: string): Promise<any | nu
  * Callers that surface a degraded-path error should include this so the
  * operator learns the cause instead of only the symptom.
  */
-export declare function getBridgeFailureReason(): string | null;
+export declare function getBridgeFailureReason(dbPath?: string): string | null;
 /**
  * Install a pre-initialized registry for deterministic bridge tests.
  *
@@ -321,10 +326,8 @@ export declare function __setMemoryBridgeRegistryForTests(registry: any | null):
  * 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 declare function shutdownBridge(): Promise<void>;
 /**
@@ -589,15 +592,7 @@ export declare function bridgeHierarchicalRecall(params: {
     topK?: number;
     includeExpired?: boolean;
 }): Promise<any>;
-/**
- * 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 declare function bridgeConsolidate(params: {
     minAge?: number;
     maxEntries?: number;
@@ -612,10 +607,6 @@ export declare function bridgeBatchOperation(params: {
     operation: string;
     entries: any[];
 }): Promise<any>;
-/**
- * Synthesize context from memories.
- * ContextSynthesizer.synthesize is a static method that takes MemoryPattern[] (not a string).
- */
 export declare function bridgeContextSynthesize(params: {
     query: string;
     maxEntries?: number;