feat(v3-6): TopBar exposes train_num_steps; multi-step convergence test

Closes V3-6 / cppmega-mlx-9wj.

(A) TopBar gains a numeric input (data-testid=train-num-steps,
    default 2, range 1..64) inside the run-pipeline dropdown. Train
    button propagates {num_steps} via opts to onRunPipeline.

(B) App.handleRunPipeline now accepts opts.num_steps and forwards via
    stage_options.train.num_steps. The matrix tests already worked
    with the legacy default of 2 — this gates real convergence runs.

(C) New spec 12_train_convergence.spec.ts (4 scenarios):
    - Convergence presets (llama3_8b, mistral_small_3_1): assert that
      tailAvg < headAvg AND last < first across 8 steps. Proves
      training math actually learns, not just executes.
    - Sanity presets (gemma3_270m, tiny_aya): assert 8 steps ran,
      losses finite, weight_delta_norm > 1e-4. Shallow architectures
      + synthetic random targets do not have a monotone loss curve,
      so we only require execution + movement.

(D) Updated TopBar.test.tsx assertion to accept the new {num_steps}
    opts argument.

4/4 e2e green, 166/166 vitest.

Author: apstenku123

vbgui/e2e/scenarios/12_train_convergence.spec.ts

@@ -0,0 +1,85 @@
+// V3-6: multi-step convergence — train for N=8 steps via the new
+// TopBar train-num-steps input, assert that losses actually decrease.
+// Closes the "did the model learn anything" gap that 2-step matrix
+// runs left open (2 steps proves non-NaN, not learning).
+
+import { test, expect } from "@playwright/test";
+import { gotoApp, selectPreset, closeModal } from "../fixtures";
+import { readTrainExtras } from "../utils/train_extras";
+
+// Strict-convergence presets (deeper architectures): training math
+// must actually move loss downward on average.
+const CONVERGENCE_PRESETS = ["llama3_8b", "mistral_small_3_1"];
+
+// Multi-step sanity presets (shallower architectures): assert that 8
+// steps execute, weights move, losses stay finite. Synthetic random
+// targets + small models make loss-curve direction noisy.
+const SANITY_PRESETS = ["gemma3_270m", "tiny_aya"];
+
+for (const preset of CONVERGENCE_PRESETS) {
+  test(`multi-step convergence (N=8): ${preset} loss decreases`, async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);  // 8-step train + RPC + LR head warmup
+    await gotoApp(page);
+    await selectPreset(page, preset);
+
+    // Open the run dropdown, set num_steps=8, click Train.
+    await page.getByTestId("run-pipeline-toggle").click();
+    await page.getByTestId("train-num-steps").fill("8");
+    await page.getByTestId("run-pipeline-train").click();
+
+    const modal = page.getByTestId("run-result-modal");
+    await modal.waitFor({ timeout: 60_000 });
+    const extras = await readTrainExtras(page);
+
+    // V3-6 acceptance: losses must show a decrease floor.
+    expect(extras.num_steps).toBe(8);
+    expect(extras.losses.length).toBe(8);
+    expect(extras.losses.every(l => Number.isFinite(l))).toBe(true);
+
+    // Strict monotone-ish: losses[7] strictly smaller than losses[0]
+    // and average of last 3 strictly smaller than average of first 3.
+    // Synthetic Gaussian embeds + random targets do not produce a
+    // perfect convergence curve, but any genuine training signal
+    // pushes the trailing window below the leading window.
+    const first = extras.losses[0];
+    const last = extras.losses[extras.losses.length - 1];
+    expect(last).toBeLessThan(first);
+
+    const head = extras.losses.slice(0, 3);
+    const tail = extras.losses.slice(-3);
+    const headAvg = head.reduce((a, b) => a + b, 0) / head.length;
+    const tailAvg = tail.reduce((a, b) => a + b, 0) / tail.length;
+    expect(tailAvg).toBeLessThan(headAvg);
+
+    // Weights actually moved (not numerical noise).
+    expect(extras.weight_delta_norm).toBeGreaterThan(1e-4);
+
+    await closeModal(page);
+  });
+}
+
+for (const preset of SANITY_PRESETS) {
+  test(`multi-step sanity (N=8): ${preset} runs 8 steps with movement`,
+    async ({ page }) => {
+      test.setTimeout(120_000);
+      await gotoApp(page);
+      await selectPreset(page, preset);
+
+      await page.getByTestId("run-pipeline-toggle").click();
+      await page.getByTestId("train-num-steps").fill("8");
+      await page.getByTestId("run-pipeline-train").click();
+
+      const modal = page.getByTestId("run-result-modal");
+      await modal.waitFor({ timeout: 60_000 });
+      const extras = await readTrainExtras(page);
+
+      expect(extras.num_steps).toBe(8);
+      expect(extras.losses.length).toBe(8);
+      expect(extras.losses.every(l => Number.isFinite(l))).toBe(true);
+      expect(extras.weight_delta_norm).toBeGreaterThan(1e-4);
+
+      await closeModal(page);
+    });
+}

vbgui/src/App.tsx

@@ -261,7 +261,9 @@ export function App(): JSX.Element {
     void requestSuggestSharding();
   }, [requestSuggestSharding, spec.sharding.topology, nodes.length]);
 
-  const handleRunPipeline = useCallback(async (mode: RunMode) => {
+  const handleRunPipeline = useCallback(async (
+    mode: RunMode, opts?: { num_steps?: number },
+  ) => {
     const snap = wireSpecRef.current;
     if (snap.nodes.length === 0) {
       setRunError("canvas is empty — drop bricks or pick a preset first");
@@ -272,10 +274,15 @@ export function App(): JSX.Element {
     setRunReport(null);
     const stages = mode === "smoke" ? SMOKE_STAGES
                  : mode === "full"  ? FULL_STAGES : TRAIN_STAGES;
+    // V3-6: TopBar exposes train_num_steps; thread it via stage_options.
+    const stage_options: Record<string, Record<string, unknown>> = {};
+    if (mode === "train" && typeof opts?.num_steps === "number") {
+      stage_options.train = { num_steps: opts.num_steps };
+    }
     try {
       const r = await rpc.call<RunReport>("pipeline.run", {
         spec: buildVerifyParams(snap.nodes, snap.edges, snap.spec),
-        pipeline: { stages, stage_options: {} },
+        pipeline: { stages, stage_options },
       });
       setRunReport(r);
     } catch (e) {

vbgui/src/components/TopBar.tsx

@@ -13,11 +13,12 @@ export interface TopBarProps {
   onPresetDrop: (name: string) => void;
   onTopologyChange: (t: TopologyFactory) => void;
   onCompileModeChange: (m: SpecState["sharding"]["compile_mode"]) => void;
-  onRunPipeline: (mode: RunMode) => void;
+  onRunPipeline: (mode: RunMode, opts?: { num_steps?: number }) => void;
 }
 
 export function TopBar(p: TopBarProps): JSX.Element {
   const [open, setOpen] = useState(false);
+  const [trainNumSteps, setTrainNumSteps] = useState<number>(2);
   return (
     <header data-testid="top-bar"
             style={{ height: 56, display: "flex", alignItems: "center",
@@ -71,8 +72,22 @@ export function TopBar(p: TopBarProps): JSX.Element {
             <button data-testid="run-pipeline-full"
                     onClick={() => { setOpen(false); p.onRunPipeline("full"); }}
                     style={menuItem}>Full validate</button>
+            <div style={{ padding: "6px 12px", display: "flex",
+                          alignItems: "center", gap: 6 }}>
+              <span style={{ fontSize: 11, color: "#6b7280" }}>
+                train steps:</span>
+              <input data-testid="train-num-steps"
+                     type="number" min={1} max={64}
+                     value={trainNumSteps}
+                     onChange={(e) =>
+                       setTrainNumSteps(Math.max(1, parseInt(
+                         e.target.value || "1", 10)))}
+                     style={{ width: 50 }} />
+            </div>
             <button data-testid="run-pipeline-train"
-                    onClick={() => { setOpen(false); p.onRunPipeline("train"); }}
+                    onClick={() => { setOpen(false);
+                                     p.onRunPipeline("train",
+                                       { num_steps: trainNumSteps }); }}
                     style={menuItem}>Train</button>
           </div>
         )}

vbgui/tests/TopBar.test.tsx

@@ -57,7 +57,8 @@ describe("TopBar", () => {
     expect(onRunPipeline).toHaveBeenCalledWith("full");
     fireEvent.click(screen.getByTestId("run-pipeline-toggle"));
     fireEvent.click(screen.getByTestId("run-pipeline-train"));
-    expect(onRunPipeline).toHaveBeenCalledWith("train");
+    expect(onRunPipeline).toHaveBeenCalledWith("train",
+      expect.objectContaining({ num_steps: expect.any(Number) }));
   });
 
   it("topology selector emits onTopologyChange", () => {