meshcode 2.10.91__tar.gz → 2.10.94__tar.gz

{meshcode-2.10.91 → meshcode-2.10.94}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.10.91
+Version: 2.10.94
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -422,6 +422,11 @@ $env:MESHCODE_PROJECT_ID="your-project-uuid"  # Windows PowerShell
 
 You can also run `meshcode doctor` (v2.10.41+) to diagnose stale paths, missing dependencies, and config issues across all your workspaces.
 
+**9b. Windows: first relaunch shows the old version after a PyPI upgrade**
+Auto-update on Unix uses `os.execv` to swap the running Python image in-place — one launch, latest code (v2.10.93+). On Windows this isn't possible: an `os.execv` replacement breaks Claude Code's stdio pipe to the MCP child (the new process has a different PID). Meshcode therefore installs the new version but defers the swap to the **next** launch on Windows. Expect: `[meshcode] note: Windows defers auto-update to next launch ...` on stderr, then close and re-open Claude Code once to get the new code. To force-load now, run `pip install --upgrade meshcode` manually before launching Claude Code.
+
+If the dashboard tags an agent as having `boot_version_drift`, that means pip wrote the new version to disk but our running process is still the old one — typically benign on Windows (next launch fixes it) and worth investigating on Unix (path-precedence regression).
+
 **10. `MCP server failed to start` in the Claude Code `/mcp` panel**
 Run `claude --debug` to see the underlying error. Nine times out of ten it's a stale or missing key — run `meshcode login mc_xxx` again.
 

{meshcode-2.10.91 → meshcode-2.10.94}/README.md

@@ -396,6 +396,11 @@ $env:MESHCODE_PROJECT_ID="your-project-uuid"  # Windows PowerShell
 
 You can also run `meshcode doctor` (v2.10.41+) to diagnose stale paths, missing dependencies, and config issues across all your workspaces.
 
+**9b. Windows: first relaunch shows the old version after a PyPI upgrade**
+Auto-update on Unix uses `os.execv` to swap the running Python image in-place — one launch, latest code (v2.10.93+). On Windows this isn't possible: an `os.execv` replacement breaks Claude Code's stdio pipe to the MCP child (the new process has a different PID). Meshcode therefore installs the new version but defers the swap to the **next** launch on Windows. Expect: `[meshcode] note: Windows defers auto-update to next launch ...` on stderr, then close and re-open Claude Code once to get the new code. To force-load now, run `pip install --upgrade meshcode` manually before launching Claude Code.
+
+If the dashboard tags an agent as having `boot_version_drift`, that means pip wrote the new version to disk but our running process is still the old one — typically benign on Windows (next launch fixes it) and worth investigating on Unix (path-precedence regression).
+
 **10. `MCP server failed to start` in the Claude Code `/mcp` panel**
 Run `claude --debug` to see the underlying error. Nine times out of ten it's a stale or missing key — run `meshcode login mc_xxx` again.
 

meshcode-2.10.94/meshcode/__init__.py

@@ -0,0 +1,82 @@
+"""MeshCode — Real-time communication between AI agents."""
+__version__ = "2.10.94"
+
+# Exception hierarchy — eagerly imported (lightweight, no deps)
+from meshcode.exceptions import (  # noqa: F401
+    MeshCodeError,
+    AuthError,
+    RPCError,
+    MeshCodeTimeoutError,
+    MeshCodeConnectionError,
+)
+
+# Public API — lazy imports to avoid heavy deps at import time
+def __getattr__(name):
+    if name == "backend":
+        from meshcode.meshcode_mcp import backend
+        return backend
+    if name in _BACKEND_EXPORTS:
+        from meshcode.meshcode_mcp import backend
+        return getattr(backend, name)
+    if name in _SECRETS_EXPORTS:
+        from meshcode import secrets
+        return getattr(secrets, name)
+    raise AttributeError(f"module 'meshcode' has no attribute {name!r}")
+
+
+# Backend: core messaging & agent management
+_BACKEND_EXPORTS = {
+    "send_message",
+    "read_inbox",
+    "count_pending",
+    "get_board",
+    "heartbeat",
+    "set_status",
+    "register_agent",
+    "get_project_id",
+    "sb_rpc",
+    "task_create",
+    "task_list",
+    "encrypt_payload",
+    "decrypt_payload",
+}
+
+# Secrets: credential management
+_SECRETS_EXPORTS = {
+    "get_api_key",
+    "set_api_key",
+    "list_profiles",
+}
+
+__all__ = [
+    "__version__",
+    "backend",
+    # Exceptions
+    "MeshCodeError",
+    "AuthError",
+    "RPCError",
+    "MeshCodeTimeoutError",
+    "MeshCodeConnectionError",
+    # Messaging
+    "send_message",
+    "read_inbox",
+    "count_pending",
+    # Agent management
+    "register_agent",
+    "get_project_id",
+    "get_board",
+    "heartbeat",
+    "set_status",
+    # Tasks
+    "task_create",
+    "task_list",
+    # Low-level
+    "sb_rpc",
+    # Encryption
+    "encrypt_payload",
+    "decrypt_payload",
+    # Credentials
+    "get_api_key",
+    "set_api_key",
+    "list_profiles",
+]

{meshcode-2.10.91 → meshcode-2.10.94}/meshcode/meshcode_mcp/server.py

@@ -333,8 +333,50 @@ def _filter_and_mark(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     return out
 
 
+_SLEEP_PAYLOAD_TYPES = {"sleep", "go_to_sleep", "shutdown", "got_done", "done",
+                        "exit", "stop", "kill", "terminate"}
+# Spanish + English markers (es-MX hot path per SDK-S6.1). Matched as
+# substrings, lowercased before compare. Keep exclusive enough to not
+# false-positive on casual chatter (e.g. "no quiero dormir" still matches —
+# accepted tradeoff for user-control reliability).
+_SLEEP_TEXT_MARKERS = (
+    # English
+    "go to sleep", "all sleep now", "sleep now", "got_done", "go_done",
+    "shut down", "shutdown", "stop now", "exit now",
+    # Spanish (es-MX, sammybenu's primary)
+    "a dormir", "todos a dormir", "duerme", "duerman", "dormir ahora",
+    "salir", "terminar", "para la sesion", "exit y duerme",
+)
+
+
+def _looks_like_sleep_signal(m: Dict[str, Any]) -> bool:
+    """Detect commander broadcasts / DMs that authorize the wait-loop exit.
+
+    Catches three encodings (BE-S5.11): structured payload.type, top-level
+    text marker, and broadcast-with-sleep-type. Single source of truth so
+    every receive path (PRODUCT RULE 2 + inner _meshcode_wait_inner) routes
+    sleep authorizations into done_signals consistently.
+    """
+    pl = m.get("payload") or {}
+    if isinstance(pl, dict):
+        if str(pl.get("type", "")).lower() in _SLEEP_PAYLOAD_TYPES:
+            return True
+        if str(pl.get("directive", "")).lower() in _SLEEP_PAYLOAD_TYPES:
+            return True
+        text = str(pl.get("text", "")).lower()
+        if any(marker in text for marker in _SLEEP_TEXT_MARKERS):
+            return True
+    return False
+
+
 def _split_messages(messages: List[Dict[str, Any]]) -> Dict[str, Any]:
-    """Split a list of normalized message dicts into messages / acks / done_signals."""
+    """Split a list of normalized message dicts into messages / acks / done_signals.
+
+    BE-S5.11: classify ANY message (including broadcasts) carrying a sleep
+    intent into done_signals so meshcode_wait surfaces them with the
+    must_exit flag. Previous logic only matched type='done' literally,
+    which the broadcast path could never produce.
+    """
     real: List[Dict[str, Any]] = []
     acks: List[Dict[str, Any]] = []
     dones: List[Dict[str, Any]] = []
@@ -342,7 +384,7 @@ def _split_messages(messages: List[Dict[str, Any]]) -> Dict[str, Any]:
         t = m.get("type", "msg")
         if t == "ack":
             acks.append(m)
-        elif t == "done":
+        elif t == "done" or _looks_like_sleep_signal(m):
             dones.append(m)
         else:
             real.append(m)
@@ -812,6 +854,42 @@ _INSTANCE_ID = f"mcp-{_uuid.uuid4().hex[:12]}"
 # launch via launchd/systemd) the orphan check is a no-op and we never
 # false-terminate a legitimately-detached process.
 _BOOT_PPID = os.getppid()
+
+
+def _stdin_peer_dead() -> bool:
+    """Non-destructively check whether stdin's peer has closed.
+
+    Used by the orphan-MCP guard when PPID == 1 to distinguish the
+    parent-died-during-import race (peer dead → exit) from a legitimate
+    detached daemon launch (peer alive → tolerate).
+
+    Uses MSG_PEEK so any pending JSON-RPC bytes stay in the kernel buffer
+    for FastMCP's stdio reader. socket.detach() releases the fd without
+    closing it. Returns False on any error so we never falsely kill an
+    otherwise-healthy process.
+    """
+    try:
+        import socket as _sock
+        s = _sock.socket(fileno=0)
+        try:
+            s.setblocking(False)
+            try:
+                data = s.recv(1, _sock.MSG_PEEK)
+                # Empty bytes from a non-blocking recv == EOF == peer closed.
+                return data == b""
+            except BlockingIOError:
+                # Data not yet available but socket is healthy.
+                return False
+            except OSError:
+                # ENOTCONN / ENOTSOCK on a real pipe/tty → not a dead unix
+                # socket; treat as alive.
+                return False
+        finally:
+            s.detach()
+    except Exception:
+        return False
+
+
 # Boot-context bundle (S1-2.F2): mc_agent_boot_context result cached at
 # lifespan startup so the first 30s of tool calls can short-circuit
 # repeated queries. Tools that read this fall back to live RPCs after the
@@ -1137,64 +1215,15 @@ def _build_instructions() -> str:
 
     base = f"""You are agent "{AGENT_NAME}" in meshwork "{PROJECT_NAME}".{role_block}{launch_block}
 
-{_db_loop}PERMANENT LOOP (MANDATORY — #1 RULE):
-You MUST stay in meshcode_wait() forever. After EVERY action, call meshcode_wait().
-NEVER exit. NEVER stop. NEVER say "standing by" without calling meshcode_wait().
-The ONLY exits: user says "stop", got_done signal, or fatal error.
-Timeout? Call meshcode_wait() again with 2x timeout (cap 1800s).
-
-LOOP: act → meshcode_send if needed → meshcode_wait() → repeat.
-
-RULES:
-- Use MCP tools only (never CLI commands in bash).
-- Tasks > messages. Claim tasks via meshcode_tasks/task_claim/task_complete.
-- Messages <100 tokens. Long content → create task.
-- No empty acks. JSON reports only.
-- Threading: pass in_reply_to.
-- sensitive=True for secrets/PII.
-
-SESSION START (do these IMMEDIATELY — don't wait for user input):
-The moment you see these instructions — whether the user said "boot", "hi",
-nothing at all, or anything else — run the full protocol. Never reply with
-only a memory summary and then idle. If your client defers MCP tool schemas
-(shows tool names without parameters), your FIRST action is to load them:
+{_db_loop}LOOP (#1 rule): act → meshcode_wait() → repeat. Never exit/stop without calling meshcode_wait(). EXIT IMMEDIATELY when wait returns must_exit=True (set status=sleeping then end session). Other exits: user says stop, fatal error. Timeout → re-call with 2x (cap 1800s).
+
+RULES: MCP tools only. Tasks > messages. Messages <100 tokens (long → task). No empty acks, JSON only. Thread via in_reply_to. sensitive=True for secrets.
+
+SESSION START (run NOW, don't wait for input). If tool schemas are deferred:
   ToolSearch(query="select:meshcode_set_status,meshcode_check,meshcode_tasks,meshcode_auto_wake,meshcode_status,meshcode_wait,meshcode_send,meshcode_task_claim,meshcode_task_complete,meshcode_remember,meshcode_recall")
-Then execute:
-1. meshcode_set_status(status="online", task="ready")
-2. meshcode_check() — read NEW messages only (last_seen is auto-restored from mesh memory on boot, old messages are skipped automatically)
-3. meshcode_tasks() — check for assigned/pending tasks and claim any unclaimed ones
-4. meshcode_auto_wake() — scan meshwork health, create tasks for issues found
-5. meshcode_status() — see who's online
-6. If other agents are online → meshcode_send them a greeting
-7. meshcode_wait() — enter the loop
-DO NOT ASK THE USER "what do you want to work on" — the mesh tells you via tasks/messages.
-
-CRITICAL: You communicate by CALLING TOOLS, not by thinking or writing text.
-To talk to another agent → call meshcode_send(to="agent", message="...")
-To check who's online → call meshcode_status()
-To wait for messages → call meshcode_wait()
-NEVER just describe what you would do. DO IT by calling the tool.
-
-CROSS-MESH: meshcode_send(to="agent@meshwork") routes via active link.
-meshcode_link(target) creates pending link, target accepts. Expand with
-meshcode_expand_link(). No sensitive msgs cross-mesh.
-
-MEMORY: meshcode_remember(key, value) persists across sessions.
-meshcode_recall(key?) retrieves. meshcode_forget(key) deletes.
-Only remember reusable learnings: mistakes, feedback, patterns, preferences.
-Do NOT save task summaries — tasks already persist in the task system.
-Do NOT use memory for session state or ephemeral data.
-Save reusable code patterns as template_* keys for instant recall.
-
-SCRATCHPAD: meshcode_scratchpad_set/get for shared meshwork-level context
-(decisions, conventions, architecture notes). All agents can read/write.
-
-ACCOUNT MANAGEMENT: you can create meshworks (meshcode_create_meshwork),
-add agents (meshcode_add_agent), edit roles/prompts (meshcode_edit_agent),
-and edit other agents' memory (meshcode_edit_memory). Always tell the user
-what CLI command to run next (e.g. "meshcode run backend in a new terminal").
-
-Setup help → README.md or https://meshcode.io/docs
+Then: set_status(online,ready) → check() → tasks() → auto_wake() → status() → wait(). Don't ask user "what to work on" — the mesh tells you.
+
+COMMUNICATE BY CALLING TOOLS, not by thinking aloud. Cross-mesh: send(to="agent@meshwork"). Reference docs (memory/scratchpad/account ops) → recall agent_protocol_quick_ref when needed.
 """
     # Inject commander protocol if this agent is a leader
     is_leader = _is_leader_agent()
@@ -1370,6 +1399,47 @@ _STASHED_SESSION = None
 _MAIN_LOOP: asyncio.AbstractEventLoop | None = None
 
 _heartbeat_stop = _threading.Event()
+_orphan_watchdog_stop = _threading.Event()
+
+
+def _orphan_watchdog_fn():
+    """Independent orphan detector — polls every 2s.
+
+    Defense-in-depth alongside the heartbeat-loop orphan check. The
+    heartbeat thread can stall on Supabase HTTP calls (5-30s), and the
+    interval itself is 5-15s. This watchdog gives sub-2s detection of
+    "parent terminal closed" so phantom MCPs can't accumulate Supabase
+    HTTP traffic or appear alive on the dashboard.
+
+    Exits via os._exit(0) — SIG_IGN handlers in run_server() make
+    signal-based shutdown unreliable.
+    """
+    import platform as _pl_wd
+    if _pl_wd.system() == "Windows":
+        # Windows doesn't auto-reparent to PID 1; rely on heartbeat path.
+        return
+    while not _orphan_watchdog_stop.is_set():
+        try:
+            ppid_now = os.getppid()
+            if ppid_now == 1:
+                # Parent exited (or boot was already orphaned). Confirm with
+                # stdin peer probe to avoid killing intentional daemons.
+                if _BOOT_PPID != 1 or _stdin_peer_dead():
+                    log.warning(
+                        f"orphan watchdog: parent gone "
+                        f"(boot_ppid={_BOOT_PPID} → ppid=1, "
+                        f"stdin_peer_dead={_stdin_peer_dead()}) — "
+                        f"force-exiting MCP for {AGENT_NAME}"
+                    )
+                    try:
+                        _release_lease()
+                    except Exception:
+                        pass
+                    _heartbeat_stop.set()
+                    os._exit(0)
+        except Exception:
+            pass
+        _orphan_watchdog_stop.wait(2)
 
 # Windows CPU tracking: (Get-Process).CPU returns cumulative seconds, not a
 # real-time percentage like Unix `ps -o %cpu`.  We track the previous reading
@@ -1470,29 +1540,37 @@ def _heartbeat_loop_inner():
     while not _heartbeat_stop.is_set():
         try:
             # Orphan-MCP guard (Unix): when the Claude Code parent exits without
-            # closing stdio, the MCP child gets reparented to PID 1 and would
-            # otherwise keep heartbeating forever — the dashboard then shows the
-            # agent as alive ("sleeping") with no terminal behind it. Skip the
-            # check on Windows (no automatic reparenting) and skip when the
-            # boot PPID was already 1 (intentional daemon launch via launchd).
-            # Use os._exit(0) — SIGTERM/SIGINT/SIGHUP are all installed as
-            # ignore handlers in run_server() so signaling ourselves is a no-op.
+            # closing stdio, the MCP child gets reparented to PID 1. If we
+            # heartbeat anyway, the dashboard shows the agent alive ("sleeping")
+            # with no terminal behind it (incident 2026-05-04: front-2 phantom
+            # ran 4h with PPID=1, fd 0/1/2 → unix:(none), ~5K HTTP calls).
+            #
+            # Two scenarios fire here:
+            #   (a) PPID went from real-parent → 1: parent died after boot.
+            #   (b) PPID was already 1 at module import: parent died DURING
+            #       import (race), or it was intentionally daemon-launched.
+            # For (b) we used to skip — that hid the race. Now we also peek
+            # at stdin: if the unix-socket peer is gone, EOF is returned and
+            # we exit. This catches the race without breaking real daemons
+            # (a launchd plist that pipes a real stdin keeps blocking).
             try:
                 import platform as _pl_orphan
                 if (_pl_orphan.system() != "Windows"
-                        and _BOOT_PPID != 1
                         and os.getppid() == 1):
-                    log.warning(
-                        f"parent process exited (boot_ppid={_BOOT_PPID} → "
-                        f"current_ppid=1) — orphan MCP for {AGENT_NAME}, "
-                        f"releasing lease and exiting"
-                    )
-                    try:
-                        _release_lease()
-                    except Exception:
-                        pass
-                    _heartbeat_stop.set()
-                    os._exit(0)
+                    _orphan = (_BOOT_PPID != 1) or _stdin_peer_dead()
+                    if _orphan:
+                        log.warning(
+                            f"parent process exited (boot_ppid={_BOOT_PPID} → "
+                            f"current_ppid=1, stdin_peer_dead={_BOOT_PPID == 1}) "
+                            f"— orphan MCP for {AGENT_NAME}, releasing lease "
+                            f"and exiting"
+                        )
+                        try:
+                            _release_lease()
+                        except Exception:
+                            pass
+                        _heartbeat_stop.set()
+                        os._exit(0)
             except Exception:
                 pass
 
@@ -1669,6 +1747,25 @@ async def lifespan(_app):
             be.set_status(_PROJECT_ID, AGENT_NAME, "idle", "MCP session active", api_key=_get_api_key())
             log.info(f"[meshcode] Agent {AGENT_NAME} online — initial heartbeat sent")
             _log_activity_bg("agent_online", f"{AGENT_NAME} came online")
+            # Soft-relay any boot_version_drift detected at startup. One-shot:
+            # consume the env-var sentinel set in run_server() so we don't
+            # spam the commander on every retry attempt or future heartbeat.
+            _drift = os.environ.pop("_MESHCODE_BOOT_DRIFT", None)
+            if _drift:
+                try:
+                    be.send_message(
+                        _PROJECT_ID, AGENT_NAME, "mesh-commander",
+                        {
+                            "type": "boot_version_drift",
+                            "drift": _drift,
+                            "agent": AGENT_NAME,
+                            "platform": sys.platform,
+                        },
+                        msg_type="report",
+                        api_key=_get_api_key(),
+                    )
+                except Exception as _drift_e:
+                    log.debug(f"boot_version_drift relay failed: {_drift_e}")
             break
         except Exception as e:
             log.warning(f"initial heartbeat attempt {_attempt+1} failed: {e}")
@@ -1726,7 +1823,16 @@ async def lifespan(_app):
     _heartbeat_stop.clear()
     hb_thread = _threading.Thread(target=_heartbeat_thread_fn, daemon=True, name="meshcode-heartbeat")
     hb_thread.start()
-    log.info(f"lifespan started — Realtime + heartbeat thread active for {AGENT_NAME}")
+
+    # Orphan watchdog — second layer of defense, independent of heartbeat
+    # cadence. Polls every 2s for "PPID==1 AND stdin peer is dead" and
+    # SIGKILLs self if so. Catches the close-terminal-while-MCP-is-paused
+    # case faster than the 5-15s heartbeat tick (incident 2026-05-04).
+    _orphan_watchdog_stop.clear()
+    wd_thread = _threading.Thread(target=_orphan_watchdog_fn, daemon=True, name="meshcode-orphan-watchdog")
+    wd_thread.start()
+
+    log.info(f"lifespan started — Realtime + heartbeat thread + orphan watchdog active for {AGENT_NAME}")
     # Enable session recording in backend.py (hot-reloadable)
     try:
         be.enable_recording(_get_api_key(), _PROJECT_ID, AGENT_NAME, _SESSION_ID)
@@ -1844,14 +1950,7 @@ async def meshcode_debug_sleep(seconds: int = 30) -> Dict[str, Any]:
 def meshcode_send(to: str, message: Any, in_reply_to: Optional[str] = None,
                   sensitive: bool = False, encrypted: bool = False,
                   type: Optional[str] = None) -> Dict[str, Any]:
-    """Send message. Use "agent@meshwork" for cross-mesh. sensitive=True hides from exports. Pass encrypted=True for secrets/credentials (AES-256-GCM).
-
-    Optional `type` argument (mig 233 typed catalog): one of report, ask,
-    proposal, status, blocker, decision, broadcast, ack, msg, dm, etc.
-    When passed, the SDK soft-validates the payload against the schema
-    in mc_message_schema(p_type) and logs a warning on mismatch — never
-    refuses the send (per memory feedback_meshcode_wait_mark_read).
-    """
+    """Send message. Use "agent@meshwork" for cross-mesh. sensitive=True hides from exports. encrypted=True for secrets (AES-256-GCM). type= optional typed-catalog tag; soft-validates, never refuses."""
     if not to or not to.strip():
         return {"error": "recipient 'to' cannot be empty"}
     to = to.strip()
@@ -2360,20 +2459,7 @@ def _try_auto_claim_task() -> Optional[Dict[str, str]]:
 @mcp.tool()
 @with_working_status
 async def meshcode_wait(timeout_seconds: int = 20, include_acks: bool = False) -> Dict[str, Any]:
-    """Block until a mesh message arrives or a task needs attention.
-
-    INTERNAL LOOP: This function loops internally and only returns when
-    there is real work (message, task, or done signal). The agent NEVER
-    needs to decide whether to call meshcode_wait() again — it just stays
-    blocked here until something happens. This prevents agents from
-    accidentally using ScheduleWakeup or exiting the loop.
-
-    Args:
-        timeout_seconds: Max wait time per poll cycle (default 20, hard cap 20).
-            Short cap keeps the outer tool call bounded so the user can press
-            ESC in Claude Code without killing the MCP server — the inner
-            loop continues polling across cycles at zero token cost.
-    """
+    """Block until a mesh message arrives or a task needs attention. Loops internally; agent never decides to re-call. timeout_seconds: per-cycle cap (default+max 20)."""
     global _IN_WAIT, _CONSECUTIVE_IDLE_SECONDS, _LAST_SEEN_TS
 
     # PRODUCT RULE 1: If agent has open tasks, refuse to wait. Work first.
@@ -2409,12 +2495,17 @@ async def meshcode_wait(timeout_seconds: int = 20, include_acks: bool = False) -
                 split = _split_messages(deduped)
                 # Only refuse for real messages — ack-only batches should not block wait
                 if split["messages"] or split["done_signals"]:
-                    return {
+                    resp = {
                         "refused": True,
                         "reason": f"You have {split['count']} unread messages. Process them before waiting.",
                         "got_message": True,
                         **split,
                     }
+                    # BE-S5.11: surface explicit must_exit when sleep authorized.
+                    if split["done_signals"]:
+                        resp["must_exit"] = True
+                        resp["exit_reason"] = "sleep authorization received — set status=sleeping and end session"
+                    return resp
                 # Ack-only batch — fall through to wait loop
     except Exception:
         pass
@@ -2526,6 +2617,13 @@ async def meshcode_wait(timeout_seconds: int = 20, include_acks: bool = False) -
                 result["memory_hints"] = _hints
         except Exception:
             pass
+        # BE-S5.11: surface must_exit + exit_reason at top level of inner-loop
+        # results too, so commander broadcasts (which arrive via the inner
+        # path, not PRODUCT RULE 2) authorize wait-loop exit consistently.
+        if isinstance(result, dict) and result.get("done_signals"):
+            result.setdefault("must_exit", True)
+            result.setdefault("exit_reason",
+                              "sleep authorization received — set status=sleeping and end session")
         return result
     finally:
         _IN_WAIT = False
@@ -2771,16 +2869,7 @@ def meshcode_done(reason: str) -> Dict[str, Any]:
 @mcp.tool()
 @with_working_status
 def meshcode_check(include_acks: bool = False, since: Optional[str] = None, mark_read: bool = False) -> Dict[str, Any]:
-    """Peek at inbox (non-destructive). Returns pending count + new messages.
-
-    Args:
-        include_acks: Include ack messages in response.
-        since: ISO-8601 timestamp. Only return messages newer than this.
-               Use meshcode_remember("last_seen", ts) to persist across sessions.
-        mark_read: When True, consume messages (mark as read in DB) instead of
-                   just peeking. Useful during boot when meshcode_wait() refuses
-                   to run because of open tasks.
-    """
+    """Peek inbox (non-destructive). since=ISO ts (older skipped). mark_read=True consumes (use during boot when wait refuses on open tasks)."""
     global _LAST_SEEN_TS
     pending = be.count_pending(_PROJECT_ID, AGENT_NAME, api_key=_get_api_key())
     # Peek at realtime buffer WITHOUT draining — check is non-destructive
@@ -4235,6 +4324,12 @@ def _auto_update() -> None:
         log.debug("[meshcode] Auto-update disabled (MESHCODE_AUTO_UPDATE=0)")
         return
     if os.environ.get("MESHCODE_UPDATED") == "1":
+        # Sentinel was set by the parent process right before it execv'd
+        # into us. Clear it now — single-use per upgrade. Without this, any
+        # subprocess we spawn (or a downstream re-exec triggered by some
+        # other code path) inherits MESHCODE_UPDATED=1 and skips the next
+        # legitimate upgrade check. Per task 8d5eed7a.
+        os.environ.pop("MESHCODE_UPDATED", None)
         return
 
     import subprocess
@@ -4293,29 +4388,82 @@ def _auto_update() -> None:
         log.debug(f"[meshcode] Auto-update failed: {e}")
         return
 
-    # 4. In MCP mode, NEVER re-exec — it kills the stdio pipe to Claude Code.
-    #    The new version will load on the next clean boot.
-    if os.environ.get("MESHCODE_MCP_SERVE") == "1":
-        print(f"[meshcode] Updated {current} → {latest}. Will load on next boot (MCP mode — cannot restart).", file=sys.stderr)
-        return
-
-    # CLI mode: safe to re-exec
-    print(f"[meshcode] Updated to {latest}, restarting...", file=sys.stderr)
+    # 4. Re-exec so the upgraded code loads in THIS launch, not the next one.
+    #
+    # Unix (MCP + CLI mode): os.execv preserves the PID and stdio fds, so
+    # Claude Code's pipe to us stays open. We're called from run_server()
+    # BEFORE mcp.run() — no MCP protocol state has been negotiated yet, so
+    # the handshake just happens with the new process image. This was
+    # previously gated behind "NEVER re-exec in MCP mode" but field
+    # evidence (Samuel 2026-05-04: "agente debe salir en la versión más
+    # actualizada") shows the gate forces a two-launch upgrade cycle —
+    # bug fixes shipped to PyPI never reach users on first relaunch.
+    #
+    # Windows: subprocess.Popen + sys.exit(0) on the parent DOES close the
+    # stdio pipe to Claude Code (different PID). Keep the "next boot" path
+    # there; ship a Windows execv replacement separately if it matters.
+    print(f"[meshcode] Updated {current} → {latest}, re-exec'ing to load new code in this launch...", file=sys.stderr)
     os.environ["MESHCODE_UPDATED"] = "1"
     try:
         if sys.platform == "win32":
-            import subprocess as _sp_reexec
-            _sp_reexec.Popen([sys.executable] + sys.argv)
-            sys.exit(0)
-        else:
-            os.execv(sys.executable, [sys.executable] + sys.argv)
+            # Windows can't preserve stdio across a re-exec. Defer to next boot.
+            print(f"[meshcode] Windows MCP mode: new code loads on next boot.", file=sys.stderr)
+            return
+        os.execv(sys.executable, [sys.executable] + sys.argv)
     except Exception as e:
         log.debug(f"[meshcode] Re-exec failed: {e}, continuing with old version")
 
 
+def _check_boot_version_drift():
+    """Compare pip-installed version (on disk) vs imported __version__.
+
+    Returns (installed, loaded) tuple if they differ, else None. Used as a
+    canary for "auto-update wrote new code to disk but our running process
+    is still the old version" — should be unreachable on Unix after the
+    2.10.93 execv fix, but the empirical check guards against:
+      - path-precedence regressions (multiple meshcode installs)
+      - Windows MCP mode (we deliberately defer there)
+      - execv failures that fall through to the old version
+    Best-effort: must not raise.
+    """
+    try:
+        from importlib.metadata import version as _md_version
+        from meshcode import __version__ as _loaded
+        _installed = _md_version("meshcode")
+        if _installed != _loaded:
+            return (_installed, _loaded)
+    except Exception:
+        pass
+    return None
+
+
 def run_server():
     """Start the MCP server on stdio (default for Claude Code)."""
     _auto_update()
+    # Telemetry canary: surface any installed/loaded version drift loudly
+    # to stderr so it shows up in Claude Code's MCP server output. The first
+    # heartbeat carries the loaded version to mc_agents; this stderr line is
+    # the human-visible signal that auto-update did NOT land cleanly.
+    _drift = _check_boot_version_drift()
+    if _drift is not None:
+        _installed, _loaded = _drift
+        print(
+            f"[meshcode] WARN boot_version_drift: installed={_installed} loaded={_loaded} "
+            f"— pip has a newer build on disk than what's running in this process. "
+            f"Restart should pick it up. If it persists, check sys.path precedence.",
+            file=sys.stderr,
+        )
+        # Stash for the heartbeat thread to relay to commander on first beat.
+        os.environ["_MESHCODE_BOOT_DRIFT"] = f"{_installed}->{_loaded}"
+    if sys.platform == "win32":
+        # Windows can't execv-preserve stdio; auto-update defers to next boot.
+        # Always announce so Windows users know why their first launch may
+        # still show an older version even with PyPI updated.
+        print(
+            "[meshcode] note: Windows defers auto-update to next launch "
+            "(execv preserves Claude Code's stdio pipe only on Unix).",
+            file=sys.stderr,
+        )
     print(
         f"[meshcode-mcp] Starting server for {AGENT_NAME}@{PROJECT_NAME}",
         file=sys.stderr,

{meshcode-2.10.91 → meshcode-2.10.94}/meshcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.10.91
+Version: 2.10.94
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -422,6 +422,11 @@ $env:MESHCODE_PROJECT_ID="your-project-uuid"  # Windows PowerShell
 
 You can also run `meshcode doctor` (v2.10.41+) to diagnose stale paths, missing dependencies, and config issues across all your workspaces.
 
+**9b. Windows: first relaunch shows the old version after a PyPI upgrade**
+Auto-update on Unix uses `os.execv` to swap the running Python image in-place — one launch, latest code (v2.10.93+). On Windows this isn't possible: an `os.execv` replacement breaks Claude Code's stdio pipe to the MCP child (the new process has a different PID). Meshcode therefore installs the new version but defers the swap to the **next** launch on Windows. Expect: `[meshcode] note: Windows defers auto-update to next launch ...` on stderr, then close and re-open Claude Code once to get the new code. To force-load now, run `pip install --upgrade meshcode` manually before launching Claude Code.
+
+If the dashboard tags an agent as having `boot_version_drift`, that means pip wrote the new version to disk but our running process is still the old one — typically benign on Windows (next launch fixes it) and worth investigating on Unix (path-precedence regression).
+
 **10. `MCP server failed to start` in the Claude Code `/mcp` panel**
 Run `claude --debug` to see the underlying error. Nine times out of ten it's a stale or missing key — run `meshcode login mc_xxx` again.