@claude-flow/cli 3.38.0 → 3.38.2

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

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.38.0",
+    "version": "3.38.2",
     "files": {
       "auto-memory-hook.mjs": "85fe05c757421c52137c0bc8545a0896bab6b4714538c2a11d1d0835bfcc8c1c",
       "hook-handler.cjs": "dae295fb9ae2626b89899c19a20cc911541af82b52d2eeb9b214d618b96e9a86",
@@ -8,6 +8,6 @@
       "statusline.cjs": "0457fe53f8cd2c56458ff178392536a5868efd1a573665fa43bc01d2d95ca677"
     }
   },
-  "signature": "KDmhF8M4Fz1bTODUCbObwx77UqNUnPWCiF/k/TrpKlga0vFmu0Ax1k/JAPKLi5LmVvtZBpl1NWKm+SHnavP+Cg==",
+  "signature": "aUyZD8VBc8slPjWIexWvx5vD6cF9ms5YKEDvLl+6WSX8Y0hrtXQgSs42Bmetyqj0LTRW5+W9GF3kUNB6zGiDBw==",
   "algorithm": "ed25519"
 }

package/README.md

@@ -56,7 +56,7 @@ There are **two different install paths** with very different surface areas. Pic
 |---|---|---|
 | What it gives you | Slash commands + a few skills + agent definitions per-plugin | Full Ruflo loop — 98 agents, 60+ commands, 30 skills, MCP server, hooks, daemon |
 | Files in your workspace | **Zero** | `.claude/`, `.claude-flow/`, `CLAUDE.md`, helpers, settings |
-| MCP server registered | **No** (`memory_store`, `swarm_init`, etc. unavailable to Claude) | Yes |
+| MCP server registered | Only if `ruflo-core` is installed (it ships its own `.mcp.json`) — most other plugins don't | Yes |
 | Hooks installed | No | Yes |
 | Best for | Try a single plugin's commands without committing to the full install | Production use — everything works as documented |
 
@@ -73,7 +73,7 @@ There are **two different install paths** with very different surface areas. Pic
 /plugin install ruflo-neural-trader@ruflo
 ```
 
-This adds slash commands and agent definitions only. The Ruflo MCP server is NOT registered, so `memory_store`, `swarm_init`, `agent_spawn`, etc. won't be callable from Claude. For the full loop, use Path B below.
+This adds slash commands and agent definitions. `ruflo-core` (installed above) does register its own MCP server on install — its tools are callable as `mcp__plugin_ruflo-core_ruflo__*` (e.g. `mcp__plugin_ruflo-core_ruflo__memory_store`), not the bare `memory_store`/`swarm_init`/`agent_spawn` names the CLI-track scaffold uses. Other plugins generally don't ship their own MCP server. For the full loop with the CLI-track tool names, use Path B below.
 
 <details>
 <summary><strong>🔌 All 35 plugins</strong></summary>
@@ -187,8 +187,8 @@ npm install -g ruflo@latest
 ### MCP Server
 
 ```bash
-# Add Ruflo as an MCP server in Claude Code (canonical form, matches USERGUIDE.md)
-claude mcp add ruflo -- npx ruflo@latest mcp start
+# Add Ruflo as an MCP server in Claude Code
+claude mcp add claude-flow -- npx ruflo@latest mcp start
 ```
 
 ---

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 4,
-  "generatedAt": "2026-08-11T22:42:24.276Z",
-  "gitSha": "6b01dc5a",
+  "generatedAt": "2026-08-12T15:41:12.144Z",
+  "gitSha": "87f4f8ab",
   "catalog": {
     "agents": 164,
     "tools": 397,

package/dist/src/commands/mcp.js

@@ -201,7 +201,43 @@ const startCommand = {
             if (daemon) {
                 output.writeln(output.dim('  Running in background mode'));
             }
-            return { success: true, data: status };
+            // #2984: this command is only reached via the "normal CLI mode" branch
+            // of bin/cli.js — i.e. every invocation NOT auto-detected as Claude
+            // Code's implicit piped-stdin MCP handshake (that path bypasses this
+            // action entirely and blocks on stdin forever, which is why it was
+            // unaffected). bin/cli.js unconditionally exits the process once this
+            // action's promise resolves (`cli.run().then(() => process.exit(0))`,
+            // #1552) — a design that assumed "mcp start never resolves" but this
+            // action DID resolve immediately after printing the table above, so
+            // the freshly-bound http/websocket listener (or the interactive-TTY
+            // stdio server) was torn down within milliseconds of the printed
+            // "Status: Running" claim. `daemonize` is not currently wired to
+            // actually fork/detach a background process (no branch reads it in
+            // MCPServerManager), so there is no real backgrounding path yet —
+            // every successful start here is a foreground server and must block
+            // until told to stop, matching `daemon start --foreground`'s
+            // established pattern in daemon.ts.
+            output.writeln();
+            output.writeln(output.dim('Press Ctrl+C to stop the server'));
+            let stopping = false;
+            const shutdown = async () => {
+                if (stopping)
+                    return;
+                stopping = true;
+                try {
+                    await manager.stop();
+                }
+                catch { /* best-effort */ }
+                process.exit(0);
+            };
+            process.on('SIGINT', () => { void shutdown(); });
+            process.on('SIGTERM', () => { void shutdown(); });
+            // Ref'd handle so Node's event loop can't drain to empty even if some
+            // transport internals unref their own timers — same belt-and-suspenders
+            // as daemon.ts's foreground path (#1478).
+            setInterval(() => { }, 60_000);
+            await new Promise(() => { }); // Never resolves — server runs until killed.
+            return { success: true, data: status }; // unreachable, keeps the return type honest
         }
         catch (error) {
             output.printError(`Failed to start MCP server: ${error.message}`);

package/dist/src/commands/memory.js

@@ -214,7 +214,15 @@ const storeCommand = {
                 ]
             });
             output.writeln();
-            output.printSuccess('Data stored successfully');
+            if (result.persistWarning) {
+                // #2968: the write ran, but the checkpoint signal indicates it may
+                // not have reached disk (sql.js fallback driver) — do not print an
+                // unconditional green success for a write that might vanish.
+                output.printWarning(`Data stored, but persistence is not guaranteed: ${result.persistWarning}`);
+            }
+            else {
+                output.printSuccess('Data stored successfully');
+            }
             return { success: true, data: { ...storeData, id: result.id, embedding: result.embedding, provenanceType: provenance || 'unknown' } };
         }
         catch (error) {

package/dist/src/commands/migrate-agent-detection.js

@@ -105,7 +105,11 @@ export function detectRemovedAgentGaps(cwd, removedAgents, options = {}) {
         gaps.push({
             agent: basename,
             plugin,
-            installCommand: `ruflo plugins install ${plugin}`,
+            // #2985: these are Claude Code *marketplace* plugins. `ruflo plugins
+            // install` targets a different system (the npm-package PluginManager —
+            // see the module header) and cannot install them; the marketplace
+            // command below is the one that satisfies the registry check above.
+            installCommand: `/plugin install ${plugin}@ruflo`,
         });
     }
     return gaps;

package/dist/src/commands/migrate-agent-restore.d.ts

@@ -0,0 +1,30 @@
+import type { RemovedAgentGap } from './migrate-agent-detection.js';
+export type RestoreSource = 'marketplace-clone' | 'repo-checkout' | 'github-tag' | 'github-main';
+export interface RestoreResult {
+    agent: string;
+    plugin: string;
+    status: 'restored' | 'skipped' | 'failed';
+    /** Where the content came from (set when status === 'restored'). */
+    source?: RestoreSource;
+    /** Project-relative path written (set when status === 'restored' | 'skipped'). */
+    path?: string;
+    /** Human-readable failure reason (set when status === 'failed'). */
+    error?: string;
+}
+export interface RestoreRemovedAgentsOptions {
+    /** Test injection: overrides os.homedir() for the marketplace-clone probe. */
+    homeDir?: string;
+    /** Test injection: overrides global fetch for the GitHub fallback. */
+    fetchImpl?: typeof fetch;
+    /** CLI version used to pin the GitHub tag (e.g. "3.38.1" -> tag v3.38.1). */
+    version?: string;
+    /** Report what would be written without writing. */
+    dryRun?: boolean;
+}
+/**
+ * Restore each gap's agent file into <cwd>/.claude/agents/<category>/.
+ * Never overwrites an existing file (detection already excludes present
+ * basenames anywhere under .claude/agents/, but re-check defensively).
+ */
+export declare function restoreRemovedAgents(cwd: string, gaps: RemovedAgentGap[], options?: RestoreRemovedAgentsOptions): Promise<RestoreResult[]>;
+//# sourceMappingURL=migrate-agent-restore.d.ts.map

package/dist/src/commands/migrate-agent-restore.js

@@ -0,0 +1,201 @@
+/**
+ * ADR-382 Part B follow-up (#2985) — `ruflo migrate fix --agents`: actually
+ * restore the agents ADR-128 Phase 2 removed from the init template, instead
+ * of only pointing at them.
+ *
+ * Content resolution order (first hit wins):
+ *   1. The Claude Code marketplace clone, when present —
+ *      ~/.claude/plugins/marketplaces/ruflo/plugins/<plugin>/agents/<basename>
+ *   2. A repo checkout at the project root (dogfood / development) —
+ *      <cwd>/plugins/<plugin>/agents/<basename>
+ *   3. GitHub raw, pinned to this CLI's own version tag (v<version>), falling
+ *      back to `main` when the tag predates the file. Requires network; the
+ *      failure message says so explicitly.
+ *
+ * npm-track consideration: plugin agent bodies reference the
+ * `mcp__plugin_ruflo-core_ruflo__*` tool namespace, which only resolves when
+ * ruflo-core is installed as a Claude Code marketplace plugin. A user
+ * reaching for this command is on the npm track (otherwise the owning plugin
+ * would cover the gap and no restore would be offered), so restored copies
+ * are rewritten to the canonical `claude-flow` server key (#2206). The
+ * rewrite is annotated in a provenance comment inside the restored file.
+ *
+ * Kept in a sibling module (not migrate.ts) for the same reason as
+ * migrate-agent-detection.ts — migrate.ts is over the 500-line budget.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { fileURLToPath } from 'node:url';
+// Same local-reader pattern as mcp-tools/system-tools.ts — avoids importing
+// from ../index.js (cycle risk) just for a version string.
+function getPackageVersion() {
+    try {
+        const dir = path.dirname(fileURLToPath(import.meta.url));
+        for (const depth of ['../..', '../../..']) {
+            const pkgPath = path.join(dir, depth, 'package.json');
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name?.includes('claude-flow') || pkg.name === 'ruflo') {
+                    return pkg.version;
+                }
+            }
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Marketplace plugin namespace prefix — resolves only under a marketplace install. */
+const PLUGIN_NAMESPACE_PREFIX = 'mcp__plugin_ruflo-core_ruflo__';
+/** Canonical npm-track namespace for the same server (key `claude-flow`, #2206). */
+const CANONICAL_NAMESPACE_PREFIX = 'mcp__claude-flow__';
+/**
+ * Where each removed agent lived in the init template before ADR-128 Phase 2
+ * deleted it (see the ADR's Gap 2 table). Restoring to the original category
+ * keeps category-based tooling (e.g. `--agents=<cat>` style filters) working.
+ */
+const RESTORE_CATEGORY = {
+    'coder.md': 'core',
+    'researcher.md': 'core',
+    'reviewer.md': 'core',
+    'tester.md': 'core',
+    'memory-specialist.md': 'v3',
+    'security-auditor.md': 'v3',
+    'sparc-orchestrator.md': 'v3',
+    'adr-architect.md': 'v3',
+    'goal-planner.md': 'goal',
+};
+const GITHUB_RAW_BASE = 'https://raw.githubusercontent.com/ruvnet/ruflo';
+function findFileRecursive(dir, basename, depth) {
+    if (depth > 4)
+        return null;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const hit = findFileRecursive(full, basename, depth + 1);
+            if (hit)
+                return hit;
+        }
+        else if (entry.isFile() && entry.name === basename) {
+            return full;
+        }
+    }
+    return null;
+}
+function readLocalCandidate(root, plugin, basename) {
+    const agentsDir = path.join(root, 'plugins', plugin, 'agents');
+    const hit = findFileRecursive(agentsDir, basename, 0);
+    if (!hit)
+        return null;
+    try {
+        return fs.readFileSync(hit, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchGithubCandidate(fetchImpl, ref, plugin, basename) {
+    const url = `${GITHUB_RAW_BASE}/${ref}/plugins/${plugin}/agents/${basename}`;
+    try {
+        const res = await fetchImpl(url);
+        if (!res.ok)
+            return null;
+        return await res.text();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Rewrite the marketplace-plugin tool namespace to the canonical npm-track
+ * one and record provenance right after the frontmatter block, so a reader
+ * (or a future dedup pass) can tell a restored copy from a hand-authored
+ * agent. Inserting after the closing `---` keeps frontmatter parseable.
+ */
+function adaptForNpmTrack(content, plugin, source) {
+    const rewritten = content.split(PLUGIN_NAMESPACE_PREFIX).join(CANONICAL_NAMESPACE_PREFIX);
+    const provenance = `<!-- restored by \`ruflo migrate fix --agents\` from plugins/${plugin} ` +
+        `(canonical per ADR-128; source: ${source}); MCP namespace rewritten to the ` +
+        `canonical claude-flow server key (#2206, #2985) -->`;
+    const fmClose = rewritten.indexOf('\n---', rewritten.startsWith('---') ? 3 : 0);
+    if (rewritten.startsWith('---') && fmClose !== -1) {
+        const insertAt = rewritten.indexOf('\n', fmClose + 1);
+        if (insertAt !== -1) {
+            return rewritten.slice(0, insertAt + 1) + provenance + '\n' + rewritten.slice(insertAt + 1);
+        }
+    }
+    return provenance + '\n' + rewritten;
+}
+async function resolveContent(cwd, homeDir, fetchImpl, version, plugin, basename) {
+    const marketplaceRoot = path.join(homeDir, '.claude', 'plugins', 'marketplaces', 'ruflo');
+    const fromMarketplace = readLocalCandidate(marketplaceRoot, plugin, basename);
+    if (fromMarketplace !== null)
+        return { content: fromMarketplace, source: 'marketplace-clone' };
+    const fromCheckout = readLocalCandidate(cwd, plugin, basename);
+    if (fromCheckout !== null)
+        return { content: fromCheckout, source: 'repo-checkout' };
+    if (version) {
+        const fromTag = await fetchGithubCandidate(fetchImpl, `v${version}`, plugin, basename);
+        if (fromTag !== null)
+            return { content: fromTag, source: 'github-tag' };
+    }
+    const fromMain = await fetchGithubCandidate(fetchImpl, 'main', plugin, basename);
+    if (fromMain !== null)
+        return { content: fromMain, source: 'github-main' };
+    return null;
+}
+/**
+ * Restore each gap's agent file into <cwd>/.claude/agents/<category>/.
+ * Never overwrites an existing file (detection already excludes present
+ * basenames anywhere under .claude/agents/, but re-check defensively).
+ */
+export async function restoreRemovedAgents(cwd, gaps, options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const version = options.version ?? getPackageVersion();
+    const results = [];
+    for (const gap of gaps) {
+        const category = RESTORE_CATEGORY[gap.agent] ?? 'core';
+        const relPath = path.join('.claude', 'agents', category, gap.agent);
+        const destPath = path.join(cwd, relPath);
+        if (fs.existsSync(destPath)) {
+            results.push({ agent: gap.agent, plugin: gap.plugin, status: 'skipped', path: relPath });
+            continue;
+        }
+        const resolved = await resolveContent(cwd, homeDir, fetchImpl, version, gap.plugin, gap.agent);
+        if (!resolved) {
+            results.push({
+                agent: gap.agent,
+                plugin: gap.plugin,
+                status: 'failed',
+                error: 'no local marketplace clone or repo checkout, and GitHub fetch failed ' +
+                    '(offline?) — install the owning plugin instead: ' +
+                    `/plugin install ${gap.plugin}@ruflo`,
+            });
+            continue;
+        }
+        const adapted = adaptForNpmTrack(resolved.content, gap.plugin, resolved.source);
+        if (!options.dryRun) {
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            fs.writeFileSync(destPath, adapted, 'utf-8');
+        }
+        results.push({
+            agent: gap.agent,
+            plugin: gap.plugin,
+            status: 'restored',
+            source: resolved.source,
+            path: relPath,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=migrate-agent-restore.js.map

package/dist/src/commands/migrate.js

@@ -6,6 +6,7 @@ import { output } from '../output.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { detectRemovedAgentGaps } from './migrate-agent-detection.js';
+import { restoreRemovedAgents } from './migrate-agent-restore.js';
 // Migration targets
 const MIGRATION_TARGETS = [
     { value: 'config', label: 'Configuration', hint: 'Migrate configuration files' },
@@ -167,6 +168,7 @@ const statusCommand = {
             });
             output.writeln();
             output.printInfo(`${removedAgentGaps.length} agent(s) removed by ADR-128 are missing from .claude/agents/ and not covered by an installed plugin.`);
+            output.printInfo('Run "ruflo migrate fix --agents" to restore them from their canonical plugin content, or install the owning plugin.');
         }
         return { success: true, data: { components, needsMigration, removedAgentGaps } };
     }
@@ -713,16 +715,81 @@ const breakingCommand = {
         return { success: true, data: changes };
     }
 };
+// Fix command — apply remediations that `status` can only point at (#2985).
+// Logic lives in migrate-agent-restore.ts (migrate.ts is over the 500-line
+// budget; same split as migrate-agent-detection.ts).
+const fixCommand = {
+    name: 'fix',
+    description: 'Apply fixes for gaps detected by "migrate status"',
+    options: [
+        {
+            name: 'agents',
+            description: 'Restore agents removed by ADR-128 from their canonical plugin content',
+            type: 'boolean',
+            default: false
+        },
+        {
+            name: 'dry-run',
+            short: 'd',
+            description: 'Show what would be restored without writing',
+            type: 'boolean',
+            default: false
+        }
+    ],
+    action: async (ctx) => {
+        const cwd = ctx.cwd || process.cwd();
+        if (!ctx.flags.agents) {
+            output.printInfo('Nothing selected. Pass --agents to restore ADR-128-removed agents.');
+            return { success: true };
+        }
+        const gaps = detectRemovedAgentGaps(cwd, REMOVED_AGENTS);
+        if (gaps.length === 0) {
+            output.printSuccess('No removed-agent gaps to fix — every agent is present or covered by an installed plugin.');
+            return { success: true, data: { results: [] } };
+        }
+        const dryRun = Boolean(ctx.flags['dry-run']);
+        const results = await restoreRemovedAgents(cwd, gaps, { dryRun });
+        if (ctx.flags.format === 'json') {
+            output.printJson({ dryRun, results });
+            return { success: results.every(r => r.status !== 'failed'), data: { dryRun, results } };
+        }
+        output.writeln();
+        output.writeln(output.bold(dryRun ? 'Restore Plan (dry run)' : 'Restored Agents'));
+        output.printTable({
+            columns: [
+                { key: 'agent', header: 'Agent', width: 24 },
+                { key: 'status', header: 'Status', width: 10 },
+                { key: 'detail', header: dryRun ? 'Would write' : 'Detail', width: 44 }
+            ],
+            data: results.map(r => ({
+                agent: r.agent,
+                status: r.status === 'failed' ? output.warning(r.status) : r.status,
+                detail: r.status === 'failed' ? output.dim(r.error ?? '') : output.dim(`${r.path ?? ''}${r.source ? ` (from ${r.source})` : ''}`)
+            })),
+            border: false
+        });
+        const failed = results.filter(r => r.status === 'failed');
+        output.writeln();
+        if (failed.length > 0) {
+            output.printWarning(`${failed.length} agent(s) could not be restored — install the owning plugin instead (see table).`);
+        }
+        else if (!dryRun) {
+            output.printSuccess(`${results.filter(r => r.status === 'restored').length} agent(s) restored. Re-run "ruflo migrate status" to verify.`);
+        }
+        return { success: failed.length === 0, data: { dryRun, results } };
+    }
+};
 // Main migrate command
 export const migrateCommand = {
     name: 'migrate',
     description: 'V2 to V3 migration tools',
-    subcommands: [statusCommand, runCommand, verifyCommand, rollbackCommand, breakingCommand],
+    subcommands: [statusCommand, runCommand, verifyCommand, rollbackCommand, breakingCommand, fixCommand],
     options: [],
     examples: [
         { command: 'claude-flow migrate status', description: 'Check migration status' },
         { command: 'claude-flow migrate run --dry-run', description: 'Preview migration' },
-        { command: 'claude-flow migrate run -t all', description: 'Run full migration' }
+        { command: 'claude-flow migrate run -t all', description: 'Run full migration' },
+        { command: 'claude-flow migrate fix --agents', description: 'Restore ADR-128-removed agents' }
     ],
     action: async (ctx) => {
         output.writeln();
@@ -736,7 +803,8 @@ export const migrateCommand = {
             `${output.highlight('run')}       - Run migration`,
             `${output.highlight('verify')}    - Verify migration integrity`,
             `${output.highlight('rollback')}  - Rollback to previous version`,
-            `${output.highlight('breaking')}  - Show breaking changes`
+            `${output.highlight('breaking')}  - Show breaking changes`,
+            `${output.highlight('fix')}       - Apply fixes for detected gaps (--agents)`
         ]);
         return { success: true };
     }

package/dist/src/init/executor.js

@@ -962,7 +962,9 @@ async function writeMCPConfig(targetDir, options, result) {
     // #1779/#2612 — Skip writing if the user already has this MCP server
     // registered elsewhere (parent .mcp.json, ~/.claude.json, etc). The
     // canonical key is `claude-flow` (per #2206 — matches mcp__claude-flow__*
-    // plugin tool refs); a stray `ruflo`-keyed entry pointing at the same
+    // tool refs used throughout the CLI-track scaffold; NOT the marketplace
+    // plugin binding, which is mcp__plugin_<plugin>_<server>__* per plugin —
+    // see #2985); a stray `ruflo`-keyed entry pointing at the same
     // binary is the legacy-duplicate form that #2612 healed. Writing our
     // fresh `claude-flow` entry on top of either variant starts the same
     // binary twice under two tool namespaces. Force-mode (`--force`)

package/dist/src/memory/memory-bridge.d.ts

@@ -67,6 +67,13 @@ export declare function bridgeStoreEntry(options: {
     cached?: boolean;
     attested?: boolean;
     error?: string;
+    /** #2968: set when the post-write checkpoint failed in a way that
+     *  indicates this connection may not durably persist writes at all
+     *  (the sql.js fallback driver, engaged when better-sqlite3's native
+     *  binding is missing). The write above still ran and `success` is
+     *  still true — this is advisory, not a failure — but callers should
+     *  surface it instead of only printing an unconditional success message. */
+    persistWarning?: string;
 } | null>;
 /**
  * Search entries via AgentDB v3.

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

@@ -897,12 +897,27 @@ export async function bridgeStoreEntry(options) {
         // `sqlite3` vector count) then see a stale/empty main DB file and report
         // "0 vectors" / empty search. A PASSIVE checkpoint flushes committed pages
         // into the main file without blocking writers. Best-effort, never fatal.
+        let persistWarning;
         try {
             if (typeof ctx.db.pragma === 'function') {
                 ctx.db.pragma('wal_checkpoint(PASSIVE)');
             }
         }
-        catch { /* non-WAL, busy, or unsupported — non-fatal */ }
+        catch (checkpointErr) {
+            // #2968: on the sql.js fallback driver (engaged when better-sqlite3's
+            // native binding never got built — e.g. a skipped optionalDependency
+            // postinstall), this PRAGMA isn't implemented and throws "Invalid
+            // PRAGMA command". sql.js has no WAL journal to checkpoint at all, so
+            // this specific failure is the strongest signal available here that
+            // the insert above may exist only in this process's in-memory image
+            // and never reach disk — not the ordinary "non-WAL, busy, or
+            // unsupported" case the old blanket catch assumed. Surface it rather
+            // than swallow it silently; other pragma failures stay non-fatal.
+            const msg = checkpointErr instanceof Error ? checkpointErr.message : String(checkpointErr);
+            if (/Invalid PRAGMA/i.test(msg)) {
+                persistWarning = `sql.js fallback driver in use — this write may not be durably persisted to disk (${msg}). Install better-sqlite3's native binding to restore durable writes (see issue #2968: npm rebuild better-sqlite3, or reinstall with install scripts enabled).`;
+            }
+        }
         // Phase 2: Write-through to TieredCache
         const safeNs = String(namespace).replace(/:/g, '_');
         const safeKey = String(key).replace(/:/g, '_');
@@ -918,6 +933,7 @@ export async function bridgeStoreEntry(options) {
             guarded: true,
             cached: true,
             attested: true,
+            ...(persistWarning ? { persistWarning } : {}),
         };
     }
     catch (err) {
@@ -995,10 +1011,17 @@ export async function bridgeSearchEntries(options) {
         const whereExtra = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
         let rows;
         try {
+            // #2982/#2976: this pre-rank SELECT truncates the corpus to 1000 rows
+            // before BM25/embedding scoring runs. Without ORDER BY, SQLite returns
+            // rows in arbitrary storage order (effectively oldest-inserted-first at
+            // scale), so on any corpus over 1000 entries the newest — and often
+            // most relevant — rows never reach scoring at all. bridgeListEntries()
+            // already orders by updated_at DESC for the same reason; mirror it here.
             const stmt = ctx.db.prepare(`
         SELECT id, key, namespace, content, embedding, provenance_type
         FROM memory_entries
         WHERE ${ACTIVE_MEMORY_ROW_SQL} ${whereExtra}
+        ORDER BY updated_at DESC
         LIMIT 1000
       `);
             rows = filterParams.length > 0 ? stmt.all(...filterParams) : stmt.all();
@@ -1506,10 +1529,14 @@ export async function bridgeSearchHNSW(queryEmbedding, options, dbPath) {
             : '';
         let rows;
         try {
+            // #2982/#2976: same unordered pre-rank truncation as bridgeSearchEntries
+            // above — without ORDER BY, a corpus over 10000 rows silently drops
+            // its newest entries before cosine scoring ever runs.
             const stmt = ctx.db.prepare(`
         SELECT id, key, namespace, content, embedding
         FROM memory_entries
         WHERE status = 'active' AND embedding IS NOT NULL ${nsFilter}
+        ORDER BY updated_at DESC
         LIMIT 10000
       `);
             rows = nsFilter

package/dist/src/memory/memory-initializer.d.ts

@@ -448,6 +448,9 @@ export declare function storeEntry(options: {
         model: string;
     };
     error?: string;
+    /** #2968: set when the bridge's checkpoint failed in a way indicating
+     *  this write may not be durably persisted (sql.js fallback driver). */
+    persistWarning?: string;
 }>;
 /**
  * Search entries using sql.js with vector similarity

package/package.json

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