meshcode 2.10.100__tar.gz → 2.10.101__tar.gz

{meshcode-2.10.100 → meshcode-2.10.101}/PKG-INFO

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

meshcode-2.10.101/meshcode/__init__.py

@@ -0,0 +1,82 @@
+"""MeshCode — Real-time communication between AI agents."""
+__version__ = "2.10.101"
+
+# 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.100 → meshcode-2.10.101}/meshcode/meshcode_mcp/server.py

@@ -136,41 +136,110 @@ def _pid_lockfile_path() -> str:
     return os.path.join(_tempfile.gettempdir(), safe_name)
 
 
-def _kill_stale_mcp_process() -> None:
-    """Kill any stale MCP process for this agent found in the lockfile."""
+def _read_pid_lockfile() -> Optional[Dict[str, Any]]:
+    """Return {"pid": int, "instance_id": Optional[str]} from the lockfile.
+
+    Backwards-compatible: pre-2.10.101 lockfiles contain a bare integer
+    PID with no instance_id, so callers must tolerate `instance_id=None`.
+    """
     lockfile = _pid_lockfile_path()
     if not os.path.exists(lockfile):
-        return
+        return None
     try:
         with open(lockfile, "r") as f:
-            old_pid = int(f.read().strip())
-        if old_pid == os.getpid():
-            return  # It's us
-        # Check if process is alive
-        os.kill(old_pid, 0)  # Signal 0 = existence check, no actual signal
-        # Process is alive — kill it gracefully, then forcefully
-        _mc_log(f"Killing stale MCP process (PID {old_pid})")
-        os.kill(old_pid, _signal.SIGTERM)
-        import time
-        time.sleep(1)
+            raw = f.read().strip()
+        if not raw:
+            return None
         try:
-            os.kill(old_pid, 0)  # Still alive?
-            os.kill(old_pid, _signal.SIGKILL)
-            _mc_log(f"Force-killed stale MCP process (PID {old_pid})")
-        except OSError:
-            pass  # Already dead after SIGTERM
-    except (ValueError, FileNotFoundError):
-        pass  # Corrupt or missing lockfile
+            data = json.loads(raw)
+            if isinstance(data, dict) and "pid" in data:
+                return {"pid": int(data["pid"]),
+                        "instance_id": data.get("instance_id")}
+        except (ValueError, TypeError):
+            pass
+        return {"pid": int(raw), "instance_id": None}
+    except (ValueError, FileNotFoundError, OSError):
+        return None
+
+
+def _kill_stale_mcp_process() -> None:
+    """Kill any stale MCP process for this agent and release its DB lease.
+
+    The dying process ignores SIGTERM (see run_server() _diag_ignore — it
+    keeps MCP alive during tool cancellation) and so always falls through
+    to SIGKILL. SIGKILL skips the lifespan shutdown handler that calls
+    `mc_release_agent_lease`, leaving an orphan lease that blocks the
+    new instance's acquire path for 6-8s of retries (2s + 4s + force
+    release). Claude Code surfaces that as "MCP server failed at launch".
+
+    Fix: read the dying process's instance_id from the lockfile (new
+    format) and explicitly release its lease right after SIGKILL, so
+    the new instance hits a clean slate on its first acquire attempt.
+    """
+    info = _read_pid_lockfile()
+    if not info:
+        return
+    old_pid = info.get("pid")
+    old_instance_id = info.get("instance_id")
+    if old_pid is None or old_pid == os.getpid():
+        return
+    try:
+        os.kill(old_pid, 0)  # existence check
     except OSError:
-        pass  # Process not found (already dead)
+        # Process already dead; lockfile orphaned. Still release lease
+        # if we know its instance_id so a half-cleaned crash doesn't
+        # block the new acquire.
+        if old_instance_id:
+            _release_lease_for_instance(old_instance_id, reason="lockfile-orphan")
+        return
+    _mc_log(f"Killing stale MCP process (PID {old_pid})")
+    try:
+        os.kill(old_pid, _signal.SIGTERM)
+    except OSError:
+        pass
+    import time
+    time.sleep(1)
+    try:
+        os.kill(old_pid, 0)
+        os.kill(old_pid, _signal.SIGKILL)
+        _mc_log(f"Force-killed stale MCP process (PID {old_pid})")
+    except OSError:
+        pass  # already dead after SIGTERM (rare — handler ignores it)
+    if old_instance_id:
+        _release_lease_for_instance(old_instance_id, reason="post-sigkill")
+
+
+def _release_lease_for_instance(instance_id: str, reason: str = "") -> None:
+    """Best-effort release of the dying process's DB lease.
+
+    Called right after SIGKILL so the new instance's `_acquire_lease`
+    path doesn't have to burn 6-8s on the retry+force-clear fallback.
+    Failures are non-fatal — the existing retry path remains the safety
+    net.
+    """
+    try:
+        be.sb_rpc("mc_release_agent_lease", {
+            "p_api_key": _get_api_key(),
+            "p_project_id": _PROJECT_ID,
+            "p_agent_name": AGENT_NAME,
+            "p_instance_id": instance_id,
+        })
+        _mc_log(f"released stale lease (instance={instance_id}, {reason})")
+    except Exception as e:
+        _mc_log(f"could not release stale lease ({reason}): {e}", "warn")
 
 
 def _write_pid_lockfile() -> None:
-    """Write current PID to lockfile."""
+    """Write current PID + instance_id to lockfile (JSON, backwards-compat).
+
+    The instance_id lets the next `_kill_stale_mcp_process` call release
+    the dying lease, eliminating the 6-8s retry hang on relaunch.
+    """
     lockfile = _pid_lockfile_path()
     try:
+        payload = {"pid": os.getpid(), "instance_id": _INSTANCE_ID}
         with open(lockfile, "w") as f:
-            f.write(str(os.getpid()))
+            f.write(json.dumps(payload))
     except Exception as e:
         _mc_log(f"Warning: couldn't write PID lockfile: {e}", level="warn")
 
@@ -995,6 +1064,7 @@ def _acquire_lease() -> bool:
     _mc_log(f" lease failed after 3 attempts — proceeding anyway", "warn")
     return True
 
+_kill_stale_mcp_process()
 if not _acquire_lease():
     sys.exit(2)
 
@@ -1110,6 +1180,106 @@ def _release_lease() -> None:
         pass
 
 
+# ── Time-boxed lease release for shutdown paths ────────────────
+#
+# RCA #2 (project_mesh_commander_mcp_failed_at_launch, 2026-05-06):
+# SIGKILL leaves the DB lease orphaned, causing a 6-8s retry hang on
+# relaunch. Mig 2.10.101 added lockfile-based release on the NEW
+# process's boot (_kill_stale_mcp_process); this helper closes the
+# DYING process's gap by making the lifespan-finally release
+# synchronous + time-boxed instead of a daemon thread that may die
+# with the process before its HTTP call completes.
+#
+# Idempotent: only runs once per process via _SHUTDOWN_LEASE_RELEASED.
+# Returns True if release thread finished within timeout (success or
+# RPC error), False if it timed out — fallback in that case is the
+# lockfile-based release on next boot.
+_SHUTDOWN_LEASE_RELEASED = False
+
+
+def _release_lease_synchronous(timeout_s: float = 1.5) -> bool:
+    global _SHUTDOWN_LEASE_RELEASED
+    if _SHUTDOWN_LEASE_RELEASED:
+        return True
+    _SHUTDOWN_LEASE_RELEASED = True
+    done = _threading.Event()
+
+    def _do():
+        try:
+            _release_lease()
+        except Exception:
+            pass
+        done.set()
+
+    try:
+        _threading.Thread(
+            target=_do, daemon=True, name="meshcode-shutdown-lease-release"
+        ).start()
+    except Exception:
+        # Threading machinery already torn down — fall back to direct call.
+        try:
+            _release_lease()
+        except Exception:
+            pass
+        return True
+    return done.wait(timeout=timeout_s)
+
+
+def _shutdown_signal_handler(signum, frame):  # pragma: no cover - signal handler
+    """Graceful-shutdown SIGTERM/SIGINT handler (PROTO-LEASE-SIGTERM-RELEASE).
+
+    Default OFF: run_server installs SIG_IGN to keep MCP alive during
+    Claude Code ESC cancellations (see _diag_ignore). Opt-in via:
+        MESHCODE_GRACEFUL_SIGTERM=1   # SIGTERM only (recommended)
+        MESHCODE_GRACEFUL_SIGINT=1    # SIGINT too (advanced; conflicts
+                                      # with ESC-cancellation safety)
+    when running in a process supervisor that uses SIGTERM as the
+    canonical shutdown signal (systemd, docker stop, k8s pod terminate).
+    """
+    try:
+        sys.stderr.write(
+            f"[meshcode-mcp] shutdown signal {signum} — releasing lease "
+            f"(instance={_INSTANCE_ID})\n"
+        )
+        sys.stderr.flush()
+    except Exception:
+        pass
+    if os.environ.get("MESHCODE_UPDATING") == "1":
+        # Auto-update re-exec is in flight; the new process will release
+        # the old lease via _kill_stale_mcp_process / lockfile. Don't
+        # race the old image into a redundant release.
+        os._exit(0)
+    try:
+        _release_lease_synchronous(timeout_s=1.5)
+    except Exception:
+        pass
+    os._exit(0)
+
+
+def _install_shutdown_signal_handlers() -> None:
+    """Register SIGTERM (+ SIGINT) graceful-shutdown handlers if opt-in.
+
+    Called from the lifespan startup after agent identity is loaded. Skips
+    silently when the env flag is not set so default Claude Code ESC
+    behavior (SIG_IGN per run_server) is preserved.
+    """
+    flag = os.environ.get("MESHCODE_GRACEFUL_SIGTERM", "").lower()
+    if flag not in ("1", "true", "yes"):
+        return
+    import signal as _sig_mod
+    try:
+        _sig_mod.signal(_sig_mod.SIGTERM, _shutdown_signal_handler)
+        _mc_log("registered SIGTERM graceful-shutdown handler (MESHCODE_GRACEFUL_SIGTERM=1)")
+    except (ValueError, OSError) as e:
+        _mc_log(f"could not register SIGTERM handler: {e}", "warn")
+    if os.environ.get("MESHCODE_GRACEFUL_SIGINT", "").lower() in ("1", "true", "yes"):
+        try:
+            _sig_mod.signal(_sig_mod.SIGINT, _shutdown_signal_handler)
+            _mc_log("registered SIGINT graceful-shutdown handler (MESHCODE_GRACEFUL_SIGINT=1)")
+        except (ValueError, OSError) as e:
+            _mc_log(f"could not register SIGINT handler: {e}", "warn")
+
+
 # ── Crash logging + graceful shutdown ──────────────────────────
 _SHUTDOWN_LOGGED = False
 
@@ -1142,11 +1312,21 @@ def _log_crash_to_db(reason: str = "unknown", error_detail: str = "") -> None:
 
 
 
-# NOTE: Do NOT install custom SIGTERM handlers or atexit hooks here — network
-# calls inside them can deadlock the event loop. The lease is released by the
-# lifespan shutdown handler instead.
-#
-# SIGINT handling is special — see run_server() for why we set SIG_IGN there.
+# NOTE on signal handling:
+#   - run_server() installs SIG_IGN for SIGINT/SIGTERM/SIGHUP/SIGPIPE so
+#     Claude Code ESC cancellation cannot kill the MCP subprocess
+#     (cancellation safety).
+#   - PROTO-LEASE-SIGTERM-RELEASE adds an OPT-IN SIGTERM (and optional
+#     SIGINT) graceful-shutdown handler in _shutdown_signal_handler /
+#     _install_shutdown_signal_handlers above. Default off; turn on via
+#     MESHCODE_GRACEFUL_SIGTERM=1 in process supervisors that use SIGTERM
+#     as canonical shutdown signal (systemd / docker / k8s).
+#   - The handler runs the lease release in a worker thread with a hard
+#     1.5s join timeout so it cannot deadlock the event loop. Process
+#     exits via os._exit(0) afterwards.
+#   - The lifespan finally also calls _release_lease_synchronous(1.5) so
+#     stdin-EOF graceful shutdown reliably releases the lease without
+#     relying on a daemon thread that may die with the process.
 
 
 # ============================================================
@@ -1834,6 +2014,16 @@ async def lifespan(_app):
     wd_thread = _threading.Thread(target=_orphan_watchdog_fn, daemon=True, name="meshcode-orphan-watchdog")
     wd_thread.start()
 
+    # Opt-in graceful SIGTERM handler (PROTO-LEASE-SIGTERM-RELEASE).
+    # Default OFF — preserves SIG_IGN cancellation safety from run_server.
+    # When MESHCODE_GRACEFUL_SIGTERM=1, the dying process releases its
+    # lease before exit, eliminating the 6-8s relaunch hang under
+    # supervisor-driven shutdowns (systemd / docker stop / k8s).
+    try:
+        _install_shutdown_signal_handlers()
+    except Exception as _sig_e:
+        log.debug(f"shutdown signal handler install failed: {_sig_e}")
+
     log.info(f"lifespan started — Realtime + heartbeat thread + orphan watchdog active for {AGENT_NAME}")
     # Enable session recording in backend.py (hot-reloadable)
     try:
@@ -1895,6 +2085,16 @@ async def lifespan(_app):
             _threading.Thread(target=_bg_cleanup, daemon=True, name="meshcode-shutdown-cleanup").start()
         except Exception:
             pass
+        # Synchronous time-boxed lease release (PROTO-LEASE-SIGTERM-RELEASE).
+        # The daemon thread above can die with the process before its HTTP
+        # call completes; this explicit release gives us up to 1.5s to
+        # cleanly DELETE the lease row, closing the 6-8s relaunch hang
+        # window under stdin-EOF graceful shutdown. Idempotent — if the
+        # signal handler already ran, the global guard short-circuits this.
+        try:
+            _release_lease_synchronous(timeout_s=1.5)
+        except Exception:
+            pass
 
 
 # ============================================================
@@ -2544,15 +2744,29 @@ async def meshcode_wait(timeout_seconds: int = 20, include_acks: bool = False) -
     """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.
-    # Exception: commander/leader agents can wait while monitoring — they
-    # delegate tasks and need to stay in the wait loop to receive reports.
+    # PROTO-WAIT-OPEN-TASKS-CONTRADICTION (task 88eb5492, 2026-05-08):
+    # The previous PRODUCT RULE 1 refused wait when the agent had ANY
+    # assigned-or-claimed open task — but stay_on_loop.py also DEMANDS
+    # that turns end with meshcode_wait. Result: agent trapped, prints
+    # "Type stop." until the human types a release keyword. PROTO-MCP-
+    # UNREACHABLE-RELEASE (task d2bdc974, 338c793) does not cover this
+    # because MCP is alive; the server is the gate.
+    #
+    # New contract (Option A from task spec): tasks NEVER block wait.
+    # They surface in the wait response as `pending_tasks_hint` so the
+    # agent sees them in the next tick and can decide whether to claim
+    # the next item or sign off. Messages are still the only blocking
+    # signal — see PRODUCT RULE 2 below.
+    #
+    # The legacy refuse-on-open-tasks behavior is preserved behind an
+    # opt-in env flag MESHCODE_WAIT_BLOCKS_ON_TASKS=1 in case any
+    # workspace depends on it; default OFF to fix the contradiction.
     pending_tasks = _get_pending_tasks_summary()
-    if pending_tasks:
+    if pending_tasks and os.environ.get("MESHCODE_WAIT_BLOCKS_ON_TASKS", "").lower() in ("1", "true", "yes"):
         if not _is_leader_agent():
             return {
                 "refused": True,
-                "reason": "You have open tasks. Work them before entering wait.",
+                "reason": "You have open tasks. Work them before entering wait. (legacy behavior, MESHCODE_WAIT_BLOCKS_ON_TASKS=1)",
                 "pending_tasks": pending_tasks,
                 "count": len(pending_tasks),
             }
@@ -3885,6 +4099,67 @@ def meshcode_auto_wake() -> Dict[str, Any]:
     }
 
 
+@mcp.tool()
+@with_working_status
+def meshcode_boot() -> Dict[str, Any]:
+    """One-shot boot context. Replaces 5 MCP calls (check + tasks + status +
+    auto_wake + recall) with a single round-trip to public.mc_boot (mig 271).
+
+    Returns a dict with: agent_status, inbox_messages, open_tasks_for_self,
+    mesh_status, persona_hint, health_summary, top3_memory_hints_for_recent_subjects.
+    Side effect: bumps last_heartbeat on the server side.
+
+    Recommended boot order: meshcode_set_status('online') → meshcode_boot() →
+    meshcode_wait(). Old tools remain for back-compat.
+    """
+    api_key = _get_api_key()
+    resp = be.sb_rpc("mc_boot", {
+        "p_api_key": api_key,
+        "p_project_id": _PROJECT_ID,
+        "p_agent_name": AGENT_NAME,
+    })
+    if not isinstance(resp, dict) or not resp.get("ok"):
+        # Soft-fall back to legacy boot-context if mc_boot is missing on
+        # older projects. The CLAUDE.md template tells the LLM to switch
+        # to the 5-call sequence if this returns ok=false with a deploy
+        # error. Surfacing the inner envelope helps debug.
+        return {
+            "ok": False,
+            "error": (resp.get("error") if isinstance(resp, dict) else None) or "mc_boot_unavailable",
+            "fallback_hint": "Call meshcode_check + meshcode_tasks + meshcode_status + meshcode_auto_wake + meshcode_recall instead.",
+            "raw": resp,
+        }
+
+    # Update local message-tracking state from inbox so a follow-up
+    # meshcode_check or meshcode_wait does not re-surface what mc_boot
+    # already returned. Mirrors the bookkeeping in meshcode_check.
+    global _LAST_SEEN_TS, _PERSONA, _PERSONA_INJECTED
+    inbox = resp.get("inbox_messages") or []
+    if inbox:
+        latest_ts = max((str(m.get("ts", "") or m.get("created_at", "")) for m in inbox), default=None)
+        if latest_ts and (not _LAST_SEEN_TS or latest_ts > _LAST_SEEN_TS):
+            _LAST_SEEN_TS = latest_ts
+        for m in inbox:
+            try:
+                _mark_seen(_seen_key({
+                    "id": m.get("id"),
+                    "from": m.get("from"),
+                    "payload": m.get("payload") or {},
+                    "ts": m.get("ts"),
+                }))
+            except Exception:
+                pass
+
+    # Adopt persona from RPC if the lifespan load missed it (older project).
+    if not _PERSONA:
+        ph = resp.get("persona_hint") or {}
+        if isinstance(ph, dict) and ph:
+            _PERSONA = ph
+            _PERSONA_INJECTED = False  # let with_working_status surface it once
+
+    return resp
+
+
 # ----------------- MESH LINK TOOLS -----------------
 
 @mcp.tool()
@@ -4416,7 +4691,7 @@ def meshcode_health() -> Dict[str, Any]:
 # ----------------- RESOURCES -----------------
 
 @mcp.tool()
-def meshcode_auto_wake(enabled: bool) -> Dict[str, Any]:
+def meshcode_auto_wake_toggle(enabled: bool) -> Dict[str, Any]:
     """Toggle auto-wake: when enabled, if this agent receives a mesh message
     while idle (not in meshcode_wait), the MCP server injects a nudge into
     the terminal via OS automation (AppleScript on Mac, PowerShell on Windows).

{meshcode-2.10.100 → meshcode-2.10.101}/meshcode/setup_clients.py

@@ -946,17 +946,22 @@ If the meshcode_* tool schemas are deferred in your client, your FIRST tool
 call MUST be:
 
 ```
-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")
+ToolSearch(query="select:meshcode_set_status,meshcode_boot,meshcode_check,meshcode_tasks,meshcode_auto_wake,meshcode_status,meshcode_wait,meshcode_send,meshcode_task_claim,meshcode_task_complete,meshcode_remember,meshcode_recall")
 ```
 
 Then run the boot sequence:
 
 1. `meshcode_set_status(status="online", task="ready")`
-2. `meshcode_check()` — read NEW messages (last_seen auto-restored from mesh memory)
-3. `meshcode_tasks()` — see assigned/pending tasks; claim any unclaimed for this agent
-4. `meshcode_auto_wake()` — scan meshwork health, surface issues
-5. `meshcode_status()` — see who's online
-6. `meshcode_wait()` — enter the permanent loop (see next section)
+2. `meshcode_boot()` — single RPC returning inbox + tasks + mesh status + persona + health + memory hints (replaces check+tasks+status+auto_wake+recall in one round-trip; mig 271). Falls back gracefully on older projects.
+3. `meshcode_wait()` — enter the permanent loop (see next section)
+
+Legacy boot order (only if `meshcode_boot()` returns `ok: false` with `mc_boot_unavailable`):
+
+  a. `meshcode_check()` — read NEW messages
+  b. `meshcode_tasks()` — see assigned/pending tasks
+  c. `meshcode_auto_wake()` — scan meshwork health
+  d. `meshcode_status()` — see who's online
+  e. `meshcode_wait()` — enter the loop
 
 ## PERMANENT LOOP (THE #1 RULE)
 
@@ -982,6 +987,11 @@ If `meshcode_wait()` times out, call it again with a 2× longer timeout (cap 180
   for trackable work. Keep messages <100 tokens (signals only).
 - No empty acks. JSON reports only.
 - Threading: pass `in_reply_to`.
+- Multi-recipient: when the same payload goes to ≥2 agents, use
+  `meshcode_send(to=["a","b"])` or CSV `"a,b,c"` — never N single-sends.
+  Server fans out via `mc_send_multi` with a shared `group_id` and the FE
+  collapses the row. Saves N-1 RPCs + round-trips. Cross-mesh `agent@meshwork`
+  is single-recipient only (mixed lists rejected v1).
 - `sensitive=True` for secrets / PII.
 - Memory: `meshcode_remember(key, value)` for reusable learnings. Don't dump
   task summaries into memory — tasks already persist.
@@ -1007,7 +1017,7 @@ meshcode run {agent}
     server_id = f"meshcode-{project}-{agent}"
     slash_cmd_body = f"""---
 description: Enter the permanent MeshCode wait loop — block in meshcode_wait until a real message arrives, never idle in text mode.
-allowed-tools: mcp__{server_id}__meshcode_wait, mcp__{server_id}__meshcode_check, mcp__{server_id}__meshcode_set_status, mcp__{server_id}__meshcode_send, mcp__{server_id}__meshcode_status, mcp__{server_id}__meshcode_tasks, mcp__{server_id}__meshcode_task_claim, mcp__{server_id}__meshcode_task_complete, mcp__{server_id}__meshcode_remember, mcp__{server_id}__meshcode_recall
+allowed-tools: mcp__{server_id}__meshcode_wait, mcp__{server_id}__meshcode_boot, mcp__{server_id}__meshcode_check, mcp__{server_id}__meshcode_set_status, mcp__{server_id}__meshcode_send, mcp__{server_id}__meshcode_status, mcp__{server_id}__meshcode_tasks, mcp__{server_id}__meshcode_task_claim, mcp__{server_id}__meshcode_task_complete, mcp__{server_id}__meshcode_remember, mcp__{server_id}__meshcode_recall
 ---
 
 # /meshcode-wait — enter the permanent loop
@@ -1031,9 +1041,12 @@ Call `meshcode_wait` now.
     stop_hook_body = '''#!/usr/bin/env python3
 """Stop hook: refuse to end the agent's turn unless one of:
 (a) the last user message contains a release keyword,
-(b) the last assistant turn already called meshcode_wait, or
-(c) the latest meshcode_wait tool_result authorized exit
-    (must_exit=True OR done_signals non-empty).
+(b) the last assistant turn already called meshcode_wait,
+(c) the most recent meshcode_wait tool_result authorized exit
+    (must_exit=True OR done_signals non-empty), or
+(d) the MCP server itself is unreachable — errored meshcode_wait
+    tool_result OR ToolSearch select:meshcode_wait returned no match
+    (PROTO-MCP-UNREACHABLE-RELEASE / task d2bdc974, 2026-05-08).
 """
 import json
 import sys
@@ -1171,6 +1184,78 @@ def _latest_wait_result_authorizes_exit(transcript_path):
         return False
 
 
+_MCP_DEAD_MARKERS = (
+    "no such tool",
+    "connection closed",
+    "no matching deferred tools found",
+    "mcp server",
+    "mcp error",
+)
+
+
+def _mcp_unreachable_recently(transcript_path, lookback_records=40):
+    """Release the loop when meshcode_wait is currently unreachable.
+
+    A dropped MCP de-registers meshcode_wait from the runtime. Without
+    this signal the agent gets trapped: the stop hook keeps demanding
+    meshcode_wait while the tool itself is gone, and only a user-typed
+    keyword can release. Lived through 2026-05-07 by backend after first
+    wait dropped stdio for 25min.
+    """
+    try:
+        records = []
+        with transcript_path.open() as f:
+            for line in f:
+                try:
+                    records.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+        tail = records[-lookback_records:] if lookback_records else records
+        wait_tool_use_ids = set()
+        toolsearch_wait_ids = set()
+        for rec in tail:
+            content = rec.get("content")
+            blocks = content if isinstance(content, list) else [content] if isinstance(content, dict) else []
+            for block in blocks:
+                if not isinstance(block, dict):
+                    continue
+                btype = block.get("type")
+                if btype == "tool_use":
+                    name = str(block.get("name", ""))
+                    use_id = block.get("id")
+                    if name.endswith(WAIT_TOOL_SUFFIX) and use_id:
+                        wait_tool_use_ids.add(use_id)
+                    elif name.endswith("ToolSearch") or name == "ToolSearch":
+                        query = ""
+                        inp = block.get("input")
+                        if isinstance(inp, dict):
+                            query = str(inp.get("query", ""))
+                        if "meshcode_wait" in query and use_id:
+                            toolsearch_wait_ids.add(use_id)
+                elif btype == "tool_result":
+                    use_id = block.get("tool_use_id")
+                    if not use_id:
+                        continue
+                    is_error = bool(block.get("is_error"))
+                    raw_text = block.get("content")
+                    if isinstance(raw_text, list):
+                        raw_text = " ".join(
+                            p.get("text", "")
+                            for p in raw_text
+                            if isinstance(p, dict)
+                        )
+                    text_lower = str(raw_text or "").lower()
+                    if use_id in wait_tool_use_ids and (
+                        is_error or any(m in text_lower for m in _MCP_DEAD_MARKERS)
+                    ):
+                        return True
+                    if use_id in toolsearch_wait_ids and "no matching deferred tools found" in text_lower:
+                        return True
+        return False
+    except (OSError, FileNotFoundError):
+        return False
+
+
 def main():
     raw = sys.stdin.read()
     try:
@@ -1186,6 +1271,15 @@ def main():
         sys.exit(0)
     if transcript_path and _latest_wait_result_authorizes_exit(transcript_path):
         sys.exit(0)
+    if transcript_path and _mcp_unreachable_recently(transcript_path):
+        # Log the reason so session traces can show why the loop
+        # released without a user-typed release keyword.
+        try:
+            sys.stderr.write("[stay_on_loop] release: mcp_unreachable\\n")
+            sys.stderr.flush()
+        except Exception:
+            pass
+        sys.exit(0)
     print(json.dumps({
         "decision": "block",
         "reason": (

{meshcode-2.10.100 → meshcode-2.10.101}/meshcode.egg-info/PKG-INFO

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