swarph-cli 0.13.1__tar.gz → 0.13.3__tar.gz

{swarph_cli-0.13.1/src/swarph_cli.egg-info → swarph_cli-0.13.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.13.1
+Version: 0.13.3
 Summary: The `swarph` binary — multi-LLM CLI + mesh-gateway integration: multi-provider `swarph spawn` (claude/codex/antigravity per cell.provider via a ProviderMembrane + subprocess billing-scrub), interactive `swarph init`, `swarph mesh` (send/inbox/register) + inbox sidecar, `assisted_memory` (git-backed durable memory), session import, watchdog. v0.9.5: foolproof Windows auto-relaunch (genuine-WT detection via process ancestry, not WT_SESSION).
 Author: Pierre Samson, Claude Opus
 License: MIT

{swarph_cli-0.13.1 → swarph_cli-0.13.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.13.1"
+version = "0.13.3"
 description = "The `swarph` binary — multi-LLM CLI + mesh-gateway integration: multi-provider `swarph spawn` (claude/codex/antigravity per cell.provider via a ProviderMembrane + subprocess billing-scrub), interactive `swarph init`, `swarph mesh` (send/inbox/register) + inbox sidecar, `assisted_memory` (git-backed durable memory), session import, watchdog. v0.9.5: foolproof Windows auto-relaunch (genuine-WT detection via process ancestry, not WT_SESSION)."
 readme = "README.md"
 license = { text = "MIT" }

{swarph_cli-0.13.1 → swarph_cli-0.13.3}/src/swarph_cli/__init__.py

@@ -16,6 +16,6 @@ The architecture splits CLI from substrate so:
 
 from __future__ import annotations
 
-__version__ = "0.13.1"
+__version__ = "0.13.2"
 
 __all__ = ["__version__"]

{swarph_cli-0.13.1 → swarph_cli-0.13.3}/src/swarph_cli/commands/chat.py

@@ -35,7 +35,7 @@ import sys
 from dataclasses import dataclass, field
 from typing import Optional
 
-from swarph_cli.caller import default_caller
+from swarph_cli.caller import _sanitize_username, default_caller
 
 
 _BANNER = """\
@@ -123,13 +123,17 @@ def _default_repl_caller() -> str:
     """``cli.repl.<user>`` — distinct from ``cli.oneshot.<user>`` so
     attribution rows distinguish REPL turns from one-shot calls.
 
-    Falls back to the caller-convention default if env-derived user
-    extraction fails."""
+    Reuses ``caller._sanitize_username`` (the SAME sanitizer ``default_caller``
+    uses) so the slug is guaranteed convention-valid: leading letter (``u_``
+    prefix if not), collapsed underscores, ``unknown`` on empty. The previous
+    inline slug omitted those guards, so a leading-digit username produced a
+    non-conforming ``cli.repl.3bob`` that crashed SwarphCall at runtime (#83).
+    Falls back to the caller-convention default if env-derived user extraction
+    fails."""
     user = os.environ.get("USER") or os.environ.get("LOGNAME")
     if not user:
         return default_caller()
-    user_slug = "".join(c if c.isalnum() else "_" for c in user.lower())
-    return f"cli.repl.{user_slug}"
+    return f"cli.repl.{_sanitize_username(user)}"
 
 
 def _print(msg: str = "", *, file=None) -> None:

{swarph_cli-0.13.1 → swarph_cli-0.13.3}/src/swarph_cli/commands/spawn.py

@@ -28,6 +28,7 @@ import os
 import shutil
 import subprocess
 import sys
+import time
 from pathlib import Path
 from typing import Optional
 from urllib.parse import quote
@@ -914,6 +915,54 @@ def _tmux_has_session(tmux: str, name: str) -> bool:
     return result.returncode == 0
 
 
+def _tmux_create_session(tmux: str, name: str, cwd: Path) -> bool:
+    """Create the durable detached session that runs ``swarph spawn <name>``.
+
+    Robust against a STALE session registration. When a multiplexer server dies
+    uncleanly (operator closed the owning console, ``kill``, a crash) it can leave
+    the session NAME registered with no live server behind it. On the native-Windows
+    psmux build (``marlocarlo.psmux``) this poisons re-creation: ``new-session``
+    becomes a SILENT no-op — it returns rc=0 but creates nothing — so the name can
+    never come back. That is the exact failure that strands a peer's cell ("the
+    session got killed and won't return"; verified on workstation-lc 2026-06-18).
+    Real tmux on Linux/mac does not hit this, and the extra steps are a harmless
+    no-op there (the create succeeds first try and the loop breaks immediately).
+
+    So: clear any stale registration first (``kill-session`` — a no-op if the name
+    is truly absent), then create. Because psmux clears the stale lock
+    ASYNCHRONOUSLY (~1s observed), do NOT trust the create's exit code (rc=0 even on
+    the silent no-op): VERIFY with ``has-session`` and retry until it actually
+    materialises. Returns True once the session exists, False if it never appears.
+    """
+    create_cmd = [
+        tmux, "new-session", "-d", "-s", name,
+        "-c", str(cwd), "-e", "SWARPH_SPAWN=1",
+        "swarph", "spawn", name,
+    ]
+    # Clear a stale (server-less) registration; harmless if the name is truly absent.
+    try:
+        subprocess.run(
+            [tmux, "kill-session", "-t", f"={name}"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except OSError:
+        return False
+    for attempt in range(6):
+        try:
+            subprocess.run(
+                create_cmd,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE,
+            )
+        except OSError:
+            return False
+        if _tmux_has_session(tmux, name):
+            return True
+        time.sleep(0.4)  # let psmux's async stale-lock clear catch up, then retry
+    return False
+
+
 def _launch_via_tmux(
     binary: str, argv: list[str], cwd: Path, session_name: str,
 ) -> bool:
@@ -978,24 +1027,15 @@ def _launch_via_tmux(
     interactive = sys.stdout.isatty()
 
     if not _tmux_has_session(tmux, session_name):
-        # Create the durable session detached. The command re-enters spawn so
-        # the membrane env-scrub + starter injection apply inside the pane; the
-        # inherited $TMUX (and SWARPH_SPAWN below) stop it from re-deciding.
-        try:
-            subprocess.run(
-                [
-                    tmux, "new-session", "-d", "-s", session_name,
-                    "-c", str(cwd), "-e", "SWARPH_SPAWN=1",
-                    "swarph", "spawn", session_name,
-                ],
-                check=True,
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.PIPE,
-            )
-        except (OSError, subprocess.CalledProcessError) as exc:
+        # Create the durable session detached. The command re-enters spawn so the
+        # membrane env-scrub + starter injection apply inside the pane; the inherited
+        # $TMUX (and SWARPH_SPAWN) stop it from re-deciding. _tmux_create_session
+        # also clears a stale (server-less) registration that would otherwise make
+        # psmux's new-session a silent no-op and strand the cell.
+        if not _tmux_create_session(tmux, session_name, cwd):
             print(
-                f"swarph spawn: tmux session create failed ({exc}); falling "
-                "back to the standard launch.",
+                "swarph spawn: tmux session create failed (stale registration "
+                "could not be cleared?); falling back to the standard launch.",
                 file=sys.stderr,
             )
             return False

{swarph_cli-0.13.1 → swarph_cli-0.13.3}/src/swarph_cli/compress/levers.py

@@ -4,6 +4,12 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass
 
+# Caller tag for the shorthand model call. MUST satisfy swarph_shared's
+# caller convention (^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$ — dotted, not
+# hyphenated), or SwarphCall(...) raises ValueError at runtime. See
+# tests/test_compress_caller_convention.py.
+SHORTHAND_CALLER = "swarph.compress"
+
 
 @dataclass
 class ArchivalResult:
@@ -41,7 +47,7 @@ async def shorthand(source: str, *, system_prompt: str = SHORTHAND_SYSTEM, chat=
     (messages, system_prompt, **kw)->resp with .text; defaults to swarph_mesh."""
     if chat is None:
         from swarph_mesh import ChatMessage, SwarphCall
-        sc = SwarphCall(provider="claude", caller="swarph-compress")
+        sc = SwarphCall(provider="claude", caller=SHORTHAND_CALLER)
         async def chat(messages, system_prompt=None, **kw):
             return await sc.chat(messages=messages, system_prompt=system_prompt, **kw)
         msgs = [ChatMessage(role="user", content=source)]

{swarph_cli-0.13.1 → swarph_cli-0.13.3}/src/swarph_cli/compress/verify.py

@@ -4,6 +4,11 @@ from __future__ import annotations
 import gzip, re
 from pathlib import Path
 
+# Caller tag for the adversarial verify-expand model call. MUST satisfy
+# swarph_shared's dotted caller convention or SwarphCall raises at runtime.
+# See tests/test_compress_caller_convention.py.
+VERIFY_EXPAND_CALLER = "swarph.compress.verify"
+
 _LINK_RE = re.compile(r"\]\(([^)]+)\)")
 
 
@@ -67,7 +72,7 @@ async def verify_expand(source: str, compressed: str, *, chat=None) -> bool:
     fact in source not recoverable from compressed. One dropped fact -> False."""
     if chat is None:
         from swarph_mesh import ChatMessage, SwarphCall
-        sc = SwarphCall(provider="claude", caller="swarph-compress-verify")
+        sc = SwarphCall(provider="claude", caller=VERIFY_EXPAND_CALLER)
         async def chat(messages, system_prompt=None, **kw):
             return await sc.chat(messages=messages, system_prompt=system_prompt, **kw)
         msgs = [ChatMessage(role="user", content=f"ORIGINAL:\n{source}\n\nCOMPRESSED:\n{compressed}")]

{swarph_cli-0.13.1 → swarph_cli-0.13.3/src/swarph_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.13.1
+Version: 0.13.3
 Summary: The `swarph` binary — multi-LLM CLI + mesh-gateway integration: multi-provider `swarph spawn` (claude/codex/antigravity per cell.provider via a ProviderMembrane + subprocess billing-scrub), interactive `swarph init`, `swarph mesh` (send/inbox/register) + inbox sidecar, `assisted_memory` (git-backed durable memory), session import, watchdog. v0.9.5: foolproof Windows auto-relaunch (genuine-WT detection via process ancestry, not WT_SESSION).
 Author: Pierre Samson, Claude Opus
 License: MIT

{swarph_cli-0.13.1 → swarph_cli-0.13.3}/src/swarph_cli.egg-info/SOURCES.txt

@@ -55,6 +55,7 @@ tests/test_artifact_mcp.py
 tests/test_artifact_skill.py
 tests/test_artifact_tool.py
 tests/test_artifact_uri.py
+tests/test_caller_meta_guard.py
 tests/test_capture_lineage.py
 tests/test_capture_liveness.py
 tests/test_capture_manifest.py
@@ -67,6 +68,7 @@ tests/test_cell_verify.py
 tests/test_chat_command.py
 tests/test_claude_parser.py
 tests/test_claude_tmux_template.py
+tests/test_compress_caller_convention.py
 tests/test_compress_command.py
 tests/test_compress_levers.py
 tests/test_compress_marker.py
@@ -90,6 +92,7 @@ tests/test_mesh_sidecar.py
 tests/test_onboard_command.py
 tests/test_protocol_handler.py
 tests/test_ratify_command.py
+tests/test_repl_caller_convention.py
 tests/test_security.py
 tests/test_session_path_role_gate.py
 tests/test_smoke_chat.py

swarph_cli-0.13.3/tests/test_caller_meta_guard.py

@@ -0,0 +1,117 @@
+"""Repo-wide caller-convention meta-guard (issue #81).
+
+The #80 bug: a hyphenated caller tag (`swarph-compress`) was silently dead at
+runtime because it fails swarph_shared's dotted `role.subrole` convention — and it
+was masked because the levers/verify tests injected a fake chat and never built a
+real SwarphCall. That fix added a per-caller regression test for the two compress
+callers. THIS guard generalizes it: it discovers EVERY static caller tag across the
+whole `swarph_cli` package by import-introspection and validates each, so the bug
+class can't be re-introduced in ANY module without someone remembering to add a
+per-caller test.
+
+Design (converged lab+droplet, #81): import-introspection, not AST literal-walking.
+The callers live in named `*_CALLER` constants — `caller=SHORTHAND_CALLER` is an
+ast.Name, not a literal, so a naive literal-walk would miss exactly the callers #80
+hardened. Introspection resolves the value for free and nudges the light convention
+that caller tags live in discoverable `*_CALLER` constants.
+
+NOT covered here (separate follow-up, flagged in the PR): the DYNAMIC default-caller
+producers (`default_caller` / `_default_repl_caller`) do not guarantee an
+[a-z]-leading slug, so a leading-digit/empty OS username yields a non-conforming
+`cli.repl.<digit...>` tag — a real robustness bug in the sanitizers, out of scope
+for this static meta-guard.
+"""
+import importlib
+import pkgutil
+
+import swarph_cli
+from swarph_shared.caller_convention import validate_caller
+
+
+def _iter_caller_constants():
+    """Yield (module, attr, value) for every module-level ``*_CALLER`` str constant
+    across the swarph_cli package. Walks the package so a NEW module's caller
+    constant is covered automatically. A submodule that can't be imported in this
+    env (e.g. an optional dep) is skipped — importability is other tests' concern,
+    not this guard's."""
+    for mod in pkgutil.walk_packages(swarph_cli.__path__, swarph_cli.__name__ + "."):
+        try:
+            m = importlib.import_module(mod.name)
+        except Exception:
+            continue
+        for attr in dir(m):
+            if attr.endswith("_CALLER"):
+                val = getattr(m, attr, None)
+                if isinstance(val, str):
+                    yield mod.name, attr, val
+
+
+def test_all_caller_constants_conform():
+    """Every ``*_CALLER`` constant in the package satisfies the dotted convention."""
+    found = list(_iter_caller_constants())
+    # Sanity: the compress callers from #80 must be discovered, else the walk is broken
+    # (e.g. swarph_cli resolving to a stale install rather than this tree).
+    names = {f"{m.rsplit('.', 1)[-1]}.{a}" for m, a, _ in found}
+    assert "levers.SHORTHAND_CALLER" in names and "verify.VERIFY_EXPAND_CALLER" in names, (
+        f"meta-guard didn't discover the known compress callers; found: {sorted(names)}")
+    for modname, attr, val in found:
+        try:
+            validate_caller(val)
+        except ValueError as e:
+            raise AssertionError(
+                f"caller constant {modname}.{attr} = {val!r} violates the convention "
+                f"(dotted role.subrole) — would crash SwarphCall at runtime: {e}")
+
+
+def test_default_caller_producers_conform_happy_path(monkeypatch):
+    """The default-caller producers emit a conforming tag for a normal username.
+    Username is injected so this is deterministic regardless of the CI runner's
+    real user (the adversarial leading-digit case is a flagged follow-up, not here)."""
+    monkeypatch.setenv("USER", "alice")
+    monkeypatch.setenv("LOGNAME", "alice")
+    from swarph_cli.main import default_caller
+    from swarph_cli.commands.chat import _default_repl_caller
+    for fn in (default_caller, _default_repl_caller):
+        val = fn()
+        try:
+            validate_caller(val)
+        except ValueError as e:
+            raise AssertionError(
+                f"{fn.__module__}.{fn.__name__}() -> {val!r} violates the convention: {e}")
+
+
+def test_guard_catches_a_planted_bad_caller(monkeypatch):
+    """PIN the catch-property — a guard's catch must be COMMITTED, not remembered
+    (the very #80 lesson this PR generalizes; droplet review). Plant a hyphenated
+    `*_CALLER` on a real, discovered module and assert the guard both DISCOVERS it
+    and REJECTS it. monkeypatch auto-removes the plant so the real guard test stays
+    clean regardless of order."""
+    import pytest
+
+    import swarph_cli.compress.levers as lev
+    monkeypatch.setattr(lev, "PLANTED_BAD_CALLER", "swarph-bad-hyphen", raising=False)
+
+    # 1) introspection DISCOVERS the planted constant
+    found = {f"{m}.{a}": v for m, a, v in _iter_caller_constants()}
+    assert found.get("swarph_cli.compress.levers.PLANTED_BAD_CALLER") == "swarph-bad-hyphen", (
+        "the walk failed to discover a planted *_CALLER — discovery is broken")
+
+    # 2) the guard CATCHES it (fails loud, names the offending constant)
+    with pytest.raises(AssertionError, match="violates the convention"):
+        test_all_caller_constants_conform()
+
+
+def test_no_modules_skipped_by_the_walk():
+    """The guard resiliently SKIPS an unimportable submodule (so an unrelated optional-
+    dep import error can't break it) — but a silent skip could hide a bad caller in a
+    module that's importable in prod yet not in this env. Assert NONE are skipped here,
+    so the walk is exhaustive; if this ever fails in CI, run with full extras."""
+    skipped = []
+    for mod in pkgutil.walk_packages(swarph_cli.__path__, swarph_cli.__name__ + "."):
+        try:
+            importlib.import_module(mod.name)
+        except Exception as e:  # noqa: BLE001 — we want to surface ANY import failure
+            skipped.append((mod.name, repr(e)))
+    assert not skipped, (
+        f"caller meta-guard walk skipped modules (a bad caller in one could ship "
+        f"uncaught): {skipped}")

swarph_cli-0.13.3/tests/test_compress_caller_convention.py

@@ -0,0 +1,21 @@
+"""Regression: the compress model-call caller tags MUST satisfy swarph_shared's
+caller convention (dotted `role.subrole`, not hyphenated). The existing
+levers/verify tests inject a fake `chat` and never construct a real SwarphCall,
+so they passed while the production path crashed at SwarphCall(...) on a
+hyphenated caller ('swarph-compress'). This test checks the tags directly so
+the break can't silently regress again."""
+from swarph_shared.caller_convention import validate_caller
+
+from swarph_cli.compress.levers import SHORTHAND_CALLER
+from swarph_cli.compress.verify import VERIFY_EXPAND_CALLER
+
+
+def test_shorthand_caller_matches_convention():
+    # raises ValueError if it doesn't match ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$
+    validate_caller(SHORTHAND_CALLER)
+    assert SHORTHAND_CALLER == "swarph.compress"
+
+
+def test_verify_expand_caller_matches_convention():
+    validate_caller(VERIFY_EXPAND_CALLER)
+    assert VERIFY_EXPAND_CALLER == "swarph.compress.verify"

swarph_cli-0.13.3/tests/test_repl_caller_convention.py

@@ -0,0 +1,43 @@
+"""Regression (#83): `_default_repl_caller` must emit a convention-valid caller for
+ANY OS username — including the adversarial cases the old inline slug logic broke on.
+
+#80 fixed a hyphenated STATIC caller constant. This is the same crash-class on the
+DYNAMIC repl-default path: `_default_repl_caller` rolled its own slug
+(`"".join(c if c.isalnum() else "_" ...)`) that — unlike `caller._sanitize_username`
+which `default_caller` uses — did NOT guarantee a leading letter, collapse underscores,
+or fall back on empty. So a leading-digit username produced `cli.repl.3bob`, which
+fails `^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$` and would crash SwarphCall at runtime.
+Fix: reuse `_sanitize_username` (single sanitizer, no divergence).
+"""
+import pytest
+
+from swarph_shared.caller_convention import validate_caller
+
+from swarph_cli.commands.chat import _default_repl_caller
+
+
+@pytest.mark.parametrize("username", [
+    "3bob",      # leading digit — the reported crash
+    "9",         # all-digit
+    "!!!",       # all-special -> empty slug -> must fall back, not emit `cli.repl.`
+    "ALICE",     # uppercase
+    "bob.smith", # dot (would otherwise split the segment)
+    "a-b-c",     # hyphens (the #80 char)
+    "_",         # underscore-only -> empty after strip
+    "  ",        # whitespace-only
+])
+def test_repl_caller_conforms_for_adversarial_usernames(monkeypatch, username):
+    """The repl default caller validates clean for every adversarial username."""
+    monkeypatch.setenv("USER", username)
+    monkeypatch.delenv("LOGNAME", raising=False)
+    # raises ValueError if the produced tag violates the convention
+    validate_caller(_default_repl_caller())
+
+
+def test_repl_caller_stays_distinct_from_oneshot(monkeypatch):
+    """Still `cli.repl.*` (not `cli.oneshot.*`) — the separate producer exists so
+    attribution distinguishes REPL turns from one-shot calls; the fix must not
+    collapse them."""
+    monkeypatch.setenv("USER", "alice")
+    monkeypatch.delenv("LOGNAME", raising=False)
+    assert _default_repl_caller().startswith("cli.repl.")

{swarph_cli-0.13.1 → swarph_cli-0.13.3}/tests/test_spawn_command.py

@@ -1323,6 +1323,13 @@ def test_run_spawn_grok_assisted_memory_no_double_system_prompt(
     monkeypatch.setattr("shutil.which", lambda name: "/bin/fake-grok")
     # neutralize the named-tmux launch so we reach launch()/execve in-test
     monkeypatch.setattr(spawn, "_launch_via_tmux", lambda *a, **k: False)
+    # This asserts on the composed argv (no doubled --system-prompt-override),
+    # which is platform-independent. Pin to a POSIX platform so launch() takes the
+    # os.execve branch we mock below — otherwise on Windows it takes the
+    # subprocess.run branch (v0.12.1 pane-collapse fix), the execve mock never
+    # fires, and the real /bin/fake-grok exec fails (WinError 2). Matches the
+    # platform-pinning convention of the launch tests above.
+    monkeypatch.setattr(spawn.sys, "platform", "linux")
 
     exec_args = []
     monkeypatch.setattr("os.execve", lambda p, a, e: exec_args.append((p, a, e)))

{swarph_cli-0.13.1 → swarph_cli-0.13.3}/tests/test_spawn_tmux_session.py

@@ -59,19 +59,27 @@ class _FakeStdout:
 
 def _drive(monkeypatch, *, platform="win32", tmux=TMUX, wt=WT, in_tmux=None,
            spawn_marker=None, isatty=True, session_exists=False,
-           new_session_exc=None):
+           new_session_exc=None, create_succeeds=True, create_succeeds_after=1):
     """Drive `_launch_via_tmux` with tmux/subprocess/execv mocked.
 
-    `run` dispatches on the subcommand: `has-session` returns rc 0/1 per
-    `session_exists`; `new-session` returns rc 0 (or raises `new_session_exc`);
-    `attach` (Windows path only) returns rc 0. The POSIX attach is os.execv,
-    mocked to raise `_ExecvReplaced` (simulating its never-returns replace).
+    `run` dispatches on the subcommand and is STATEFUL to model reality after the
+    stale-registration fix: `has-session` returns rc 0 once the session exists —
+    either pre-existing (`session_exists`) OR after a `new-session` "takes".
+    `_tmux_create_session` clears a stale reg (`kill-session`, rc 0 here) then
+    creates + VERIFIES via `has-session`, retrying because psmux clears the stale
+    lock asynchronously. `create_succeeds_after` models that delay: the session
+    only materialises on the Nth `new-session` call (1 = first try, the happy
+    path). `create_succeeds=False` models a create that never materialises (e.g. a
+    stale lock that won't clear) → the loop exhausts and returns False.
+    `new-session` raises `new_session_exc` when set. `attach` (Windows) returns rc
+    0; POSIX attach is os.execv, mocked to raise `_ExecvReplaced`.
 
     Returns `(result, run, execv)`. `result` is the function's bool, or the
     `_EXECV` sentinel when the POSIX execv attach took over.
     """
     monkeypatch.setattr(spawn.sys, "platform", platform)
     monkeypatch.setattr(spawn.sys, "stdout", _FakeStdout(isatty))
+    monkeypatch.setattr(spawn.time, "sleep", lambda *_a, **_k: None)  # no real wait
     for var, val in (("TMUX", in_tmux), ("SWARPH_SPAWN", spawn_marker)):
         if val is None:
             monkeypatch.delenv(var, raising=False)
@@ -83,12 +91,20 @@ def _drive(monkeypatch, *, platform="win32", tmux=TMUX, wt=WT, in_tmux=None,
 
     monkeypatch.setattr(spawn.shutil, "which", _which)
 
+    state = {"new_calls": 0, "created": False}
+
     def _run(cmd, **kwargs):
         if "has-session" in cmd:
-            return MagicMock(returncode=0 if session_exists else 1)
-        if "new-session" in cmd and new_session_exc is not None:
-            raise new_session_exc
-        return MagicMock(returncode=0)
+            exists = session_exists or state["created"]
+            return MagicMock(returncode=0 if exists else 1)
+        if "new-session" in cmd:
+            if new_session_exc is not None:
+                raise new_session_exc
+            state["new_calls"] += 1
+            if create_succeeds and state["new_calls"] >= create_succeeds_after:
+                state["created"] = True
+            return MagicMock(returncode=0)
+        return MagicMock(returncode=0)  # kill-session, attach, ...
 
     run = MagicMock(side_effect=_run)
     monkeypatch.setattr(spawn.subprocess, "run", run)
@@ -108,6 +124,11 @@ def _cmds(run):
     return [c.args[0] for c in run.call_args_list]
 
 
+def _killed_stale(run):
+    """True if the stale-registration clear (`kill-session`) was issued."""
+    return any("kill-session" in c for c in _cmds(run))
+
+
 def _attached_via_run(run):
     """True if the Windows blocking-subprocess.run attach fired."""
     return [TMUX, "attach", "-t", SESSION] in _cmds(run)
@@ -239,17 +260,33 @@ def test_existing_session_headless_is_a_noop_handoff(monkeypatch, platform):
 
 
 @pytest.mark.parametrize("platform", ["win32", "linux"])
-def test_create_failure_falls_through(monkeypatch, platform):
-    # tmux new-session errors => return False so the caller drops to the standard
-    # launch; never attach a half-created session.
-    boom = subprocess.CalledProcessError(1, "tmux")
+def test_create_never_materialises_falls_through(monkeypatch, platform):
+    # The session never appears (e.g. a psmux stale registration that won't clear:
+    # new-session returns rc 0 but creates nothing). The verify+retry loop exhausts
+    # => return False so the caller drops to the standard launch; never attach a
+    # phantom session. We also issued the stale-clear kill-session first.
     r, run, execv = _drive(monkeypatch, platform=platform,
-                           session_exists=False, new_session_exc=boom)
+                           session_exists=False, create_succeeds=False)
     assert r is False
+    assert _killed_stale(run)
     assert not _attached_via_run(run)
     execv.assert_not_called()
 
 
+@pytest.mark.parametrize("platform", ["win32", "linux", "darwin"])
+def test_stale_registration_cleared_then_create_retried(monkeypatch, platform):
+    # The poisoned-name recovery path: kill-session clears the stale reg, but psmux
+    # clears the lock async so the FIRST new-session is a silent no-op; the session
+    # only materialises on the 2nd attempt. The verify loop must retry and succeed.
+    r, run, execv = _drive(monkeypatch, platform=platform, session_exists=False,
+                           isatty=False, create_succeeds_after=2)
+    assert r is True                              # headless: created, claimed launch
+    assert _killed_stale(run)                     # stale reg cleared first
+    new_calls = [c for c in _cmds(run) if "new-session" in c]
+    assert len(new_calls) >= 2                    # retried past the silent no-op
+    execv.assert_not_called()
+
+
 @pytest.mark.parametrize("platform", ["win32", "linux"])
 def test_create_oserror_falls_through(monkeypatch, platform):
     r, run, execv = _drive(