claude-flow 3.25.0 → 3.25.2

package/.claude/helpers/metrics-db.mjs

@@ -6,7 +6,7 @@
  */
 
 import initSqlJs from 'sql.js';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, openSync, writeSync, fsyncSync, closeSync, renameSync, rmSync } from 'fs';
 import { dirname, join, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -138,7 +138,22 @@ async function initDatabase() {
 function persist() {
   const data = db.export();
   const buffer = Buffer.from(data);
-  writeFileSync(DB_PATH, buffer);
+  // Atomic write (issue #2584): temp → fsync → rename so a kill/OOM mid-flush
+  // or a concurrent writer can't leave a torn, malformed metrics.db image.
+  const tmp = `${DB_PATH}.tmp-${process.pid}-${Date.now().toString(36)}`;
+  let fd;
+  try {
+    fd = openSync(tmp, 'wx');
+    if (buffer.length > 0) writeSync(fd, buffer, 0, buffer.length, 0);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(tmp, DB_PATH);
+  } catch (e) {
+    if (fd !== undefined) { try { closeSync(fd); } catch { /* */ } }
+    try { rmSync(tmp, { force: true }); } catch { /* */ }
+    throw e;
+  }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.25.0",
+  "version": "3.25.2",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/fs-secure.d.ts

@@ -16,6 +16,25 @@
  * sniff so legacy plaintext files keep working unchanged during the
  * incremental migration.
  */
+/**
+ * Crash-safe atomic file write (issue #2584).
+ *
+ * A plain `writeFileSync(dbPath, db.export())` of a large sql.js image is NOT
+ * crash-safe: a kill/OOM mid-write — or a second process rewriting the same
+ * path concurrently — leaves a half-written image, and reopening it yields
+ * `database disk image is malformed`. The corruption window scales with file
+ * size, so a 185 MB monolithic flush is especially exposed.
+ *
+ * This writes to a unique temp sibling, fsyncs the bytes to disk, then
+ * `rename()`s over the target. rename() is atomic on POSIX within one
+ * filesystem, so a reader/reopen sees either the old complete image or the new
+ * complete image — never a torn one. The directory entry is best-effort fsynced
+ * so the rename itself survives a crash. On any failure the temp file is
+ * removed and the original is left untouched.
+ */
+export declare function writeFileAtomic(path: string, data: Buffer, opts?: {
+    mode?: number;
+}): void;
 /**
  * Create a directory tree with mode 0700 (owner-only). No-op if exists.
  * Uses recursive: true so missing parents are created with the same mode.

package/v3/@claude-flow/cli/dist/src/fs-secure.js

@@ -16,8 +16,76 @@
  * sniff so legacy plaintext files keep working unchanged during the
  * incremental migration.
  */
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { decryptBuffer, encryptBuffer, getKey, isEncryptedBlob, isEncryptionEnabled, } from './encryption/vault.js';
+/**
+ * Crash-safe atomic file write (issue #2584).
+ *
+ * A plain `writeFileSync(dbPath, db.export())` of a large sql.js image is NOT
+ * crash-safe: a kill/OOM mid-write — or a second process rewriting the same
+ * path concurrently — leaves a half-written image, and reopening it yields
+ * `database disk image is malformed`. The corruption window scales with file
+ * size, so a 185 MB monolithic flush is especially exposed.
+ *
+ * This writes to a unique temp sibling, fsyncs the bytes to disk, then
+ * `rename()`s over the target. rename() is atomic on POSIX within one
+ * filesystem, so a reader/reopen sees either the old complete image or the new
+ * complete image — never a torn one. The directory entry is best-effort fsynced
+ * so the rename itself survives a crash. On any failure the temp file is
+ * removed and the original is left untouched.
+ */
+export function writeFileAtomic(path, data, opts = {}) {
+    const mode = opts.mode ?? 0o600;
+    const dir = dirname(path);
+    const tmp = join(dir, `.${basename(path)}.tmp-${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
+    let fd;
+    try {
+        fd = openSync(tmp, 'wx', mode);
+        if (data.length > 0)
+            writeSync(fd, data, 0, data.length, 0);
+        fsyncSync(fd); // durability: force bytes to disk BEFORE the rename
+        closeSync(fd);
+        fd = undefined;
+        renameSync(tmp, path); // atomic swap — readers never see a torn image
+        try {
+            chmodSync(path, mode);
+        }
+        catch {
+            // Windows / FS without POSIX modes — silently skip.
+        }
+        // Best-effort: fsync the directory so the rename survives a power loss.
+        try {
+            const dfd = openSync(dir, 'r');
+            try {
+                fsyncSync(dfd);
+            }
+            finally {
+                closeSync(dfd);
+            }
+        }
+        catch {
+            // Directory fsync unsupported (e.g. Windows) — the rename is still atomic.
+        }
+    }
+    catch (e) {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* already closed */
+            }
+        }
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* temp never created / already gone */
+        }
+        throw e;
+    }
+}
 /**
  * Create a directory tree with mode 0700 (owner-only). No-op if exists.
  * Uses recursive: true so missing parents are created with the same mode.
@@ -45,20 +113,11 @@ export function writeFileRestricted(path, data, optsOrEncoding = 'utf-8') {
         const plaintext = Buffer.isBuffer(data) ? data : Buffer.from(data, encoding);
         payload = encryptBuffer(plaintext, getKey());
     }
-    // For encrypted payloads we always have a Buffer — pass through without an
-    // encoding so writeFileSync doesn't try to text-decode it.
-    if (Buffer.isBuffer(payload)) {
-        writeFileSync(path, payload);
-    }
-    else {
-        writeFileSync(path, payload, encoding);
-    }
-    try {
-        chmodSync(path, 0o600);
-    }
-    catch {
-        // Windows / FS without POSIX modes — silently skip.
-    }
+    // Atomic write (temp → fsync → rename) so a torn/concurrent flush can never
+    // leave a half-written file — the failure mode behind issue #2584. Buffers go
+    // straight through; strings are encoded first (default utf-8).
+    const buf = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, encoding);
+    writeFileAtomic(path, buf, { mode: 0o600 });
 }
 export function readFileMaybeEncrypted(path, encoding = 'utf-8') {
     const raw = readFileSync(path);

package/v3/@claude-flow/cli/dist/src/mcp-tools/neural-tools.js

@@ -89,26 +89,26 @@ function ensureEmbeddings() {
         return embeddingsPromise;
     embeddingsPromise = (async () => {
         try {
-            // Tier -1 (PRIMARY): Lattice WASM — real multi-model semantic embeddings
-            // (miniLM / bge / paraphrase-miniLM / GPU qwen3-0.6b) ahead of everything.
-            // Optional + FAIL-CLOSED: absent/init-fail ⇒ fall straight through to the
-            // existing ruvector-ONNX → hash tiers with zero regression.
+            // Tier -1 (PRIMARY): optional WASM embedder — a pluggable real embedder
+            // ahead of everything. OPT-IN (RUFLO_EMBED_WASM_PKG) + FAIL-CLOSED: unset
+            // or absent/init-fail ⇒ fall straight through to the existing
+            // ruvector-ONNX → hash tiers with zero regression.
             try {
-                const lat = await import('../ruvector/lattice-wasm.js').catch(() => null);
-                if (lat && await lat.latticeAvailable()) {
-                    const model = lat.DEFAULT_LATTICE_MODEL;
+                const we = await import('../ruvector/wasm-embedder.js').catch(() => null);
+                if (we && await we.wasmEmbedderAvailable()) {
+                    const model = we.DEFAULT_EMBED_MODEL;
                     realEmbeddings = {
                         embed: async (text) => {
-                            const v = await lat.latticeEmbed(text, model);
+                            const v = await we.wasmEmbed(text, model);
                             if (!v || !v.length)
-                                throw new Error('lattice embed failed'); // → generateEmbedding falls to next tier
+                                throw new Error('wasm embed failed'); // → generateEmbedding falls to next tier
                             return v;
                         },
                     };
-                    embeddingServiceName = `lattice-wasm/${model} (${lat.latticeModels().length} model${lat.latticeModels().length === 1 ? '' : 's'})`;
+                    embeddingServiceName = `wasm-embedder/${model} (${we.wasmEmbedderModels().length} model${we.wasmEmbedderModels().length === 1 ? '' : 's'})`;
                 }
             }
-            catch { /* lattice absent — fall through */ }
+            catch { /* not configured — fall through */ }
             // Tier 0: ruvector@0.2.27 — bundled all-MiniLM-L6-v2 + parallel worker pool.
             // Probe with isOnnxAvailable() and verify an actual embed succeeds (avoids
             // the type-load-success-but-runtime-fails trap from ADR-086). The probe now
@@ -320,6 +320,7 @@ async function generateEmbedding(text, dims = 384) {
     // Hash-based deterministic embedding (better than pure random for consistency)
     // NOTE: No semantic meaning — only useful for consistent deduplication, not similarity search
     if (text) {
+        (await import('../memory/embedding-policy.js')).enforceNoStub('neural-tools.generateEmbedding'); // "no stubs" strict mode
         if (embeddingServiceName === 'none') {
             embeddingServiceName = 'hash-fallback';
         }

package/v3/@claude-flow/cli/dist/src/memory/embedding-policy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Embedding policy — "no more stubs" enforcement.
+ *
+ * Every embedder in the codebase tries REAL models first (Lattice WASM →
+ * ruvector ONNX → AgentDB bridge → transformers.js) and only falls back to a
+ * deterministic HASH embedding when none loads. A hash embedding has no semantic
+ * meaning — it silently degrades similarity search into noise.
+ *
+ * This module makes that failure mode a POLICY choice instead of a silent
+ * default. With RUFLO_REQUIRE_REAL_EMBEDDINGS truthy, any hash last-resort throws
+ * loudly ("no stubs") rather than returning a meaningless vector — fail-closed,
+ * so a broken embedding substrate is a hard error, not corrupt retrieval.
+ *
+ * Default (unset): unchanged behavior (warn + degrade), so nothing breaks for
+ * installs where a real embedder genuinely can't load. Set the flag in any
+ * environment that must never serve pseudo-embeddings.
+ */
+export declare function requireRealEmbeddings(): boolean;
+/** Throw the canonical "no stubs" error if strict mode is on; else no-op. */
+export declare function enforceNoStub(where: string): void;
+//# sourceMappingURL=embedding-policy.d.ts.map

package/v3/@claude-flow/cli/dist/src/memory/embedding-policy.js

@@ -0,0 +1,30 @@
+/**
+ * Embedding policy — "no more stubs" enforcement.
+ *
+ * Every embedder in the codebase tries REAL models first (Lattice WASM →
+ * ruvector ONNX → AgentDB bridge → transformers.js) and only falls back to a
+ * deterministic HASH embedding when none loads. A hash embedding has no semantic
+ * meaning — it silently degrades similarity search into noise.
+ *
+ * This module makes that failure mode a POLICY choice instead of a silent
+ * default. With RUFLO_REQUIRE_REAL_EMBEDDINGS truthy, any hash last-resort throws
+ * loudly ("no stubs") rather than returning a meaningless vector — fail-closed,
+ * so a broken embedding substrate is a hard error, not corrupt retrieval.
+ *
+ * Default (unset): unchanged behavior (warn + degrade), so nothing breaks for
+ * installs where a real embedder genuinely can't load. Set the flag in any
+ * environment that must never serve pseudo-embeddings.
+ */
+export function requireRealEmbeddings() {
+    return /^(1|true|yes|on|strict)$/i.test(process.env.RUFLO_REQUIRE_REAL_EMBEDDINGS ?? '');
+}
+/** Throw the canonical "no stubs" error if strict mode is on; else no-op. */
+export function enforceNoStub(where) {
+    if (requireRealEmbeddings()) {
+        throw new Error(`[no-stub] real embeddings required but only a hash fallback was available at ${where}. ` +
+            `RUFLO_REQUIRE_REAL_EMBEDDINGS is set — install a real embedder ` +
+            `(ruvector, or @claude-flow/embeddings with "embeddings init --download") ` +
+            `or unset the flag to allow degraded hash embeddings.`);
+    }
+}
+//# sourceMappingURL=embedding-policy.js.map

package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.d.ts

@@ -262,6 +262,9 @@ export declare function recoverMemoryDatabase(dbPath: string, opts?: {
     backupPath?: string;
     rows?: number;
     reason?: string;
+    restoredFromBackup?: boolean;
+    from?: string;
+    restoreReason?: string;
 }>;
 export declare function repairVectorIndexes(dbPath: string, opts?: {
     verbose?: boolean;

package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js

@@ -11,7 +11,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createRequire } from 'node:module';
-import { readFileMaybeEncrypted, writeFileRestricted } from '../fs-secure.js';
+import { readFileMaybeEncrypted, writeFileAtomic, writeFileRestricted } from '../fs-secure.js';
+import { restoreMemoryDbFromBackup } from '../services/memory-backup.js';
 /**
  * #2356 — cached, synchronous capability probe for @ruvector/core. `getHNSWStatus`
  * is sync and is called by `neural status` in a fresh process that never warms
@@ -1182,6 +1183,16 @@ async function activateControllerRegistry(dbPath, verbose) {
 export async function recoverMemoryDatabase(dbPath, opts = {}) {
     if (!dbPath || !fs.existsSync(dbPath))
         return { recovered: false, reason: 'no-db' };
+    // Fallback for when the in-place rebuild can't produce a verified DB (issue
+    // #2584): rebuild-from-corrupt salvages nothing when the damage is total, so
+    // restore the newest integrity-ok backup instead of leaving the store dead.
+    const restoreFromBackup = async (reason) => {
+        const r = await restoreMemoryDbFromBackup(dbPath, { verbose: opts.verbose });
+        if (r.restored) {
+            return { recovered: true, restoredFromBackup: true, backupPath: r.corruptBackupPath, rows: r.rows, from: r.from };
+        }
+        return { recovered: false, reason, restoreReason: r.skipped };
+    };
     let Database;
     try {
         // Module name behind a variable so TS does not statically resolve the
@@ -1190,7 +1201,7 @@ export async function recoverMemoryDatabase(dbPath, opts = {}) {
         Database = (await import(mod)).default;
     }
     catch {
-        return { recovered: false, reason: 'no-native' };
+        return await restoreFromBackup('no-native');
     }
     const ts = Date.now();
     const tmpPath = `${dbPath}.recovering-${ts}`;
@@ -1287,9 +1298,9 @@ export async function recoverMemoryDatabase(dbPath, opts = {}) {
             }
             catch { /* */ }
             if (opts.verbose) {
-                console.log(`memory DB auto-recovery aborted (integrity=${integ}, rows ${dstRows}/${srcRows}) — original untouched`);
+                console.log(`memory DB rebuild-in-place failed (integrity=${integ}, rows ${dstRows}/${srcRows}) — trying newest good backup`);
             }
-            return { recovered: false, reason: 'verify-failed' };
+            return await restoreFromBackup('verify-failed');
         }
         // Back up the corrupt DB, then atomically swap in the verified rebuild.
         fs.copyFileSync(dbPath, bakPath);
@@ -1323,8 +1334,8 @@ export async function recoverMemoryDatabase(dbPath, opts = {}) {
         }
         catch { /* */ }
         if (opts.verbose)
-            console.log(`memory DB auto-recovery error: ${e?.message ?? e}`);
-        return { recovered: false, reason: 'error' };
+            console.log(`memory DB rebuild-in-place error (${e?.message ?? e}) — trying newest good backup`);
+        return await restoreFromBackup('error');
     }
 }
 export async function repairVectorIndexes(dbPath, opts = {}) {
@@ -1717,9 +1728,9 @@ export async function applyTemporalDecay(dbPath) {
     `;
         db.run(decayQuery, [now, now, now]);
         const changes = db.getRowsModified();
-        // Save
+        // Save (atomic — issue #2584: a torn full-image flush corrupts the store)
         const data = db.export();
-        fs.writeFileSync(path_, Buffer.from(data));
+        writeFileAtomic(path_, Buffer.from(data));
         db.close();
         return {
             success: true,
@@ -2011,6 +2022,7 @@ export async function generateLocalEmbedding(text) {
     }
     // Deterministic hash-based fallback (for testing/demo without ONNX).
     // AUDIT #3: backend='mock' — these vectors do NOT carry real semantics.
+    (await import('./embedding-policy.js')).enforceNoStub('memory-initializer.generateLocalEmbedding'); // "no stubs" strict mode
     const embedding = generateHashEmbedding(text, state.dimensions);
     return {
         embedding,

package/v3/@claude-flow/cli/dist/src/ruvector/vector-db.js

@@ -13,6 +13,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { enforceNoStub } from '../memory/embedding-policy.js';
 // ============================================================================
 // Fallback Implementation (when ruvector not available)
 // ============================================================================
@@ -248,6 +249,7 @@ export function generateEmbedding(text, dimensions = 768) {
             // Fall back to hash-based embedding
         }
     }
+    enforceNoStub('vector-db.generateEmbedding'); // "no stubs" strict mode → throw instead of hash
     const embedding = generateHashEmbedding(text, dimensions);
     // Tag the result so consumers can detect it came from hash fallback
     Object.defineProperty(embedding, '_warning', {

package/v3/@claude-flow/cli/dist/src/ruvector/wasm-embedder.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Package specifier for the optional WASM embedder. EMPTY by default (opt-in).
+ * `RUFLO_LATTICE_WASM_PKG` is accepted as a back-compat alias.
+ */
+export declare const EMBED_WASM_PKG: string;
+export declare const DEFAULT_EMBED_MODEL: string;
+/** Is an optional WASM embedder configured + installed + initializable? Cached; never throws. */
+export declare function wasmEmbedderAvailable(): Promise<boolean>;
+/** Models the configured WASM embedder reports (empty until available). */
+export declare function wasmEmbedderModels(): string[];
+/** Embed via the optional WASM embedder, or null (caller falls through). Never throws. */
+export declare function wasmEmbed(text: string, model?: string): Promise<number[] | null>;
+//# sourceMappingURL=wasm-embedder.d.ts.map

package/v3/@claude-flow/cli/dist/src/ruvector/wasm-embedder.js

@@ -0,0 +1,143 @@
+/**
+ * Optional WASM embedder tier — a pluggable PRIMARY embedding tier ahead of
+ * ruvector-ONNX → hash.
+ *
+ * OPT-IN by design: there is NO default package (an earlier iteration defaulted
+ * to `@ruvector/lattice-wasm`, which does not exist — npm 404). Point
+ * `RUFLO_EMBED_WASM_PKG` at any real WASM embedder that follows the ruvnet
+ * wasm-bindgen convention (a text→vector embed export). With the env unset, this
+ * tier is INERT and everything resolves exactly as before (ruvector ONNX). Fully
+ * fail-closed; never throws.
+ *
+ * The adapter probes the module's API tolerantly and verifies a real embed
+ * succeeds before accepting the tier (guards the ADR-086 loads-but-runtime-fails
+ * trap), so an incompatible package simply reports unavailable.
+ */
+import { createRequire } from 'module';
+import { readFileSync } from 'fs';
+const require_ = createRequire(import.meta.url);
+/**
+ * Package specifier for the optional WASM embedder. EMPTY by default (opt-in).
+ * `RUFLO_LATTICE_WASM_PKG` is accepted as a back-compat alias.
+ */
+export const EMBED_WASM_PKG = process.env.RUFLO_EMBED_WASM_PKG || process.env.RUFLO_LATTICE_WASM_PKG || '';
+export const DEFAULT_EMBED_MODEL = process.env.RUFLO_EMBED_MODEL || 'default';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+let _mod = null;
+let _ready = false;
+let _probed = false;
+let _available = false;
+let _models = [];
+async function loadModule() {
+    if (!EMBED_WASM_PKG)
+        return null; // opt-in: no package configured ⇒ inert
+    if (_mod)
+        return _mod;
+    _mod = await import(EMBED_WASM_PKG).catch(() => null); // optional — absent ⇒ null ⇒ unavailable
+    return _mod;
+}
+async function ensureInit() {
+    if (_ready)
+        return true;
+    const mod = await loadModule();
+    if (!mod)
+        return false;
+    try {
+        if (typeof mod.initSync === 'function') {
+            let wasmBytes;
+            for (const cand of ['index_bg.wasm', 'embedder_bg.wasm', 'wasm_bg.wasm']) {
+                try {
+                    wasmBytes = readFileSync(require_.resolve(`${EMBED_WASM_PKG}/${cand}`));
+                    break;
+                }
+                catch { /* try next */ }
+            }
+            mod.initSync(wasmBytes ? { module: wasmBytes } : undefined);
+        }
+        else if (typeof mod.default === 'function') {
+            await mod.default();
+        }
+        _ready = true;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function toVec(r) {
+    const v = (r && typeof r === 'object' && 'embedding' in r) ? r.embedding : r;
+    if (!v)
+        return null;
+    if (Array.isArray(v))
+        return v;
+    if (v.length !== undefined)
+        return Array.from(v);
+    return null;
+}
+async function embedRaw(text, model) {
+    const mod = _mod;
+    if (!mod)
+        return null;
+    const attempts = [
+        () => typeof mod.embed === 'function' ? mod.embed(text, model) : undefined,
+        () => typeof mod.embed === 'function' ? mod.embed(text) : undefined,
+        () => typeof mod.embedText === 'function' ? mod.embedText(text, model) : undefined,
+        () => typeof mod.Embedder === 'function' ? new mod.Embedder(model).embed(text) : undefined,
+    ];
+    for (const a of attempts) {
+        try {
+            const r = await a();
+            const v = toVec(r);
+            if (v)
+                return v;
+        }
+        catch { /* try next surface */ }
+    }
+    return null;
+}
+/** Is an optional WASM embedder configured + installed + initializable? Cached; never throws. */
+export async function wasmEmbedderAvailable() {
+    if (_probed)
+        return _available;
+    _probed = true;
+    try {
+        if (!EMBED_WASM_PKG) {
+            _available = false;
+            return false;
+        } // opt-in; not configured
+        if (!(await ensureInit())) {
+            _available = false;
+            return false;
+        }
+        const mod = _mod;
+        try {
+            const list = typeof mod.listModels === 'function' ? mod.listModels() : (mod.models ?? mod.MODELS);
+            if (Array.isArray(list) && list.length)
+                _models = list;
+        }
+        catch { /* leave default */ }
+        if (!_models.length)
+            _models = [DEFAULT_EMBED_MODEL];
+        const probe = await embedRaw('probe', DEFAULT_EMBED_MODEL);
+        _available = !!probe && probe.length > 0;
+        return _available;
+    }
+    catch {
+        _available = false;
+        return false;
+    }
+}
+/** Models the configured WASM embedder reports (empty until available). */
+export function wasmEmbedderModels() { return [..._models]; }
+/** Embed via the optional WASM embedder, or null (caller falls through). Never throws. */
+export async function wasmEmbed(text, model = DEFAULT_EMBED_MODEL) {
+    try {
+        if (!(await wasmEmbedderAvailable()))
+            return null;
+        return await embedRaw(text, model);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=wasm-embedder.js.map

package/v3/@claude-flow/cli/dist/src/services/memory-backup.d.ts

@@ -21,4 +21,33 @@ export interface BackupResult {
 }
 export declare function defaultMemoryDbPath(cwd?: string): string;
 export declare function backupMemoryDb(opts?: BackupOptions): Promise<BackupResult>;
+export interface RestoreResult {
+    restored: boolean;
+    /** The backup file that was restored. */
+    from?: string;
+    /** memory_entries count in the restored DB (-1 if it couldn't be verified). */
+    rows?: number;
+    /** Where the corrupt live DB was parked before the swap. */
+    corruptBackupPath?: string;
+    skipped?: string;
+}
+/**
+ * Restore the newest integrity-ok backup over a corrupt/malformed memory DB
+ * (issue #2584).
+ *
+ * The in-place rebuild path (`recoverMemoryDatabase`) rebuilds FROM the corrupt
+ * image, so when the damage is bad enough that `sqlite3 .recover` salvages
+ * nothing, that rebuild also salvages nothing and every `memory_store` keeps
+ * erroring. This is the missing fallback: scan `<db dir>/backups/` newest-first,
+ * pick the newest snapshot that passes `PRAGMA integrity_check` (and has rows),
+ * park the corrupt live DB at `<db>.corrupt-<ts>.bak`, then ATOMICALLY install
+ * the good backup (copy → fsync → rename, no full-image buffer in memory). Drops
+ * stale -wal/-shm. Non-destructive on failure: the live DB is only replaced once
+ * a verified backup is in hand.
+ */
+export declare function restoreMemoryDbFromBackup(dbPath: string, opts?: {
+    destDir?: string;
+    timestamp?: number;
+    verbose?: boolean;
+}): Promise<RestoreResult>;
 //# sourceMappingURL=memory-backup.d.ts.map

package/v3/@claude-flow/cli/dist/src/services/memory-backup.js

@@ -91,4 +91,108 @@ export async function backupMemoryDb(opts = {}) {
     }
     return { backedUp: true, path: destPath, sizeBytes, rotatedAway, gcsUri };
 }
+/**
+ * Restore the newest integrity-ok backup over a corrupt/malformed memory DB
+ * (issue #2584).
+ *
+ * The in-place rebuild path (`recoverMemoryDatabase`) rebuilds FROM the corrupt
+ * image, so when the damage is bad enough that `sqlite3 .recover` salvages
+ * nothing, that rebuild also salvages nothing and every `memory_store` keeps
+ * erroring. This is the missing fallback: scan `<db dir>/backups/` newest-first,
+ * pick the newest snapshot that passes `PRAGMA integrity_check` (and has rows),
+ * park the corrupt live DB at `<db>.corrupt-<ts>.bak`, then ATOMICALLY install
+ * the good backup (copy → fsync → rename, no full-image buffer in memory). Drops
+ * stale -wal/-shm. Non-destructive on failure: the live DB is only replaced once
+ * a verified backup is in hand.
+ */
+export async function restoreMemoryDbFromBackup(dbPath, opts = {}) {
+    if (!dbPath)
+        return { restored: false, skipped: 'no-db-path' };
+    const destDir = opts.destDir ?? path.join(path.dirname(dbPath), 'backups');
+    let snaps;
+    try {
+        snaps = fs
+            .readdirSync(destDir)
+            .filter(f => /^memory-.*\.db$/.test(f))
+            .map(f => path.join(destDir, f))
+            .sort() // ISO-stamped names sort chronologically
+            .reverse(); // newest first
+    }
+    catch {
+        return { restored: false, skipped: 'no-backups-dir' };
+    }
+    if (!snaps.length)
+        return { restored: false, skipped: 'no-backups' };
+    // better-sqlite3 verifies a candidate's integrity. Absent (WASM-only host) →
+    // accept the newest non-empty snapshot, flagged rows=-1 (unverified).
+    let Database = null;
+    try {
+        const mod = 'better-sqlite3';
+        Database = (await import(mod)).default;
+    }
+    catch {
+        /* verifier unavailable — trust newest non-empty */
+    }
+    let chosen = null;
+    for (const file of snaps) {
+        try {
+            if (Database) {
+                const db = new Database(file, { readonly: true });
+                const integ = String(db.pragma('integrity_check', { simple: true }) ?? '');
+                let rows = 0;
+                try {
+                    rows = db.prepare('SELECT COUNT(*) AS c FROM memory_entries').get()?.c ?? 0;
+                }
+                catch { /* no entries table — not a usable memory DB */ }
+                db.close();
+                if (integ.toLowerCase() === 'ok' && rows > 0) {
+                    chosen = { file, rows };
+                    break;
+                }
+            }
+            else if (fs.statSync(file).size > 0) {
+                chosen = { file, rows: -1 };
+                break;
+            }
+        }
+        catch { /* unreadable snapshot — try the next-older one */ }
+    }
+    if (!chosen)
+        return { restored: false, skipped: 'no-integrity-ok-backup' };
+    const ts = opts.timestamp ?? Date.now();
+    const corruptBackupPath = `${dbPath}.corrupt-${ts}.bak`;
+    const tmp = `${dbPath}.restoring-${ts}`;
+    try {
+        if (fs.existsSync(dbPath))
+            fs.copyFileSync(dbPath, corruptBackupPath);
+        fs.copyFileSync(chosen.file, tmp); // stream copy — no 185MB buffer
+        const fd = fs.openSync(tmp, 'r+');
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        } // durable before swap
+        fs.renameSync(tmp, dbPath); // atomic install
+        for (const s of ['-wal', '-shm']) {
+            try {
+                fs.rmSync(`${dbPath}${s}`, { force: true });
+            }
+            catch { /* */ }
+        }
+    }
+    catch (e) {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch { /* */ }
+        return { restored: false, skipped: `install failed: ${e?.message ?? e}` };
+    }
+    if (opts.verbose) {
+        console.log(`memory DB restored from backup ${path.basename(chosen.file)}` +
+            (chosen.rows >= 0 ? ` (${chosen.rows} rows)` : ' (unverified)') +
+            `. Corrupt original saved to ${corruptBackupPath}`);
+    }
+    return { restored: true, from: chosen.file, rows: chosen.rows, corruptBackupPath };
+}
 //# sourceMappingURL=memory-backup.js.map

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.25.0",
+  "version": "3.25.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",