claude-flow 3.19.0 → 3.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",
@@ -117,7 +117,7 @@
     "@grpc/grpc-js": ">=1.14.4",
     "form-data": ">=4.0.6",
     "http-proxy-middleware": ">=3.0.7",
-    "@ruvector/ruvllm": ">=2.5.7"
+    "@ruvector/ruvllm": ">=2.6.0"
   },
   "devDependencies": {
     "@openai/codex": "^0.98.0",

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

@@ -24,6 +24,8 @@ const trainCommand = {
         { name: 'contrastive', type: 'boolean', description: 'Use contrastive learning (InfoNCE)', default: 'true' },
         { name: 'curriculum', type: 'boolean', description: 'Enable curriculum learning', default: 'false' },
         { name: 'backend', type: 'string', description: 'Training backend: auto (native when available), native (@ruvector/ruvllm TrainingPipeline, disk checkpoints), wasm (RuVector MicroLoRA/InfoNCE)', default: 'auto' },
+        { name: 'val-split', type: 'number', description: 'Validation holdout fraction 0..1 (native backend). >0 reports Best Val Loss + early stopping; 0 disables', default: '0.1' },
+        { name: 'resume', type: 'string', description: 'Resume native training from a checkpoint path (weights on 2.5.7; epoch position on >=2.6.0). Native backend only', default: '' },
     ],
     examples: [
         { command: 'claude-flow neural train -p coordination -e 100', description: 'Train coordination patterns' },
@@ -41,6 +43,17 @@ const trainCommand = {
         // 'wasm' = RuVector MicroLoRA/InfoNCE (pre-3.19 behavior),
         // 'auto' = native when the module resolves, else wasm.
         const backendFlag = String(ctx.flags.backend || 'auto');
+        // Feature: validation split + resume (native TrainingPipeline leg).
+        const valSplitRaw = parseFloat(ctx.flags['val-split'] ?? '0.1');
+        const valSplit = Number.isFinite(valSplitRaw) ? Math.max(0, Math.min(1, valSplitRaw)) : 0.1;
+        const resumePath = ctx.flags.resume ? String(ctx.flags.resume) : undefined;
+        // --resume is a native-only capability; refuse the WASM combination up
+        // front so the user gets a clear error rather than a silently-ignored flag.
+        if (resumePath && backendFlag === 'wasm') {
+            output.writeln();
+            output.writeln(output.error('--resume is only supported by the native backend; drop --backend wasm.'));
+            return { success: false, exitCode: 1 };
+        }
         const useWasm = ctx.flags.wasm !== false;
         const useFlash = ctx.flags.flash !== false;
         const useMoE = ctx.flags.moe === true;
@@ -195,18 +208,34 @@ const trainCommand = {
             const nativeTraining = await import('../services/native-training.js');
             const useNative = backendFlag === 'native'
                 || (backendFlag === 'auto' && nativeTraining.nativeTrainingAvailable());
+            // --resume only works on the native pipeline; if native is unavailable
+            // (module absent), fail loudly rather than silently fresh-train.
+            if (resumePath && !useNative) {
+                spinner.fail('--resume requires the native @ruvector/ruvllm backend, which is not available');
+                return { success: false, exitCode: 1 };
+            }
             let nativeResult = null;
             if (useNative) {
                 spinner.setText(`Training ${patternType} on native @ruvector/ruvllm pipeline...`);
                 const path = await import('path');
-                nativeResult = await nativeTraining.runNativeTraining({
-                    embeddings,
-                    epochs,
-                    batchSize,
-                    learningRate,
-                    dim,
-                    checkpointPath: path.join(process.cwd(), '.claude-flow', 'neural', `lora-checkpoint-${Date.now()}.json`),
-                });
+                try {
+                    nativeResult = await nativeTraining.runNativeTraining({
+                        embeddings,
+                        epochs,
+                        batchSize,
+                        learningRate,
+                        dim,
+                        validationSplit: valSplit,
+                        resumeFrom: resumePath,
+                        checkpointPath: path.join(process.cwd(), '.claude-flow', 'neural', `lora-checkpoint-${Date.now()}.json`),
+                    });
+                }
+                catch (err) {
+                    // ResumeFailedError — an explicit --resume that could not load is a
+                    // loud, exit-1 failure, never a silent fall-through to fresh training.
+                    spinner.fail(`Resume failed: ${err.message}`);
+                    return { success: false, exitCode: 1 };
+                }
                 if (!nativeResult && backendFlag === 'native') {
                     spinner.fail('Native backend requested (--backend native) but @ruvector/ruvllm training failed');
                     return { success: false, exitCode: 1 };
@@ -325,7 +354,20 @@ const trainCommand = {
             ];
             // Native pipeline metrics (#2549 — the LoRA leg trained on ruvllm)
             if (nativeResult) {
-                tableData.push({ metric: 'Backend', value: 'native (@ruvector/ruvllm TrainingPipeline)' }, { metric: 'Native Steps', value: String(nativeResult.steps) }, { metric: 'Final Loss', value: nativeResult.finalLoss.toExponential(3) }, { metric: 'Early Stopped', value: nativeResult.earlyStopped ? 'yes' : 'no' });
+                tableData.push({ metric: 'Backend', value: 'native (@ruvector/ruvllm TrainingPipeline)' }, { metric: 'Native Steps', value: String(nativeResult.steps) }, { metric: 'Final Loss', value: nativeResult.finalLoss.toExponential(3) });
+                // Validation metrics only surface when a holdout actually ran
+                // (bestValLoss is non-null); Early Stopped is only meaningful then.
+                if (nativeResult.bestValLoss !== null && nativeResult.bestValLoss !== undefined) {
+                    tableData.push({ metric: 'Best Val Loss', value: nativeResult.bestValLoss.toExponential(3) }, { metric: 'Early Stopped', value: nativeResult.earlyStopped ? 'yes' : 'no' });
+                }
+                if (nativeResult.resumed) {
+                    tableData.push({
+                        metric: 'Resumed',
+                        value: nativeResult.resumeMode === 'resumeFrom'
+                            ? `${resumePath} (epoch position restored)`
+                            : `${resumePath} (weights only — epoch-position resume needs @ruvector/ruvllm >=2.6.0)`,
+                    });
+                }
                 if (nativeResult.checkpointPath) {
                     tableData.push({
                         metric: 'Checkpoint',
@@ -523,10 +565,14 @@ const statusCommand = {
                         details: stats._trainingBackend === 'ruvllm'
                             ? await (async () => {
                                 try {
-                                    const { nativeCheckpointsSupported } = await import('../ruvector/lora-adapter.js');
-                                    return nativeCheckpointsSupported()
+                                    const { nativeCheckpointsSupported, latestCheckpointInfo } = await import('../ruvector/lora-adapter.js');
+                                    // Most important info first (truncation-friendly): backend
+                                    // capability, then the newest checkpoint + age when one exists.
+                                    const base = nativeCheckpointsSupported()
                                         ? 'native @ruvector/ruvllm pipeline + disk checkpoints'
                                         : 'native @ruvector/ruvllm pipeline (checkpoints need >=2.5.7)';
+                                    const cp = latestCheckpointInfo();
+                                    return cp ? `${base} · latest: ${cp.filename} (${cp.ageLabel})` : base;
                                 }
                                 catch {
                                     return 'native @ruvector/ruvllm pipeline';

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

@@ -121,6 +121,7 @@ export const agenticowTools = [
                 branchPath: { type: 'string', description: 'Path to write the branch file' },
                 label: { type: 'string', description: 'Human-readable label for the branch (alnum + _.-:/@ only)' },
                 dimension: { type: 'integer', description: 'Vector dimension (required only when basePath does not exist yet)' },
+                nativeAnn: { type: 'boolean', description: 'Use the native Rust COW dual-graph ANN path (recall@10=1.0, query spans the COW boundary in one Rust call). Default false (exact JS chain-walk). Set true when the branch will be queried.', default: false },
             },
             required: ['basePath', 'branchPath', 'label'],
         },
@@ -132,9 +133,10 @@ export const agenticowTools = [
             const basePath = resolveMemoryPath(String(input.basePath));
             const branchPath = resolveMemoryPath(String(input.branchPath));
             const dim = input.dimension;
+            const nativeAnn = input.nativeAnn === true;
             const base = await openWithLineage(api, basePath, dim);
             try {
-                const branch = await base.fork(label, branchPath);
+                const branch = await base.fork(label, branchPath, { nativeAnn });
                 // Persist lineage manifests so the branch (and base) reopen with
                 // their COW chain intact. Without this, fork is in-memory only.
                 await branch.save?.(manifestFor(branchPath));
@@ -145,6 +147,7 @@ export const agenticowTools = [
                     basePath,
                     branchPath,
                     label,
+                    nativeAnn,
                 };
             }
             finally {
@@ -152,6 +155,181 @@ export const agenticowTools = [
             }
         },
     },
+    {
+        name: 'agenticow_ingest',
+        description: 'agenticow — write vectors (with optional text payloads) into an .rvf memory branch or base. Records: [{id?, vector, text?}] — id auto-assigns when omitted. This is the write half that makes a branch usable: agenticow_branch creates an empty COW child, but without ingest it has nothing to read back. Use after branching to populate an agent/session-local memory. Editing the base directly is wrong when the writes are speculative — ingest into a branch, then promote only if validated. Persists via .agenticow.json lineage manifest.',
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'ingest', 'write'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file (branch or base)' },
+                records: {
+                    type: 'array',
+                    description: 'Vectors to ingest: [{id?: number, vector: number[], text?: string}]',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'integer', description: 'Explicit id (auto-assigned when omitted)' },
+                            vector: { type: 'array', items: { type: 'number' }, description: 'Embedding vector (length must equal the memory dimension)' },
+                            text: { type: 'string', description: 'Optional payload surfaced on query hits' },
+                        },
+                        required: ['vector'],
+                    },
+                },
+                dimension: { type: 'integer', description: 'Vector dimension (required only when path does not exist yet)' },
+            },
+            required: ['path', 'records'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const records = input.records;
+            if (!Array.isArray(records) || records.length === 0) {
+                throw new Error('records must be a non-empty array of {id?, vector, text?}');
+            }
+            for (const r of records) {
+                if (!Array.isArray(r.vector) || r.vector.length === 0) {
+                    throw new Error('each record requires a non-empty numeric vector');
+                }
+            }
+            const dim = input.dimension ?? records[0].vector.length;
+            const mem = await openWithLineage(api, path, dim);
+            try {
+                const result = await mem.ingest(records.map((r) => ({
+                    ...(typeof r.id === 'number' ? { id: r.id } : {}),
+                    vector: r.vector,
+                    ...(r.text !== undefined ? { text: r.text } : {}),
+                })));
+                await mem.save?.(manifestFor(path));
+                return { success: true, path, ingested: result };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        name: 'agenticow_query',
+        description: 'agenticow — k-NN read across an .rvf memory branch\'s full COW lineage (parent ∪ edits, child wins), returning {id, distance, branch, text}. Read-only (no manifest write). The `branch` field on each hit tells you which lineage node the result came from — the read-through semantics that make branching useful. Use to retrieve from an agent/session branch without materializing a full copy. Re-opening the base and manually merging edits is wrong: query already spans the chain (and uses the single-call Rust path when the branch was forked with nativeAnn).',
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'query', 'read', 'search'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file' },
+                vector: { type: 'array', items: { type: 'number' }, description: 'Query embedding vector' },
+                k: { type: 'integer', description: 'Number of nearest neighbors to return', default: 10 },
+                efSearch: { type: 'integer', description: 'HNSW efSearch per lineage store (higher = better recall, slower)' },
+            },
+            required: ['path', 'vector'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const vector = input.vector;
+            if (!Array.isArray(vector) || vector.length === 0) {
+                throw new Error('vector must be a non-empty numeric array');
+            }
+            const k = typeof input.k === 'number' ? input.k : 10;
+            const opts = {};
+            if (typeof input.efSearch === 'number')
+                opts.efSearch = input.efSearch;
+            const mem = await openWithLineage(api, path);
+            try {
+                const hits = await mem.query(vector, k, opts);
+                return { success: true, path, k, hits };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        name: 'agenticow_diff',
+        description: 'agenticow — show what a branch changed relative to its lineage: {added, overridden, deleted} vector-id lists. Use before promote to preview the exact merge, or to audit what an agent/session branch actually wrote. Diffing by re-querying is wrong because deletions (tombstones) are invisible to a read — diff() surfaces them explicitly. Requires the branch was opened with edit tracking (default on).',
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'diff'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to branch .rvf file' },
+            },
+            required: ['path'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const mem = await openWithLineage(api, path);
+            try {
+                const diff = await mem.diff();
+                return { success: true, path, diff };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        name: 'agenticow_lineage',
+        description: 'agenticow — walk the COW chain of an .rvf memory file: an ordered list of nodes (role working|checkpoint|base, id, label, parent, createdAt, mutations, tombstones). Use to understand branch history, find checkpoint ids for a targeted rollback, or debug a promote. Guessing the chain from filenames is wrong — lineage is the authoritative structure the store maintains.',
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'lineage', 'history'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file' },
+            },
+            required: ['path'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const mem = await openWithLineage(api, path);
+            try {
+                const lineage = await mem.lineage();
+                return { success: true, path, lineage };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        name: 'agenticow_status',
+        description: 'agenticow — health/geometry of an .rvf memory file: {totalVectors, totalSegments, fileSize, currentEpoch, deadSpaceRatio, readOnly, chainDepth, dimension, metric}. Use to check vector count before/after ingest, spot compaction pressure (deadSpaceRatio), or confirm the dimension before ingesting into a shared base. Pure read.',
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'status'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file' },
+            },
+            required: ['path'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const mem = await openWithLineage(api, path);
+            try {
+                const status = await mem.status();
+                return { success: true, path, status };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
     {
         name: 'agenticow_checkpoint',
         description: 'agenticow — freeze a labelled restore point on an .rvf memory file. Subsequent edits stay in a fresh COW child; rollback returns here. Use when you are about to run an experimental Darwin tick or speculative agent edit that may need to be discarded. Relying on the working node alone is wrong because there is no "undo last N writes" semantics — without a checkpoint, a bad ingest contaminates the base. Persists via .agenticow.json lineage manifest so it survives close+reopen.',
@@ -191,6 +369,7 @@ export const agenticowTools = [
             type: 'object',
             properties: {
                 path: { type: 'string', description: 'Path to .rvf memory file' },
+                checkpointId: { type: 'string', description: 'Target checkpoint id from agenticow_lineage (omit to roll back to the most recent checkpoint)' },
             },
             required: ['path'],
         },
@@ -199,9 +378,10 @@ export const agenticowTools = [
             if (!api)
                 return degradedResult('agenticow-not-found');
             const path = resolveMemoryPath(String(input.path));
+            const checkpointId = input.checkpointId ? String(input.checkpointId) : undefined;
             const mem = await openWithLineage(api, path);
             try {
-                const r = await mem.rollback();
+                const r = checkpointId ? await mem.rollback(checkpointId) : await mem.rollback();
                 await mem.save?.(manifestFor(path));
                 return { success: true, path, rolledBack: true, result: r };
             }

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

@@ -18,7 +18,7 @@ export { DiffClassifier, createDiffClassifier, analyzeDiff, analyzeDiffSync, ass
 export { CoverageRouter, createCoverageRouter, coverageRoute, coverageSuggest, coverageGaps, clearCoverageCache, getCoverageCacheStats, type CoverageRouterConfig, type FileCoverage, type CoverageReport, type CoverageRouteResult, type CoverageSuggestResult, type CoverageGapsResult, type CoverageRouteOptions, type CoverageSuggestOptions, type CoverageGapsOptions, } from './coverage-router.js';
 export { coverageRouterTools, hooksCoverageRoute, hooksCoverageSuggest, hooksCoverageGaps } from './coverage-tools.js';
 export { buildDependencyGraph, analyzeGraph, analyzeMinCutBoundaries, analyzeModuleCommunities, detectCircularDependencies, exportToDot, loadRuVector, fallbackMinCut, fallbackLouvain, clearGraphCaches, getGraphCacheStats, type GraphNode, type GraphEdge, type DependencyGraph, type MinCutBoundary, type ModuleCommunity, type CircularDependency, type GraphAnalysisResult, } from './graph-analyzer.js';
-export { LoRAAdapter, getLoRAAdapter, resetLoRAAdapter, createLoRAAdapter, adaptEmbedding, trainLoRA, getLoRAStats, DEFAULT_RANK, DEFAULT_ALPHA, INPUT_DIM as LORA_INPUT_DIM, OUTPUT_DIM as LORA_OUTPUT_DIM, type LoRAConfig, type LoRAWeights, type AdaptationResult, type LoRAStats, } from './lora-adapter.js';
+export { LoRAAdapter, getLoRAAdapter, resetLoRAAdapter, createLoRAAdapter, adaptEmbedding, trainLoRA, getLoRAStats, loadLatestCheckpoint, latestCheckpointInfo, formatCheckpointAge, DEFAULT_RANK, DEFAULT_ALPHA, INPUT_DIM as LORA_INPUT_DIM, OUTPUT_DIM as LORA_OUTPUT_DIM, type LoRAConfig, type LoRAWeights, type AdaptationResult, type LoRAStats, type CheckpointInfo, } from './lora-adapter.js';
 export { ModelRouter, getModelRouter, resetModelRouter, createModelRouter, routeToModel, routeToModelFull, analyzeTaskComplexity, getModelRouterStats, recordModelOutcome, MODEL_CAPABILITIES, COMPLEXITY_INDICATORS, type ClaudeModel, type ModelRouterConfig, type ModelRoutingResult, type ComplexityAnalysis, } from './model-router.js';
 export { SemanticRouter, createSemanticRouter, type Intent, type RouteResult, type RouterConfig, } from './semantic-router.js';
 export { isRuvllmWasmAvailable, initRuvllmWasm, getRuvllmStatus, createHnswRouter, createSonaInstant, createMicroLora, formatChat, createKvCache, createGenerateConfig, createBufferPool, createInferenceArena, HNSW_MAX_SAFE_PATTERNS, type HnswRouterConfig, type HnswPattern, type HnswRouteResult, type SonaConfig, type MicroLoraConfig, type ChatMessage, type GenerateOptions, type RuvllmStatus, } from './ruvllm-wasm.js';

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

@@ -36,7 +36,7 @@ clearGraphCaches, getGraphCacheStats, } from './graph-analyzer.js';
 // consumers (hooks-tools.ts, neural-tools.ts) import from '@claude-flow/neural'
 // explicitly; re-exporting through this barrel pulls the package's
 // transitive @ruvector/sona dep into vitest's eager resolution.
-export { LoRAAdapter, getLoRAAdapter, resetLoRAAdapter, createLoRAAdapter, adaptEmbedding, trainLoRA, getLoRAStats, DEFAULT_RANK, DEFAULT_ALPHA, INPUT_DIM as LORA_INPUT_DIM, OUTPUT_DIM as LORA_OUTPUT_DIM, } from './lora-adapter.js';
+export { LoRAAdapter, getLoRAAdapter, resetLoRAAdapter, createLoRAAdapter, adaptEmbedding, trainLoRA, getLoRAStats, loadLatestCheckpoint, latestCheckpointInfo, formatCheckpointAge, DEFAULT_RANK, DEFAULT_ALPHA, INPUT_DIM as LORA_INPUT_DIM, OUTPUT_DIM as LORA_OUTPUT_DIM, } from './lora-adapter.js';
 export { ModelRouter, getModelRouter, resetModelRouter, createModelRouter, routeToModel, routeToModelFull, analyzeTaskComplexity, getModelRouterStats, recordModelOutcome, MODEL_CAPABILITIES, COMPLEXITY_INDICATORS, } from './model-router.js';
 export { SemanticRouter, createSemanticRouter, } from './semantic-router.js';
 // ── RuVector LLM WASM (inference utilities) ─────────────────

package/v3/@claude-flow/cli/dist/src/ruvector/lora-adapter.d.ts

@@ -213,6 +213,41 @@ export declare class LoRAAdapter {
         scaling: number;
     }): boolean;
 }
+/**
+ * Info about the newest on-disk training checkpoint.
+ */
+export interface CheckpointInfo {
+    /** Absolute path to the checkpoint file */
+    path: string;
+    /** Basename, e.g. lora-checkpoint-1712345678901.json */
+    filename: string;
+    /** Age in ms derived from the filename timestamp (falls back to mtime) */
+    ageMs: number;
+    /** Human-friendly age, e.g. "2h ago" */
+    ageLabel: string;
+}
+/** Compact relative-age label. Most-significant unit only. */
+export declare function formatCheckpointAge(ms: number): string;
+/**
+ * Find the newest `lora-checkpoint-<ts>.json` without loading it. Pure disk
+ * scan — safe to call from read-only status surfaces. Returns null when no
+ * checkpoint exists or the directory is unreadable.
+ */
+export declare function latestCheckpointInfo(): CheckpointInfo | null;
+/**
+ * Flywheel entry point: locate the newest trained checkpoint and load it into
+ * `adapter` via the adapter's existing loadCheckpoint path, so routing /
+ * adaptation benefits from prior `neural train` runs.
+ *
+ * Contract: lazy (call on first adaptation use, never at CLI startup),
+ * non-fatal on any failure, and kill-switchable via
+ * CLAUDE_FLOW_NO_CHECKPOINT_AUTOLOAD=1.
+ */
+export declare function loadLatestCheckpoint(adapter: LoRAAdapter): Promise<{
+    loaded: boolean;
+    path?: string;
+    ageMs?: number;
+}>;
 /**
  * Get or create singleton LoRA adapter instance
  */

package/v3/@claude-flow/cli/dist/src/ruvector/lora-adapter.js

@@ -17,7 +17,7 @@
  *
  * @module lora-adapter
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { createRequire } from 'module';
 // ============================================================================
@@ -527,6 +527,105 @@ export class LoRAAdapter {
         }
     }
 }
+/**
+ * Directories `neural train` writes checkpoints to. It only ever writes to
+ * `<cwd>/.claude-flow/neural` (see commands/neural.ts + services/native-training.ts),
+ * so that is the single source of truth — kept in a helper so the discovery
+ * and status surfaces stay consistent.
+ */
+function checkpointDirs() {
+    return [join(process.cwd(), '.claude-flow', 'neural')];
+}
+/** Compact relative-age label. Most-significant unit only. */
+export function formatCheckpointAge(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    const d = Math.floor(h / 24);
+    return `${d}d ago`;
+}
+/**
+ * Find the newest `lora-checkpoint-<ts>.json` without loading it. Pure disk
+ * scan — safe to call from read-only status surfaces. Returns null when no
+ * checkpoint exists or the directory is unreadable.
+ */
+export function latestCheckpointInfo() {
+    try {
+        let best = null;
+        for (const dir of checkpointDirs()) {
+            if (!existsSync(dir))
+                continue;
+            for (const f of readdirSync(dir)) {
+                const match = /^lora-checkpoint-(\d+)\.json$/.exec(f);
+                if (!match)
+                    continue;
+                const ts = Number(match[1]);
+                if (!Number.isFinite(ts))
+                    continue;
+                if (!best || ts > best.ts)
+                    best = { path: join(dir, f), filename: f, ts };
+            }
+        }
+        if (!best)
+            return null;
+        const ageMs = Math.max(0, Date.now() - best.ts);
+        return { path: best.path, filename: best.filename, ageMs, ageLabel: formatCheckpointAge(ageMs) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate a file looks like a ruvllm training checkpoint before loading it,
+ * so a stray/corrupt JSON in the neural dir can't poison routing weights.
+ * Accepts both the JS-fallback envelope ({A,B,scaling}) and native ruvllm
+ * checkpoint shapes (weights/adapter/epoch/step/loss/version/index markers).
+ */
+function isCheckpointEnvelope(path) {
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!data || typeof data !== 'object')
+            return false;
+        const obj = data;
+        if (Array.isArray(obj.A) && Array.isArray(obj.B))
+            return true;
+        return ['weights', 'adapter', 'epoch', 'step', 'loss', 'version', 'index'].some((k) => k in obj);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Flywheel entry point: locate the newest trained checkpoint and load it into
+ * `adapter` via the adapter's existing loadCheckpoint path, so routing /
+ * adaptation benefits from prior `neural train` runs.
+ *
+ * Contract: lazy (call on first adaptation use, never at CLI startup),
+ * non-fatal on any failure, and kill-switchable via
+ * CLAUDE_FLOW_NO_CHECKPOINT_AUTOLOAD=1.
+ */
+export async function loadLatestCheckpoint(adapter) {
+    if (process.env.CLAUDE_FLOW_NO_CHECKPOINT_AUTOLOAD === '1')
+        return { loaded: false };
+    try {
+        const info = latestCheckpointInfo();
+        if (!info)
+            return { loaded: false };
+        if (!isCheckpointEnvelope(info.path))
+            return { loaded: false, path: info.path, ageMs: info.ageMs };
+        const loaded = await adapter.loadCheckpoint(info.path);
+        return { loaded, path: info.path, ageMs: info.ageMs };
+    }
+    catch {
+        return { loaded: false };
+    }
+}
 // ============================================================================
 // Singleton & Factory Functions
 // ============================================================================
@@ -545,6 +644,14 @@ export async function getLoRAAdapter() {
     initPromise = (async () => {
         const adapter = new LoRAAdapter();
         await adapter.initialize();
+        // Flywheel: fold in the newest trained checkpoint so routing/adaptation
+        // benefits from prior `neural train` runs. This singleton is constructed
+        // lazily on first adaptation use (NOT at CLI startup), so the checkpoint
+        // scan + ruvllm load stay off the hot `--help` path. Non-fatal.
+        try {
+            await loadLatestCheckpoint(adapter);
+        }
+        catch { /* auto-load is best-effort — never block adaptation */ }
         loraInstance = adapter;
         return adapter;
     })();

package/v3/@claude-flow/cli/dist/src/services/native-training.d.ts

@@ -25,6 +25,14 @@ export interface NativeTrainingResult {
     earlyStopped: boolean;
     checkpointPath?: string;
     checkpointBytes?: number;
+    /** True when training resumed from a --resume checkpoint. */
+    resumed?: boolean;
+    /**
+     * How the resume happened: 'resumeFrom' (ruvllm >=2.6.0 — restores epoch
+     * position + optimizer state) or 'loadCheckpoint' (2.5.7 fallback —
+     * weights only, training restarts from epoch 0).
+     */
+    resumeMode?: 'resumeFrom' | 'loadCheckpoint';
 }
 export interface NativeTrainingOptions {
     embeddings: Float32Array[];
@@ -32,9 +40,29 @@ export interface NativeTrainingOptions {
     batchSize: number;
     learningRate: number;
     dim: number;
+    /**
+     * Validation holdout fraction (0..1). >0 makes the pipeline report
+     * bestValLoss + early-stopping; 0 (or omitted) disables validation.
+     * validationSplit exists in ruvllm 2.5.7 — no version gate needed.
+     */
+    validationSplit?: number;
+    /**
+     * Resume weights (and, on >=2.6.0, epoch position) from this checkpoint
+     * BEFORE training. A missing/invalid path throws ResumeFailedError — an
+     * explicit --resume must fail loudly, never silently fresh-train.
+     */
+    resumeFrom?: string;
     /** When set, the TRAINED pipeline checkpoints here (ruvllm >=2.5.7). */
     checkpointPath?: string;
 }
+/**
+ * Thrown when an explicit --resume checkpoint cannot be found or loaded.
+ * Distinct from the generic "native unavailable → null" degradation so the
+ * caller can surface a loud, exit-1 failure rather than fresh training.
+ */
+export declare class ResumeFailedError extends Error {
+    constructor(message: string);
+}
 export declare function nativeTrainingAvailable(): boolean;
 export declare function runNativeTraining(opts: NativeTrainingOptions): Promise<NativeTrainingResult | null>;
 //# sourceMappingURL=native-training.d.ts.map

package/v3/@claude-flow/cli/dist/src/services/native-training.js

@@ -19,6 +19,17 @@
 import { createRequire } from 'module';
 import { mkdirSync, existsSync } from 'fs';
 import { dirname } from 'path';
+/**
+ * Thrown when an explicit --resume checkpoint cannot be found or loaded.
+ * Distinct from the generic "native unavailable → null" degradation so the
+ * caller can surface a loud, exit-1 failure rather than fresh training.
+ */
+export class ResumeFailedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ResumeFailedError';
+    }
+}
 export function nativeTrainingAvailable() {
     try {
         createRequire(import.meta.url).resolve('@ruvector/ruvllm');
@@ -29,19 +40,53 @@ export function nativeTrainingAvailable() {
     }
 }
 export async function runNativeTraining(opts) {
-    const { embeddings, epochs, batchSize, learningRate, dim, checkpointPath } = opts;
+    const { embeddings, epochs, batchSize, learningRate, dim, validationSplit, resumeFrom, checkpointPath } = opts;
     if (embeddings.length < 2)
         return null;
     try {
         const req = createRequire(import.meta.url);
         const ruvllm = req('@ruvector/ruvllm');
-        const pipeline = new ruvllm.TrainingPipeline({
+        const pipelineConfig = {
             learningRate,
             batchSize,
             epochs,
             inputDim: dim,
             outputDim: dim,
-        });
+        };
+        // 0 (or omitted) disables validation; only pass a real holdout through.
+        if (typeof validationSplit === 'number' && validationSplit > 0) {
+            pipelineConfig.validationSplit = validationSplit;
+        }
+        const pipeline = new ruvllm.TrainingPipeline(pipelineConfig);
+        // Resume BEFORE training. Prefer resumeFrom() (2.6.0 — epoch position +
+        // optimizer state); fall back to loadCheckpoint() (2.5.7 — weights only).
+        // Any failure with an explicit --resume is loud (ResumeFailedError),
+        // never silent fresh training.
+        let resumed = false;
+        let resumeMode;
+        if (resumeFrom) {
+            if (!existsSync(resumeFrom)) {
+                throw new ResumeFailedError(`--resume checkpoint not found: ${resumeFrom}`);
+            }
+            try {
+                if (typeof pipeline.resumeFrom === 'function') {
+                    pipeline.resumeFrom(resumeFrom);
+                    resumeMode = 'resumeFrom';
+                }
+                else {
+                    const ok = pipeline.loadCheckpoint(resumeFrom);
+                    if (ok === false)
+                        throw new Error('loadCheckpoint returned false');
+                    resumeMode = 'loadCheckpoint';
+                }
+                resumed = true;
+            }
+            catch (e) {
+                if (e instanceof ResumeFailedError)
+                    throw e;
+                throw new ResumeFailedError(`--resume failed to load checkpoint ${resumeFrom}: ${e.message}`);
+            }
+        }
         // Pattern-alignment pairs, chunked into pipeline batches.
         const inputs = [];
         const targets = [];
@@ -55,13 +100,21 @@ export async function runNativeTraining(opts) {
             pipeline.addBatch(inputs.slice(i, i + batchSize), targets.slice(i, i + batchSize), qualities.slice(i, i + batchSize));
         }
         const r = pipeline.train();
+        // When validation is disabled the pipeline reports Infinity for
+        // bestValLoss — normalize any non-finite value to null so downstream
+        // "bestValLoss !== null ⇒ validation ran" holds for the results table.
+        const bestValLoss = typeof r.bestValLoss === 'number' && Number.isFinite(r.bestValLoss)
+            ? r.bestValLoss
+            : null;
         const result = {
             epochs: r.epochs,
             steps: r.steps,
             finalLoss: r.finalLoss,
-            bestValLoss: r.bestValLoss ?? null,
+            bestValLoss,
             durationMs: r.durationMs,
             earlyStopped: !!r.earlyStopped,
+            resumed,
+            resumeMode,
         };
         if (checkpointPath) {
             try {
@@ -77,7 +130,11 @@ export async function runNativeTraining(opts) {
         }
         return result;
     }
-    catch {
+    catch (err) {
+        // An explicit --resume failure must propagate as a loud error; every
+        // other failure degrades to null so callers fall back to the WASM path.
+        if (err instanceof ResumeFailedError)
+            throw err;
         return null;
     }
 }

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

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