claude-flow 3.19.0 → 3.21.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';
@@ -3937,11 +3983,319 @@ const routerCommand = {
         return { success: true };
     },
 };
+// ============================================================================
+// ADR-150 weight-eft slice — `neural distill export | plan | eval | train`
+//
+// Turns ruflo's captured run transcripts into AUDITED TRAINING DATA + a
+// COST-PARETO measurement + a GPU TRAINING PLAN via the optional
+// `@metaharness/weight-eft` dependency. HARD honesty rule: this ships training
+// DATA + a cost audit + a GPU plan — it does NOT train a model and does NOT
+// "reduce escalation". weight-eft's own `train` never spawns; `resolved` in the
+// captured archive is a PROXY (no SWE-bench gold oracle). Every path degrades
+// gracefully ({degraded:true}) when the optional dep is absent (ADR-150).
+// ============================================================================
+const distillExportCommand = {
+    name: 'export',
+    description: 'Export captured run transcripts → SFT (OpenAI chat) + DPO (TRL preference) JSONL + a guard report (contamination / reward-hack / long-context). $0, offline. Does NOT train.',
+    options: [
+        { name: 'archive', short: 'a', type: 'string', description: 'Run-transcript JSONL to read (default: $CLAUDE_FLOW_RUN_TRANSCRIPTS_PATH or .swarm/run-transcripts.jsonl)' },
+        { name: 'out-dir', short: 'o', type: 'string', description: 'Output dir for sft.jsonl / dpo.jsonl / export-report.json', default: '.claude-flow/neural/weft-export' },
+        { name: 'eval-holdout', type: 'string', description: 'Comma-separated instance_ids reserved for eval (contamination guard). Excluded + asserted-disjoint.' },
+        { name: 'max-tokens', type: 'number', description: 'Per-trajectory token budget (default weight-eft 28000)' },
+        { name: 'truncate', type: 'boolean', description: 'Truncate over-length trajectories instead of dropping', default: 'false' },
+        { name: 'keep-reward-hacked', type: 'boolean', description: 'Disable the reward-hacking filter (debug only; NOT recommended)', default: 'false' },
+        { name: 'format', short: 'f', type: 'string', description: 'Output format: table, json', default: 'table' },
+    ],
+    examples: [
+        { command: 'claude-flow neural distill export', description: 'Export from the default captured .swarm/run-transcripts.jsonl' },
+        { command: 'claude-flow neural distill export -a runs.jsonl -o ./out --eval-holdout astropy__astropy-1', description: 'Export a specific archive, holding out one instance' },
+    ],
+    action: async (ctx) => {
+        const fs = await import('node:fs');
+        const path = await import('node:path');
+        const { readRunTranscripts } = await import('../ruvector/run-transcript-recorder.js');
+        const { buildArchiveFromRecords, runExport } = await import('../services/weight-eft.js');
+        const fmt = ctx.flags.format || 'table';
+        const archivePath = ctx.flags.archive
+            ?? process.env.CLAUDE_FLOW_RUN_TRANSCRIPTS_PATH
+            ?? path.resolve(process.cwd(), '.swarm', 'run-transcripts.jsonl');
+        const { records, malformed } = readRunTranscripts(archivePath);
+        if (records.length === 0) {
+            const msg = `No run transcripts at ${archivePath}. Enable capture with CLAUDE_FLOW_RUN_TRANSCRIPTS=1, or pass --archive <file>.`;
+            if (fmt === 'json')
+                output.writeln(JSON.stringify({ ok: false, archivePath, records: 0, malformed, error: msg }, null, 2));
+            else
+                output.printError(msg);
+            return { success: false, exitCode: 1, data: { archivePath, records: 0 } };
+        }
+        const { trajectories, stats, proxyNote } = buildArchiveFromRecords(records);
+        const holdout = (ctx.flags['eval-holdout'] ?? ctx.flags.evalHoldout)?.split(',').map((s) => s.trim()).filter(Boolean) ?? [];
+        const maxTokens = (ctx.flags['max-tokens'] ?? ctx.flags.maxTokens) != null ? parseInt(String((ctx.flags['max-tokens'] ?? ctx.flags.maxTokens)), 10) : undefined;
+        const res = await runExport({
+            archive: trajectories,
+            evalHoldout: holdout,
+            maxTokens,
+            truncateOverLength: ctx.flags.truncate === true,
+            dropRewardHacked: (ctx.flags['keep-reward-hacked'] ?? ctx.flags.keepRewardHacked) === true ? false : undefined,
+        });
+        if (res.degraded) {
+            // ADR-150 graceful degradation: dep absent → not a runtime failure.
+            const payload = { degraded: true, reason: res.reason, archiveTrajectories: trajectories.length };
+            if (fmt === 'json')
+                output.writeln(JSON.stringify(payload, null, 2));
+            else {
+                output.writeln(output.warning(`weight-eft unavailable (${res.reason}).`));
+                output.writeln(output.dim('Install the optional dep: npm i @metaharness/weight-eft. Archive was built (' + trajectories.length + ' trajectories) but not exported.'));
+            }
+            return { success: true, exitCode: 0, data: payload };
+        }
+        const outDir = path.resolve(process.cwd(), (ctx.flags['out-dir'] ?? ctx.flags.outDir) || '.claude-flow/neural/weft-export');
+        fs.mkdirSync(outDir, { recursive: true });
+        const sftPath = path.join(outDir, 'sft.jsonl');
+        const dpoPath = path.join(outDir, 'dpo.jsonl');
+        const reportPath = path.join(outDir, 'export-report.json');
+        fs.writeFileSync(sftPath, res.sftJsonl);
+        fs.writeFileSync(dpoPath, res.dpoJsonl);
+        fs.writeFileSync(reportPath, JSON.stringify({ report: res.report, archiveStats: stats, proxyNote }, null, 2));
+        const payload = {
+            ok: true, archivePath, outDir, sftPath, dpoPath, reportPath,
+            sftRows: res.sftRows, dpoRows: res.dpoRows, malformed,
+            archiveStats: stats, report: res.report, proxyNote,
+        };
+        if (fmt === 'json') {
+            output.writeln(JSON.stringify(payload, null, 2));
+            return { success: true, data: payload };
+        }
+        output.writeln();
+        output.writeln(output.bold('weight-eft export — audited training data ($0, no model trained)'));
+        output.writeln(`  archive:      ${archivePath} (${records.length} records, ${malformed} malformed skipped)`);
+        output.writeln(`  trajectories: ${stats.total} (cheap ${stats.byTier.cheap} / frontier ${stats.byTier.frontier}), resolved ${stats.resolved}`);
+        output.writeln(`  SFT rows:     ${res.sftRows}  → ${sftPath}`);
+        output.writeln(`  DPO rows:     ${res.dpoRows}  → ${dpoPath}`);
+        output.writeln(`  guards:       holdout=${res.report.excludedByHoldout} reward-hacked=${res.report.droppedRewardHacked} over-length=${res.report.droppedOverLength} truncated=${res.report.truncatedOverLength}`);
+        output.writeln(`  report:       ${reportPath}`);
+        output.writeln();
+        output.writeln(output.warning('resolved provenance: ' + JSON.stringify(stats.byResolvedSource)));
+        output.writeln(output.dim(proxyNote));
+        return { success: true, data: payload };
+    },
+};
+const distillPlanCommand = {
+    name: 'plan',
+    description: 'Print the two-stage (SFT → on-policy DPO) GPU training plan + the exact `ruvllm microlora` commands a GPU host would run. $0 dry-run — NEVER spawns a tune.',
+    options: [
+        { name: 'sft', type: 'string', description: 'Path to sft.jsonl (default: .claude-flow/neural/weft-export/sft.jsonl)' },
+        { name: 'dpo', type: 'string', description: 'Path to dpo.jsonl (default: .claude-flow/neural/weft-export/dpo.jsonl)' },
+        { name: 'base', short: 'b', type: 'string', description: 'Base model id to tune (7-14B band). Default Qwen2.5-Coder-7B-Instruct' },
+        { name: 'params-b', type: 'number', description: 'Base model param count in billions (gate [1,14]). Default 7' },
+        { name: 'adapter-prefix', type: 'string', description: 'Adapter output prefix', default: 'ruflo-weft' },
+        { name: 'format', short: 'f', type: 'string', description: 'Output format: table, json', default: 'table' },
+    ],
+    examples: [
+        { command: 'claude-flow neural distill plan', description: 'Print the GPU plan for the last export ($0 dry-run)' },
+        { command: 'claude-flow neural distill plan --base Qwen/Qwen2.5-Coder-7B-Instruct --params-b 7', description: 'Plan for a specific base model' },
+    ],
+    action: async (ctx) => {
+        const path = await import('node:path');
+        const { runPlan, DEFAULT_BASE_MODEL } = await import('../services/weight-eft.js');
+        const fmt = ctx.flags.format || 'table';
+        const sftPath = ctx.flags.sft || path.resolve(process.cwd(), '.claude-flow/neural/weft-export/sft.jsonl');
+        const dpoPath = ctx.flags.dpo || path.resolve(process.cwd(), '.claude-flow/neural/weft-export/dpo.jsonl');
+        const base = ctx.flags.base
+            ? { id: String(ctx.flags.base), paramsB: (ctx.flags['params-b'] ?? ctx.flags.paramsB) != null ? parseInt(String((ctx.flags['params-b'] ?? ctx.flags.paramsB)), 10) : 7 }
+            : DEFAULT_BASE_MODEL;
+        const res = await runPlan({ base, sftPath, dpoPath, adapterPrefix: String((ctx.flags['adapter-prefix'] ?? ctx.flags.adapterPrefix) || 'ruflo-weft') });
+        if (res.degraded) {
+            const payload = { degraded: true, reason: res.reason };
+            if (fmt === 'json')
+                output.writeln(JSON.stringify(payload, null, 2));
+            else {
+                output.writeln(output.warning(`weight-eft unavailable (${res.reason}).`));
+                output.writeln(output.dim('Install: npm i @metaharness/weight-eft'));
+            }
+            return { success: true, exitCode: 0, data: payload };
+        }
+        const payload = { ok: true, base: res.base, sft: res.sft, dpo: res.dpo, dryRun: true };
+        if (fmt === 'json') {
+            output.writeln(JSON.stringify(payload, null, 2));
+            return { success: true, data: payload };
+        }
+        output.writeln();
+        output.writeln(output.bold(`weight-eft GPU training plan ($0 dry-run — no tune runs from ruflo)`));
+        output.writeln(`  base model: ${res.base.id} (${res.base.paramsB}B)`);
+        output.writeln(output.dim('  SFT stage:'));
+        output.writeln(`    ${res.sft.summary}`);
+        output.writeln(`    $ ${res.sft.command}`);
+        output.writeln(output.dim('  DPO stage (on-policy, init from SFT adapter):'));
+        output.writeln(`    ${res.dpo.summary}`);
+        output.writeln(`    $ ${res.dpo.command}`);
+        output.writeln();
+        output.writeln(output.dim('These commands run on a GPU host; ruflo does not execute them. See `neural distill train --remote` for a spend-gated remote path.'));
+        return { success: true, data: payload };
+    },
+};
+const distillEvalCommand = {
+    name: 'eval',
+    description: 'Fold two CascadeOutcome[] JSON files (base vs adapter) into the cost-Pareto delta — escalation-rate reduction + $/resolved. $0. Measures cost, does NOT claim a tune ran.',
+    options: [
+        { name: 'base-outcomes', type: 'string', description: 'JSON file: CascadeOutcome[] for the BASE cascade run', required: true },
+        { name: 'adapter-outcomes', type: 'string', description: 'JSON file: CascadeOutcome[] for the ADAPTER cascade run', required: true },
+        { name: 'format', short: 'f', type: 'string', description: 'Output format: table, json', default: 'table' },
+    ],
+    examples: [
+        { command: 'claude-flow neural distill eval --base-outcomes base.json --adapter-outcomes adapter.json', description: 'Cost-Pareto delta between base and adapter cascade runs' },
+    ],
+    action: async (ctx) => {
+        const fs = await import('node:fs');
+        const { runEval } = await import('../services/weight-eft.js');
+        const fmt = ctx.flags.format || 'table';
+        const basePath = (ctx.flags['base-outcomes'] ?? ctx.flags.baseOutcomes);
+        const adapterPath = (ctx.flags['adapter-outcomes'] ?? ctx.flags.adapterOutcomes);
+        if (!basePath || !adapterPath) {
+            output.printError('Both --base-outcomes and --adapter-outcomes are required.');
+            return { success: false, exitCode: 2 };
+        }
+        let baseOutcomes;
+        let adapterOutcomes;
+        try {
+            baseOutcomes = JSON.parse(fs.readFileSync(basePath, 'utf8'));
+            adapterOutcomes = JSON.parse(fs.readFileSync(adapterPath, 'utf8'));
+        }
+        catch (e) {
+            output.printError(`Failed to read outcome files: ${e.message}`);
+            return { success: false, exitCode: 1 };
+        }
+        if (!Array.isArray(baseOutcomes) || !Array.isArray(adapterOutcomes)) {
+            output.printError('Both files must contain a JSON array of CascadeOutcome objects.');
+            return { success: false, exitCode: 1 };
+        }
+        const res = await runEval({ baseOutcomes: baseOutcomes, adapterOutcomes: adapterOutcomes });
+        if (res.degraded) {
+            const payload = { degraded: true, reason: res.reason };
+            if (fmt === 'json')
+                output.writeln(JSON.stringify(payload, null, 2));
+            else {
+                output.writeln(output.warning(`weight-eft unavailable (${res.reason}).`));
+                output.writeln(output.dim('Install: npm i @metaharness/weight-eft'));
+            }
+            return { success: true, exitCode: 0, data: payload };
+        }
+        if (fmt === 'json') {
+            output.writeln(JSON.stringify({ ok: true, delta: res.delta }, null, 2));
+            return { success: true, data: res.delta };
+        }
+        output.writeln();
+        output.writeln(output.bold('weight-eft cost-Pareto delta (measurement only)'));
+        output.writeln(`  cheap-resolve lift:       ${res.delta.cheapResolveLift.toFixed(4)}`);
+        output.writeln(`  escalation-rate reduction: ${res.delta.escalationRateReduction.toFixed(4)}`);
+        output.writeln(`  $/resolved reduction:      ${res.delta.costPerResolvedReduction.toFixed(6)}`);
+        output.writeln(`  resolve-rate delta:        ${res.delta.resolveRateDelta.toFixed(4)} (expected ≈ 0 — ceiling unmoved)`);
+        output.writeln(`  verdict: ${res.delta.verdict}`);
+        return { success: true, data: res.delta };
+    },
+};
+const distillTrainCommand = {
+    name: 'train',
+    description: 'Remote-GPU LoRA tune over SSH — DRY-RUN by default (prints ssh/rsync/ruvllm commands + read-only preflight). Real compute ONLY with --execute --yes (spends GPU time on YOUR host). Not a $0/local tune.',
+    options: [
+        { name: 'remote', short: 'r', type: 'string', description: 'SSH host or tailscale name (default: $RUFLO_DISTILL_REMOTE). Never hard-coded.' },
+        { name: 'base', short: 'b', type: 'string', description: 'Base model id to tune. Default Qwen2.5-Coder-7B-Instruct' },
+        { name: 'sft', type: 'string', description: 'Local sft.jsonl (default: .claude-flow/neural/weft-export/sft.jsonl)' },
+        { name: 'dpo', type: 'string', description: 'Local dpo.jsonl (default: .claude-flow/neural/weft-export/dpo.jsonl)' },
+        { name: 'adapter-dir', type: 'string', description: 'Local dir to fetch the trained adapter into', default: '.claude-flow/neural' },
+        { name: 'ssh-user', type: 'string', description: 'SSH user (default: current user)' },
+        { name: 'ssh-port', type: 'number', description: 'SSH port', default: '22' },
+        { name: 'remote-workdir', type: 'string', description: 'Remote working dir (default: ~/.ruflo-weft/<runId>)' },
+        { name: 'execute', type: 'boolean', description: 'Opt in to REAL GPU compute on the remote host (still needs --yes)', default: 'false' },
+        { name: 'yes', type: 'boolean', description: 'Second confirmation gate; required with --execute to actually spend', default: 'false' },
+        { name: 'preflight', type: 'boolean', description: 'Opt in to read-only reachability/GPU probes against the host (bare dry-run is fully offline and contacts nothing)', default: 'false' },
+        { name: 'format', short: 'f', type: 'string', description: 'Output format: table, json', default: 'table' },
+    ],
+    examples: [
+        { command: 'claude-flow neural distill train --remote gpu-box', description: 'OFFLINE DRY-RUN: print the ssh/rsync/ruvllm commands only (no host contact)' },
+        { command: 'claude-flow neural distill train --remote gpu-box --preflight', description: 'DRY-RUN + read-only reachability/GPU probes against the host' },
+        { command: 'RUFLO_DISTILL_REMOTE=gpu-box claude-flow neural distill train --execute --yes', description: 'Run the real remote tune (spends GPU time on your host)' },
+    ],
+    action: async (ctx) => {
+        const path = await import('node:path');
+        const { runRemoteTrain } = await import('../services/weight-eft.js');
+        const fmt = ctx.flags.format || 'table';
+        const host = ctx.flags.remote || process.env.RUFLO_DISTILL_REMOTE;
+        if (!host) {
+            output.printError('No remote host. Pass --remote <host> or set RUFLO_DISTILL_REMOTE.');
+            return { success: false, exitCode: 2 };
+        }
+        const res = await runRemoteTrain({
+            host,
+            base: ctx.flags.base ? String(ctx.flags.base) : undefined,
+            sftPath: ctx.flags.sft || path.resolve(process.cwd(), '.claude-flow/neural/weft-export/sft.jsonl'),
+            dpoPath: ctx.flags.dpo || path.resolve(process.cwd(), '.claude-flow/neural/weft-export/dpo.jsonl'),
+            adapterDir: (ctx.flags['adapter-dir'] ?? ctx.flags.adapterDir) || '.claude-flow/neural',
+            sshUser: (ctx.flags['ssh-user'] ?? ctx.flags.sshUser) ? String((ctx.flags['ssh-user'] ?? ctx.flags.sshUser)) : undefined,
+            sshPort: (ctx.flags['ssh-port'] ?? ctx.flags.sshPort) != null ? parseInt(String((ctx.flags['ssh-port'] ?? ctx.flags.sshPort)), 10) : undefined,
+            remoteWorkdir: (ctx.flags['remote-workdir'] ?? ctx.flags.remoteWorkdir) ? String((ctx.flags['remote-workdir'] ?? ctx.flags.remoteWorkdir)) : undefined,
+            execute: ctx.flags.execute === true,
+            yes: ctx.flags.yes === true,
+            preflight: ctx.flags.preflight === true,
+        });
+        if ('degraded' in res && res.degraded) {
+            const payload = { degraded: true, reason: res.reason };
+            if (fmt === 'json')
+                output.writeln(JSON.stringify(payload, null, 2));
+            else
+                output.writeln(output.warning(`remote-train unavailable (${res.reason}).`));
+            return { success: true, exitCode: 0, data: payload };
+        }
+        if (fmt === 'json') {
+            output.writeln(JSON.stringify(res, null, 2));
+            return { success: res.mode !== 'preflight-failed', data: res };
+        }
+        output.writeln();
+        output.writeln(output.bold(`weight-eft remote-GPU tune [${res.mode}] on ${res.plan.host}`));
+        if (res.mode === 'dry-run')
+            output.writeln(output.dim('DRY-RUN — no data transferred, no training. Re-run with --execute --yes to spend GPU time on your host.'));
+        if (res.reason)
+            output.writeln(output.warning(res.reason));
+        output.writeln(`  base: ${res.plan.base}   remote workdir: ${res.plan.remoteWorkdir}   adapter → ${res.plan.adapterDir}/${res.plan.dpoAdapter}`);
+        if (res.preflight) {
+            output.writeln(output.dim('  preflight (read-only probes):'));
+            for (const p of res.preflight)
+                output.writeln(`    [${p.ok ? 'ok ' : 'FAIL'}] ${p.label}: ${p.detail}`);
+        }
+        output.writeln(output.dim('  commands that ' + (res.mode === 'executed' ? 'ran' : 'WOULD run') + ':'));
+        for (const c of res.plan.humanCommands)
+            output.writeln(`    $ ${c}`);
+        if (res.steps) {
+            output.writeln(output.dim('  execution:'));
+            for (const s of res.steps)
+                output.writeln(`    [${s.ok ? 'ok ' : 'FAIL'}] ${s.label}: ${s.detail}`);
+        }
+        output.writeln();
+        output.writeln(output.dim('Honesty: ruflo does not train locally or at $0. This is an explicit, user-triggered remote-GPU spend. resolved-gold in the SFT data is still a proxy.'));
+        return { success: res.mode !== 'preflight-failed', data: res };
+    },
+};
+const distillCommand = {
+    name: 'distill',
+    description: 'weight-eft training-data + cost-audit slice (ADR-150): export | plan | eval | train. Ships audited SFT/DPO data + a cost-Pareto measurement + a GPU plan. Does NOT train a model or reduce escalation.',
+    subcommands: [distillExportCommand, distillPlanCommand, distillEvalCommand, distillTrainCommand],
+    examples: [
+        { command: 'claude-flow neural distill export', description: 'Captured transcripts → audited SFT/DPO JSONL + guard report ($0)' },
+        { command: 'claude-flow neural distill plan', description: 'Print the GPU training plan + ruvllm commands ($0 dry-run)' },
+        { command: 'claude-flow neural distill eval --base-outcomes b.json --adapter-outcomes a.json', description: 'Cost-Pareto delta ($0)' },
+        { command: 'claude-flow neural distill train --remote gpu-box', description: 'Remote-GPU tune DRY-RUN (spend-gated behind --execute --yes)' },
+    ],
+    action: async () => {
+        output.writeln('Use a subcommand: export | plan | eval | train');
+        output.writeln(output.dim('Ships audited training DATA + a cost audit + a GPU plan. It does NOT train a model or reduce escalation (weight-eft train never spawns; resolved is a proxy).'));
+        return { success: true };
+    },
+};
 // Main neural command
 export const neuralCommand = {
     name: 'neural',
     description: 'Neural pattern training, MoE, Flash Attention, pattern learning',
-    subcommands: [trainCommand, statusCommand, patternsCommand, predictCommand, optimizeCommand, benchmarkCommand, listCommand, exportCommand, importCommand, routerCommand],
+    subcommands: [trainCommand, statusCommand, patternsCommand, predictCommand, optimizeCommand, benchmarkCommand, listCommand, exportCommand, importCommand, routerCommand, distillCommand],
     examples: [
         { command: 'claude-flow neural status', description: 'Check neural system status' },
         { command: 'claude-flow neural train -p coordination', description: 'Train coordination patterns' },

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

@@ -50,6 +50,9 @@ import { metaharnessTools } from './mcp-tools/metaharness-tools.js';
 // agenticow@~0.2.3 — Copy-On-Write memory branching tools (162-byte branches);
 // optional runtime dep, every handler returns `{degraded: true}` when missing.
 import { agenticowTools } from './mcp-tools/agenticow-tools.js';
+// agenticow step 4 — speculative branch-and-promote (A/B memory exploration).
+// Optional runtime dep, degrades to `{degraded: true}` when agenticow is missing.
+import { agenticowSpeculateTools } from './mcp-tools/agenticow-speculate-tools.js';
 // ADR-164 — AgentBBS federated business-domain BBS rooms (Phase 1).
 // Optional runtime dep, every handler returns `{degraded: true}` when missing.
 import { agentbbsTools } from './mcp-tools/agentbbs-tools.js';
@@ -139,8 +142,10 @@ registerTools([
     ...coverageRouterTools,
     // ADR-150 — MetaHarness static-analysis tools (5)
     ...metaharnessTools,
-    // agenticow@~0.2.3 — COW memory branching (4 tools, graceful-degraded when missing)
+    // agenticow@~0.2.4 — COW memory branching (9 tools: branch/checkpoint/rollback/promote + ingest/query/diff/lineage/status, graceful-degraded when missing)
     ...agenticowTools,
+    // agenticow step 4 — speculative branch-and-promote (1 tool, graceful-degraded when missing)
+    ...agenticowSpeculateTools,
     // ADR-164 — AgentBBS federated business-domain BBS rooms (4 tools, Phase 1, graceful-degraded)
     ...agentbbsTools,
     // ADR-164 Phase 2 + Phase 3 — business_pod_validate + business_pod_route_backend

package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-execute-core.js

@@ -512,6 +512,39 @@ export async function executeAgentTask(input) {
             }
             catch { /* never break execution */ }
         }
+        // ADR-150 weight-eft capture seam — the ONLY place a run's full outcome is
+        // known here: prompt (issue), assistant transcript, model, tier, and a
+        // resolved PROXY. Gated behind CLAUDE_FLOW_RUN_TRANSCRIPTS=1 (off by
+        // default; PII/retention surface, mirrors the router trajectory recorder).
+        // HONESTY: `resolved` here is the WEAKEST proxy — 'api-success' means only
+        // that the model returned without an API error, NOT that the output is
+        // correct (ruflo has no SWE-bench gold oracle). model_patch is '' because
+        // this single-shot execute path produces no unified diff. Both facts are
+        // stamped so no downstream weight-eft export mistakes this for gold data.
+        if (process.env.CLAUDE_FLOW_RUN_TRANSCRIPTS === '1') {
+            try {
+                const { recordRunTranscript, tierForModel } = await import('../ruvector/run-transcript-recorder.js');
+                const modelId = agent.modelId ?? String(agent.model ?? 'unknown');
+                const messages = [];
+                if (systemPrompt)
+                    messages.push({ role: 'system', content: systemPrompt });
+                messages.push({ role: 'user', content: input.prompt });
+                if (result.success && typeof result.output === 'string') {
+                    messages.push({ role: 'assistant', content: result.output });
+                }
+                recordRunTranscript({
+                    task: input.prompt,
+                    model: modelId,
+                    tier: tierForModel(modelId),
+                    resolved: outcome === 'success',
+                    resolvedSource: 'api-success',
+                    messages,
+                    source: 'agent-execute',
+                    tokens: result.usage ? { input: result.usage.inputTokens, output: result.usage.outputTokens } : undefined,
+                });
+            }
+            catch { /* never break execution */ }
+        }
     }
     catch {
         // Silent — bandit feedback must never block routing.

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

@@ -224,6 +224,8 @@ export const agentTools = [
                     description: 'Claude model alias (haiku=fast/cheap, sonnet=balanced, opus=current Opus 4.8, opus-4.7=prior Opus pin)'
                 },
                 task: { type: 'string', description: 'Task description for intelligent model routing' },
+                memoryBase: { type: 'string', description: 'Opt-in: base .rvf memory file to fork a per-agent Copy-On-Write branch from (agenticow). When set, the agent gets an isolated ~162-byte COW branch instead of a full copy — promote on success, discard on terminate. Requires the optional `agenticow` dep; degrades to a no-op when absent or when CLAUDE_FLOW_NO_COW_MEMORY=1.' },
+                memoryDimension: { type: 'integer', description: 'Vector dimension for the COW base (required only when memoryBase does not exist yet)' },
             },
             required: ['agentType'],
         },
@@ -295,6 +297,31 @@ export const agentTools = [
                 await addNode({ id: agentId, type: 'agent', name: agentType });
             }
             catch { /* graph-node not available */ }
+            // ACOW — opt-in per-agent COW memory branch. Only when the caller
+            // supplies `memoryBase` does the agent get an isolated 162-byte branch
+            // (vs a full .rvf copy). Lazy-imported so agenticow stays off the
+            // startup path. Non-fatal: a branch failure never blocks the spawn —
+            // the agent is already registered above.
+            let memoryBranch;
+            if (input.memoryBase) {
+                try {
+                    const { SwarmMemoryBranches } = await import('../services/swarm-memory-branches.js');
+                    const svc = new SwarmMemoryBranches();
+                    const br = await svc.branchForAgent(String(input.memoryBase), agentId, {
+                        dimension: typeof input.memoryDimension === 'number' ? input.memoryDimension : undefined,
+                    });
+                    if (br.branchPath) {
+                        memoryBranch = br.branchPath;
+                        agent.memoryBranch = br.branchPath;
+                        agent.memoryBase = br.basePath;
+                        store.agents[agentId] = agent;
+                        saveAgentStore(store);
+                    }
+                    // else: degraded (agenticow missing / kill-switched) — agent stands
+                    // without an isolated branch; callers see no memoryBranch field.
+                }
+                catch { /* COW branch is best-effort; agent already registered */ }
+            }
             // Include deterministic codemod routing info if applicable
             const response = {
                 success: true,
@@ -307,6 +334,7 @@ export const agentTools = [
                 ...(routingResult.openrouterModel ? { openrouterModel: routingResult.openrouterModel } : {}),
                 status: 'registered',
                 createdAt: agent.createdAt,
+                ...(memoryBranch ? { memoryBranch, memoryBase: agent.memoryBase } : {}),
                 note: 'Agent registered for coordination. Three execution paths: ' +
                     '(1) call agent_execute(agentId, prompt) — direct LLM call via Anthropic Messages API (requires ANTHROPIC_API_KEY); ' +
                     '(2) Claude Code Task tool — spawns a real subagent; ' +
@@ -375,6 +403,7 @@ export const agentTools = [
             properties: {
                 agentId: { type: 'string', description: 'ID of agent to terminate' },
                 force: { type: 'boolean', description: 'Force immediate termination' },
+                promoteMemory: { type: 'boolean', description: 'When the agent has a per-agent COW memory branch (spawned with memoryBase), promote (merge) its edits into the shared base on terminate. Default false → discard the branch (throw its edits away). No-op when the agent has no branch.' },
             },
             required: ['agentId'],
         },
@@ -385,13 +414,30 @@ export const agentTools = [
             const store = loadAgentStore();
             const agentId = input.agentId;
             if (store.agents[agentId]) {
-                store.agents[agentId].status = 'terminated';
+                const rec = store.agents[agentId];
+                rec.status = 'terminated';
                 saveAgentStore(store);
+                // ACOW — resolve the agent's COW memory branch on teardown: promote
+                // (merge into base) when asked, else discard. Non-fatal — a failure
+                // here never blocks termination. Discard needs no agenticow (pure fs),
+                // so cleanup still works in the degraded path.
+                let memory;
+                if (rec.memoryBranch) {
+                    try {
+                        const { SwarmMemoryBranches } = await import('../services/swarm-memory-branches.js');
+                        const svc = new SwarmMemoryBranches();
+                        memory = input.promoteMemory
+                            ? (await svc.promoteAgent(agentId))
+                            : (await svc.discardAgent(agentId));
+                    }
+                    catch { /* best-effort teardown */ }
+                }
                 return {
                     success: true,
                     agentId,
                     terminated: true,
                     terminatedAt: new Date().toISOString(),
+                    ...(memory ? { memory } : {}),
                 };
             }
             return {

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

@@ -0,0 +1,59 @@
+/**
+ * Agenticow shared loader + helpers.
+ *
+ * Extracted from `agenticow-tools.ts` so both the MCP tool surface AND the
+ * `SwarmMemoryBranches` service (src/services/swarm-memory-branches.ts) share
+ * one loader, one degradation contract, and one set of path/lineage helpers —
+ * rather than duplicating the optional-dep dance in two places.
+ *
+ * Architectural constraint (ADR-150, mirrors metaharness-tools.ts):
+ *   - `agenticow` lives in `optionalDependencies` — never a hard runtime dep.
+ *   - When the package is missing, callers get `null` from `loadAgenticow()`
+ *     (or a `{degraded:true}` result via `degradedResult`) and MUST fall back
+ *     gracefully — never throw a MODULE_NOT_FOUND.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-loader
+ */
+export declare const PACKAGE_NAME = "agenticow";
+export interface AgenticowApi {
+    open: (file: string, opts?: {
+        dimension?: number;
+        metric?: string;
+    }) => Promise<any>;
+    openBase?: (file: string, opts?: any) => Promise<any>;
+    AgenticMemory: any;
+}
+/**
+ * Lazily import `agenticow`. Returns the module on success, or `null` when the
+ * package is not installed (the optional-dep degraded path). Any OTHER load
+ * error (e.g. a corrupt install) is re-thrown so it is not silently masked.
+ */
+export declare function loadAgenticow(): Promise<AgenticowApi | null>;
+/** Reset the module-level load cache. Test-only seam. */
+export declare function __resetAgenticowCache(): void;
+export declare function degradedResult(reason: string): {
+    success: true;
+    degraded: true;
+    reason: string;
+};
+/**
+ * Resolve a user-supplied memory path against the project cwd, rejecting path
+ * traversal and NUL bytes (D-2 style hardening — same rule the MCP verbs use).
+ */
+export declare function resolveMemoryPath(path: string): string;
+/**
+ * Lineage manifest companion path. agenticow persists the COW chain
+ * (working → checkpoints → base) into `<file>.agenticow.json` next to the
+ * `.rvf` data file. Without it, forks/checkpoints are in-memory only and
+ * disappear when the AgenticMemory handle closes.
+ */
+export declare function manifestFor(file: string): string;
+/** Validate a COW branch/checkpoint label (alnum + a small safe symbol set). */
+export declare function validateLabel(label: string): string;
+/**
+ * Open (or create) a memory file, restoring its COW chain from the lineage
+ * manifest when one exists. When neither the `.rvf` nor the manifest exists,
+ * `dimension` is required to create a fresh base.
+ */
+export declare function openWithLineage(api: AgenticowApi, file: string, dimension?: number): Promise<any>;
+//# sourceMappingURL=agenticow-loader.d.ts.map