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): honest agentdb_pattern-store failures; share AgentDB's better-sqlite3 for graph writer (#3691, #3693)

ruv67261ac049dc
diff --git a/v3/@claude-flow/cli/__tests__/agentdb-pattern-store-honest-3691.test.ts b/v3/@claude-flow/cli/__tests__/agentdb-pattern-store-honest-3691.test.ts
new file mode 100644
index 0000000000..326ba4994c
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/agentdb-pattern-store-honest-3691.test.ts
@@ -0,0 +1,75 @@
+/**
+ * Regression for #3691: agentdb_pattern-store acknowledged persistence
+ * ("success: true") even when the underlying write returned {success:false}.
+ * - registry-null fallback ignored storeEntry's result
+ * - bridgeStorePattern's bridge-fallback only checked `!result`, so a
+ * structured {success:false} became a successful receipt
+ */
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const bridgeStorePattern = vi.fn();
+const storeEntry = vi.fn();
+vi.mock('../src/memory/memory-bridge.js', async (orig) => ({
+ ...(await orig<any>()),
+ bridgeStorePattern: (...a: unknown[]) => bridgeStorePattern(...a),
+}));
+vi.mock('../src/memory/memory-initializer.js', async (orig) => ({
+ ...(await orig<any>()),
+ storeEntry: (...a: unknown[]) => storeEntry(...a),
+}));
+
+import { agentdbPatternStore } from '../src/mcp-tools/agentdb-tools.js';
+
+beforeEach(() => { bridgeStorePattern.mockReset(); storeEntry.mockReset(); });
+
+describe('#3691 agentdb_pattern-store reports failed persistence honestly', () => {
+ it('registry-null fallback: storeEntry {success:false} is NOT acknowledged', async () => {
+ bridgeStorePattern.mockResolvedValue(null);
+ storeEntry.mockResolvedValue({ success: false, id: '', error: 'disk full' });
+ const r: any = await agentdbPatternStore.handler({ pattern: 'p', type: 't' });
+ expect(r.success).toBe(false);
+ expect(r.patternId).toBeUndefined();
+ expect(JSON.stringify(r)).toContain('disk full');
+ });
+
+ it('registry-null fallback: storeEntry success still acknowledged as degraded', async () => {
+ bridgeStorePattern.mockResolvedValue(null);
+ storeEntry.mockResolvedValue({ success: true, id: 'x' });
+ const r: any = await agentdbPatternStore.handler({ pattern: 'p', type: 't' });
+ expect(r.success).toBe(true);
+ expect(r.degraded).toBe(true);
+ });
+
+ it('bridge returning structured success:false is passed through as failure', async () => {
+ bridgeStorePattern.mockResolvedValue({ success: false, patternId: '', controller: 'bridge-fallback', error: 'guard rejected' });
+ const r: any = await agentdbPatternStore.handler({ pattern: 'p', type: 't' });
+ expect(r.success).toBe(false);
+ expect(r.error).toContain('guard rejected');
+ expect(r.degraded).toBeUndefined();
+ expect(JSON.stringify(r)).not.toMatch(/persisted via/i);
+ });
+});
+
+describe('#3691 bridgeStorePattern bridge-fallback refuses a failed write', () => {
+ it('returns success:false (not a receipt) when the SQL write throws/returns failure', async () => {
+ const real = await vi.importActual<typeof import('../src/memory/memory-bridge.js')>('../src/memory/memory-bridge.js');
+ const stub = {
+ prepare() { return { run: () => ({ changes: 0 }), get: () => undefined, all: () => [] }; },
+ exec() { /* schema no-op */ },
+ pragma() { return []; },
+ };
+ real.__setMemoryBridgeRegistryForTests({
+ getAgentDB: () => ({ database: stub, embedder: null }),
+ get: () => null,
+ } as any);
+ try {
+ const r: any = await real.bridgeStorePattern({ pattern: 'p', type: 't', confidence: 0.5, dbPath: '/nonexistent/x.db' });
+ // A write that persisted nothing (changes=0) must never become a success receipt
+ expect(r).not.toBeNull();
+ expect(r.success).toBe(false);
+ expect(r.patternId).toBeFalsy();
+ } finally {
+ real.__setMemoryBridgeRegistryForTests(null);
+ }
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/graph-writer-shared-sqlite-3693.test.ts b/v3/@claude-flow/cli/__tests__/graph-writer-shared-sqlite-3693.test.ts
new file mode 100644
index 0000000000..b719ee9fbf
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/graph-writer-shared-sqlite-3693.test.ts
@@ -0,0 +1,94 @@
+/**
+ * #3693: a CLI-owned better-sqlite3 handle opened through a DIFFERENT installed
+ * copy than AgentDB's must not delete the -wal/-shm sidecars of a live AgentDB
+ * handle when the graph writer's idle release closes it.
+ *
+ * Deterministic: real native modules (a second copy of the built binary is
+ * placed in a temp "agentdb" tree), fake timers drive the idle close.
+ */
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { createRequire } from 'node:module';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const req = createRequire(import.meta.url);
+const root = mkdtempSync(join(tmpdir(), 'ruflo-3693-'));
+const agentdbDir = join(root, 'node_modules', 'agentdb');
+const agentdbEntry = join(agentdbDir, 'index.js');
+let HolderCtor: any;
+let native = true;
+
+beforeAll(() => {
+ try {
+ const pkgDir = dirname(req.resolve('better-sqlite3/package.json'));
+ const nm = join(agentdbDir, 'node_modules');
+ mkdirSync(nm, { recursive: true });
+ writeFileSync(agentdbEntry, '');
+ cpSync(pkgDir, join(nm, 'better-sqlite3'), { recursive: true });
+ for (const dep of ['bindings', 'file-uri-to-path']) {
+ try { symlinkSync(dirname(req.resolve(`${dep}/package.json`)), join(nm, dep)); } catch { /* optional */ }
+ }
+ HolderCtor = createRequire(agentdbEntry)('better-sqlite3');
+ const probe = new HolderCtor(':memory:'); probe.close();
+ } catch { native = false; }
+});
+
+afterEach(() => { vi.useRealTimers(); vi.resetModules(); vi.doUnmock('../src/memory/shared-sqlite.js'); });
+
+const ino = (f: string) => (existsSync(f) ? statSync(f).ino : null);
+
+async function scenario(useShared: boolean) {
+ const dbPath = join(root, `m-${useShared}.db`);
+ const holder = new HolderCtor(dbPath);
+ holder.pragma('journal_mode=WAL');
+ holder.exec('create table memory_entries(x)');
+ holder.prepare('insert into memory_entries values(1)').run();
+ const before = [ino(dbPath + '-wal'), ino(dbPath + '-shm')];
+
+ process.env.CLAUDE_FLOW_GRAPH_EDGE_IDLE_MS = '50';
+ if (useShared) {
+ vi.doMock('../src/memory/shared-sqlite.js', () => ({
+ loadBetterSqlite3: async () => HolderCtor,
+ resolveAgentdbBetterSqlite3: () => HolderCtor,
+ }));
+ }
+ vi.useFakeTimers();
+ const gw = await import('../src/memory/graph-edge-writer.js');
+ const db = await gw.getBridgeDb(dbPath);
+ expect(db).not.toBeNull();
+ db.prepare('insert into memory_entries values(2)').run();
+ vi.advanceTimersByTime(60); // idle release fires: checkpoint(TRUNCATE) + close
+ vi.useRealTimers();
+ const after = [ino(dbPath + '-wal'), ino(dbPath + '-shm')];
+ holder.prepare('insert into memory_entries values(3)').run();
+ const integrity = holder.pragma('integrity_check');
+ holder.close();
+ return { before, after, integrity };
+}
+
+afterAll(() => { try { rmSync(root, { recursive: true, force: true }); } catch { /* */ } });
+
+describe('#3693 graph writer idle close vs live AgentDB handle', () => {
+ it('helper resolves the constructor from the agentdb dependency owner', async () => {
+ if (!native) return;
+ const { resolveAgentdbBetterSqlite3 } = await import('../src/memory/shared-sqlite.js');
+ expect(resolveAgentdbBetterSqlite3(agentdbEntry)).toBe(HolderCtor);
+ });
+
+ it("control: a different native copy DOES strip the live holder's sidecars (the hazard)", async () => {
+ if (!native) return;
+ const r = await scenario(false);
+ expect(r.before[0]).not.toBeNull();
+ expect(r.after).toEqual([null, null]);
+ });
+
+ it('graph writer sharing the holder copy leaves the WAL/SHM sidecars intact', async () => {
+ if (!native) return;
+ const r = await scenario(true);
+ expect(r.before[0]).not.toBeNull();
+ expect(r.after).toEqual(r.before);
+ expect(r.integrity).toEqual([{ integrity_check: 'ok' }]);
+ });
+});
+
diff --git a/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts
index 9b4f83a6ec..d0fac859ad 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts
@@ -162,6 +162,10 @@ export const agentdbPatternStore: MCPTool = {
const bridge = await getBridge();
const result = await bridge.bridgeStorePattern({ pattern, type, confidence });
+ if (result && result.success === false) {
+ // #3691: the write was refused/not persisted — never acknowledge it.
+ return { success: false, error: `Pattern store failed: ${result.error ?? 'write not persisted'}`, controller: result.controller };
+ }
if (result) {
// #3288: `controller: 'reasoningBank'` is the ONLY label that means
// the healthy path ran. Every other label bridgeStorePattern can
@@ -188,12 +192,20 @@ export const agentdbPatternStore: MCPTool = {
const { storeEntry } = await import('../memory/memory-initializer.js');
const patternId = `pattern-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
const value = JSON.stringify({ pattern, type, confidence, _fallback: 'reasoningBank-unavailable' });
- await storeEntry({
+ const stored = await storeEntry({
key: patternId,
value,
namespace: 'pattern',
tags: [type, 'reasoning-pattern', 'fallback'],
});
+ // #3691: storeEntry reports failure as {success:false}, not a throw.
+ if (!stored || stored.success !== true) {
+ return {
+ success: false,
+ error: `Pattern store failed: memory_store fallback did not persist (${stored?.error ?? 'no result'})`,
+ recommendation: 'Run agentdb_health to inspect controller registration and check that .swarm/memory.db is writable.',
+ };
+ }
return {
success: true,
// #3288: a caller must not have to already know to distrust a
diff --git a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
index c3ab3ba854..d0d784ddf4 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
@@ -3601,7 +3601,7 @@ export const hooksPatternStore: MCPTool = {
// Fallback: persist using memory-initializer store
let storeResult: { success: boolean; id?: string; embedding?: { dimensions: number; model: string }; error?: string } = { success: false };
- if (!reasoningResult) {
+ if (!reasoningResult?.success) {
const storeFn = await getRealStoreFunction();
if (storeFn) {
try {
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 5587388d1d..5193cfda17 100644
--- a/v3/@claude-flow/cli/src/memory/graph-edge-writer.ts
+++ b/v3/@claude-flow/cli/src/memory/graph-edge-writer.ts
@@ -35,6 +35,7 @@ import * as fs from 'fs';
import * as crypto from 'crypto';
import { getMemoryRoot } from './memory-initializer.js';
import { encodeEmbedding } from './embedding-quantization.js';
+import { loadBetterSqlite3 } from './shared-sqlite.js';
// ============================================================================
// Lazy-cached better-sqlite3 db handle
@@ -143,8 +144,8 @@ export async function getBridgeDb(customDbPath?: string, opts?: { createIfMissin
// the try/catch below.
let BetterSqlite3: any;
try {
- const mod: string = 'better-sqlite3';
- BetterSqlite3 = (await import(mod)).default;
+ // #3693: share AgentDB's better-sqlite3 so the idle close cannot detach its handle.
+ BetterSqlite3 = await loadBetterSqlite3();
} catch {
return null;
}
diff --git a/v3/@claude-flow/cli/src/memory/memory-bridge.ts b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
index 22f6d090f2..c1eff0fc24 100644
--- a/v3/@claude-flow/cli/src/memory/memory-bridge.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
@@ -18,6 +18,7 @@
*/
import { liveMemoryRowSql } from './live-memory-row.js';
+import { resolveAgentdbBetterSqlite3 } from './shared-sqlite.js';
import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS } from './embedding-q8.js';
import * as path from 'path';
import * as crypto from 'crypto';
@@ -432,7 +433,8 @@ async function getRegistry(dbPath?: string): Promise<any | null> {
try {
const attestationFile = path.join(adbDir, 'dist/src/security/AttestationLog.js');
if (fs.existsSync(attestationFile)) {
- const Database = (cjsRequire('better-sqlite3') as unknown) as new (p: string) => unknown;
+ // #3693: same better-sqlite3 copy AgentDB uses, so closing this handle cannot disturb its WAL.
+ const Database = ((resolveAgentdbBetterSqlite3() ?? cjsRequire('better-sqlite3')) as unknown) as new (p: string) => unknown;
const swarmDir = path.resolve(process.cwd(), '.swarm');
if (!fs.existsSync(swarmDir)) fs.mkdirSync(swarmDir, { recursive: true });
const dbPath = path.join(swarmDir, 'attestation.db');
@@ -2303,7 +2305,7 @@ export async function bridgeStorePattern(options: {
confidence: number;
metadata?: Record<string, unknown>;
dbPath?: string;
-}): Promise<{ success: boolean; patternId: string; controller: string; hasEmbedding?: boolean; embeddingError?: string } | null> {
+}): Promise<{ success: boolean; patternId: string; controller: string; hasEmbedding?: boolean; embeddingError?: string; error?: string } | null> {
if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeStorePattern(options));
const registry = await getRegistry(options.dbPath);
if (!registry) return null;
@@ -2354,6 +2356,18 @@ export async function bridgeStorePattern(options: {
if (!result) return null;
+ // #3691: bridgeStoreEntry reports data-level failures (MutationGuard
+ // rejection, nothing written) as a truthy {success:false}. Do not turn
+ // that into a success receipt — refuse at this boundary.
+ if (!result.success) {
+ return {
+ success: false,
+ patternId: '',
+ controller: 'bridge-fallback',
+ error: result.error ?? 'pattern write was not persisted',
+ };
+ }
+
// Add to HNSW index for fast semantic search (bridgeStoreEntry stores SQL only)
if (result.rawEmbedding) {
try {
diff --git a/v3/@claude-flow/cli/src/memory/memory-initializer.ts b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
index c017a16dd7..72584961bc 100644
--- a/v3/@claude-flow/cli/src/memory/memory-initializer.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
@@ -9,6 +9,7 @@
* @module v3/cli/memory-initializer
*/
+import { loadBetterSqlite3 } from './shared-sqlite.js';
import { liveMemoryRowSql } from './live-memory-row.js';
import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS, type EmbeddingQ8 } from './embedding-q8.js';
import * as fs from 'fs';
@@ -1606,8 +1607,8 @@ export async function recoverMemoryDatabase(
try {
// Module name behind a variable so TS does not statically resolve the
// optional native dep's types at build time (CI may not install them).
- const mod: string = 'better-sqlite3';
- Database = (await import(mod)).default;
+ // #3693: same better-sqlite3 identity as AgentDB (see shared-sqlite.ts).
+ Database = await loadBetterSqlite3();
} catch {
return await restoreFromBackup('no-native');
}
@@ -1723,8 +1724,8 @@ export async function repairVectorIndexes(
try {
// Module name behind a variable so TS does not statically resolve the
// optional native dep's types at build time (CI may not install them).
- const mod: string = 'better-sqlite3';
- Database = (await import(mod)).default;
+ // #3693: same better-sqlite3 identity as AgentDB (see shared-sqlite.ts).
+ Database = await loadBetterSqlite3();
} catch {
// Native module absent (e.g. WASM-only host). Statusline fix still covers
// the display; nothing to repair here.
diff --git a/v3/@claude-flow/cli/src/memory/shared-sqlite.ts b/v3/@claude-flow/cli/src/memory/shared-sqlite.ts
new file mode 100644
index 0000000000..08f9a9b1c0
--- /dev/null
+++ b/v3/@claude-flow/cli/src/memory/shared-sqlite.ts
@@ -0,0 +1,45 @@
+/**
+ * #3693 — one better-sqlite3 identity per process.
+ *
+ * AgentDB (via @claude-flow/memory) owns a live native handle on memory.db. If
+ * the CLI opens its own handle through a DIFFERENT installed copy of
+ * better-sqlite3 (a nested `agentdb/node_modules/better-sqlite3` next to a
+ * hoisted one is the common layout), the two copies each statically link their
+ * own SQLite and keep separate per-process file bookkeeping. Closing the CLI's
+ * handle (graph-edge idle release: wal_checkpoint(TRUNCATE) + close) then looks
+ * like "last connection" to that copy and deletes the -wal/-shm sidecars out
+ * from under AgentDB's still-open handle.
+ *
+ * Resolve the constructor from the same place AgentDB resolves it, so both
+ * share one SQLite instance (and its connection bookkeeping). Falls back to the
+ * CLI's own copy when agentdb cannot be resolved.
+ */
+import { createRequire } from 'node:module';
+
+type DbCtor = new (path: string, opts?: Record<string, unknown>) => any;
+
+let cached: DbCtor | null | undefined;
+
+/** Test seam: pass `from` to resolve relative to another entry file. */
+export function resolveAgentdbBetterSqlite3(from?: string): DbCtor | null {
+ if (!from && cached !== undefined) return cached;
+ let found: DbCtor | null = null;
+ try {
+ const own = createRequire(import.meta.url);
+ const agentdbEntry = from ?? own.resolve('agentdb');
+ const mod = createRequire(agentdbEntry)('better-sqlite3');
+ found = (mod?.default ?? mod) as DbCtor;
+ } catch {
+ found = null;
+ }
+ if (!from) cached = found;
+ return found;
+}
+
+/** Constructor shared with AgentDB when possible, else the CLI's own copy. */
+export async function loadBetterSqlite3(): Promise<DbCtor> {
+ const shared = resolveAgentdbBetterSqlite3();
+ if (shared) return shared;
+ const mod: string = 'better-sqlite3';
+ return (await import(mod)).default as DbCtor;
+}