π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.tsnew file mode 100644index 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.tsindex 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.tsindex 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);