meshcode 2.11.109__tar.gz → 2.11.110rc1__tar.gz

{meshcode-2.11.109 → meshcode-2.11.110rc1}/PKG-INFO

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

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode/__init__.py

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

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode/_stop_hook_template.py

@@ -48,6 +48,7 @@ reported commander trapped in this exact path. Two new release paths:
       connected") → human-confirmed unreachable.
 """
 import json
+import os
 import sys
 from pathlib import Path
 
@@ -469,6 +470,13 @@ def _user_explicitly_reports_mcp_failure(transcript_path, lookback_records=_UNRE
 
 
 def main():
+    # MESHCODE_AGENT_SESSION gate (task 24e3dd44): this hook is safe to install at USER
+    # scope (~/.claude/settings.json) because it NO-OPS for any Claude session that is not
+    # a meshcode agent launch. run_agent exports MESHCODE_AGENT_SESSION=1 for every agent;
+    # a human's personal `claude` session has it unset -> the loop hook never traps them.
+    # (Workspace-scope installs also inherit the env, so agent loop-survival is unchanged.)
+    if not os.environ.get("MESHCODE_AGENT_SESSION"):
+        sys.exit(0)
     raw = sys.stdin.read()
     try:
         payload = json.loads(raw) if raw else {}

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode/comms_v4.py

@@ -1797,8 +1797,15 @@ def _heartbeat_loop_pidfile(project, name):
     return Path.home() / ".meshcode" / f"heartbeat_{project}_{name}.pid"
 
 
-def _start_heartbeat_daemon(project, name):
-    """Fork a tiny background process that POSTs mc_heartbeat every 30s."""
+def _start_heartbeat_daemon(project, name, agent_pid=None):
+    """Fork a tiny background process that POSTs mc_heartbeat every 30s.
+
+    Fix A (task 24e3dd44, mesh-dev): when agent_pid is given (the long-lived claude
+    PID = connect_terminal ppid), the fork verifies that process is ALIVE before each
+    POST and self-exits when gone — so a dead agent stops showing 'online'. Windows-
+    SAFE: never os.kill(pid,0) on win32 (that TERMINATES); uses OpenProcess +
+    GetExitCodeProcess (259 == STILL_ACTIVE).
+    """
     pid_file = _heartbeat_loop_pidfile(project, name)
     pid_file.parent.mkdir(parents=True, exist_ok=True)
     # Stop any existing heartbeat
@@ -1818,7 +1825,24 @@ def _start_heartbeat_daemon(project, name):
         f"project={project!r}; name={name!r}\n"
         f"url={SUPABASE_URL!r}; key={SUPABASE_KEY!r}\n"
         f"api_key={_ak!r}\n"
+        f"agent_pid={agent_pid!r}\n"
         "import urllib.parse\n"
+        "def agent_alive():\n"
+        "    if not agent_pid: return True\n"
+        "    if sys.platform=='win32':\n"
+        "        try:\n"
+        "            import ctypes\n"
+        "            h=ctypes.windll.kernel32.OpenProcess(0x1000, False, int(agent_pid))\n"
+        "            if not h: return False\n"
+        "            code=ctypes.c_ulong()\n"
+        "            ok=ctypes.windll.kernel32.GetExitCodeProcess(h, ctypes.byref(code))\n"
+        "            ctypes.windll.kernel32.CloseHandle(h)\n"
+        "            return bool(ok) and code.value==259\n"
+        "        except Exception: return True\n"
+        "    try:\n"
+        "        os.kill(int(agent_pid),0); return True\n"
+        "    except ProcessLookupError: return False\n"
+        "    except Exception: return True\n"
         "def post(path, body):\n"
         "    req=urllib.request.Request(url+path, data=json.dumps(body).encode(),\n"
         "        headers={'apikey':key,'Authorization':'Bearer '+key,'Content-Type':'application/json','Accept-Profile':'meshcode','Content-Profile':'meshcode'}, method='POST')\n"
@@ -1856,6 +1880,8 @@ def _start_heartbeat_daemon(project, name):
         "    except Exception: return True\n"
         "pid=get_pid_for_project()\n"
         "while True:\n"
+        "    if not agent_alive():\n"
+        "        sys.exit(0)\n"
         "    if pid:\n"
         "        if not check_still_leased(pid):\n"
         "            sys.exit(0)\n"
@@ -1961,7 +1987,9 @@ def connect_terminal(project, name, role=""):
     except Exception:
         pass  # Non-critical — don't block agent boot
 
-    hb_pid = _start_heartbeat_daemon(project, name)
+    # Fix A: hand the heartbeat fork the owning claude/agent PID so it self-exits when
+    # the agent dies (instead of keeping a dead agent 'online'). ppid is that long-lived process.
+    hb_pid = _start_heartbeat_daemon(project, name, agent_pid=ppid)
 
     pending = (rpc_result or {}).get("pending_messages", 0)
     print(f"[meshcode] Connected: {name} -> {project}")
@@ -3382,6 +3410,7 @@ if __name__ == "__main__":
             proj_override = flags.get("project")
         editor_override = flags.get("editor")
         perm_override = flags.get("permission")  # bypass | safe | ask
+        repo_override = flags.get("repo")  # repo-scoped launch (cwd=repo + repo-lock hooks); task 24e3dd44
         if "--bypass" in sys.argv:
             perm_override = "bypass"
         elif "--safe" in sys.argv:
@@ -3413,7 +3442,7 @@ if __name__ == "__main__":
         autonomous = bool(flags.get("autonomous")) or autonomous_env
         import importlib
         _run = importlib.import_module("meshcode.run_agent").run
-        sys.exit(_run(agent, project=proj_override, editor_override=editor_override, permission_override=perm_override, dry_run=dry_run, autonomous=autonomous))
+        sys.exit(_run(agent, project=proj_override, editor_override=editor_override, permission_override=perm_override, dry_run=dry_run, autonomous=autonomous, repo_path=repo_override))
 
     elif cmd == "scan":
         # meshcode scan — detect identicon from stdin/clipboard and launch agent

meshcode-2.11.110rc1/meshcode/hooks/__init__.py

@@ -0,0 +1,7 @@
+"""MeshCode packaged Claude Code hook scripts (shipped as package data).
+
+Currently: repo_path_lock.py — the canonical PreToolUse repo-path lock that
+hard-locks a repo-scoped agent session to its registered repo even under
+--dangerously-skip-permissions. Installed to ~/.claude/hooks by
+run_agent.ensure_repo_lock_hook_installed() (fallback user-scope path).
+"""

meshcode-2.11.110rc1/meshcode/hooks/repo_path_lock.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""MeshCode canonical PreToolUse repo-path lock hook.
+
+Hard-locks an agent's filesystem tool calls to its registered repo path —
+EVEN under `--dangerously-skip-permissions` (bypassPermissions). This works
+because Claude Code fires PreToolUse hooks BEFORE any permission-mode check,
+and a hook returning `permissionDecision: "deny"` blocks the tool in every
+mode. settings.json `permissions.deny` does NOT survive bypass — only this hook does.
+
+Env contract (exported by the launcher):
+  MESHCODE_REPO_LOCK        absolute repo root the session is locked to.
+                            UNSET/empty -> hook is a NO-OP (fail-open).
+  MESHCODE_REPO_LOCK_ALLOW  optional os.pathsep-separated extra allowed roots.
+  MESHCODE_REPO_LOCK_BASH   "1" to also scan Bash commands (heuristic).
+Always-allowed: locked root + ALLOW entries + ~/.claude/projects + OS temp.
+"""
+import json
+import os
+import re
+import sys
+import tempfile
+
+_CYGDRIVE_RE = re.compile(r"^/cygdrive/([a-zA-Z])(?=/|$)")
+_MSYS_DRIVE_RE = re.compile(r"^/([a-zA-Z])(?=/|$)")
+
+
+def _demsys(path: str) -> str:
+    path = _CYGDRIVE_RE.sub(lambda m: m.group(1) + ":", path)
+    return _MSYS_DRIVE_RE.sub(lambda m: m.group(1) + ":", path)
+
+
+def _norm(p: str) -> str:
+    return os.path.normcase(os.path.realpath(p))
+
+
+def _resolve(path: str, cwd: str) -> str:
+    path = os.path.expanduser(_demsys(path))
+    cwd = os.path.expanduser(_demsys(cwd))
+    if not os.path.isabs(path):
+        path = os.path.join(cwd, path)
+    return _norm(path)
+
+
+def _within(target: str, root: str) -> bool:
+    if target == root:
+        return True
+    return target.startswith(root + os.sep)
+
+
+def _allowed_roots(cwd: str):
+    roots = []
+    lock = os.environ.get("MESHCODE_REPO_LOCK", "").strip()
+    if lock:
+        roots.append(_norm(lock))
+    extra = os.environ.get("MESHCODE_REPO_LOCK_ALLOW", "").strip()
+    if extra:
+        for r in extra.split(os.pathsep):
+            r = r.strip()
+            if r:
+                roots.append(_norm(r))
+    home = os.path.expanduser("~")
+    roots.append(_norm(os.path.join(home, ".claude", "projects")))
+    roots.append(_norm(tempfile.gettempdir()))
+    return roots
+
+
+_PATH_KEYS = {
+    "Read": ["file_path"],
+    "Edit": ["file_path"],
+    "Write": ["file_path"],
+    "MultiEdit": ["file_path"],
+    "NotebookEdit": ["notebook_path"],
+    "Glob": ["path"],
+    "Grep": ["path"],
+    "LS": ["path"],
+}
+
+
+def _deny(reason: str) -> None:
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }))
+    sys.exit(0)
+
+
+def _candidate_bash_paths(command: str):
+    toks = re.findall(r'"[^"]*"|\'[^\']*\'|\S+', command)
+    for t in toks:
+        t = t.strip('"\'')
+        if not t:
+            continue
+        looks_pathy = (
+            bool(_MSYS_DRIVE_RE.match(t))
+            or bool(_CYGDRIVE_RE.match(t))
+            or t.startswith("~/")
+            or t.startswith("..")
+            or "/.." in t
+            or "\\.." in t
+            or (len(t) >= 3 and t[1] == ":" and t[2] in "\\/")
+        )
+        if looks_pathy:
+            yield t
+
+
+def main() -> int:
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return 0
+
+    if not os.environ.get("MESHCODE_REPO_LOCK", "").strip():
+        return 0
+
+    tool = data.get("tool_name") or ""
+    tool_input = data.get("tool_input") or {}
+    cwd = data.get("cwd") or os.getcwd()
+    roots = _allowed_roots(cwd)
+
+    try:
+        if tool in _PATH_KEYS:
+            for key in _PATH_KEYS[tool]:
+                raw_path = tool_input.get(key)
+                if not raw_path:
+                    continue
+                target = _resolve(str(raw_path), cwd)
+                if not any(_within(target, r) for r in roots):
+                    _deny(
+                        f"repo-path lock: {tool} target '{raw_path}' is outside "
+                        f"the locked repo. Allowed root: "
+                        f"{os.environ.get('MESHCODE_REPO_LOCK')}"
+                    )
+        elif tool == "Bash" and os.environ.get("MESHCODE_REPO_LOCK_BASH", "").strip() == "1":
+            command = str(tool_input.get("command") or "")
+            for cand in _candidate_bash_paths(command):
+                target = _resolve(cand, cwd)
+                if not any(_within(target, r) for r in roots):
+                    _deny(
+                        f"repo-path lock: Bash command references '{cand}' outside "
+                        f"the locked repo ({os.environ.get('MESHCODE_REPO_LOCK')}). "
+                        f"Set MESHCODE_REPO_LOCK_BASH=0 to disable bash scanning."
+                    )
+    except SystemExit:
+        raise
+    except Exception:
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode/hostd.py

@@ -34,6 +34,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import shlex
 import shutil
 import signal as _signal
@@ -327,7 +328,26 @@ def _meshcode_bin() -> str:
     return "meshcode"
 
 
-def _spawn_agent(project: str, agent: str, headless: bool = False) -> bool:
+def _validate_repo_path(rp) -> Optional[str]:
+    """Validate a per-agent repo override (task 24e3dd44 #4, mc_agents.repo_path).
+    Returns an absolute realpath dir, or None. REJECTS (None + logs): NULL/empty, a value with a
+    double-quote or control char (injection hardening), or a path that is not an existing dir."""
+    if not rp or not isinstance(rp, str):
+        return None
+    if '"' in rp or any(ord(ch) < 0x20 for ch in rp):
+        _log(f"WARN: repo_path rejected (quote/control char): {rp!r}")
+        return None
+    try:
+        p = os.path.realpath(os.path.expanduser(rp))
+    except Exception:
+        return None
+    if not os.path.isdir(p):
+        _log(f"WARN: repo_path rejected (not a directory): {rp!r} -> {p}")
+        return None
+    return p
+
+
+def _spawn_agent(project: str, agent: str, headless: bool = False, repo_path=None) -> bool:
     """Relaunch `meshcode run <project>/<agent>`.
 
     headless=False (default): VISIBLE terminal window. Samuel must SEE it — we
@@ -338,9 +358,14 @@ def _spawn_agent(project: str, agent: str, headless: bool = False) -> bool:
 
     headless=True (Fleet Control mig404 per-agent flag): background process, NO
     window — for fleet agents that don't need a terminal (like the qa launch).
+
+    repo_path (task 24e3dd44 #4): optional per-agent repo. When set + valid, `--repo <path>` is
+    appended so `meshcode run` opens there. NULL/invalid = unchanged. Inert until mc_agents.repo_path
+    + the respawn RPC carry it.
     """
     target = f"{project}/{agent}"
     bin_ = _meshcode_bin()
+    repo = _validate_repo_path(repo_path)
     if headless:
         # background, NO terminal — UNIVERSAL macOS/Linux/Windows (task c1a6c6a8, mesh-dev specs).
         # Clean env (a stale CLAUDECODE aborts `meshcode run`); keep crash logs in a per-agent logfile
@@ -403,7 +428,8 @@ def _spawn_agent(project: str, agent: str, headless: bool = False) -> bool:
         try:
             # `python -m meshcode` (NOT the meshcode.exe shim) so the .exe isn't held open by the
             # agent -> a background `pip install -U` can replace it on Windows (task 14782bb4 #4).
-            proc = subprocess.Popen([sys.executable, "-m", "meshcode", "run", target], **kwargs)
+            argv = [sys.executable, "-m", "meshcode", "run", target] + (["--repo", repo] if repo else [])
+            proc = subprocess.Popen(argv, **kwargs)
             # LAUNCH-NO-WINDOW (task 35bee961): record the headless PID so the Stop sweep
             # (_do_stops) can hard-kill it — a headless agent has NO window for Samuel to
             # close, so desired_state='stopped' must be enforced by killing the process.
@@ -435,14 +461,17 @@ def _spawn_agent(project: str, agent: str, headless: bool = False) -> bool:
     except Exception:
         _bindir = ""
     if sys.platform == "win32":
+        # repo already validated (no '"'/control chars, real dir) -> safe to double-quote.
+        _repo_win = f' --repo "{repo}"' if repo else ''
         cmd = (f'set "CLAUDECODE=" & set "CLAUDE_CODE_SESSION=" & '
                f'set "MESHCODE_NO_UPDATE=" & set "MESHCODE_NO_AUTO_UPDATE=" & '
                + (f'set "PATH={_bindir};%PATH%" & ' if _bindir else '')
-               + f'"{sys.executable}" -m meshcode run "{target}"')
+               + f'"{sys.executable}" -m meshcode run "{target}"{_repo_win}')
     else:
+        _repo_posix = f" --repo {shlex.quote(repo)}" if repo else ''
         cmd = (f"unset CLAUDECODE CLAUDE_CODE_SESSION MESHCODE_NO_UPDATE MESHCODE_NO_AUTO_UPDATE; "
                + (f"export PATH={shlex.quote(_bindir)}:$PATH; " if _bindir else "")
-               + f"exec {shlex.quote(sys.executable)} -m meshcode run {shlex.quote(target)}")
+               + f"exec {shlex.quote(sys.executable)} -m meshcode run {shlex.quote(target)}{_repo_posix}")
     try:
         from meshcode import protocol_handler as _ph
         ok, info = _ph._spawn_terminal(cmd)
@@ -567,7 +596,7 @@ def _do_respawns(api_key: str, host_id: str) -> int:
         _old_vis_pids = _discover_agent_pids(_target) if (_is_recycle and _visible) else []
         _log(f"{'RECYCLE-RESPAWN' if _is_recycle else 'RESPAWN'} {proj}/{agent} "
              f"({'VISIBLE ' if _visible else ''}stale {c.get('heartbeat_age_s')}s, count={c.get('respawn_count')})")
-        if _spawn_agent(proj, agent, headless=_hl):
+        if _spawn_agent(proj, agent, headless=_hl, repo_path=c.get("repo_path")):
             _record_spawn(_target)  # count the terminal we just opened, against the breaker
             if _is_recycle:
                 if _visible and _old_vis_pids:
@@ -839,8 +868,14 @@ def _pid_cmdline(pid: int) -> str:
 def _discover_agent_pids(target: str) -> list:
     """Fallback PID discovery by command line, for agents spawned before this hostd
     (no recorded PID) or after a state-file loss. Matches `meshcode run <target>`.
-    Best-effort; returns [] on any failure."""
+    Best-effort; returns [] on any failure.
+
+    SAFETY (prefix-match fix, task 24e3dd44): target must match as a WHOLE token — `run <target>`
+    followed by whitespace/end/quote — NEVER a bare substring, else 'back' matches 'back-2' and a
+    downstream reaper/force-kill could KILL a healthy sibling. re.escape keeps target literal. On
+    POSIX pgrep -f is substring, so re-verify each candidate's full cmdline with the exact regex."""
     pids = []
+    tok = re.compile(r"run\s+" + re.escape(target) + r"(?=\s|$|[\"'])")
     try:
         if sys.platform == "win32":
             out = subprocess.run(
@@ -850,7 +885,7 @@ def _discover_agent_pids(target: str) -> list:
             for line in out.splitlines():
                 line = line.strip()
                 if line.startswith("CommandLine="):
-                    block_pid = ("meshcode" in line and f"run {target}" in line)
+                    block_pid = ("meshcode" in line and bool(tok.search(line)))
                 elif line.startswith("ProcessId=") and block_pid:
                     try:
                         pids.append(int(line.split("=", 1)[1]))
@@ -863,14 +898,52 @@ def _discover_agent_pids(target: str) -> list:
                 capture_output=True, text=True, timeout=8).stdout
             for ln in out.split():
                 try:
-                    pids.append(int(ln))
+                    p = int(ln)
                 except Exception:
-                    pass
+                    continue
+                # pgrep matched a substring; keep ONLY if the full cmdline has the exact token.
+                if tok.search(_pid_cmdline(p)):
+                    pids.append(p)
     except Exception:
         pass
     return pids
 
 
+def _kill_heartbeat_fork(target: str) -> None:
+    """Kill the agent's heartbeat daemon fork (Fix B, task 24e3dd44). The fork is detached into its
+    OWN session, so os.killpg(getpgid(agent_pid)) in _kill_headless_pid does NOT take it down — it
+    would keep POSTing and show a stopped agent 'online'. Stop it by its pidfile
+    heartbeat_<proj>_<name>.pid. Best-effort."""
+    try:
+        proj, _, agent = target.partition("/")
+        if not agent:
+            return
+        pidf = STATE_DIR / f"heartbeat_{proj}_{agent}.pid"
+        if not pidf.exists():
+            return
+        try:
+            hb = int(pidf.read_text(encoding="utf-8").strip())
+        except Exception:
+            hb = 0
+        if hb:
+            try:
+                if sys.platform == "win32":
+                    subprocess.run(["taskkill", "/PID", str(hb), "/F"], capture_output=True, timeout=8)
+                else:
+                    os.kill(hb, _signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+            except Exception:
+                pass
+        try:
+            pidf.unlink()
+        except Exception:
+            pass
+        _log(f"STOP {target}: stopped heartbeat fork (pid {hb or '?'})")
+    except Exception:
+        pass
+
+
 def _kill_headless_pid(target: str, pid: int) -> bool:
     """Hard-kill a recorded headless PID + its child tree. Guards against PID reuse by
     confirming the cmdline still looks like this meshcode agent. Returns True if killed."""
@@ -905,6 +978,7 @@ def _kill_headless_pid(target: str, pid: int) -> bool:
                 except Exception:
                     pass
         _log(f"STOP {target}: hard-killed headless pid {pid}")
+        _kill_heartbeat_fork(target)  # Fix B: its detached heartbeat fork won't die with the killpg
         return True
     except Exception as e:
         _log(f"WARN: STOP {target} kill pid {pid} failed: {e}")
@@ -980,8 +1054,11 @@ def _do_force_kills(api_key: str, host_id: str) -> int:
             if not pid:
                 continue
             if _FORCE_KILL_DRYRUN:
+                # SAFE-ARM logging: log the cmdline so the would-kill can be validated as a real
+                # stuck visible agent before _FORCE_KILL_DRYRUN is flipped.
                 _log(f"FORCE-KILL-DRYRUN {target}: WOULD kill visible pid {pid} (explicit human stop, "
-                     f"hb {a.get('heartbeat_age_s')}s) — log-only. Flip _FORCE_KILL_DRYRUN=False to enforce.")
+                     f"hb {a.get('heartbeat_age_s')}s) cmdline={_pid_cmdline(pid).strip()[:100]!r} — "
+                     f"log-only. Flip _FORCE_KILL_DRYRUN=False to enforce.")
             elif _kill_headless_pid(target, pid):
                 pids.pop(target, None)
                 n += 1
@@ -1037,8 +1114,11 @@ def _do_reap(api_key: str, host_id: str) -> int:
         """LOG-ONLY while _REAP_DRYRUN; else hard-kill (reuse-guard inside). Returns 1 if killed."""
         nonlocal pids
         if _REAP_DRYRUN:
-            _log(f"REAP-DRYRUN {target}: WOULD kill pid {pid} ({reason}) — log-only, no kill. "
-                 f"Flip _REAP_DRYRUN=False after confirming zero false positives.")
+            # SAFE-ARM logging: include the cmdline of what we WOULD kill so it can be validated as a
+            # true ghost/orphan — NOT a healthy agent — before flip.
+            _log(f"REAP-DRYRUN {target}: WOULD kill pid {pid} ({reason}) "
+                 f"cmdline={_pid_cmdline(pid).strip()[:100]!r} — log-only, no kill. "
+                 f"Flip _REAP_DRYRUN=False ONLY after confirming zero false positives.")
             return 0
         if _kill_headless_pid(target, pid):
             if pids.get(target) == pid:

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode/meshcode_mcp/server.py

@@ -4324,31 +4324,51 @@ def _mark_realtime_msgs_read_in_db(messages: List[Dict[str, Any]]) -> None:
     if not api_key:
         return
 
-    # Try batch first (1 RPC for N messages = ~50ms total)
-    try:
-        result = be.sb_rpc("mc_mark_messages_read_batch", {
-            "p_api_key": api_key,
-            "p_project_id": _PROJECT_ID,
-            "p_message_ids": msg_ids,
-        })
-        if result and not be.is_error(result):
-            log.debug(f"batch mark_read: {result.get('marked', 0)}/{len(msg_ids)} marked")
-            return
-        # Batch RPC returned error — fall through to individual
-        log.debug(f"batch mark_read failed: {be.get_error_message(result)}, falling back to individual")
-    except Exception as e:
-        log.debug(f"batch mark_read unavailable ({e}), falling back to individual")
+    # RE-DELIVERY FIX (2.11.110, task 01465452 / Samuel+commander 2026-06-04):
+    # mark_read IS the read-watermark. If it silently fails under DB load, the
+    # messages stay read=false and meshcode_wait RE-DELIVERS them next cycle
+    # (commander hit this 3-4x this session). Retry transient failures with a
+    # short backoff; SURFACE (WARNING) any IDs still unmarked instead of
+    # swallowing at debug — "exactly-once" delivery depends on this completing.
+    def _retry_rpc(fn, attempts=3, base=0.2):
+        last = None
+        for i in range(attempts):
+            try:
+                r = fn()
+                if not (isinstance(r, dict) and be.is_error(r)):
+                    return r, None
+                last = be.get_error_message(r)
+            except Exception as e:
+                last = str(e)
+            if i < attempts - 1:
+                _time.sleep(base * (i + 1))  # 0.2s, 0.4s — transient timeout/contention
+        return None, last
+
+    # Try batch first (1 RPC for N messages), retried on transient failure.
+    result, err = _retry_rpc(lambda: be.sb_rpc("mc_mark_messages_read_batch", {
+        "p_api_key": api_key,
+        "p_project_id": _PROJECT_ID,
+        "p_message_ids": msg_ids,
+    }))
+    if result is not None:
+        log.debug(f"batch mark_read: {result.get('marked', 0)}/{len(msg_ids)} marked")
+        return
+    log.debug(f"batch mark_read failed after retries ({err}); falling back to individual")
 
-    # Fallback: individual RPCs (N RPCs = ~N*50ms)
+    # Fallback: individual RPCs, each retried. Track stragglers so a persistent
+    # failure is VISIBLE (re-delivery is the lesser evil vs silent message loss).
+    unmarked = []
     for mid in msg_ids:
-        try:
-            be.sb_rpc("mc_mark_message_read", {
-                "p_api_key": api_key,
-                "p_project_id": _PROJECT_ID,
-                "p_message_id": mid,
-            })
-        except Exception as e:
-            log.debug(f"mark_read failed for msg {mid}: {e}")
+        _r, _e = _retry_rpc(lambda mid=mid: be.sb_rpc("mc_mark_message_read", {
+            "p_api_key": api_key,
+            "p_project_id": _PROJECT_ID,
+            "p_message_id": mid,
+        }), attempts=2)
+        if _r is None:
+            unmarked.append(mid)
+    if unmarked:
+        log.warning(f"mark_read: {len(unmarked)}/{len(msg_ids)} msgs UNMARKED after retries "
+                    f"(will re-deliver) — likely DB-load timeout: {unmarked[:5]}")
 
     # Confirm delivery (best-effort, background) — completes the
     # delivery pipeline: sent → read → confirmed.

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode/protocol_handler.py

@@ -257,8 +257,14 @@ def _spawn_terminal(cmd: str) -> tuple[bool, str]:
 # ============================================================
 # launch-batch
 # ============================================================
-def cmd_launch_batch(agent_names: Iterable[str]) -> int:
-    """meshcode launch-batch <agent_names...> — spawn one terminal each.
+def cmd_launch_batch(agent_names: Iterable[str], repo_path: Optional[str] = None) -> int:
+    """meshcode launch-batch <agent_names...> [--repo <path>] — spawn one terminal each.
+
+    repo_path (optional, core-commander launch-diff 2.11.110): if set, each agent
+    launches repo-scoped (`meshcode run <name> --repo <path>` → cwd=repo + repo-lock
+    hooks). Validated AT THIS SINK (realpath + isdir + reject '"'/control chars)
+    BEFORE shell/cmd.exe interpolation, since repo_path is USER input. Empty/None
+    => unscoped (100% legacy behavior).
 
     Returns 0 on full success, 1 if any agent failed to launch (still
     prints JSON summary to stdout).
@@ -275,6 +281,18 @@ def cmd_launch_batch(agent_names: Iterable[str]) -> int:
     # Resolve `meshcode` binary path (CLI wrapper installed by pip).
     mc_bin = shutil.which("meshcode") or "meshcode"
 
+    # SECURITY (audit P1-4): repo_path is USER input that gets interpolated into the
+    # platform launch string below. Validate AT THE SINK: canonicalize, require a
+    # real dir, reject the double-quote + control chars that could break out of the
+    # cmd.exe / shell quoting. None/empty => rp=None => unscoped (legacy behavior).
+    rp: Optional[str] = None
+    if repo_path:
+        rp = os.path.realpath(os.path.expanduser(repo_path))
+        if (not os.path.isdir(rp)) or ('"' in rp) or any(ord(c) < 32 for c in rp):
+            print(json.dumps({"ok": False, "error": f"invalid repo path: {repo_path!r}",
+                              "error_code": "invalid_repo_path"}))
+            return 1
+
     # RATE LIMIT: hard-cap the batch so a crafted `agents=` list can't spawn an
     # unbounded number of terminals (DoS). Excess is reported, never launched.
     if len(names) > _MAX_BATCH:
@@ -309,9 +327,9 @@ def cmd_launch_batch(agent_names: Iterable[str]) -> int:
         # PER-PLATFORM quoting (mesh-core FIX2): cmd.exe wants double-quotes, not POSIX shlex
         # single-quotes (cmd.exe passes single-quotes through literally -> file-not-found).
         if sys.platform == "win32":
-            cmd = f'"{mc_bin}" run "{name}"'
+            cmd = f'"{mc_bin}" run "{name}"' + (f' --repo "{rp}"' if rp else "")
         else:
-            cmd = f"{shlex.quote(mc_bin)} run {shlex.quote(name)}"
+            cmd = f"{shlex.quote(mc_bin)} run {shlex.quote(name)}" + (f" --repo {shlex.quote(rp)}" if rp else "")
         ok, info = _spawn_terminal(cmd)
         if ok:
             launched.append(name)
@@ -404,7 +422,12 @@ def cmd_launch_url(url: str) -> int:
                           "error_code": "invalid_input"}))
         return 1
 
-    return cmd_launch_batch(agents)
+    # core-commander launch-diff: optional repo= scopes every launched agent to a
+    # repo (cwd=repo + repo-lock hooks). parse_qs ALREADY URL-decodes the value, so
+    # no extra unquote here (double-decode would corrupt a path with a literal '%').
+    # Path is validated at the sink in cmd_launch_batch.
+    repo = qs.get("repo", [""])[0].strip()
+    return cmd_launch_batch(agents, repo_path=repo or None)
 
 
 # ============================================================
@@ -543,7 +566,14 @@ def main(argv: list[str]) -> int:
     sub = argv[0]
     rest = argv[1:]
     if sub == "launch-batch":
-        return cmd_launch_batch(rest)
+        # Optional `--repo <path>` (core-commander launch-diff): pull it out of the
+        # positional agent-name list; remaining tokens are agent names.
+        _repo = None
+        if "--repo" in rest:
+            _i = rest.index("--repo")
+            _repo = rest[_i + 1] if _i + 1 < len(rest) else None
+            rest = rest[:_i] + rest[_i + 2:]
+        return cmd_launch_batch(rest, repo_path=_repo)
     if sub == "launch-url":
         if not rest:
             print(json.dumps({"ok": False, "error": "url required",

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode/run_agent.py

@@ -679,7 +679,73 @@ def _preflight_heartbeat(agent: str, project: str) -> None:
         print(f"[meshcode]   Pre-flight heartbeat skipped: {e}", file=sys.stderr)
 
 
-def run(agent: str, project: Optional[str] = None, editor_override: Optional[str] = None, permission_override: Optional[str] = None, dry_run: bool = False, autonomous: bool = False) -> int:
+# Repo-scoped launch (task 24e3dd44 / core-commander launch-diff). When `meshcode run
+# <agent> --repo <path>` is used, the agent boots with cwd=repo (not the meshcode
+# workspace), so its repo CLAUDE.md loads — we carry the boot protocol via
+# --append-system-prompt so the mesh loop + rules still apply. .format(agent, project,
+# role, repo) at launch.
+MESHCODE_BOOT_PROTOCOL = """You are agent {agent} in MeshCode meshwork {project}. Role: {role}.
+You are running INSIDE the repo at {repo} (your cwd) — operate here like a normal terminal opened in this repo: read its CLAUDE.md + local memory, work here, and do NOT leave it (a hard repo-path lock denies file ops outside it).
+
+ON SESSION START (run NOW, don't idle/greet): if meshcode_* tools are deferred, FIRST call ToolSearch(query="select:meshcode_set_status,meshcode_boot,meshcode_wait,meshcode_send,meshcode_task_complete"). Then 1) meshcode_set_status(status="online",task="ready"); 2) meshcode_boot(); 3) meshcode_wait().
+
+PERMANENT LOOP (#1 rule): after boot and after EVERY action, your next tool call MUST be meshcode_wait(). act -> (optional meshcode_send) -> meshcode_wait() -> repeat. NEVER exit/stop without calling meshcode_wait(). Only exits: user says stop/sleep/exit, commander got_done/sleep auth, or fatal error. If wait times out, re-call with 2x timeout (cap 1800s).
+
+RULES: MCP tools only (don't shell out to the meshcode CLI). Tasks > messages; messages <100 tokens (signals), no empty acks, JSON, thread via in_reply_to. Close tasks immediately when done (meshcode_task_complete); work assigned tasks immediately. Sync vs async: turn-based/shared-state -> meshcode_call; informing -> meshcode_send. meshcode_remember(key,value) for reusable learnings.
+
+ALWAYS USE SKILLS + SUBAGENTS (mandatory): invoke the Skill tool whenever any skill matches (even 1%) BEFORE acting; dispatch subagents for multi-file search/audits. Samuel flagged skipping skills/subagents as underperforming — hard rule."""
+
+
+def ensure_repo_lock_hook_installed():
+    """FALLBACK (user-scope) install of the canonical repo-path lock as a PreToolUse hook in
+    ~/.claude/settings.json. SELF-GATED on MESHCODE_REPO_LOCK (the hook no-ops when unset), so
+    installing it globally is safe. Idempotent — never duplicates an existing identical command."""
+    try:
+        import importlib.resources
+        import json as _json
+        home = Path(os.path.expanduser("~"))
+        hd = home / ".claude" / "hooks"
+        hd.mkdir(parents=True, exist_ok=True)
+        dst = hd / "repo-path-lock.py"
+        dst.write_text((importlib.resources.files("meshcode.hooks") / "repo_path_lock.py").read_text("utf-8"), "utf-8")
+        py = sys.executable or "python3"
+        settings = home / ".claude" / "settings.json"
+        doc = _json.loads(settings.read_text("utf-8")) if settings.exists() else {}
+        pre = doc.setdefault("hooks", {}).setdefault("PreToolUse", [])
+        cmd = f'"{py}" "{dst}"'
+        matcher = "Read|Edit|Write|MultiEdit|NotebookEdit|Glob|Grep|LS|Bash"
+        if not any(any(h.get("command") == cmd for h in e.get("hooks", [])) for e in pre):
+            pre.append({"matcher": matcher, "hooks": [{"type": "command", "command": cmd}]})
+            settings.write_text(_json.dumps(doc, indent=2), "utf-8")
+    except Exception:
+        pass
+
+
+def ensure_loop_hook_installed():
+    """FALLBACK (user-scope) install of stay_on_loop as a Stop hook in ~/.claude/settings.json.
+    SAFE globally because STOP_HOOK_BODY now no-ops unless MESHCODE_AGENT_SESSION is set (a human's
+    personal claude session never gets trapped). Reuses the canonical STOP_HOOK_BODY. Idempotent."""
+    try:
+        from meshcode._stop_hook_template import STOP_HOOK_BODY
+        import json as _json
+        home = Path(os.path.expanduser("~"))
+        hd = home / ".claude" / "hooks"
+        hd.mkdir(parents=True, exist_ok=True)
+        dst = hd / "stay_on_loop.py"
+        dst.write_text(STOP_HOOK_BODY, "utf-8")
+        py = sys.executable or "python3"
+        settings = home / ".claude" / "settings.json"
+        doc = _json.loads(settings.read_text("utf-8")) if settings.exists() else {}
+        stop = doc.setdefault("hooks", {}).setdefault("Stop", [])
+        cmd = f'"{py}" "{dst}"'
+        if not any(any(h.get("command") == cmd for h in e.get("hooks", [])) for e in stop):
+            stop.append({"hooks": [{"type": "command", "command": cmd}]})
+            settings.write_text(_json.dumps(doc, indent=2), "utf-8")
+    except Exception:
+        pass
+
+
+def run(agent: str, project: Optional[str] = None, editor_override: Optional[str] = None, permission_override: Optional[str] = None, dry_run: bool = False, autonomous: bool = False, repo_path: Optional[str] = None) -> int:
     """Launch the user's editor with ONLY the named agent's MCP server loaded.
 
     dry_run: when True, exercise the full bootstrap codepath (auth check,
@@ -836,6 +902,33 @@ def run(agent: str, project: Optional[str] = None, editor_override: Optional[str
         except Exception:
             pass
 
+    # ── Repo-scoped launch + mesh-session hook wiring (task 24e3dd44 / core-commander) ─
+    # MESHCODE_AGENT_SESSION marks THIS process as a mesh agent launch — it gates the
+    # user-scope stay_on_loop fallback so the loop is enforced for agents but a human's
+    # personal `claude` session is NEVER trapped. Exported for EVERY launch (not only
+    # repo-scoped) so loop-survival is unconditional.
+    os.environ["MESHCODE_AGENT_SESSION"] = "1"
+    repo_lock = None
+    if repo_path:
+        _rp = os.path.realpath(os.path.expanduser(repo_path))
+        if (not os.path.isdir(_rp)) or ('"' in _rp) or any(ord(c) < 32 for c in _rp):
+            print(json.dumps({"ok": False, "error": f"invalid --repo path: {repo_path!r}",
+                              "error_code": "invalid_repo_path"}), file=sys.stderr)
+            return 2
+        repo_lock = _rp
+        os.environ["MESHCODE_REPO_LOCK"] = repo_lock
+        os.environ.setdefault("MESHCODE_REPO_LOCK_BASH", "1")
+        os.environ["MESHCODE_REPO_LOCK_ALLOW"] = os.pathsep.join(
+            [str(ws), os.path.expanduser("~/.claude/projects")])
+        print(f"[meshcode]   Repo-lock: {repo_lock} (file ops outside it are denied)", file=sys.stderr)
+    # Pre-stage BOTH user-scope fallback hooks (idempotent). repo-lock self-gates on
+    # MESHCODE_REPO_LOCK; loop gates on MESHCODE_AGENT_SESSION — so this is safe even when
+    # --settings already carries the workspace hooks (the primary path). One boot test
+    # reveals which path fires; both are wired so no recut is needed.
+    if not dry_run:
+        ensure_repo_lock_hook_installed()
+        ensure_loop_hook_installed()
+
     # ── Validate stop hook exists (required for wait-loop integrity) ─
     # If the workspace was created on an old CLI that didn't install hooks
     # (or someone wiped .claude/), Claude Code has nothing blocking turn-end
@@ -929,6 +1022,9 @@ def run(agent: str, project: Optional[str] = None, editor_override: Optional[str
     # color synchronously, so the banner gets the real color without any
     # cross-process coordination.
 
+    # Default so a banner-build failure below can't leave agent_role undefined for the
+    # repo-scoped --append-system-prompt .format() further down (task 24e3dd44).
+    agent_role = "MCP-connected agent"
     # ── Welcome banner with unique ASCII art + personality ──────────
     try:
         from .ascii_art import generate_art, render_welcome
@@ -1032,13 +1128,27 @@ def run(agent: str, project: Optional[str] = None, editor_override: Optional[str
         # instructions so the agent auto-initializes (set_status, check
         # messages, claim tasks, greet peers) without waiting for user input.
         # Uses -- to separate options from the positional prompt argument.
+        # Repo-scoped launch (task 24e3dd44 / core-commander): when --repo is set the
+        # session runs at cwd=repo (NOT the workspace), so explicitly load the workspace
+        # .mcp.json + .claude/settings.json (Stop + repo-lock hooks) via flags, and carry
+        # the mesh boot protocol via --append-system-prompt (the repo's own CLAUDE.md
+        # loads from cwd). --repo unset => none of this added => behavior 100% unchanged.
+        if repo_lock:
+            cmd += [
+                "--mcp-config", str(mcp_json_path),
+                "--settings", str(ws / ".claude" / "settings.json"),
+                "--append-system-prompt", MESHCODE_BOOT_PROTOCOL.format(
+                    agent=agent, project=resolved_project,
+                    role=(agent_role or "MCP-connected agent"), repo=repo_lock),
+            ]
         cmd.extend(["--", "boot"])
-        if not os.path.isdir(ws):
-            print(f"[meshcode] WARNING: workspace dir does not exist: {ws}", file=sys.stderr)
+        _launch_cwd = repo_lock or str(ws)
+        if not os.path.isdir(_launch_cwd):
+            print(f"[meshcode] WARNING: launch dir does not exist: {_launch_cwd}", file=sys.stderr)
         try:
-            os.chdir(ws)
+            os.chdir(_launch_cwd)
         except Exception as e:
-            print(f"[meshcode] WARNING: chdir to workspace failed: {e}", file=sys.stderr)
+            print(f"[meshcode] WARNING: chdir to {_launch_cwd} failed: {e}", file=sys.stderr)
     elif editor_stem == "cursor":
         # Cursor reads .cursor/mcp.json from the workspace cwd.
         cmd = [editor, str(ws)]

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode/setup_clients.py

@@ -24,6 +24,15 @@ from typing import Dict, Any, Optional
 
 from meshcode.exceptions import AuthError, RPCError, MeshCodeConnectionError
 from meshcode._stop_hook_template import STOP_HOOK_BODY as _STOP_HOOK_BODY
+# Repo-path lock hook body (task 24e3dd44) — read from the packaged canonical hook so the
+# workspace copy + the user-scope fallback (run_agent.ensure_repo_lock_hook_installed) stay
+# byte-identical. Best-effort: empty -> workspace just won't get the primary-path PreToolUse
+# hook (the user-scope fallback still installs it; an empty hook would fail-open anyway).
+try:
+    import importlib.resources as _ilr
+    _REPO_LOCK_BODY = (_ilr.files("meshcode.hooks") / "repo_path_lock.py").read_text("utf-8")
+except Exception:
+    _REPO_LOCK_BODY = ""
 from meshcode._session_handoff_template import (
     HANDOFF_WRITE_BODY as _HANDOFF_WRITE_BODY,
     HANDOFF_READ_BODY as _HANDOFF_READ_BODY,
@@ -345,12 +354,23 @@ def _meshcode_settings_dict() -> dict:
     """Canonical .claude/settings.json content (Stop + PreCompact +
     SessionStart hooks, all Windows-safe). Single source used by both the
     scaffolder and the patch-hooks fresh-create path."""
-    return {
+    d = {
         "hooks": {
             event: [{"hooks": [{"type": "command", "command": _hook_command(script)}]}]
             for event, script in _MESHCODE_HOOKS
         },
     }
+    # Repo-path lock (task 24e3dd44 / core-commander): PreToolUse needs a MATCHER (the other
+    # meshcode hooks are matcher-less), so it's added explicitly rather than via _MESHCODE_HOOKS.
+    # The hook self-gates on MESHCODE_REPO_LOCK -> inert for non-repo-scoped sessions, so adding
+    # it to every workspace's settings.json is safe. run_agent passes --settings <ws>/.claude/
+    # settings.json on a repo-scoped launch so this Stop+PreToolUse pair loads into the cwd=repo
+    # session (the PRIMARY path; the user-scope install is the fallback).
+    d["hooks"]["PreToolUse"] = [{
+        "matcher": "Read|Edit|Write|MultiEdit|NotebookEdit|Glob|Grep|LS|Bash",
+        "hooks": [{"type": "command", "command": _hook_command("repo_path_lock.py")}],
+    }]
+    return d
 
 
 def _heal_settings_hooks(ws: Path, dry_run: bool = False):
@@ -1354,6 +1374,10 @@ If `meshcode_wait()` times out, call it again with a 2× longer timeout (cap 180
 - `sensitive=True` for secrets / PII.
 - Memory: `meshcode_remember(key, value)` for reusable learnings. Don't dump
   task summaries into memory — tasks already persist.
+- **ALWAYS USE SKILLS + SUBAGENTS (mandatory):** invoke the Skill tool whenever
+  any skill matches (even 1%) BEFORE acting; dispatch subagents for multi-file
+  search/audits. Samuel flagged skipping skills/subagents as underperforming —
+  hard rule.
 
 ## Mobile-first UI verification (before task_complete)
 
@@ -1527,6 +1551,7 @@ Call `meshcode_wait` now.
             ("stay_on_loop.py", stop_hook_body),
             ("session_handoff_write.py", _HANDOFF_WRITE_BODY),
             ("session_handoff_read.py", _HANDOFF_READ_BODY),
+            ("repo_path_lock.py", _REPO_LOCK_BODY),  # task 24e3dd44: primary-path repo-lock (PreToolUse)
         ):
             _hp = ws / ".claude" / "hooks" / _name
             _hp.write_text(_body, encoding="utf-8")

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode.egg-info/PKG-INFO

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

{meshcode-2.11.109 → meshcode-2.11.110rc1}/meshcode.egg-info/SOURCES.txt

@@ -43,6 +43,8 @@ meshcode.egg-info/dependency_links.txt
 meshcode.egg-info/entry_points.txt
 meshcode.egg-info/requires.txt
 meshcode.egg-info/top_level.txt
+meshcode/hooks/__init__.py
+meshcode/hooks/repo_path_lock.py
 meshcode/meshcode_mcp/__init__.py
 meshcode/meshcode_mcp/__main__.py
 meshcode/meshcode_mcp/backend.py

{meshcode-2.11.109 → meshcode-2.11.110rc1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meshcode"
-version = "2.11.109"
+version = "2.11.110rc1"
 description = "Real-time communication between AI agents — Supabase-backed CLI"
 readme = "README.md"
 license = {text = "MIT"}
@@ -51,3 +51,4 @@ include = ["meshcode", "meshcode.*"]
 
 [tool.setuptools.package-data]
 meshcode = ["comms_v4.py"]
+"meshcode.hooks" = ["*.py"]