feat(v5-g23): gradient_clip_norm activation + extras.gradient_clip

Closes V5-G23 / cppmega-mlx-br8. OptimSpec.gradient_clip_norm existed
as decorative field — stage_train never applied it.

Backend (stages.py):
  - Read spec.optim.gradient_clip_norm (from rewritten or original spec)
  - Per step: compute global L2 grad norm; if > threshold, rescale all
    grads by threshold/norm; bump num_clips counter
  - extras.gradient_clip = {threshold, max_grad_norm_seen, num_clips}

Wire (schema.py + methods.py + App.tsx):
  - OptimSpecPayload.gradient_clip_norm field (default 1.0)
  - _make_optim threads it into OptimSpec()
  - App.tsx buildVerifyParams + suggest_sharding payload include
    gradient_clip_norm: spec.optim.grad_clip_norm (UI used underscore
    variant of the name; mapped to camel-free wire form)

Pytest (4 in test_stage_train_clip.py):
  - threshold=1.0 populates max_grad_norm_seen > 0
  - None disables (no observation)
  - 0.001 triggers num_clips > 0
  - 1000 large threshold → num_clips=0 but max_seen reported

E2E (1 in 52_clip_norm.spec.ts):
  - UI OptimTab clip=0.001 → Apply → Train → extras.gradient_clip
    .threshold=0.001 + num_clips>0

Regression: 183 vitest + 49 stage_train pytest unchanged.

Author: apstenku123

cppmega_v4/jsonrpc/methods.py

@@ -195,7 +195,8 @@ def _make_schedule(g) -> ScheduleSpec | None:
         )
         for g in payload.groups
     )
-    return OptimSpec(kind=kind, groups=groups)
+    return OptimSpec(kind=kind, groups=groups,
+                     gradient_clip_norm=payload.gradient_clip_norm)
 
 
 def _make_topology(payload: TopologyPayload):

cppmega_v4/jsonrpc/schema.py

@@ -155,6 +155,9 @@ class OptimSpecPayload(BaseModel):
 
     kind: str
     groups: list[ParamGroupPayload]
+    # V5-G23: UI gradient_clip_norm passed through to backend OptimSpec
+    # so stage_train can apply L2-norm clipping. None disables.
+    gradient_clip_norm: float | None = 1.0
 
 
 def _default_optim_payload() -> OptimSpecPayload:

vbgui/e2e/scenarios/52_clip_norm.spec.ts

@@ -0,0 +1,34 @@
+// G23: gradient_clip_norm activation observable in extras.gradient_clip.
+
+import { test, expect } from "@playwright/test";
+import { gotoApp, selectPreset, closeModal } from "../fixtures";
+
+test("G23: tight clip (0.001) triggers num_clips > 0 in extras", async ({
+  page,
+}) => {
+  test.setTimeout(60_000);
+  await gotoApp(page);
+  await selectPreset(page, "llama3_8b");
+
+  await page.getByTestId("sidebar-tab-optim").click();
+  await page.getByTestId("optim-clip").fill("0.001");
+  await page.getByTestId("optim-apply").click();
+
+  await page.getByTestId("run-pipeline-toggle").click();
+  await page.getByTestId("train-num-steps").fill("4");
+  await page.getByTestId("run-pipeline-train").click();
+  const modal = page.getByTestId("run-result-modal");
+  await modal.waitFor({ timeout: 60_000 });
+  await page.getByTestId("run-result-expand-train").click();
+
+  const numClips = parseInt(
+    (await page.getByTestId("run-result-extras-train-gradient_clip-num_clips")
+      .textContent()) ?? "0", 10);
+  const threshold = parseFloat(
+    (await page.getByTestId("run-result-extras-train-gradient_clip-threshold")
+      .textContent()) ?? "0");
+  expect(threshold).toBeCloseTo(0.001, 6);
+  expect(numClips).toBeGreaterThan(0);
+
+  await closeModal(page);
+});

vbgui/src/App.tsx

@@ -253,6 +253,7 @@ export function App(): JSX.Element {
         loss: { kind: snap.spec.loss.kind,
                 head_outputs: snap.spec.loss.head_outputs },
         optim: { kind: snap.spec.optim.kind,
+                 gradient_clip_norm: snap.spec.optim.grad_clip_norm,
                  groups: snap.spec.optim.groups.map((g) => ({
                    matcher: g.matcher, lr: g.lr,
                    weight_decay: g.weight_decay,
@@ -481,6 +482,7 @@ function buildVerifyParams(
     loss: { kind: spec.loss.kind, head_outputs: spec.loss.head_outputs,
             params: spec.loss.params },
     optim: { kind: spec.optim.kind,
+             gradient_clip_norm: spec.optim.grad_clip_norm,
              groups: spec.optim.groups.map((g) => ({
                matcher: g.matcher, lr: g.lr,
                weight_decay: g.weight_decay, betas: g.betas,