meshcode 2.11.94__tar.gz → 2.11.97__tar.gz

{meshcode-2.11.94 → meshcode-2.11.97}/PKG-INFO

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

{meshcode-2.11.94 → meshcode-2.11.97}/meshcode/__init__.py

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

meshcode-2.11.97/meshcode/daemon.py

@@ -0,0 +1,492 @@
+"""MeshCode autonomy v1 — headless wake daemon.
+
+Per-agent background daemon that polls `mc_agent_should_wake` every ~60s and
+spawns `meshcode run <project> <agent>` only when the backend reports real
+work (urgent task, scheduled action, unread P0 broadcast, kicked status).
+
+Layout:
+  Darwin: ~/Library/LaunchAgents/io.meshcode.daemon.<project>.<agent>.plist
+  Linux:  ~/.config/systemd/user/meshcode-daemon-<project>-<agent>.{service,timer}
+
+The plist/timer fires `meshcode daemon-tick <project> <agent>` every 60s. The
+tick is short-lived: it asks the RPC, checks anti-flap, and either exits or
+spawns a detached agent process. The agent runs its own session and exits
+when meshcode_wait returns must_exit=True. The daemon stays asleep between
+ticks — zero LLM tokens consumed during idle.
+
+Anti-flap:
+  - PID file at ~/.meshcode/daemons/<project>.<agent>.json carries last_spawn_at,
+    consecutive_failures.
+  - 30s hold-down: never re-spawn within 30s of the last spawn.
+  - Failure backoff: after 3 consecutive spawn failures inside 5 min, the
+    daemon suspends itself for 15 min before retrying.
+"""
+from __future__ import annotations
+
+import json
+import os
+import platform
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+HOME = Path.home()
+DAEMON_STATE_DIR = HOME / ".meshcode" / "daemons"
+CREDS_PATH = HOME / ".meshcode" / "credentials.json"
+
+LAUNCHD_DIR = HOME / "Library" / "LaunchAgents"
+SYSTEMD_DIR = HOME / ".config" / "systemd" / "user"
+
+POLL_INTERVAL_SECONDS = 60
+HOLD_DOWN_SECONDS = 30
+FAILURE_WINDOW_SECONDS = 300
+FAILURE_BACKOFF_SECONDS = 900
+MAX_FAILURES = 3
+
+
+def _label(project: str, agent: str) -> str:
+    return f"io.meshcode.daemon.{project}.{agent}"
+
+
+def _systemd_unit_name(project: str, agent: str) -> str:
+    return f"meshcode-daemon-{project}-{agent}"
+
+
+def _plist_path(project: str, agent: str) -> Path:
+    return LAUNCHD_DIR / f"{_label(project, agent)}.plist"
+
+
+def _systemd_service_path(project: str, agent: str) -> Path:
+    return SYSTEMD_DIR / f"{_systemd_unit_name(project, agent)}.service"
+
+
+def _systemd_timer_path(project: str, agent: str) -> Path:
+    return SYSTEMD_DIR / f"{_systemd_unit_name(project, agent)}.timer"
+
+
+def _state_path(project: str, agent: str) -> Path:
+    return DAEMON_STATE_DIR / f"{project}.{agent}.json"
+
+
+def _read_state(project: str, agent: str) -> dict:
+    p = _state_path(project, agent)
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text())
+    except Exception:
+        return {}
+
+
+def _write_state(project: str, agent: str, state: dict) -> None:
+    DAEMON_STATE_DIR.mkdir(parents=True, exist_ok=True)
+    _state_path(project, agent).write_text(json.dumps(state, indent=2))
+
+
+def _meshcode_bin() -> str:
+    """Best-effort: prefer the meshcode console_script on PATH; fall back to
+    `python -m meshcode`."""
+    from shutil import which
+
+    found = which("meshcode")
+    if found:
+        return found
+    return f"{sys.executable} -m meshcode"
+
+
+def _plist_xml(project: str, agent: str) -> str:
+    label = _label(project, agent)
+    log_dir = HOME / ".meshcode" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_out = log_dir / f"daemon.{project}.{agent}.out.log"
+    log_err = log_dir / f"daemon.{project}.{agent}.err.log"
+    bin_parts = _meshcode_bin().split()
+    program_args = "\n    ".join(f"<string>{p}</string>" for p in bin_parts) + (
+        f"\n    <string>daemon-tick</string>\n    <string>{project}</string>\n    <string>{agent}</string>"
+    )
+    # Bake current env into the plist so the headless tick can reach the
+    # backend without relying on the user's shell rc files.
+    sb_url = os.environ.get("SUPABASE_URL", "")
+    sb_key = os.environ.get("SUPABASE_KEY") or os.environ.get("SUPABASE_ANON_KEY") or ""
+    extra_env = ""
+    if sb_url:
+        extra_env += f"\n    <key>SUPABASE_URL</key><string>{sb_url}</string>"
+    if sb_key:
+        extra_env += f"\n    <key>SUPABASE_KEY</key><string>{sb_key}</string>"
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>{label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    {program_args}
+  </array>
+  <key>StartInterval</key><integer>{POLL_INTERVAL_SECONDS}</integer>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><false/>
+  <key>StandardOutPath</key><string>{log_out}</string>
+  <key>StandardErrorPath</key><string>{log_err}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+    <key>HOME</key><string>{HOME}</string>
+    <key>PYTHONUNBUFFERED</key><string>1</string>
+    <key>PYTHONIOENCODING</key><string>utf-8</string>{extra_env}
+  </dict>
+</dict>
+</plist>
+"""
+
+
+def _systemd_service(project: str, agent: str) -> str:
+    bin_cmd = _meshcode_bin()
+    sb_url = os.environ.get("SUPABASE_URL", "")
+    sb_key = os.environ.get("SUPABASE_KEY") or os.environ.get("SUPABASE_ANON_KEY") or ""
+    env_lines = ""
+    if sb_url:
+        env_lines += f"\nEnvironment=SUPABASE_URL={sb_url}"
+    if sb_key:
+        env_lines += f"\nEnvironment=SUPABASE_KEY={sb_key}"
+    return f"""[Unit]
+Description=MeshCode autonomy daemon ({project}/{agent})
+
+[Service]
+Type=oneshot{env_lines}
+ExecStart={bin_cmd} daemon-tick {project} {agent}
+StandardOutput=append:{HOME}/.meshcode/logs/daemon.{project}.{agent}.out.log
+StandardError=append:{HOME}/.meshcode/logs/daemon.{project}.{agent}.err.log
+"""
+
+
+def _systemd_timer(project: str, agent: str) -> str:
+    return f"""[Unit]
+Description=MeshCode autonomy daemon timer ({project}/{agent})
+
+[Timer]
+OnBootSec=30
+OnUnitActiveSec={POLL_INTERVAL_SECONDS}
+AccuracySec=10
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _run(cmd: list[str]) -> tuple[int, str, str]:
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=15)
+        return p.returncode, p.stdout, p.stderr
+    except Exception as e:
+        return 1, "", str(e)
+
+
+def cmd_install(project: str, agent: str) -> int:
+    if not project or not agent:
+        print("[daemon] ERROR: usage: meshcode daemon install <project> <agent>", file=sys.stderr)
+        return 2
+    DAEMON_STATE_DIR.mkdir(parents=True, exist_ok=True)
+    (HOME / ".meshcode" / "logs").mkdir(parents=True, exist_ok=True)
+
+    sysname = platform.system()
+    if sysname == "Darwin":
+        LAUNCHD_DIR.mkdir(parents=True, exist_ok=True)
+        plist = _plist_path(project, agent)
+        plist.write_text(_plist_xml(project, agent))
+        print(f"[daemon] wrote {plist}")
+        _run(["launchctl", "unload", str(plist)])
+        rc, _, err = _run(["launchctl", "load", "-w", str(plist)])
+        if rc != 0:
+            print(f"[daemon] launchctl load failed: {err}", file=sys.stderr)
+            return rc
+        print(f"[daemon] launchd registered: {_label(project, agent)} (poll {POLL_INTERVAL_SECONDS}s)")
+        return 0
+    elif sysname == "Linux":
+        SYSTEMD_DIR.mkdir(parents=True, exist_ok=True)
+        svc = _systemd_service_path(project, agent)
+        tmr = _systemd_timer_path(project, agent)
+        svc.write_text(_systemd_service(project, agent))
+        tmr.write_text(_systemd_timer(project, agent))
+        print(f"[daemon] wrote {svc} + {tmr}")
+        _run(["systemctl", "--user", "daemon-reload"])
+        rc, _, err = _run(["systemctl", "--user", "enable", "--now", tmr.name])
+        if rc != 0:
+            print(f"[daemon] systemctl enable failed: {err}", file=sys.stderr)
+            return rc
+        print(f"[daemon] systemd timer enabled: {tmr.name}")
+        return 0
+    else:
+        print(f"[daemon] ERROR: unsupported platform '{sysname}'. Darwin/Linux only.", file=sys.stderr)
+        return 2
+
+
+def cmd_uninstall(project: str, agent: str) -> int:
+    if not project or not agent:
+        print("[daemon] ERROR: usage: meshcode daemon uninstall <project> <agent>", file=sys.stderr)
+        return 2
+    sysname = platform.system()
+    if sysname == "Darwin":
+        plist = _plist_path(project, agent)
+        if plist.exists():
+            _run(["launchctl", "unload", str(plist)])
+            plist.unlink()
+            print(f"[daemon] removed {plist}")
+        else:
+            print("[daemon] plist not present")
+        return 0
+    elif sysname == "Linux":
+        svc = _systemd_service_path(project, agent)
+        tmr = _systemd_timer_path(project, agent)
+        _run(["systemctl", "--user", "disable", "--now", tmr.name])
+        for p in (svc, tmr):
+            if p.exists():
+                p.unlink()
+                print(f"[daemon] removed {p}")
+        _run(["systemctl", "--user", "daemon-reload"])
+        return 0
+    else:
+        print(f"[daemon] ERROR: unsupported platform '{sysname}'.", file=sys.stderr)
+        return 2
+
+
+def cmd_status(project: str, agent: str) -> int:
+    if not project or not agent:
+        print("[daemon] ERROR: usage: meshcode daemon status <project> <agent>", file=sys.stderr)
+        return 2
+    state = _read_state(project, agent)
+    sysname = platform.system()
+    print(f"[daemon] {project}/{agent}")
+    if sysname == "Darwin":
+        plist = _plist_path(project, agent)
+        if plist.exists():
+            rc, out, _ = _run(["launchctl", "list", _label(project, agent)])
+            print(f"  launchd: {'loaded' if rc == 0 else 'not loaded'}")
+        else:
+            print("  launchd: not installed")
+    elif sysname == "Linux":
+        tmr = _systemd_timer_path(project, agent)
+        if tmr.exists():
+            rc, out, _ = _run(["systemctl", "--user", "is-active", tmr.name])
+            print(f"  systemd timer: {out.strip() or 'unknown'}")
+        else:
+            print("  systemd timer: not installed")
+    if state:
+        last_spawn = state.get("last_spawn_at", 0)
+        since = time.time() - last_spawn if last_spawn else None
+        print(f"  last_spawn: {since:.0f}s ago" if since else "  last_spawn: never")
+        print(f"  consecutive_failures: {state.get('consecutive_failures', 0)}")
+        if state.get("backoff_until", 0) > time.time():
+            print(f"  backoff_until: {int(state['backoff_until'] - time.time())}s remaining")
+    return 0
+
+
+def _load_api_key() -> str:
+    env_key = os.environ.get("MESHCODE_API_KEY", "")
+    if env_key:
+        return env_key
+    if CREDS_PATH.exists():
+        try:
+            return json.loads(CREDS_PATH.read_text()).get("api_key", "") or ""
+        except Exception:
+            return ""
+    return ""
+
+
+def _should_wake(api_key: str, project_id: str, agent: str) -> dict:
+    """Call mc_agent_should_wake via Supabase REST. Lightweight — no SDK
+    dependencies inside the daemon hot path."""
+    import urllib.request
+    import urllib.error
+
+    supabase_url = os.environ.get("SUPABASE_URL") or _supabase_url_from_env()
+    supabase_key = os.environ.get("SUPABASE_KEY") or _supabase_key_from_env()
+    if not (supabase_url and supabase_key):
+        return {"ok": False, "should_wake": False, "error": "no_supabase_env"}
+    body = json.dumps({
+        "p_api_key": api_key,
+        "p_project_id": project_id,
+        "p_agent_name": agent,
+    }).encode()
+    req = urllib.request.Request(
+        f"{supabase_url}/rest/v1/rpc/mc_agent_should_wake",
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "apikey": supabase_key,
+            "Authorization": f"Bearer {supabase_key}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as r:
+            return json.loads(r.read().decode())
+    except urllib.error.HTTPError as e:
+        return {"ok": False, "should_wake": False, "http": e.code, "error": e.reason}
+    except Exception as e:
+        return {"ok": False, "should_wake": False, "error": str(e)}
+
+
+def _supabase_url_from_env() -> str:
+    """No hardcoded fallback — wrong project ref would silently misroute the
+    tick. Caller must export SUPABASE_URL or have it baked into the launchd /
+    systemd EnvironmentVariables."""
+    return os.environ.get("SUPABASE_URL", "")
+
+
+def _supabase_key_from_env() -> str:
+    # Daemon avoids embedding service-role; use the anon publishable key.
+    return os.environ.get("SUPABASE_KEY") or os.environ.get("SUPABASE_ANON_KEY") or ""
+
+
+def _resolve_project_id(api_key: str, project_name: str) -> str:
+    """Resolve project name → uuid via mc_resolve_project (read-only, gated by
+    api_key). Cached in daemon state to avoid an extra round-trip per tick."""
+    state = _read_state(project_name, "_resolver")
+    cached = state.get("project_id")
+    if cached:
+        return cached
+    import urllib.request
+
+    supabase_url = _supabase_url_from_env()
+    supabase_key = _supabase_key_from_env()
+    if not (supabase_url and supabase_key):
+        return ""
+    body = json.dumps({"p_api_key": api_key, "p_project_name": project_name}).encode()
+    req = urllib.request.Request(
+        f"{supabase_url}/rest/v1/rpc/mc_resolve_project",
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "apikey": supabase_key,
+            "Authorization": f"Bearer {supabase_key}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as r:
+            payload = json.loads(r.read().decode())
+            project_id = payload.get("project_id") or payload.get("id") or ""
+            if project_id:
+                _write_state(project_name, "_resolver", {"project_id": project_id})
+            return project_id
+    except Exception:
+        return ""
+
+
+def _spawn_agent(project: str, agent: str) -> bool:
+    """Detached `meshcode run <agent>` so the agent owns its own lifetime.
+    Daemon does NOT wait — the launchd/systemd tick just kicked off the spawn
+    and exits."""
+    bin_cmd = _meshcode_bin().split()
+    args = bin_cmd + ["run", project, agent]
+    log_dir = HOME / ".meshcode" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    out = open(log_dir / f"agent.{project}.{agent}.out.log", "ab", buffering=0)
+    err = open(log_dir / f"agent.{project}.{agent}.err.log", "ab", buffering=0)
+    try:
+        subprocess.Popen(
+            args,
+            stdout=out,
+            stderr=err,
+            stdin=subprocess.DEVNULL,
+            start_new_session=True,
+            close_fds=True,
+        )
+        return True
+    except Exception as e:
+        print(f"[daemon] spawn failed: {e}", file=sys.stderr)
+        return False
+
+
+def cmd_tick(project: str, agent: str) -> int:
+    """One iteration of the wake loop. Designed to be called by launchd /
+    systemd at POLL_INTERVAL_SECONDS cadence."""
+    if not project or not agent:
+        print("[daemon-tick] ERROR: usage: meshcode daemon-tick <project> <agent>", file=sys.stderr)
+        return 2
+    now = time.time()
+    state = _read_state(project, agent)
+
+    backoff_until = state.get("backoff_until", 0)
+    if backoff_until and now < backoff_until:
+        return 0
+
+    api_key = _load_api_key()
+    if not api_key:
+        print("[daemon-tick] no api_key (run `meshcode login <key>` first)", file=sys.stderr)
+        return 1
+
+    project_id = _resolve_project_id(api_key, project)
+    if not project_id:
+        print(f"[daemon-tick] could not resolve project '{project}'", file=sys.stderr)
+        return 1
+
+    resp = _should_wake(api_key, project_id, agent)
+    should = bool(resp.get("should_wake"))
+    if not should:
+        return 0
+
+    last_spawn = state.get("last_spawn_at", 0)
+    if now - last_spawn < HOLD_DOWN_SECONDS:
+        return 0
+
+    spawned = _spawn_agent(project, agent)
+    state["last_spawn_at"] = now
+    if spawned:
+        state["consecutive_failures"] = 0
+        state.pop("backoff_until", None)
+        state["last_reasons"] = resp.get("reasons", [])
+        _write_state(project, agent, state)
+        print(f"[daemon-tick] spawned {project}/{agent} reasons={resp.get('reasons')}")
+        return 0
+
+    fails = state.get("consecutive_failures", 0) + 1
+    # If the prior burst is older than the failure window, treat this as a
+    # fresh first failure so backoff math is monotonic.
+    first = state.get("first_failure_at", 0)
+    if fails == 1 or (first and now - first > FAILURE_WINDOW_SECONDS):
+        state["first_failure_at"] = now
+        first = now
+        fails = 1
+    state["consecutive_failures"] = fails
+    state["last_failure_at"] = now
+    if fails >= MAX_FAILURES and now - first < FAILURE_WINDOW_SECONDS:
+        state["backoff_until"] = now + FAILURE_BACKOFF_SECONDS
+        # Clear the burst so the next failure cycle starts fresh.
+        state.pop("first_failure_at", None)
+        state["consecutive_failures"] = 0
+        print(f"[daemon-tick] entering {FAILURE_BACKOFF_SECONDS}s backoff after {fails} failures")
+    _write_state(project, agent, state)
+    return 1
+
+
+def main(argv: list[str]) -> int:
+    if not argv:
+        print(
+            "usage:\n"
+            "  meshcode daemon install <project> <agent>\n"
+            "  meshcode daemon uninstall <project> <agent>\n"
+            "  meshcode daemon status <project> <agent>\n"
+            "  meshcode daemon-tick <project> <agent>   # internal, fired by launchd/systemd",
+            file=sys.stderr,
+        )
+        return 2
+    sub = argv[0]
+    proj = argv[1] if len(argv) > 1 else ""
+    name = argv[2] if len(argv) > 2 else ""
+    if sub == "install":
+        return cmd_install(proj, name)
+    if sub == "uninstall":
+        return cmd_uninstall(proj, name)
+    if sub == "status":
+        return cmd_status(proj, name)
+    if sub == "tick":
+        return cmd_tick(proj, name)
+    print(f"[daemon] unknown subcommand: {sub}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

{meshcode-2.11.94 → meshcode-2.11.97}/meshcode/hostd.py

@@ -403,13 +403,23 @@ def _spawn_agent(project: str, agent: str, headless: bool = False) -> bool:
     # on ';' -> file-not-found. Layered ON TOP of the 2.11.72 headless-flags fix (visible branch only).
     # task 14782bb4: CLEAR any inherited NO_*UPDATE (so the agent auto-updates non-blocking) and run
     # via `python -m meshcode` (NOT the .exe shim) so a bg `pip install -U` can replace meshcode.exe.
+    # RELIABILITY (commander, REOPEN_PATH_bug): the VISIBLE spawn must also put the meshcode
+    # console script on PATH (a8efddeb fixed only the headless branch). Without it the spawned
+    # agent + its `meshcode mcp` child die with "meshcode not on PATH". Prepend sys.executable's
+    # bin dir, mirroring the headless POSIX fix + the win32 venv-Scripts injection.
+    try:
+        _bindir = str(Path(sys.executable).resolve().parent)
+    except Exception:
+        _bindir = ""
     if sys.platform == "win32":
         cmd = (f'set "CLAUDECODE=" & set "CLAUDE_CODE_SESSION=" & '
                f'set "MESHCODE_NO_UPDATE=" & set "MESHCODE_NO_AUTO_UPDATE=" & '
-               f'"{sys.executable}" -m meshcode run "{target}"')
+               + (f'set "PATH={_bindir};%PATH%" & ' if _bindir else '')
+               + f'"{sys.executable}" -m meshcode run "{target}"')
     else:
         cmd = (f"unset CLAUDECODE CLAUDE_CODE_SESSION MESHCODE_NO_UPDATE MESHCODE_NO_AUTO_UPDATE; "
-               f"exec {shlex.quote(sys.executable)} -m meshcode run {shlex.quote(target)}")
+               + (f"export PATH={shlex.quote(_bindir)}:$PATH; " if _bindir else "")
+               + f"exec {shlex.quote(sys.executable)} -m meshcode run {shlex.quote(target)}")
     try:
         from meshcode import protocol_handler as _ph
         ok, info = _ph._spawn_terminal(cmd)
@@ -446,9 +456,15 @@ def _do_respawns(api_key: str, host_id: str) -> int:
         # PROMPTLY (the RPC returned it at a 15s stale gate, not STALE_SECONDS) and recorded as a
         # RECYCLE (mc_record_recycle), NEVER against the crash respawn cap.
         _is_recycle = bool(c.get("recycle_fast"))
+        # 798dd1bd: on-demand recycle with recycle_visible -> reopen a FRESH VISIBLE window
+        # (Samuel's "terminals reopen fresh"); else PRESERVE the agent's headless state
+        # (don't silently un-headless a headless fleet — backend2 A2). One-shot: mc_record_recycle
+        # clears recycle_visible so subsequent respawns use the normal headless flag.
+        _visible = _is_recycle and bool(c.get("recycle_visible"))
+        _hl = False if _visible else bool(c.get("headless"))
         _log(f"{'RECYCLE-RESPAWN' if _is_recycle else 'RESPAWN'} {proj}/{agent} "
-             f"(stale {c.get('heartbeat_age_s')}s, count={c.get('respawn_count')})")
-        if _spawn_agent(proj, agent, headless=bool(c.get("headless"))):
+             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 _is_recycle:
                 _rpc("mc_record_recycle",
                      {"p_api_key": api_key, "p_project_id": c.get("project_id"), "p_agent_name": agent})
@@ -515,13 +531,38 @@ def _record_headless_pid(target: str, pid: int) -> None:
     try:
         st = _load_state()
         pids = st.get("headless_pids") or {}
-        pids[target] = pid
+        pids[target] = pid          # overwrite any stale entry for this target (refresh on respawn)
         st["headless_pids"] = pids
         _save_state(st)
     except Exception:
         pass
 
 
+def _gc_headless_pids() -> None:
+    """GC dead PIDs from headless_pids (cb90b058) so a stale entry can't mask a live agent +
+    the recorded PID stays accurate for enforce. Cheap; runs once per sweep. Best-effort."""
+    try:
+        st = _load_state()
+        pids = st.get("headless_pids") or {}
+        if not pids:
+            return
+        live = {}
+        for target, pid in pids.items():
+            try:
+                os.kill(int(pid), 0)   # raises ProcessLookupError if the PID is gone
+                live[target] = pid
+            except (ProcessLookupError, ValueError):
+                pass                    # dead / bad -> drop
+            except Exception:
+                live[target] = pid      # alive (PermissionError) or unknown -> keep (reuse-guard covers kill-time)
+        if len(live) != len(pids):
+            st["headless_pids"] = live
+            _save_state(st)
+            _log(f"GC headless_pids: dropped {len(pids)-len(live)} dead PID(s)")
+    except Exception:
+        pass
+
+
 def _pid_cmdline(pid: int) -> str:
     """Best-effort command line for a pid (to avoid killing a reused PID). '' on failure."""
     try:
@@ -1206,6 +1247,7 @@ def cmd_hostd(args: list) -> int:
                         recycled = _do_recycles(api_key, host_id)
                         ver_recycled = _do_version_recycles(api_key, host_id)
                         stopped = _do_stops(api_key, host_id)
+                        _gc_headless_pids()  # cb90b058: drop dead PIDs (stale entry can't mask a live agent)
                         _up = int(time.monotonic() - _spawn_mono)
                         if relaunched or recycled or ver_recycled or stopped or enforced:
                             _log(f"sweep done (uptime={_up}s) — {relaunched} respawned, {recycled} recycled, {ver_recycled} version-recycled, {stopped} stopped, {enforced} recycle-enforced")