meshcode 2.11.62__tar.gz → 2.11.63__tar.gz

{meshcode-2.11.62 → meshcode-2.11.63}/PKG-INFO

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

{meshcode-2.11.62 → meshcode-2.11.63}/meshcode/__init__.py

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

meshcode-2.11.63/meshcode/claude_update.py

@@ -0,0 +1,253 @@
+"""Synchronous Claude Code CLI auto-update for `meshcode run`.
+
+Companion to self_update.py (which handles the `meshcode` Python package).
+When `meshcode run` launches an agent, this module probes the npm registry
+for the latest @anthropic-ai/claude-code release and runs `npm install -g`
+inline if the installed version is older. The launch BLOCKS until the
+upgrade finishes (or times out).
+
+This is intentional: Samuel's requirement is "siempre arrancar con la
+ultima version". The two-launch async model in self_update.py cannot
+satisfy that — it always uses the old binary on launch N. The blocking
+model trades ~5-30s extra latency on launches where an upgrade is
+available for the guarantee that the freshly-spawned editor uses the
+newest CLI.
+
+Skip conditions (any one → no-op):
+  - MESHCODE_NO_UPDATE=1 / --no-update on argv
+  - Inside an existing Claude Code session (CLAUDECODE=1)
+  - User pinned a specific version via env / prefs (let _resolve_pinned_claude handle it)
+  - Editor is not `claude` (cursor / code / codex / windsurf)
+  - npm not in PATH
+  - Network unreachable / npm registry down
+  - Already at latest version
+
+Failures are best-effort: any error prints a single WARN line and lets
+launch continue with whatever version is installed.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Optional, Tuple
+
+NPM_PKG = "@anthropic-ai/claude-code"
+NPM_REGISTRY_URL = f"https://registry.npmjs.org/{NPM_PKG}/latest"
+NETWORK_TIMEOUT_SEC = 2.5
+INSTALL_TIMEOUT_SEC = 90  # npm i -g can be slow on cold-cache machines
+
+STATE_DIR = Path.home() / ".meshcode"
+LOG_PATH = STATE_DIR / "claude_update.log"
+
+
+# ============================================================
+# Skip-condition helpers
+# ============================================================
+
+def _is_claude_session() -> bool:
+    """True if we're being called from inside an existing Claude Code session.
+
+    Replacing the npm binary while claude is running is unsafe and pointless
+    — the running claude won't pick up the new code anyway.
+    """
+    return os.environ.get("CLAUDECODE") == "1" or bool(os.environ.get("CLAUDE_CODE_SESSION"))
+
+
+def _update_disabled() -> bool:
+    if os.environ.get("MESHCODE_NO_UPDATE") == "1":
+        return True
+    if "--no-update" in sys.argv:
+        return True
+    return False
+
+
+def _resolve_user_pin() -> Optional[str]:
+    """Return a specific version pin if set; None if 'latest' / unset.
+
+    Sources checked (first non-empty wins):
+      1. MESHCODE_CLAUDE_VERSION env var
+      2. prefs['claude_version']
+
+    Note: 'latest' / 'none' / 'skip' values are treated as "no pin" — the
+    user wants whatever is current. We do NOT consult the global admin
+    config from mc_global_config here; if an admin pins a specific
+    version, _resolve_pinned_claude in run_agent.py will route through
+    npx regardless of what's installed locally.
+    """
+    pinned = (os.environ.get("MESHCODE_CLAUDE_VERSION") or "").strip()
+    if not pinned:
+        try:
+            from .preferences import load_prefs
+            pinned = (load_prefs().get("claude_version") or "").strip()
+        except Exception:
+            pinned = ""
+    if not pinned:
+        return None
+    if pinned.lower() in ("latest", "none", "skip"):
+        return None
+    return pinned
+
+
+# ============================================================
+# Version probes
+# ============================================================
+
+def _get_installed_version(editor_cmd: str) -> Optional[str]:
+    """Run `<editor_cmd> --version` and pull the first semver from stdout."""
+    try:
+        use_shell = sys.platform == "win32" and editor_cmd.lower().endswith((".cmd", ".bat"))
+        r = subprocess.run(
+            [editor_cmd, "--version"],
+            capture_output=True, text=True, timeout=10,
+            shell=use_shell,
+        )
+        m = re.search(r"\d+\.\d+\.\d+", r.stdout or "")
+        return m.group(0) if m else None
+    except Exception:
+        return None
+
+
+def _fetch_npm_latest() -> Optional[str]:
+    """GET https://registry.npmjs.org/<pkg>/latest — returns the JSON manifest
+    of the version tagged `latest`, with a `version` field.
+
+    Do NOT send the `application/vnd.npm.install-v1+json` Accept header
+    here: the slim-manifest content type is only valid on the package
+    ROOT (/<pkg>), not on /<pkg>/<tag>. Sending it on the tag endpoint
+    returns HTTP 406. Default Accept (*/*) gets the canonical JSON.
+    """
+    try:
+        import urllib.request
+        req = urllib.request.Request(NPM_REGISTRY_URL)
+        with urllib.request.urlopen(req, timeout=NETWORK_TIMEOUT_SEC) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        v = data.get("version")
+        if isinstance(v, str):
+            return v
+    except Exception:
+        pass
+    return None
+
+
+def _version_tuple(v: str) -> Tuple[int, ...]:
+    parts = []
+    for p in v.split("."):
+        digits = "".join(c for c in p if c.isdigit())
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts)
+
+
+def _is_newer(remote: str, local: str) -> bool:
+    try:
+        return _version_tuple(remote) > _version_tuple(local)
+    except Exception:
+        return False
+
+
+# ============================================================
+# Editor-stem detection (only act when editor is claude)
+# ============================================================
+
+def _editor_is_claude(editor_cmd: str) -> bool:
+    name = os.path.basename(editor_cmd).lower()
+    if sys.platform == "win32":
+        name = name.rsplit(".", 1)[0] if "." in name else name
+    return name == "claude"
+
+
+# ============================================================
+# Public entrypoint
+# ============================================================
+
+def check_and_maybe_update_claude_blocking(
+    editor_cmd: str,
+    verbose: bool = True,
+    timeout_sec: int = INSTALL_TIMEOUT_SEC,
+) -> Optional[str]:
+    """Probe npm + foreground-install latest claude if newer.
+
+    Returns the new version on successful upgrade, None otherwise.
+    Never raises — all errors are swallowed and logged via WARN line.
+    """
+    if _update_disabled():
+        return None
+    if _is_claude_session():
+        return None
+    if _resolve_user_pin():
+        return None
+    if not _editor_is_claude(editor_cmd):
+        return None
+
+    current = _get_installed_version(editor_cmd)
+    latest = _fetch_npm_latest()
+    if not current:
+        if verbose:
+            print(f"[meshcode] (Could not read claude --version; skipping auto-update)", file=sys.stderr)
+        return None
+    if not latest:
+        if verbose:
+            print(f"[meshcode] (Could not reach npm registry; staying on claude {current})", file=sys.stderr)
+        return None
+    if not _is_newer(latest, current):
+        if verbose:
+            print(f"[meshcode] claude {current} (already latest)", file=sys.stderr)
+        return None
+
+    npm = shutil.which("npm")
+    if not npm:
+        if verbose:
+            print(
+                f"[meshcode] WARN: claude {current} < {latest} on npm, but `npm` not in PATH; "
+                f"continuing on {current}",
+                file=sys.stderr,
+            )
+        return None
+
+    if verbose:
+        print(
+            f"[meshcode] Upgrading claude {current} -> {latest} (blocking, can take ~30s)...",
+            file=sys.stderr,
+        )
+
+    cmd = [npm, "install", "-g", f"{NPM_PKG}@{latest}"]
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        with open(LOG_PATH, "ab") as logf:
+            logf.write(
+                f"\n=== {time.strftime('%Y-%m-%d %H:%M:%S')} blocking "
+                f"npm i -g {NPM_PKG}@{latest} ===\n".encode()
+            )
+            logf.flush()
+            proc = subprocess.run(cmd, stdout=logf, stderr=logf, timeout=timeout_sec)
+        if proc.returncode == 0:
+            if verbose:
+                print(f"[meshcode]   claude upgraded to {latest}", file=sys.stderr)
+            return latest
+        if verbose:
+            print(
+                f"[meshcode] WARN: npm install exit {proc.returncode}; "
+                f"continuing on {current} (log: {LOG_PATH})",
+                file=sys.stderr,
+            )
+        return None
+    except subprocess.TimeoutExpired:
+        if verbose:
+            print(
+                f"[meshcode] WARN: npm install timed out after {timeout_sec}s; "
+                f"continuing on {current}",
+                file=sys.stderr,
+            )
+        return None
+    except Exception as e:
+        if verbose:
+            print(
+                f"[meshcode] WARN: npm install failed: {e}; continuing on {current}",
+                file=sys.stderr,
+            )
+        return None

meshcode-2.11.63/meshcode/hostd.py

@@ -0,0 +1,381 @@
+"""meshcode hostd — host-side daemon: respawn + recycle managed agents.
+
+Complements supervisor.py (launchd KeepAlive = process-exit restart only).
+hostd polls the CLOUD for staleness (heartbeat) + recycle triggers that
+launchd cannot see:
+
+  - RESPAWN: agent's heartbeat is stale (process/daemon-thread dead) and
+    desired_state='running' → relaunch. Loop-guard cap 3/10min → 'crashed'.
+  - RECYCLE: managed agent exceeds its recycle policy (context% or uptime)
+    → relaunch at a task boundary (never mid-task). Recorded separately
+    from the crash cap.
+
+Contract (mig366/367/368/369, DBA-cleared):
+  mc_register_host, mc_agents_needing_respawn, mc_record_respawn,
+  mc_record_recycle, mc_set_desired_state, mc_host_recycle_policy.
+
+Source of truth is the cloud (mc_agents / mc_host_config), never local
+folders. host_id lives in ~/.meshcode/host_id (generated once).
+
+    meshcode hostd run       — run the daemon loop (foreground)
+    meshcode hostd status    — show this host's managed agents
+    meshcode hostd install   — install launchd trigger-start plist
+    meshcode hostd uninstall — remove it
+
+Design invariants:
+  - NEVER respawn desired_state != 'running' (NULL=unmanaged, stopped=
+    intentional, crashed=gave-up). The cloud RPC enforces this; we trust it.
+  - Single retry / capped respawn — never an infinite relaunch loop.
+  - Recycle only at task boundary: we relaunch a recycle candidate only
+    when it is NOT actively working (status not in working/online-busy) OR
+    the agent has self-flagged 'recycling'. Mid-task agents are skipped.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+import urllib.request
+import uuid
+from pathlib import Path
+from typing import Optional
+
+STATE_DIR = Path.home() / ".meshcode"
+HOST_ID_PATH = STATE_DIR / "host_id"
+LOG_PATH = STATE_DIR / "hostd.log"
+
+POLL_INTERVAL_SEC = 45
+STALE_SECONDS = 150          # heartbeat liveness cutoff (QA #3)
+RESPAWN_TIMEOUT_SEC = 30
+# statuses that mean "actively working" → never recycle mid-task
+BUSY_STATUSES = {"working", "online", "busy"}
+
+
+def _log(msg: str) -> None:
+    line = f"[{time.strftime('%Y-%m-%d %H:%M:%S')}] {msg}"
+    print(line, file=sys.stderr)
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        with open(LOG_PATH, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+    except Exception:
+        pass
+
+
+def get_host_id() -> str:
+    """Read ~/.meshcode/host_id, generating a stable UUID on first use."""
+    try:
+        if HOST_ID_PATH.exists():
+            v = HOST_ID_PATH.read_text(encoding="utf-8").strip()
+            if v:
+                return v
+    except Exception:
+        pass
+    new_id = str(uuid.uuid4())
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        HOST_ID_PATH.write_text(new_id, encoding="utf-8")
+    except Exception:
+        pass
+    return new_id
+
+
+# ------------------------------------------------------------------
+# Cloud RPC (PostgREST) — self-contained urllib, no internal client dep
+# ------------------------------------------------------------------
+
+def _supabase_cfg() -> tuple:
+    url = os.environ.get("SUPABASE_URL", "").rstrip("/")
+    key = os.environ.get("SUPABASE_KEY") or os.environ.get("MESHCODE_SUPABASE_ANON_KEY") or ""
+    return url, key
+
+
+def _api_key() -> Optional[str]:
+    """The meshcode agent/user api key, used as p_api_key in mc_ RPCs."""
+    k = os.environ.get("MESHCODE_API_KEY")
+    if k:
+        return k
+    try:
+        # same source meshcode run uses (per-profile state)
+        prof = STATE_DIR / "profiles.json"
+        if prof.exists():
+            data = json.loads(prof.read_text(encoding="utf-8"))
+            # best-effort: first profile with an api_key
+            for v in (data.values() if isinstance(data, dict) else []):
+                if isinstance(v, dict) and v.get("api_key"):
+                    return v["api_key"]
+    except Exception:
+        pass
+    return None
+
+
+def _rpc(fn: str, payload: dict) -> Optional[dict]:
+    """Call a PostgREST RPC. Returns parsed JSON or None on any failure."""
+    url, key = _supabase_cfg()
+    if not url or not key:
+        _log("WARN: SUPABASE_URL/KEY not set — cannot reach cloud")
+        return None
+    try:
+        req = urllib.request.Request(
+            f"{url}/rest/v1/rpc/{fn}",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "apikey": key,
+                "Authorization": f"Bearer {key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except Exception as e:
+        _log(f"WARN: rpc {fn} failed: {e}")
+        return None
+
+
+# ------------------------------------------------------------------
+# Respawn
+# ------------------------------------------------------------------
+
+def _meshcode_bin() -> str:
+    cand = Path(sys.argv[0]).resolve()
+    if cand.exists() and cand.name.startswith("meshcode"):
+        return str(cand)
+    return "meshcode"
+
+
+def _spawn_agent(project: str, agent: str) -> bool:
+    """Relaunch `meshcode run <project>/<agent>` detached + visible-friendly."""
+    target = f"{project}/{agent}"
+    env = dict(os.environ)
+    # env hygiene (item1 RC): a stale CLAUDECODE aborts `meshcode run` (exit2)
+    env.pop("CLAUDECODE", None)
+    env.pop("CLAUDE_CODE_SESSION", None)
+    env["MESHCODE_NO_AUTO_UPDATE"] = env.get("MESHCODE_NO_AUTO_UPDATE", "1")
+    try:
+        subprocess.Popen(
+            [_meshcode_bin(), "run", target],
+            env=env, start_new_session=True,
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        )
+        return True
+    except Exception as e:
+        _log(f"WARN: spawn {target} failed: {e}")
+        return False
+
+
+def _do_respawns(api_key: str, host_id: str) -> int:
+    """One respawn sweep. Returns number relaunched."""
+    res = _rpc("mc_agents_needing_respawn",
+               {"p_api_key": api_key, "p_host_id": host_id, "p_stale_seconds": STALE_SECONDS})
+    if not res or not res.get("ok"):
+        return 0
+    n = 0
+    for c in res.get("candidates", []):
+        proj, agent = c.get("project_name"), c.get("agent")
+        if not proj or not agent:
+            continue
+        if not c.get("respawn_allowed", True):
+            _log(f"SKIP respawn {proj}/{agent}: cap reached (count={c.get('respawn_count')})")
+            rec = _rpc("mc_record_respawn",
+                       {"p_api_key": api_key, "p_project_id": c.get("project_id"), "p_agent_name": agent})
+            if rec and rec.get("give_up"):
+                _rpc("mc_set_desired_state", {"p_api_key": api_key, "p_state": "crashed"})
+                _log(f"ALERT {proj}/{agent}: marked crashed after respawn cap — operator attention")
+            continue
+        _log(f"RESPAWN {proj}/{agent} (stale {c.get('heartbeat_age_s')}s)")
+        if _spawn_agent(proj, agent):
+            _rpc("mc_record_respawn",
+                 {"p_api_key": api_key, "p_project_id": c.get("project_id"), "p_agent_name": agent})
+            n += 1
+    return n
+
+
+# ------------------------------------------------------------------
+# Recycle — relaunch a managed agent at a TASK BOUNDARY when it exceeds
+# its recycle policy. Uptime-recycle is daemon-driven (needs mig370's
+# project_name in the roster). Context-recycle is agent-cooperative (the
+# agent self-persists handoff + exits at a boundary; our respawn path then
+# relaunches it). Recorded via mc_record_recycle — NEVER counted against
+# the crash respawn cap.
+# ------------------------------------------------------------------
+
+_HOSTD_STATE_PATH = STATE_DIR / "hostd_state.json"
+
+
+def _load_state() -> dict:
+    try:
+        if _HOSTD_STATE_PATH.exists():
+            return json.loads(_HOSTD_STATE_PATH.read_text(encoding="utf-8"))
+    except Exception:
+        pass
+    return {}
+
+
+def _save_state(st: dict) -> None:
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        _HOSTD_STATE_PATH.write_text(json.dumps(st), encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _do_recycles(api_key: str, host_id: str) -> int:
+    """Uptime-based recycle at task boundary. Returns number recycled."""
+    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
+    pol = _rpc("mc_host_recycle_policy", {"p_api_key": api_key, "p_host_id": host_id})
+    mode = (pol or {}).get("recycle_mode")
+    value = (pol or {}).get("recycle_value")
+    if mode != "time" or not value:
+        return 0  # context-recycle is agent-cooperative; only time is daemon-driven
+    st = _load_state()
+    now = time.time()
+    n = 0
+    seen = set()
+    for a in cfg.get("agents", []):
+        if a.get("desired_state") != "running":
+            continue
+        proj, agent = a.get("project_name"), a.get("name")
+        if not proj or not agent:
+            continue
+        key = f"{a.get('project_id')}/{agent}"
+        seen.add(key)
+        first = st.get(key)
+        if first is None:
+            st[key] = now  # start the uptime clock on first observation
+            continue
+        if (a.get("status") or "") in BUSY_STATUSES:
+            continue  # task boundary only — never mid-task
+        if (now - first) >= float(value) * 3600.0:
+            _log(f"RECYCLE {proj}/{agent} (uptime {(now-first)/3600:.1f}h >= {value}h)")
+            if _spawn_agent(proj, agent):
+                _rpc("mc_record_recycle",
+                     {"p_api_key": api_key, "p_project_id": a.get("project_id"), "p_agent_name": agent})
+                st[key] = now  # reset clock after recycle
+                n += 1
+    # prune state for agents no longer managed on this host
+    for k in [k for k in st if k not in seen]:
+        st.pop(k, None)
+    _save_state(st)
+    return n
+
+
+# ------------------------------------------------------------------
+# launchd trigger-start (macOS) — extends supervisor.py pattern.
+# The hostd daemon is NOT autostart-at-login: RunAtLoad=false. It is
+# kicked off on demand (button -> meshcode:// -> `launchctl kickstart`)
+# and KeepAlive keeps it alive while it runs. One job per host.
+# ------------------------------------------------------------------
+
+_HOSTD_PLIST_LABEL = "io.meshcode.hostd"
+
+
+def _hostd_plist_path():
+    return Path.home() / "Library" / "LaunchAgents" / f"{_HOSTD_PLIST_LABEL}.plist"
+
+
+def _hostd_plist_xml() -> str:
+    import shutil
+    mc = shutil.which("meshcode") or f"{sys.executable} -m meshcode"
+    args = (mc.split() + ["hostd", "run"]) if " -m " in mc else [mc, "hostd", "run"]
+    args_xml = "\n".join(f"        <string>{a}</string>" for a in args)
+    logdir = STATE_DIR / "logs"
+    logdir.mkdir(parents=True, exist_ok=True)
+    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>{_HOSTD_PLIST_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+{args_xml}
+    </array>
+    <key>RunAtLoad</key><false/>
+    <key>KeepAlive</key><true/>
+    <key>ThrottleInterval</key><integer>10</integer>
+    <key>StandardOutPath</key><string>{logdir / "hostd.stdout.log"}</string>
+    <key>StandardErrorPath</key><string>{logdir / "hostd.stderr.log"}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key><string>/usr/local/bin:/usr/bin:/bin:{os.path.dirname(sys.executable)}</string>
+        <key>MESHCODE_NO_AUTO_UPDATE</key><string>1</string>
+    </dict>
+</dict>
+</plist>
+"""
+
+
+def _hostd_install() -> int:
+    import platform
+    if platform.system() != "Darwin":
+        print("[hostd] launchd install is macOS only (Linux: use systemd --user; or run `meshcode hostd run` under your own supervisor).", file=sys.stderr)
+        return 2
+    plist = _hostd_plist_path()
+    plist.parent.mkdir(parents=True, exist_ok=True)
+    plist.write_text(_hostd_plist_xml(), encoding="utf-8")
+    subprocess.run(["launchctl", "unload", str(plist)], capture_output=True, text=True)
+    r = subprocess.run(["launchctl", "load", str(plist)], capture_output=True, text=True)
+    if r.returncode != 0:
+        print(f"[hostd] launchctl load failed: {r.stderr.strip()}", file=sys.stderr)
+        return 1
+    print(f"[hostd] installed (RunAtLoad=false, trigger-start). plist: {plist}")
+    print(f"[hostd] start now:  launchctl kickstart gui/$(id -u)/{_HOSTD_PLIST_LABEL}")
+    return 0
+
+
+def _hostd_uninstall() -> int:
+    plist = _hostd_plist_path()
+    if not plist.exists():
+        print("[hostd] not installed")
+        return 0
+    subprocess.run(["launchctl", "unload", str(plist)], capture_output=True, text=True)
+    plist.unlink(missing_ok=True)
+    print("[hostd] uninstalled")
+    return 0
+
+
+def cmd_hostd(args: list) -> int:
+    """Entry point for `meshcode hostd ...`."""
+    if not args or args[0] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    sub = args[0]
+    host_id = get_host_id()
+    api_key = _api_key()
+
+    if sub == "status":
+        if not api_key:
+            print("[hostd] no api key configured", file=sys.stderr)
+            return 1
+        res = _rpc("mc_agents_needing_respawn",
+                   {"p_api_key": api_key, "p_host_id": host_id, "p_stale_seconds": STALE_SECONDS})
+        print(json.dumps({"host_id": host_id, "needing_respawn": res}, indent=2))
+        return 0
+
+    if sub == "install":
+        return _hostd_install()
+
+    if sub == "uninstall":
+        return _hostd_uninstall()
+
+    if sub == "run":
+        if not api_key:
+            _log("FATAL: no api key — set MESHCODE_API_KEY")
+            return 1
+        _log(f"hostd starting — host_id={host_id} interval={POLL_INTERVAL_SEC}s stale={STALE_SECONDS}s")
+        while True:
+            try:
+                relaunched = _do_respawns(api_key, host_id)
+                recycled = _do_recycles(api_key, host_id)
+                if relaunched or recycled:
+                    _log(f"sweep done — {relaunched} respawned, {recycled} recycled")
+            except Exception as e:
+                _log(f"WARN: sweep error: {e}")
+            time.sleep(POLL_INTERVAL_SEC)
+
+    print(f"[hostd] unknown subcommand: {sub}", file=sys.stderr)
+    return 1