Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(memory): isolate bridge failures by canonical database path

Rudy Celeklibc05a89bf84a
diff --git a/v3/@claude-flow/cli/__tests__/memory-bridge-path-failure-3143.test.ts b/v3/@claude-flow/cli/__tests__/memory-bridge-path-failure-3143.test.ts
new file mode 100644
index 0000000000..2532762561
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/memory-bridge-path-failure-3143.test.ts
@@ -0,0 +1,157 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const state = {
+ calls: [] as string[],
+ closed: [] as string[],
+ failPath: '' as string,
+ failOperationPath: '' as string,
+ initializeGate: null as Promise<void> | null,
+};
+
+class FakeRegistry {
+ private dbPath = '';
+ async initialize(options: { dbPath: string }) {
+ this.dbPath = options.dbPath;
+ state.calls.push(options.dbPath);
+ if (state.initializeGate) await state.initializeGate;
+ if (options.dbPath === state.failPath) throw new Error('database A unavailable');
+ }
+ get() {
+ if (this.dbPath === state.failOperationPath) throw new Error('database A pattern operation failed');
+ return null;
+ }
+ getAgentDB() { return null; }
+ async shutdown() { state.closed.push(this.dbPath); }
+}
+
+vi.mock('../src/memory/intelligence.js', () => ({
+ initializeIntelligence: vi.fn(async () => ({ reasoningBankEnabled: false, sonaEnabled: false })),
+}));
+
+const bridge = await import('../src/memory/memory-bridge.js');
+
+let root: string;
+beforeEach(() => {
+ root = realpathSync(mkdtempSync(join(tmpdir(), 'ruflo-bridge-path-3143-')));
+ state.calls.length = 0;
+ state.closed.length = 0;
+ state.failPath = '';
+ state.failOperationPath = '';
+ state.initializeGate = null;
+ bridge._resetRegistryCacheForTest();
+ bridge.__setMemoryBridgeRegistryFactoryForTests(() => new FakeRegistry());
+});
+afterEach(async () => {
+ await bridge.shutdownBridge();
+ rmSync(root, { recursive: true, force: true });
+});
+
+describe('#3143 bridge state belongs to a canonical database path', () => {
+ it('a failed database does not disable a healthy database in the same process', async () => {
+ const a = join(root, 'a.db');
+ const b = join(root, 'b.db');
+ state.failPath = a;
+
+ expect(await bridge.getControllerRegistry(a)).toBeNull();
+ expect(bridge.getBridgeFailureReason(a)).toContain('database A unavailable');
+ expect(bridge.getBridgeFailureReason(b)).toBeNull();
+
+ const healthy = await bridge.getControllerRegistry(b);
+ expect(healthy).not.toBeNull();
+ expect(await bridge.isBridgeAvailable(b)).toBe(true);
+ expect(await bridge.isBridgeAvailable(a)).toBe(false);
+ expect(state.calls).toEqual([a, b]);
+ expect(state.closed).toEqual([a]);
+ });
+
+ it('symlink aliases and direct paths share one registry', async () => {
+ const db = join(root, 'memory.db');
+ const aliasDir = join(root, 'alias');
+ writeFileSync(db, '');
+ mkdirSync(aliasDir);
+ const alias = join(aliasDir, 'memory.db');
+ symlinkSync(db, alias);
+
+ const directRegistry = await bridge.getControllerRegistry(db);
+ const aliasRegistry = await bridge.getControllerRegistry(alias);
+
+ expect(aliasRegistry).toBe(directRegistry);
+ expect(state.calls).toEqual([db]);
+ });
+
+ it('canonicalizes a symlinked directory before the database file exists', async () => {
+ const db = join(root, 'new.db');
+ const aliasDir = join(root, 'alias-dir');
+ symlinkSync(root, aliasDir, 'dir');
+
+ const directRegistry = await bridge.getControllerRegistry(db);
+ const aliasRegistry = await bridge.getControllerRegistry(join(aliasDir, 'new.db'));
+
+ expect(aliasRegistry).toBe(directRegistry);
+ expect(state.calls).toEqual([db]);
+ });
+
+ it('can retry a failed database after shutdown without affecting another database', async () => {
+ const a = join(root, 'a.db');
+ const b = join(root, 'b.db');
+ state.failPath = a;
+ expect(await bridge.getControllerRegistry(a)).toBeNull();
+ expect(await bridge.getControllerRegistry(b)).not.toBeNull();
+
+ await bridge.shutdownBridge();
+ expect(bridge.getBridgeFailureReason(a)).toBeNull();
+ expect(state.closed.sort()).toEqual([a, b].sort());
+ state.failPath = '';
+ bridge.__setMemoryBridgeRegistryFactoryForTests(() => new FakeRegistry());
+
+ expect(await bridge.getControllerRegistry(a)).not.toBeNull();
+ expect(state.calls).toEqual([a, b, a]);
+ });
+
+ it('keeps a per-operation diagnostic on the database whose controller failed', async () => {
+ const a = join(root, 'a.db');
+ const b = join(root, 'b.db');
+ await bridge.getControllerRegistry(a);
+ await bridge.getControllerRegistry(b);
+ state.failOperationPath = a;
+
+ expect(await bridge.bridgeStorePattern({ pattern: 'p', type: 'test', confidence: 1, dbPath: a })).toBeNull();
+ expect(bridge.getBridgeFailureReason(a)).toContain('database A pattern operation failed');
+ expect(bridge.getBridgeFailureReason(b)).toBeNull();
+ expect(await bridge.isBridgeAvailable(b)).toBe(true);
+ });
+
+ it('concurrent opens deduplicate per path and shutdown closes each registry once', async () => {
+ const a = join(root, 'a.db');
+ const b = join(root, 'b.db');
+ const [first, again, second] = await Promise.all([
+ bridge.getControllerRegistry(a),
+ bridge.getControllerRegistry(a),
+ bridge.getControllerRegistry(b),
+ ]);
+ expect(first).toBe(again);
+ expect(second).not.toBe(first);
+ expect(state.calls.filter((path) => path === a)).toHaveLength(1);
+ expect(state.calls.filter((path) => path === b)).toHaveLength(1);
+
+ await bridge.shutdownBridge();
+ expect(state.closed.sort()).toEqual([a, b].sort());
+ });
+
+ it('waits for an in-flight open before closing its native handle', async () => {
+ const a = join(root, 'a.db');
+ let release!: () => void;
+ state.initializeGate = new Promise<void>((resolve) => { release = resolve; });
+
+ const opening = bridge.getControllerRegistry(a);
+ const shutdown = bridge.shutdownBridge();
+ release();
+ await Promise.all([opening, shutdown]);
+
+ expect(state.closed).toEqual([a]);
+ expect(bridge.getBridgeFailureReason(a)).toBeNull();
+ });
+});
diff --git a/v3/@claude-flow/cli/src/memory/memory-bridge.ts b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
index 948ef83b11..f81a4e4e35 100644
--- a/v3/@claude-flow/cli/src/memory/memory-bridge.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
@@ -19,6 +19,7 @@
import * as path from 'path';
import * as crypto from 'crypto';
+import { realpathSync } from 'node:fs';
import { createRequire } from 'node:module';
// ===== Lazy registry cache, keyed by database path =====
@@ -49,22 +50,34 @@ const registryInstances = new Map<string, any>();
* pass the same path the seam guessed, which is how #2968's fixture broke.
*/
let testRegistryOverride: any = null;
-let bridgeAvailable: boolean | null = null;
+let testRegistryFactory: (() => any) | null = 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: string | null = null;
+const bridgeFailureReasons = new Map<string, string>();
+
+/** Resolve aliases even when the database file or some parent dirs do not exist yet. */
+function canonicalDbPath(dbPath?: string): string {
+ const resolved = dbPath === ':memory:' ? ':memory:' : path.resolve(dbPath ?? getAgentDbPath());
+ if (resolved === ':memory:') return resolved;
+ let ancestor = resolved;
+ const suffix: string[] = [];
+ 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
@@ -197,19 +210,12 @@ export function shouldSuppressInitLog(msg: string): boolean {
* Returns null if @claude-flow/memory is not available.
*/
async function getRegistry(dbPath?: string): Promise<any | null> {
- 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';
- return null;
- }
+ 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;
@@ -217,9 +223,11 @@ async function getRegistry(dbPath?: string): Promise<any | null> {
let registryPromise = registryPromises.get(resolvedPath);
if (!registryPromise) {
registryPromise = (async () => {
+ let registry: any;
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).
@@ -453,16 +461,14 @@ async function getRegistry(dbPath?: string): Promise<any | null> {
}
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;
}
})();
@@ -477,8 +483,13 @@ export function _resetRegistryCacheForTest(): void {
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: (() => any) | null): void {
+ testRegistryFactory = factory;
}
/** #3196: the sibling store AgentDB owns next to a given sql.js database. */
@@ -1052,7 +1063,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
@@ -1163,7 +1174,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;
}
}
@@ -2049,7 +2060,6 @@ export async function bridgeListControllers(
* Check if the AgentDB v3 bridge is available.
*/
export async function isBridgeAvailable(dbPath?: string): Promise<boolean> {
- if (bridgeAvailable !== null) return bridgeAvailable;
const registry = await getRegistry(dbPath);
return registry !== null;
}
@@ -2064,8 +2074,7 @@ export async 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.
@@ -2073,8 +2082,13 @@ export async function getControllerRegistry(dbPath?: string): Promise<any | null
* Callers that surface a degraded-path error should include this so the
* operator learns the cause instead of only the symptom.
*/
-export function getBridgeFailureReason(): string | null {
- return bridgeFailureReason;
+export function getBridgeFailureReason(dbPath?: string): string | null {
+ 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;
}
/**
@@ -2090,22 +2104,22 @@ export function __setMemoryBridgeRegistryForTests(registry: any | null): void {
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(): Promise<void> {
- // #3196: every cached registry owns an open database handle, so shutting down
- // one of several would leave the rest holding files open.
+ // An initialization already in flight can publish a native handle after a
+ // synchronous cache clear. Wait for the opens we know about before closing.
+ await Promise.allSettled([...registryPromises.values()]);
+ // #3196: every cached registry owns an open database handle.
for (const registry of registryInstances.values()) {
try {
await registry.shutdown();
@@ -2116,8 +2130,8 @@ export async function shutdownBridge(): Promise<void> {
registryInstances.clear();
registryPromises.clear();
testRegistryOverride = null;
- bridgeAvailable = null;
- bridgeFailureReason = null;
+ testRegistryFactory = null;
+ bridgeFailureReasons.clear();
}
// ===== Phase 3: ReasoningBank pattern operations =====
@@ -2215,7 +2229,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;
}
}
@@ -2316,7 +2330,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;
}
}
diff --git a/v3/@claude-flow/cli/src/memory/memory-initializer.ts b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
index 634c4df7ea..f347ee39ee 100644
--- a/v3/@claude-flow/cli/src/memory/memory-initializer.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
@@ -213,14 +213,14 @@ async function getBridge(): Promise<typeof import('./memory-bridge.js') | null>
* missing better-sqlite3. Appending the recorded reason turns an unactionable
* message into a diagnosis.
*/
-async function walRefusalError(operation: 'write' | 'read/write'): Promise<string> {
+async function walRefusalError(operation: 'write' | 'read/write', bridgeDbPath?: string): Promise<string> {
const base = 'memory database has an active native WAL connection '
+ '(found -wal/-shm sidecar files) β€” refusing an unsafe sql.js '
+ `whole-image ${operation}. Retry once the native writer completes, or `
+ 'restore the native better-sqlite3 bridge.';
try {
const bridge = await getBridge();
- const reason = bridge?.getBridgeFailureReason?.();
+ const reason = bridge?.getBridgeFailureReason?.(bridgeDbPath);
if (reason) return `${base} Bridge unavailable: ${reason}`;
} catch {
// Diagnostics must never mask the refusal they annotate.
@@ -2967,7 +2967,7 @@ export async function storeEntry(options: {
return {
success: false,
id: '',
- error: await walRefusalError('write'),
+ error: await walRefusalError('write', options.dbPath),
};
}
@@ -3642,7 +3642,7 @@ export async function getEntry(options: {
return {
success: false,
found: false,
- error: await walRefusalError('read/write'),
+ error: await walRefusalError('read/write', options.dbPath),
};
}
@@ -3796,7 +3796,7 @@ export async function deleteEntry(options: {
key,
namespace,
remainingEntries: 0,
- error: await walRefusalError('write'),
+ error: await walRefusalError('write', options.dbPath),
};
}