meshcode 2.10.34__tar.gz → 2.10.36__tar.gz

{meshcode-2.10.34 → meshcode-2.10.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.10.34
+Version: 2.10.36
 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.34 → meshcode-2.10.36}/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.34 → meshcode-2.10.36}/meshcode/__init__.py

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

{meshcode-2.10.34 → meshcode-2.10.36}/meshcode/comms_v4.py

@@ -1730,10 +1730,21 @@ SETUP (advanced):
   register <proj> <name> [role]              Register agent manually
   setup <client> <proj> <name> [role]        Legacy: global MCP config
 
+AGENT CONTROL:
+  scan                                       Scan identicon from clipboard → run
+  kill <proj> <name>                         Force disconnect agent
+  wake <proj> <name>                         Send wake signal
+  sleep <proj> <name>                        Send sleep signal
+  disconnect <proj> <name>                   Graceful disconnect
+  whoami                                     Show logged-in identity
+  profile [agent]                            Show/set agent profile
+  connect <proj> <name>                      Connect existing agent
+
 ADMIN:
   clear <proj> <name>                        Clear inbox
   unregister <proj> <name>                   Leave project
   prefs                                      View/set preferences
+  update                                     Check for package updates
 
 PROFILES (multi-account):
   profiles                                   List stored keychain profiles
@@ -1856,6 +1867,80 @@ Clear inbox: marks all unread messages as read for an agent.
     "unregister": """meshcode unregister <project> <name>
 
 Remove an agent from a meshwork (deletes the row from mc_agents).
+""",
+    "setup": """meshcode setup <project> <agent> [role]
+
+Create an isolated workspace at ~/meshcode/<project>-<agent>/ with
+.mcp.json configured for the agent's MCP server. Usually auto-created
+by `meshcode go`.
+
+EXAMPLES:
+  meshcode setup my-app backend "Backend Engineer"
+""",
+    "run": """meshcode run <agent> [--project <name>] [--editor claude|cursor|code]
+
+Launch an agent in your preferred editor. Detects Claude Code, Cursor,
+VS Code, Windsurf, or Codex. Use <project>/<agent> to disambiguate.
+
+EXAMPLES:
+  meshcode run backend
+  meshcode run my-app/backend --editor cursor
+""",
+    "go": """meshcode go <agent> [--project <name>]
+
+Shortcut for setup + run. Creates workspace if needed, then launches.
+
+EXAMPLES:
+  meshcode go backend
+  meshcode go my-app/frontend
+""",
+    "scan": """meshcode scan
+
+Read an agent identicon from clipboard (or stdin) and launch the agent.
+The identicon must contain a ⟨ project/agent ⟩ tag.
+
+EXAMPLES:
+  meshcode scan                    # reads from clipboard
+  cat identicon.txt | meshcode scan
+""",
+    "invite": """meshcode invite <project> <agent> [--role "..."] [--days 7]
+
+Generate an invite token for a teammate to join as a specific agent.
+--days 0 = permanent (never expires).
+
+EXAMPLES:
+  meshcode invite my-app frontend --role "React Developer" --days 7
+""",
+    "join": """meshcode join <token> [--display-name "alice"]
+
+Accept an invite and create a workspace for the assigned agent.
+
+EXAMPLES:
+  meshcode join mc_invite_abc123 --display-name "Alice"
+""",
+    "invites": """meshcode invites <project>
+
+List outstanding and redeemed invites for a meshwork.
+""",
+    "members": """meshcode members <project>
+
+List all members (owner + invited) of a meshwork.
+""",
+    "whoami": """meshcode whoami
+
+Show the currently logged-in user (email, user_id, profile).
+""",
+    "prefs": """meshcode prefs [key] [value]
+
+View or set preferences (permission-mode, auto-update, etc.).
+
+EXAMPLES:
+  meshcode prefs                          # show all
+  meshcode prefs permission-mode bypass   # set
+""",
+    "profiles": """meshcode profiles
+
+List all stored keychain profiles (default + per-meshwork guest keys).
 """,
 }
 
@@ -1981,6 +2066,9 @@ if __name__ == "__main__":
                 from_a, to_a = target.split(":", 1)
             else:
                 from_a, to_a = "?", target
+            if not message.strip():
+                print("[meshcode] ERROR: message cannot be empty. Usage: meshcode send <project> <from>:<to> <message>")
+                sys.exit(1)
             send_msg(proj, from_a, to_a, message, compact=compact)
 
     elif cmd == "broadcast":
@@ -1989,12 +2077,15 @@ if __name__ == "__main__":
             from_a = flags["from"]
             message = flags.get("msg", flags.get("message", " ".join(pos)))
             msg_type = flags.get("type", "broadcast")
-            broadcast(proj, from_a, message, msg_type)
         else:
             proj = pos[0] if len(pos) > 0 else "default"
             from_a = pos[1] if len(pos) > 1 else "?"
             message = " ".join(pos[2:]) if len(pos) > 2 else ""
-            broadcast(proj, from_a, message)
+            msg_type = "broadcast"
+        if not message.strip():
+            print("[meshcode] ERROR: message cannot be empty. Usage: meshcode broadcast <project> <from> <message>")
+            sys.exit(1)
+        broadcast(proj, from_a, message, msg_type)
 
     elif cmd == "read":
         proj = flags.get("project", pos[0] if len(pos) > 0 else "default")
@@ -2007,8 +2098,14 @@ if __name__ == "__main__":
     elif cmd == "watch":
         proj = flags.get("project", pos[0] if len(pos) > 0 else "default")
         name = flags.get("name", pos[1] if len(pos) > 1 else "agent")
-        interval = int(flags.get("interval", pos[2] if len(pos) > 2 else "10"))
-        timeout = int(flags.get("timeout", pos[3] if len(pos) > 3 else "0"))
+        try:
+            interval = int(flags.get("interval", pos[2] if len(pos) > 2 else "10"))
+        except (ValueError, TypeError):
+            interval = 10
+        try:
+            timeout = int(flags.get("timeout", pos[3] if len(pos) > 3 else "0"))
+        except (ValueError, TypeError):
+            timeout = 0
         watch(proj, name, interval, timeout)
 
     elif cmd == "board":
@@ -2230,12 +2327,15 @@ if __name__ == "__main__":
             print("    meshcode scan                  # reads from clipboard")
             print("    cat identicon.txt | meshcode scan  # reads from stdin")
             sys.exit(1)
-        # Look for ⟨ agent ⟩ or ⟨ meshwork/agent ⟩
-        match = _re.search(r'⟨\s*(\S+)\s*⟩', art_text)
-        if not match:
+        # Find ALL identicon tags, prefer the one with project/agent format.
+        # Identicons contain two tags: ⟨ agent ⟩ and ⟨ project/agent ⟩.
+        # re.search returns the first (agent-only), missing the project.
+        all_tags = _re.findall(r'⟨\s*(\S+)\s*⟩', art_text)
+        if not all_tags:
             print("[meshcode] No identicon tag found. Expected: ⟨ agent_name ⟩")
             sys.exit(1)
-        tag = match.group(1)
+        # Prefer project/agent tag, fall back to agent-only
+        tag = next((t for t in all_tags if "/" in t), all_tags[0])
         if "/" in tag:
             _proj, _agent = tag.split("/", 1)
         else:

meshcode-2.10.36/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.34 → meshcode-2.10.36}/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.34 → meshcode-2.10.36}/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
@@ -62,7 +65,7 @@ class _CircuitBreaker:
         return self.state == self.OPEN
 
 
-_circuit = _CircuitBreaker(failure_threshold=5, recovery_timeout=30.0)
+_circuit = _CircuitBreaker(failure_threshold=5, recovery_timeout=10.0)
 
 # Bake in production defaults — RLS-protected publishable key, safe to ship.
 _DEFAULT_SUPABASE_URL = "https://gjinagyyjttyxnaoavnz.supabase.co"
@@ -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.34 → meshcode-2.10.36}/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.34 → meshcode-2.10.36}/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)
@@ -898,7 +923,9 @@ meshcode_expand_link(). No sensitive msgs cross-mesh.
 
 MEMORY: meshcode_remember(key, value) persists across sessions.
 meshcode_recall(key?) retrieves. meshcode_forget(key) deletes.
-Auto-remember after each task: mistakes, feedback, patterns, preferences.
+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
@@ -912,7 +939,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 +1132,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 +1194,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}")
 
@@ -1321,6 +1400,9 @@ 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) -> 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)."""
+    if not to or not to.strip():
+        return {"error": "recipient 'to' cannot be empty"}
+    to = to.strip()
     if isinstance(message, str):
         # Auto-wrap strings into dict. Warn if very long but don't reject.
         if len(message) > 2000:
@@ -1528,6 +1610,22 @@ def _get_pending_tasks_summary() -> Optional[List[Dict[str, str]]]:
                 or t.get("assignee") == AGENT_NAME  # Directly assigned to me
             )
         ]
+        # For leader agents: also include unclaimed '*' tasks as pending
+        # so commanders auto-triage them instead of letting them pile up.
+        _leader_haystack = ((_ROLE_DESCRIPTION or '') + ' ' + AGENT_NAME).lower()
+        _LEADER_KW = ('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_KW)
+        if is_leader:
+            wildcard_tasks = [
+                {"id": t["id"][:8], "title": t["title"][:80], "priority": t.get("priority", "normal"), "status": t["status"]}
+                for t in tasks
+                if t.get("status") == "open"
+                and t.get("assignee") == "*"
+                and not t.get("claimed_by")
+            ]
+            pending.extend(wildcard_tasks)
         return pending if pending else None
     except Exception:
         return None
@@ -1553,14 +1651,22 @@ async def meshcode_wait(timeout_seconds: int = 20, include_acks: bool = False) -
     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.
     pending_tasks = _get_pending_tasks_summary()
     if pending_tasks:
-        return {
-            "refused": True,
-            "reason": "You have open tasks. Work them before entering wait.",
-            "pending_tasks": pending_tasks,
-            "count": len(pending_tasks),
-        }
+        _leader_haystack = ((_ROLE_DESCRIPTION or '') + ' ' + AGENT_NAME).lower()
+        _LEADER_KW = ('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_KW)
+        if not _is_leader:
+            return {
+                "refused": True,
+                "reason": "You have open tasks. Work them before entering wait.",
+                "pending_tasks": pending_tasks,
+                "count": len(pending_tasks),
+            }
 
     # PRODUCT RULE 2: If agent has unread messages in DB, refuse to wait.
     try:
@@ -1626,8 +1732,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 +1758,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 +1787,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 +1882,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 +1906,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()
@@ -1973,8 +2079,10 @@ def meshcode_init(project: str, agent: str, role: str = "") -> Dict[str, Any]:
 def meshcode_task_create(title: str, description: str = "", assignee: str = "*",
                           priority: str = "normal", parent_task_id: Optional[str] = None) -> Dict[str, Any]:
     """Create task. assignee="*" for any, priority: low/normal/high/urgent."""
+    if not title or not title.strip():
+        return {"error": "title cannot be empty"}
     api_key = _get_api_key()
-    result = be.task_create(api_key, _PROJECT_ID, AGENT_NAME, title,
+    result = be.task_create(api_key, _PROJECT_ID, AGENT_NAME, title.strip(),
                            description=description, assignee=assignee,
                            priority=priority, parent_task_id=parent_task_id)
     # Auto-notify assignee so they wake from meshcode_wait
@@ -2045,7 +2153,7 @@ def meshcode_task_claim(task_id: str) -> Dict[str, Any]:
 @mcp.tool()
 @with_working_status
 def meshcode_task_complete(task_id: str, summary: str = "", force: bool = False) -> Dict[str, Any]:
-    """Complete a claimed task with summary. Auto-remembers the task summary.
+    """Complete a claimed task with summary.
 
     Refuses if the task has open subtasks, unless force=True is passed with a
     reason in `summary`. This prevents closing a parent while lanes are still
@@ -2071,25 +2179,8 @@ def meshcode_task_complete(task_id: str, summary: str = "", force: bool = False)
         except Exception:
             pass  # Best-effort check; don't block on listing failure.
     result = be.task_complete(api_key, _PROJECT_ID, task_id, AGENT_NAME, summary=summary)
-    # Auto-remember task completion for future context
-    if isinstance(result, dict) and result.get("ok") and summary:
-        try:
-            import threading
-            def _auto_remember():
-                try:
-                    be.sb_rpc("mc_memory_set", {
-                        "p_api_key": api_key,
-                        "p_agent_name": AGENT_NAME,
-                        "p_key": f"task_{task_id[:8]}",
-                        "p_value": {"title": result.get("title", ""), "summary": summary, "completed": True},
-                        "p_tier": "episodic",
-                        "p_project_name": PROJECT_NAME,
-                    })
-                except Exception:
-                    pass
-            threading.Thread(target=_auto_remember, daemon=True).start()
-        except Exception:
-            pass
+    # Task data persists in the task system — do NOT duplicate to memory.
+    # Samuel: "los tasks no deben guardarse en memoria, para eso salen en tasks"
     return result
 
 
@@ -2191,6 +2282,7 @@ def meshcode_auto_wake() -> Dict[str, Any]:
     suggestions: List[Dict[str, str]] = []
 
     # 1. Check for stale agents (heartbeat >10 min, not offline/sleeping)
+    agents = []  # Initialize before try so downstream checks don't NameError
     try:
         agents = be.get_board(_PROJECT_ID)
         import datetime as _dt
@@ -2530,12 +2622,15 @@ source: meshcode
 @mcp.tool()
 @with_working_status
 def meshcode_remember(key: str, value: Any) -> Dict[str, Any]:
-    """Store a persistent memory (survives restarts). Auto-remember after each task.
+    """Store a persistent memory (survives restarts). Only for reusable learnings, NOT task data.
 
     Args:
         key: Short key (e.g. "team_conventions").
         value: Any JSON-serializable value.
     """
+    if not key or not key.strip():
+        return {"error": "key cannot be empty"}
+    key = key.strip()
     api_key = _get_api_key()
     json_value = value if isinstance(value, (dict, list)) else json.dumps(value)
     if isinstance(json_value, str):
@@ -2671,7 +2766,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.34 → meshcode-2.10.36}/meshcode/run_agent.py

@@ -447,6 +447,38 @@ def run(agent: str, project: Optional[str] = None, editor_override: Optional[str
             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.
@@ -479,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.34 → meshcode-2.10.36}/meshcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.10.34
+Version: 2.10.36
 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.34 → meshcode-2.10.36}/pyproject.toml

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

meshcode-2.10.34/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"