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): 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.mjs
index 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.ts
new file mode 100644
index 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.ts
index 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?: { createIfMissin
const 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?: { createIfMissin
CREATE 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.ts
index 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,