meshcode 2.11.152__tar.gz → 2.11.154__tar.gz

{meshcode-2.11.152 → meshcode-2.11.154}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.11.152
+Version: 2.11.154
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT

{meshcode-2.11.152 → meshcode-2.11.154}/meshcode/__init__.py

@@ -1,5 +1,5 @@
 """MeshCode — Real-time communication between AI agents."""
-__version__ = "2.11.152"
+__version__ = "2.11.154"
 
 # Exception hierarchy — eagerly imported (lightweight, no deps)
 from meshcode.exceptions import (  # noqa: F401

meshcode-2.11.154/meshcode/_launch_smoke.py

@@ -0,0 +1,227 @@
+"""Golden launch smoke — Layer 1 of Launch Regression Armor (task 2e85c6a8).
+
+Deterministic, offline-capable proof that a launch path is HEALTHY. It exists so a
+broken launch is caught at two gates instead of in Samuel's terminal:
+
+  * Layer 2 (pre-publish CI gate) runs the OFFLINE subset against a freshly built
+    wheel — a wheel that fails smoke never reaches PyPI.
+  * Layer 3 (runtime update-guard) runs the OFFLINE subset against an on-disk env
+    BEFORE hostd execs into it — a bad version is refused, not adopted.
+
+OFFLINE subset (no creds, no live mesh — the part CI/runtime-guard rely on):
+
+  version_coherence
+      meshcode.__version__ (the loaded module) must equal the installed dist
+      metadata version, and — if the launcher stamped it — MESHCODE_EXPECTED_VERSION.
+      A mismatch IS the runtime version-split (user-site vs pinned env, or an
+      egg-info source shadow) that produced Samuel's doubles + loop-drop. This is
+      THE root cause this armor exists for, so it is check #1.
+
+  mcp_import
+      meshcode.meshcode_mcp.server must import cleanly in an isolated subprocess in
+      under the MCP handshake budget (2.0 s). Catches import-time sys.exit
+      (BUG-COMMANDER-MCP-BOOT) and slow-import regressions that silently drop the
+      meshcode_* tools past Claude Code's 5 s MCP_TIMEOUT. Mirrors the env + parse
+      contract of meshcode_mcp/test_boot_timing.py (single source of the budget).
+
+LIVE subset (--live; needs creds + a resolvable agent), additive on top of offline:
+
+  doctor          doctor.run_doctor() reports no hard failures.
+  dry_run_launch  `meshcode run <project>/<agent> --dry-run` exits 0 ("DRY-RUN OK"):
+                  the full bootstrap codepath (workspace, .mcp.json, ensure_boot_env,
+                  ownership, editor detection, cmd construction) short of execvp.
+
+CLI:  meshcode smoke [--live] [--json] [project/agent]
+      exit 0 iff every selected check passes. --json emits a machine-readable report
+      {ok, checks:[{check, ok, detail}, ...]} for the CI gate to parse.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from typing import Optional
+
+# MCP handshake budget. Claude Code's default MCP_TIMEOUT is 5 s; a 2 s import ceiling
+# leaves room for run_server() + lifespan pre-yield work. Kept in lock-step with
+# meshcode_mcp/test_boot_timing.py:MAX_IMPORT_MS (2000).
+BOOT_IMPORT_BUDGET_S = 2.0
+
+
+def _check_version_coherence() -> dict:
+    """Loaded __version__ == installed dist metadata == MESHCODE_EXPECTED_VERSION.
+
+    Returns N/A-pass when the dist metadata is absent (source/editable checkout) so
+    dev runs don't false-positive; a mismatch when BOTH are present is the version
+    split we are hunting and fails hard.
+    """
+    try:
+        import meshcode
+        loaded = getattr(meshcode, "__version__", None)
+    except Exception as e:  # pragma: no cover - import of own pkg failing is itself a fail
+        return {"check": "version_coherence", "ok": False,
+                "detail": f"import meshcode failed: {e}"}
+
+    installed: Optional[str] = None
+    try:
+        from importlib.metadata import version as _dist_version
+        installed = _dist_version("meshcode")
+    except Exception:
+        installed = None  # source/editable run — no dist metadata to compare against
+
+    expected = (os.environ.get("MESHCODE_EXPECTED_VERSION") or "").strip() or None
+
+    mismatches = []
+    if installed and loaded and installed != loaded:
+        mismatches.append(f"loaded={loaded} != installed_dist={installed}")
+    if expected and loaded and expected != loaded:
+        mismatches.append(f"loaded={loaded} != expected_env={expected}")
+
+    ok = not mismatches and bool(loaded)
+    if not loaded:
+        detail = "meshcode.__version__ missing"
+    elif mismatches:
+        detail = "; ".join(mismatches)
+    else:
+        detail = f"loaded={loaded} installed={installed or 'n/a(source)'} expected={expected or 'unset'}"
+    return {"check": "version_coherence", "ok": ok, "detail": detail}
+
+
+def _check_mcp_import() -> dict:
+    """Import meshcode.meshcode_mcp.server in a clean subprocess; assert it succeeds
+    fast. Env + IMPORT_MS parse contract mirror test_boot_timing.py exactly."""
+    env = os.environ.copy()
+    # Stable identity so the module-load path doesn't enter the slow mc_resolve_project
+    # retry loop; these mirror what `meshcode setup` bakes into a real .mcp.json.
+    env.setdefault("MESHCODE_PROJECT", "launch-smoke")
+    env.setdefault("MESHCODE_PROJECT_ID", "00000000-0000-0000-0000-000000000000")
+    env.setdefault("MESHCODE_AGENT", "launch-smoke")
+    env.setdefault("MESHCODE_KEYCHAIN_PROFILE", "default")
+    env.setdefault("SUPABASE_URL", "https://gjinagyyjttyxnaoavnz.supabase.co")
+    env.setdefault("SUPABASE_KEY", "sb_publishable_qwN9PO1L7jUXhhbhhVk2CQ_z1FXG2Qf")
+    # Skip the PyPI auto-update HTTP GET — orthogonal to import latency.
+    env["MESHCODE_AUTO_UPDATE"] = "0"
+
+    # server.py redirects sys.stdout->stderr at load to protect the JSON-RPC channel,
+    # so write the marker via os.write(1, ...) and check both buffers (per test_boot_timing).
+    snippet = (
+        "import time, sys, os\n"
+        "t0 = time.monotonic_ns()\n"
+        "import meshcode.meshcode_mcp.server  # noqa: F401\n"
+        "elapsed_ms = (time.monotonic_ns() - t0) / 1_000_000\n"
+        "os.write(1, f'IMPORT_MS={elapsed_ms:.0f}\\n'.encode())\n"
+    )
+    try:
+        result = subprocess.run(
+            [sys.executable, "-c", snippet],
+            env=env, capture_output=True, text=True, timeout=30,
+        )
+    except subprocess.TimeoutExpired:
+        return {"check": "mcp_import", "ok": False, "detail": "import timed out >30s"}
+
+    elapsed_ms = None
+    for buf in (result.stdout, result.stderr):
+        for line in buf.splitlines():
+            if line.startswith("IMPORT_MS="):
+                try:
+                    elapsed_ms = float(line.split("=", 1)[1])
+                except ValueError:
+                    pass
+                break
+        if elapsed_ms is not None:
+            break
+
+    if result.returncode != 0 or elapsed_ms is None:
+        tail = "\n".join((result.stderr or result.stdout or "").splitlines()[-3:]).strip()
+        return {"check": "mcp_import", "ok": False,
+                "detail": f"import failed rc={result.returncode}: {tail or '(no output)'}"}
+
+    budget_ms = BOOT_IMPORT_BUDGET_S * 1000
+    ok = elapsed_ms < budget_ms
+    return {"check": "mcp_import", "ok": ok,
+            "detail": f"import {elapsed_ms:.0f}ms (budget {budget_ms:.0f}ms)"}
+
+
+def _check_doctor() -> dict:
+    """Live: doctor.run_doctor() reports no hard failures (warnings allowed)."""
+    try:
+        from meshcode.doctor import run_doctor
+        rc = run_doctor(skip_api_key_check=False, quiet=True)
+    except Exception as e:
+        return {"check": "doctor", "ok": False, "detail": f"run_doctor raised: {e}"}
+    return {"check": "doctor", "ok": rc == 0,
+            "detail": "no hard failures" if rc == 0 else f"run_doctor rc={rc} (a check failed)"}
+
+
+def _check_dry_run_launch(target: str) -> dict:
+    """Live: `meshcode run <target> --dry-run` exits 0 and prints DRY-RUN OK."""
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "meshcode", "run", target, "--dry-run"],
+            capture_output=True, text=True, timeout=60,
+        )
+    except subprocess.TimeoutExpired:
+        return {"check": "dry_run_launch", "ok": False, "detail": f"{target}: dry-run timed out >60s"}
+    blob = (result.stdout or "") + (result.stderr or "")
+    ok = result.returncode == 0 and "DRY-RUN OK" in blob
+    if ok:
+        detail = f"{target}: DRY-RUN OK"
+    else:
+        tail = "\n".join(blob.splitlines()[-3:]).strip()
+        detail = f"{target}: rc={result.returncode} {tail or '(no DRY-RUN OK marker)'}"
+    return {"check": "dry_run_launch", "ok": ok, "detail": detail}
+
+
+def run_smoke(live: bool = False, target: Optional[str] = None) -> dict:
+    """Run the smoke suite. Returns {ok, live, checks:[...]}.
+
+    Offline checks always run. `live` adds doctor + (if `target` resolvable) a
+    dry-run launch. `target` defaults to MESHCODE_PROJECT/MESHCODE_AGENT env when set.
+    """
+    checks = [_check_version_coherence(), _check_mcp_import()]
+
+    if live:
+        checks.append(_check_doctor())
+        tgt = target
+        if not tgt:
+            proj = (os.environ.get("MESHCODE_PROJECT") or "").strip()
+            agent = (os.environ.get("MESHCODE_AGENT") or "").strip()
+            if proj and agent:
+                tgt = f"{proj}/{agent}"
+        if tgt:
+            checks.append(_check_dry_run_launch(tgt))
+        else:
+            checks.append({"check": "dry_run_launch", "ok": True,
+                           "detail": "skipped (no target; pass project/agent or set MESHCODE_PROJECT+AGENT)"})
+
+    ok = all(c["ok"] for c in checks)
+    return {"ok": ok, "live": live, "checks": checks}
+
+
+def cmd_smoke(flags, pos) -> int:
+    """CLI entry: meshcode smoke [--live] [--json] [project/agent]."""
+    live = bool(flags.get("live")) or "--live" in sys.argv
+    json_out = bool(flags.get("json")) or "--json" in sys.argv
+    target = pos[0] if pos else None
+
+    report = run_smoke(live=live, target=target)
+
+    if json_out:
+        print(json.dumps(report))
+    else:
+        mark = {True: "PASS", False: "FAIL"}
+        print(f"\n  meshcode launch smoke — {'LIVE' if live else 'offline'} subset\n")
+        for c in report["checks"]:
+            print(f"    [{mark[c['ok']]}] {c['check']:<18} {c['detail']}")
+        print()
+        print(f"  {'ALL CHECKS PASS' if report['ok'] else 'SMOKE FAILED'}\n")
+
+    return 0 if report["ok"] else 1
+
+
+if __name__ == "__main__":
+    # Allow `python -m meshcode._launch_smoke [--live] [--json] [target]`.
+    _flags = {a.lstrip("-"): True for a in sys.argv[1:] if a.startswith("--")}
+    _pos = [a for a in sys.argv[1:] if not a.startswith("--")]
+    sys.exit(cmd_smoke(_flags, _pos))

meshcode-2.11.154/meshcode/_update_guard.py

@@ -0,0 +1,175 @@
+"""Runtime update-guard — Layer 3 of Launch Regression Armor (task 2e85c6a8).
+
+Gates the two seams where meshcode adopts a NEW on-disk version at runtime — the
+freshly built immutable env (self_update.ensure_versioned_env) and the hostd
+version-drift restart — on the L1 golden smoke run against the CANDIDATE env. A
+candidate that fails launch smoke is, under enforce, refused: the known-good version
+keeps running and every mesh commander is alerted.
+
+    MESHCODE_UPDATE_GUARD = off | dry_run | enforce   (default: off)
+
+      off     guard_blocks_candidate() is always False — ZERO behavior change.
+              Ship dark, flip to dry_run via config (no recut).
+      dry_run smoke runs; a failing candidate is LOGGED + alerted (mode=dry_run),
+              but guard_blocks_candidate() returns False (caller proceeds). Pure
+              observability — the rollout step before enforce.
+      enforce a failing candidate makes guard_blocks_candidate() return True.
+
+Hard invariants:
+  * NEVER raises into a caller. Any internal error -> allow (fail-open) so a guard
+    bug can never wedge a launch.
+  * A candidate that predates the `meshcode smoke` verb (no parseable verdict) ->
+    fail-open (allow) — the guard only enforces what it can actually measure.
+  * Results are TTL-cached per candidate version so a hot caller (hostd's sweep
+    loop) doesn't re-run smoke every cycle.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from typing import List, Optional, Tuple
+
+_VALID_MODES = ("off", "dry_run", "enforce")
+_SMOKE_TIMEOUT_S = 90
+_CACHE_TTL_S = 300.0
+# {to_version: (monotonic_ts, smoke_ok_or_None, failures)}
+_CACHE: dict = {}
+
+
+def guard_mode() -> str:
+    m = (os.environ.get("MESHCODE_UPDATE_GUARD") or "off").strip().lower()
+    return m if m in _VALID_MODES else "off"
+
+
+def _log(msg: str) -> None:
+    try:
+        print(f"[meshcode][update-guard] {msg}", file=sys.stderr)
+    except Exception:
+        pass
+
+
+def _run_smoke(candidate_py: str) -> Tuple[Optional[bool], List[str]]:
+    """Run `<candidate_py> -m meshcode smoke --json` from a SCRATCH cwd.
+
+    Scratch cwd is mandatory: running from a source/checkout tree makes the smoke's
+    version_coherence read the repo's stale egg-info metadata and false-fail (the
+    documented egg-info-shadow trap). Returns (ok, failures); ok is None when the
+    harness could not produce a verdict (treated as fail-open by the caller).
+    """
+    scratch = None
+    try:
+        scratch = tempfile.mkdtemp(prefix="mc-smoke-")
+    except Exception:
+        scratch = None
+    try:
+        r = subprocess.run(
+            [candidate_py, "-m", "meshcode", "smoke", "--json"],
+            capture_output=True, text=True, timeout=_SMOKE_TIMEOUT_S,
+            cwd=scratch or None,
+        )
+    except Exception:
+        return None, []  # couldn't run -> no verdict -> fail-open
+    finally:
+        if scratch:
+            try:
+                import shutil
+                shutil.rmtree(scratch, ignore_errors=True)
+            except Exception:
+                pass
+
+    report = None
+    for line in reversed((r.stdout or "").splitlines()):
+        line = line.strip()
+        if line.startswith("{"):
+            try:
+                report = json.loads(line)
+                break
+            except Exception:
+                continue
+    if not isinstance(report, dict) or "ok" not in report:
+        return None, []  # candidate has no smoke verb / unparseable -> fail-open
+    failures = [f"{c.get('check')}: {c.get('detail')}"
+                for c in report.get("checks", []) if not c.get("ok")]
+    return bool(report["ok"]), failures
+
+
+def _cached_smoke(to_version: str, candidate_py: str) -> Tuple[Optional[bool], List[str]]:
+    now = time.monotonic()
+    hit = _CACHE.get(to_version)
+    if hit and (now - hit[0]) < _CACHE_TTL_S:
+        return hit[1], hit[2]
+    ok, failures = _run_smoke(candidate_py)
+    _CACHE[to_version] = (now, ok, failures)
+    return ok, failures
+
+
+def _emit_alert(mode: str, from_version: str, to_version: str,
+                failures: List[str], context: str) -> None:
+    """Best-effort in-mesh alert (type version_guard_block) to mesh-commander.
+
+    Cross-mesh fan-out to EVERY mesh commander (Samuel "TODOS los commanders", Q3) is
+    the commander/server piece (pending the mc_alert_all_commanders-vs-iterate
+    decision). Here we always LOG (the durable DRY-RUN telemetry signal) and
+    best-effort send the in-mesh report — creds may be absent in a hostd context, in
+    which case the log line is the record.
+    """
+    payload = {
+        "type": "version_guard_block", "mode": mode,
+        "from_version": from_version, "to_version": to_version,
+        "reason": "smoke_fail", "smoke_failures": failures[:6], "context": context,
+    }
+    _log(f"ALERT version_guard_block mode={mode} {from_version}->{to_version} "
+         f"context={context} failures={failures[:3]}")
+    agent = os.environ.get("MESHCODE_AGENT") or "hostd"
+    try:
+        from meshcode import backend as _be
+        proj = os.environ.get("MESHCODE_PROJECT") or ""
+        if proj:
+            _be.send_message(proj, agent, "mesh-commander", payload, msg_type="report")
+        # Cross-mesh fan-out to EVERY mesh commander (Q3, Samuel "TODOS los
+        # commanders"). database task 0cdc6646: mc_alert_all_commanders enumerates
+        # the commander of each ACTIVE-linked mesh + the local one. Best-effort —
+        # needs an agent api key (may be absent in a bare hostd ctx); the in-mesh
+        # report + log above are the fallback signal.
+        _key = os.environ.get("MESHCODE_API_KEY") or ""
+        if _key:
+            _be.sb_rpc("mc_alert_all_commanders", {
+                "p_api_key": _key,
+                "p_payload": payload,
+                "p_from_agent": agent,
+                "p_type": "version_guard_block",
+            })
+    except Exception:
+        pass  # best-effort; the log line above is the durable signal
+
+
+def guard_blocks_candidate(candidate_py: str, *, to_version: str,
+                           from_version: str = "?", context: str = "") -> bool:
+    """Return True iff the caller MUST refuse this candidate version.
+
+    True only when mode==enforce AND smoke gives a definitive ok==False. off ->
+    False without running smoke. dry_run -> runs smoke + alerts on failure but
+    returns False. Fail-open on any ambiguity (no verdict / internal error).
+    """
+    try:
+        mode = guard_mode()
+        if mode == "off":
+            return False
+        ok, failures = _cached_smoke(to_version, candidate_py)
+        if ok is None:
+            _log(f"no smoke verdict for {to_version} (context={context}) -> fail-open (allow)")
+            return False
+        if ok:
+            return False
+        _emit_alert(mode, from_version, to_version, failures, context)
+        if mode == "enforce":
+            _log(f"BLOCK {from_version}->{to_version} (context={context}); keeping known-good.")
+            return True
+        _log(f"DRY-RUN would-block {from_version}->{to_version} (context={context}); proceeding.")
+        return False
+    except Exception:
+        return False  # the guard must NEVER wedge a caller

{meshcode-2.11.152 → meshcode-2.11.154}/meshcode/comms_v4.py

@@ -3322,21 +3322,31 @@ if __name__ == "__main__":
 
     elif cmd in ("kill", "wake", "sleep"):
         # meshcode kill|wake|sleep <project> <agent>
+        # F3 (task f54a0c30): the old mc_agent_kill(p_project_id,p_agent_name) carried
+        # NO p_api_key, so it could not authenticate the OWNER -> "Permission denied".
+        # Route through the api-key-authenticated power RPC (mig581
+        # mc_agent_power_by_api_key) so the caller's key proves ownership.
+        # kill/sleep -> desired_state='stopped'; wake -> 'running' (+restart).
         proj = pos[0] if len(pos) > 0 else "default"
         name = pos[1] if len(pos) > 1 else ""
         if not name:
             print(f"[meshcode] ERROR: Usage: meshcode {cmd} <project> <agent>")
             sys.exit(1)
-        project_id = get_project_id(proj)
-        if not project_id:
-            print(f"[meshcode] ERROR: project '{proj}' not found")
+        _ak = _load_api_key_for_cli()
+        if not _ak:
+            print("[meshcode] ERROR: not logged in (run: meshcode login <api_key>)")
             sys.exit(1)
-        rpc_name = {"kill": "mc_agent_kill", "wake": "mc_agent_wake", "sleep": "mc_agent_sleep"}[cmd]
-        result = sb_rpc(rpc_name, {"p_project_id": project_id, "p_agent_name": name})
-        if result and result.get("error"):
-            print(f"[meshcode] ERROR: {result['error']}")
+        _state = "running" if cmd == "wake" else "stopped"
+        _params = {"p_api_key": _ak, "p_project": proj, "p_agent": name, "p_state": _state}
+        if cmd == "wake":
+            _params["p_restart"] = True
+        result = sb_rpc("mc_agent_power_by_api_key", _params)
+        if not isinstance(result, dict) or result.get("error") or not result.get("ok", True):
+            _msg = ((result or {}).get("error") or (result or {}).get("detail") or "unknown error") \
+                if isinstance(result, dict) else "no response from server"
+            print(f"[meshcode] ERROR: {cmd} failed: {_msg}")
             sys.exit(1)
-        print(f"[{proj}] {name}: {cmd} → {json.dumps(result, ensure_ascii=False)}")
+        print(f"[{proj}] {name}: {cmd} → desired_state={_state}")
 
     elif cmd == "profile":
         # meshcode profile get|set <project> <agent> [--color X --display-name Y --role Z --launch-prompt P]
@@ -3404,7 +3414,7 @@ if __name__ == "__main__":
             proj, base = base.split("/", 1)
         if not base:
             print("[meshcode] ERROR: usage: meshcode replicate <agent> --count N "
-                  "[--project <name>] [--no-launch]")
+                  "[--project <name>] [--no-launch] [--mode copilotos|independientes]")
             sys.exit(1)
         try:
             count = int(flags.get("count", pos[1] if len(pos) > 1 else 0))
@@ -3414,6 +3424,14 @@ if __name__ == "__main__":
             print("[meshcode] ERROR: --count must be an integer in 1..16")
             sys.exit(1)
         desired = None if flags.get("no-launch") else "running"
+        # p_mode (task 986947b5): copilotos = shared swarm_id (coordinate via one tray) |
+        # independientes = distinct swarm_id per replica (isolated). Default copilotos
+        # (Samuel's canonical spec). DB mig586 honors it on both overloads.
+        mode = str(flags.get("mode", "copilotos")).lower()
+        if mode not in ("copilotos", "independientes"):
+            print("[meshcode] ERROR: --mode must be 'copilotos' (shared/coordinate) or "
+                  "'independientes' (isolated)")
+            sys.exit(1)
         res = sb_rpc("mc_replicate_agent", {
             "p_api_key": _ak,
             "p_base_agent": base,
@@ -3421,10 +3439,25 @@ if __name__ == "__main__":
             "p_project": proj,
             "p_desired_state": desired,
             "p_replica_group_id": flags.get("group"),
+            "p_mode": mode,
         })
         if not isinstance(res, dict) or res.get("error") or not res.get("ok", True):
-            _err = (res or {}).get("error", "unknown") if isinstance(res, dict) else "no response"
-            print(f"[meshcode] ERROR: replicate failed: {_err}")
+            # F1 (task f54a0c30): the RPC puts the actionable text in `detail` /
+            # `error_code`, but the old handler read only `error` -> "unknown".
+            # Surface error_code + detail, with a concrete fix for ambiguous_project.
+            if not isinstance(res, dict):
+                print("[meshcode] ERROR: replicate failed: no response from server")
+            elif res.get("error_code") == "ambiguous_project":
+                print(f"[meshcode] ERROR: replicate: base agent '{base}' exists in "
+                      f"multiple projects — disambiguate with:")
+                print(f"    meshcode replicate <project>/{base} --count {count}"
+                      + ("" if desired == "running" else " --no-launch")
+                      + "   (or pass --project <name>)")
+            else:
+                _ec = res.get("error_code")
+                _msg = res.get("error") or res.get("detail") or "unknown error"
+                print("[meshcode] ERROR: replicate failed"
+                      + (f" [{_ec}]" if _ec else "") + f": {_msg}")
             sys.exit(1)
         created = res.get("created") or []
         print(f"[meshcode] Replicated {base} → {len(created)} replica(s) "
@@ -3994,6 +4027,15 @@ if __name__ == "__main__":
     elif cmd == "doctor":
         cmd_doctor(flags, pos)
 
+    elif cmd == "smoke":
+        # Golden launch smoke (Layer 1 of launch-armor, task 2e85c6a8).
+        # Offline subset (version coherence + mcp import) uses no backend; --live
+        # adds doctor + dry-run launch. The Layer-2 CI gate and Layer-3 runtime
+        # update-guard invoke this against a fresh wheel / on-disk env.
+        import importlib
+        _smoke = importlib.import_module("meshcode._launch_smoke")
+        sys.exit(_smoke.cmd_smoke(flags, pos))
+
     elif cmd == "quickstart":
         import importlib
         _qs = importlib.import_module("meshcode.quickstart")