meshcode 2.11.108__tar.gz → 2.11.110rc1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.11.108
+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.108 → meshcode-2.11.110rc1}/meshcode/__init__.py

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

{meshcode-2.11.108 → 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.108 → 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.108 → 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)
@@ -561,11 +590,17 @@ def _do_respawns(api_key: str, host_id: str) -> int:
                 except Exception:
                     pass
             continue
+        # Part 2 (Samuel req #2): for a VISIBLE recycle, snapshot the OLD window
+        # pid(s) BEFORE spawning the fresh one — so the new pid is never in the
+        # close set (commander q1: never touch the fresh terminal).
+        _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:
+                    _close_old_visible_recycle(_target, _old_vis_pids)  # close old window (DRY-RUN first)
                 _rpc("mc_record_recycle",
                      {"p_api_key": api_key, "p_project_id": c.get("project_id"), "p_agent_name": agent})
                 n += 1
@@ -667,6 +702,69 @@ def _recycle_blocked(st, target, now=None):
     return None
 
 
+# Samuel rule 2026-06-04: never recycle a CONNECTED agent (live MCP session) except
+# the >3h uptime lifecycle. BUSY_STATUSES (working/online/busy) MISSES a connected-
+# but-idle agent (status idle/standby, window open, heartbeat fresh) — a fresh
+# heartbeat is the stronger 'live session' signal, so an idle-but-connected agent
+# was being version-recycled out from under the user (the storm he kept seeing).
+_CONNECTED_HEARTBEAT_S = _env_int("MESHCODE_CONNECTED_HEARTBEAT_SEC", 60, 10)
+
+
+def _agent_connected(a) -> bool:
+    """True if the agent has a live MCP session: an explicitly-busy status OR a
+    very-recent heartbeat (window open even when idle/standby)."""
+    if (a.get("status") or "") in BUSY_STATUSES:
+        return True
+    hb = a.get("heartbeat_age_s")
+    try:
+        return hb is not None and float(hb) < _CONNECTED_HEARTBEAT_S
+    except (TypeError, ValueError):
+        return False
+
+
+# Part 2 (Samuel req #2 2026-06-04): on a VISIBLE recycle, close the OLD window so
+# old+new don't both stay open (audit gap 6a203baa). DRY-RUN first (commander q2 +
+# reaper safe-arm pattern): log-only until the logs confirm it's ONLY the old pid.
+_CLOSE_OLD_VISIBLE_DRYRUN = True
+
+
+def _pid_alive(pid) -> bool:
+    if not pid:
+        return False
+    try:
+        os.kill(int(pid), 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True   # exists, owned by another uid — treat as alive (don't guess)
+    except Exception:
+        return False
+
+
+def _close_old_visible_recycle(target: str, old_pids) -> int:
+    """Close the OLD window's still-alive process on a VISIBLE recycle. `old_pids`
+    is the PRE-SPAWN snapshot, so the freshly-opened window's pid is excluded by
+    construction — we NEVER touch the fresh terminal (commander q1). Graceful
+    self-exit (the stop-hook ends the session on must_exit=recycle) is PRIMARY
+    (q3): an already-exited old pid is skipped. DRY-RUN first (q2): log the
+    would-close pid; flip _CLOSE_OLD_VISIBLE_DRYRUN=False to arm once logs show
+    it's only the old pid. Real kill reuses _kill_headless_pid's cmdline guard."""
+    n = 0
+    for pid in old_pids:
+        if not _pid_alive(pid):
+            continue  # already self-closed gracefully (q3 primary) — nothing to do
+        if _CLOSE_OLD_VISIBLE_DRYRUN:
+            _log(f"CLOSE-OLD-VISIBLE-DRYRUN {target}: WOULD close old window pid {pid} "
+                 f"(visible recycle; fresh window already spawned + excluded) — log-only. "
+                 f"Flip _CLOSE_OLD_VISIBLE_DRYRUN=False after confirming it's ONLY the old pid.")
+            continue
+        if _kill_headless_pid(target, pid):
+            _log(f"CLOSE-OLD-VISIBLE {target}: closed old window pid {pid} (visible recycle; kept fresh window)")
+            n += 1
+    return n
+
+
 def _spawn_rate_ok(target: str):
     """Anti-spam circuit breaker. Returns (ok, tripped_burst, reason).
 
@@ -770,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(
@@ -781,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]))
@@ -794,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."""
@@ -836,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}")
@@ -911,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
@@ -968,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:
@@ -1054,6 +1203,9 @@ def _do_recycle_enforce(api_key: str, host_id: str) -> int:
     agent (headless_pids, with _kill_headless_pid's reuse-guard) — NEVER blind cmdline. After the
     kill it goes stale and the recycle FAST-PATH in _do_respawns relaunches it within seconds ->
     SessionStart restores the handoff. Returns number force-killed."""
+    # DEAD-FEATURE (task 222b1b02, Samuel 2026-06-04): RECYCLE disabled in prod — hard no-op
+    # (no recycles are triggered, so there is nothing to enforce). Crash-RESPAWN unaffected.
+    return 0
     res = _rpc("mc_recycle_enforce_candidates", {"p_api_key": api_key, "p_host_id": host_id})
     if not res or not res.get("ok"):
         return 0
@@ -1099,6 +1251,11 @@ def _do_recycle_enforce(api_key: str, host_id: str) -> int:
 
 def _do_recycles(api_key: str, host_id: str) -> int:
     """Uptime-based recycle at task boundary. Returns number recycled."""
+    # DEAD-FEATURE (task 222b1b02, Samuel 2026-06-04): the RECYCLE feature is disabled in
+    # prod (unreliable — kept causing version/env-mismatch storms). Hard no-op in source so
+    # it stays dead even if a schedule row reappears. Crash-RESPAWN (_do_respawns) is
+    # UNAFFECTED — only RECYCLE triggers are killed.
+    return 0
     cfg = _rpc("mc_host_config_get", {"p_api_key": api_key, "p_host_id": host_id})
     if not cfg or not cfg.get("ok"):
         return 0
@@ -1489,6 +1646,10 @@ def _do_version_recycles(api_key: str, host_id: str) -> int:
     mid-task), rate-limited (<=1 version-recycle per agent / 30min), recycle-not-kill (clean handoff via
     mc_request_recycle -> agent exits at its boundary -> _do_respawns relaunches on the new version).
     Recorded via mc_record_recycle (NEVER counts against the mig406 crash respawn cap). Owner-scoped."""
+    # DEAD-FEATURE (task 222b1b02, Samuel 2026-06-04): RECYCLE disabled in prod — hard no-op.
+    # This was the env-mismatch storm source; fixed-at-source via run_agent env-sync, but the
+    # whole recycle feature is being removed per owner. Crash-RESPAWN is unaffected.
+    return 0
     cfg = _rpc("mc_host_config_get", {"p_api_key": api_key, "p_host_id": host_id})
     if not cfg or not cfg.get("ok"):
         return 0
@@ -1513,8 +1674,10 @@ def _do_version_recycles(api_key: str, host_id: str) -> int:
                 continue  # agent already on the on-disk version (or newer) — nothing to do
         except Exception:
             continue
-        if (a.get("status") or "") in BUSY_STATUSES:
-            continue  # safe-point ONLY — never recycle a working agent mid-task
+        if _agent_connected(a):
+            continue  # Samuel rule: never version-recycle a CONNECTED agent (live MCP session,
+                      # even if idle/standby) — the >3h uptime lifecycle (_do_recycles) is the
+                      # only recycle that may touch a connected agent.
         proj, agent = a.get("project_name"), a.get("name")
         if not proj or not agent:
             continue