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): refuse unsafe sql.js whole-image writes under a live native WAL writer (#2749)

rUv03b2dbf3262a
diff --git a/v3/@claude-flow/cli/__tests__/issue-2735-memory-wal-sidecar-guard.test.ts b/v3/@claude-flow/cli/__tests__/issue-2735-memory-wal-sidecar-guard.test.ts
new file mode 100644
index 0000000000..3d12907f2d
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/issue-2735-memory-wal-sidecar-guard.test.ts
@@ -0,0 +1,122 @@
+/**
+ * Regression coverage for issue #2735: memory CRUD's sql.js fallback did a
+ * whole-image read-modify-persist (export() + rename over the live
+ * database path) with no regard for whether a native better-sqlite3 WAL
+ * connection was already attached β€” corrupting the shared database or
+ * silently losing an acknowledged write when the fallback fired while a
+ * native writer (daemon, MCP server, another CLI invocation) held the file
+ * open.
+ *
+ * This suite covers the scoped fix actually shipped: refuse the sql.js
+ * fallback (`success: false`, typed error, never a whole-image write) when
+ * `-wal`/`-shm` sidecar files are present next to the database β€” strong
+ * evidence of a live native WAL connection, since a native connection keeps
+ * its sidecars on disk for its entire lifetime. It does NOT cover the
+ * fuller "scan live process holders" design also discussed in the issue β€”
+ * that remains a documented follow-up, not part of this fix.
+ *
+ * The bridge is force-disabled via CLAUDE_FLOW_DISABLE_BRIDGE=1 (the
+ * package's own documented switch, dist/src/memory/memory-initializer.js)
+ * so every case below exercises the sql.js fallback path directly,
+ * deterministically, without needing a real second native connection.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+let dir: string;
+let dbPath: string;
+const ORIGINAL_ENV = process.env.CLAUDE_FLOW_DISABLE_BRIDGE;
+
+beforeEach(async () => {
+ dir = mkdtempSync(path.join(tmpdir(), 'ruflo-2735-'));
+ dbPath = path.join(dir, 'memory.db');
+ process.env.CLAUDE_FLOW_DISABLE_BRIDGE = '1';
+ // Reset the module registry so each test gets a fresh dynamic import β€”
+ // the module under test is pure-functional (no top-level state this
+ // suite depends on), but sql.js's own WASM init is safest re-run clean.
+ const { initializeMemoryDatabase } = await import('../src/memory/memory-initializer.js');
+ const initResult = await initializeMemoryDatabase({ dbPath, verbose: false });
+ expect(initResult.success).toBe(true);
+});
+
+afterEach(() => {
+ if (ORIGINAL_ENV === undefined) delete process.env.CLAUDE_FLOW_DISABLE_BRIDGE;
+ else process.env.CLAUDE_FLOW_DISABLE_BRIDGE = ORIGINAL_ENV;
+ rmSync(dir, { recursive: true, force: true });
+});
+
+describe('memory sql.js fallback WAL-sidecar guard β€” issue #2735', () => {
+ it('storeEntry refuses the whole-image write when -wal sidecar is present', async () => {
+ writeFileSync(`${dbPath}-wal`, '');
+ const { storeEntry } = await import('../src/memory/memory-initializer.js');
+ const result = await storeEntry({ key: 'k1', value: 'v1', dbPath });
+ expect(result.success).toBe(false);
+ expect(result.error).toMatch(/native WAL connection/i);
+ });
+
+ it('storeEntry refuses the whole-image write when -shm sidecar is present', async () => {
+ writeFileSync(`${dbPath}-shm`, '');
+ const { storeEntry } = await import('../src/memory/memory-initializer.js');
+ const result = await storeEntry({ key: 'k1', value: 'v1', dbPath });
+ expect(result.success).toBe(false);
+ expect(result.error).toMatch(/native WAL connection/i);
+ });
+
+ it('storeEntry proceeds normally with no sidecars present', async () => {
+ const { storeEntry } = await import('../src/memory/memory-initializer.js');
+ const result = await storeEntry({ key: 'k1', value: 'v1', dbPath, generateEmbeddingFlag: false });
+ expect(result.success).toBe(true);
+ expect(result.id).not.toBe('');
+ });
+
+ it('getEntry refuses the whole-image access_count-bump write when sidecars are present', async () => {
+ const { storeEntry } = await import('../src/memory/memory-initializer.js');
+ const stored = await storeEntry({ key: 'k2', value: 'v2', dbPath, generateEmbeddingFlag: false });
+ expect(stored.success).toBe(true);
+
+ writeFileSync(`${dbPath}-wal`, '');
+ const { getEntry } = await import('../src/memory/memory-initializer.js');
+ const result = await getEntry({ key: 'k2', dbPath });
+ expect(result.success).toBe(false);
+ expect(result.error).toMatch(/native WAL connection/i);
+ });
+
+ it('getEntry proceeds normally with no sidecars present', async () => {
+ const { storeEntry, getEntry } = await import('../src/memory/memory-initializer.js');
+ await storeEntry({ key: 'k3', value: 'v3', dbPath, generateEmbeddingFlag: false });
+ const result = await getEntry({ key: 'k3', dbPath });
+ expect(result.success).toBe(true);
+ expect(result.found).toBe(true);
+ });
+
+ it('deleteEntry refuses the whole-image write when sidecars are present', async () => {
+ const { storeEntry } = await import('../src/memory/memory-initializer.js');
+ await storeEntry({ key: 'k4', value: 'v4', dbPath, generateEmbeddingFlag: false });
+
+ writeFileSync(`${dbPath}-shm`, '');
+ const { deleteEntry } = await import('../src/memory/memory-initializer.js');
+ const result = await deleteEntry({ key: 'k4', dbPath });
+ expect(result.success).toBe(false);
+ expect(result.error).toMatch(/native WAL connection/i);
+ });
+
+ it('deleteEntry proceeds normally with no sidecars present', async () => {
+ const { storeEntry, deleteEntry } = await import('../src/memory/memory-initializer.js');
+ await storeEntry({ key: 'k5', value: 'v5', dbPath, generateEmbeddingFlag: false });
+ const result = await deleteEntry({ key: 'k5', dbPath });
+ expect(result.success).toBe(true);
+ expect(result.deleted).toBe(true);
+ });
+
+ it('a refused store never touches the database file (no whole-image write occurred)', async () => {
+ const before = existsSync(dbPath) ? require('node:fs').statSync(dbPath).mtimeMs : 0;
+ writeFileSync(`${dbPath}-wal`, '');
+ const { storeEntry } = await import('../src/memory/memory-initializer.js');
+ const result = await storeEntry({ key: 'k6', value: 'v6', dbPath });
+ expect(result.success).toBe(false);
+ const after = require('node:fs').statSync(dbPath).mtimeMs;
+ expect(after).toBe(before);
+ });
+});
diff --git a/v3/@claude-flow/cli/src/memory/memory-bridge.ts b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
index 025451be4a..d8495e9805 100644
--- a/v3/@claude-flow/cli/src/memory/memory-bridge.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
@@ -27,6 +27,29 @@ let registryPromise: Promise<any> | null = null;
let registryInstance: any = null;
let bridgeAvailable: boolean | null = null;
+// #2735 β€” the native-bridge -> sql.js whole-image fallback used to be
+// completely silent: a registry init failure cached `bridgeAvailable =
+// false` for the rest of the process, and a per-operation bridge exception
+// swallowed itself with a bare `catch { return null; }` β€” in both cases the
+// caller fell back to memory-initializer.ts's unsafe whole-image sql.js
+// path with zero diagnostic trail. When that path corrupted a database, the
+// demotion that caused it was structurally unknowable after the fact. Log
+// once per distinct reason (not once per call β€” a hot per-op catch could
+// otherwise spam stderr on every single memory operation) so the first
+// occurrence is attributable. Stderr only β€” never stdout, which callers may
+// be parsing as JSON.
+const loggedDemotions = new Set<string>();
+function logDemotionOnce(where: string, reason: string): void {
+ const dedupeKey = `${where}:${reason}`;
+ if (loggedDemotions.has(dedupeKey)) return;
+ loggedDemotions.add(dedupeKey);
+ try {
+ process.stderr.write(
+ `[memory-bridge] demoted to sql.js fallback in ${where}: ${reason}\n`,
+ );
+ } catch { /* stderr unavailable β€” nothing more we can do */ }
+}
+
/**
* Resolve database path with path traversal protection.
* Only allows paths within or below the project's working directory,
@@ -325,9 +348,13 @@ async function getRegistry(dbPath?: string): Promise<any | null> {
registryInstance = registry;
bridgeAvailable = true;
return registry;
- } catch {
+ } catch (err) {
bridgeAvailable = false;
registryPromise = null;
+ logDemotionOnce(
+ 'getRegistry (process-wide, cached for the rest of this process)',
+ err instanceof Error ? err.message : String(err),
+ );
return null;
}
})();
@@ -795,7 +822,8 @@ export async function bridgeStoreEntry(options: {
cached: true,
attested: true,
};
- } catch {
+ } catch (err) {
+ logDemotionOnce('bridgeStoreEntry', err instanceof Error ? err.message : String(err));
return null;
}
}
@@ -1158,7 +1186,8 @@ export async function bridgeGetEntry(options: {
await cacheSet(registry, cacheKey, entry);
return { success: true, found: true, cacheHit: false, entry };
- } catch {
+ } catch (err) {
+ logDemotionOnce('bridgeGetEntry', err instanceof Error ? err.message : String(err));
return null;
}
}
@@ -1234,7 +1263,8 @@ export async function bridgeDeleteEntry(options: {
remainingEntries: remaining,
guarded: true,
};
- } catch {
+ } catch (err) {
+ logDemotionOnce('bridgeDeleteEntry', err instanceof Error ? err.message : String(err));
return null;
}
}
@@ -1298,7 +1328,8 @@ export async function bridgePurgeNamespace(options: {
remainingEntries: remaining,
guarded: true,
};
- } catch {
+ } catch (err) {
+ logDemotionOnce('bridgePurgeNamespace', 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 fb5490bea0..1147acba36 100644
--- a/v3/@claude-flow/cli/src/memory/memory-initializer.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
@@ -36,6 +36,33 @@ function isRuvectorCoreResolvable(): boolean {
return _ruvectorCoreResolvable;
}
+/**
+ * #2735 β€” before a whole-image sql.js read-modify-persist (export() +
+ * rename over the live database path), refuse if there is evidence of a
+ * live native (better-sqlite3) WAL connection: `-wal`/`-shm` sidecar files
+ * on disk. A native connection in WAL mode keeps its sidecars present for
+ * its entire lifetime (removed only on the last connection's clean close),
+ * so their presence is strong evidence of a live native holder β€” and their
+ * absence means the image is a clean, checkpointed, standalone file that
+ * sql.js can safely read-modify-write.
+ *
+ * This is a scoped-down version of the fuller "scan live process holders"
+ * design discussed in #2735: it does not close the narrow assess-then-write
+ * race (a native opener could still attach in the gap between this check
+ * and the write), but it directly closes the demonstrated corruption
+ * mechanism β€” a whole-image write proceeding while an ALREADY-OPEN native
+ * connection's sidecars are on disk β€” with no platform-specific process
+ * scanning. Fails closed (treats a stat error as "unsafe") because this is
+ * a safety gate, not a best-effort probe.
+ */
+function hasNativeWalSidecars(dbPath: string): boolean {
+ try {
+ return fs.existsSync(`${dbPath}-wal`) || fs.existsSync(`${dbPath}-shm`);
+ } catch {
+ return true;
+ }
+}
+
/**
* #1854: previously every site that needed the memory directory hardcoded
* `getMemoryRoot()`, so the documented config entry
@@ -2668,6 +2695,23 @@ export async function storeEntry(options: {
return { success: false, id: '', error: 'Database not initialized. Run: claude-flow memory init' };
}
+ // #2735 β€” refuse an unsafe whole-image write while a native WAL
+ // connection appears to be attached (sidecars on disk). See
+ // hasNativeWalSidecars()'s doc comment for the corruption mechanism
+ // this closes and its known residual (the narrow assess-then-write
+ // race). This check gates ensureSchemaColumns()'s own whole-image
+ // write below too, not just this function's.
+ if (hasNativeWalSidecars(dbPath)) {
+ return {
+ success: false,
+ id: '',
+ error: 'memory database has an active native WAL connection ' +
+ '(found -wal/-shm sidecar files) β€” refusing an unsafe sql.js ' +
+ 'whole-image write. Retry once the native writer completes, or ' +
+ 'restore the native better-sqlite3 bridge.',
+ };
+ }
+
// Ensure schema has all required columns (migration for older DBs)
await ensureSchemaColumns(dbPath);
@@ -3179,6 +3223,21 @@ export async function getEntry(options: {
return { success: false, found: false, error: 'Database not found' };
}
+ // #2735 β€” see storeEntry's identical gate for the corruption mechanism
+ // this closes. Applies here too because the fallback's access_count
+ // bump is itself a whole-image write, not a lightweight read, even
+ // though this function's contract reads as a "get".
+ if (hasNativeWalSidecars(dbPath)) {
+ return {
+ success: false,
+ found: false,
+ error: 'memory database has an active native WAL connection ' +
+ '(found -wal/-shm sidecar files) β€” refusing an unsafe sql.js ' +
+ 'whole-image read/write. Retry once the native writer completes, ' +
+ 'or restore the native better-sqlite3 bridge.',
+ };
+ }
+
// Ensure schema has all required columns (migration for older DBs)
await ensureSchemaColumns(dbPath);
@@ -3320,6 +3379,22 @@ export async function deleteEntry(options: {
};
}
+ // #2735 β€” see storeEntry's identical gate for the corruption mechanism
+ // this closes.
+ if (hasNativeWalSidecars(dbPath)) {
+ return {
+ success: false,
+ deleted: false,
+ key,
+ namespace,
+ remainingEntries: 0,
+ error: 'memory database has an active native WAL connection ' +
+ '(found -wal/-shm sidecar files) β€” refusing an unsafe sql.js ' +
+ 'whole-image write. Retry once the native writer completes, or ' +
+ 'restore the native better-sqlite3 bridge.',
+ };
+ }
+
// Ensure schema has all required columns (migration for older DBs)
await ensureSchemaColumns(dbPath);