@claude-flow/cli 3.56.8 → 3.56.10

package/dist/src/mcp-tools/agent-execute-core.js

@@ -10,6 +10,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getProjectCwd } from './types.js';
+import { appendAgentExecution, summarizeAgentExecutions } from './agent-health-metrics.js';
 import { configManager } from '../services/config-file-manager.js';
 const STORAGE_DIR = '.claude-flow';
 const AGENT_DIR = 'agents';
@@ -669,6 +670,20 @@ export async function executeAgentTask(input) {
             }
             if (out)
                 current.lastResult = out;
+            const previousMeasuredHealth = summarizeAgentExecutions(current.executionHistory).health;
+            const mayUpdateStoredHealth = previousMeasuredHealth === null
+                ? current.health === agent.health
+                : current.health === previousMeasuredHealth;
+            current.executionHistory = appendAgentExecution(current.executionHistory, {
+                at: new Date().toISOString(),
+                success: result.success,
+                durationMs: result.durationMs ?? Date.now() - startedAt,
+            });
+            // An explicit agent_update during the provider call still wins. The
+            // measured value remains available from executionHistory in agent_health.
+            if (mayUpdateStoredHealth) {
+                current.health = summarizeAgentExecutions(current.executionHistory).health ?? current.health;
+            }
             saveAgentStore(latest);
         };
         if (result.success) {

package/dist/src/mcp-tools/agent-health-metrics.d.ts

@@ -0,0 +1,22 @@
+/** Bounded execution evidence for agent_health. Registry records are not processes. */
+export interface AgentExecutionSample {
+    at: string;
+    success: boolean;
+    durationMs: number;
+}
+export declare const AGENT_HEALTH_WINDOW = 20;
+export declare function appendAgentExecution(value: unknown, sample: AgentExecutionSample): AgentExecutionSample[];
+export declare function summarizeAgentExecutions(value: unknown): {
+    health: number | null;
+    errorRate: number | null;
+    sampleCount: number;
+    successes: number;
+    failures: number;
+    latency: {
+        avg: number | null;
+        p50: number | null;
+        p95: number | null;
+        p99: number | null;
+    };
+};
+//# sourceMappingURL=agent-health-metrics.d.ts.map

package/dist/src/mcp-tools/agent-health-metrics.js

@@ -0,0 +1,33 @@
+export const AGENT_HEALTH_WINDOW = 20;
+function validSamples(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((sample) => sample !== null && typeof sample === 'object' &&
+        typeof sample.at === 'string' && typeof sample.success === 'boolean' &&
+        typeof sample.durationMs === 'number' && Number.isFinite(sample.durationMs) && sample.durationMs >= 0).slice(-AGENT_HEALTH_WINDOW);
+}
+export function appendAgentExecution(value, sample) {
+    return [...validSamples(value), sample].slice(-AGENT_HEALTH_WINDOW);
+}
+export function summarizeAgentExecutions(value) {
+    const samples = validSamples(value);
+    const sampleCount = samples.length;
+    const successes = samples.filter(sample => sample.success).length;
+    const failures = sampleCount - successes;
+    const durations = samples.map(sample => sample.durationMs).sort((a, b) => a - b);
+    const percentile = (p) => sampleCount ? durations[Math.ceil(p * sampleCount) - 1] : null;
+    return {
+        health: sampleCount ? successes / sampleCount : null,
+        errorRate: sampleCount ? failures / sampleCount : null,
+        sampleCount,
+        successes,
+        failures,
+        latency: {
+            avg: sampleCount ? durations.reduce((sum, duration) => sum + duration, 0) / sampleCount : null,
+            p50: percentile(0.5),
+            p95: percentile(0.95),
+            p99: percentile(0.99),
+        },
+    };
+}
+//# sourceMappingURL=agent-health-metrics.js.map

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

@@ -10,6 +10,7 @@ import { readRecordStore } from './record-store.js';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText, validateAgentSpawn } from './validate-input.js';
 import { executeAgentTask } from './agent-execute-core.js';
+import { AGENT_HEALTH_WINDOW, summarizeAgentExecutions } from './agent-health-metrics.js';
 import { pheromoneAgentEligibility } from './swarm-tools.js';
 // Storage paths
 const STORAGE_DIR = '.claude-flow';
@@ -691,7 +692,7 @@ export const agentTools = [
     },
     {
         name: 'agent_health',
-        description: 'Compute an agent\'s rolling health score (0-1) from recent task success ratio + response-latency p50/p95 + error rate. Use when native Task tool is wrong because you\'re running a long-lived agent (autonomous loop / hive-mind worker / federation peer) and need to detect degradation before the breaker trips it. For one-shot Task invocations there is no history to score. Pair with hooks_post-task so the scores stay current.',
+        description: 'Report measured agent_execute provider-call outcomes over the last 20 calls: API success-ratio health (0-1), error rate, and response-latency p50/p95. This does not measure task correctness. Agents with no observed calls have unknown health; registration is not proof of a running process. Native Task and hooks_post-task outcomes are not recorded here. Use when you need measured reliability for agents driven through agent_execute; native Task results are invisible to this tool, so inspect those directly.',
         category: 'agent',
         inputSchema: {
             type: 'object',
@@ -708,58 +709,80 @@ export const agentTools = [
             }
             const store = loadAgentStore();
             const agents = Object.values(store.agents).filter(a => a.status !== 'terminated');
-            const threshold = input.threshold || 0.5;
+            const threshold = input.threshold === undefined ? 0.5 : input.threshold;
+            if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+                return { error: 'threshold must be a finite number between 0 and 1' };
+            }
+            const healthStatus = (health) => health === null ? 'unknown' : health >= threshold ? 'healthy' : health >= 0.3 ? 'degraded' : 'unhealthy';
             if (input.agentId) {
                 const agent = store.agents[input.agentId];
                 if (agent) {
+                    const metrics = summarizeAgentExecutions(agent.executionHistory);
                     return {
                         agentId: agent.agentId,
-                        health: agent.health,
+                        ...metrics,
+                        healthStatus: healthStatus(metrics.health),
                         status: agent.status,
-                        healthy: agent.health >= threshold,
+                        healthy: metrics.health === null ? null : metrics.health >= threshold,
                         taskCount: agent.taskCount,
-                        uptime: Date.now() - new Date(agent.createdAt).getTime(),
+                        uptime: null,
+                        registryAgeMs: Date.now() - new Date(agent.createdAt).getTime(),
+                        windowSize: AGENT_HEALTH_WINDOW,
+                        source: 'agent_execute',
                     };
                 }
                 return { agentId: input.agentId, error: 'Agent not found' };
             }
-            const healthyAgents = agents.filter(a => a.health >= threshold);
-            const degradedAgents = agents.filter(a => a.health >= 0.3 && a.health < threshold);
-            const unhealthyAgents = agents.filter(a => a.health < 0.3);
-            const avgHealth = agents.length > 0 ? agents.reduce((sum, a) => sum + a.health, 0) / agents.length : 1;
+            const observed = agents.map(agent => ({ agent, metrics: summarizeAgentExecutions(agent.executionHistory) }));
+            const healthyAgents = observed.filter(({ metrics }) => healthStatus(metrics.health) === 'healthy');
+            const degradedAgents = observed.filter(({ metrics }) => healthStatus(metrics.health) === 'degraded');
+            const unhealthyAgents = observed.filter(({ metrics }) => healthStatus(metrics.health) === 'unhealthy');
+            const measuredAgents = observed.filter(({ metrics }) => metrics.health !== null);
+            const unknownCount = agents.length - measuredAgents.length;
+            const avgHealth = measuredAgents.length > 0
+                ? measuredAgents.reduce((sum, { metrics }) => sum + metrics.health, 0) / measuredAgents.length
+                : null;
             return {
                 // CLI expected fields
-                agents: agents.map(a => {
-                    const uptime = Date.now() - new Date(a.createdAt).getTime();
+                agents: observed.map(({ agent, metrics }) => {
                     return {
-                        id: a.agentId,
-                        type: a.agentType,
-                        health: a.health >= threshold ? 'healthy' : (a.health >= 0.3 ? 'degraded' : 'unhealthy'),
-                        uptime,
-                        tasks: { active: a.taskCount > 0 ? 1 : 0, queued: 0, completed: a.taskCount, failed: 0 },
-                        _note: 'Per-agent OS metrics not available — use system_metrics for real CPU/memory',
+                        id: agent.agentId,
+                        type: agent.agentType,
+                        health: healthStatus(metrics.health),
+                        score: metrics.health,
+                        sampleCount: metrics.sampleCount,
+                        errorRate: metrics.errorRate,
+                        latency: metrics.latency,
+                        errors: { count: metrics.failures },
+                        uptime: null,
+                        registryAgeMs: Date.now() - new Date(agent.createdAt).getTime(),
+                        tasks: { active: agent.status === 'busy' ? 1 : 0, queued: null, completed: metrics.successes, failed: metrics.failures },
+                        _note: `Provider-call outcomes and latency cover only the last ${AGENT_HEALTH_WINDOW} agent_execute calls; task correctness, process liveness and CPU/memory are not observed`,
                     };
                 }),
                 overall: {
                     healthy: healthyAgents.length,
                     degraded: degradedAgents.length,
                     unhealthy: unhealthyAgents.length,
+                    unknown: unknownCount,
                     cpu: null,
                     memory: null,
                     _note: 'Per-agent CPU/memory not available — use system_metrics for real OS-level stats',
-                    score: Math.round(avgHealth * 100),
+                    score: avgHealth === null ? null : Math.round(avgHealth * 100),
                     issues: unhealthyAgents.length,
                 },
                 // Additional fields
                 total: agents.length,
+                observedCount: measuredAgents.length,
+                unknownCount,
                 healthyCount: healthyAgents.length,
                 unhealthyCount: unhealthyAgents.length,
                 threshold,
                 avgHealth,
-                unhealthyAgents: unhealthyAgents.map(a => ({
-                    agentId: a.agentId,
-                    health: a.health,
-                    status: a.status,
+                unhealthyAgents: unhealthyAgents.map(({ agent, metrics }) => ({
+                    agentId: agent.agentId,
+                    health: metrics.health,
+                    status: agent.status,
                 })),
             };
         },

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

@@ -50,7 +50,7 @@
  *
  * @module @claude-flow/cli/mcp-tools/agentbbs-federation
  */
-import { type Server } from 'node:http';
+import type { Server } from 'node:http';
 /** Max envelopes accepted from one peer in one sync. */
 export declare const MAX_ENVELOPES_PER_SYNC = 5000;
 /** Max serialized bytes for a single envelope. */

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

@@ -53,7 +53,12 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, chmodSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
-import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+// Lazy, CommonJS-style load of node:http: an ESM `import … from 'node:http'`
+// materialises every export of the builtin, which trips http's lazy undici
+// getters (~2.5 MB heap / ~6 MB RSS) at MCP startup even when no server is
+// ever started. require() of the builtin does not touch those getters.
+const loadHttp = () => createRequire(import.meta.url)('node:http');
 /** Max envelopes accepted from one peer in one sync. */
 export const MAX_ENVELOPES_PER_SYNC = 5_000;
 /** Max serialized bytes for a single envelope. */
@@ -389,7 +394,7 @@ export async function syncRoomFromPeer(basePath, peer, roomId, fetchImpl = fetch
  */
 export function serveFederation(basePath, opts = {}) {
     const host = opts.bindHost ?? '127.0.0.1';
-    const server = createServer((req, res) => {
+    const server = loadHttp().createServer((req, res) => {
         const send = (code, obj) => {
             const buf = Buffer.from(JSON.stringify(obj));
             res.writeHead(code, { 'content-type': 'application/json', 'content-length': buf.length });

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

@@ -80,6 +80,21 @@ async function bridgeUnavailableResult() {
         hint: 'Check Node version + try `ruflo memory init` to initialize manually.',
     };
 }
+// #4135 / #4161: graph reads (agentdb_graph-query, agentdb_graph-pathfinder) open the
+// graph_edges database; under encryption at rest that file is an RFE1 blob they cannot
+// open. A recorded edge is then unreadable even though the write reports success, so the
+// write says so instead of letting a caller assume it can read the edge back.
+async function unreadableEdgeWarning() {
+    try {
+        const { isBridgeDbEncryptedAtRest } = await getGraphEdgeWriter();
+        if (!isBridgeDbEncryptedAtRest())
+            return undefined;
+        return 'Edge recorded, but graph reads (agentdb_graph-query, agentdb_graph-pathfinder) cannot open the graph_edges database because it is encrypted at rest (RFE1), so this edge cannot be read back yet. Your data is intact (#2889, #4135).';
+    }
+    catch {
+        return undefined;
+    }
+}
 let memInitMod = null;
 async function getMemInit() {
     if (!memInitMod)
@@ -554,7 +569,9 @@ export const agentdbCausalEdge = {
                         // Also record in AgentDB bridge for compatibility
                         const bridge = await getBridge();
                         await bridge.bridgeRecordCausalEdge({ sourceId, targetId, relation, weight: typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined }).catch(() => { });
-                        return { ...graphResult, _graphNodeBackend: true, ...(legacyWarning && { warning: legacyWarning }) };
+                        const unreadable = await unreadableEdgeWarning();
+                        const warning = [legacyWarning, unreadable].filter(Boolean).join(' ');
+                        return { ...graphResult, _graphNodeBackend: true, ...(unreadable && { readable: false }), ...(warning && { warning }) };
                     }
                 }
             }
@@ -567,7 +584,9 @@ export const agentdbCausalEdge = {
                 weight: typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined,
             });
             const baseResult = result ?? { success: false, error: 'AgentDB bridge not available. Use memory_store/memory_search instead.' };
-            return legacyWarning ? { ...baseResult, warning: legacyWarning } : baseResult;
+            const unreadable = baseResult.success === false ? undefined : await unreadableEdgeWarning();
+            const warning = [legacyWarning, unreadable].filter(Boolean).join(' ');
+            return warning ? { ...baseResult, ...(unreadable && { readable: false }), warning } : baseResult;
         }
         catch (error) {
             return { success: false, error: sanitizeError(error) };
@@ -1157,6 +1176,10 @@ export const agentdbGraphQuery = {
                 catch (error) {
                     return { success: false, error: `Retained SQL graph query failed: ${sanitizeError(error)}`, mode, nodeId };
                 }
+                // #4135: name the real reason when the retained store is encrypted at rest.
+                const encryptedAtRest = await getGraphEdgeWriter().then((w) => w.isBridgeDbEncryptedAtRest()).catch(() => false);
+                if (encryptedAtRest)
+                    return { success: false, ...(await bridgeUnavailableResult()), mode, nodeId };
                 return { success: false, error: 'Retained SQL graph_edges backend is unavailable for k-hop query', mode, nodeId };
             }
             // ── semantic mode ────────────────────────────────────────────────────────

package/dist/src/mcp-tools/aidefence-known-misses.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Known-miss registry for aidefence_learn (#4147).
+ *
+ * The detector's learned patterns are written by `learnFromDetection`, but
+ * they are only created from threats the detector already found, and
+ * `detect()` never reads them back. A threat the detector MISSED (a false
+ * negative, the case feedback matters most for) therefore had nowhere to go.
+ *
+ * This registry stores a SHA-256 of the whitespace/case-normalised input so a
+ * reported miss is flagged next time the identical text is scanned. It is an
+ * exact-match list, not generalisation: the raw text is never stored.
+ */
+export interface KnownMiss {
+    hash: string;
+    threatType: string;
+    reportedAt: string;
+}
+export declare function hashInput(input: string): string;
+/** Returns true when the miss was newly recorded, false when it was already known. */
+export declare function recordKnownMiss(input: string, threatType: string, cwd?: string): boolean;
+export declare function findKnownMiss(input: string, cwd?: string): KnownMiss | undefined;
+//# sourceMappingURL=aidefence-known-misses.d.ts.map

package/dist/src/mcp-tools/aidefence-known-misses.js

@@ -0,0 +1,57 @@
+/**
+ * Known-miss registry for aidefence_learn (#4147).
+ *
+ * The detector's learned patterns are written by `learnFromDetection`, but
+ * they are only created from threats the detector already found, and
+ * `detect()` never reads them back. A threat the detector MISSED (a false
+ * negative, the case feedback matters most for) therefore had nowhere to go.
+ *
+ * This registry stores a SHA-256 of the whitespace/case-normalised input so a
+ * reported miss is flagged next time the identical text is scanned. It is an
+ * exact-match list, not generalisation: the raw text is never stored.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const MAX_ENTRIES = 500;
+function storePath(cwd) {
+    return join(cwd, '.claude-flow', 'aidefence-known-misses.json');
+}
+export function hashInput(input) {
+    const normalised = input.normalize('NFKC').toLowerCase().replace(/\s+/g, ' ').trim();
+    return createHash('sha256').update(normalised).digest('hex');
+}
+function load(cwd) {
+    try {
+        const p = storePath(cwd);
+        if (!existsSync(p))
+            return [];
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        return Array.isArray(parsed) ? parsed.filter((e) => e && typeof e.hash === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Returns true when the miss was newly recorded, false when it was already known. */
+export function recordKnownMiss(input, threatType, cwd = process.cwd()) {
+    const hash = hashInput(input);
+    const entries = load(cwd);
+    if (entries.some((e) => e.hash === hash))
+        return false;
+    entries.push({ hash, threatType, reportedAt: new Date().toISOString() });
+    const dir = join(cwd, '.claude-flow');
+    mkdirSync(dir, { recursive: true });
+    const tmp = `${storePath(cwd)}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(entries.slice(-MAX_ENTRIES), null, 2), { mode: 0o600 });
+    renameSync(tmp, storePath(cwd));
+    return true;
+}
+export function findKnownMiss(input, cwd = process.cwd()) {
+    const entries = load(cwd);
+    if (entries.length === 0)
+        return undefined;
+    const hash = hashInput(input);
+    return entries.find((e) => e.hash === hash);
+}
+//# sourceMappingURL=aidefence-known-misses.js.map

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

@@ -3,14 +3,14 @@
  * Provides diff analysis and classification via MCP protocol
  */
 import { validateGitRef, validatePath } from './validate-input.js';
-import { analyzeDiff, assessFileRisk, assessOverallRisk, classifyDiff, suggestReviewers, getGitDiffNumstat, } from '../ruvector/diff-classifier.js';
+import { analyzeDiff, assessFileRisk, assessOverallRisk, suggestReviewers, getGitDiffNumstat, } from '../ruvector/diff-classifier.js';
 /**
  * Diff Analysis Tool
  * Analyzes git diffs for change risk assessment and classification
  */
 export const analyzeDiffTool = {
     name: 'analyze_diff',
-    description: 'Analyze git diff for change risk assessment and classification Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
+    description: 'Heuristically analyze git diff paths, changed lines, and one-commit subjects for risk and classification. Use when preparing a review that needs a quick evidence-based summary; inspect the diff for final judgment.',
     category: 'analyze',
     tags: ['diff', 'risk', 'classification', 'git'],
     inputSchema: {
@@ -85,7 +85,7 @@ export const analyzeDiffTool = {
  */
 export const diffRiskTool = {
     name: 'analyze_diff-risk',
-    description: 'Quick risk assessment for git diff Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
+    description: 'Heuristically assess git diff risk from changed file paths, sizes, and status. Use when triaging which files merit closer human review; this is not a security guarantee.',
     category: 'analyze',
     tags: ['diff', 'risk', 'git'],
     inputSchema: {
@@ -130,7 +130,7 @@ export const diffRiskTool = {
  */
 export const diffClassifyTool = {
     name: 'analyze_diff-classify',
-    description: 'Classify git diff change type Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
+    description: 'Heuristically classify a git diff from changed lines, file paths, and a single-commit subject when available. Use when you need a coarse change category; inspect the diff to confirm.',
     category: 'analyze',
     tags: ['diff', 'classification', 'git'],
     inputSchema: {
@@ -151,12 +151,11 @@ export const diffClassifyTool = {
         }
         const ref = params.ref || 'HEAD';
         try {
-            const files = getGitDiffNumstat(ref);
-            const classification = classifyDiff(files);
+            const result = await analyzeDiff({ ref });
             return {
                 ref,
-                classification,
-                files: files.length,
+                classification: result.classification,
+                files: result.files.length,
             };
         }
         catch (error) {
@@ -174,7 +173,7 @@ export const diffClassifyTool = {
  */
 export const diffReviewersTool = {
     name: 'analyze_diff-reviewers',
-    description: 'Suggest reviewers for git diff changes Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
+    description: 'Suggest reviewer roles from git diff paths and risk; does not identify people or read CODEOWNERS. Use when triaging expertise for a change, then consult CODEOWNERS to assign people.',
     category: 'analyze',
     tags: ['diff', 'reviewers', 'git'],
     inputSchema: {
@@ -225,7 +224,7 @@ export const diffReviewersTool = {
  */
 export const fileRiskTool = {
     name: 'analyze_file-risk',
-    description: 'Assess risk for a specific file change Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
+    description: 'Heuristically assess risk for a file path and optional change metadata. Use when triaging a changed file for focused review; inspect the source for final judgment.',
     category: 'analyze',
     tags: ['file', 'risk'],
     inputSchema: {
@@ -280,7 +279,7 @@ export const fileRiskTool = {
  */
 export const diffStatsTool = {
     name: 'analyze_diff-stats',
-    description: 'Get quick statistics for git diff Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
+    description: 'Count changed files, additions, and deletions in a git diff. Use when you need a quick size summary before inspecting the full patch.',
     category: 'analyze',
     tags: ['diff', 'stats', 'git'],
     inputSchema: {

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

@@ -8,7 +8,7 @@
  * @module @claude-flow/cli/mcp-tools/autopilot
  */
 import { validateText } from './validate-input.js';
-import { loadState, saveState, appendLog, loadLog, discoverTasks, isTerminal, tryLoadLearning, validateNumber, validateConfiguredTaskSources, VALID_TASK_SOURCES, } from '../autopilot-state.js';
+import { loadState, saveState, appendLog, loadLog, discoverTasks, isTerminal, tryLoadLearning, getLearningLoadError, validateNumber, validateConfiguredTaskSources, VALID_TASK_SOURCES, } from '../autopilot-state.js';
 function ok(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
@@ -175,7 +175,7 @@ const autopilotLearn = {
             ]);
             return ok({ metrics, patterns });
         }
-        return ok({ available: false, reason: 'AgentDB/AutopilotLearning not initialized', patterns: [] });
+        return ok({ available: false, reason: getLearningLoadError() ?? 'AgentDB/AutopilotLearning not initialized', patterns: [] });
     },
 };
 const autopilotHistory = {

package/dist/src/mcp-tools/browser-intent-tools.js

@@ -85,9 +85,13 @@
  * @module @claude-flow/cli/mcp-tools/browser-intent
  */
 import { createRequire } from 'node:module';
-import { createServer } from 'node:http';
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+// Lazy, CommonJS-style load of node:http: an ESM `import … from 'node:http'`
+// materialises every export of the builtin, which trips http's lazy undici
+// getters (~2.5 MB heap / ~6 MB RSS) at MCP startup even when no server is
+// ever started. require() of the builtin does not touch those getters.
+const loadHttp = () => createRequire(import.meta.url)('node:http');
 import { validateText, validateIdentifier } from './validate-input.js';
 import { execBrowserCommand } from './browser-tools.js';
 import { storeEntry } from '../memory/memory-initializer.js';
@@ -175,7 +179,7 @@ export function resolvePageAgentLLMConfig(env = process.env) {
 export const PLACEHOLDER_API_KEY = 'ruflo-proxied-key';
 export function startLocalLLMProxy(real) {
     return new Promise((resolve, reject) => {
-        const server = createServer((req, res) => {
+        const server = loadHttp().createServer((req, res) => {
             const target = `${real.baseURL.replace(/\/+$/, '')}${req.url ?? ''}`;
             const chunks = [];
             req.on('data', (c) => chunks.push(c));

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

@@ -93,16 +93,28 @@ function toPoincare(euclidean, curvature) {
     const factor = Math.tanh(sqrtC * norm / 2) / (sqrtC * norm + 1e-15);
     return euclidean.map(x => x * factor);
 }
-// Poincaré distance
+// #4159: a point is usable only strictly inside the ball of radius 1/sqrt(c).
+function insidePoincareBall(p, curvature) {
+    const c = Math.abs(curvature);
+    return c * p.reduce((sum, x) => sum + x * x, 0) < 1;
+}
+// Poincaré distance, d_c(a,b) = acosh(1 + 2c|a-b|^2 / ((1-c|a|^2)(1-c|b|^2))) / sqrt(c).
+// Returns NaN for a point on or outside the ball (the formula is undefined there);
+// callers must check Number.isFinite before reporting it.
 function poincareDistance(a, b, curvature) {
     const c = Math.abs(curvature);
+    if (a.length !== b.length || !insidePoincareBall(a, curvature) || !insidePoincareBall(b, curvature)) {
+        return NaN;
+    }
     const diffSq = a.reduce((sum, _, i) => sum + (a[i] - b[i]) ** 2, 0);
     const normASq = a.reduce((sum, x) => sum + x * x, 0);
     const normBSq = b.reduce((sum, x) => sum + x * x, 0);
-    const denom = (1 - normASq) * (1 - normBSq);
-    const delta = 2 * diffSq / (denom + 1e-15);
+    const denom = (1 - c * normASq) * (1 - c * normBSq);
+    const delta = (2 * c * diffSq) / denom;
     return (1 / Math.sqrt(c)) * Math.acosh(1 + delta);
 }
+const HYPERBOLIC_RADIUS_NOTE = 'convert is an exponential map at the origin: it preserves the input norm ordering, so unit-norm text embeddings all land at the same radius. ' +
+    'It does not encode hierarchy; depth/tree structure has to come from the hierarchy itself (for example depth chosen as the radius, or embeddings trained on the tree edges).';
 // Cosine similarity
 function cosineSimilarity(a, b) {
     const dot = a.reduce((sum, _, i) => sum + a[i] * b[i], 0);
@@ -339,6 +351,9 @@ export const embeddingsTools = [
                     const poinc1 = toPoincare(emb1, config.hyperbolic.curvature);
                     const poinc2 = toPoincare(emb2, config.hyperbolic.curvature);
                     distance = poincareDistance(poinc1, poinc2, config.hyperbolic.curvature);
+                    if (!Number.isFinite(distance)) {
+                        return { success: false, error: 'Hyperbolic distance is undefined for these inputs (a converted point reached the ball boundary).' };
+                    }
                     similarity = 1 / (1 + distance);
                     break;
                 case 'euclidean':
@@ -739,6 +754,7 @@ export const embeddingsTools = [
                         poincare,
                         curvature,
                         poincareNorm: Math.sqrt(poincare.reduce((sum, x) => sum + x * x, 0)),
+                        note: HYPERBOLIC_RADIUS_NOTE,
                     };
                 case 'distance':
                     const emb1 = input.embedding1;
@@ -747,6 +763,13 @@ export const embeddingsTools = [
                         return { success: false, error: 'embedding1 and embedding2 required for distance action' };
                     }
                     const dist = poincareDistance(emb1, emb2, curvature);
+                    if (!Number.isFinite(dist)) {
+                        return {
+                            success: false,
+                            error: 'Poincaré distance needs two points of equal length strictly inside the ball (|x| < 1/sqrt(c)); got a point on or outside it, or mismatched lengths. Run convert on Euclidean vectors first.',
+                            curvature,
+                        };
+                    }
                     return {
                         success: true,
                         action: 'distance',
@@ -780,11 +803,10 @@ export const embeddingsTools = [
                             epsilon: config.hyperbolic.epsilon,
                             maxNorm: config.hyperbolic.maxNorm,
                         },
+                        note: HYPERBOLIC_RADIUS_NOTE,
                         benefits: [
-                            'Better hierarchical data representation',
-                            'Exponential capacity in low dimensions',
-                            'Preserves tree-like structures',
-                            'Natural for taxonomy embeddings',
+                            'Exponential capacity in low dimensions when the points are placed by hierarchy (for example by depth)',
+                            'Natural geometry for taxonomy embeddings that are trained or constructed for it',
                         ],
                     };
             }

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

@@ -3253,6 +3253,8 @@ export const hooksTrajectoryEnd = {
                         learned: result.learned,
                         patternKey: result.patternKey,
                         confidence: result.confidence,
+                        reinforcedNeighbour: result.reinforcedNeighbour,
+                        routingGate: result.routingGate,
                     };
                 }
                 catch {
@@ -3416,6 +3418,8 @@ export const hooksTrajectoryEnd = {
                 sonaUpdate: sonaResult.learned,
                 sonaPatternKey: sonaResult.patternKey || undefined,
                 sonaConfidence: sonaResult.confidence || undefined,
+                sonaReinforcedNeighbour: sonaResult.reinforcedNeighbour || undefined,
+                sonaRoutingGate: sonaResult.routingGate,
                 ewcConsolidation: ewcResult.consolidated,
                 ewcPenalty: ewcResult.penalty || undefined,
                 patternsExtracted,