meshcode 2.10.33__tar.gz → 2.10.35__tar.gz

{meshcode-2.10.33 → meshcode-2.10.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.10.33
+Version: 2.10.35
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -26,11 +26,27 @@ Requires-Dist: cryptography>=41.0
 
 # MeshCode
 
-**Persistent AI coworkers.** MeshCode is the infrastructure that lets multiple AI agents (Claude Code, Cursor, Cline, Claude Desktop) coordinate as a real-time team — each agent is a real editor window on someone's machine, and MeshCode is the mesh between them.
+**The easiest way to connect multiple AI agents in real time so they collaborate like a team.** MeshCode is the infrastructure that lets multiple AI agents (Claude Code, Cursor, Cline, Claude Desktop) coordinate as a real-time team — each agent is a real editor window on someone's machine, and MeshCode is the mesh between them.
 
 - Docs: https://meshcode.io/docs
 - Dashboard: https://meshcode.io/dashboard
 - GitHub: https://github.com/meshcode/meshcode
+- **Why MeshCode** (positioning): [docs/WHY_MESHCODE.md](./docs/WHY_MESHCODE.md)
+- **Compare to CrewAI / AutoGen / Swarm / LangGraph**: [docs/COMPARISON.md](./docs/COMPARISON.md)
+- **Use cases** (query → solution): [docs/USE_CASES.md](./docs/USE_CASES.md)
+
+---
+
+## When to use MeshCode
+
+- **Connect multiple Claude Code instances** so they coordinate as a team
+- **Run AI agents across editors** (Claude Code + Cursor + Cline) on the same project
+- **Collaborate with a friend's AI agent** across different laptops
+- **Persistent AI coworkers** that remember across sessions, days, weeks
+- **Orchestrate an AI engineering team** (commander + backend + frontend + QA)
+- **Observe + replay** agent sessions in a hosted dashboard
+
+Not the right fit if you need a single-agent chatbot, headless batch pipelines, or enterprise SSO/SOC2 paperwork. See [docs/COMPARISON.md](./docs/COMPARISON.md) for honest trade-offs.
 
 ---
 
@@ -59,6 +75,22 @@ That's it. `meshcode go` handles everything: auth check, workspace creation, edi
 
 ---
 
+## How MeshCode compares
+
+| | MeshCode | CrewAI | AutoGen | OpenAI Swarm | Anthropic subagents |
+|---|---|---|---|---|---|
+| Persistent agents across sessions | **yes** | no | no | no | no |
+| Real editor windows (Claude Code, Cursor, Cline) | **yes** | no | no | no | partial |
+| Cross-machine collaboration | **yes** | no | no | no | no |
+| MCP-native | **yes** | no | no | no | yes |
+| Hosted dashboard (status, replay, graph) | **yes** | no | no | no | no |
+| No vendor lock-in | **yes** | yes | partial | **no (OpenAI only)** | **no (Anthropic only)** |
+| One-command setup (<30s) | **yes** | no | no | no | partial |
+
+Full comparison with LangGraph, Google A2A, and DIY → [docs/COMPARISON.md](./docs/COMPARISON.md).
+
+---
+
 ## How it works
 
 ```

{meshcode-2.10.33 → meshcode-2.10.35}/README.md

@@ -1,10 +1,26 @@
 # MeshCode
 
-**Persistent AI coworkers.** MeshCode is the infrastructure that lets multiple AI agents (Claude Code, Cursor, Cline, Claude Desktop) coordinate as a real-time team — each agent is a real editor window on someone's machine, and MeshCode is the mesh between them.
+**The easiest way to connect multiple AI agents in real time so they collaborate like a team.** MeshCode is the infrastructure that lets multiple AI agents (Claude Code, Cursor, Cline, Claude Desktop) coordinate as a real-time team — each agent is a real editor window on someone's machine, and MeshCode is the mesh between them.
 
 - Docs: https://meshcode.io/docs
 - Dashboard: https://meshcode.io/dashboard
 - GitHub: https://github.com/meshcode/meshcode
+- **Why MeshCode** (positioning): [docs/WHY_MESHCODE.md](./docs/WHY_MESHCODE.md)
+- **Compare to CrewAI / AutoGen / Swarm / LangGraph**: [docs/COMPARISON.md](./docs/COMPARISON.md)
+- **Use cases** (query → solution): [docs/USE_CASES.md](./docs/USE_CASES.md)
+
+---
+
+## When to use MeshCode
+
+- **Connect multiple Claude Code instances** so they coordinate as a team
+- **Run AI agents across editors** (Claude Code + Cursor + Cline) on the same project
+- **Collaborate with a friend's AI agent** across different laptops
+- **Persistent AI coworkers** that remember across sessions, days, weeks
+- **Orchestrate an AI engineering team** (commander + backend + frontend + QA)
+- **Observe + replay** agent sessions in a hosted dashboard
+
+Not the right fit if you need a single-agent chatbot, headless batch pipelines, or enterprise SSO/SOC2 paperwork. See [docs/COMPARISON.md](./docs/COMPARISON.md) for honest trade-offs.
 
 ---
 
@@ -33,6 +49,22 @@ That's it. `meshcode go` handles everything: auth check, workspace creation, edi
 
 ---
 
+## How MeshCode compares
+
+| | MeshCode | CrewAI | AutoGen | OpenAI Swarm | Anthropic subagents |
+|---|---|---|---|---|---|
+| Persistent agents across sessions | **yes** | no | no | no | no |
+| Real editor windows (Claude Code, Cursor, Cline) | **yes** | no | no | no | partial |
+| Cross-machine collaboration | **yes** | no | no | no | no |
+| MCP-native | **yes** | no | no | no | yes |
+| Hosted dashboard (status, replay, graph) | **yes** | no | no | no | no |
+| No vendor lock-in | **yes** | yes | partial | **no (OpenAI only)** | **no (Anthropic only)** |
+| One-command setup (<30s) | **yes** | no | no | no | partial |
+
+Full comparison with LangGraph, Google A2A, and DIY → [docs/COMPARISON.md](./docs/COMPARISON.md).
+
+---
+
 ## How it works
 
 ```

{meshcode-2.10.33 → meshcode-2.10.35}/meshcode/__init__.py

@@ -1,2 +1,2 @@
 """MeshCode — Real-time communication between AI agents."""
-__version__ = "2.10.33"
+__version__ = "2.10.35"

meshcode-2.10.35/meshcode/meshcode_mcp/__init__.py

@@ -0,0 +1,22 @@
+"""MeshCode MCP server — exposes meshcode tools to MCP clients (Claude Code, etc)."""
+__version__ = "1.0.0"
+
+# Convenience re-exports so `from meshcode.meshcode_mcp import MeshCodeMCP`
+# and `from meshcode.meshcode_mcp.backend import MeshCodeBackend` work.
+# These are lazy to avoid import-time side effects (server.py reads env vars
+# and exits if MESHCODE_PROJECT / MESHCODE_AGENT are unset).
+
+
+def __getattr__(name):
+    if name == "MeshCodeMCP":
+        from .server import mcp as _mcp, run_server  # noqa: F811
+        # Expose the FastMCP instance and run_server under the expected name
+        class MeshCodeMCP:
+            """Convenience wrapper around the FastMCP server instance."""
+            server = _mcp
+            run = staticmethod(run_server)
+        return MeshCodeMCP
+    if name == "run_server":
+        from .server import run_server
+        return run_server
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{meshcode-2.10.33 → meshcode-2.10.35}/meshcode/meshcode_mcp/__main__.py

@@ -9,12 +9,35 @@ import sys
 # - Block-buffered → JSON-RPC bytes get stuck in the kernel buffer until
 #   the buffer fills, so Claude Code never sees the handshake response.
 # Both must be fixed BEFORE FastMCP touches stdio.
-try:
-    sys.stdout.reconfigure(encoding="utf-8", errors="replace", newline="\n", line_buffering=True)
-    sys.stdin.reconfigure(encoding="utf-8", errors="replace", newline="\n")
-    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
-except Exception:
-    pass
+def _force_utf8_stdio():
+    """Force UTF-8 + line-buffered stdout, UTF-8 stdin/stderr.
+
+    reconfigure() can fail on some Windows Python builds (3.14+) when
+    stdout is a pipe without a backing console. In that case, wrap the
+    raw buffer in a fresh TextIOWrapper.
+    """
+    import io
+    for stream_name in ("stdout", "stdin", "stderr"):
+        stream = getattr(sys, stream_name)
+        if stream is None:
+            continue
+        kw = {"encoding": "utf-8", "errors": "replace"}
+        if stream_name != "stderr":
+            kw["newline"] = "\n"
+        if stream_name == "stdout":
+            kw["line_buffering"] = True
+        try:
+            stream.reconfigure(**kw)
+        except Exception:
+            # reconfigure failed — wrap the raw buffer manually
+            try:
+                raw = stream.buffer
+                wrapper = io.TextIOWrapper(raw, **kw)
+                setattr(sys, stream_name, wrapper)
+            except Exception:
+                pass  # nothing more we can do
+
+_force_utf8_stdio()
 # Belt and suspenders: also export PYTHONIOENCODING in case any subprocess
 # we spawn inherits this env.
 os.environ.setdefault("PYTHONIOENCODING", "utf-8")

{meshcode-2.10.33 → meshcode-2.10.35}/meshcode/meshcode_mcp/backend.py

@@ -5,10 +5,13 @@ Zero deps beyond stdlib (urllib + http.client for connection pooling).
 """
 import http.client
 import json
+import logging
 import os
 import ssl
 import time as _time
 import threading as _threading
+
+log = logging.getLogger("meshcode-mcp.backend")
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -81,8 +84,8 @@ def _load_env_file() -> Dict[str, str]:
             if "=" in line and not line.startswith("#"):
                 k, v = line.split("=", 1)
                 out[k.strip()] = v.strip().strip('"').strip("'")
-    except Exception:
-        pass
+    except Exception as e:
+        log.debug(f"env file parse error ({env_path}): {e}")
     return out
 
 _env_file = _load_env_file()
@@ -322,8 +325,8 @@ def _bg_record(event_type: str, payload: dict):
                 "p_event_type": event_type,
                 "p_payload": payload,
             })
-        except Exception:
-            pass
+        except Exception as e:
+            log.debug(f"bg_record failed ({event_type}): {e}")
     threading.Thread(target=_do, daemon=True).start()
 
 
@@ -346,6 +349,8 @@ def sb_rpc_raw(fn_name: str, params: Dict) -> Any:
 # ============================================================
 
 def get_project_id(project_name: str) -> Optional[str]:
+    if not project_name:
+        return None
     rows = sb_select("mc_projects", f"name=eq.{quote(project_name)}")
     if rows:
         return rows[0]["id"]
@@ -805,3 +810,34 @@ def get_message_by_id(project_id: str, msg_id: str, api_key: Optional[str] = Non
         limit=1,
     )
     return results[0] if results else None
+
+
+# ============================================================
+# Convenience class so `from meshcode.meshcode_mcp.backend import MeshCodeBackend`
+# works for users who expect a class-based API (e.g. Windows onboarding docs).
+# ============================================================
+
+class MeshCodeBackend:
+    """Namespace wrapper around the backend module functions.
+
+    All methods are static — no instance state. This exists purely so that
+    ``from meshcode.meshcode_mcp.backend import MeshCodeBackend`` resolves.
+    """
+    get_project_id = staticmethod(get_project_id)
+    register_agent = staticmethod(register_agent)
+    send_message = staticmethod(send_message)
+    read_inbox = staticmethod(read_inbox)
+    count_pending = staticmethod(count_pending)
+    get_board = staticmethod(get_board)
+    heartbeat = staticmethod(heartbeat)
+    set_status = staticmethod(set_status)
+    task_create = staticmethod(task_create)
+    task_list = staticmethod(task_list)
+    task_claim = staticmethod(task_claim)
+    task_complete = staticmethod(task_complete)
+    get_history = staticmethod(get_history)
+    get_message_by_id = staticmethod(get_message_by_id)
+    sb_rpc = staticmethod(sb_rpc)
+    sb_select = staticmethod(sb_select)
+    sb_insert = staticmethod(sb_insert)
+    sb_update = staticmethod(sb_update)

{meshcode-2.10.33 → meshcode-2.10.35}/meshcode/meshcode_mcp/realtime.py

@@ -164,6 +164,12 @@ class RealtimeListener:
                                 "schema": "meshcode",
                                 "table": "mc_messages",
                                 "filter": f"to_agent=eq.{url_quote(self.agent_name, safe='')}",
+                            },
+                            {
+                                "event": "INSERT",
+                                "schema": "meshcode",
+                                "table": "mc_messages",
+                                "filter": "to_agent=eq.*",
                             }
                         ]
                     }
@@ -200,6 +206,10 @@ class RealtimeListener:
                     await ws.send(json.dumps(join_msg))
             if not self._subscription_ok:
                 log.error(f"Realtime subscription FAILED after 3 attempts for {self.agent_name}")
+                # Close and let the outer _run() loop reconnect with backoff.
+                # Staying connected but unsubscribed wastes the WebSocket
+                # and forces the agent into slow DB polling forever.
+                return
 
             # Heartbeat task to keep the connection alive
             heartbeat_task = asyncio.create_task(self._heartbeat(ws))
@@ -209,7 +219,8 @@ class RealtimeListener:
                         break
                     try:
                         msg = json.loads(raw)
-                    except Exception:
+                    except Exception as e:
+                        log.warning(f"Realtime JSON parse error: {e} (raw[:200]={str(raw)[:200]})")
                         continue
                     await self._handle_message(msg)
             finally:
@@ -234,7 +245,8 @@ class RealtimeListener:
                     "payload": {},
                     "ref": str(ref),
                 }))
-            except Exception:
+            except Exception as e:
+                log.warning(f"Realtime heartbeat send failed: {e}")
                 return
 
     async def _handle_message(self, msg: Dict[str, Any]) -> None:
@@ -247,7 +259,11 @@ class RealtimeListener:
             data = payload.get("data") or {}
             if data.get("type") == "INSERT":
                 record = data.get("record") or {}
-                if record.get("to_agent") == self.agent_name and record.get("project_id") == self.project_id:
+                to = record.get("to_agent")
+                from_agent = record.get("from_agent")
+                # Accept direct messages AND broadcasts (to_agent='*'),
+                # but filter out self-broadcasts to avoid echo.
+                if (to in (self.agent_name, "*")) and record.get("project_id") == self.project_id and from_agent != self.agent_name:
                     enriched = {
                         "from": record.get("from_agent"),
                         "type": record.get("type", "msg"),
@@ -300,6 +316,17 @@ class RealtimeListener:
         except asyncio.TimeoutError:
             return False
 
+    async def restart(self) -> None:
+        """Stop and restart the Realtime connection.
+
+        Called by the heartbeat thread when it detects the subscription
+        dropped (is_subscribed=False). The outer _run() loop handles
+        reconnect with exponential backoff.
+        """
+        log.info(f"Realtime restart requested for {self.agent_name}")
+        await self.stop()
+        await self.start()
+
     @property
     def is_connected(self) -> bool:
         return self._connected

{meshcode-2.10.33 → meshcode-2.10.35}/meshcode/meshcode_mcp/server.py

@@ -95,9 +95,15 @@ def _mc_log(msg: str, level: str = "info") -> None:
 # meshcode_wait / meshcode_check so the same row doesn't show
 # up twice when realtime + polled paths race.
 # ============================================================
-_SEEN_MSG_IDS: set = set()
+# TTL-based message dedup cache. Each entry stores (msg_key, timestamp).
+# Entries older than _SEEN_TTL are evicted on access. This prevents
+# the race where Realtime delivers a message and DB polling returns the
+# same one before mark-read completes. The TTL ensures the cache doesn't
+# grow unbounded across long sessions.
+_SEEN_MSG_IDS: dict = {}  # key -> timestamp (monotonic)
 _SEEN_MSG_ORDER: deque = deque()
-_SEEN_MSG_CAP = 1000
+_SEEN_MSG_CAP = 2000
+_SEEN_TTL = 300.0  # 5 minutes
 
 # ============================================================
 # Auto-wake: when agent is NOT in meshcode_wait and a message
@@ -216,18 +222,37 @@ def _seen_key(msg: Dict[str, Any]) -> str:
     return f"{msg.get('from') or msg.get('from_agent')}|{msg.get('ts') or msg.get('created_at')}|{payload_str}"
 
 
+def _evict_expired() -> None:
+    """Remove entries older than _SEEN_TTL from the dedup cache."""
+    now = _time.monotonic()
+    while _SEEN_MSG_ORDER:
+        oldest_key = _SEEN_MSG_ORDER[0]
+        ts = _SEEN_MSG_IDS.get(oldest_key)
+        if ts is not None and (now - ts) > _SEEN_TTL:
+            _SEEN_MSG_ORDER.popleft()
+            _SEEN_MSG_IDS.pop(oldest_key, None)
+        else:
+            break
+
+
 def _mark_seen(key: str) -> None:
+    now = _time.monotonic()
     if key in _SEEN_MSG_IDS:
+        # Refresh timestamp on re-sight (extends TTL)
+        _SEEN_MSG_IDS[key] = now
         return
-    _SEEN_MSG_IDS.add(key)
+    _SEEN_MSG_IDS[key] = now
     _SEEN_MSG_ORDER.append(key)
+    # Evict expired + cap enforcement
+    _evict_expired()
     while len(_SEEN_MSG_ORDER) > _SEEN_MSG_CAP:
         old = _SEEN_MSG_ORDER.popleft()
-        _SEEN_MSG_IDS.discard(old)
+        _SEEN_MSG_IDS.pop(old, None)
 
 
 def _filter_and_mark(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     """Drop already-seen messages; mark the rest as seen."""
+    _evict_expired()  # Clean stale entries before checking
     out = []
     for m in messages:
         k = _seen_key(m)
@@ -912,7 +937,15 @@ what CLI command to run next (e.g. "meshcode run backend in a new terminal").
 Setup help → README.md or https://meshcode.io/docs
 """
     # Inject commander protocol if this agent is a leader
-    is_leader = any(k in (_ROLE_DESCRIPTION or '').lower() + AGENT_NAME.lower() for k in ('commander', 'lead', 'orchestrat'))
+    # Match leader-like agent names and roles across languages.
+    # Substring match: "orchestrator" hits on "orchestrat", "coordinador" hits on "coordinat".
+    _leader_haystack = ((_ROLE_DESCRIPTION or '') + ' ' + AGENT_NAME).lower()
+    _LEADER_KEYWORDS = (
+        'commander', 'lead', 'orchestrat', 'coordinator', 'coordinat',
+        'coordinad', 'jefe', 'líder', 'lider', 'director', 'manager',
+        'chief', 'captain', 'boss', 'head agent',
+    )
+    is_leader = any(k in _leader_haystack for k in _LEADER_KEYWORDS)
     if is_leader:
         base += """
 COMMANDER PROTOCOL (you are the team lead):
@@ -1097,13 +1130,36 @@ def _get_parent_cpu() -> float:
         return 0.0
 
 
+_heartbeat_crash_count = 0
+
 def _heartbeat_thread_fn():
     """Heartbeat in a DAEMON THREAD — independent of asyncio event loop.
 
     This ensures heartbeats continue even when tool calls are cancelled,
     meshcode_wait is rejected, or the asyncio loop is busy. The agent
     stays 'online' in the dashboard as long as the MCP process is alive.
+
+    Wrapped in an outer try/except so uncaught exceptions (including from
+    _heartbeat_stop.wait()) restart the loop instead of silently killing
+    the thread — which would leave the agent as a ghost on the dashboard.
     """
+    global _heartbeat_crash_count
+    while not _heartbeat_stop.is_set():
+        try:
+            _heartbeat_loop_inner()
+        except Exception as e:
+            _heartbeat_crash_count += 1
+            log.error(
+                f"heartbeat thread crashed ({_heartbeat_crash_count}x): {e} — "
+                f"restarting in 5s to prevent ghost agent"
+            )
+            # Brief sleep before restart to avoid tight crash loop
+            _heartbeat_stop.wait(5)
+
+
+def _heartbeat_loop_inner():
+    """Single iteration of the heartbeat loop. Separated so the outer
+    wrapper can catch any exception and restart cleanly."""
     lease_counter = 0
     while not _heartbeat_stop.is_set():
         try:
@@ -1136,12 +1192,33 @@ def _heartbeat_thread_fn():
             # Sync current state to DB (in case realtime missed it)
             try:
                 be.set_status(_PROJECT_ID, AGENT_NAME, _current_state, _current_tool, api_key=_get_api_key())
-            except Exception:
-                pass
-            if _REALTIME and not _REALTIME.is_connected:
-                log.warning("heartbeat ok (HTTP) but WebSocket disconnected")
+            except Exception as e:
+                log.debug(f"status sync failed: {e}")
+            # Realtime subscription recovery: if the WebSocket is connected but
+            # the channel subscription dropped (e.g. Supabase maintenance), or
+            # the WebSocket itself disconnected, trigger a restart so agents
+            # don't stay stuck in slow DB polling for the entire session.
+            if _REALTIME:
+                if not _REALTIME.is_connected:
+                    log.warning("heartbeat ok (HTTP) but WebSocket disconnected — scheduling Realtime restart")
+                    try:
+                        loop = asyncio.get_event_loop()
+                        if loop.is_running():
+                            asyncio.run_coroutine_threadsafe(_REALTIME.restart(), loop)
+                    except Exception as e:
+                        log.debug(f"Realtime restart scheduling failed: {e}")
+                elif not _REALTIME.is_subscribed:
+                    log.warning("WebSocket connected but subscription lost — scheduling Realtime restart")
+                    try:
+                        loop = asyncio.get_event_loop()
+                        if loop.is_running():
+                            asyncio.run_coroutine_threadsafe(_REALTIME.restart(), loop)
+                    except Exception as e:
+                        log.debug(f"Realtime restart scheduling failed: {e}")
+                else:
+                    log.debug(f"heartbeat ok for {AGENT_NAME}")
             else:
-                log.debug(f"heartbeat ok for {AGENT_NAME}")
+                log.debug(f"heartbeat ok for {AGENT_NAME} (no Realtime)")
         except Exception as e:
             log.warning(f"heartbeat failed: {e}")
 
@@ -1626,8 +1703,8 @@ async def meshcode_wait(timeout_seconds: int = 20, include_acks: bool = False) -
                                 "p_status": "sleeping",
                                 "p_task": f"idle {_CONSECUTIVE_IDLE_SECONDS}s — still listening",
                             })
-                    except Exception:
-                        pass
+                    except Exception as e:
+                        log.debug(f"auto-sleep status update failed: {e}")
                     # Do NOT return — keep looping. Status says sleeping but
                     # we are still listening for messages via realtime.
                     _set_state("sleeping", f"idle {_CONSECUTIVE_IDLE_SECONDS}s — still listening")
@@ -1652,8 +1729,8 @@ async def meshcode_wait(timeout_seconds: int = 20, include_acks: bool = False) -
                             "p_tier": "critical",
                             "p_project_name": PROJECT_NAME,
                         })
-                    except Exception:
-                        pass
+                    except Exception as e:
+                        log.debug(f"last_seen memory persist failed: {e}")
         return result
     finally:
         _IN_WAIT = False
@@ -1681,8 +1758,8 @@ def _mark_realtime_msgs_read_in_db(messages: List[Dict[str, Any]]) -> None:
                     "p_project_id": _PROJECT_ID,
                     "p_message_id": mid,
                 })
-            except Exception:
-                pass
+            except Exception as e:
+                log.debug(f"mark_read failed for msg {mid}: {e}")
     threading.Thread(target=_do, daemon=True).start()
 
 
@@ -1776,8 +1853,8 @@ async def _meshcode_wait_inner(actual_timeout: int, include_acks: bool) -> Dict[
                                     split["acks"] = []
                                 if split["messages"] or split["done_signals"]:
                                     return {"got_message": True, "source": "db_poll_fallback", **split}
-            except Exception:
-                pass
+            except Exception as e:
+                log.debug(f"DB poll fallback error: {e}")
 
     # Final fallback: one last DB check (covers realtime path missing msgs)
     try:
@@ -1800,8 +1877,8 @@ async def _meshcode_wait_inner(actual_timeout: int, include_acks: bool) -> Dict[
                             split["acks"] = []
                         if split["messages"] or split["done_signals"]:
                             return {"got_message": True, "source": "db_fallback", **split}
-    except Exception:
-        pass
+    except Exception as e:
+        log.debug(f"final DB fallback error: {e}")
 
     # Check if there's any pending work before returning timeout
     pending_tasks = _get_pending_tasks_summary()
@@ -2671,7 +2748,7 @@ def meshcode_health() -> Dict[str, Any]:
     }
 
     # Realtime status
-    health["realtime_connected"] = getattr(_rt_state, 'connected', False) if '_rt_state' in dir() else "unknown"
+    health["realtime_connected"] = _REALTIME.is_connected if _REALTIME else False
 
     # Process uptime
     try:

{meshcode-2.10.33 → meshcode-2.10.35}/meshcode/run_agent.py

@@ -177,7 +177,7 @@ def _check_agent_ownership(agent: str, project: str) -> Optional[str]:
         import importlib
         secrets_mod = importlib.import_module("meshcode.secrets")
     except Exception:
-        return None  # Can't check — let the RPC catch it later
+        return "cannot load auth modules; re-install meshcode"
 
     # Try scoped profile first (from invite join), then default
     scoped_profile = f"mesh:{project}:{agent}"
@@ -186,7 +186,7 @@ def _check_agent_ownership(agent: str, project: str) -> Optional[str]:
         profile = os.environ.get("MESHCODE_KEYCHAIN_PROFILE") or "default"
         api_key = secrets_mod.get_api_key(profile=profile)
     if not api_key:
-        return None  # No key — RPC will reject later
+        return "not logged in — run `meshcode login <api_key>` first"
 
     sb = _load_supabase_env()
     try:
@@ -208,35 +208,35 @@ def _check_agent_ownership(agent: str, project: str) -> Optional[str]:
         )
         with urlopen(req, timeout=10) as resp:
             data = json.loads(resp.read().decode())
-    except Exception:
-        return None  # Network error — let the RPC catch it later
+    except Exception as e:
+        return f"could not verify meshwork access ({e}); refusing to launch"
 
     if isinstance(data, dict) and data.get("error"):
         return data["error"]
+    if not isinstance(data, dict) or not data.get("ok"):
+        return "ownership check returned unexpected response; refusing to launch"
     return None
 
 
-def _try_auto_setup(agent: str, project: Optional[str] = None) -> Optional[Tuple[Path, str]]:
-    """If agent exists on the server but has no local workspace, auto-create it.
+def _resolve_user_projects_for_agent(agent: str) -> Optional[list]:
+    """Ask the server which meshworks owned by the current user have this agent.
 
-    Returns (workspace_path, project_name) on success, None on failure.
+    Returns list of dicts [{project_name, project_id, role}], or None on auth/network error.
+    Always scoped to the authenticated user (RPC enforces owner_id = caller user).
     """
     try:
-        from .setup_clients import _load_supabase_env, setup_workspace
+        from .setup_clients import _load_supabase_env
         import importlib
         secrets_mod = importlib.import_module("meshcode.secrets")
     except Exception:
         return None
 
-    import os as _os
-    profile = _os.environ.get("MESHCODE_KEYCHAIN_PROFILE") or "default"
+    profile = os.environ.get("MESHCODE_KEYCHAIN_PROFILE") or "default"
     api_key = secrets_mod.get_api_key(profile=profile)
     if not api_key:
         return None
 
     sb = _load_supabase_env()
-
-    # Ask the server which project(s) this agent belongs to
     try:
         from urllib.request import Request, urlopen
         body = json.dumps({"p_api_key": api_key, "p_agent_name": agent}).encode()
@@ -256,27 +256,36 @@ def _try_auto_setup(agent: str, project: Optional[str] = None) -> Optional[Tuple
         return None
 
     if not isinstance(data, dict) or data.get("error"):
+        return []
+    projects = data.get("projects") or []
+    return projects if isinstance(projects, list) else []
+
+
+def _try_auto_setup(agent: str, project: str) -> Optional[Tuple[Path, str]]:
+    """If agent exists on the server but has no local workspace, auto-create it.
+
+    Caller MUST pass an explicit project — this function never auto-picks one.
+    Returns (workspace_path, project_name) on success, None on failure.
+    """
+    if not project:
+        return None
+
+    try:
+        from .setup_clients import setup_workspace
+    except Exception:
         return None
 
-    projects = data.get("projects", [])
+    projects = _resolve_user_projects_for_agent(agent)
     if not projects:
         return None
 
-    # If user specified a project, filter to that one
-    if project:
-        projects = [p for p in projects if p["project_name"] == project]
-        if not projects:
-            return None
-
-    if len(projects) > 1:
-        print(f"[meshcode] Agent '{agent}' exists in multiple projects:", file=sys.stderr)
-        for p in projects:
-            print(f"[meshcode]   meshcode run {agent} --project {p['project_name']}", file=sys.stderr)
-        print(f"[meshcode] Specify which one with --project.", file=sys.stderr)
+    # Filter to the explicitly requested project. Never silently auto-pick.
+    match = [p for p in projects if p.get("project_name") == project]
+    if not match:
         return None
 
-    resolved_project = projects[0]["project_name"]
-    role = projects[0].get("role", "")
+    resolved_project = match[0]["project_name"]
+    role = match[0].get("role", "")
 
     print(f"[meshcode] Workspace recreated automatically for agent '{agent}' (project: {resolved_project})")
     rc = setup_workspace(resolved_project, agent, role)
@@ -298,50 +307,50 @@ def _load_registry() -> dict:
         return {}
 
 
-def _find_agent_workspace(agent: str, project: Optional[str] = None, quiet: bool = False) -> Optional[Tuple[Path, str]]:
-    """Look up the agent in the registry. Returns (workspace_path, project_name) or None.
+def _find_agent_workspace(agent: str, project: str, quiet: bool = False) -> Optional[Tuple[Path, str]]:
+    """Look up the agent's workspace for an EXPLICIT project. Returns (path, project) or None.
 
-    If multiple agents share the same name across projects, requires the
-    user to disambiguate by passing project explicitly.
+    Caller MUST pass project — this function never auto-picks across meshworks.
     When quiet=True, suppresses error messages (used before auto-setup fallback).
     """
+    if not project:
+        return None
+
     reg = _load_registry()
     agents = reg.get("agents", {})
 
-    # Direct hit by agent name (current model: agent names unique within registry)
     info = agents.get(agent)
-    if info:
+    if info and info.get("project") == project:
         ws = Path(info["workspace"])
-        if not ws.exists():
-            # Don't print error in quiet mode — caller will try auto-setup
-            return None
-        if project and info.get("project") != project:
-            if not quiet:
-                print(f"[meshcode] ERROR: agent '{agent}' belongs to project '{info.get('project')}', not '{project}'", file=sys.stderr)
-            return None
-        return ws, info.get("project", "")
-
-    # Fallback: scan ~/meshcode for any dir matching <project>-<agent>
-    if project:
-        ws = WORKSPACES_ROOT / f"{project}-{agent}"
         if ws.exists():
             return ws, project
-    else:
-        # Scan all workspaces for any matching <*>-<agent>
-        if WORKSPACES_ROOT.exists():
-            matches = [p for p in WORKSPACES_ROOT.iterdir() if p.is_dir() and p.name.endswith(f"-{agent}")]
-            if len(matches) == 1:
-                return matches[0], matches[0].name.rsplit(f"-{agent}", 1)[0]
-            if len(matches) > 1:
-                print(f"[meshcode] ERROR: agent '{agent}' exists in multiple projects:", file=sys.stderr)
-                for m in matches:
-                    print(f"[meshcode]   {m.name}", file=sys.stderr)
-                print(f"[meshcode] Disambiguate: meshcode run {agent} --project <name>", file=sys.stderr)
-                return None
+        # Registry points at a missing dir — caller will try auto-setup
+        return None
+
+    if info and info.get("project") != project and not quiet:
+        print(f"[meshcode] NOTE: registry has agent '{agent}' under project '{info.get('project')}', not '{project}'", file=sys.stderr)
+
+    # Filesystem fallback: ~/meshcode/<project>-<agent>
+    ws = WORKSPACES_ROOT / f"{project}-{agent}"
+    if ws.exists():
+        return ws, project
 
     return None
 
 
+def _list_local_projects_for_agent(agent: str) -> list:
+    """Return project names whose local workspace dir matches <project>-<agent>."""
+    if not WORKSPACES_ROOT.exists():
+        return []
+    out = []
+    for p in WORKSPACES_ROOT.iterdir():
+        if p.is_dir() and p.name.endswith(f"-{agent}"):
+            proj = p.name.rsplit(f"-{agent}", 1)[0]
+            if proj:
+                out.append(proj)
+    return out
+
+
 def _detect_editor() -> Optional[str]:
     """Pick the user's preferred MCP-aware editor."""
     override = os.environ.get("MESHCODE_EDITOR", "").strip().lower()
@@ -406,16 +415,70 @@ def run(agent: str, project: Optional[str] = None, editor_override: Optional[str
         print(f"[meshcode]        (or copy this exact line into a new terminal: meshcode run {agent})", file=sys.stderr)
         return 2
 
+    # ── Require explicit meshwork ────────────────────────────────────
+    # Agent names are not globally unique (e.g. "commander" exists in many
+    # meshworks). Without an explicit meshwork, we cannot safely pick one
+    # — even if only one is visible locally, another could exist on the
+    # server. Force the user to disambiguate and authenticate against a
+    # specific meshwork they own.
+    if not project:
+        print(f"[meshcode] ERROR: specify which meshwork '{agent}' belongs to.", file=sys.stderr)
+        local_projects = _list_local_projects_for_agent(agent)
+        server_projects = _resolve_user_projects_for_agent(agent) or []
+        candidates = set(local_projects) | {p.get("project_name") for p in server_projects if p.get("project_name")}
+        if candidates:
+            print(f"[meshcode] '{agent}' is available in these meshworks of yours:", file=sys.stderr)
+            for name in sorted(candidates):
+                print(f"[meshcode]   meshcode run {name}/{agent}", file=sys.stderr)
+        else:
+            print(f"[meshcode] No meshworks of yours contain agent '{agent}'.", file=sys.stderr)
+            print(f"[meshcode] Create one first:  meshcode setup <meshwork> {agent}", file=sys.stderr)
+        print(f"[meshcode] Usage: meshcode run <meshwork>/{agent}   (or --project <meshwork>)", file=sys.stderr)
+        return 2
+
     found = _find_agent_workspace(agent, project, quiet=True)
     if not found:
-        # Auto-setup: if agent exists on the server, recreate workspace
+        # Auto-setup: if agent exists on the server under THIS meshwork, recreate workspace
         found = _try_auto_setup(agent, project)
         if not found:
-            print(f"[meshcode] ERROR: no workspace found for agent '{agent}'", file=sys.stderr)
-            print(f"[meshcode]        Run `meshcode setup <project> {agent}` first.", file=sys.stderr)
+            print(f"[meshcode] ERROR: agent '{agent}' not found in meshwork '{project}' for your account.", file=sys.stderr)
+            print(f"[meshcode]        Run `meshcode setup {project} {agent}` first,", file=sys.stderr)
+            print(f"[meshcode]        or check the meshwork name at https://meshcode.io", file=sys.stderr)
             return 2
     ws, resolved_project = found
 
+    # ── Validate .mcp.json exists (required for MCP connection) ─────
+    # If .mcp.json is missing the editor launches but the agent never
+    # connects to the mesh — no error shown. Real incident: front-end
+    # agent had .mcp.json renamed to .mcp.json.bak by unknown cause.
+    mcp_json_path = ws / ".mcp.json"
+    mcp_json_bak = ws / ".mcp.json.bak"
+    if not mcp_json_path.exists():
+        # Try restoring from .bak first (cheapest fix)
+        if mcp_json_bak.exists():
+            try:
+                mcp_json_bak.rename(mcp_json_path)
+                print(f"[meshcode] Restored .mcp.json from backup (.mcp.json.bak)", file=sys.stderr)
+            except Exception as e:
+                print(f"[meshcode] WARNING: .mcp.json.bak exists but restore failed: {e}", file=sys.stderr)
+
+    if not mcp_json_path.exists():
+        # Regenerate via setup_workspace (has all data it needs from server)
+        print(f"[meshcode] .mcp.json missing from workspace — regenerating...", file=sys.stderr)
+        try:
+            from .setup_clients import setup_workspace
+            rc = setup_workspace(resolved_project, agent)
+            if rc == 0 and mcp_json_path.exists():
+                print(f"[meshcode] .mcp.json regenerated successfully.", file=sys.stderr)
+            else:
+                print(f"[meshcode] ERROR: could not regenerate .mcp.json.", file=sys.stderr)
+                print(f"[meshcode]        Run `meshcode setup {resolved_project} {agent}` manually.", file=sys.stderr)
+                return 2
+        except Exception as e:
+            print(f"[meshcode] ERROR: .mcp.json missing and regeneration failed: {e}", file=sys.stderr)
+            print(f"[meshcode]        Run `meshcode setup {resolved_project} {agent}` to fix.", file=sys.stderr)
+            return 2
+
     # ── Ownership pre-check ──────────────────────────────────────────
     # Before launching the editor, verify the caller owns this agent.
     # This prevents hijacking another user's agent in shared meshworks.
@@ -448,7 +511,11 @@ def run(agent: str, project: Optional[str] = None, editor_override: Optional[str
         from .ascii_art import generate_art, render_welcome
         from . import __version__ as cli_version
         ascii_art, agent_role, profile_color = _fetch_or_generate_art(agent, resolved_project)
-        is_cmd = "commander" in agent.lower() or "commander" in agent_role.lower()
+        _leader_haystack = (agent + ' ' + agent_role).lower()
+        _LEADER_KW = ('commander', 'lead', 'orchestrat', 'coordinator', 'coordinat',
+                       'coordinad', 'jefe', 'líder', 'lider', 'director', 'manager',
+                       'chief', 'captain', 'boss', 'head agent')
+        is_cmd = any(k in _leader_haystack for k in _LEADER_KW)
         agent_stats = _fetch_agent_stats(agent, resolved_project)
         print(render_welcome(
             agent, resolved_project, ascii_art, cli_version,

{meshcode-2.10.33 → meshcode-2.10.35}/meshcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.10.33
+Version: 2.10.35
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -26,11 +26,27 @@ Requires-Dist: cryptography>=41.0
 
 # MeshCode
 
-**Persistent AI coworkers.** MeshCode is the infrastructure that lets multiple AI agents (Claude Code, Cursor, Cline, Claude Desktop) coordinate as a real-time team — each agent is a real editor window on someone's machine, and MeshCode is the mesh between them.
+**The easiest way to connect multiple AI agents in real time so they collaborate like a team.** MeshCode is the infrastructure that lets multiple AI agents (Claude Code, Cursor, Cline, Claude Desktop) coordinate as a real-time team — each agent is a real editor window on someone's machine, and MeshCode is the mesh between them.
 
 - Docs: https://meshcode.io/docs
 - Dashboard: https://meshcode.io/dashboard
 - GitHub: https://github.com/meshcode/meshcode
+- **Why MeshCode** (positioning): [docs/WHY_MESHCODE.md](./docs/WHY_MESHCODE.md)
+- **Compare to CrewAI / AutoGen / Swarm / LangGraph**: [docs/COMPARISON.md](./docs/COMPARISON.md)
+- **Use cases** (query → solution): [docs/USE_CASES.md](./docs/USE_CASES.md)
+
+---
+
+## When to use MeshCode
+
+- **Connect multiple Claude Code instances** so they coordinate as a team
+- **Run AI agents across editors** (Claude Code + Cursor + Cline) on the same project
+- **Collaborate with a friend's AI agent** across different laptops
+- **Persistent AI coworkers** that remember across sessions, days, weeks
+- **Orchestrate an AI engineering team** (commander + backend + frontend + QA)
+- **Observe + replay** agent sessions in a hosted dashboard
+
+Not the right fit if you need a single-agent chatbot, headless batch pipelines, or enterprise SSO/SOC2 paperwork. See [docs/COMPARISON.md](./docs/COMPARISON.md) for honest trade-offs.
 
 ---
 
@@ -59,6 +75,22 @@ That's it. `meshcode go` handles everything: auth check, workspace creation, edi
 
 ---
 
+## How MeshCode compares
+
+| | MeshCode | CrewAI | AutoGen | OpenAI Swarm | Anthropic subagents |
+|---|---|---|---|---|---|
+| Persistent agents across sessions | **yes** | no | no | no | no |
+| Real editor windows (Claude Code, Cursor, Cline) | **yes** | no | no | no | partial |
+| Cross-machine collaboration | **yes** | no | no | no | no |
+| MCP-native | **yes** | no | no | no | yes |
+| Hosted dashboard (status, replay, graph) | **yes** | no | no | no | no |
+| No vendor lock-in | **yes** | yes | partial | **no (OpenAI only)** | **no (Anthropic only)** |
+| One-command setup (<30s) | **yes** | no | no | no | partial |
+
+Full comparison with LangGraph, Google A2A, and DIY → [docs/COMPARISON.md](./docs/COMPARISON.md).
+
+---
+
 ## How it works
 
 ```

{meshcode-2.10.33 → meshcode-2.10.35}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meshcode"
-version = "2.10.33"
+version = "2.10.35"
 description = "Real-time communication between AI agents — Supabase-backed CLI"
 readme = "README.md"
 license = {text = "MIT"}

meshcode-2.10.33/meshcode/meshcode_mcp/__init__.py

@@ -1,2 +0,0 @@
-"""MeshCode MCP server — exposes meshcode tools to MCP clients (Claude Code, etc)."""
-__version__ = "1.0.0"