π 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): release graph-edge-writer's native WAL handle so sql.js memory_store isn't refused (#3397) (#3405)
rUv72e17533ca6d
diff --git a/scripts/audit-env-var-precedence.mjs b/scripts/audit-env-var-precedence.mjsindex dd3ebf3787..22a9ed35eb 100644--- a/scripts/audit-env-var-precedence.mjs+++ b/scripts/audit-env-var-precedence.mjs@@ -53,6 +53,7 @@ const REPO_ROOT = resolve(__dirname, '..');const KNOWN_ESCAPE_HATCHES = new Set([// ββ CI / test escape hatches ββββββββββββββββββββββββββββββββββββββββββββββββ'CLAUDE_FLOW_DISABLE_BRIDGE', // CI/test: force raw sql.js path β intentionally no CLI flag+ 'CLAUDE_FLOW_GRAPH_EDGE_IDLE_MS', // CI/test tuning: idle-close window (ms) for graph-edge-writer's native WAL handle (#3397). Internal lifecycle knob with a safe default (1000); no user-facing command owns it, so no CLI flag.'RUFLO_ADMIN_TOKEN', // credential: the x.ruv.io gateway's OWN admin token, read by plugins/ruflo-x-gateway. Env-only by design β a secret must never be a CLI flag (shell history / process lists), and the gateway is a service with no typed command surface at all.'RUFLO_SERAPHINA_DAILY_CAP', // gateway spend guard (#3275): shared daily Seraphina budget. Read by a long-running service, not a typed command β there is no invocation to attach a flag to.'RUFLO_SERAPHINA_IP_HOURLY_CAP',// gateway spend guard (#3275): per-client hourly Seraphina budget. Same service-only reasoning.diff --git a/v3/@claude-flow/cli/__tests__/issue-3397-graph-edge-handle-release.test.ts b/v3/@claude-flow/cli/__tests__/issue-3397-graph-edge-handle-release.test.tsnew file mode 100644index 0000000000..430d47c9c9--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/issue-3397-graph-edge-handle-release.test.ts@@ -0,0 +1,93 @@+/**+ * #3397 β graph-edge-writer cached its better-sqlite3 WAL handle in a module+ * singleton for the whole life of the MCP server. The `-wal`/`-shm` sidecars+ * therefore stayed on disk forever, and the #2735 guard (correctly) refused+ * every later sql.js whole-image write: after one `hooks_post-task`, every+ * `memory_store` in that server failed with "active native WAL connection".+ *+ * The reported symptom is Windows-only because that is where the native+ * AgentDB bridge is disabled by default (#3024), so `memory_store` takes the+ * sql.js path. The handle lifecycle and the guard decision are+ * platform-independent, so they are exercised here on the sql.js path by+ * forcing CLAUDE_FLOW_DISABLE_BRIDGE=1. Windows' mandatory file locking is+ * NOT reproduced by this test.+ */+import { afterEach, beforeEach, describe, expect, it } from 'vitest';+import { existsSync, mkdtempSync, rmSync } from 'node:fs';+import { createRequire } from 'node:module';+import { tmpdir } from 'node:os';+import path from 'node:path';++let dir: string;+let dbPath: string;+const ORIGINAL_BRIDGE = process.env.CLAUDE_FLOW_DISABLE_BRIDGE;+const ORIGINAL_IDLE = process.env.CLAUDE_FLOW_GRAPH_EDGE_IDLE_MS;++const sidecars = () => existsSync(`${dbPath}-wal`) || existsSync(`${dbPath}-shm`);+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));++beforeEach(async () => {+ dir = mkdtempSync(path.join(tmpdir(), 'ruflo-3397-'));+ dbPath = path.join(dir, 'memory.db');+ process.env.CLAUDE_FLOW_DISABLE_BRIDGE = '1';+ const { initializeMemoryDatabase } = await import('../src/memory/memory-initializer.js');+ expect((await initializeMemoryDatabase({ dbPath, verbose: false })).success).toBe(true);+ expect(sidecars()).toBe(false);+});++afterEach(async () => {+ const { _resetBridgeDb } = await import('../src/memory/graph-edge-writer.js');+ _resetBridgeDb();+ if (ORIGINAL_BRIDGE === undefined) delete process.env.CLAUDE_FLOW_DISABLE_BRIDGE;+ else process.env.CLAUDE_FLOW_DISABLE_BRIDGE = ORIGINAL_BRIDGE;+ if (ORIGINAL_IDLE === undefined) delete process.env.CLAUDE_FLOW_GRAPH_EDGE_IDLE_MS;+ else process.env.CLAUDE_FLOW_GRAPH_EDGE_IDLE_MS = ORIGINAL_IDLE;+ rmSync(dir, { recursive: true, force: true });+});++describe('#3397 graph-edge-writer releases its native WAL handle', () => {+ it('a sql.js memory store right after a graph-edge write succeeds and keeps the edge', async () => {+ const { insertGraphEdge, countGraphEdges } = await import('../src/memory/graph-edge-writer.js');+ const { storeEntry } = await import('../src/memory/memory-initializer.js');++ expect(await insertGraphEdge({ sourceId: 'task-1', targetId: 'agent-1', relation: 'assigned_to', dbPath })).toBe(true);+ // The writer's own handle is what put the sidecars there.+ expect(sidecars()).toBe(true);++ const stored = await storeEntry({ key: 'after-edge', value: 'v', dbPath, generateEmbeddingFlag: false });+ expect(stored.error).toBeUndefined();+ expect(stored.success).toBe(true);++ // The edge was checkpointed into the main file before sql.js rewrote the+ // image, so the whole-image write did not drop it.+ expect(await countGraphEdges(dbPath)).toBe(1);+ });++ it('closes the handle after an idle window, so the sidecars disappear on their own', async () => {+ process.env.CLAUDE_FLOW_GRAPH_EDGE_IDLE_MS = '50';+ const { insertGraphEdge } = await import('../src/memory/graph-edge-writer.js');++ expect(await insertGraphEdge({ sourceId: 'a', targetId: 'b', relation: 'rel', dbPath })).toBe(true);+ expect(sidecars()).toBe(true);++ await sleep(400);+ expect(sidecars()).toBe(false);+ });++ it('still refuses the sql.js write while a foreign native WAL connection is attached', async () => {+ const { storeEntry } = await import('../src/memory/memory-initializer.js');+ const Database = createRequire(import.meta.url)('better-sqlite3');+ const foreign = new Database(dbPath);+ try {+ foreign.pragma('journal_mode = WAL');+ foreign.prepare('SELECT 1').get();+ expect(sidecars()).toBe(true);++ const result = await storeEntry({ key: 'blocked', value: 'v', dbPath, generateEmbeddingFlag: false });+ expect(result.success).toBe(false);+ expect(result.error).toMatch(/native WAL connection/i);+ } finally {+ foreign.close();+ }+ });+});diff --git a/v3/@claude-flow/cli/src/memory/graph-edge-writer.ts b/v3/@claude-flow/cli/src/memory/graph-edge-writer.tsindex a286e9c7be..5587388d1d 100644--- a/v3/@claude-flow/cli/src/memory/graph-edge-writer.ts+++ b/v3/@claude-flow/cli/src/memory/graph-edge-writer.ts@@ -44,6 +44,61 @@ let _db: any = null;let _dbPath = '';let _dbInitializing = false;+// #3397 β the handle used to live for the whole MCP server process, keeping+// the -wal/-shm sidecars on disk forever; the #2735 guard then refused every+// later sql.js whole-image write (memory_store on Windows, where the native+// bridge is off by default). The handle is now released after a short idle+// window, and memory-initializer releases it on demand before its guard.+//+// Invariant this relies on: every caller of getBridgeDb() finishes using the+// returned handle synchronously after the await (no await between it and the+// last `db.` call), so a release can only land between operations. If a+// caller ever breaks that, it gets "database connection is not open", which+// every call site already catches.+const DEFAULT_IDLE_RELEASE_MS = 1000;+let _idleTimer: ReturnType<typeof setTimeout> | null = null;+let _exitHookInstalled = false;++function idleReleaseMs(): number {+ const configured = Number(process.env.CLAUDE_FLOW_GRAPH_EDGE_IDLE_MS);+ return Number.isFinite(configured) && configured >= 0 ? configured : DEFAULT_IDLE_RELEASE_MS;+}++function armIdleRelease(): void {+ if (_idleTimer) clearTimeout(_idleTimer);+ _idleTimer = setTimeout(() => { _idleTimer = null; releaseBridgeDb(); }, idleReleaseMs());+ _idleTimer.unref?.();+ if (!_exitHookInstalled) {+ _exitHookInstalled = true;+ // 'exit' (not SIGINT/SIGTERM handlers, which would change Node's default+ // termination) β sync-only work, so a clean shutdown checkpoints and+ // removes the sidecars instead of leaving them for the next process.+ process.once('exit', () => { releaseBridgeDb(); });+ }+}++/**+ * Checkpoint and close the cached handle if it is open (optionally only if it+ * is open on `dbPath`). Returns true if a handle was released. Never throws.+ *+ * busy_timeout is dropped to 0 first so the TRUNCATE checkpoint cannot stall+ * the event loop behind another connection: if another native connection is+ * attached the sidecars stay anyway (it owns them), so a busy checkpoint loses+ * nothing; if this is the only connection, the checkpoint is never busy.+ */+export function releaseBridgeDb(dbPath?: string): boolean {+ if (!_db) return false;+ if (dbPath !== undefined && path.resolve(dbPath) !== path.resolve(_dbPath)) return false;+ if (_idleTimer) { clearTimeout(_idleTimer); _idleTimer = null; }+ const db = _db;+ _db = null;+ _dbPath = '';+ try { db.pragma('busy_timeout = 0'); } catch { /* best-effort */ }+ try { db.pragma('wal_checkpoint(TRUNCATE)'); } catch { /* best-effort */ }+ try { db.close(); } catch { /* best-effort */ }+ return true;+}+/*** Return the better-sqlite3 Database instance for graph_edges writes.* Creates the graph_edges table if it is absent (idempotent).@@ -61,7 +116,7 @@ export async function getBridgeDb(customDbPath?: string, opts?: { createIfMissinconst dbPath = customDbPath ?? path.join(getMemoryRoot(), 'memory.db');const createIfMissing = opts?.createIfMissing === true;- if (_db && _dbPath === dbPath) return _db;+ if (_db && _dbPath === dbPath) { armIdleRelease(); return _db; }if (_dbInitializing) return null;_dbInitializing = true;@@ -127,8 +182,12 @@ export async function getBridgeDb(customDbPath?: string, opts?: { createIfMissinCREATE INDEX IF NOT EXISTS idx_graph_edges_reinforced ON graph_edges (last_reinforced);`);+ // A handle cached for a different path would otherwise be orphaned+ // (still open, sidecars still on disk) by the reassignment below.+ releaseBridgeDb();_db = db;_dbPath = dbPath;+ armIdleRelease();return db;} catch {return null;@@ -267,6 +326,7 @@ export async function countGraphEdges(dbPath?: string): Promise<number> {* writes deterministically, regardless of platform/timing.*/export function _resetBridgeDb(): void {+ if (_idleTimer) { clearTimeout(_idleTimer); _idleTimer = null; }if (_db) {try { _db.pragma('wal_checkpoint(TRUNCATE)'); } catch { /* best-effort */ }try { _db.close(); } catch { /* best-effort */ }diff --git a/v3/@claude-flow/cli/src/memory/memory-initializer.ts b/v3/@claude-flow/cli/src/memory/memory-initializer.tsindex b0d82635da..634c4df7ea 100644--- a/v3/@claude-flow/cli/src/memory/memory-initializer.ts+++ b/v3/@claude-flow/cli/src/memory/memory-initializer.ts@@ -85,6 +85,23 @@ function hasNativeWalSidecars(dbPath: string): boolean {}}+/**+ * #3397 β this process's own graph-edge-writer handle keeps -wal/-shm on disk+ * between its idle-release ticks. Release (checkpoint + close) it before the+ * #2735 guard runs, so the guard only sees sidecars some OTHER native+ * connection is holding. The guard itself is unchanged: even a same-process+ * open WAL connection makes a whole-image sql.js write unsafe until its WAL+ * has been checkpointed, which is exactly what releasing does.+ */+async function releaseOwnNativeHandle(dbPath: string): Promise<void> {+ try {+ const { releaseBridgeDb } = await import('./graph-edge-writer.js');+ releaseBridgeDb(dbPath);+ } catch {+ // Writer module unavailable β nothing of ours to release; the guard decides.+ }+}+/*** #1854: previously every site that needed the memory directory hardcoded* `getMemoryRoot()`, so the documented config entry@@ -2945,6 +2962,7 @@ export async function storeEntry(options: {// 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.+ await releaseOwnNativeHandle(dbPath);if (hasNativeWalSidecars(dbPath)) {return {success: false,@@ -3619,6 +3637,7 @@ export async function getEntry(options: {// 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".+ await releaseOwnNativeHandle(dbPath);if (hasNativeWalSidecars(dbPath)) {return {success: false,@@ -3769,6 +3788,7 @@ export async function deleteEntry(options: {// #2735 β see storeEntry's identical gate for the corruption mechanism// this closes.+ await releaseOwnNativeHandle(dbPath);if (hasNativeWalSidecars(dbPath)) {return {success: false,