@claude-flow/cli 3.19.0 → 3.21.0

package/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' },