meshcode 2.11.136__tar.gz → 2.11.137__tar.gz

{meshcode-2.11.136 → meshcode-2.11.137}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: meshcode
-Version: 2.11.136
+Version: 2.11.137
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -18,17 +18,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Requires-Dist: mcp[cli]>=1.0.0
-Requires-Dist: websockets>=12.0
-Requires-Dist: realtime>=2.0.0
-Requires-Dist: keyring>=24.0
-Requires-Dist: cryptography>=41.0
 Provides-Extra: test
-Requires-Dist: pytest>=8; extra == "test"
 Provides-Extra: dev
-Requires-Dist: build>=1.0; extra == "dev"
-Requires-Dist: twine>=4; extra == "dev"
-Requires-Dist: pytest>=8; extra == "dev"
 
 # MeshCode
 

{meshcode-2.11.136 → meshcode-2.11.137}/meshcode/__init__.py

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

meshcode-2.11.137/meshcode/helper_visuals.py

@@ -0,0 +1,142 @@
+"""Helper terminal visuals (task d8f8e325 — Samuel msgs edf0ed8d + 68c7fee0).
+
+ENJAMBRE helpers must open VISUALLY DISTINCT from top-level agents on every
+platform, so a wall of fleet tabs reads instantly: amber = ephemeral helper,
+normal = real agent. Two layers (both silent-degrade — a visuals failure must
+NEVER break a spawn):
+
+  [1] UNIVERSAL — `meshcode run` emits OSC 0/2 (title "helper:<name>") +
+      OSC 11 (dark-amber background) at session start. Works in Windows
+      Terminal, iTerm2 and most xterm-compatible Linux terminals regardless
+      of which launcher opened the window; terminals that ignore OSC 11
+      (e.g. macOS Terminal.app) still get the title.
+  [2] PER-PLATFORM at spawn — Windows Terminal gets `--tabColor <amber>` +
+      `--title helper:<name>` on the fleet tab; the Linux/macOS launcher
+      scripts prepend the same OSC prelude so the tint applies even before
+      `meshcode run` boots.
+
+HOW A SPAWNER KNOWS IT'S A HELPER (no agent_kind in the spawn payloads —
+probed live 2026-06-12: mc_agents_needing_respawn candidates and
+mc_host_config_get agents carry no kind field):
+
+  - MARKER FILE: swarm.spawn_helper() runs on the PARENT's host, which is the
+    same host the helper spawns on (W5: helper row inherits the parent's
+    host/repo). It stamps ~/.meshcode/helpers/<name>.json with the helper's
+    TTL; spawners treat a FRESH marker as "helper". TTL expiry is the
+    cleanup (helpers are ephemeral by contract, TTL <= 86400).
+  - NAME PREFIX fallback: a name starting with 'helper' counts even without
+    a marker (covers cross-host edge cases + the observed naming convention).
+
+Tradeoff (documented): a top-level agent that shares a helper's bare name on
+the same host within the marker TTL would render amber — cosmetic only, and
+name collisions are already rejected server-side within a meshwork.
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+# Spec colors (task d8f8e325): amber tab; dark-amber background tint that
+# keeps default light-on-dark text readable.
+HELPER_TAB_COLOR = "#E8A33D"
+HELPER_BG_COLOR = "#3A2310"
+HELPER_TITLE_PREFIX = "helper:"
+
+_MARKER_TTL_CAP_S = 86400  # mirror of the server-side helper TTL ceiling
+
+
+def _helpers_dir() -> Path:
+    """Marker directory, behind a function so tests can patch it."""
+    return Path.home() / ".meshcode" / "helpers"
+
+
+def _safe_name(name: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_.-]", "_", (name or "").strip()).strip("_")[:80]
+
+
+def mark_helper(name: str, ttl_seconds: int = 3600) -> None:
+    """Stamp <name> as a helper on THIS host (called by swarm.spawn_helper).
+    Best-effort: never raises. Opportunistically prunes expired markers."""
+    try:
+        safe = _safe_name(name)
+        if not safe:
+            return
+        d = _helpers_dir()
+        d.mkdir(parents=True, exist_ok=True)
+        ttl = max(60, min(int(ttl_seconds or 3600), _MARKER_TTL_CAP_S))
+        (d / f"{safe}.json").write_text(
+            json.dumps({"name": name, "expires_at": time.time() + ttl}),
+            encoding="utf-8")
+        for p in d.glob("*.json"):
+            try:
+                if float(json.loads(p.read_text(encoding="utf-8"))
+                         .get("expires_at", 0)) < time.time():
+                    p.unlink()
+            except Exception:
+                continue
+    except Exception:
+        pass
+
+
+def unmark_helper(name: str) -> None:
+    """Drop the marker (helper retired). Best-effort."""
+    try:
+        safe = _safe_name(name)
+        if safe:
+            (_helpers_dir() / f"{safe}.json").unlink(missing_ok=True)
+    except Exception:
+        pass
+
+
+def is_helper(target: str) -> bool:
+    """True when `target` (bare 'name' or 'project/name') is a swarm helper:
+    fresh marker on this host OR the 'helper' name prefix. Never raises."""
+    try:
+        agent = (target or "").rsplit("/", 1)[-1].strip()
+        if not agent:
+            return False
+        if agent.lower().startswith("helper"):
+            return True
+        p = _helpers_dir() / f"{_safe_name(agent)}.json"
+        if not p.exists():
+            return False
+        data = json.loads(p.read_text(encoding="utf-8"))
+        return float(data.get("expires_at", 0)) >= time.time()
+    except Exception:
+        return False
+
+
+def helper_title(target: str) -> str:
+    """Tab/window title for a helper: 'helper:<bare name>' (sanitized)."""
+    agent = _safe_name((target or "").rsplit("/", 1)[-1])
+    return f"{HELPER_TITLE_PREFIX}{agent or 'agent'}"[:48]
+
+
+def osc_prelude(target: str) -> str:
+    """Escape string: OSC 0 title + OSC 11 background. Terminals that don't
+    support either sequence ignore it (that IS the degradation path)."""
+    return (f"\x1b]0;{helper_title(target)}\x07"
+            f"\x1b]11;{HELPER_BG_COLOR}\x07")
+
+
+def osc_prelude_shell(target: str) -> str:
+    """The same prelude as a POSIX-shell `printf` command (for launcher
+    scripts / bash -lc command strings). Title is sanitized [A-Za-z0-9_.-:]
+    so it can never break out of the single quotes."""
+    return ("printf '\\033]0;%s\\007\\033]11;%s\\007' 2>/dev/null || true"
+            % (helper_title(target), HELPER_BG_COLOR))
+
+
+def emit_osc(target: str) -> None:
+    """Universal layer: write the prelude to the live terminal from
+    `meshcode run`. Best-effort, TTY-gated (a piped/CI stdout never sees
+    escape garbage)."""
+    try:
+        if sys.stdout.isatty():
+            sys.stdout.write(osc_prelude(target))
+            sys.stdout.flush()
+    except Exception:
+        pass

{meshcode-2.11.136 → meshcode-2.11.137}/meshcode/hostd.py

@@ -41,6 +41,7 @@ import signal as _signal
 import subprocess
 import sys
 import time
+import urllib.error
 import urllib.request
 import uuid
 from pathlib import Path
@@ -170,6 +171,14 @@ LOG_PATH = STATE_DIR / "hostd.log"
 _HOSTD_STARTED_AT = time.time()
 _BOOT_AUTOSTART = os.environ.get("MESHCODE_BOOT_AUTOSTART", "").strip().lower() in ("1", "true", "yes", "on")
 
+# task 89d50a14 [B] FAIL-CLOSED anti-self-spawn: when PID discovery ERRORS (psutil
+# broken AND the native fallback raised — e.g. wmic removed on Win11 24H2 before
+# the Get-CimInstance fallback existed), an empty result does NOT mean "no live
+# session"; spawning on it is exactly the double-session zombie. Default: skip
+# the spawn that sweep. This env opts back into the old spawn-blind behavior —
+# escape hatch for a host where discovery can never work but respawn must.
+_DISCOVERY_FAIL_OPEN = os.environ.get("MESHCODE_DISCOVERY_FAIL_OPEN", "").strip().lower() in ("1", "true", "yes", "on")
+
 def _env_poll_interval() -> int:
     # task 399d7b51 SPEED: poll faster so click->desired_state->spawn latency drops (was 45s).
     # Env-configurable (survives upgrade); floor 3s so we never hammer the DB.
@@ -468,6 +477,16 @@ def _rpc(fn: str, payload: dict) -> Optional[dict]:
         )
         with urllib.request.urlopen(req, timeout=15) as resp:
             return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        # task 89d50a14 [E]: log the PostgREST error BODY, not just the status line.
+        # mc_log_respawn_event failed 400 for DAYS and the cause (42804 host_id
+        # uuid-vs-text) was undiagnosable from "HTTP Error 400: Bad Request" alone.
+        try:
+            body = e.read().decode("utf-8", "replace").strip()[:300]
+        except Exception:
+            body = ""
+        _log(f"WARN: rpc {fn} failed: {e}" + (f" — {body}" if body else ""))
+        return None
     except Exception as e:
         _log(f"WARN: rpc {fn} failed: {e}")
         return None
@@ -628,6 +647,18 @@ _MAX_SPAWNS_PER_SWEEP = 3
 # session, so the SKIP line prints once per agent instead of every ~10s sweep.
 _TOMBSTONE_LOGGED: set = set()
 
+# task 89d50a14 [E]: boot-stale leftovers (desired_state='running' from a PRIOR
+# session, e.g. concreta-app/studio fleets never explicitly stopped) re-qualify
+# as candidates EVERY ~10s sweep forever — the skip line printed ~15-19 times
+# per sweep and grew hostd.log to ~40MB. Same once-per-target-per-session
+# discipline as _TOMBSTONE_LOGGED. The skip itself still happens every sweep.
+_BOOTSTALE_LOGGED: set = set()
+
+# task 89d50a14 [B]: discovery fail-closed already logged this session (per
+# target) — the FAIL-CLOSED skip repeats every sweep while the candidate
+# persists; log + telemetry only on the first one, clear on recovery.
+_DISCOVERY_ERR_LOGGED: set = set()
+
 
 def _do_respawns(api_key: str, host_id: str) -> int:
     """One respawn sweep. Returns number relaunched."""
@@ -695,10 +726,20 @@ def _do_respawns(api_key: str, host_id: str) -> int:
             _hb_age = c.get("heartbeat_age_s")
             _alive_on_our_watch = _hb_age is not None and _hb_age < _hostd_uptime
             if (_spawn_age is None or _spawn_age >= _hostd_uptime) and not _alive_on_our_watch:
-                _log(f"BOOT-AUTOSTART OFF: skip auto-respawn {proj}/{agent} (desired_state=running set "
-                     f"before this hostd start — boot-stale leftover; explicit launch required). "
-                     f"Set MESHCODE_BOOT_AUTOSTART=1 to auto-launch at boot.")
+                # log-once per target per daemon session (task 89d50a14 [E]) — this
+                # skip repeats every ~10s sweep for every stale fleet and was the
+                # main feeder of the ~40MB hostd.log.
+                _bs_target = f"{proj}/{agent}"
+                if _bs_target not in _BOOTSTALE_LOGGED:
+                    _BOOTSTALE_LOGGED.add(_bs_target)
+                    _log(f"BOOT-AUTOSTART OFF: skip auto-respawn {_bs_target} (desired_state=running set "
+                         f"before this hostd start — boot-stale leftover; explicit launch required). "
+                         f"Set MESHCODE_BOOT_AUTOSTART=1 to auto-launch at boot. "
+                         f"(logged once per agent per session; skip repeats silently)")
                 continue
+            # an explicit launch / live heartbeat got this target past the gate —
+            # if it ever goes boot-stale again, the skip deserves a fresh line.
+            _BOOTSTALE_LOGGED.discard(f"{proj}/{agent}")
         # RECYCLE FAST-PATH (task c0fc5597): a recycle-exited agent (recycle_fast) is relaunched
         # 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.
@@ -786,7 +827,20 @@ def _do_respawns(api_key: str, host_id: str) -> int:
                 _cv.pop("blocked_ts", None)
                 _cv["count"] = 0  # TTL elapsed -> one clean retry; re-blocks if it storms again
             # LIVE-SESSION GUARD: never stack a second terminal on a still-alive session.
-            _live = [p for p in _discover_agent_pids(_target) if _pid_alive(p)]
+            # task 89d50a14 [B]: discovery that ERRORED returns an untrustworthy empty
+            # list — fail closed (skip this sweep) instead of concluding "no live session".
+            _live_d = _discover_agent_pids_ex(_target)
+            if _live_d["errored"] and not _DISCOVERY_FAIL_OPEN:
+                if _target not in _DISCOVERY_ERR_LOGGED:
+                    _DISCOVERY_ERR_LOGGED.add(_target)
+                    _log(f"SPAWN-AUDIT {_target}: DISCOVERY ERRORED (path={_live_d['path']}; "
+                         f"{_live_d['error']}) — FAIL-CLOSED: cannot prove no live session, NOT "
+                         f"spawning; retrying every sweep (set MESHCODE_DISCOVERY_FAIL_OPEN=1 to "
+                         f"spawn blind). [respawn_blocked_reason=discovery_error] (logged once)")
+                    _log_respawn_event(api_key, host_id, c, "respawn", "failed", "discovery_error",
+                                       detail=f"live-guard path={_live_d['path']}: {_live_d['error'][:300]}")
+                continue
+            _live = [p for p in _live_d["pids"] if _pid_alive(p)]
             if _live:
                 _hold_all = dict(_st2.get("respawn_hold") or {})
                 _hold = dict(_hold_all.get(_target) or {})
@@ -884,8 +938,27 @@ def _do_respawns(api_key: str, host_id: str) -> int:
         # MESHCODE_NO_SPAWN_RECONCILE), spawning anyway IS the double-session bug —
         # skip this sweep and retry on the next one (the survivor either dies then
         # or reconnects and stops qualifying as a respawn candidate).
-        _still_alive = [p for p in (_discover_agent_pids(_target) + _discover_serve_pids(_target))
-                        if _pid_alive(p)]
+        _ag_d = _discover_agent_pids_ex(_target)
+        _sv_d = _discover_serve_pids_ex(_target)
+        # task 89d50a14 [B] FAIL-CLOSED: an errored discovery proves NOTHING about
+        # live sessions — spawning on its empty result is the double-session bug
+        # with extra steps. Skip the spawn; the candidate re-qualifies next sweep.
+        if (_ag_d["errored"] or _sv_d["errored"]) and not _DISCOVERY_FAIL_OPEN:
+            if _target not in _DISCOVERY_ERR_LOGGED:
+                _DISCOVERY_ERR_LOGGED.add(_target)
+                _log(f"SPAWN-AUDIT {_target}: DISCOVERY ERRORED (agent path={_ag_d['path']}; "
+                     f"{_ag_d['error'] or '-'} | serve: {_sv_d['error'] or '-'}) — FAIL-CLOSED: "
+                     f"cannot prove no live session, NOT spawning; retrying every sweep "
+                     f"(set MESHCODE_DISCOVERY_FAIL_OPEN=1 to spawn blind). "
+                     f"[respawn_blocked_reason=discovery_error] (logged once)")
+                _log_respawn_event(api_key, host_id, c,
+                                   "recycle_respawn" if _is_recycle else "respawn",
+                                   "failed", "discovery_error",
+                                   detail=(f"pre-spawn path={_ag_d['path']}: "
+                                           f"{(_ag_d['error'] or _sv_d['error'])[:300]}"))
+            continue
+        _DISCOVERY_ERR_LOGGED.discard(_target)  # discovery healthy again → re-arm the log-once
+        _still_alive = [p for p in (_ag_d["pids"] + _sv_d["pids"]) if _pid_alive(p)]
         if _still_alive:
             _log(f"SPAWN-AUDIT {_target}: SKIP spawn — live session still present after "
                  f"reconcile (pids {_still_alive}); retry next sweep")
@@ -911,7 +984,8 @@ def _do_respawns(api_key: str, host_id: str) -> int:
         _log(f"SPAWN-AUDIT {_target}: spawning — reason={'recycle_fast' if _is_recycle else 'crash_respawn'} "
              f"desired_state=running hb_age={c.get('heartbeat_age_s')}s "
              f"spawned_age={c.get('spawned_age_s')}s respawn_count={c.get('respawn_count')} "
-             f"reconciled={_reconciled} host={host_id}")
+             f"reconciled={_reconciled} discovery={_ag_d['path']}/{_sv_d['path']} "
+             f"(agent_pids={len(_ag_d['pids'])} serve_pids={len(_sv_d['pids'])}) host={host_id}")
         _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, repo_path=c.get("repo_path")):
@@ -1273,13 +1347,54 @@ def _gc_headless_pids() -> None:
         pass
 
 
+def _cim_pid_cmdline(pid: int) -> str:
+    """Windows cmdline via Get-CimInstance (task 89d50a14 [B]): wmic is deprecated
+    and REMOVED by default on Win11 24H2+ — every wmic call there raises
+    FileNotFoundError and discovery silently went blind. powershell.exe (Windows
+    PowerShell 5.1) ships with every supported Windows. '' on failure."""
+    try:
+        out = subprocess.run(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command",
+             f"(Get-CimInstance Win32_Process -Filter \"ProcessId={int(pid)}\").CommandLine"],
+            capture_output=True, text=True, timeout=15).stdout
+        return out or ""
+    except Exception:
+        return ""
+
+
+def _cim_python_pid_cmdlines() -> list:
+    """(pid, cmdline) of every python.exe via Get-CimInstance — the Windows native
+    discovery fallback when psutil is unavailable and wmic is gone (task 89d50a14
+    [B]). One 'pid|cmdline' line per process; partition('|') keeps any '|' inside
+    the cmdline intact. Raises on subprocess failure (caller decides fail-closed)."""
+    script = ("Get-CimInstance Win32_Process -Filter \"Name='python.exe'\" | "
+              "ForEach-Object { '{0}|{1}' -f $_.ProcessId, $_.CommandLine }")
+    out = subprocess.run(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", script],
+        capture_output=True, text=True, timeout=15).stdout
+    rows = []
+    for line in (out or "").splitlines():
+        pid_s, sep, cl = line.partition("|")
+        if not sep:
+            continue
+        try:
+            rows.append((int(pid_s.strip()), cl))
+        except ValueError:
+            continue
+    return rows
+
+
 def _pid_cmdline(pid: int) -> str:
     """Best-effort command line for a pid (to avoid killing a reused PID). '' on failure."""
     try:
         if sys.platform == "win32":
-            out = subprocess.run(
-                ["wmic", "process", "where", f"ProcessId={pid}", "get", "CommandLine"],
-                capture_output=True, text=True, timeout=5).stdout
+            try:
+                out = subprocess.run(
+                    ["wmic", "process", "where", f"ProcessId={pid}", "get", "CommandLine"],
+                    capture_output=True, text=True, timeout=5).stdout
+            except (FileNotFoundError, OSError):
+                # wmic removed (Win11 24H2+) — CIM fallback (task 89d50a14 [B])
+                out = _cim_pid_cmdline(pid)
         else:
             out = subprocess.run(
                 ["ps", "-o", "args=", "-p", str(pid)],
@@ -1401,7 +1516,26 @@ def _discover_agent_pids(target: str) -> list:
     mesh (psutil path only; the native fallbacks accept the regex as-is, documented
     tradeoff: a zombie that survives every stop is the live bug, the cross-mesh
     same-name collision is the rare one)."""
+    return _discover_agent_pids_ex(target)["pids"]
+
+
+def _discover_agent_pids_ex(target: str) -> dict:
+    """Instrumented discovery (task 89d50a14 [B]) — same matching as
+    _discover_agent_pids (see its docstring for every safety rule), but the
+    result distinguishes 'found nothing' from 'COULD NOT LOOK':
+
+      {"pids": [..], "errored": bool, "path": str, "error": str}
+
+    errored=True means the path that produced the final result RAISED — the
+    empty pid list is untrustworthy and spawn decisions must FAIL CLOSED
+    (an empty-but-clean result stays spawn-safe). path is the mechanism that
+    produced the result: 'psutil' | 'native-wmic' | 'native-cim' |
+    'native-pgrep'. Windows native goes wmic → Get-CimInstance (wmic is
+    removed by default on Win11 24H2+; it raising FileNotFoundError and the
+    sweep silently treating that as 'no live session' was a double-session
+    feeder)."""
     pids = []
+    err_notes = []
     tok = _run_token_rx(target)
     ps = _psutil()
     if ps is not None:
@@ -1428,30 +1562,51 @@ def _discover_agent_pids(target: str) -> list:
             # `return pids` skipped the POSIX launcher-children fallback whenever
             # psutil was importable — re-defeating the '0 stopped forever' hole on
             # every box with psutil. Fall through to the shared tail instead.
-            return pids + ([p for p in _discover_launcher_child_pids(target)
-                            if p not in pids] if sys.platform != "win32" else [])
-        except Exception:
+            return {"pids": pids + ([p for p in _discover_launcher_child_pids(target)
+                                     if p not in pids] if sys.platform != "win32" else []),
+                    "errored": False, "path": "psutil", "error": ""}
+        except Exception as e:
+            err_notes.append(f"psutil: {e!r}")
             pids = []  # psutil enumeration itself broke — fall through to native
+    path = "native"
+    errored = False
     try:
         if sys.platform == "win32":
-            out = subprocess.run(
-                ["wmic", "process", "where", "name='python.exe'", "get", "ProcessId,CommandLine", "/FORMAT:LIST"],
-                capture_output=True, text=True, timeout=8).stdout
-            block_pid = None
-            for line in out.splitlines():
-                line = line.strip()
-                if line.startswith("CommandLine="):
-                    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]))
-                    except Exception:
-                        pass
-                    block_pid = None
+            wmic_out = None
+            try:
+                cp = subprocess.run(
+                    ["wmic", "process", "where", "name='python.exe'", "get", "ProcessId,CommandLine", "/FORMAT:LIST"],
+                    capture_output=True, text=True, timeout=8)
+                if cp.returncode == 0 or (cp.stdout or "").strip():
+                    wmic_out = cp.stdout or ""
+                else:
+                    err_notes.append(f"wmic: rc={cp.returncode}")
+            except (FileNotFoundError, OSError) as e:
+                # wmic deprecated/removed (Win11 24H2+) — Get-CimInstance fallback
+                err_notes.append(f"wmic: {e!r}")
+            if wmic_out is not None:
+                path = "native-wmic"
+                block_pid = None
+                for line in wmic_out.splitlines():
+                    line = line.strip()
+                    if line.startswith("CommandLine="):
+                        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]))
+                        except Exception:
+                            pass
+                        block_pid = None
+            else:
+                path = "native-cim"
+                for cim_pid, cl in _cim_python_pid_cmdlines():
+                    if cl and "meshcode" in cl and tok.search(cl):
+                        pids.append(cim_pid)
         else:
             # task 3ed8781d: pattern WITHOUT the target so bare-name spawns
             # (`run "agent"`) are candidates too; the exact tok filter below
             # keeps the kill set tight.
+            path = "native-pgrep"
             out = subprocess.run(
                 ["pgrep", "-f", "meshcode.* run "],
                 capture_output=True, text=True, timeout=8).stdout
@@ -1463,8 +1618,10 @@ def _discover_agent_pids(target: str) -> list:
                 # 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
+    except Exception as e:
+        # the LAST mechanism available raised — the empty result is a lie, not a fact
+        err_notes.append(f"{path}: {e!r}")
+        errored = True
     # GHOST-TERMINAL fix (task 91201315): on POSIX `meshcode run` EXECVP's claude, so the
     # live agent's cmdline is `claude …` — no 'meshcode run <target>' survives and the
     # pgrep above sees NOTHING for a visible macOS agent (the '0 stopped forever' hole).
@@ -1477,7 +1634,7 @@ def _discover_agent_pids(target: str) -> list:
             pids += [p for p in _discover_launcher_child_pids(target) if p not in pids]
         except Exception:
             pass
-    return pids
+    return {"pids": pids, "errored": errored, "path": path, "error": "; ".join(err_notes)}
 
 
 def _discover_launcher_child_pids(target: str) -> list:
@@ -1543,12 +1700,21 @@ def _discover_serve_pids(target: str) -> list:
     relaunch reconcile) matches on MESHCODE_AGENT alone — the relaunch click means
     'fresh session of THIS agent on this box', so any project's orphan of that name
     is a survivor to clear. Qualified targets keep the exact two-field match."""
+    return _discover_serve_pids_ex(target)["pids"]
+
+
+def _discover_serve_pids_ex(target: str) -> dict:
+    """Instrumented serve discovery (task 89d50a14 [B]) — same result contract as
+    _discover_agent_pids_ex. psutil-missing is errored=False (degraded BY DESIGN,
+    documented since 14e0760c: the session-root tree kill still covers parented
+    serves); the enumeration itself raising is errored=True (empty result is
+    untrustworthy → spawn decisions fail closed)."""
     ps = _psutil()
     if ps is None:
-        return []
+        return {"pids": [], "errored": False, "path": "none(psutil-missing)", "error": ""}
     proj, _, agent = target.rpartition("/")
     if not agent:
-        return []
+        return {"pids": [], "errored": False, "path": "psutil", "error": ""}
     own = _own_pid()
     out = []
     try:
@@ -1565,9 +1731,9 @@ def _discover_serve_pids(target: str) -> list:
                     out.append(p.pid)
             except Exception:
                 continue  # process vanished / access denied — never block the sweep
-    except Exception:
-        return []
-    return out
+    except Exception as e:
+        return {"pids": [], "errored": True, "path": "psutil", "error": f"psutil: {e!r}"}
+    return {"pids": out, "errored": False, "path": "psutil", "error": ""}
 
 
 def _kill_heartbeat_fork(target: str) -> None:

{meshcode-2.11.136 → meshcode-2.11.137}/meshcode/meshcode_mcp/server.py

@@ -6723,6 +6723,47 @@ def meshcode_tray_claim(lease_seconds: int = 900,
                              lease_seconds=lease_seconds)
 
 
+@mcp.tool()
+@with_working_status
+def meshcode_tray_seed(title: str,
+                       description: str = "",
+                       priority: str = "normal",
+                       swarm_id: Optional[str] = None,
+                       parent_task_id: Optional[str] = None,
+                       depends_on: Optional[list] = None,
+                       queue_position: Optional[int] = None) -> Dict[str, Any]:
+    """PARENT loop step: seed ONE task into your swarm tray so helpers drain
+    it via meshcode_tray_claim (work-stealing, DAG-gated, priority-ordered).
+
+    ENJAMBRE (mig 524, task d4af9eb7 — before this, nothing could create
+    swarm_id-stamped tasks: lanes went by direct assignment and lost
+    work-stealing + the mig 471 barrier-on-drain). Canonical flow:
+    meshcode_helper_spawn (mints the tray + stamps YOUR swarm_id) →
+    meshcode_tray_seed xN → helpers tray_claim/complete → barrier fires when
+    the tray drains. Seed BEFORE or AFTER spawning — claims only see
+    status='open' rows, there is no race.
+
+    Identity-bound (agent-scoped api key) and member-only: you can seed only
+    the swarm you belong to. The task lands assignee=you (concrete-owner
+    rule); stealing is via claimed_by.
+
+    Args:
+        title: task title (required, <=200 chars).
+        description: full lane instructions (helpers see it at claim time).
+        priority: low|normal|medium|high|urgent (claim order).
+        swarm_id: override tray; omit and the SERVER resolves your own row's swarm.
+        parent_task_id: umbrella task — seeded tasks participate in its
+            barrier-on-drain (mig 471) automatically.
+        depends_on: task UUIDs that DAG-gate this one (validated same-project).
+        queue_position: tiebreaker within same priority (lower first).
+    """
+    from . import swarm as _swarm
+    return _swarm.tray_seed(_get_api_key(), _PROJECT_ID, title,
+                            description=description, priority=priority,
+                            swarm_id=swarm_id, parent_task_id=parent_task_id,
+                            depends_on=depends_on, queue_position=queue_position)
+
+
 @mcp.tool()
 @with_working_status
 def meshcode_helper_retire(reason: str = "tray_drained") -> Dict[str, Any]:

{meshcode-2.11.136 → meshcode-2.11.137}/meshcode/meshcode_mcp/swarm.py

@@ -184,6 +184,16 @@ def spawn_helper(api_key: str, project_id: str, name: str, *,
                 "error": _explain_spawn_refusal(code, err),
                 **({"error_code": code} if code else {})}
 
+    # HELPER VISUALS (task d8f8e325): stamp the local marker SO THE SPAWNER
+    # (hostd / protocol_handler, same host by W5 inheritance) can render the
+    # helper's terminal distinct (amber tab + helper: title). Best-effort —
+    # never blocks the spawn.
+    try:
+        from meshcode import helper_visuals as _hv
+        _hv.mark_helper(name, ttl_seconds=int(ttl_seconds))
+    except Exception:
+        pass
+
     out: Dict[str, Any] = {"ok": True, "helper": name, "launched": bool(launch)}
     if isinstance(reg, dict):
         out.update({k: reg[k] for k in
@@ -217,6 +227,45 @@ def spawn_helper(api_key: str, project_id: str, name: str, *,
     return out
 
 
+RPC_TRAY_SEED = "mc_tray_seed_as_agent"
+
+
+def tray_seed(api_key: str, project_id: str, title: str, *,
+              description: str = "",
+              priority: str = "normal",
+              swarm_id: Optional[str] = None,
+              parent_task_id: Optional[str] = None,
+              depends_on: Optional[list] = None,
+              queue_position: Optional[int] = None) -> Dict[str, Any]:
+    """Seed ONE task into the swarm tray (task d4af9eb7 — closes the gap where
+    mc_task_claim_from_tray could only CLAIM and nothing could create
+    swarm_id-stamped tasks, so lanes fell back to direct assignment and lost
+    work-stealing + DAG gate + barrier-on-drain).
+
+    swarm_id=None lets the SERVER resolve the caller's own mc_agents.swarm_id
+    (same contract as tray_claim — the SDK never reads mc_agents directly).
+    Identity-bound: requires an agent-scoped api key; the caller must belong
+    to the swarm. The seeded task lands status='open' (exactly what
+    tray_claim picks up), assignee=caller (mig 213 concrete-owner rule;
+    stealing is via claimed_by). depends_on ids are validated server-side
+    against the same project so a typo can never DAG-block the tray forever."""
+    result = be.sb_rpc(RPC_TRAY_SEED, {
+        "p_api_key": api_key,
+        "p_project_id": project_id,
+        "p_title": title,
+        "p_description": description,
+        "p_priority": priority,
+        "p_swarm_id": swarm_id,
+        "p_parent_task_id": parent_task_id,
+        "p_depends_on": depends_on,
+        "p_queue_position": queue_position,
+    })
+    err = _err(result)
+    if err:
+        return {"ok": False, "error": err}
+    return result if isinstance(result, dict) else {"ok": False, "error": "bad response shape"}
+
+
 def tray_claim(api_key: str, project_id: str, *,
                swarm_id: Optional[str] = None,
                lease_seconds: int = DEFAULT_LEASE_SECONDS) -> Dict[str, Any]:
@@ -255,6 +304,17 @@ def retire_self(api_key: str, project_id: str, *,
     err = _err(result)
     if err:
         return {"ok": False, "error": err}
+    # HELPER VISUALS (task d8f8e325): retired — drop this host's marker so a
+    # later same-named top-level agent doesn't render amber. Self-identify via
+    # the MCP env (.mcp.json always sets MESHCODE_AGENT). Best-effort.
+    try:
+        import os as _os
+        from meshcode import helper_visuals as _hv
+        _own = _os.environ.get("MESHCODE_AGENT", "")
+        if _own:
+            _hv.unmark_helper(_own)
+    except Exception:
+        pass
     return result if isinstance(result, dict) else {"ok": False, "error": "bad response shape"}