@claude-flow/cli 3.42.0 → 3.42.2

package/.claude/helpers/.helpers-version

@@ -1 +1 @@
-3.42.0
+3.42.2

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.42.0",
+    "version": "3.42.2",
     "files": {
       "auto-memory-hook.mjs": "85fe05c757421c52137c0bc8545a0896bab6b4714538c2a11d1d0835bfcc8c1c",
       "hook-handler.cjs": "209d9fafe10e17d1be0866727f6f9cf9ac66f9a0793f1c793a4f58319e8e4583",
@@ -8,6 +8,6 @@
       "statusline.cjs": "4a48353b4f1566fa4379b00fd0321b6676a22b6cc91fbbd8380ac5183d619468"
     }
   },
-  "signature": "Sk/d/KcF51uXVXWVYWTuNHw1s3Rl3uLg87zI0tzfsqutQtUISPujuCmxdnV6lZ1tC0gXP0cbLRMtIdqCPLNvAQ==",
+  "signature": "BP9fvsTRg7yqAXGECf5zxGSUx6E4GwF7XkApK7VgX+4zW5+6kIg6RMeTlu///RzbZW0xa6jqHU/hZE4I2ydrDA==",
   "algorithm": "ed25519"
 }

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 6,
-  "generatedAt": "2026-09-15T00:43:36.860Z",
-  "gitSha": "2abc9292",
+  "generatedAt": "2026-09-16T02:58:04.943Z",
+  "gitSha": "6debd741",
   "catalog": {
     "agents": 167,
     "tools": 418,

package/dist/src/commands/doctor.d.ts

@@ -5,6 +5,13 @@
  * Created with ruv.io
  */
 import type { Command } from '../types.js';
+interface HealthCheck {
+    name: string;
+    status: 'pass' | 'warn' | 'fail';
+    message: string;
+    fix?: string;
+}
+export declare function checkMemoryPersistenceDriver(): Promise<HealthCheck>;
 export declare const doctorCommand: Command;
 export default doctorCommand;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/src/commands/doctor.js

@@ -506,23 +506,13 @@ async function checkMemoryStructuralIntegrity() {
         catch { /* best-effort */ }
     }
 }
-// #2968 option 1 — read-only doctor check for the active SQLite driver.
-//
-// Native better-sqlite3 (durable, WAL-capable) can silently degrade to the
-// sql.js WASM fallback (non-durable — `wal_checkpoint` calls are rejected
-// and the write is lost) when a postinstall script is skipped. `memory
-// store` still printed "Data stored successfully" before the persistWarning
-// fix in #2983/3.38.1 (see memory-store-persist-warning-2968.test.ts); this
-// check gives a standing, read-only signal so the driver split is visible
-// any time doctor runs, independent of any single store call.
-//
-// Table count in the on-disk memory.db is the cheap, reliable signal from
-// the issue report: the native driver's schema produces 47 tables, the
-// sql.js fallback's produces only 10. Deliberately does NOT change install
-// behavior (that's option 2 from #2968, explicitly out of scope here) —
-// this only reports, it never repairs.
-const MEMORY_DRIVER_NATIVE_TABLE_FLOOR = 20; // roughly midpoint of sql.js's ~10 and native's ~47
-async function checkMemoryPersistenceDriver() {
+// #2968/#3321 — read-only native SQLite capability probe. A skipped
+// postinstall can leave the wrapper importable but its binding unavailable.
+// Schema size cannot identify the runtime driver or the database's history:
+// memory init creates its schema with sql.js even when native is available.
+// This probe does not verify schema compatibility or cross-process writes;
+// integrity checks and memory store's persistWarning retain their own roles.
+export async function checkMemoryPersistenceDriver() {
     const NAME = 'Memory Persistence Driver';
     const dbPath = await resolveMemoryDbPath();
     if (!dbPath) {
@@ -549,6 +539,7 @@ async function checkMemoryPersistenceDriver() {
     let tableCount = null;
     let nativeUnavailableReason = null;
     let nativeOpenOtherError = null;
+    let nativeQueryError = null;
     if (Database) {
         let db;
         try {
@@ -566,10 +557,15 @@ async function checkMemoryPersistenceDriver() {
         if (db) {
             try {
                 const row = db.prepare("SELECT count(*) AS c FROM sqlite_master WHERE type='table'").get();
-                tableCount = Number(row?.c ?? 0);
+                if (typeof row?.c === 'number' && Number.isSafeInteger(row.c) && row.c >= 0) {
+                    tableCount = row.c;
+                }
+                else {
+                    nativeQueryError = 'query returned no reliable table count';
+                }
             }
-            catch {
-                // leave null — Memory Integrity above already reports open/query failures
+            catch (e) {
+                nativeQueryError = e.message || String(e);
             }
             finally {
                 try {
@@ -589,7 +585,10 @@ async function checkMemoryPersistenceDriver() {
         if (sdb) {
             try {
                 const res = sdb.exec("SELECT count(*) FROM sqlite_master WHERE type='table'");
-                tableCount = Number(res[0]?.values?.[0]?.[0] ?? 0);
+                const count = res[0]?.values?.[0]?.[0];
+                if (typeof count === 'number' && Number.isSafeInteger(count) && count >= 0) {
+                    tableCount = count;
+                }
             }
             catch {
                 // leave null
@@ -604,12 +603,12 @@ async function checkMemoryPersistenceDriver() {
     }
     const tableSummary = tableCount === null
         ? 'table count unavailable'
-        : `${tableCount} tables (native schema ~47, sql.js-fallback schema ~10 — #2968)`;
+        : `${tableCount} tables`;
     if (nativeUnavailableReason) {
         return {
             name: NAME,
             status: 'warn',
-            message: `${dbPath} — active driver: sql.js (WASM fallback, non-durable) — native better-sqlite3 binding unavailable: ${nativeUnavailableReason} — wal_checkpoint calls silently no-op, writes may not persist across processes (#2968/#2867/#2219) [${tableSummary}]`,
+            message: `${dbPath} — native better-sqlite3 binding unavailable: ${nativeUnavailableReason} — native read-only probe unavailable; runtime driver and write persistence not verified (#2968) [${tableSummary}; sql.js main-image-only fallback]`,
             fix: 'reinstall with npm install scripts enabled, or run `npm rebuild better-sqlite3`; then rerun this check',
         };
     }
@@ -620,18 +619,17 @@ async function checkMemoryPersistenceDriver() {
             message: `${dbPath} — native better-sqlite3 module loadable, but could not open this database (${nativeOpenOtherError}) — see Memory Integrity above for the corruption/encryption diagnosis [${tableSummary}]`,
         };
     }
-    if (tableCount !== null && tableCount < MEMORY_DRIVER_NATIVE_TABLE_FLOOR) {
+    if (nativeQueryError || tableCount === null) {
         return {
             name: NAME,
             status: 'warn',
-            message: `${dbPath} — active driver: native better-sqlite3, but this database has only ${tableCount} tables — that matches the sql.js-fallback schema shape (~10), not the native schema (~47); it was likely created before the native binding became available, and durable writes made before then may be missing`,
-            fix: 'back up .swarm/memory.db then `claude-flow memory init --force` to rebuild under the native driver',
+            message: `${dbPath} — native better-sqlite3 opened read-only, but table count unavailable: ${nativeQueryError ?? 'query returned no reliable result'}; runtime driver and write persistence not verified`,
         };
     }
     return {
         name: NAME,
         status: 'pass',
-        message: `${dbPath} — active driver: native better-sqlite3 (durable, WAL-capable) [${tableSummary}]`,
+        message: `${dbPath} — native better-sqlite3 read-only open and schema query succeeded [${tableSummary}]; runtime driver, schema compatibility, and write persistence not verified`,
     };
 }
 // Check 1 (--component memory, deep path) — #2737 part 2 strengthens this:
@@ -2011,20 +2009,45 @@ async function checkMetaharnessDeclaredPackages() {
 }
 async function checkMetaharness() {
     try {
-        const version = await runCommand('npx -y metaharness@latest --version 2>&1', 15000);
-        // metaharness emits multi-line stdout; parse a version-shaped line.
-        const versionMatch = version.match(/(\d+\.\d+\.\d+)/);
-        if (!versionMatch) {
+        // `metaharness` has no --version flag (it falls through to the usage
+        // banner, which never matches a version regex) and shelling out via
+        // `npx metaharness@latest` ignores the installed version and hits the
+        // network every run. Resolve the version from the installed package's
+        // own package.json instead. `import.meta.resolve` is the reliable route:
+        // `require('metaharness/package.json')` is blocked by the package's
+        // `exports` map, and `createRequire().resolve()` fails on its ESM-only
+        // entry point.
+        const resolved = import.meta.resolve('metaharness');
+        let dir = dirname(fileURLToPath(resolved));
+        let version = null;
+        for (let i = 0; i < 8; i++) {
+            const pj = join(dir, 'package.json');
+            if (existsSync(pj)) {
+                try {
+                    const j = JSON.parse(readFileSync(pj, 'utf-8'));
+                    if (j.name === 'metaharness') {
+                        version = j.version ?? null;
+                        break;
+                    }
+                }
+                catch { /* keep walking */ }
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        if (!version) {
             return {
                 name: 'MetaHarness (ADR-150)',
                 status: 'warn',
-                message: 'Installed but version-string not parseable; integration may still work',
+                message: 'Installed but its package.json was not found while walking up from the resolved module; integration may still work',
             };
         }
         return {
             name: 'MetaHarness (ADR-150)',
             status: 'pass',
-            message: `v${versionMatch[1]} — run \`npx ruflo metaharness score\` for the full scorecard`,
+            message: `v${version} — run \`npx ruflo metaharness score\` for the full scorecard`,
         };
     }
     catch {
@@ -2348,7 +2371,7 @@ export const doctorCommand = {
             checkDaemonStatus,
             checkMemoryDatabase,
             checkMemoryStructuralIntegrity, // #2737 — bounded, native quick_check on every default run
-            checkMemoryPersistenceDriver, // #2968 — native better-sqlite3 vs sql.js fallback, read-only
+            checkMemoryPersistenceDriver, // #2968/#3321 — read-only native capability probe
             checkLearningBridge, // #2545 — can the auto-memory hook actually load @claude-flow/memory?
             checkApiKeys,
             checkMcpServers,
@@ -2386,7 +2409,7 @@ export const doctorCommand = {
             'memory': [
                 checkMemoryDatabase, // existing: exists + statable (unchanged)
                 checkMemoryIntegrity, // #2677 check 1: sql.js open + PRAGMA integrity_check
-                checkMemoryPersistenceDriver, // #2968: native better-sqlite3 vs sql.js fallback
+                checkMemoryPersistenceDriver, // #2968/#3321: read-only native capability probe
                 checkMemoryContent, // #2677 check 2: memory_entries content coverage
                 checkMemoryEmbeddingCoverage, // #2677 check 3: vector coverage on populated rows
                 checkMemoryReflexionCoverage, // #2677 check 6: episodes are retrievable

package/dist/src/commands/swarm.js

@@ -8,6 +8,56 @@ import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { swarmJoinCommand } from './agntcy/swarm-join.js';
 import * as fs from 'fs';
 import * as path from 'path';
+// Read the CLI-side swarm state file (`.swarm/state.json`), written by
+// `swarm init` and rewritten by `swarm start` / `swarm stop`.
+function readLocalSwarmState() {
+    const swarmStateFile = path.join(process.cwd(), '.swarm', 'state.json');
+    if (!fs.existsSync(swarmStateFile))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(swarmStateFile, 'utf-8'));
+    }
+    catch {
+        // Ignore parse errors
+        return null;
+    }
+}
+// Resolve the id of the current swarm. Three writers persist it, under two
+// different keys and in two different files:
+//
+//   `.swarm/state.json`                    `id`                 ← `swarm init`
+//   `.swarm/state.json`                    `swarmId`            ← `swarm start`
+//   `.claude-flow/swarm/swarm-state.json`  `swarms[id].swarmId` ← MCP `swarm_init`
+//
+// The status payload used to read only the first key of the first file, so a
+// Claude Code session (which drives the MCP path) reported an active swarm
+// with agents but no usable id. Check every writer, most local first.
+function resolveSwarmId(swarmState) {
+    // A state file left behind by a previous `swarm stop` must not shadow a
+    // swarm that is still live in the MCP store — otherwise `stop` names the
+    // dead id while `swarm_shutdown`'s own "most recent running" fallback
+    // terminates a different swarm.
+    if (swarmState?.status !== 'stopped') {
+        const fromState = swarmState?.id ?? swarmState?.swarmId;
+        if (typeof fromState === 'string' && fromState)
+            return fromState;
+    }
+    try {
+        const storePath = path.join(process.cwd(), '.claude-flow', 'swarm', 'swarm-state.json');
+        if (!fs.existsSync(storePath))
+            return null;
+        const store = JSON.parse(fs.readFileSync(storePath, 'utf-8'));
+        // Most recently updated swarm that has not been shut down.
+        const live = Object.values(store.swarms ?? {})
+            .filter(swarm => swarm.status !== 'terminated')
+            .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime());
+        return live[0]?.swarmId ?? null;
+    }
+    catch {
+        // Ignore — an unreadable MCP store just means no id to resolve.
+        return null;
+    }
+}
 // Get dynamic swarm status from memory/session files
 function getSwarmStatus(swarmId) {
     const swarmDir = path.join(process.cwd(), '.swarm');
@@ -17,16 +67,7 @@ function getSwarmStatus(swarmId) {
         path.join(process.cwd(), '.claude', 'memory.db'),
     ];
     // Check for active swarm state file
-    const swarmStateFile = path.join(swarmDir, 'state.json');
-    let swarmState = null;
-    if (fs.existsSync(swarmStateFile)) {
-        try {
-            swarmState = JSON.parse(fs.readFileSync(swarmStateFile, 'utf-8'));
-        }
-        catch {
-            // Ignore parse errors
-        }
-    }
+    const swarmState = readLocalSwarmState();
     // Count active agents from process files
     let activeAgents = 0;
     let totalAgents = 0;
@@ -175,10 +216,22 @@ function getSwarmStatus(swarmId) {
         status = 'completed';
     }
     else if (swarmState) {
-        status = 'ready';
+        // The file's own lifecycle state wins over the "a file exists, so we are
+        // ready" default — a swarm explicitly recorded as stopped is not ready.
+        // Live agents still win above: they are observed reality, whereas the file
+        // records an intent that may be stale.
+        status = swarmState.status === 'stopped' ? 'stopped' : 'ready';
     }
+    // Resolve once — the id also settles whether there is a swarm to report.
+    // An MCP `swarm_init` with no agents spawned yet leaves no `.swarm/state.json`
+    // and no agent store, so without this the payload contradicted itself:
+    // a real `id` alongside `hasActiveSwarm: false`.
+    const resolvedId = swarmId || resolveSwarmId(swarmState);
     return {
-        id: swarmId || swarmState?.id || 'no-active-swarm',
+        // `null` when genuinely unknown — never a sentinel string. `status` and
+        // `hasActiveSwarm` already carry the "no active swarm" fact, and a
+        // consumer reading `.id` must get an id or nothing.
+        id: resolvedId,
         topology: swarmState?.topology || 'none',
         status,
         objective: swarmState?.objective || 'No active objective',
@@ -290,7 +343,13 @@ function getSwarmStatus(swarmId) {
             }
             return { consensusRounds, messagesSent, conflictsResolved };
         })(),
-        hasActiveSwarm: !!swarmState || totalAgents > 0
+        // A state file left behind by `swarm stop` is not an active swarm — without
+        // this it claimed one it could not name (`id: null`, zero agents), which is
+        // the same contradiction from the other side. Live agents or a resolvable
+        // id still count, so a stopped file never masks real activity.
+        hasActiveSwarm: (!!swarmState && swarmState.status !== 'stopped')
+            || totalAgents > 0
+            || resolvedId !== null
     };
 }
 // Swarm topologies
@@ -630,6 +689,9 @@ const startCommand = {
         if (!fs.existsSync(swarmDir))
             fs.mkdirSync(swarmDir, { recursive: true });
         const executionState = {
+            // `id` mirrors what `swarm init` writes so both files share one key;
+            // `swarmId` stays for existing files and readers.
+            id: swarmId,
             swarmId,
             objective,
             strategy,
@@ -673,7 +735,7 @@ const statusCommand = {
             output.writeln();
             return { success: true, data: status };
         }
-        output.writeln(output.bold(`Swarm Status: ${status.id}`));
+        output.writeln(output.bold(`Swarm Status: ${status.id ?? output.dim('unknown id')}`));
         output.writeln();
         // Progress bar
         output.writeln(`Overall Progress: ${output.progressBar(status.progress, 100, 40)}`);
@@ -747,10 +809,16 @@ const stopCommand = {
         }
     ],
     action: async (ctx) => {
-        const swarmId = ctx.args[0];
+        // Bare `swarm stop` used to hard-fail, and no CLI surface handed out an
+        // id to pass (there is no `swarm list`). Default to the persisted swarm;
+        // an explicit argument still wins.
+        const swarmId = ctx.args[0] || resolveSwarmId(readLocalSwarmState());
         const force = ctx.flags.force;
         if (!swarmId) {
-            output.printError('Swarm ID is required');
+            output.printError('No swarm found to stop');
+            output.writeln(output.dim('  Find an id with: claude-flow swarm status --format json   (the "id" field)'));
+            output.writeln(output.dim('  Or pass one:     claude-flow swarm stop <swarm-id>'));
+            output.writeln(output.dim('  Or start one:    claude-flow swarm init'));
             return { success: false, exitCode: 1 };
         }
         if (ctx.interactive && !force) {
@@ -810,11 +878,14 @@ const scaleCommand = {
         }
     ],
     action: async (ctx) => {
-        const swarmId = ctx.args[0];
+        // Same resolution as `stop` — the id is persisted, so don't demand it.
+        const swarmId = ctx.args[0] || resolveSwarmId(readLocalSwarmState());
         const targetAgents = ctx.flags.agents;
         const agentType = ctx.flags.type;
         if (!swarmId) {
-            output.printError('Swarm ID is required');
+            output.printError('No swarm found to scale');
+            output.writeln(output.dim('  Find an id with: claude-flow swarm status --format json   (the "id" field)'));
+            output.writeln(output.dim('  Or pass one:     claude-flow swarm scale <swarm-id> --agents N'));
             return { success: false, exitCode: 1 };
         }
         if (!targetAgents) {

package/dist/src/mcp-tools/agentbbs-tools.d.ts

@@ -35,5 +35,20 @@
  * @module @claude-flow/cli/mcp-tools/agentbbs
  */
 import type { MCPTool } from './types.js';
+/** Last envelope's seq by scanning only the file tail; full-read fallback keeps it exact. */
+export declare function nextSeq(path: string): number;
+/** Timestamp (ms) of the most recent PeerHello for a room, or -Infinity if none. */
+export declare function lastPeerHelloMs(logPath: string): number;
+/**
+ * Whether a `register` call should append a PeerHello: only for a genuinely new
+ * registration, or once the heartbeat window has elapsed since the last one.
+ * A re-register within the window is a retry and must NOT spam a near-identical
+ * hello. Pure — the decision the handler makes, exported for test.
+ */
+export declare function shouldEmitHello(alreadyRegistered: boolean, nowMs: number, lastHelloMs: number, windowSecs: number): boolean;
+/** Collapse duplicate envelopeIds, preserving order (first occurrence wins). Pure. */
+export declare function dedupEnvelopes<T extends {
+    envelopeId: string;
+}>(list: T[]): T[];
 export declare const agentbbsTools: MCPTool[];
 //# sourceMappingURL=agentbbs-tools.d.ts.map

package/dist/src/mcp-tools/agentbbs-tools.js

@@ -34,7 +34,7 @@
  *
  * @module @claude-flow/cli/mcp-tools/agentbbs
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { resolve, isAbsolute, join } from 'node:path';
 import { randomBytes, createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
@@ -133,12 +133,83 @@ function readEnvelopes(path) {
     }
     return out;
 }
-function nextSeq(path) {
+// Tail of the log we scan to find the last seq. Envelopes are small; one line
+// always fits well inside this. Reading only the tail keeps append O(1) instead
+// of O(n) as a room log grows (ADR-164 §3.2.2 requires monotonic seq, and a
+// full re-parse on every publish was the cost).
+const SEQ_TAIL_BYTES = 65536;
+/** Last envelope's seq by scanning only the file tail; full-read fallback keeps it exact. */
+export function nextSeq(path) {
+    if (!existsSync(path))
+        return 1;
+    try {
+        const size = statSync(path).size;
+        if (size === 0)
+            return 1;
+        const start = Math.max(0, size - SEQ_TAIL_BYTES);
+        const fd = openSync(path, 'r');
+        let text;
+        try {
+            const buf = Buffer.alloc(size - start);
+            readSync(fd, buf, 0, buf.length, start);
+            text = buf.toString('utf-8');
+        }
+        finally {
+            closeSync(fd);
+        }
+        // If we started mid-file the first fragment may be a partial line — drop it.
+        const lines = text.split(/\r?\n/).filter(l => l.trim());
+        const candidates = start > 0 && lines.length > 1 ? lines.slice(1) : lines;
+        for (let i = candidates.length - 1; i >= 0; i--) {
+            try {
+                const e = JSON.parse(candidates[i]);
+                if (typeof e.seq === 'number')
+                    return e.seq + 1;
+            }
+            catch { /* keep scanning upward for the last parseable line */ }
+        }
+    }
+    catch { /* fall through to the exact full-read path */ }
+    // Fallback: whole-file parse (rare — huge single line, or a tail with no seq).
     const env = readEnvelopes(path);
     if (env.length === 0)
         return 1;
     return (env[env.length - 1].seq ?? env.length) + 1;
 }
+/** Window within which a fresh PeerHello is suppressed as a duplicate (heartbeat, not spam). */
+const HELLO_WINDOW_SECS = Number(process.env.FEDERATION_BBS_HELLO_WINDOW_SECS ?? 60);
+/** Timestamp (ms) of the most recent PeerHello for a room, or -Infinity if none. */
+export function lastPeerHelloMs(logPath) {
+    if (!existsSync(logPath))
+        return -Infinity;
+    const env = readEnvelopes(logPath);
+    for (let i = env.length - 1; i >= 0; i--) {
+        if (env[i].msgType === 'PeerHello') {
+            const t = Date.parse(env[i].timestamp);
+            return Number.isNaN(t) ? -Infinity : t;
+        }
+    }
+    return -Infinity;
+}
+/**
+ * Whether a `register` call should append a PeerHello: only for a genuinely new
+ * registration, or once the heartbeat window has elapsed since the last one.
+ * A re-register within the window is a retry and must NOT spam a near-identical
+ * hello. Pure — the decision the handler makes, exported for test.
+ */
+export function shouldEmitHello(alreadyRegistered, nowMs, lastHelloMs, windowSecs) {
+    return !alreadyRegistered || nowMs - lastHelloMs >= windowSecs * 1000;
+}
+/** Collapse duplicate envelopeIds, preserving order (first occurrence wins). Pure. */
+export function dedupEnvelopes(list) {
+    const seen = new Set();
+    return list.filter(e => {
+        if (seen.has(e.envelopeId))
+            return false;
+        seen.add(e.envelopeId);
+        return true;
+    });
+}
 /**
  * Ephemeral per-process Ed25519 keypair for human-join token signing.
  * Phase 1 contract: keys are NOT persisted across process restart — every
@@ -212,6 +283,7 @@ export const agentbbsTools = [
             const registryPath = roomsRegistryPath(basePath);
             const registry = existsSync(registryPath) ? JSON.parse(readFileSync(registryPath, 'utf-8')) : {};
             // Idempotent — re-registering the same label updates timestamp but keeps id stable.
+            const alreadyRegistered = roomId in registry;
             const entry = {
                 roomId,
                 roomLabel,
@@ -220,17 +292,25 @@ export const agentbbsTools = [
             };
             registry[roomId] = entry;
             writeFileSync(registryPath, JSON.stringify(registry, null, 2));
-            // Emit a synthetic PeerHello envelope into the room log so watchers see the join.
+            // Emit a PeerHello only when it carries information: a genuinely new
+            // registration, or a heartbeat refresh once HELLO_WINDOW_SECS has elapsed.
+            // A re-register within the window is a retry/no-op — appending a
+            // near-identical hello every call is the spam ADR-164 dedup guards against
+            // (observed live: one node published 8 near-identical PeerHellos).
             const logPath = roomLogPath(basePath, roomId);
-            const env = {
-                envelopeId: base64url(randomBytes(12)),
-                roomId,
-                seq: nextSeq(logPath),
-                msgType: 'PeerHello',
-                payload: { roomLabel, trustLevel: 'attested' },
-                timestamp: entry.registeredAt,
-            };
-            appendFileSync(logPath, JSON.stringify(env) + '\n');
+            const nowMs = Date.parse(entry.registeredAt);
+            const helloEmitted = shouldEmitHello(alreadyRegistered, nowMs, lastPeerHelloMs(logPath), HELLO_WINDOW_SECS);
+            if (helloEmitted) {
+                const env = {
+                    envelopeId: base64url(randomBytes(12)),
+                    roomId,
+                    seq: nextSeq(logPath),
+                    msgType: 'PeerHello',
+                    payload: { roomLabel, trustLevel: 'attested' },
+                    timestamp: entry.registeredAt,
+                };
+                appendFileSync(logPath, JSON.stringify(env) + '\n');
+            }
             // nodeId: deterministic per (cwd, roomId) so re-registers reuse identity.
             const nodeId = createHash('sha256')
                 .update(`agentbbs:node:${basePath}:${roomId}`)
@@ -241,6 +321,7 @@ export const agentbbsTools = [
                 roomId,
                 nodeId,
                 trustLevel: 'attested',
+                helloEmitted,
             };
         },
     },
@@ -357,13 +438,16 @@ export const agentbbsTools = [
                 const idx = all.findIndex(e => e.envelopeId === sinceEnvelopeId);
                 slice = idx >= 0 ? all.slice(idx + 1) : all;
             }
-            const envelopes = slice.slice(-limit);
+            // Dedup by envelopeId before applying the limit — a relay replay or a
+            // double-append must not surface the same envelope twice to a watcher.
+            const deduped = dedupEnvelopes(slice);
+            const envelopes = deduped.slice(-limit);
             return {
                 success: true,
                 roomId,
                 envelopes,
                 count: envelopes.length,
-                hasMore: slice.length > envelopes.length,
+                hasMore: deduped.length > envelopes.length,
             };
         },
     },

package/dist/src/mcp-tools/memory-tools.js

@@ -238,6 +238,58 @@ async function describeBackend() {
         return 'sqlite';
     }
 }
+/** #3311: one page per round trip, so a store larger than one page is
+ * counted rather than silently cut off at the old hardcoded 100000. */
+const MEMORY_STATS_PAGE = 10000;
+/** #3311: a hard stop so a `total` that never agrees with the rows returned
+ * cannot spin forever. Reaching it is reported as a truncated count, not as
+ * a complete one. */
+const MEMORY_STATS_MAX_PAGES = 200;
+/**
+ * Page through the store and return every row, or the first failure.
+ *
+ * The old call asked for `limit: 100000` in one shot and read only
+ * `entries`/`total` off the result — so a bigger store had its namespace
+ * breakdown and embedding coverage computed from a prefix, and a listing
+ * that reported `success: false` was read as an empty one.
+ */
+async function collectAllEntries(listEntries) {
+    const entries = [];
+    let total = 0;
+    for (let page = 0; page < MEMORY_STATS_MAX_PAGES; page++) {
+        const result = await listEntries({ limit: MEMORY_STATS_PAGE, offset: entries.length });
+        if (!result.success) {
+            return { success: false, entries, total: result.total ?? total, error: result.error };
+        }
+        total = result.total;
+        entries.push(...result.entries);
+        if (result.entries.length === 0 || entries.length >= total)
+            break;
+    }
+    return { success: true, entries, total };
+}
+/** #3311: unavailable is its own answer. The zeros this replaces were
+ * indistinguishable from a store that really is empty. */
+function memoryStatsUnavailable(error) {
+    return { initialized: null, available: false, error };
+}
+/**
+ * Version and feature labels from the initialization probe.
+ *
+ * Metadata only. The probe reads a whole-image snapshot that cannot see live
+ * WAL frames, so it is allowed to fail without that meaning the store is
+ * missing — which is exactly the conflation #3311 reports.
+ */
+async function readMemoryStatusLabels() {
+    try {
+        const { checkMemoryInitialization } = await getMemoryFunctions();
+        const status = await checkMemoryInitialization();
+        return { version: status.version, features: status.features };
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Ensure memory database is initialized and migrate legacy data if needed.
  * #1606: Wrapped in try/catch to prevent process-level crashes that kill
@@ -704,41 +756,60 @@ export const memoryTools = [
         },
         handler: async () => {
             await ensureInitialized();
-            const { checkMemoryInitialization, listEntries } = await getMemoryFunctions();
+            const { listEntries } = await getMemoryFunctions();
+            // #3311: the store's own listing decides whether memory is there.
+            // `checkMemoryInitialization` opens a whole-image sql.js snapshot of
+            // the main database file, which cannot include live SQLite WAL frames
+            // — so a store the bridge reads and searches perfectly well came back
+            // `initialized: false` from this tool alone. The probe is still read
+            // below, for the version and feature labels it is the only source of,
+            // but it no longer gets to overrule a working store.
+            let listing;
             try {
-                const status = await checkMemoryInitialization();
-                const allEntries = await listEntries({ limit: 100000 });
-                // Count by namespace
-                const namespaces = {};
-                let withEmbeddings = 0;
-                for (const entry of allEntries.entries) {
-                    namespaces[entry.namespace] = (namespaces[entry.namespace] || 0) + 1;
-                    if (entry.hasEmbedding)
-                        withEmbeddings++;
-                }
-                return {
-                    initialized: status.initialized,
-                    totalEntries: allEntries.total,
-                    entriesWithEmbeddings: withEmbeddings,
-                    embeddingCoverage: allEntries.total > 0
-                        ? `${((withEmbeddings / allEntries.total) * 100).toFixed(1)}%`
-                        : '0%',
-                    namespaces,
-                    backend: await describeBackend(),
-                    version: status.version || '3.0.0',
-                    features: status.features || {
-                        vectorEmbeddings: true,
-                        hnswIndex: true,
-                        semanticSearch: true,
-                    },
-                };
+                listing = await collectAllEntries(listEntries);
             }
             catch (error) {
-                return {
-                    initialized: false,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                };
+                return memoryStatsUnavailable(error instanceof Error ? error.message : 'Unknown error');
+            }
+            if (!listing.success) {
+                // A failed query is not an empty store. Reporting zeros here is
+                // what made a WAL refusal look like "you have no memories".
+                return memoryStatsUnavailable(listing.error || 'listEntries reported failure');
             }
+            // Object.create(null): a namespace literally named `__proto__` is a
+            // legal key, and assigning it on an object literal sets the prototype
+            // instead of counting anything — so that namespace's entries vanished
+            // from the breakdown while still being counted in the total.
+            const namespaces = Object.create(null);
+            let withEmbeddings = 0;
+            for (const entry of listing.entries) {
+                namespaces[entry.namespace] = (namespaces[entry.namespace] || 0) + 1;
+                if (entry.hasEmbedding)
+                    withEmbeddings++;
+            }
+            const counted = listing.entries.length;
+            const status = await readMemoryStatusLabels();
+            return {
+                initialized: true,
+                totalEntries: listing.total,
+                entriesCounted: counted,
+                // The breakdown below covers `entriesCounted` rows, which is every
+                // row unless the listing was truncated; say so rather than letting
+                // a partial count read as the whole store.
+                ...(counted < listing.total ? { truncated: true } : {}),
+                entriesWithEmbeddings: withEmbeddings,
+                embeddingCoverage: counted > 0
+                    ? `${((withEmbeddings / counted) * 100).toFixed(1)}%`
+                    : '0%',
+                namespaces: { ...namespaces },
+                backend: await describeBackend(),
+                version: status.version || '3.0.0',
+                features: status.features || {
+                    vectorEmbeddings: true,
+                    hnswIndex: true,
+                    semanticSearch: true,
+                },
+            };
         },
     },
     {

package/dist/src/mcp-tools/seraphina-tools.js

@@ -1,3 +1,4 @@
+import { relayPayload } from './x-federation-tools.js';
 // ADR-125 precedence: explicit tool args (metaLlmUrl / gatewayUrl) take precedence over the
 // SERAPHINA_METALLM_URL / RUFLO_X_GATEWAY_URL env vars, which precede the defaults.
 const META_LLM = (override) => (override || process.env.SERAPHINA_METALLM_URL || 'https://api.cognitum.one').replace(/\/$/, '');
@@ -14,7 +15,9 @@ async function gatewayRead(uri, gatewayUrl) {
     const text = await res.text();
     const line = text.split('\n').find((l) => l.startsWith('data:'));
     const p = JSON.parse(line ? line.slice(5) : text);
-    return JSON.parse(p.result?.contents?.[0]?.text ?? '{}');
+    // roster and claims are relay-sourced and therefore fenced (#3300). These values
+    // are indexed directly below, so take the payload, not the envelope.
+    return relayPayload(p.result?.contents?.[0]?.text ?? '{}');
 }
 async function gatewaySync(sinceSeconds, limit, gatewayUrl) {
     const res = await fetch(`${GATEWAY(gatewayUrl)}/mcp`, { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
@@ -22,7 +25,9 @@ async function gatewaySync(sinceSeconds, limit, gatewayUrl) {
     const text = await res.text();
     const line = text.split('\n').find((l) => l.startsWith('data:'));
     const p = JSON.parse(line ? line.slice(5) : text);
-    return JSON.parse(p.result?.content?.[0]?.text ?? '{}');
+    // federation_sync is relay-sourced and therefore fenced (#3300); `.messages` is
+    // read directly below, so an envelope here would silently mean "empty swarm".
+    return relayPayload(p.result?.content?.[0]?.text ?? '{}');
 }
 export async function askSeraphina(goal, opts = {}) {
     // Credential: intentionally env-only (never a CLI flag). Registered in audit-env-var-precedence.mjs.

package/dist/src/mcp-tools/x-federation-tools.d.ts

@@ -8,5 +8,17 @@
  * `ruv://federation/registry` resource), not through these gateway-identity tools.
  */
 import type { MCPTool } from './types.js';
+export declare function parseGatewayText(text: string): Record<string, unknown>;
+/**
+ * The payload, for consumers INSIDE this package that immediately index the
+ * value (`recent.messages`, `Object.keys(roster)`).
+ *
+ * At the MCP boundary we return the whole envelope so the caller can see whose
+ * words these are. Internally that shape is a hazard: reading `.messages` off an
+ * envelope yields undefined and `Object.keys()` yields the envelope's own five
+ * keys, so a miscount looks like a real answer. Never do a bare property read on
+ * a parseGatewayText result — come through here.
+ */
+export declare function relayPayload(text: string): Record<string, unknown>;
 export declare const xFederationTools: MCPTool[];
 //# sourceMappingURL=x-federation-tools.d.ts.map

package/dist/src/mcp-tools/x-federation-tools.js

@@ -18,18 +18,100 @@ async function gatewayRpc(method, params, gatewayUrl) {
         throw new Error(`x.ruv.io: ${payload.error.message ?? 'rpc error'}`);
     return payload.result;
 }
+/**
+ * Relay-sourced gateway responses are not bare JSON. Since #3300 the gateway
+ * wraps anything published by other federation members in a provenance envelope
+ * (plugins/ruflo-x-gateway/src/untrusted.mjs): several lines of gateway-authored
+ * prose, then the JSON body between a matched
+ * `<<<UNTRUSTED_RELAY_DATA <uuid>>>>` / `<<<END_UNTRUSTED_RELAY_DATA <uuid>>>>`
+ * pair. `JSON.parse` on the whole string fails on the first prose word, which is
+ * the `Unexpected token 'T', "The block "...` seen from every federation read.
+ *
+ * Three things keep a publisher from closing the block early, and it is worth
+ * being precise about which one is doing the work today:
+ *   1. The body is JSON.stringify'd, so it is a SINGLE line — a publisher's text
+ *      cannot contain a raw newline, and the markers below are newline-anchored.
+ *      This is what actually neutralises forged markers in relay content today.
+ *   2. The token backreference: a forged END carrying any other token does not
+ *      terminate the region. This is the defence that survives (1) — if the body
+ *      is ever pretty-printed, it becomes the only one left. It is tested
+ *      directly rather than incidentally, so it cannot be refactored away quietly.
+ *   3. Exactly one opening marker is permitted. `fenceUntrusted` splices its
+ *      `note` verbatim BEFORE the fence, so a caller that ever interpolates
+ *      relay-derived text into a note could otherwise smuggle in a complete
+ *      earlier envelope; first-match-wins would return it, with untrusted:false.
+ *
+ * We deliberately return the WHOLE envelope (`untrusted`, `provenance`, `relay`,
+ * `retrievedAt`, `data`) rather than lifting `data` out of it. The point of the
+ * envelope is that a caller can tell whose words these are; quietly unwrapping to
+ * the payload would restore valid JSON by discarding the labelling that made it
+ * safe to read. Unfenced responses (the registry resource, gateway-authored
+ * errors) parse unchanged.
+ */
+const UNTRUSTED_FENCE = /<<<UNTRUSTED_RELAY_DATA ([0-9a-fA-F-]{36})>>>\n([\s\S]*?)\n<<<END_UNTRUSTED_RELAY_DATA \1>>>/;
+// Count only NEWLINE-ANCHORED opening markers. A marker inside the body is just
+// characters — the body is one JSON line, so it can never be preceded by a raw
+// newline and can never open a fence. Counting raw occurrences instead would make
+// a publisher able to hard-fail every read simply by typing the marker into a
+// message, which trades a parse bug for a denial of service.
+const OPEN_MARKER_ANCHORED = /(?:^|\n)<<<UNTRUSTED_RELAY_DATA /g;
+export function parseGatewayText(text) {
+    // One response carries exactly one envelope. More than one means something
+    // upstream spliced an envelope-shaped string into the response, and picking
+    // either is a guess — refuse rather than choose.
+    const opens = (text.match(OPEN_MARKER_ANCHORED) ?? []).length;
+    if (opens > 1) {
+        throw new Error('x.ruv.io: response carries more than one untrusted-data envelope (tampered response)');
+    }
+    const fenced = UNTRUSTED_FENCE.exec(text);
+    if (fenced)
+        return JSON.parse(fenced[2]);
+    // An opening marker with no matching close is a truncated or tampered response.
+    // Fail loudly: parsing the remainder would silently drop relay content.
+    if (opens === 1) {
+        throw new Error('x.ruv.io: untrusted-data envelope is unterminated (truncated or tampered response)');
+    }
+    return JSON.parse(text);
+}
+/**
+ * The payload, for consumers INSIDE this package that immediately index the
+ * value (`recent.messages`, `Object.keys(roster)`).
+ *
+ * At the MCP boundary we return the whole envelope so the caller can see whose
+ * words these are. Internally that shape is a hazard: reading `.messages` off an
+ * envelope yields undefined and `Object.keys()` yields the envelope's own five
+ * keys, so a miscount looks like a real answer. Never do a bare property read on
+ * a parseGatewayText result — come through here.
+ */
+export function relayPayload(text) {
+    const parsed = parseGatewayText(text);
+    return (parsed.untrusted === true && parsed.data !== undefined
+        ? parsed.data
+        : parsed);
+}
 async function gatewayTool(name, args) {
     const { gatewayUrl, ...rest } = args;
     const r = (await gatewayRpc('tools/call', { name, arguments: rest }, gatewayUrl));
-    const text = r.content?.[0]?.text ?? '{}';
-    const parsed = JSON.parse(text);
-    if (r.isError || parsed.error)
-        throw new Error(String(parsed.error ?? 'gateway tool error'));
+    const raw = r.content?.[0]?.text ?? '{}';
+    // An isError result is the SDK's createToolError, whose message is raw text and
+    // not JSON. Parsing first turns "private channels cannot be published…" into
+    // "Unexpected token 'p'" — the same class of bug this parser exists to fix.
+    if (r.isError) {
+        let msg = raw;
+        try {
+            msg = String(parseGatewayText(raw).error ?? raw);
+        }
+        catch { /* raw text: use as-is */ }
+        throw new Error(msg || 'gateway tool error');
+    }
+    const parsed = parseGatewayText(raw);
+    if (parsed.error)
+        throw new Error(String(parsed.error));
     return parsed;
 }
 async function gatewayResource(uri, gatewayUrl) {
     const r = (await gatewayRpc('resources/read', { uri }, gatewayUrl));
-    return JSON.parse(r.contents?.[0]?.text ?? '{}');
+    return parseGatewayText(r.contents?.[0]?.text ?? '{}');
 }
 // Credential: intentionally env-only (a secret must never be a CLI flag — it would land in
 // shell history / process lists). Registered in scripts/audit-env-var-precedence.mjs.

package/dist/src/memory/memory-initializer.js

@@ -1855,12 +1855,15 @@ export async function checkMemoryInitialization(dbPath) {
     if (!fs.existsSync(path_)) {
         return { initialized: false };
     }
+    // #3249: declared outside the try so the handle can be released on the
+    // failure path as well as the success path.
+    let db;
     try {
         // Try to load with sql.js
         const initSqlJs = (await import('sql.js')).default;
         const SQL = await initSqlJs();
         const fileBuffer = fs.readFileSync(path_);
-        const db = new SQL.Database(fileBuffer);
+        db = new SQL.Database(fileBuffer);
         // Check for metadata table
         const tables = db.exec("SELECT name FROM sqlite_master WHERE type='table'");
         const tableNames = tables[0]?.values?.map(v => v[0]) || [];
@@ -1876,7 +1879,6 @@ export async function checkMemoryInitialization(dbPath) {
         catch {
             // Metadata table might not exist
         }
-        db.close();
         return {
             initialized: true,
             version,
@@ -1893,6 +1895,21 @@ export async function checkMemoryInitialization(dbPath) {
         // Could not read database
         return { initialized: false };
     }
+    finally {
+        // #3249: release the handle on every path. An RFE1-encrypted image is not
+        // parseable as SQLite, so the schema query above throws and the catch
+        // returns — which used to skip the inline db.close() entirely, leaving the
+        // sql.js Database and its MEMFS copy open for the life of the process.
+        // Every memory MCP tool call runs this check, so a long session accumulates
+        // one unclosed handle per call. Measured retention is a few hundred KiB per
+        // leaked handle (it does not scale with image size).
+        try {
+            db?.close();
+        }
+        catch {
+            // Already closed, or never successfully constructed.
+        }
+    }
 }
 /**
  * Apply temporal decay to patterns

package/dist/src/ruvector/graph-backend.js

@@ -13,51 +13,137 @@
  */
 import { join } from 'path';
 // Lazy-loaded graph-node module
-let graphNodeModule = null;
-let graphDb = null;
-let graphBackendLoaded = false;
+let graphNodeModulePromise = null;
+let graphDbPromise = null;
 let graphBackendAvailable = false;
 const DEFAULT_EMBEDDING_DIM = 8; // Minimal embedding for graph structure
+const DEFAULT_DISTANCE_METRIC = 'Cosine';
 /**
- * Load @ruvector/graph-node via createRequire (CJS package)
+ * Load @ruvector/graph-node via createRequire (CJS package).
+ *
+ * The promise is the memo rather than a "loaded" flag. The flag was set
+ * BEFORE its own `await`, so a caller arriving inside that window would take
+ * the early return and read `graphNodeModule` while it was still `null`.
+ * I could not make that window observable -- `import('module')` resolves a
+ * builtin before another caller gets a turn -- so this is hardening on the
+ * same shape as the open memo below, not a defect with a reproduction behind
+ * it.
  */
 async function loadGraphNode() {
-    if (graphBackendLoaded)
-        return graphNodeModule;
-    graphBackendLoaded = true;
-    try {
-        const { createRequire } = await import('module');
-        const requireCjs = createRequire(import.meta.url);
-        graphNodeModule = requireCjs('@ruvector/graph-node');
-        graphBackendAvailable = true;
-        return graphNodeModule;
+    if (!graphNodeModulePromise) {
+        graphNodeModulePromise = (async () => {
+            try {
+                const { createRequire } = await import('module');
+                const requireCjs = createRequire(import.meta.url);
+                const mod = requireCjs('@ruvector/graph-node');
+                graphBackendAvailable = true;
+                return mod;
+            }
+            catch {
+                graphBackendAvailable = false;
+                return null;
+            }
+        })();
     }
-    catch {
-        graphBackendAvailable = false;
-        return null;
+    return graphNodeModulePromise;
+}
+/**
+ * Report a graph-backend problem.
+ *
+ * No "already warned" flag: the open runs once per process because
+ * `getGraphDb` memoizes the promise, and a second flag would only hide it if
+ * that ever stopped being true.
+ */
+function warnGraphInit(message) {
+    console.warn(`[graph-backend] ${message}`);
+}
+/**
+ * Whether this handle is actually backed by the file we asked for.
+ *
+ * `@ruvector/graph-node` 2.1.0 accepts a bare path STRING without throwing
+ * and hands back a volatile in-memory instance -- `isPersistent() === false`,
+ * `getStoragePath() === null`. Nothing downstream notices: writes succeed,
+ * reads succeed, and the graph is gone at exit. Passing the options object
+ * fixes that, and this check is what makes the fix self-reporting instead of
+ * something a future signature change can quietly undo.
+ *
+ * A build that exposes neither accessor cannot be interrogated, so it is
+ * accepted rather than refused -- this guards against a silent downgrade, not
+ * against an unfamiliar version.
+ */
+function isPersistentAt(db, storagePath) {
+    const canReport = typeof db?.isPersistent === 'function' || typeof db?.getStoragePath === 'function';
+    if (!canReport)
+        return true;
+    if (typeof db.isPersistent === 'function' && db.isPersistent() !== true)
+        return false;
+    if (typeof db.getStoragePath === 'function' && db.getStoragePath() !== storagePath) {
+        return false;
     }
+    return true;
 }
 /**
- * Get or create the singleton graph database instance
+ * Open the graph database, or return null with a stated reason.
+ *
+ * The old fallback replaced an open failure with `new mod.GraphDatabase()` --
+ * an empty in-memory graph that answers every query successfully and persists
+ * nothing. A permission error, a lock held by another process and a healthy
+ * database were indistinguishable from the outside. Callers already handle
+ * `null` by degrading to `backend: 'unavailable'`, which is the honest shape
+ * for "the graph is not there".
  */
-async function getGraphDb() {
-    if (graphDb)
-        return graphDb;
+async function openGraphDb() {
     const mod = await loadGraphNode();
     if (!mod)
         return null;
-    // Use persistent path if available, otherwise in-memory
     const dataDir = join(process.cwd(), '.claude-flow', 'graph');
+    const storagePath = join(dataDir, 'agents.db');
+    let db;
     try {
         const fs = await import('fs');
         fs.mkdirSync(dataDir, { recursive: true });
-        graphDb = new mod.GraphDatabase(join(dataDir, 'agents.db'));
+        // The options object, not the path string: see `isPersistentAt`.
+        db = new mod.GraphDatabase({
+            storagePath,
+            dimensions: DEFAULT_EMBEDDING_DIM,
+            distanceMetric: DEFAULT_DISTANCE_METRIC,
+        });
     }
-    catch {
-        // Fallback to in-memory
-        graphDb = new mod.GraphDatabase();
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        warnGraphInit(`could not open ${storagePath}: ${reason}. Graph backend disabled.`);
+        return null;
+    }
+    if (!isPersistentAt(db, storagePath)) {
+        const reported = typeof db?.getStoragePath === 'function' ? db.getStoragePath() : 'unknown';
+        warnGraphInit(`opened a non-persistent graph (storage path ${String(reported)}, wanted ${storagePath}). ` +
+            'Graph backend disabled rather than writing to a graph that vanishes at exit.');
+        try {
+            db?.close?.();
+        }
+        catch {
+            // A handle we are already discarding.
+        }
+        return null;
+    }
+    return db;
+}
+/**
+ * Get or create the singleton graph database instance.
+ *
+ * The promise is the singleton, not the handle: two callers racing the first
+ * call used to each run the constructor, and the second overwrote the first's
+ * `graphDb` while nodes were already being written through it.
+ */
+async function getGraphDb() {
+    if (!graphDbPromise) {
+        graphDbPromise = openGraphDb().catch((error) => {
+            const reason = error instanceof Error ? error.message : String(error);
+            warnGraphInit(`initialization failed: ${reason}. Graph backend disabled.`);
+            return null;
+        });
     }
-    return graphDb;
+    return graphDbPromise;
 }
 /**
  * Create a minimal embedding for non-vector graph operations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.42.0",
+  "version": "3.42.2",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -125,11 +125,11 @@
     "ws": "^8.21.0",
     "yaml": "^2.8.0",
     "zod": "^3.22.0",
-    "@claude-flow/memory": "^3.0.0-alpha.23"
+    "@claude-flow/memory": "^3.0.0-alpha.24"
   },
   "optionalDependencies": {
     "@agntcy/slim-bindings": "2.0.0-alpha.5",
-    "@claude-flow/memory": "^3.0.0-alpha.23",
+    "@claude-flow/memory": "^3.0.0-alpha.24",
     "@metaharness/darwin": "~0.10.2",
     "@metaharness/flywheel": "~0.1.10",
     "@metaharness/radio": "~0.1.0",