meshcode 2.11.155__tar.gz → 2.11.157__tar.gz

{meshcode-2.11.155 → meshcode-2.11.157}/PKG-INFO

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

{meshcode-2.11.155 → meshcode-2.11.157}/meshcode/__init__.py

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

{meshcode-2.11.155 → meshcode-2.11.157}/meshcode/meshcode_mcp/server.py

@@ -491,6 +491,40 @@ def _try_auto_wake(from_agent: str, preview: str, urgent: bool = False) -> None:
     # configurations, pipelines, tmux without termguicolors) render the raw
     # bytes — "[91m[1m[mesh][0m …" — which is worse UX than no color at all.
     nudge = f"[mesh] {safe_agent} > {safe_preview} — meshcode_check()"
+    # tmux fast-path (task 780d7397): the fleet runs inside a tmux session, so the
+    # MCP serve process (a child of `claude` in the pane) inherits TMUX_PANE. When
+    # it's present, prefer `tmux send-keys` over the window-activation fallbacks —
+    # only tmux can ACTUALLY interrupt Claude's current turn (Escape) and then
+    # inject+submit the nudge, so an urgent message reaches a mid-step agent in
+    # ~1-2s instead of waiting for its next tool-call boundary. AppleScript/
+    # PowerShell/xdotool below cannot interrupt generation; they only help a truly
+    # idle agent and so remain the fallback when we're not inside tmux.
+    tmux_pane = os.environ.get("TMUX_PANE", "")
+    if tmux_pane and re.match(r'^%[0-9]+$', tmux_pane):
+        # Urgent gets a short, unambiguous marker that forces a meshcode_check —
+        # never the full payload (the agent reads the real message via the check).
+        marker = (f"[URGENT] {safe_agent} - run meshcode_check()"
+                  if urgent else nudge)
+        try:
+            # 1) Escape interrupts Claude's in-flight generation/turn.
+            subprocess.run(["tmux", "send-keys", "-t", tmux_pane, "Escape"],
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                           timeout=5)
+            # 2) brief pause so the interrupt registers before we type.
+            _time.sleep(0.2)
+            # 3) inject the marker literally (-l so it is never parsed as a key
+            #    name), then submit with a separate Enter so Claude reads it now.
+            subprocess.run(["tmux", "send-keys", "-t", tmux_pane, "-l", marker],
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                           timeout=5)
+            _time.sleep(0.15)  # let the TUI register the typed text before submit
+            subprocess.run(["tmux", "send-keys", "-t", tmux_pane, "Enter"],
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                           timeout=5)
+            log.info(f"auto-wake: interrupted+injected via tmux pane {tmux_pane}")
+            return
+        except Exception as e:
+            log.debug(f"auto-wake tmux path failed, falling back: {e}")
     system = platform.system()
     try:
         if system == "Darwin":

{meshcode-2.11.155 → meshcode-2.11.157}/meshcode/protocol_handler.py

@@ -373,6 +373,60 @@ def _fleet_attach_linux(tmux: str) -> tuple[bool, str]:
     return _spawn_terminal_linux(attach)
 
 
+def _reap_dead_fleet_windows(tmux: str, cap: Optional[int] = None) -> int:
+    """Reap accumulated DEAD windows from the fleet tmux session (task 22fcdb21,
+    Samuel P1: dead panes stacked to 51).
+
+    The RAII trap in _fleet_wrap closes a window on a CLEAN / SIGTERM exit, but
+    a SIGKILL (rc=137: force-kill / OOM / recycle) cannot be trapped, so the
+    per-window `remain-on-exit=failed` keeps that dead pane forever. Over days
+    these pile up and `#{session_windows}` (the 'N agents' counter) counts
+    cadavers, not live agents.
+
+    Sweeps every fleet window whose panes are ALL dead, KEEPING only the `cap`
+    most-recently-dead (bounded crash-retention for debugging) and killing the
+    rest. It NEVER touches a window with a live pane, so it can never close a
+    running agent. Returns the count reaped. Best-effort; never raises. Tunable
+    via MESHCODE_FLEET_DEAD_CAP (default 3; 0 = reap every dead pane)."""
+    if cap is None:
+        try:
+            cap = int(os.environ.get("MESHCODE_FLEET_DEAD_CAP", "3") or 3)
+        except ValueError:
+            cap = 3
+    cap = max(0, cap)
+    try:
+        r = _tmux(tmux, "list-panes", "-s", "-t", f"={_FLEET_SESSION}",
+                  "-F", "#{window_id}\t#{pane_dead}\t#{pane_dead_time}")
+        if r.returncode != 0:
+            return 0
+        # Group panes by window: a window is dead only if EVERY pane is dead
+        # (fleet windows are single-pane, but stay correct if that changes).
+        wins: dict = {}
+        for line in (r.stdout or "").splitlines():
+            parts = line.split("\t")
+            if len(parts) < 2:
+                continue
+            wid, pdead = parts[0], parts[1]
+            try:
+                pdt = int(parts[2]) if len(parts) > 2 and parts[2] else 0
+            except ValueError:
+                pdt = 0
+            w = wins.setdefault(wid, {"all_dead": True, "dt": 0})
+            if pdead != "1":
+                w["all_dead"] = False
+            else:
+                w["dt"] = max(w["dt"], pdt)
+        dead = sorted(((v["dt"], wid) for wid, v in wins.items() if v["all_dead"]),
+                      reverse=True)  # newest dead first; keep[:cap], reap the tail
+        reaped = 0
+        for _dt, wid in dead[cap:]:
+            if _tmux(tmux, "kill-window", "-t", wid).returncode == 0:
+                reaped += 1
+        return reaped
+    except Exception:
+        return 0
+
+
 def _spawn_fleet_tab(cmd: str) -> tuple[bool, str]:
     """Run `cmd` as a TAB (tmux window) of the shared fleet window.
 
@@ -399,6 +453,11 @@ def _spawn_fleet_tab(cmd: str) -> tuple[bool, str]:
             if r.returncode != 0:  # lost a create race -> join as a tab
                 fresh_session = False
         if not fresh_session:
+            # Sweep-on-launch: reap accumulated dead panes BEFORE adding this
+            # agent's tab, so the fleet bar reflects live agents (not the 51
+            # cadavers Samuel saw) and a respawn reuses the slot (task 22fcdb21).
+            # Only ever touches already-dead windows — never a live agent.
+            _reap_dead_fleet_windows(tmux)
             r = _tmux(tmux, "new-window", "-d", "-t", f"={_FLEET_SESSION}:",
                       "-n", label, "-P", "-F", "#{window_id}", wrapped)
             if r.returncode != 0:

{meshcode-2.11.155 → meshcode-2.11.157}/meshcode/self_update.py

@@ -704,6 +704,16 @@ def ensure_boot_env(mcp_json_path, verbose: bool = True) -> Optional[str]:
         if env_block.get("MESHCODE_EXPECTED_VERSION") != target:
             env_block["MESHCODE_EXPECTED_VERSION"] = target
             changed = True
+        # urgent-wake default-on rollout (task 780d7397): setup_clients bakes
+        # MESHCODE_URGENT_WAKE=1 only for FRESH `meshcode setup`. Existing agents'
+        # .mcp.json is never regenerated on `meshcode run`, so the env-gated
+        # feature would stay OFF forever on installed fleets. Backfill it here —
+        # the one place that mutates an existing server env every boot — but only
+        # when the key is ABSENT, so an explicit user opt-out (set to "0") is
+        # never clobbered.
+        if "MESHCODE_URGENT_WAKE" not in env_block:
+            env_block["MESHCODE_URGENT_WAKE"] = "1"
+            changed = True
         if changed:
             tmp = mcp_json_path.with_name(mcp_json_path.name + ".tmp")
             tmp.write_text(json.dumps(doc, indent=2), encoding="utf-8")

{meshcode-2.11.155 → meshcode-2.11.157}/meshcode/setup_clients.py

@@ -215,6 +215,14 @@ def _build_server_block(project: str, project_id: str, agent: str, role: str,
         # Mark this Python process as the MCP serve subprocess so other
         # parts of the package (e.g. self_update) skip auto-update inside it.
         "MESHCODE_MCP_SERVE": "1",
+        # Urgent-interrupt nudging (task 780d7397, Samuel 2026-06-22): a
+        # priority='urgent' message must INTERRUPT a busy agent and be read
+        # at once, not merely queue until its next meshcode_wait. This opt-in
+        # gates the urgent-only path in server._try_auto_wake (tmux ESC+inject
+        # when in a tmux pane, AppleScript/etc fallback otherwise). Deliberately
+        # urgent-only — we do NOT set MESHCODE_AUTO_WAKE so non-urgent traffic
+        # never injects keystrokes (that stays the conservative default OFF).
+        "MESHCODE_URGENT_WAKE": "1",
     }
     if editor_type:
         env["MESHCODE_EDITOR_TYPE"] = editor_type

{meshcode-2.11.155 → meshcode-2.11.157}/meshcode.egg-info/PKG-INFO

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

{meshcode-2.11.155 → meshcode-2.11.157}/meshcode.egg-info/SOURCES.txt

@@ -70,11 +70,13 @@ tests/test_core.py
 tests/test_cross_agent_messaging.py
 tests/test_date_parse.py
 tests/test_doctor.py
+tests/test_ensure_boot_env_urgent_wake.py
 tests/test_epistemic_v1_python_sdk.py
 tests/test_epistemic_v1_stop_conditions.py
 tests/test_esc_deaf_state.py
 tests/test_exceptions.py
 tests/test_file_upload.py
+tests/test_fleet_reaper.py
 tests/test_helper_visuals.py
 tests/test_hostd_launch_pinned_env.py
 tests/test_hostd_serve_discovery_split.py
@@ -113,4 +115,5 @@ tests/test_task_progress.py
 tests/test_terminal_lifecycle.py
 tests/test_up_launch_cmd.py
 tests/test_update_guard.py
+tests/test_urgent_wake_tmux.py
 tests/test_wait_open_tasks_contradiction.py

{meshcode-2.11.155 → meshcode-2.11.157}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meshcode"
-version = "2.11.155"
+version = "2.11.157"
 description = "Real-time communication between AI agents — Supabase-backed CLI"
 readme = "README.md"
 license = {text = "MIT"}

meshcode-2.11.157/tests/test_ensure_boot_env_urgent_wake.py

@@ -0,0 +1,95 @@
+"""
+ensure_boot_env backfills MESHCODE_URGENT_WAKE (task 780d7397 / 2.11.157)
+=========================================================================
+setup_clients bakes MESHCODE_URGENT_WAKE=1 only for a FRESH `meshcode setup`.
+An already-installed agent's .mcp.json is never regenerated on `meshcode run`
+(run_agent only writes it when MISSING), so the env-gated urgent-wake feature
+would stay OFF forever on existing fleets — exactly the gap that would have made
+the front-end smoke fail.
+
+ensure_boot_env is the one place that mutates an existing server env block every
+boot. It must backfill the flag when ABSENT, but must NEVER clobber an explicit
+user opt-out (value "0").
+
+These tests stub the version-resolution surface so no network / env-pin happens;
+they exercise only the .mcp.json mutation.
+"""
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import meshcode.self_update as su
+
+
+def _write_mcp(tmp_path, env_block):
+    p = tmp_path / ".mcp.json"
+    doc = {
+        "mcpServers": {
+            "meshcode-x": {
+                "command": "/fake/envs/9.9.9/bin/python3",
+                "args": ["-m", "meshcode.meshcode_mcp", "serve"],
+                "env": env_block,
+            }
+        }
+    }
+    p.write_text(json.dumps(doc, indent=2), encoding="utf-8")
+    return p
+
+
+def _stub_versions(monkeypatch, target="9.9.9"):
+    """No-network: current env already == target, so no env-pin path runs."""
+    monkeypatch.setattr(su, "update_disabled", lambda: False)
+    monkeypatch.setattr(su, "is_editable_install", lambda: False)
+    monkeypatch.setattr(su, "resolve_target_version", lambda: target)
+    monkeypatch.setattr(su, "_env_version", lambda cmd: target)
+
+
+def _read_env(p):
+    doc = json.loads(p.read_text(encoding="utf-8"))
+    return next(iter(doc["mcpServers"].values()))["env"]
+
+
+def test_backfills_when_absent(tmp_path, monkeypatch):
+    _stub_versions(monkeypatch)
+    p = _write_mcp(tmp_path, {"MESHCODE_EXPECTED_VERSION": "9.9.9"})
+    out = su.ensure_boot_env(p, verbose=False)
+    assert out == "9.9.9"
+    assert _read_env(p)["MESHCODE_URGENT_WAKE"] == "1"
+
+
+def test_does_not_clobber_explicit_optout(tmp_path, monkeypatch):
+    _stub_versions(monkeypatch)
+    p = _write_mcp(tmp_path, {
+        "MESHCODE_EXPECTED_VERSION": "9.9.9",
+        "MESHCODE_URGENT_WAKE": "0",
+    })
+    su.ensure_boot_env(p, verbose=False)
+    assert _read_env(p)["MESHCODE_URGENT_WAKE"] == "0", "user opt-out was clobbered"
+
+
+def test_preserves_existing_on_value(tmp_path, monkeypatch):
+    _stub_versions(monkeypatch)
+    p = _write_mcp(tmp_path, {
+        "MESHCODE_EXPECTED_VERSION": "9.9.9",
+        "MESHCODE_URGENT_WAKE": "1",
+    })
+    su.ensure_boot_env(p, verbose=False)
+    assert _read_env(p)["MESHCODE_URGENT_WAKE"] == "1"
+
+
+def test_idempotent_second_boot_no_rewrite(tmp_path, monkeypatch):
+    _stub_versions(monkeypatch)
+    p = _write_mcp(tmp_path, {"MESHCODE_EXPECTED_VERSION": "9.9.9"})
+    su.ensure_boot_env(p, verbose=False)
+    mtime1 = p.stat().st_mtime_ns
+    # Second boot: everything already in place -> changed=False -> no rewrite.
+    su.ensure_boot_env(p, verbose=False)
+    assert p.stat().st_mtime_ns == mtime1, "rewrote .mcp.json with nothing to change"
+    assert _read_env(p)["MESHCODE_URGENT_WAKE"] == "1"
+
+
+if __name__ == "__main__":
+    import pytest
+    sys.exit(pytest.main([__file__, "-q"]))

meshcode-2.11.157/tests/test_fleet_reaper.py

@@ -0,0 +1,176 @@
+"""
+Fleet dead-window reaper (task 22fcdb21, Samuel P1)
+===================================================
+Samuel saw "51 agents" in the fleet tab bar — almost all cadavers. A SIGKILL
+(rc=137: force-kill / OOM / recycle) cannot be trapped by the RAII wrapper, so
+`remain-on-exit=failed` keeps that dead pane forever and `#{session_windows}`
+counts corpses, not live agents.
+
+`_reap_dead_fleet_windows` sweeps windows whose panes are ALL dead, keeping only
+the `cap` most-recently-dead (bounded crash retention) and killing the rest. The
+load-bearing safety property: it must NEVER kill a window that still has a live
+pane (a running agent).
+
+These tests stub `_tmux` so nothing real is spawned.
+"""
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import meshcode.protocol_handler as ph
+
+
+class _R:
+    def __init__(self, returncode=0, stdout=""):
+        self.returncode = returncode
+        self.stdout = stdout
+
+
+def _install_fake_tmux(monkeypatch_target, panes_output, *, list_rc=0):
+    """Replace ph._tmux with a stub. Records every kill-window target."""
+    killed = []
+
+    def fake(tmux, *args):
+        if args and args[0] == "list-panes":
+            return _R(returncode=list_rc, stdout=panes_output)
+        if args and args[0] == "kill-window":
+            # args == ("kill-window", "-t", "<wid>")
+            killed.append(args[2])
+            return _R(returncode=0)
+        return _R(returncode=0)
+
+    monkeypatch_target._tmux = fake
+    return killed
+
+
+def _panes(*rows):
+    """rows: (window_id, pane_dead, pane_dead_time) tuples -> tmux -F lines."""
+    return "\n".join(f"{w}\t{d}\t{t}" for (w, d, t) in rows)
+
+
+def test_reaps_dead_beyond_cap_keeps_newest():
+    # 5 dead windows, cap=2 -> keep the 2 newest-dead (@5,@4), reap @3,@2,@1.
+    out = _panes(("@1", "1", "100"), ("@2", "1", "200"), ("@3", "1", "300"),
+                 ("@4", "1", "400"), ("@5", "1", "500"))
+    orig = ph._tmux
+    try:
+        killed = _install_fake_tmux(ph, out)
+        n = ph._reap_dead_fleet_windows("tmux", cap=2)
+        assert n == 3, n
+        assert set(killed) == {"@1", "@2", "@3"}, killed
+        assert "@4" not in killed and "@5" not in killed, killed
+    finally:
+        ph._tmux = orig
+
+
+def test_never_reaps_live_window():
+    # @2 is LIVE (pane_dead=0). Even with cap=0 it must survive.
+    out = _panes(("@1", "1", "100"), ("@2", "0", "0"), ("@3", "1", "300"))
+    orig = ph._tmux
+    try:
+        killed = _install_fake_tmux(ph, out)
+        n = ph._reap_dead_fleet_windows("tmux", cap=0)
+        assert "@2" not in killed, f"killed a LIVE agent window: {killed}"
+        assert set(killed) == {"@1", "@3"}, killed
+        assert n == 2, n
+    finally:
+        ph._tmux = orig
+
+
+def test_multipane_window_with_one_live_pane_survives():
+    # @1 has two panes: one dead, one live -> window is NOT all-dead -> keep.
+    out = _panes(("@1", "1", "100"), ("@1", "0", "0"), ("@2", "1", "200"))
+    orig = ph._tmux
+    try:
+        killed = _install_fake_tmux(ph, out)
+        ph._reap_dead_fleet_windows("tmux", cap=0)
+        assert "@1" not in killed, f"reaped a window with a live pane: {killed}"
+        assert killed == ["@2"], killed
+    finally:
+        ph._tmux = orig
+
+
+def test_cap_zero_reaps_all_dead():
+    out = _panes(("@1", "1", "100"), ("@2", "1", "200"))
+    orig = ph._tmux
+    try:
+        killed = _install_fake_tmux(ph, out)
+        n = ph._reap_dead_fleet_windows("tmux", cap=0)
+        assert n == 2 and set(killed) == {"@1", "@2"}, killed
+    finally:
+        ph._tmux = orig
+
+
+def test_under_cap_reaps_nothing():
+    out = _panes(("@1", "1", "100"), ("@2", "1", "200"))
+    orig = ph._tmux
+    try:
+        killed = _install_fake_tmux(ph, out)
+        n = ph._reap_dead_fleet_windows("tmux", cap=3)
+        assert n == 0 and killed == [], killed
+    finally:
+        ph._tmux = orig
+
+
+def test_list_panes_failure_is_noop():
+    orig = ph._tmux
+    try:
+        killed = _install_fake_tmux(ph, "", list_rc=1)
+        n = ph._reap_dead_fleet_windows("tmux", cap=0)
+        assert n == 0 and killed == [], killed
+    finally:
+        ph._tmux = orig
+
+
+def test_env_default_cap_when_none():
+    out = _panes(("@1", "1", "100"), ("@2", "1", "200"),
+                 ("@3", "1", "300"), ("@4", "1", "400"))
+    orig = ph._tmux
+    prev = os.environ.get("MESHCODE_FLEET_DEAD_CAP")
+    try:
+        os.environ["MESHCODE_FLEET_DEAD_CAP"] = "1"
+        killed = _install_fake_tmux(ph, out)
+        n = ph._reap_dead_fleet_windows("tmux")  # cap=None -> env -> 1
+        assert n == 3, n
+        assert "@4" not in killed, killed  # newest-dead kept
+    finally:
+        if prev is None:
+            os.environ.pop("MESHCODE_FLEET_DEAD_CAP", None)
+        else:
+            os.environ["MESHCODE_FLEET_DEAD_CAP"] = prev
+        ph._tmux = orig
+
+
+def test_bad_env_cap_falls_back_to_default():
+    out = _panes(*[(f"@{i}", "1", str(i * 100)) for i in range(1, 6)])
+    orig = ph._tmux
+    prev = os.environ.get("MESHCODE_FLEET_DEAD_CAP")
+    try:
+        os.environ["MESHCODE_FLEET_DEAD_CAP"] = "not-an-int"
+        killed = _install_fake_tmux(ph, out)
+        n = ph._reap_dead_fleet_windows("tmux")  # bad env -> default cap 3
+        assert n == 2, n  # 5 dead, keep 3, reap 2
+    finally:
+        if prev is None:
+            os.environ.pop("MESHCODE_FLEET_DEAD_CAP", None)
+        else:
+            os.environ["MESHCODE_FLEET_DEAD_CAP"] = prev
+        ph._tmux = orig
+
+
+def test_exception_safe_returns_zero():
+    orig = ph._tmux
+    try:
+        def boom(*a, **k):
+            raise RuntimeError("tmux exploded")
+        ph._tmux = boom
+        assert ph._reap_dead_fleet_windows("tmux", cap=0) == 0
+    finally:
+        ph._tmux = orig
+
+
+if __name__ == "__main__":
+    import pytest
+    sys.exit(pytest.main([__file__, "-q"]))

meshcode-2.11.157/tests/test_urgent_wake_tmux.py

@@ -0,0 +1,137 @@
+"""
+Urgent-wake tmux interrupt path (task 780d7397)
+================================================
+Samuel (2026-06-22): a priority='urgent' message must INTERRUPT a busy agent
+and be read at once, not merely queue until its next meshcode_wait.
+
+Mechanism (server._try_auto_wake):
+  - When the MCP serve process inherits TMUX_PANE (the fleet runs inside tmux),
+    prefer `tmux send-keys`: Escape (interrupt the current Claude turn) → inject
+    a short marker literally (-l) → Enter (submit). This actually interrupts
+    generation, unlike the AppleScript/PowerShell/xdotool window-activation
+    fallbacks which only help a truly idle agent.
+  - Gated on MESHCODE_URGENT_WAKE (urgent-only; we deliberately do NOT enable
+    full MESHCODE_AUTO_WAKE). setup_clients._build_server_block bakes the flag.
+
+These tests don't need a running MCP server — they drive _try_auto_wake directly
+with the module globals arranged + subprocess stubbed.
+"""
+import inspect
+import os
+import sys
+from pathlib import Path
+
+# Minimal env so importing the server module doesn't hard-exit.
+for _k, _v in {
+    "SUPABASE_URL": "https://gjinagyyjttyxnaoavnz.supabase.co",
+    "SUPABASE_KEY": "test",
+    "MESHCODE_MCP_SERVE": "1",
+    "MESHCODE_PROJECT": "meshcode-self-improve",
+    "MESHCODE_PROJECT_ID": "test",
+    "MESHCODE_AGENT": "backend",
+    "MESHCODE_API_KEY": "test-key",
+}.items():
+    os.environ.setdefault(_k, _v)
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import subprocess as _real_subprocess  # server.py does `import subprocess` inside the fn
+
+
+def _arrange(srv, *, urgent_wake=True, auto_wake=False, in_wait=False,
+            state="working", agent="backend", pane="%7"):
+    """Put the module into a known state and capture tmux/osascript calls."""
+    srv._URGENT_WAKE = urgent_wake
+    srv._AUTO_WAKE = auto_wake
+    srv._IN_WAIT = in_wait
+    srv._current_state = state
+    srv.AGENT_NAME = agent
+    srv._last_tool_at = 0.0
+    srv._time.sleep = lambda *a, **k: None
+    if pane is None:
+        os.environ.pop("TMUX_PANE", None)
+    else:
+        os.environ["TMUX_PANE"] = pane
+    calls = []
+
+    class _R:
+        returncode = 0
+
+    _real_subprocess.run = lambda args, **kw: (calls.append(args), _R())[1]
+    return calls
+
+
+def _get_srv():
+    import meshcode.meshcode_mcp.server as srv
+    return srv
+
+
+def test_urgent_fires_escape_marker_enter_in_order():
+    srv = _get_srv()
+    calls = _arrange(srv, pane="%7")
+    srv._try_auto_wake(from_agent="mesh-commander", preview="urgent test", urgent=True)
+
+    assert any(c[:4] == ["tmux", "send-keys", "-t", "%7"] and c[-1] == "Escape"
+               for c in calls), f"no Escape: {calls}"
+    assert any("-l" in c and any("URGENT" in str(x) for x in c)
+               for c in calls), f"no literal URGENT marker: {calls}"
+    assert any(c[-1] == "Enter" for c in calls), f"no Enter submit: {calls}"
+    # ordering: Escape < marker < Enter
+    order = [c[-1] if c[-1] in ("Escape", "Enter") else ("MARKER" if "-l" in c else c[-1])
+             for c in calls]
+    assert order.index("Escape") < order.index("MARKER") < order.index("Enter"), order
+    # tmux path must return before any AppleScript fallback runs
+    assert not any("osascript" in str(c) for c in calls), f"fallback fired: {calls}"
+
+
+def test_urgent_overrides_busy_state():
+    """A 'working' (busy) agent must still be interrupted by urgent."""
+    srv = _get_srv()
+    calls = _arrange(srv, state="working", pane="%7")
+    srv._try_auto_wake(from_agent="mesh-commander", preview="x", urgent=True)
+    assert calls, "urgent should fire even when the agent is working"
+
+
+def test_non_urgent_busy_agent_does_not_fire():
+    """Non-urgent + not sleeping → state guard blocks (no keystroke injection)."""
+    srv = _get_srv()
+    calls = _arrange(srv, state="working", pane="%7")
+    srv._try_auto_wake(from_agent="mesh-commander", preview="x", urgent=False)
+    assert calls == [], f"non-urgent busy agent should not fire: {calls}"
+
+
+def test_self_echo_guard():
+    """Urgent from yourself must never inject into your own terminal."""
+    srv = _get_srv()
+    calls = _arrange(srv, agent="backend", pane="%7")
+    srv._try_auto_wake(from_agent="backend", preview="self", urgent=True)
+    assert calls == [], f"self-echo should not fire: {calls}"
+
+
+def test_gate_blocks_when_urgent_wake_disabled():
+    """No MESHCODE_URGENT_WAKE → urgent must not fire (opt-in respected)."""
+    srv = _get_srv()
+    calls = _arrange(srv, urgent_wake=False, auto_wake=False, pane="%7")
+    srv._try_auto_wake(from_agent="mesh-commander", preview="x", urgent=True)
+    assert calls == [], f"urgent fired with URGENT_WAKE off: {calls}"
+
+
+def test_skips_while_in_wait():
+    """_IN_WAIT means the wait loop will deliver — never inject keystrokes."""
+    srv = _get_srv()
+    calls = _arrange(srv, in_wait=True, pane="%7")
+    srv._try_auto_wake(from_agent="mesh-commander", preview="x", urgent=True)
+    assert calls == [], f"fired during meshcode_wait: {calls}"
+
+
+def test_setup_clients_bakes_urgent_wake_only():
+    """setup_clients env dict opts into urgent-only, never full auto-wake."""
+    import meshcode.setup_clients as sc
+    src = inspect.getsource(sc._build_server_block)
+    assert '"MESHCODE_URGENT_WAKE": "1"' in src, "URGENT_WAKE flag missing"
+    assert '"MESHCODE_AUTO_WAKE"' not in src, "AUTO_WAKE must stay unset (urgent-only)"
+
+
+if __name__ == "__main__":
+    import pytest
+    sys.exit(pytest.main([__file__, "-q"]))