@claude-flow/cli 3.43.0 → 3.45.0

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

@@ -1,13 +1,14 @@
 {
   "manifest": {
-    "version": "3.43.0",
+    "version": "3.45.0",
     "files": {
       "auto-memory-hook.mjs": "85fe05c757421c52137c0bc8545a0896bab6b4714538c2a11d1d0835bfcc8c1c",
       "hook-handler.cjs": "209d9fafe10e17d1be0866727f6f9cf9ac66f9a0793f1c793a4f58319e8e4583",
       "intelligence.cjs": "30e42ed7ec4ca5a94ac54fdb1330d2d47ac5f3fdeeef207753574723a9e77b5c",
-      "statusline.cjs": "4a48353b4f1566fa4379b00fd0321b6676a22b6cc91fbbd8380ac5183d619468"
+      "statusline.cjs": "4a48353b4f1566fa4379b00fd0321b6676a22b6cc91fbbd8380ac5183d619468",
+      "router.js": "b6998397e7883191b62229ccdc66fb87f1ccca1d5b2039ecb8c1e686d1ad81f8"
     }
   },
-  "signature": "OlZvg4x9E5xfjdOatTAJz53uTxtK9dOj56GdkqnvqSWjFOKYCWWmbdijaMeVugo9e/u1y06VtWDGXrKSL82xDA==",
+  "signature": "IO42tJDeyKIl8l7ewYgoPdlZqQdsESvjIJr3KoAHDYHTi7gMCElwEyah4jx/RC6+Lq2zXv8XSOd/cgHI2U5zAg==",
   "algorithm": "ed25519"
 }

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 6,
-  "generatedAt": "2026-09-23T15:00:55.000Z",
-  "gitSha": "025842bb",
+  "generatedAt": "2026-09-24T22:48:10.625Z",
+  "gitSha": "aab1d625",
   "catalog": {
     "agents": 167,
     "tools": 418,

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

@@ -12,6 +12,15 @@ interface HealthCheck {
     fix?: string;
 }
 export declare function checkMemoryPersistenceDriver(): Promise<HealthCheck>;
+/**
+ * #3392: pure verdict for "does the @claude-flow/memory the CLI loads satisfy
+ * the range the CLI declares?". `npx @claude-flow/cli@latest` reuses one npx
+ * cache directory across CLI versions, and npm keeps an already-installed
+ * dependency that still satisfies a caret range, so a stale memory could
+ * survive a CLI upgrade with no error. Exported for unit testing.
+ */
+export declare function evaluateMemoryPackageVersion(declared: string | null, installed: string | null): HealthCheck;
+export declare function checkMemoryPackageVersion(): Promise<HealthCheck>;
 export declare const doctorCommand: Command;
 export default doctorCommand;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/src/commands/doctor.js

@@ -13,7 +13,8 @@ import { execSync, exec } from 'child_process';
 import { promisify } from 'util';
 import { decodeKey, isEncryptionEnabled } from '../encryption/vault.js';
 import { isEncryptedBlob } from '../encryption/vault.js';
-import { resolveMemoryPackageFromProject, readMemoryPackageVersion, recordMemoryPackagePath, } from '../init/memory-package-resolver.js';
+import * as semver from 'semver';
+import { resolveMemoryPackageFromProject, resolveMemoryPackageFromCli, readMemoryPackageVersion, recordMemoryPackagePath, } from '../init/memory-package-resolver.js';
 // Promisified exec with proper shell and env inheritance for cross-platform support
 const execAsync = promisify(exec);
 /**
@@ -1045,6 +1046,70 @@ async function checkLearningBridge() {
         fix: 'npm i -D @claude-flow/memory   (optional dep appears absent — likely --omit=optional install)',
     };
 }
+/**
+ * #3392: pure verdict for "does the @claude-flow/memory the CLI loads satisfy
+ * the range the CLI declares?". `npx @claude-flow/cli@latest` reuses one npx
+ * cache directory across CLI versions, and npm keeps an already-installed
+ * dependency that still satisfies a caret range, so a stale memory could
+ * survive a CLI upgrade with no error. Exported for unit testing.
+ */
+export function evaluateMemoryPackageVersion(declared, installed) {
+    const NAME = '@claude-flow/memory version';
+    if (!declared) {
+        return { name: NAME, status: 'warn', message: 'could not read the @claude-flow/memory range declared by @claude-flow/cli' };
+    }
+    if (!installed) {
+        return {
+            name: NAME,
+            status: 'warn',
+            message: `@claude-flow/memory is not resolvable from the CLI (declared ${declared}) — memory features fall back to degraded paths`,
+            fix: `npm install @claude-flow/memory@${declared} --include=optional`,
+        };
+    }
+    if (!semver.validRange(declared) || !semver.valid(installed)) {
+        return { name: NAME, status: 'warn', message: `cannot compare installed ${installed} against declared ${declared}` };
+    }
+    if (semver.satisfies(installed, declared, { includePrerelease: true })) {
+        return { name: NAME, status: 'pass', message: `v${installed} satisfies declared ${declared}` };
+    }
+    // warn, not fail: a dev/hoisted layout can legitimately differ, and doctor's
+    // exit code must not depend on which copy a package manager happened to hoist.
+    return {
+        name: NAME,
+        status: 'warn',
+        message: `installed v${installed} does not satisfy declared ${declared} — a stale cached copy is running, so fixes shipped in a newer @claude-flow/memory are silently absent`,
+        fix: `rm -rf "$(npm config get cache)/_npx" && npx @claude-flow/cli@latest doctor   # or: npm install @claude-flow/memory@${declared}`,
+    };
+}
+export async function checkMemoryPackageVersion() {
+    try {
+        // Walk up from this module to the CLI package root (npx cache, global,
+        // project-local and monorepo dev all resolve the same way).
+        let declared = null;
+        let dir = dirname(fileURLToPath(import.meta.url));
+        for (let i = 0; i < 8 && declared === null; i++) {
+            const pj = join(dir, 'package.json');
+            if (existsSync(pj)) {
+                try {
+                    const pkg = JSON.parse(readFileSync(pj, 'utf-8'));
+                    if (pkg.name === '@claude-flow/cli') {
+                        declared = pkg.optionalDependencies?.['@claude-flow/memory'] ?? pkg.dependencies?.['@claude-flow/memory'] ?? null;
+                        break;
+                    }
+                }
+                catch { /* keep walking */ }
+            }
+            dir = dirname(dir);
+        }
+        // Resolve exactly as the CLI's own runtime does (its module context),
+        // not from process.cwd() — that would report the project's copy instead.
+        const distPath = resolveMemoryPackageFromCli();
+        return evaluateMemoryPackageVersion(declared, distPath ? readMemoryPackageVersion(distPath) : null);
+    }
+    catch (err) {
+        return { name: '@claude-flow/memory version', status: 'warn', message: `check failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 // Check API keys
 async function checkApiKeys() {
     const keys = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY', 'OPENAI_API_KEY'];
@@ -2393,6 +2458,7 @@ export const doctorCommand = {
             checkMemoryStructuralIntegrity, // #2737 — bounded, native quick_check on every default run
             checkMemoryPersistenceDriver, // #2968/#3321 — read-only native capability probe
             checkLearningBridge, // #2545 — can the auto-memory hook actually load @claude-flow/memory?
+            checkMemoryPackageVersion, // #3392 — loaded @claude-flow/memory must satisfy the CLI's declared range
             checkApiKeys,
             checkMcpServers,
             checkMcpSchemaOverhead, // #2726 — fixed tools/list prompt cost
@@ -2430,11 +2496,13 @@ export const doctorCommand = {
                 checkMemoryDatabase, // existing: exists + statable (unchanged)
                 checkMemoryIntegrity, // #2677 check 1: sql.js open + PRAGMA integrity_check
                 checkMemoryPersistenceDriver, // #2968/#3321: read-only native capability probe
+                checkMemoryPackageVersion, // #3392: loaded memory package satisfies the declared range
                 checkMemoryContent, // #2677 check 2: memory_entries content coverage
                 checkMemoryEmbeddingCoverage, // #2677 check 3: vector coverage on populated rows
                 checkMemoryReflexionCoverage, // #2677 check 6: episodes are retrievable
                 checkMemoryCritiqueCoverage, // #2677 check 6: feedback carries lessons
             ],
+            'memory-package': checkMemoryPackageVersion, // #3392
             'learning': checkLearningBridge, // #2545
             'learning-bridge': checkLearningBridge, // #2545
             'api': checkApiKeys,

package/dist/src/init/executor.js

@@ -499,7 +499,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
         const sourceHelpersForUpgrade = findSourceHelpersDir();
         if (sourceHelpersForUpgrade) {
             // Keep in sync with helper-refresh.ts:CRITICAL_HELPERS.
-            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs'];
+            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs', 'router.js'];
             for (const helperName of criticalHelpers) {
                 const targetPath = path.join(targetDir, '.claude', 'helpers', helperName);
                 const sourcePath = path.join(sourceHelpersForUpgrade, helperName);
@@ -524,6 +524,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 'hook-handler.cjs': generateHookHandler(),
                 'intelligence.cjs': generateIntelligenceStub(),
                 'auto-memory-hook.mjs': generateAutoMemoryHook(),
+                'router.js': generateAgentRouter(), // ADR-389
             };
             for (const [helperName, content] of Object.entries(generatedCritical)) {
                 const targetPath = path.join(targetDir, '.claude', 'helpers', helperName);

package/dist/src/init/helper-refresh.js

@@ -71,6 +71,10 @@ export const CRITICAL_HELPERS = [
     // statusline.cjs is here so the funnel disclosure row (ADR-301) reaches
     // existing installs on the next `ruflo` command, not only fresh `ruflo init`.
     'statusline.cjs',
+    // router.js is loaded by hook-handler.cjs to label each prompt with an agent.
+    // Without it here, installs kept the pre-#2257 substring router forever
+    // ("latest" -> tester). ADR-389 / #3401.
+    'router.js',
 ];
 function errorCode(error) {
     return typeof error === 'object' && error !== null && 'code' in error
@@ -309,6 +313,7 @@ async function writeCriticalHelpers(helpersDir, version, opts = {}) {
         'hook-handler.cjs': gen.generateHookHandler(),
         'intelligence.cjs': gen.generateIntelligenceStub(),
         'auto-memory-hook.mjs': gen.generateAutoMemoryHook(),
+        'router.js': gen.generateAgentRouter(), // ADR-389
         // Fallback needs the same generator inputs `ruflo init` uses. We match the
         // hardcoded default (maxAgents 15) because the fallback fires when the
         // installed package is unresolvable — no way to read the user's project

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

@@ -3,6 +3,7 @@
  * Provides intelligent hooks functionality via MCP protocol
  */
 import { type MCPTool } from './types.js';
+import { type RouterEmbedderKind } from '../ruvector/router-embedder.js';
 /**
  * Strip extended-thinking blocks from text before it enters a learning
  * trajectory (hermes-agent think_scrubber pattern). Claude models with extended
@@ -13,6 +14,8 @@ import { type MCPTool } from './types.js';
  * the tag names untouched.
  */
 export declare function scrubReasoningBlocks(text: string): string;
+/** Test hook: drop the cached semantic index so the next route rebuilds it. */
+export declare function resetSemanticRouterForTests(): void;
 /** Exported for tests. */
 export declare function suggestAgentsForTask(task: string): {
     agents: string[];
@@ -23,6 +26,34 @@ export declare const hooksPostEdit: MCPTool;
 export declare const hooksPreCommand: MCPTool;
 export declare const hooksPostCommand: MCPTool;
 export declare const hooksRoute: MCPTool;
+/** Result of {@link routeTaskForBench}. */
+export interface BenchRouteResult {
+    primaryAgent: string;
+    confidence: number;
+    /** Matched pattern name, or 'keyword-fallback'. */
+    pattern: string;
+    /** Embedder actually used ('hash' if MiniLM was requested but unavailable). */
+    embedder: RouterEmbedderKind;
+    embedderReason?: string;
+    /** routing.method of the underlying route ('semantic-native' | 'semantic-pure-js' | 'keyword'). */
+    method: string;
+}
+/**
+ * INTERNAL / BENCH-ONLY (ADR-391). Not a public API; may change without notice.
+ *
+ * Routes `task` through the same local path `hooks_route` uses (semantic index +
+ * keyword fallback) with an explicit embedder, without the MCP layer. It skips
+ * the two steps that are neither ADR-391 candidate A nor B: the AgentDB
+ * pre-route (`bridgeRouteTask`, which answers first when its confidence > 0.5)
+ * and the opt-in typesafe wrapper (CLAUDE_FLOW_ROUTER_TYPESAFE). With those
+ * inactive, `primaryAgent` equals `hooks_route`'s `primaryAgent.type`.
+ *
+ * Switching `embedder` between calls rebuilds the index; benchmark in blocks.
+ */
+export declare function routeTaskForBench(task: string, opts: {
+    embedder: RouterEmbedderKind;
+    context?: string;
+}): Promise<BenchRouteResult>;
 export declare const hooksMetrics: MCPTool;
 export declare const hooksList: MCPTool;
 export declare const hooksPreTask: MCPTool;

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

@@ -10,6 +10,7 @@ import { validateIdentifier, validateText, validatePath } from './validate-input
 import { checkCommandLoop, recordCommandOutcome } from './tool-loop-guardrail.js';
 import { buildLearnedRoutingPatterns, } from '../services/learned-routing.js';
 import { applyTypesafeRouting, getTypesafeRouter } from '../ruvector/typesafe-router.js';
+import { DEFAULT_ROUTER_EMBEDDER, embedForRouter, resolveRouterEmbedder, } from '../ruvector/router-embedder.js';
 // Real vector search functions - lazy loaded to avoid circular imports
 let searchEntriesFn = null;
 /**
@@ -108,46 +109,16 @@ async function getMoERouter() {
 // Tries native VectorDb first (16k+ routes/s HNSW), falls back to pure JS (47k routes/s cosine)
 let semanticRouter = null;
 let nativeVectorDb = null;
-let semanticRouterInitialized = false;
 let routerBackend = 'none';
 // Pre-computed embeddings for common task patterns (cached)
 const TASK_PATTERN_EMBEDDINGS = new Map();
-function generateSimpleEmbedding(text, dimension = 384) {
-    // Simple deterministic embedding based on character codes
-    // This is for routing purposes where we need consistent, fast embeddings
-    const embedding = new Float32Array(dimension);
-    const normalized = text.toLowerCase().replace(/[^a-z0-9\s]/g, '');
-    const words = normalized.split(/\s+/).filter(w => w.length > 0);
-    // Combine word-level and character-level features
-    for (let i = 0; i < dimension; i++) {
-        let value = 0;
-        // Word-level features
-        for (let w = 0; w < words.length; w++) {
-            const word = words[w];
-            for (let c = 0; c < word.length; c++) {
-                const charCode = word.charCodeAt(c);
-                value += Math.sin((charCode * (i + 1) + w * 17 + c * 23) * 0.0137);
-            }
-        }
-        // Character-level features
-        for (let c = 0; c < text.length; c++) {
-            value += Math.cos((text.charCodeAt(c) * (i + 1) + c * 7) * 0.0073);
-        }
-        embedding[i] = value / Math.max(1, text.length);
-    }
-    // Normalize
-    let norm = 0;
-    for (let i = 0; i < dimension; i++) {
-        norm += embedding[i] * embedding[i];
-    }
-    norm = Math.sqrt(norm);
-    if (norm > 0) {
-        for (let i = 0; i < dimension; i++) {
-            embedding[i] /= norm;
-        }
-    }
-    return embedding;
-}
+// ADR-390: the router's embedder (MiniLM or the historical hash). Pattern and
+// query vectors always come from the SAME embedder; `routerEmbedder` records the
+// one that actually built the current index (after any degradation to hash).
+let routerEmbedder = DEFAULT_ROUTER_EMBEDDER;
+let routerEmbedderReason;
+let routerRequestedEmbedder = null;
+let routerInitPromise = null;
 // ── Runtime routing outcome persistence ──────────────────────────────
 // Closes the learning loop: post-task records outcomes → route loads them.
 const ROUTING_OUTCOMES_PATH = join(resolve('.'), '.claude-flow/routing-outcomes.json');
@@ -191,7 +162,8 @@ function saveRoutingOutcomes(outcomes) {
         // The prior singleton cache made the learned store inert until restart.
         semanticRouter = null;
         nativeVectorDb = null;
-        semanticRouterInitialized = false;
+        routerInitPromise = null;
+        routerRequestedEmbedder = null;
         routerBackend = 'none';
         TASK_PATTERN_EMBEDDINGS.clear();
     }
@@ -277,12 +249,58 @@ function withTypesafeRouting(legacy) {
 /**
  * Get the semantic router with environment detection.
  * Tries native VectorDb first (HNSW, 16k routes/s), falls back to pure JS (47k routes/s cosine).
+ *
+ * ADR-390: `requested` (else CLAUDE_FLOW_ROUTER_EMBEDDER, else the default)
+ * picks the embedder. The index is rebuilt when the requested embedder changes.
+ * Concurrent callers share one in-flight build.
  */
-async function getSemanticRouter() {
-    if (semanticRouterInitialized) {
-        return { router: semanticRouter, backend: routerBackend, native: nativeVectorDb };
+async function getSemanticRouter(requested) {
+    const selection = resolveRouterEmbedder(requested);
+    if (routerInitPromise && routerRequestedEmbedder === selection.kind) {
+        return routerInitPromise;
     }
-    semanticRouterInitialized = true;
+    semanticRouter = null;
+    nativeVectorDb = null;
+    routerBackend = 'none';
+    TASK_PATTERN_EMBEDDINGS.clear();
+    routerRequestedEmbedder = selection.kind;
+    routerInitPromise = buildSemanticRouter(selection.kind, selection.reason);
+    return routerInitPromise;
+}
+/** Test hook: drop the cached semantic index so the next route rebuilds it. */
+export function resetSemanticRouterForTests() {
+    semanticRouter = null;
+    nativeVectorDb = null;
+    routerBackend = 'none';
+    routerInitPromise = null;
+    routerRequestedEmbedder = null;
+    TASK_PATTERN_EMBEDDINGS.clear();
+}
+/** Embed every pattern keyword with ONE embedder (ADR-390: never mix spaces). */
+async function embedPatternKeywords(patterns, kind) {
+    const entries = Object.entries(patterns);
+    const flat = entries.flatMap(([, p]) => p.keywords);
+    const res = await embedForRouter(flat, kind);
+    const vectors = new Map();
+    let i = 0;
+    for (const [name, p] of entries) {
+        vectors.set(name, res.vectors.slice(i, i + p.keywords.length));
+        i += p.keywords.length;
+    }
+    return { vectors, embedder: res.embedder, reason: res.reason };
+}
+async function buildSemanticRouter(kind, selectionReason) {
+    const patterns = getMergedTaskPatterns();
+    const embedded = await embedPatternKeywords(patterns, kind);
+    routerEmbedder = embedded.embedder;
+    routerEmbedderReason = embedded.reason ?? selectionReason;
+    const handle = () => ({
+        router: semanticRouter,
+        backend: routerBackend,
+        native: nativeVectorDb,
+        embedder: routerEmbedder,
+        ...(routerEmbedderReason ? { embedderReason: routerEmbedderReason } : {}),
+    });
     // STEP 1: Try native VectorDb from @ruvector/router (HNSW-backed)
     // Note: Native VectorDb uses a persistent database file which can have lock issues
     // in concurrent environments. We try it first but fall back gracefully to pure JS.
@@ -304,17 +322,17 @@ async function getSemanticRouter() {
                     hnswEfSearch: 100,
                 });
                 // Initialize with static + runtime-learned task patterns
-                for (const [patternName, { keywords }] of Object.entries(getMergedTaskPatterns())) {
-                    for (const keyword of keywords) {
-                        const embedding = generateSimpleEmbedding(keyword);
-                        db.insert(`${patternName}:${keyword}`, embedding);
-                        TASK_PATTERN_EMBEDDINGS.set(`${patternName}:${keyword}`, embedding);
-                    }
+                for (const [patternName, { keywords }] of Object.entries(patterns)) {
+                    const embeddings = embedded.vectors.get(patternName) ?? [];
+                    keywords.forEach((keyword, i) => {
+                        db.insert(`${patternName}:${keyword}`, embeddings[i]);
+                        TASK_PATTERN_EMBEDDINGS.set(`${patternName}:${keyword}`, embeddings[i]);
+                    });
                 }
                 nativeVectorDb = db;
                 routerBackend = 'native';
-                console.log('[hooks] Semantic router initialized: native VectorDb (HNSW, 16k+ routes/s)');
-                return { router: null, backend: routerBackend, native: nativeVectorDb };
+                console.log(`[hooks] Semantic router initialized: native VectorDb (HNSW, 16k+ routes/s), embedder=${routerEmbedder}`);
+                return handle();
             }
         }
         catch (err) {
@@ -326,8 +344,8 @@ async function getSemanticRouter() {
     try {
         const { SemanticRouter } = await import('../ruvector/semantic-router.js');
         semanticRouter = new SemanticRouter({ dimension: 384 });
-        for (const [patternName, { keywords, agents, source, support, reliability }] of Object.entries(getMergedTaskPatterns())) {
-            const embeddings = keywords.map(kw => generateSimpleEmbedding(kw));
+        for (const [patternName, { keywords, agents, source, support, reliability }] of Object.entries(patterns)) {
+            const embeddings = embedded.vectors.get(patternName) ?? [];
             semanticRouter.addIntentWithEmbeddings(patternName, embeddings, {
                 agents,
                 keywords,
@@ -341,14 +359,14 @@ async function getSemanticRouter() {
             });
         }
         routerBackend = 'pure-js';
-        console.log('[hooks] Semantic router initialized: pure JS (cosine, 47k routes/s)');
+        console.log(`[hooks] Semantic router initialized: pure JS (cosine, 47k routes/s), embedder=${routerEmbedder}`);
     }
     catch {
         semanticRouter = null;
         routerBackend = 'none';
         console.log('[hooks] Semantic router initialized: none (no backend available)');
     }
-    return { router: semanticRouter, backend: routerBackend, native: nativeVectorDb };
+    return handle();
 }
 /**
  * Get router backend info for status display.
@@ -1021,134 +1039,185 @@ export const hooksRoute = {
                 // AgentDB router not available — fall through to local routing
             }
         }
-        // Get router (tries native VectorDb first, falls back to pure JS)
-        const { router, backend, native } = useSemanticRouter
-            ? await getSemanticRouter()
-            : { router: null, backend: 'none', native: null };
-        let semanticResult = [];
-        let routingMethod = 'keyword';
-        let routingLatencyMs = 0;
-        let backendInfo = '';
-        const queryText = context ? `${task} ${context}` : task;
-        const queryEmbedding = generateSimpleEmbedding(queryText);
-        // Try native VectorDb (HNSW-backed)
-        if (native && backend === 'native') {
-            const routeStart = performance.now();
-            try {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const results = native.search(queryEmbedding, 5);
-                routingLatencyMs = performance.now() - routeStart;
-                routingMethod = 'semantic-native';
-                backendInfo = 'native VectorDb (HNSW)';
-                // Convert results to semantic format
-                const mergedPatterns = getMergedTaskPatterns();
-                semanticResult = results.map((r) => {
-                    const [patternName] = r.id.split(':');
-                    const pattern = mergedPatterns[patternName];
-                    return {
-                        intent: patternName,
-                        score: 1 - r.score, // Native uses distance (lower is better), convert to similarity
-                        metadata: {
-                            agents: pattern?.agents || (patternName.startsWith('learned-') ? [patternName.slice(8)] : ['coder']),
-                            source: pattern?.source ?? (patternName.startsWith('learned-') ? 'learned' : 'static'),
-                            support: pattern?.support,
-                            reliability: pattern?.reliability,
-                        },
-                    };
-                });
-            }
-            catch {
-                // Native failed, try pure JS fallback
-            }
-        }
-        // Try pure JS SemanticRouter fallback
-        if (router && backend === 'pure-js' && semanticResult.length === 0) {
-            const routeStart = performance.now();
-            semanticResult = router.routeWithEmbedding(queryEmbedding, 3);
+        return routeTaskLocal(task, context, useSemanticRouter);
+    }),
+};
+/**
+ * hooks_route's local routing (semantic index + keyword fallback), run after the
+ * AgentDB pre-route. Shared with {@link routeTaskForBench} so the benchmark
+ * measures exactly the path hooks_route takes. (Body kept at its original
+ * indentation to keep this refactor's diff small.)
+ */
+async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride) {
+    // Get router (tries native VectorDb first, falls back to pure JS)
+    let handle = useSemanticRouter
+        ? await getSemanticRouter(embedderOverride)
+        : {
+            router: null, backend: 'none', native: null,
+            embedder: resolveRouterEmbedder(embedderOverride).kind,
+            embedderReason: 'semantic router disabled (useSemanticRouter=false)',
+        };
+    let semanticResult = [];
+    let routingMethod = 'keyword';
+    let routingLatencyMs = 0;
+    let backendInfo = '';
+    const queryText = context ? `${task} ${context}` : task;
+    // ADR-390: the query is embedded with the embedder that built the index.
+    let queryEmbedding = null;
+    if (handle.router || handle.native) {
+        const q = await embedForRouter([queryText], handle.embedder);
+        if (q.embedder !== handle.embedder) {
+            // MiniLM failed on the query after building a MiniLM index: rebuild the
+            // index with the hash so patterns and query share one space again.
+            routerInitPromise = buildSemanticRouter('hash', q.reason);
+            handle = await routerInitPromise;
+        }
+        queryEmbedding = q.vectors[0];
+    }
+    const { router, backend, native } = handle;
+    // Try native VectorDb (HNSW-backed)
+    if (native && backend === 'native' && queryEmbedding) {
+        const routeStart = performance.now();
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const results = native.search(queryEmbedding, 5);
             routingLatencyMs = performance.now() - routeStart;
-            routingMethod = 'semantic-pure-js';
-            backendInfo = 'pure JS (cosine similarity)';
-        }
-        // Get agents from semantic routing or fall back to keyword
-        let agents;
-        let confidence;
-        let matchedPattern = '';
-        // Both static and learned patterns are gated on the same similarity
-        // score. Learned patterns additionally require support/reliability as a
-        // quality guard, but do NOT need a higher score bar — a learned pattern
-        // that outscores every static candidate must not lose to one anyway
-        // (#2864: a 25pp higher threshold made a top-scoring learned-researcher
-        // match at 0.57 lose to a static match at 0.52, discarding the learned
-        // store's output on the majority of routes).
-        const eligibleSemantic = semanticResult.find((match) => {
-            if (match.score <= 0.4)
-                return false;
-            const learned = match.intent.startsWith('learned-') || match.metadata.source === 'learned';
-            if (!learned)
-                return true;
-            return Number(match.metadata.support ?? 0) >= 2
-                && Number(match.metadata.reliability ?? 0) >= 0.75;
-        });
-        if (eligibleSemantic) {
-            const topMatch = eligibleSemantic;
-            agents = topMatch.metadata.agents || ['coder', 'researcher'];
-            confidence = topMatch.score;
-            matchedPattern = topMatch.intent;
+            routingMethod = 'semantic-native';
+            backendInfo = 'native VectorDb (HNSW)';
+            // Convert results to semantic format
+            const mergedPatterns = getMergedTaskPatterns();
+            semanticResult = results.map((r) => {
+                const [patternName] = r.id.split(':');
+                const pattern = mergedPatterns[patternName];
+                return {
+                    intent: patternName,
+                    score: 1 - r.score, // Native uses distance (lower is better), convert to similarity
+                    metadata: {
+                        agents: pattern?.agents || (patternName.startsWith('learned-') ? [patternName.slice(8)] : ['coder']),
+                        source: pattern?.source ?? (patternName.startsWith('learned-') ? 'learned' : 'static'),
+                        support: pattern?.support,
+                        reliability: pattern?.reliability,
+                    },
+                };
+            });
         }
-        else {
-            // Fall back to keyword matching
-            const suggestion = suggestAgentsForTask(task);
-            agents = suggestion.agents;
-            confidence = suggestion.confidence;
-            matchedPattern = 'keyword-fallback';
-            routingMethod = 'keyword';
-            backendInfo = 'keyword matching';
+        catch {
+            // Native failed, try pure JS fallback
         }
-        // Determine complexity
-        const taskLower = task.toLowerCase();
-        const complexity = taskLower.includes('complex') || taskLower.includes('architecture') || task.length > 200
-            ? 'high'
-            : taskLower.includes('simple') || taskLower.includes('fix') || task.length < 50
-                ? 'low'
-                : 'medium';
-        return {
-            task,
-            routing: {
-                method: routingMethod,
-                backend: backendInfo,
-                latencyMs: routingLatencyMs,
-                throughput: routingLatencyMs > 0 ? `${Math.round(1000 / routingLatencyMs)} routes/s` : 'N/A',
-            },
-            matchedPattern,
-            semanticMatches: semanticResult.slice(0, 3).map(r => ({
-                pattern: r.intent,
-                score: Math.round(r.score * 100) / 100,
-            })),
-            primaryAgent: {
-                type: agents[0],
-                confidence: Math.round(confidence * 100) / 100,
-                reason: routingMethod.startsWith('semantic')
-                    ? `Semantic similarity to "${matchedPattern}" pattern (${Math.round(confidence * 100)}%)`
-                    : `Task contains keywords matching ${agents[0]} specialization`,
-            },
-            alternativeAgents: agents.slice(1).map((agent, i) => ({
-                type: agent,
-                confidence: Math.round((confidence - (0.1 * (i + 1))) * 100) / 100,
-                reason: `Alternative agent for ${agent} capabilities`,
-            })),
-            estimatedMetrics: {
-                successProbability: Math.round(confidence * 100) / 100,
-                estimatedDuration: complexity === 'high' ? '2-4 hours' : complexity === 'medium' ? '30-60 min' : '10-30 min',
-                complexity,
-            },
-            swarmRecommendation: agents.length > 2 ? {
-                topology: 'hierarchical',
-                agents,
-                coordination: 'queen-led',
-            } : null,
-        };
-    }),
-};
+    }
+    // Try pure JS SemanticRouter fallback
+    if (router && backend === 'pure-js' && queryEmbedding && semanticResult.length === 0) {
+        const routeStart = performance.now();
+        semanticResult = router.routeWithEmbedding(queryEmbedding, 3);
+        routingLatencyMs = performance.now() - routeStart;
+        routingMethod = 'semantic-pure-js';
+        backendInfo = 'pure JS (cosine similarity)';
+    }
+    // Get agents from semantic routing or fall back to keyword
+    let agents;
+    let confidence;
+    let matchedPattern = '';
+    // Both static and learned patterns are gated on the same similarity
+    // score. Learned patterns additionally require support/reliability as a
+    // quality guard, but do NOT need a higher score bar — a learned pattern
+    // that outscores every static candidate must not lose to one anyway
+    // (#2864: a 25pp higher threshold made a top-scoring learned-researcher
+    // match at 0.57 lose to a static match at 0.52, discarding the learned
+    // store's output on the majority of routes).
+    const eligibleSemantic = semanticResult.find((match) => {
+        if (match.score <= 0.4)
+            return false;
+        const learned = match.intent.startsWith('learned-') || match.metadata.source === 'learned';
+        if (!learned)
+            return true;
+        return Number(match.metadata.support ?? 0) >= 2
+            && Number(match.metadata.reliability ?? 0) >= 0.75;
+    });
+    if (eligibleSemantic) {
+        const topMatch = eligibleSemantic;
+        agents = topMatch.metadata.agents || ['coder', 'researcher'];
+        confidence = topMatch.score;
+        matchedPattern = topMatch.intent;
+    }
+    else {
+        // Fall back to keyword matching
+        const suggestion = suggestAgentsForTask(task);
+        agents = suggestion.agents;
+        confidence = suggestion.confidence;
+        matchedPattern = 'keyword-fallback';
+        routingMethod = 'keyword';
+        backendInfo = 'keyword matching';
+    }
+    // Determine complexity
+    const taskLower = task.toLowerCase();
+    const complexity = taskLower.includes('complex') || taskLower.includes('architecture') || task.length > 200
+        ? 'high'
+        : taskLower.includes('simple') || taskLower.includes('fix') || task.length < 50
+            ? 'low'
+            : 'medium';
+    return {
+        task,
+        routing: {
+            method: routingMethod,
+            backend: backendInfo,
+            latencyMs: routingLatencyMs,
+            throughput: routingLatencyMs > 0 ? `${Math.round(1000 / routingLatencyMs)} routes/s` : 'N/A',
+        },
+        matchedPattern,
+        semanticMatches: semanticResult.slice(0, 3).map(r => ({
+            pattern: r.intent,
+            score: Math.round(r.score * 100) / 100,
+        })),
+        primaryAgent: {
+            type: agents[0],
+            confidence: Math.round(confidence * 100) / 100,
+            reason: routingMethod.startsWith('semantic')
+                ? `Semantic similarity to "${matchedPattern}" pattern (${Math.round(confidence * 100)}%)`
+                : `Task contains keywords matching ${agents[0]} specialization`,
+        },
+        alternativeAgents: agents.slice(1).map((agent, i) => ({
+            type: agent,
+            confidence: Math.round((confidence - (0.1 * (i + 1))) * 100) / 100,
+            reason: `Alternative agent for ${agent} capabilities`,
+        })),
+        estimatedMetrics: {
+            successProbability: Math.round(confidence * 100) / 100,
+            estimatedDuration: complexity === 'high' ? '2-4 hours' : complexity === 'medium' ? '30-60 min' : '10-30 min',
+            complexity,
+        },
+        swarmRecommendation: agents.length > 2 ? {
+            topology: 'hierarchical',
+            agents,
+            coordination: 'queen-led',
+        } : null,
+        // ADR-390: which embedder the semantic index + query used ('hash' when degraded).
+        embedder: handle.embedder,
+        ...(handle.embedderReason ? { embedderReason: handle.embedderReason } : {}),
+    };
+}
+/**
+ * INTERNAL / BENCH-ONLY (ADR-391). Not a public API; may change without notice.
+ *
+ * Routes `task` through the same local path `hooks_route` uses (semantic index +
+ * keyword fallback) with an explicit embedder, without the MCP layer. It skips
+ * the two steps that are neither ADR-391 candidate A nor B: the AgentDB
+ * pre-route (`bridgeRouteTask`, which answers first when its confidence > 0.5)
+ * and the opt-in typesafe wrapper (CLAUDE_FLOW_ROUTER_TYPESAFE). With those
+ * inactive, `primaryAgent` equals `hooks_route`'s `primaryAgent.type`.
+ *
+ * Switching `embedder` between calls rebuilds the index; benchmark in blocks.
+ */
+export async function routeTaskForBench(task, opts) {
+    const r = await routeTaskLocal(task, opts.context, true, opts.embedder);
+    return {
+        primaryAgent: r.primaryAgent.type,
+        confidence: r.primaryAgent.confidence,
+        pattern: r.matchedPattern,
+        embedder: r.embedder,
+        ...(r.embedderReason ? { embedderReason: r.embedderReason } : {}),
+        method: String(r.routing?.method ?? ''),
+    };
+}
 export const hooksMetrics = {
     name: 'hooks_metrics',
     description: 'View learning metrics dashboard Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',

package/dist/src/ruvector/router-embedder.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Router embedder (ADR-390).
+ *
+ * `hooks_route` compares a task with each agent pattern's keywords in a 384-d
+ * vector index. Historically both sides came from a character hash
+ * (`generateSimpleEmbedding`), which measures spelling, not meaning. This
+ * module lets the router use the local sentence model (all-MiniLM-L6-v2, 384-d)
+ * instead, with the hash as the fallback.
+ *
+ * Rules (ADR-390 §Decision):
+ *  - The MiniLM path uses `generateLocalEmbedding` ONLY. Never the bridge-first
+ *    `generateEmbedding` — that recursed without bound in #2312.
+ *  - One embedder per index: if ANY text cannot be embedded by the real model
+ *    (throw, backend !== 'onnx', or a non-384 vector), EVERY text in the call
+ *    is embedded with the hash, and the result says so.
+ *  - The default stays `hash` until ADR-391's benchmark says otherwise.
+ *
+ * Selection: `CLAUDE_FLOW_ROUTER_EMBEDDER=minilm|hash`. The router index is
+ * process-lifetime state, so the env var is read when the index is (re)built,
+ * not per CLI invocation.
+ */
+export type RouterEmbedderKind = 'minilm' | 'hash';
+/** Default embedder. ADR-391 decides whether this flips to 'minilm'. */
+export declare const DEFAULT_ROUTER_EMBEDDER: RouterEmbedderKind;
+/** Dimension of the router index (VectorDb + SemanticRouter are built at 384). */
+export declare const ROUTER_EMBEDDING_DIM = 384;
+export declare const ROUTER_EMBEDDER_ENV = "CLAUDE_FLOW_ROUTER_EMBEDDER";
+export interface RouterEmbedderSelection {
+    kind: RouterEmbedderKind;
+    /** Set when the requested value was invalid and the default was used. */
+    reason?: string;
+}
+export interface RouterEmbeddingResult {
+    vectors: Float32Array[];
+    /** The embedder that actually produced `vectors` (after any degradation). */
+    embedder: RouterEmbedderKind;
+    /** Why the result is `hash` when `minilm` was requested. */
+    reason?: string;
+}
+/**
+ * Resolve which embedder the router should use.
+ * Precedence: explicit override > CLAUDE_FLOW_ROUTER_EMBEDDER > DEFAULT_ROUTER_EMBEDDER.
+ */
+export declare function resolveRouterEmbedder(override?: RouterEmbedderKind, env?: NodeJS.ProcessEnv): RouterEmbedderSelection;
+/**
+ * Deterministic character-hash embedding (the router's historical embedder).
+ * Moved verbatim from hooks-tools.ts; do not change the math — existing routes
+ * and thresholds were calibrated against it.
+ */
+export declare function generateSimpleEmbedding(text: string, dimension?: number): Float32Array;
+/**
+ * Embed texts for the router. All vectors in one result come from ONE embedder.
+ * `hash` never touches the model (no load cost for default users).
+ */
+export declare function embedForRouter(texts: readonly string[], kind?: RouterEmbedderKind): Promise<RouterEmbeddingResult>;
+/** Test hook: clear the MiniLM vector memo. */
+export declare function clearRouterEmbedderCache(): void;
+//# sourceMappingURL=router-embedder.d.ts.map

package/dist/src/ruvector/router-embedder.js

@@ -0,0 +1,141 @@
+/**
+ * Router embedder (ADR-390).
+ *
+ * `hooks_route` compares a task with each agent pattern's keywords in a 384-d
+ * vector index. Historically both sides came from a character hash
+ * (`generateSimpleEmbedding`), which measures spelling, not meaning. This
+ * module lets the router use the local sentence model (all-MiniLM-L6-v2, 384-d)
+ * instead, with the hash as the fallback.
+ *
+ * Rules (ADR-390 §Decision):
+ *  - The MiniLM path uses `generateLocalEmbedding` ONLY. Never the bridge-first
+ *    `generateEmbedding` — that recursed without bound in #2312.
+ *  - One embedder per index: if ANY text cannot be embedded by the real model
+ *    (throw, backend !== 'onnx', or a non-384 vector), EVERY text in the call
+ *    is embedded with the hash, and the result says so.
+ *  - The default stays `hash` until ADR-391's benchmark says otherwise.
+ *
+ * Selection: `CLAUDE_FLOW_ROUTER_EMBEDDER=minilm|hash`. The router index is
+ * process-lifetime state, so the env var is read when the index is (re)built,
+ * not per CLI invocation.
+ */
+// memory-initializer is imported lazily (as hooks-tools does elsewhere): it is
+// heavy, and the default `hash` path must not load it at all.
+/** Default embedder. ADR-391 decides whether this flips to 'minilm'. */
+export const DEFAULT_ROUTER_EMBEDDER = 'hash';
+/** Dimension of the router index (VectorDb + SemanticRouter are built at 384). */
+export const ROUTER_EMBEDDING_DIM = 384;
+export const ROUTER_EMBEDDER_ENV = 'CLAUDE_FLOW_ROUTER_EMBEDDER';
+/**
+ * Resolve which embedder the router should use.
+ * Precedence: explicit override > CLAUDE_FLOW_ROUTER_EMBEDDER > DEFAULT_ROUTER_EMBEDDER.
+ */
+export function resolveRouterEmbedder(override, env = process.env) {
+    if (override)
+        return { kind: override };
+    // Env-only by design (registered in scripts/audit-env-var-precedence.mjs):
+    // the router index is process-lifetime MCP state, not owned by one CLI call.
+    const raw = env.CLAUDE_FLOW_ROUTER_EMBEDDER?.trim().toLowerCase();
+    if (!raw)
+        return { kind: DEFAULT_ROUTER_EMBEDDER };
+    if (raw === 'minilm' || raw === 'hash')
+        return { kind: raw };
+    return {
+        kind: DEFAULT_ROUTER_EMBEDDER,
+        reason: `${ROUTER_EMBEDDER_ENV}=${JSON.stringify(raw)} is not 'minilm' or 'hash'; using '${DEFAULT_ROUTER_EMBEDDER}'`,
+    };
+}
+/**
+ * Deterministic character-hash embedding (the router's historical embedder).
+ * Moved verbatim from hooks-tools.ts; do not change the math — existing routes
+ * and thresholds were calibrated against it.
+ */
+export function generateSimpleEmbedding(text, dimension = ROUTER_EMBEDDING_DIM) {
+    const embedding = new Float32Array(dimension);
+    const normalized = text.toLowerCase().replace(/[^a-z0-9\s]/g, '');
+    const words = normalized.split(/\s+/).filter(w => w.length > 0);
+    for (let i = 0; i < dimension; i++) {
+        let value = 0;
+        // Word-level features
+        for (let w = 0; w < words.length; w++) {
+            const word = words[w];
+            for (let c = 0; c < word.length; c++) {
+                const charCode = word.charCodeAt(c);
+                value += Math.sin((charCode * (i + 1) + w * 17 + c * 23) * 0.0137);
+            }
+        }
+        // Character-level features
+        for (let c = 0; c < text.length; c++) {
+            value += Math.cos((text.charCodeAt(c) * (i + 1) + c * 7) * 0.0073);
+        }
+        embedding[i] = value / Math.max(1, text.length);
+    }
+    return l2Normalize(embedding);
+}
+function l2Normalize(v) {
+    let norm = 0;
+    for (let i = 0; i < v.length; i++)
+        norm += v[i] * v[i];
+    norm = Math.sqrt(norm);
+    if (norm > 0)
+        for (let i = 0; i < v.length; i++)
+            v[i] /= norm;
+    return v;
+}
+// Per-(embedder, text) memo. Keyword vectors don't change when the pattern set
+// changes, so this survives router rebuilds (e.g. after saveRoutingOutcomes).
+const MINILM_CACHE = new Map();
+const MINILM_CACHE_MAX = 2048;
+async function embedOneMiniLM(text) {
+    const cached = MINILM_CACHE.get(text);
+    if (cached)
+        return cached;
+    const { generateLocalEmbedding } = await import('../memory/memory-initializer.js');
+    const out = await generateLocalEmbedding(text);
+    if (out.backend !== 'onnx') {
+        throw new RouterEmbedderDegraded(`local embedder backend is '${out.backend}' (model '${out.model}'), not onnx`);
+    }
+    if (!out.embedding || out.embedding.length !== ROUTER_EMBEDDING_DIM) {
+        throw new RouterEmbedderDegraded(`local embedder returned ${out.embedding?.length ?? 0}-d vectors; router index is ${ROUTER_EMBEDDING_DIM}-d`);
+    }
+    const vec = l2Normalize(Float32Array.from(out.embedding));
+    if (MINILM_CACHE.size >= MINILM_CACHE_MAX) {
+        const oldest = MINILM_CACHE.keys().next().value;
+        if (oldest !== undefined)
+            MINILM_CACHE.delete(oldest);
+    }
+    MINILM_CACHE.set(text, vec);
+    return vec;
+}
+class RouterEmbedderDegraded extends Error {
+}
+/**
+ * Embed texts for the router. All vectors in one result come from ONE embedder.
+ * `hash` never touches the model (no load cost for default users).
+ */
+export async function embedForRouter(texts, kind = resolveRouterEmbedder().kind) {
+    if (kind === 'hash') {
+        return { vectors: texts.map(t => generateSimpleEmbedding(t)), embedder: 'hash' };
+    }
+    try {
+        const vectors = [];
+        for (const t of texts)
+            vectors.push(await embedOneMiniLM(t));
+        return { vectors, embedder: 'minilm' };
+    }
+    catch (err) {
+        const why = err instanceof RouterEmbedderDegraded
+            ? err.message
+            : `local embedder threw: ${err instanceof Error ? err.message : String(err)}`;
+        return {
+            vectors: texts.map(t => generateSimpleEmbedding(t)),
+            embedder: 'hash',
+            reason: `minilm unavailable (${why}); using hash for patterns and query`,
+        };
+    }
+}
+/** Test hook: clear the MiniLM vector memo. */
+export function clearRouterEmbedderCache() {
+    MINILM_CACHE.clear();
+}
+//# sourceMappingURL=router-embedder.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.43.0",
+  "version": "3.45.0",
   "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.25"
   },
   "optionalDependencies": {
     "@agntcy/slim-bindings": "2.0.0-alpha.5",
-    "@claude-flow/memory": "^3.0.0-alpha.23",
+    "@claude-flow/memory": "3.0.0-alpha.25",
     "@metaharness/darwin": "~0.10.2",
     "@metaharness/flywheel": "~0.1.10",
     "@metaharness/radio": "~0.1.0",