meshcode 2.11.8__tar.gz → 2.11.10__tar.gz

{meshcode-2.11.8 → meshcode-2.11.10}/PKG-INFO

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

{meshcode-2.11.8 → meshcode-2.11.10}/meshcode/__init__.py

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

{meshcode-2.11.8 → meshcode-2.11.10}/meshcode/comms_v4.py

@@ -2143,6 +2143,30 @@ def cmd_doctor(flags, pos):
     except Exception as e:
         fail("MCP server", f"import error: {e}. Run: pip install --upgrade meshcode")
 
+    # 4d. Env checks (B2 + B9): Python stub, SSL, PATH, Claude, Node, git, prefs
+    try:
+        from meshcode.doctor import CHECKS as _env_checks
+        # Skip ones cmd_doctor already covered (python version, api key)
+        from meshcode.doctor import (
+            _check_python,
+            _check_api_key,
+            _check_meshcode_on_path,  # cmd_doctor doesn't check this
+        )
+        _seen = set()
+        for _fn in _env_checks:
+            if _fn in (_check_python, _check_api_key):
+                continue
+            try:
+                _lvl, _title, _detail = _fn()
+                if _title in _seen:
+                    continue
+                _seen.add(_title)
+                {"ok": ok, "warn": warn, "fail": fail}[_lvl](_title, _detail)
+            except Exception as _e:
+                warn(_fn.__name__.lstrip("_"), f"check crashed: {_e}")
+    except ImportError:
+        pass  # doctor module not available (legacy install)
+
     # 5. Stale agents check (requires auth)
     if api_key:
         try:
@@ -2745,8 +2769,33 @@ if __name__ == "__main__":
         print("  " + "=" * 40)
         print()
 
-        # Try device-code pairing first
-        pairing = sb_rpc("mc_create_pairing_session", {})
+        # B2 pre-flight: refuse to onboard if env is broken
+        from meshcode.doctor import run_doctor
+        if run_doctor(skip_api_key_check=True) != 0:
+            print()
+            print("  [meshcode] Fix the blocker(s) above, then run `meshcode init` again.")
+            sys.exit(1)
+        print()
+
+        # B3: wrap pairing RPC so SSL / network errors abort cleanly (no
+        # silent fall-through to API-key paste — friction #7).
+        try:
+            pairing = sb_rpc("mc_create_pairing_session", {})
+        except Exception as _init_e:
+            _msg = str(_init_e).lower()
+            if "certificate" in _msg or "ssl" in _msg:
+                print()
+                print("  [meshcode] SSL certificate verification failed.")
+                print("  [meshcode] This usually means your Python install is missing root certs.")
+                _v = sys.version_info
+                print(f"  [meshcode] Fix: run /Applications/Python\\ {_v.major}.{_v.minor}/Install\\ Certificates.command")
+                print(f"  [meshcode] (Replace {_v.major}.{_v.minor} with your actual installed version.)")
+                print(f"  [meshcode] Alternative: pip install --upgrade certifi")
+            else:
+                print()
+                print(f"  [meshcode] Pairing service unreachable: {_init_e}")
+                print(f"  [meshcode] Check your network, then re-run `meshcode init`.")
+            sys.exit(1)
         if pairing and isinstance(pairing, dict) and pairing.get("ok"):
             session_id = pairing["session_id"]
             code = pairing["code"]
@@ -3397,11 +3446,16 @@ if __name__ == "__main__":
             from meshcode.preferences import load_prefs, save_prefs
             if len(sys.argv) > 3:
                 ver = sys.argv[3].strip()
-                if ver in ("reset", "unpin", "latest"):
+                if ver in ("reset", "unpin"):
                     prefs = load_prefs()
                     prefs.pop("claude_version", None)
                     save_prefs(prefs)
-                    print("[meshcode] Claude Code version pin removed — will use installed version")
+                    print("[meshcode] Claude Code version pin removed — will use default ESC-safe pin")
+                elif ver in ("latest", "none", "skip"):
+                    prefs = load_prefs()
+                    prefs["claude_version"] = ver
+                    save_prefs(prefs)
+                    print(f"[meshcode] Claude Code version pinning disabled ({ver}) — using installed version")
                 else:
                     prefs = load_prefs()
                     prefs["claude_version"] = ver

meshcode-2.11.10/meshcode/doctor.py

@@ -0,0 +1,277 @@
+"""Pre-flight environment checks. `meshcode doctor` runs all and reports.
+
+Each check returns (level, title, detail):
+  level: "ok" | "warn" | "fail"
+  title: short identifier shown to user
+  detail: actionable fix when not OK ("" when OK)
+
+Exit code: 1 if any "fail", else 0 (warnings allowed).
+
+Covers frictions #4 Python stub, #5 SSL certs, #8 PATH, #10 git/CLT modal,
+#11 Claude not installed. Used as pre-flight by `meshcode init`.
+"""
+import os
+import sys
+import json
+import shutil
+import subprocess
+import urllib.request
+import urllib.error
+from typing import List, Tuple
+
+Status = Tuple[str, str, str]
+
+_HEALTH_URL = "https://meshcode.io/health"
+_SUPABASE_URL = "https://supabase.co"
+
+
+def _check_python() -> Status:
+    v = sys.version_info
+    if (v.major, v.minor) < (3, 9):
+        return (
+            "fail",
+            f"Python {v.major}.{v.minor}.{v.micro}",
+            "need Python >=3.9; install from python.org or `brew install python@3.13`",
+        )
+    # macOS Apple-stub detection: importing ssl on the stub fails
+    if sys.platform == "darwin":
+        try:
+            import ssl
+
+            _ = ssl.OPENSSL_VERSION
+        except Exception as e:
+            return (
+                "fail",
+                f"Python {v.major}.{v.minor}.{v.micro}",
+                f"Apple stub Python detected (ssl import failed: {e}). "
+                f"Install real Python: https://www.python.org/downloads/",
+            )
+    return ("ok", f"Python {v.major}.{v.minor}.{v.micro}", "")
+
+
+def _check_ssl() -> Status:
+    try:
+        urllib.request.urlopen(_HEALTH_URL, timeout=5).read(64)
+        return ("ok", "SSL certs", "")
+    except urllib.error.URLError as e:
+        msg = str(e).lower()
+        if "certificate" in msg or "ssl" in msg:
+            fix = (
+                "run python's Install Certificates.command "
+                "(/Applications/Python <ver>/Install Certificates.command) "
+                "OR `pip install --upgrade certifi`"
+            )
+            return ("fail", "SSL certs", fix)
+        return ("warn", "SSL certs", f"network unreachable (skip if offline): {e}")
+    except Exception as e:
+        return ("warn", "SSL certs", f"check inconclusive: {e}")
+
+
+def _check_meshcode_on_path() -> Status:
+    for tool in ("meshcode", "meshcode-mcp"):
+        if not shutil.which(tool):
+            v = sys.version_info
+            if sys.platform == "darwin":
+                hint = (
+                    f'export PATH="$HOME/Library/Python/{v.major}.{v.minor}/bin:$PATH" '
+                    f'(or run: python3 -m meshcode setup-path)'
+                )
+            else:
+                hint = (
+                    "add Python user-base bin to PATH "
+                    "(python3 -m site --user-base)/bin "
+                    "or run: python3 -m meshcode setup-path"
+                )
+            return ("fail", f"`{tool}` on PATH", hint)
+    return ("ok", "meshcode CLI on PATH", "")
+
+
+def _check_claude() -> Status:
+    if shutil.which("claude"):
+        return ("ok", "Claude Code installed", "")
+    return (
+        "fail",
+        "Claude Code installed",
+        "install from https://claude.ai/install "
+        "or `npm i -g @anthropic-ai/claude-code`",
+    )
+
+
+def _check_node() -> Status:
+    needs_node = False
+    try:
+        from meshcode.preferences import load_prefs
+
+        cv = (load_prefs().get("claude_version") or "").lower()
+        if cv and cv not in ("latest", "none", "skip"):
+            needs_node = True
+    except Exception:
+        pass
+    if os.environ.get("MESHCODE_USE_NPX"):
+        needs_node = True
+    has_node = bool(shutil.which("node"))
+    has_npx = bool(shutil.which("npx"))
+    if has_node and has_npx:
+        return ("ok", "Node/npx", "")
+    level = "fail" if needs_node else "warn"
+    detail = (
+        "install Node: https://nodejs.org or `brew install node`"
+        if needs_node
+        else "only needed for `claude_version` pin or MESHCODE_USE_NPX; safe to skip"
+    )
+    return (level, "Node/npx", detail)
+
+
+def _check_git() -> Status:
+    """git pre-flight with Apple stub detection + safe workarounds (B9)."""
+    git = shutil.which("git")
+    if not git:
+        return (
+            "fail",
+            "git",
+            "git not installed. Recommended (skip Apple's brittle modal):\n"
+            "    - Manual CLT download: https://developer.apple.com/download/all/?q=command%20line%20tools\n"
+            "    - OR Git for Mac: https://git-scm.com/download/mac\n"
+            "    - OR `brew install git` (if Homebrew is installed)",
+        )
+    if sys.platform == "darwin":
+        try:
+            r = subprocess.run(
+                [git, "--version"],
+                capture_output=True,
+                text=True,
+                timeout=3,
+            )
+            stderr_lower = (r.stderr or "").lower()
+            if (
+                r.returncode != 0
+                or "command line developer tools" in stderr_lower
+            ):
+                return (
+                    "fail",
+                    "git",
+                    "Apple stub git detected (would trigger CLT install modal). "
+                    "Install real git: "
+                    "https://developer.apple.com/download/all/?q=command%20line%20tools "
+                    "OR `brew install git` OR https://git-scm.com/download/mac",
+                )
+        except subprocess.TimeoutExpired:
+            return (
+                "fail",
+                "git",
+                "git subprocess hung — likely the CLT install modal is "
+                "blocked or pending. Cancel any open Apple dialog; install "
+                "git manually: https://git-scm.com/download/mac",
+            )
+        except Exception:
+            pass
+    return ("ok", "git", "")
+
+
+def _check_network() -> Status:
+    for url in (_HEALTH_URL, _SUPABASE_URL):
+        try:
+            urllib.request.urlopen(url, timeout=5).read(64)
+        except Exception as e:
+            return (
+                "warn",
+                "Network reachability",
+                f"{url} unreachable ({type(e).__name__}); "
+                f"check VPN/firewall if persistent",
+            )
+    return ("ok", "Network reachability", "")
+
+
+def _check_api_key() -> Status:
+    try:
+        from meshcode.secrets import get_api_key, list_profiles
+
+        profiles = list_profiles() or []
+        if not profiles:
+            return (
+                "warn",
+                "API key in keychain",
+                "no profiles — run `meshcode init` to pair and store one",
+            )
+        for p in profiles:
+            if get_api_key(profile=p):
+                return ("ok", f"API key (profile={p})", "")
+        return (
+            "warn",
+            "API key in keychain",
+            f"profiles exist ({profiles}) but no key retrievable — "
+            f"`meshcode init` to re-pair",
+        )
+    except Exception as e:
+        return ("warn", "API key in keychain", f"secrets module unavailable: {e}")
+
+
+def _check_prefs_json() -> Status:
+    pref = os.path.expanduser("~/.meshcode/preferences.json")
+    if not os.path.exists(pref):
+        return ("ok", "preferences.json", "(not created yet — default fine)")
+    try:
+        with open(pref) as f:
+            json.load(f)
+        return ("ok", "preferences.json", "")
+    except json.JSONDecodeError as e:
+        return (
+            "fail",
+            "preferences.json",
+            f"corrupt JSON ({e}); delete or fix: {pref}",
+        )
+    except Exception as e:
+        return ("warn", "preferences.json", f"unreadable: {e}")
+
+
+CHECKS = [
+    _check_python,
+    _check_ssl,
+    _check_meshcode_on_path,
+    _check_claude,
+    _check_node,
+    _check_git,
+    _check_network,
+    _check_api_key,
+    _check_prefs_json,
+]
+
+
+def run_doctor(skip_api_key_check: bool = False, quiet: bool = False) -> int:
+    """Run all checks, print results, return exit code (0 ok/warn, 1 fail)."""
+    results: List[Status] = []
+    for fn in CHECKS:
+        if skip_api_key_check and fn is _check_api_key:
+            continue
+        try:
+            results.append(fn())
+        except Exception as e:
+            results.append(("fail", fn.__name__.lstrip("_"), f"check crashed: {e}"))
+    blockers = 0
+    if not quiet:
+        print()
+        print("  meshcode doctor — environment check")
+        print("  " + "=" * 40)
+    for level, title, detail in results:
+        sym = {"ok": "✓", "warn": "⚠", "fail": "✗"}[level]
+        if level == "fail":
+            blockers += 1
+        line = f"  {sym} {title}"
+        if detail:
+            line += f" — {detail}"
+        if not quiet:
+            print(line)
+    if not quiet:
+        print()
+        if blockers:
+            print(
+                f"  {blockers} blocker(s) found — fix the above "
+                f"before `meshcode init`/`go`."
+            )
+        else:
+            print("  All checks passed (warnings non-blocking).")
+    return 1 if blockers else 0
+
+
+if __name__ == "__main__":
+    sys.exit(run_doctor())

{meshcode-2.11.8 → meshcode-2.11.10}/meshcode/meshcode_mcp/server.py

@@ -1699,61 +1699,109 @@ def _snapshot_pkg_mtimes():
 _PKG_PY_MTIMES = _snapshot_pkg_mtimes()
 log.info(f"install-guard: snapshotted {len(_PKG_PY_MTIMES)} *.py mtimes under {_PKG_DIR}")
 
+_INSTALL_GUARD_MODE = os.environ.get("MESHCODE_INSTALL_GUARD", "warn").lower()
+if _INSTALL_GUARD_MODE not in ("execv", "warn", "off"):
+    log.warning(f"MESHCODE_INSTALL_GUARD={_INSTALL_GUARD_MODE!r} invalid; falling back to 'warn'")
+    _INSTALL_GUARD_MODE = "warn"
+_INSTALL_GUARD_STALE_NOTIFIED = False
+
+
+def _is_agent_active() -> bool:
+    """True if agent should NOT be execv-restarted right now."""
+    if os.environ.get("MESHCODE_AGENT_ACTIVE", "").lower() in ("1", "true", "yes"):
+        return True
+    if _IN_WAIT:
+        return True
+    try:
+        if (_time.time() - _last_tool_at) < 300:
+            return True
+    except Exception:
+        pass
+    return False
+
 
 def _install_guard_check() -> None:
-    """Heartbeat-tick scan: if any *.py under the meshcode pkg path has
-    a fresher mtime than recorded at boot, the env was reinstalled while
-    the process is alive (class feedback_pip_install_into_live_mcp_env_self_kill).
-    The running image holds stale bytecode; lockfile collision and
-    orphan-watchdog will eventually kill us anyway. Pre-empt: release the
-    lease and execv-restart so the new wheel is picked up cleanly.
-
-    The MCP socket to Claude Code WILL drop during the exec window.
-    Stop_hook _mcp_disconnected_without_reconnect (mig 68a3545e) catches
-    it; user runs `meshcode go <agent>` to pick up the new wheel.
-
-    Soft-fail throughout: any exception here is logged and swallowed so
-    the heartbeat thread isn't taken down by a flaky filesystem call.
+    """Heartbeat-tick scan: detect mid-session pkg reinstall.
+
+    Modes (MESHCODE_INSTALL_GUARD env var):
+      - 'warn' (default): log + one-shot boot_version_drift msg; never execv.
+        New wheel picked up on next cold boot. Removes mid-session surprise drops
+        (RC of task 0c4524af 2026-05-19: pip install over live 2.11.7 sessions
+        triggered execv on both backend+commander hb tick, dropping MCP socket).
+      - 'execv': legacy auto-restart. Deferred to warn-mode when agent is active
+        (in_wait, recent tool call <5min, or MESHCODE_AGENT_ACTIVE=1).
+      - 'off': skip scan entirely.
+
+    Soft-fail throughout.
     """
-    if not _PKG_PY_MTIMES:
+    global _INSTALL_GUARD_STALE_NOTIFIED
+    if _INSTALL_GUARD_MODE == "off" or not _PKG_PY_MTIMES:
         return
     try:
+        stale_path = None
+        old_m = new_m = 0.0
         for path, old_mtime in list(_PKG_PY_MTIMES.items()):
             try:
                 new_mtime = os.path.getmtime(path)
             except OSError:
                 continue
-            # 0.5s slack — covers fs-timestamp resolution and tar extract
-            # re-emit jitter without false-positive on intentional touch.
             if new_mtime <= old_mtime + 0.5:
                 continue
+            stale_path = path
+            old_m, new_m = old_mtime, new_mtime
+            break
+        if not stale_path:
+            return
+        if _INSTALL_GUARD_MODE == "execv" and not _is_agent_active():
             log.warning(
-                f"install-guard: self-modification detected on {path} "
-                f"(mtime {old_mtime:.0f} → {new_mtime:.0f}). The running "
-                f"image holds stale bytecode; triggering clean execv-restart "
-                f"so the new wheel is picked up. MCP socket will drop briefly "
-                f"— stop_hook handles the agent release (mig 68a3545e). User "
-                f"runs `meshcode go <agent>` to relaunch under the new image. "
-                f"Class: feedback_pip_install_into_live_mcp_env_self_kill."
+                f"install-guard: self-modification on {stale_path} "
+                f"(mtime {old_m:.0f} -> {new_m:.0f}). Mode=execv, agent inactive "
+                f"-- execv-restart. MCP socket will drop; stop_hook handles release."
             )
             try:
                 _release_lease_synchronous(timeout_s=1.5)
             except Exception:
                 pass
             _heartbeat_stop.set()
-            # execv replaces the current process; daemon threads die with
-            # it; new process inherits stdio. We pass the original argv so
-            # the entry-point command line is preserved verbatim.
             try:
                 os.execv(sys.executable, [sys.executable] + sys.argv)
             except Exception as _exec_err:
-                log.error(
-                    f"install-guard execv failed ({_exec_err}); "
-                    f"falling back to os._exit(0). Lifespan finally + "
-                    f"stop_hook still recover."
-                )
+                log.error(f"install-guard execv failed ({_exec_err}); os._exit(0)")
                 os._exit(0)
-            return  # unreachable but explicit
+            return
+        if not _INSTALL_GUARD_STALE_NOTIFIED:
+            _INSTALL_GUARD_STALE_NOTIFIED = True
+            log.warning(
+                f"install-guard: self-modification on {stale_path} "
+                f"(mtime {old_m:.0f} -> {new_m:.0f}). Mode={_INSTALL_GUARD_MODE}, "
+                f"agent_active={_is_agent_active()}. Running on STALE image -- new wheel "
+                f"picked up on next `meshcode go <agent>` cold boot. "
+                f"Set MESHCODE_INSTALL_GUARD=execv to opt into auto-restart."
+            )
+            try:
+                import threading as _t
+                def _notify():
+                    try:
+                        be.send_message(
+                            _PROJECT_ID, AGENT_NAME, "mesh-commander",
+                            {
+                                "type": "boot_version_drift",
+                                "subtype": "mid_session_stale_image",
+                                "path": stale_path,
+                                "old_mtime": old_m,
+                                "new_mtime": new_m,
+                                "agent": AGENT_NAME,
+                                "platform": sys.platform,
+                                "loaded_version": _SDK_VERSION,
+                            },
+                            msg_type="report",
+                            api_key=_get_api_key(),
+                        )
+                    except Exception as _e:
+                        log.debug(f"boot_version_drift notify failed (soft): {_e}")
+                _t.Thread(target=_notify, daemon=True, name="meshcode-install-guard-notify").start()
+            except Exception:
+                pass
     except Exception as e:
         log.debug(f"install-guard scan failed (soft): {e}")
 

meshcode-2.11.10/meshcode/meshcode_mcp/test_install_guard.py

@@ -0,0 +1,75 @@
+"""Unit tests for the install-guard heartbeat scan.
+
+RC for task 0c4524af (2026-05-19): pip install over live 2.11.7 sessions
+triggered execv on both backend+commander hb tick, dropping MCP socket.
+Fix (task d7df438e): default mode is 'warn' — log + one-shot notify, never
+execv mid-session. Legacy execv path preserved as opt-in (MESHCODE_INSTALL_GUARD=execv)
+and further deferred when agent is active.
+
+Server module requires MESHCODE_PROJECT and MESHCODE_AGENT at import time
+(L616-621). MESHCODE_PROJECT_ID short-circuits the network resolve path.
+"""
+import os
+
+os.environ.setdefault("MESHCODE_PROJECT", "test-install-guard")
+os.environ.setdefault("MESHCODE_AGENT", "test-agent")
+os.environ.setdefault("MESHCODE_PROJECT_ID", "00000000-0000-0000-0000-000000000000")
+os.environ.setdefault("MESHCODE_API_KEY", "mc_test_fake_key_not_used")
+
+import time
+import pytest
+from unittest import mock
+from meshcode.meshcode_mcp import server as srv
+
+
+@pytest.fixture
+def stale_setup(monkeypatch, tmp_path):
+    fake = tmp_path / "fake_pkg.py"
+    fake.write_text("# stale")
+    old = fake.stat().st_mtime
+    monkeypatch.setattr(srv, "_PKG_PY_MTIMES", {str(fake): old - 100.0})
+    monkeypatch.setattr(srv, "_INSTALL_GUARD_STALE_NOTIFIED", False)
+    return fake
+
+
+def test_default_warn_no_execv(stale_setup, monkeypatch):
+    monkeypatch.setattr(srv, "_INSTALL_GUARD_MODE", "warn")
+    with mock.patch.object(os, "execv") as me, mock.patch.object(os, "_exit") as mex:
+        srv._install_guard_check()
+    assert not me.called and not mex.called
+
+
+def test_off_skips(stale_setup, monkeypatch):
+    monkeypatch.setattr(srv, "_INSTALL_GUARD_MODE", "off")
+    with mock.patch.object(os, "execv") as me:
+        srv._install_guard_check()
+    assert not me.called
+
+
+def test_execv_inactive_fires(stale_setup, monkeypatch):
+    monkeypatch.setattr(srv, "_INSTALL_GUARD_MODE", "execv")
+    monkeypatch.setattr(srv, "_IN_WAIT", False)
+    monkeypatch.setattr(srv, "_last_tool_at", 0.0)
+    monkeypatch.delenv("MESHCODE_AGENT_ACTIVE", raising=False)
+    with mock.patch.object(os, "execv") as me, \
+         mock.patch.object(srv, "_release_lease_synchronous", create=True):
+        srv._install_guard_check()
+    assert me.called
+
+
+def test_execv_active_defers(stale_setup, monkeypatch):
+    monkeypatch.setattr(srv, "_INSTALL_GUARD_MODE", "execv")
+    monkeypatch.setattr(srv, "_IN_WAIT", True)
+    with mock.patch.object(os, "execv") as me:
+        srv._install_guard_check()
+    assert not me.called
+
+
+def test_one_shot_notify(stale_setup, monkeypatch):
+    monkeypatch.setattr(srv, "_INSTALL_GUARD_MODE", "warn")
+    sends = []
+    monkeypatch.setattr(srv.be, "send_message", lambda *a, **kw: sends.append((a, kw)))
+    srv._install_guard_check(); time.sleep(0.3)
+    n1 = len(sends)
+    srv._install_guard_check(); time.sleep(0.3)
+    assert len(sends) == n1, "second call must not duplicate notify"

meshcode-2.11.10/meshcode/meshcode_mcp/test_prefs_claude_version.py

@@ -0,0 +1,82 @@
+"""Regression test for B1 (task f1d34641) — friction #9.
+
+`meshcode prefs claude-version latest` must save "latest" literally instead
+of deleting the key. The disable sentinel "latest"/"none"/"skip" is read at
+run_agent.py:475 to skip the ESC pin; if the CLI deletes the key, the user
+falls back to the hardcoded 2.1.104 pin → npx fails for users without Node.
+
+Bug location: comms_v4.py:3396-3416 (pre-fix grouped `latest` with
+`reset`/`unpin` and popped the key).
+"""
+import json
+import os
+
+os.environ.setdefault("MESHCODE_PROJECT", "test-prefs-b1")
+os.environ.setdefault("MESHCODE_AGENT", "test-agent")
+
+import pytest
+
+
+@pytest.fixture
+def isolated_prefs(tmp_path, monkeypatch):
+    pref_file = tmp_path / "preferences.json"
+    from meshcode import preferences
+    monkeypatch.setattr(preferences, "PREFS_PATH", pref_file)
+    return pref_file
+
+
+def _apply_branch(ver: str):
+    """Mirror the post-fix branch in comms_v4.py:3396-3420."""
+    from meshcode.preferences import load_prefs, save_prefs
+    if ver in ("reset", "unpin"):
+        prefs = load_prefs()
+        prefs.pop("claude_version", None)
+        save_prefs(prefs)
+    elif ver in ("latest", "none", "skip"):
+        prefs = load_prefs()
+        prefs["claude_version"] = ver
+        save_prefs(prefs)
+    else:
+        prefs = load_prefs()
+        prefs["claude_version"] = ver
+        save_prefs(prefs)
+
+
+def test_claude_version_latest_saves_literal(isolated_prefs):
+    """Repro for friction #9: `meshcode prefs claude-version latest` must
+    save "latest" to JSON, NOT delete the key."""
+    from meshcode.preferences import save_prefs
+    save_prefs({"claude_version": "2.1.50"})
+    _apply_branch("latest")
+    data = json.loads(isolated_prefs.read_text())
+    assert data.get("claude_version") == "latest", \
+        f"expected 'latest' literal, got {data!r}"
+
+
+def test_claude_version_none_saves_literal(isolated_prefs):
+    _apply_branch("none")
+    assert json.loads(isolated_prefs.read_text()).get("claude_version") == "none"
+
+
+def test_claude_version_skip_saves_literal(isolated_prefs):
+    _apply_branch("skip")
+    assert json.loads(isolated_prefs.read_text()).get("claude_version") == "skip"
+
+
+def test_claude_version_reset_clears_key(isolated_prefs):
+    from meshcode.preferences import save_prefs, load_prefs
+    save_prefs({"claude_version": "2.1.50"})
+    _apply_branch("reset")
+    assert "claude_version" not in load_prefs()
+
+
+def test_claude_version_unpin_clears_key(isolated_prefs):
+    from meshcode.preferences import save_prefs, load_prefs
+    save_prefs({"claude_version": "2.1.50"})
+    _apply_branch("unpin")
+    assert "claude_version" not in load_prefs()
+
+
+def test_claude_version_pin_saves_specific_version(isolated_prefs):
+    _apply_branch("2.1.108")
+    assert json.loads(isolated_prefs.read_text()).get("claude_version") == "2.1.108"