claude-flow 3.48.0 → 3.49.0

package/v3/@claude-flow/cli/dist/src/init/helper-refresh.js

@@ -20,6 +20,8 @@ import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import * as semver from 'semver';
 import { verifyHelpersManifest, sha256Hex, HELPERS_MANIFEST_FILE, } from './helper-signing.js';
+import { ensureCommonJsCompanions } from './helper-companions.js';
+import { verifyInstalledCriticalHelpers } from './helper-integrity.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 /**
  * Walk up from `startDir` to the nearest ancestor whose `package.json` names
@@ -71,10 +73,11 @@ 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.
+    // router.cjs 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',
+    // ("latest" -> tester). ADR-389 / #3401. It is CommonJS, so it ships as
+    // `.cjs`: a `.js` copy cannot load in a `"type":"module"` project (#3555).
+    'router.cjs',
 ];
 function errorCode(error) {
     return typeof error === 'object' && error !== null && 'code' in error
@@ -230,7 +233,7 @@ export function getInstalledCliVersion() {
     }
 }
 /** Locate the in-package `.claude/helpers` dir (the copy source). Null if not found. */
-function findPackageHelpersDir() {
+export function findPackageHelpersDir() {
     const candidates = [];
     try {
         const esmRequire = createRequire(import.meta.url);
@@ -313,7 +316,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
+        'router.cjs': gen.generateAgentRouter(), // ADR-389 / #3555
         // 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
@@ -339,9 +342,12 @@ async function writeCriticalHelpers(helpersDir, version, opts = {}) {
 }
 /**
  * On CLI startup: if an initialized project's critical helpers are stamped older
- * than the installed CLI version, silently re-copy them. Fast path is a single
- * stamp read + string compare (sub-ms); the copy runs at most once per version
- * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
+ * than the installed CLI version, silently re-copy them. Fast path is a stamp
+ * read + string compare, PLUS a re-hash of each installed critical helper
+ * against the signed manifest (#3565) — still sub-ms for the handful of small
+ * files involved, and lock-free unless a mismatch is found. The copy runs at
+ * most once per version bump; the heal-on-tamper path can run on any call.
+ * Best-effort, never throws. No-op outside a ruflo project (requires an
  * existing hook-handler.cjs — never creates files in an unrelated directory).
  *
  * FORWARD-ONLY (never downgrades): refreshing on any mere INEQUALITY, rather
@@ -365,6 +371,9 @@ async function writeCriticalHelpers(helpersDir, version, opts = {}) {
  * `pubkeyPemOverride` let a test build its own tiny, throwaway-keypair-
  * signed fixture and get real, deterministic coverage of the verify → hash →
  * copy logic without depending on that.
+ *
+ * #3565: also re-verifies on every stamp-match call (see helper-integrity.ts)
+ * and heals a mismatch via this same verify-then-copy path.
  */
 async function refreshOneHelpersDirLocked(helpersDir, version, opts) {
     if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs')))
@@ -377,7 +386,9 @@ async function refreshOneHelpersDirLocked(helpersDir, version, opts) {
     // on this repo (CLAUDE.md "Concurrent-session helper corruption"). The
     // existing semver.gte guard below still fires for normal installs — this
     // is the escape hatch for the small set of users editing helpers directly.
-    // Applies to whichever dir this call is refreshing (project or global).
+    // Applies to whichever dir this call is refreshing (project or global),
+    // and also exempts it from the #3565 integrity re-check below — a
+    // deliberate local edit is not "tampering".
     if (fs.existsSync(path.join(helpersDir, '.LOCKED'))) {
         return { refreshed: false, blocked: '.LOCKED marker present — refresh skipped (delete to re-enable)' };
     }
@@ -386,8 +397,28 @@ async function refreshOneHelpersDirLocked(helpersDir, version, opts) {
         stamped = fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim();
     }
     catch { /* pre-feature: unstamped */ }
-    if (stamped === version)
-        return { refreshed: false }; // up to date — fast path
+    if (stamped === version) {
+        const source = opts.sourceDirOverride ?? findPackageHelpersDir();
+        const integrity = verifyInstalledCriticalHelpers(helpersDir, source, CRITICAL_HELPERS, opts.pubkeyPemOverride);
+        if (integrity.blocked)
+            return { refreshed: false, blocked: integrity.blocked };
+        if (integrity.tampered.length === 0)
+            return { refreshed: false }; // up to date AND verified intact
+        // Tampering detected post-install — heal via the same fail-closed
+        // verify-then-copy path a version-bump refresh already uses.
+        await opts.beforeWriteOverride?.();
+        const healRes = await writeCriticalHelpers(helpersDir, version, {
+            sourceDirOverride: opts.sourceDirOverride,
+            pubkeyPemOverride: opts.pubkeyPemOverride,
+        });
+        if (healRes.blocked)
+            return { refreshed: false, blocked: healRes.blocked };
+        if (healRes.wrote)
+            await ensureCommonJsCompanions(helpersDir); // #3555
+        return healRes.wrote
+            ? { refreshed: true, healed: true, tampered: integrity.tampered, from: stamped, to: version }
+            : { refreshed: false };
+    }
     if (stamped && semver.valid(stamped) && semver.valid(version) && semver.gte(stamped, version)) {
         // Stamped version is already >= what this binary reports — refreshing
         // would silently DOWNGRADE the helpers. Skip, untouched.
@@ -400,6 +431,8 @@ async function refreshOneHelpersDirLocked(helpersDir, version, opts) {
     });
     if (res.blocked)
         return { refreshed: false, blocked: res.blocked };
+    if (res.wrote)
+        await ensureCommonJsCompanions(helpersDir); // #3555
     return res.wrote ? { refreshed: true, from: stamped || '(unstamped)', to: version } : { refreshed: false };
 }
 async function refreshOneHelpersDir(helpersDir, version, opts) {
@@ -412,8 +445,18 @@ async function refreshOneHelpersDir(helpersDir, version, opts) {
         return { refreshed: false, blocked: '.LOCKED marker present — refresh skipped (delete to re-enable)' };
     }
     try {
-        if (fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim() === version)
-            return { refreshed: false };
+        if (fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim() === version) {
+            // #3565: re-hash before trusting a stamp match (helper-integrity.ts).
+            // Read-only — no lock needed unless something's actually wrong; the
+            // (rare) heal path below re-verifies under lock.
+            const source = opts.sourceDirOverride ?? findPackageHelpersDir();
+            const integrity = verifyInstalledCriticalHelpers(helpersDir, source, CRITICAL_HELPERS, opts.pubkeyPemOverride);
+            if (integrity.blocked)
+                return { refreshed: false, blocked: integrity.blocked };
+            if (integrity.tampered.length === 0)
+                return { refreshed: false };
+            // else: tampering found — fall through to acquire the lock and heal.
+        }
     }
     catch { /* unstamped: continue to the locked path */ }
     const releaseLock = await acquireRefreshLock(helpersDir, opts);

package/v3/@claude-flow/cli/dist/src/init/helpers-generator.js

@@ -242,7 +242,7 @@ const [,, command, ...args] = process.argv;
 if (command && commands[command]) {
   commands[command](...args);
 } else {
-  console.log('Usage: session.js <start|restore|end|status|update|metric> [args]');
+  console.log('Usage: session.cjs <start|restore|end|status|update|metric> [args]');
 }
 
 module.exports = commands;
@@ -336,7 +336,7 @@ if (require.main === module) {
     const result = routeTask(task);
     console.log(JSON.stringify(result, null, 2));
   } else {
-    console.log('Usage: router.js <task description>');
+    console.log('Usage: router.cjs <task description>');
     console.log('\\nAvailable agents:', Object.keys(AGENT_CAPABILITIES).join(', '));
   }
 }
@@ -427,7 +427,7 @@ const value = valueParts.join(' ');
 if (command && commands[command]) {
   commands[command](key, value);
 } else {
-  console.log('Usage: memory.js <get|set|delete|clear|keys> [key] [value]');
+  console.log('Usage: memory.cjs <get|set|delete|clear|keys> [key] [value]');
 }
 
 module.exports = commands;
@@ -504,9 +504,9 @@ export function generateHookHandler() {
         '  return null;',
         '}',
         '',
-        "const router = safeRequire(path.join(helpersDir, 'router.js'));",
-        "const session = safeRequire(path.join(helpersDir, 'session.js'));",
-        "const memory = safeRequire(path.join(helpersDir, 'memory.js'));",
+        "const router = safeRequire(path.join(helpersDir, 'router.cjs'));",
+        "const session = safeRequire(path.join(helpersDir, 'session.cjs'));",
+        "const memory = safeRequire(path.join(helpersDir, 'memory.cjs'));",
         "const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));",
         '',
         'const [,, command, ...args] = process.argv;',
@@ -1358,7 +1358,7 @@ const [,, command, ...args] = process.argv;
 if (command && commands[command]) {
   commands[command](...args);
 } else {
-  console.log('Usage: session.js <start|restore|end|status>');
+  console.log('Usage: session.cjs <start|restore|end|status>');
   console.log(\`Platform: \${platform}\`);
   console.log(\`Data dir: \${SESSION_DIR}\`);
 }
@@ -1376,9 +1376,9 @@ export function generateHelpers(options) {
         helpers['pre-commit'] = generatePreCommitHook();
         helpers['post-commit'] = generatePostCommitHook();
         // Cross-platform Node.js scripts
-        helpers['session.js'] = generateCrossPlatformSessionManager();
-        helpers['router.js'] = generateAgentRouter();
-        helpers['memory.js'] = generateMemoryHelper();
+        helpers['session.cjs'] = generateCrossPlatformSessionManager();
+        helpers['router.cjs'] = generateAgentRouter();
+        helpers['memory.cjs'] = generateMemoryHelper();
         // Windows-specific scripts
         helpers['daemon-manager.ps1'] = generateWindowsDaemonManager();
         helpers['daemon-manager.cmd'] = generateWindowsBatchWrapper();

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.d.ts

@@ -12,11 +12,24 @@ import { type RouterEmbedderKind } from '../ruvector/router-embedder.js';
 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): {
+/**
+ * Confidence for a task nothing matched (#3567). It must rank below every real
+ * signal: keyword hits are >= 0.8, learned outcomes >= 0.7, and a semantic
+ * match is only eligible above 0.4. Matches the helper router's 0.3 fall-through.
+ */
+export declare const NO_MATCH_CONFIDENCE = 0.3;
+export interface TaskAgentSuggestion {
     agents: string[];
     confidence: number;
-};
+    /** false when no keyword or learned pattern matched; the agents are a default, not a decision. */
+    matched: boolean;
+    reason?: 'no-match-default';
+    note?: string;
+}
+/** True when the task has at least one letter or digit in any script. */
+export declare function hasRoutableText(task: string): boolean;
+/** Exported for tests. */
+export declare function suggestAgentsForTask(task: string): TaskAgentSuggestion;
 export declare const hooksPreEdit: MCPTool;
 export declare const hooksPostEdit: MCPTool;
 export declare const hooksPreCommand: MCPTool;

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

@@ -722,12 +722,41 @@ const KEYWORD_MATCHERS = Object.entries(KEYWORD_PATTERNS).map(([keyword, result]
     const body = /[\s/]/.test(keyword) ? escaped : `${escaped}(?:s|es|ing|ed)?`;
     return { regex: new RegExp(`\\b${body}\\b`, 'i'), result };
 });
+/**
+ * Confidence for a task nothing matched (#3567). It must rank below every real
+ * signal: keyword hits are >= 0.8, learned outcomes >= 0.7, and a semantic
+ * match is only eligible above 0.4. Matches the helper router's 0.3 fall-through.
+ */
+export const NO_MATCH_CONFIDENCE = 0.3;
+/** True when the task has at least one letter or digit in any script. */
+export function hasRoutableText(task) {
+    return /[\p{L}\p{N}]/u.test(task);
+}
+// Keyword matchers are English regexes; letters outside Latin script can never hit them.
+const NON_LATIN_LETTER = /(?![A-Za-zÀ-ɏ])\p{L}/u;
+function noMatchNote(task) {
+    if (!hasRoutableText(task))
+        return 'Task has no words to match.';
+    if (NON_LATIN_LETTER.test(task)) {
+        return 'Keyword matchers are English-only, so non-English text cannot match them.';
+    }
+    return 'No keyword or learned pattern matched.';
+}
 /** Exported for tests. */
 export function suggestAgentsForTask(task) {
+    const noMatch = () => ({
+        agents: ['coder', 'researcher', 'tester'],
+        confidence: NO_MATCH_CONFIDENCE,
+        matched: false,
+        reason: 'no-match-default',
+        note: noMatchNote(task),
+    });
+    if (!hasRoutableText(task))
+        return noMatch();
     // Check static keyword patterns first
     for (const { regex, result } of KEYWORD_MATCHERS) {
         if (regex.test(task)) {
-            return result;
+            return { ...result, matched: true };
         }
     }
     // Check runtime-learned patterns from successful task outcomes
@@ -747,11 +776,10 @@ export function suggestAgentsForTask(task) {
         }
         // Require at least 2 keyword overlap to prevent false positives
         if (bestAgent && bestOverlap >= 2) {
-            return { agents: [bestAgent], confidence: Math.min(0.6 + bestOverlap * 0.05, 0.85) };
+            return { agents: [bestAgent], confidence: Math.min(0.6 + bestOverlap * 0.05, 0.85), matched: true };
         }
     }
-    // Default fallback
-    return { agents: ['coder', 'researcher', 'tester'], confidence: 0.7 };
+    return noMatch();
 }
 function assessCommandRisk(command) {
     const warnings = [];
@@ -1205,6 +1233,7 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
     let agents;
     let confidence;
     let matchedPattern = '';
+    let noMatchDetail = null;
     // 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
@@ -1212,7 +1241,9 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
     // (#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) => {
+    // A task with no letters or digits has nothing for the embedder to mean;
+    // any similarity it scores is noise, so it never becomes a semantic match.
+    const eligibleSemantic = !hasRoutableText(task) ? undefined : semanticResult.find((match) => {
         if (match.score <= 0.4)
             return false;
         const learned = match.intent.startsWith('learned-') || match.metadata.source === 'learned';
@@ -1232,9 +1263,16 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
         const suggestion = suggestAgentsForTask(task);
         agents = suggestion.agents;
         confidence = suggestion.confidence;
-        matchedPattern = 'keyword-fallback';
         routingMethod = 'keyword';
-        backendInfo = 'keyword matching';
+        if (suggestion.matched) {
+            matchedPattern = 'keyword-fallback';
+            backendInfo = 'keyword matching';
+        }
+        else {
+            matchedPattern = 'no-match-default';
+            backendInfo = 'keyword matching (no match)';
+            noMatchDetail = suggestion.note ?? 'No pattern matched.';
+        }
     }
     // Determine complexity
     const taskLower = task.toLowerCase();
@@ -1252,6 +1290,9 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
             throughput: routingLatencyMs > 0 ? `${Math.round(1000 / routingLatencyMs)} routes/s` : 'N/A',
         },
         matchedPattern,
+        // #3567: callers branch on `matched`; a no-match result is a default, not a decision.
+        matched: noMatchDetail === null,
+        ...(noMatchDetail !== null ? { reason: 'no-match-default', note: noMatchDetail } : {}),
         semanticMatches: semanticResult.slice(0, 3).map(r => ({
             pattern: r.intent,
             score: Math.round(r.score * 100) / 100,
@@ -1261,15 +1302,18 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
             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`,
+                : noMatchDetail !== null
+                    ? `Nothing matched; default suggestion only. ${noMatchDetail}`
+                    : `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`,
+            confidence: Math.max(0, Math.round((confidence - (0.1 * (i + 1))) * 100) / 100),
+            reason: noMatchDetail !== null ? 'Default suggestion (nothing matched)' : `Alternative agent for ${agent} capabilities`,
         })),
         estimatedMetrics: {
-            successProbability: Math.round(confidence * 100) / 100,
+            // No pattern means no basis for a success estimate.
+            successProbability: noMatchDetail !== null ? null : Math.round(confidence * 100) / 100,
             estimatedDuration: complexity === 'high' ? '2-4 hours' : complexity === 'medium' ? '30-60 min' : '10-30 min',
             complexity,
         },
@@ -1506,12 +1550,15 @@ export const hooksPreTask = {
         return {
             taskId,
             description,
+            agentsMatched: suggestion.matched,
             suggestedAgents: suggestion.agents.map((agent, i) => ({
                 type: agent,
                 confidence: suggestion.confidence - (0.05 * i),
-                reason: i === 0
-                    ? `Primary agent for ${agent} tasks based on learned patterns`
-                    : `Alternative agent with ${agent} capabilities`,
+                reason: !suggestion.matched
+                    ? 'Default suggestion (nothing matched)'
+                    : i === 0
+                        ? `Primary agent for ${agent} tasks based on learned patterns`
+                        : `Alternative agent with ${agent} capabilities`,
             })),
             complexity,
             estimatedDuration: complexity === 'high' ? '2-4 hours' : complexity === 'medium' ? '30-60 min' : '10-30 min',
@@ -1856,8 +1903,34 @@ export const hooksExplain = {
         catch {
             // File unreadable; leave as null
         }
+        // #3567: when nothing matched, say so instead of explaining a match that did not happen.
+        if (!suggestion.matched) {
+            return {
+                task,
+                matched: false,
+                reason: 'no-match-default',
+                explanation: `No keyword or learned pattern matched this task. ${suggestion.note ?? ''} ` +
+                    `"${suggestion.agents[0]}" is a default suggestion, not a routing decision.`.trim(),
+                factors: [
+                    { factor: 'Keyword Match', weight: 0.4, value: null, impact: 'No keyword matched' },
+                    { factor: 'Historical Success', weight: 0.3, value: historicalSuccess, impact: historicalNote },
+                    { factor: 'Agent Availability', weight: 0.2, value: null, impact: 'Agent availability tracking not implemented' },
+                    { factor: 'Task Complexity', weight: 0.1, value: task.length > 100 ? 0.8 : 0.3, impact: 'Complexity assessment' },
+                ],
+                patterns: matchedPatterns,
+                decision: {
+                    agent: suggestion.agents[0],
+                    confidence: suggestion.confidence,
+                    reasoning: [
+                        'No pattern matched; the agent is a default suggestion',
+                        `Confidence ${(suggestion.confidence * 100).toFixed(0)}% is below every real match`,
+                    ],
+                },
+            };
+        }
         return {
             task,
+            matched: true,
             explanation: `The routing decision was made based on keyword analysis of the task description. ` +
                 `The task contains keywords that match the "${suggestion.agents[0]}" specialization with ${(suggestion.confidence * 100).toFixed(0)}% confidence.`,
             factors: [

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

@@ -10,5 +10,12 @@
  * @module v3/cli/mcp-tools/memory-tools
  */
 import type { MCPTool } from './types.js';
+export declare const DANGEROUS_KEY_PATTERN: RegExp;
+/**
+ * #3570: the one key rule for every memory write path (MCP store, CLI store,
+ * import). Plain `/` stays legal (`probe/x`); traversal and shell metacharacters
+ * do not. Returns the error message, or null when the key is acceptable.
+ */
+export declare function memoryKeyError(key: string): string | null;
 export declare const memoryTools: MCPTool[];
 //# sourceMappingURL=memory-tools.d.ts.map

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

@@ -42,7 +42,15 @@ const MAX_QUERY_LENGTH = 4096;
 // validateMemoryInput. Imported by sanitizeMemoryKey so write-side sanitization
 // and read-side rejection can never drift apart (the symmetry bug behind #1884).
 const DANGEROUS_KEY_CHARS = /[;&|`$(){}[\]<>!#\\\0]|\.\.[/\\]/g;
-const DANGEROUS_KEY_PATTERN = /[;&|`$(){}[\]<>!#\\\0]|\.\.[/\\]/;
+export const DANGEROUS_KEY_PATTERN = /[;&|`$(){}[\]<>!#\\\0]|\.\.[/\\]/;
+/**
+ * #3570: the one key rule for every memory write path (MCP store, CLI store,
+ * import). Plain `/` stays legal (`probe/x`); traversal and shell metacharacters
+ * do not. Returns the error message, or null when the key is acceptable.
+ */
+export function memoryKeyError(key) {
+    return DANGEROUS_KEY_PATTERN.test(key) ? 'Key contains disallowed characters' : null;
+}
 function validateMemoryInput(key, value, query, namespace) {
     if (key && key.length > MAX_KEY_LENGTH) {
         throw new Error(`Key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);
@@ -54,9 +62,9 @@ function validateMemoryInput(key, value, query, namespace) {
         throw new Error(`Query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`);
     }
     // Reject path traversal and shell metacharacters in keys/namespaces (#1425)
-    if (key && DANGEROUS_KEY_PATTERN.test(key)) {
-        throw new Error('Key contains disallowed characters');
-    }
+    const keyError = key ? memoryKeyError(key) : null;
+    if (keyError)
+        throw new Error(keyError);
     if (namespace && DANGEROUS_KEY_PATTERN.test(namespace)) {
         throw new Error('Namespace contains disallowed characters');
     }
@@ -413,6 +421,11 @@ export const memoryTools = [
                 };
             }
             validateMemoryInput(key, value, undefined, namespace);
+            // #3570: a namespace written here must be exportable and purgeable, so it
+            // passes the same validator export and purge use.
+            const vNs = validateIdentifier(namespace, 'namespace');
+            if (!vNs.valid)
+                throw new Error(vNs.error);
             const startTime = performance.now();
             try {
                 const result = await storeEntry({
@@ -1542,6 +1555,9 @@ export const memoryTools = [
             await ensureInitialized(dbPath);
             const { storeEntry } = await getMemoryFunctions();
             const t0 = Date.now();
+            // Values are re-embedded on import; count the vectors actually written
+            // rather than reporting a constant 0 next to entries that show a vector.
+            let vectors = 0;
             const inputPath = String(input.inputPath ?? '');
             if (!inputPath || !existsSync(inputPath))
                 return { error: `File not found: ${inputPath || '(empty)'}` };
@@ -1559,6 +1575,24 @@ export const memoryTools = [
                 if (!v.valid)
                     throw new Error(v.error);
             }
+            // #3570: validate every entry's namespace up front so a bad file writes nothing.
+            if (!nsOverride) {
+                for (const e of entries) {
+                    if (e && typeof e.key === 'string' && e.namespace !== undefined) {
+                        const v = validateIdentifier(String(e.namespace), 'namespace');
+                        if (!v.valid)
+                            throw new Error(v.error);
+                    }
+                }
+            }
+            // #3570 follow-up: keys get the same up-front, all-or-nothing check.
+            for (const e of entries) {
+                if (e && typeof e.key === 'string') {
+                    const keyError = memoryKeyError(e.key);
+                    if (keyError)
+                        throw new Error(`${keyError}: ${JSON.stringify(e.key)}`);
+                }
+            }
             let imported = 0;
             let skipped = 0;
             for (const e of entries) {
@@ -1569,8 +1603,11 @@ export const memoryTools = [
                 const value = typeof e.value === 'string' ? e.value : JSON.stringify(e.value ?? null);
                 try {
                     const result = await storeEntry({ key: e.key, value, namespace: nsOverride ?? e.namespace ?? 'default', upsert: input.merge !== false, dbPath });
-                    if (result.success)
+                    if (result.success) {
                         imported++;
+                        if (result.embedding)
+                            vectors++;
+                    }
                     else
                         skipped++;
                 }
@@ -1580,7 +1617,7 @@ export const memoryTools = [
             }
             return {
                 inputPath,
-                imported: { entries: imported, vectors: 0, patterns: 0 },
+                imported: { entries: imported, vectors, patterns: 0 },
                 skipped,
                 duration: Date.now() - t0,
             };

package/v3/@claude-flow/cli/dist/src/mcp-tools/session-tools.d.ts

@@ -4,5 +4,20 @@
  * Tool definitions for session management with file persistence.
  */
 import { type MCPTool } from './types.js';
+/**
+ * #3573: what session_save learned about memory, so callers can say
+ * "not included" or "no store" instead of printing an invented 0.
+ */
+export interface MemoryCaptureReport {
+    requested: boolean;
+    status: 'not-requested' | 'captured' | 'no-store' | 'error';
+    entries: number;
+    sources: {
+        memoryDb: number;
+        agentdb: number;
+        legacyJson: number;
+    };
+    error?: string;
+}
 export declare const sessionTools: MCPTool[];
 //# sourceMappingURL=session-tools.d.ts.map