feat(e-audit-05): cppmega_mlx.cli.smoke_zero1 entrypoint

V7-Q05 (E-AUDIT-05, cppmega-mlx-bfbi) — Lane 8 audit gap closure.

Implements the ZeRO-1 smoke CLI documented as "not yet implemented"
in docs/distributed_zero1_smoke_procedure.md:170. Thin wrapper around
scripts/bench_zero1_loopback.py that builds the mlx.launch command:

  python -m cppmega_mlx.cli.smoke_zero1 \
    --hosts 127.0.0.1,127.0.0.1 \
    --num-steps 20 \
    --out bench/baselines/zero1_loopback_2proc_m4.json

Flags:
- --hosts CSV (default 127.0.0.1,127.0.0.1 loopback)
- --world-size N (derived from hosts when 0)
- --num-steps N (default 20)
- --lr F (default 1e-4)
- --out PATH (default bench/baselines/zero1_smoke.json)
- --simulate (in-process fallback, no mlx.launch)
- --mlx-launch PATH (override mlx.launch binary)
- --dry-run (print would-be argv on stderr, exit 0)

Backend bench script unchanged — CLI just orchestrates mlx.launch with
the right -n / --hosts arguments and forwards --steps/--lr/--out to
the existing bench main().

Tests (8/8 PASS, tests/v4/test_smoke_zero1_cli.py):
- _resolve_world_size from CSV + explicit override
- _build_launch_argv argv composition
- _build_simulate_argv flag insertion
- --dry-run loopback + simulate paths
- missing mlx.launch on PATH -> exit 64 (EX_USAGE)
- DEFAULT_OUT / DEFAULT_SIMULATE_OUT path defaults

Doc updates:
- docs/distributed_zero1_smoke_procedure.md: replaced "not yet
  implemented" placeholder with shipping-status note.

Multi-Mac receipt (peer-48) remains BLOCKED on external hardware
per § "Step 3" — this CLI unblocks the loopback receipt today and
will produce a real multi-Mac receipt as soon as peer-48 SSH is up.

Closes Lane 8 P1 audit gap from docs/UI-TO-TRAIN-AUDIT-2026-05-23.md.

Author: apstenku123

cppmega_mlx/cli/__init__.py

@@ -0,0 +1,11 @@
+"""cppmega_mlx CLI entrypoints.
+
+Each module exposes a ``main()`` function callable from
+``python -m cppmega_mlx.cli.<name>`` for end-user orchestration of
+single-Mac, loopback, and multi-mac smoke receipts.
+
+Currently shipping:
+  - smoke_zero1 — ZeRO-1 distributed-wrapper receipt (loopback or
+    multi-host) via ``mlx.launch``. V7-Q05 closure of
+    ``docs/distributed_zero1_smoke_procedure.md`` "not yet implemented".
+"""

cppmega_mlx/cli/smoke_zero1.py

@@ -0,0 +1,169 @@
+"""V7-Q05: cppmega_mlx.cli.smoke_zero1 — ZeRO-1 distributed receipt.
+
+Thin entrypoint that wraps scripts/bench_zero1_loopback.py under
+``mlx.launch -n W --hosts H1,H2,...`` so a single command produces the
+loopback / multi-mac receipt JSON. Closes
+``docs/distributed_zero1_smoke_procedure.md`` Step 1 "not yet
+implemented" placeholder.
+
+Usage::
+
+    # 2-process loopback on the same Mac (canonical receipt)
+    python -m cppmega_mlx.cli.smoke_zero1 \\
+        --hosts 127.0.0.1,127.0.0.1 \\
+        --out bench/baselines/zero1_loopback_2proc_m4.json
+
+    # Multi-Mac (requires mlx.launch ssh access to both hosts)
+    python -m cppmega_mlx.cli.smoke_zero1 \\
+        --hosts dev-128.local,peer-48.local \\
+        --num-steps 20
+
+    # In-process simulation fallback (no mlx.launch needed)
+    python -m cppmega_mlx.cli.smoke_zero1 --simulate \\
+        --num-steps 8
+
+    # Show the launch command without running it
+    python -m cppmega_mlx.cli.smoke_zero1 --hosts 127.0.0.1,127.0.0.1 \\
+        --dry-run
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# Sit at <repo>/cppmega_mlx/cli/smoke_zero1.py — two parents up = repo root.
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_OUT = REPO_ROOT / "bench" / "baselines" / "zero1_smoke.json"
+DEFAULT_SIMULATE_OUT = (
+    REPO_ROOT / "bench" / "baselines" / "zero1_simulated_2proc_m4.json"
+)
+BENCH_SCRIPT = REPO_ROOT / "scripts" / "bench_zero1_loopback.py"
+
+
+def _resolve_world_size(hosts_csv: str, override: int) -> int:
+    """Derive world size from the hosts CSV unless an override is given."""
+    if override and override > 0:
+        return int(override)
+    return len([h for h in hosts_csv.split(",") if h.strip()])
+
+
+def _build_launch_argv(
+    *, mlx_launch: str, hosts_csv: str, world_size: int,
+    num_steps: int, lr: float, out: Path,
+) -> list[str]:
+    """Construct the mlx.launch argv that runs the loopback bench."""
+    return [
+        mlx_launch, "-n", str(world_size),
+        "--hosts", hosts_csv,
+        sys.executable, str(BENCH_SCRIPT),
+        "--steps", str(num_steps),
+        "--lr", str(lr),
+        "--out", str(out),
+    ]
+
+
+def _build_simulate_argv(
+    *, num_steps: int, lr: float, out: Path,
+) -> list[str]:
+    """Construct the in-process simulation argv (no mlx.launch needed)."""
+    return [
+        sys.executable, str(BENCH_SCRIPT),
+        "--simulate",
+        "--steps", str(num_steps),
+        "--lr", str(lr),
+        "--out", str(out),
+    ]
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="python -m cppmega_mlx.cli.smoke_zero1",
+        description="ZeRO-1 distributed smoke receipt via mlx.launch.",
+    )
+    p.add_argument(
+        "--hosts",
+        default="127.0.0.1,127.0.0.1",
+        help=("Comma-separated host list passed to mlx.launch --hosts. "
+              "Default: 127.0.0.1,127.0.0.1 (2-proc loopback)."),
+    )
+    p.add_argument(
+        "--world-size",
+        type=int,
+        default=0,
+        help=("Explicit -n value for mlx.launch. Defaults to len(hosts)."),
+    )
+    p.add_argument("--num-steps", type=int, default=20,
+                   help="Steps per rank + W=1 control (default 20).")
+    p.add_argument("--lr", type=float, default=1e-4,
+                   help="Learning rate (default 1e-4).")
+    p.add_argument("--out", type=Path, default=None,
+                   help=(f"Output JSON. Defaults to {DEFAULT_OUT} "
+                         f"(or {DEFAULT_SIMULATE_OUT} for --simulate)."))
+    p.add_argument("--simulate", action="store_true",
+                   help=("Run the in-process simulation fallback "
+                         "(no mlx.launch needed)."))
+    p.add_argument("--mlx-launch", default="mlx.launch",
+                   help="Path to mlx.launch (default: looked up on PATH).")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Print the argv that would be launched and exit 0.")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    if args.simulate:
+        out = args.out or DEFAULT_SIMULATE_OUT
+        cmd = _build_simulate_argv(
+            num_steps=args.num_steps, lr=args.lr, out=out,
+        )
+        if args.dry_run:
+            print(f"[smoke_zero1 dry-run] would run: {cmd}", file=sys.stderr)
+            return 0
+        return subprocess.call(cmd)
+
+    # Loopback / multi-mac path: requires mlx.launch on PATH.
+    world_size = _resolve_world_size(args.hosts, args.world_size)
+    if world_size < 1:
+        print("[smoke_zero1] world size resolved to 0; "
+              "pass --hosts or --world-size", file=sys.stderr)
+        return 64
+
+    if not args.dry_run:
+        # shutil.which honors PATH; explicit absolute paths bypass.
+        if "/" not in args.mlx_launch:
+            resolved = shutil.which(args.mlx_launch)
+            if resolved is None:
+                print(f"[smoke_zero1] mlx.launch not found on PATH "
+                      f"(searched as {args.mlx_launch!r}). Install MLX "
+                      f"or use --simulate.", file=sys.stderr)
+                return 64
+            mlx_launch_bin = resolved
+        else:
+            if not Path(args.mlx_launch).exists():
+                print(f"[smoke_zero1] mlx.launch not found at "
+                      f"{args.mlx_launch} (not on PATH either).",
+                      file=sys.stderr)
+                return 64
+            mlx_launch_bin = args.mlx_launch
+    else:
+        mlx_launch_bin = args.mlx_launch
+
+    out = args.out or DEFAULT_OUT
+    cmd = _build_launch_argv(
+        mlx_launch=mlx_launch_bin, hosts_csv=args.hosts,
+        world_size=world_size, num_steps=args.num_steps,
+        lr=args.lr, out=out,
+    )
+    if args.dry_run:
+        print(f"[smoke_zero1 dry-run] would run: {cmd}", file=sys.stderr)
+        return 0
+    return subprocess.call(cmd)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

docs/distributed_zero1_smoke_procedure.md

@@ -167,9 +167,12 @@ group (which `mlx.launch -n 2` guarantees), the wrapper auto-detects
 `world_size = 2` and `rank in {0, 1}` from the global group and only the
 local-shard optimizer state is allocated.
 
-Note: `cppmega_mlx.cli.smoke_zero1` is **not yet implemented**. It will be
-added alongside the first real receipt; for now, the procedure is documented
-ahead of the launcher script so we have a target signature.
+Status: `cppmega_mlx.cli.smoke_zero1` is **implemented** (V7-Q05, commit
+landed 2026-05-23). It is a thin wrapper around
+`scripts/bench_zero1_loopback.py` that constructs the `mlx.launch -n W
+--hosts H1,H2,...` command line. Loopback receipts on a single Mac
+work today; multi-Mac receipts require peer-48 hand-off (still
+external blocker per § "Step 3").
 
 ---
 

tests/v4/test_smoke_zero1_cli.py

@@ -0,0 +1,94 @@
+"""V7-Q05: regression for cppmega_mlx.cli.smoke_zero1.
+
+Pin the argparse + command-construction path. We don't actually launch
+mlx.launch in CI (multi-process, slow); --dry-run mode exposes the
+argv that *would* be invoked and the smoke receipt regeneration is
+covered separately in scripts/bench_zero1_loopback.py's own test.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+from unittest import mock
+
+from cppmega_mlx.cli import smoke_zero1
+
+
+def test_resolve_world_size_from_hosts() -> None:
+    assert smoke_zero1._resolve_world_size("a,b,c", 0) == 3
+    assert smoke_zero1._resolve_world_size("a,b", 0) == 2
+    assert smoke_zero1._resolve_world_size("solo", 0) == 1
+
+
+def test_resolve_world_size_explicit_override() -> None:
+    # Explicit --world-size wins over derived count.
+    assert smoke_zero1._resolve_world_size("a,b", 4) == 4
+
+
+def test_build_launch_argv_threads_hosts_and_steps() -> None:
+    argv = smoke_zero1._build_launch_argv(
+        mlx_launch="mlx.launch",
+        hosts_csv="127.0.0.1,127.0.0.1",
+        world_size=2, num_steps=11, lr=2e-4,
+        out=Path("/tmp/out.json"),
+    )
+    # Order matters: mlx.launch -n W --hosts H python script ...
+    assert argv[0] == "mlx.launch"
+    assert "-n" in argv and argv[argv.index("-n") + 1] == "2"
+    assert "--hosts" in argv
+    assert argv[argv.index("--hosts") + 1] == "127.0.0.1,127.0.0.1"
+    assert "--steps" in argv and argv[argv.index("--steps") + 1] == "11"
+    assert "--lr" in argv and argv[argv.index("--lr") + 1] == "0.0002"
+    assert "--out" in argv
+    assert argv[argv.index("--out") + 1] == "/tmp/out.json"
+
+
+def test_build_simulate_argv_inserts_simulate_flag() -> None:
+    argv = smoke_zero1._build_simulate_argv(
+        num_steps=7, lr=1e-3, out=Path("/tmp/sim.json"),
+    )
+    assert "--simulate" in argv
+    assert argv[0] == sys.executable
+    assert "--steps" in argv and argv[argv.index("--steps") + 1] == "7"
+
+
+def test_dry_run_returns_zero_without_subprocess(capsys) -> None:
+    code = smoke_zero1.main([
+        "--hosts", "127.0.0.1,127.0.0.1",
+        "--num-steps", "2",
+        "--dry-run",
+    ])
+    assert code == 0
+    err = capsys.readouterr().err
+    # The dry-run path prints the would-be command on stderr.
+    assert "smoke_zero1" in err
+    assert "127.0.0.1,127.0.0.1" in err
+
+
+def test_dry_run_simulate_returns_zero(capsys) -> None:
+    code = smoke_zero1.main(["--simulate", "--dry-run"])
+    assert code == 0
+    err = capsys.readouterr().err
+    assert "--simulate" in err
+
+
+def test_missing_mlx_launch_returns_ex_usage(capsys) -> None:
+    """When mlx.launch is not on PATH (non --simulate path), exit 64."""
+    with mock.patch("shutil.which", return_value=None):
+        code = smoke_zero1.main([
+            "--hosts", "127.0.0.1,127.0.0.1",
+            "--mlx-launch", "/nonexistent/mlx.launch",
+        ])
+    assert code == 64
+    err = capsys.readouterr().err
+    assert "not found" in err or "PATH" in err
+
+
+def test_out_path_default_loopback() -> None:
+    """--out default for non-simulate is bench/baselines/zero1_smoke.json."""
+    assert smoke_zero1.DEFAULT_OUT.name == "zero1_smoke.json"
+    assert smoke_zero1.DEFAULT_SIMULATE_OUT.name == \
+        "zero1_simulated_2proc_m4.json"