swarph-cli 0.19.0__tar.gz → 0.20.0__tar.gz

{swarph_cli-0.19.0/src/swarph_cli.egg-info → swarph_cli-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.19.0
+Version: 0.20.0
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -51,6 +51,8 @@ pip install swarph-cli
 swarph --version
 ```
 
+> **System requirement — a terminal multiplexer.** The session verbs (`spawn`, `cell`, `watchdog`) drive a `tmux`-compatible multiplexer. On **Linux/macOS** install `tmux` (`apt install tmux` / `brew install tmux`). On **Windows** there is no native tmux — install [**psmux**](https://github.com/psmux/psmux) (a Rust tmux-for-Windows, MIT) with `swarph install-multiplexer` (fetches the pinned, checksum-verified binary into `~/.swarph/bin`) or `winget install marlocarlo.psmux`.
+
 **What it is:** a multi-provider LLM command line. Run one-shot prompts or an interactive REPL against any supported provider; spawn long-lived agent *cells* that persist across restarts and coordinate over a mesh; install hooks, MCP servers, and skills by content-addressed URI. An open, inspectable substrate — not a closed orchestration platform.
 
 **Who it's for:** builders running more than one LLM who want them to *cooperate* instead of sitting in separate tabs — multi-agent systems across vendors, agnostic by design. A thin client over the [`swarph-mesh`](https://github.com/BrainSurfing-tech/swarph-mesh) substrate library.
@@ -79,6 +81,7 @@ swarph highlight "<x>"   log a highlight to the shared git-backed swarph timelin
 swarph spawn <role>      launch a long-lived agent session as a named mesh cell
 swarph daemon            foreground inbox-drain loop (the mesh doorbell)
 swarph watchdog          detect + recover stranded agent sessions (cron- or systemd-driven)
+swarph install-multiplexer   fetch the Windows tmux multiplexer (psmux) — pinned + checksum-verified
 swarph add <uri>         install a hook / MCP server / skill by content-addressed URI
 swarph hooks             install Claude Code hooks as reusable artifacts
 swarph onboard / ratify  bring a new peer into the mesh (mechanics + witness ratification)

{swarph_cli-0.19.0 → swarph_cli-0.20.0}/README.md

@@ -7,6 +7,8 @@ pip install swarph-cli
 swarph --version
 ```
 
+> **System requirement — a terminal multiplexer.** The session verbs (`spawn`, `cell`, `watchdog`) drive a `tmux`-compatible multiplexer. On **Linux/macOS** install `tmux` (`apt install tmux` / `brew install tmux`). On **Windows** there is no native tmux — install [**psmux**](https://github.com/psmux/psmux) (a Rust tmux-for-Windows, MIT) with `swarph install-multiplexer` (fetches the pinned, checksum-verified binary into `~/.swarph/bin`) or `winget install marlocarlo.psmux`.
+
 **What it is:** a multi-provider LLM command line. Run one-shot prompts or an interactive REPL against any supported provider; spawn long-lived agent *cells* that persist across restarts and coordinate over a mesh; install hooks, MCP servers, and skills by content-addressed URI. An open, inspectable substrate — not a closed orchestration platform.
 
 **Who it's for:** builders running more than one LLM who want them to *cooperate* instead of sitting in separate tabs — multi-agent systems across vendors, agnostic by design. A thin client over the [`swarph-mesh`](https://github.com/BrainSurfing-tech/swarph-mesh) substrate library.
@@ -35,6 +37,7 @@ swarph highlight "<x>"   log a highlight to the shared git-backed swarph timelin
 swarph spawn <role>      launch a long-lived agent session as a named mesh cell
 swarph daemon            foreground inbox-drain loop (the mesh doorbell)
 swarph watchdog          detect + recover stranded agent sessions (cron- or systemd-driven)
+swarph install-multiplexer   fetch the Windows tmux multiplexer (psmux) — pinned + checksum-verified
 swarph add <uri>         install a hook / MCP server / skill by content-addressed URI
 swarph hooks             install Claude Code hooks as reusable artifacts
 swarph onboard / ratify  bring a new peer into the mesh (mechanics + witness ratification)

{swarph_cli-0.19.0 → swarph_cli-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.19.0"
+version = "0.20.0"
 description = "The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }

{swarph_cli-0.19.0 → swarph_cli-0.20.0}/src/swarph_cli/__init__.py

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

swarph_cli-0.20.0/src/swarph_cli/commands/install_multiplexer.py

@@ -0,0 +1,59 @@
+"""``swarph install-multiplexer`` — fetch the checksum-verified psmux binary.
+
+swarph's session machinery needs a ``tmux``-compatible multiplexer on PATH. On
+Linux/macOS that's native ``tmux`` (install via apt/brew). On Windows there's no
+pip/npm package, so this verb fetches the pinned, SHA-256-verified **psmux**
+release zip and drops its ``tmux.exe`` into ``--dir`` (default
+``~/.swarph/bin``). The download is verified before anything is written.
+
+Usage:
+  swarph install-multiplexer [--dir DIR] [--force] [--version 3.3.6]
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from swarph_cli.multiplexer import (
+    PSMUX_VERSION,
+    find_multiplexer,
+    install_psmux,
+)
+
+
+def run_install_multiplexer(argv: list) -> int:
+    p = argparse.ArgumentParser(
+        prog="swarph install-multiplexer",
+        description="Fetch the checksum-verified psmux (tmux-for-Windows) binary.")
+    p.add_argument("--dir", default=os.path.expanduser("~/.swarph/bin"),
+                   help="install directory (default ~/.swarph/bin)")
+    p.add_argument("--force", action="store_true",
+                   help="reinstall even if a multiplexer is already on PATH")
+    p.add_argument("--version", default=PSMUX_VERSION,
+                   help=f"psmux version to fetch (default {PSMUX_VERSION})")
+    args = p.parse_args(argv)
+
+    if sys.platform != "win32":
+        print("swarph install-multiplexer fetches the Windows psmux binary. On "
+              "Linux/macOS, tmux is the native multiplexer — install it via your "
+              "package manager (`apt install tmux` / `brew install tmux`).",
+              file=sys.stderr)
+        return 0
+
+    if not args.force:
+        present = find_multiplexer()
+        if present:
+            print(f"multiplexer already present at {present}")
+            return 0
+
+    try:
+        path = install_psmux(args.dir, version=args.version)
+    except (RuntimeError, ValueError, OSError) as err:
+        print(f"swarph install-multiplexer: {err}", file=sys.stderr)
+        return 1
+
+    print(f"installed psmux {args.version} -> {path}; "
+          f"add {args.dir} to your PATH")
+    return 0

{swarph_cli-0.19.0 → swarph_cli-0.20.0}/src/swarph_cli/commands/spawn.py

@@ -1029,6 +1029,14 @@ def _launch_via_tmux(
         return False
     tmux = shutil.which("tmux")
     if not tmux:
+        # No tmux-compatible multiplexer on PATH — fall back (Windows: WT rescue
+        # / in-place). Surface a soft, actionable hint when interactive (Windows
+        # users typically need psmux); stay silent on headless/respawn paths so
+        # the watchdog/CI logs aren't spammed.
+        if sys.stdout.isatty():
+            from swarph_cli.multiplexer import find_multiplexer, multiplexer_hint
+            if find_multiplexer() is None:
+                print(f"swarph spawn: {multiplexer_hint()}", file=sys.stderr)
         return False
 
     interactive = sys.stdout.isatty()

{swarph_cli-0.19.0 → swarph_cli-0.20.0}/src/swarph_cli/main.py

@@ -98,6 +98,7 @@ _VERB_HANDLERS: dict[str, str] = {
     "channel": "swarph_cli.commands.channel.run_channel",
     "schedule": "swarph_cli.commands.schedule.run_schedule",
     "lane": "swarph_cli.commands.lane.run_lane",
+    "install-multiplexer": "swarph_cli.commands.install_multiplexer.run_install_multiplexer",
     "highlight": "swarph_cli.commands.highlight.run_highlight",
     # Future: "list-peers", "list-adapters", etc.
 }

swarph_cli-0.20.0/src/swarph_cli/multiplexer.py

@@ -0,0 +1,138 @@
+"""Multiplexer detection + the checksum-verified psmux fetcher.
+
+swarph's session machinery (spawn/cell/watchdog) shells out to a ``tmux``-
+compatible binary. On Linux/macOS that's ``tmux`` from the package manager; on
+Windows it's **psmux** (https://github.com/psmux/psmux — a Rust tmux-for-Windows,
+MIT) which installs a ``tmux`` command on PATH. psmux isn't on pip/npm — it ships
+as per-arch GitHub release zips, so we fetch the pinned, **checksum-verified**
+binary ourselves.
+
+Security core (``install_psmux``): the order is download -> verify SHA-256 ->
+(reject on mismatch, OR extract). A bad download NEVER reaches extraction, and a
+malicious archive member name can never escape ``dest_dir`` (zip-slip guard:
+only ``os.path.basename`` is ever honored). Nothing is executed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import platform
+import shutil
+import sys
+import tempfile
+import urllib.request
+import zipfile
+
+# --- pinned psmux release (v3.3.6, GitHub-attested digests) -----------------
+
+PSMUX_VERSION = "3.3.6"
+_URL = "https://github.com/psmux/psmux/releases/download/v3.3.6/{filename}"
+_ASSETS = {  # arch -> (filename, sha256)
+    "x64":   ("psmux-v3.3.6-windows-x64.zip",   "a56a890ea0829567818b9a368f16dcbd39c087f27328573df17c10dd39618947"),
+    "arm64": ("psmux-v3.3.6-windows-arm64.zip", "bf1e8bb9d624a2fe5cb09f6b5bb84e7f516cfd022efb677a2439f846a39f8f92"),
+    "x86":   ("psmux-v3.3.6-windows-x86.zip",   "9b387fe03cbcc1ef671a5c3fbddaafe383089d82cea03c567980d8ed3de9ba82"),
+}
+
+# binaries we accept out of the archive (basename, case-insensitive); the first
+# is the primary whose path we return.
+_BINARIES = ("tmux.exe", "psmux.exe", "pmux.exe")
+
+
+def find_multiplexer() -> str | None:
+    """Return the path of the first tmux-compatible multiplexer on PATH, else None."""
+    for name in ("tmux", "psmux", "pmux"):
+        found = shutil.which(name)
+        if found:
+            return found
+    return None
+
+
+def multiplexer_hint() -> str:
+    """A one-line, OS-aware install hint for a missing multiplexer."""
+    if sys.platform == "win32":
+        return ("no tmux-compatible multiplexer found — run "
+                "`swarph install-multiplexer` (fetches psmux) or "
+                "`winget install marlocarlo.psmux`")
+    return ("no tmux found — install it via your package manager "
+            "(e.g. `apt install tmux` / `brew install tmux`)")
+
+
+def _detect_arch() -> str:
+    """Map ``platform.machine()`` to an ``_ASSETS`` key; raise ValueError otherwise."""
+    machine = platform.machine()
+    m = machine.lower()
+    if m in ("amd64", "x86_64"):
+        return "x64"
+    if m in ("arm64", "aarch64"):
+        return "arm64"
+    if m in ("x86", "i686", "i386"):
+        return "x86"
+    raise ValueError(f"unsupported architecture for psmux: {machine!r}")
+
+
+def _default_opener(url: str) -> bytes:
+    with urllib.request.urlopen(url) as resp:  # noqa: S310 (pinned github.com URL)
+        return resp.read()
+
+
+def install_psmux(dest_dir, *, version=PSMUX_VERSION, opener=None) -> str:
+    """Fetch + verify + extract the pinned psmux binary into ``dest_dir``.
+
+    Order is load-bearing: download -> SHA-256 verify -> (reject OR extract). A
+    checksum mismatch raises BEFORE anything is written, and only the basename of
+    an archive member is ever honored (zip-slip guard). Returns the path to the
+    extracted primary binary (``tmux.exe``). Nothing is executed.
+    """
+    opener = opener or _default_opener
+
+    # 1. resolve the pinned asset for this arch
+    arch = _detect_arch()
+    filename, expected_sha = _ASSETS[arch]
+
+    # 2. download
+    data = opener(_URL.format(filename=filename))
+
+    # 3. verify BEFORE touching the filesystem — a bad download stops here
+    actual_sha = hashlib.sha256(data).hexdigest()
+    if actual_sha != expected_sha:
+        raise RuntimeError(
+            f"psmux checksum mismatch for {filename}: "
+            f"expected {expected_sha}, got {actual_sha} — refusing to extract")
+
+    # 4. only now open the verified archive and extract the binaries
+    os.makedirs(dest_dir, exist_ok=True)
+    written: dict[str, str] = {}
+    with zipfile.ZipFile(io.BytesIO(data)) as zf:
+        for member in zf.namelist():
+            base = os.path.basename(member)
+            # zip-slip guard: never honor a path component; skip anything that
+            # isn't a plain basename (no separators, no traversal).
+            if not base or base != member or ".." in member \
+                    or "/" in member or "\\" in member:
+                continue
+            if base.lower() not in _BINARIES:
+                continue
+            target = os.path.join(dest_dir, base)
+            # atomic write: temp file in dest_dir, then os.replace
+            fd, tmp = tempfile.mkstemp(dir=dest_dir, prefix=".psmux-")
+            try:
+                with os.fdopen(fd, "wb") as fh:
+                    fh.write(zf.read(member))
+                os.replace(tmp, target)
+            except BaseException:
+                if os.path.exists(tmp):
+                    os.remove(tmp)
+                raise
+            written[base.lower()] = target
+
+    if not written:
+        raise RuntimeError(
+            f"no psmux binary ({'/'.join(_BINARIES)}) found in {filename}")
+
+    # return the primary (tmux.exe) if present, else whatever we extracted
+    for name in _BINARIES:
+        if name in written:
+            return written[name]
+    return next(iter(written.values()))

{swarph_cli-0.19.0 → swarph_cli-0.20.0/src/swarph_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.19.0
+Version: 0.20.0
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -51,6 +51,8 @@ pip install swarph-cli
 swarph --version
 ```
 
+> **System requirement — a terminal multiplexer.** The session verbs (`spawn`, `cell`, `watchdog`) drive a `tmux`-compatible multiplexer. On **Linux/macOS** install `tmux` (`apt install tmux` / `brew install tmux`). On **Windows** there is no native tmux — install [**psmux**](https://github.com/psmux/psmux) (a Rust tmux-for-Windows, MIT) with `swarph install-multiplexer` (fetches the pinned, checksum-verified binary into `~/.swarph/bin`) or `winget install marlocarlo.psmux`.
+
 **What it is:** a multi-provider LLM command line. Run one-shot prompts or an interactive REPL against any supported provider; spawn long-lived agent *cells* that persist across restarts and coordinate over a mesh; install hooks, MCP servers, and skills by content-addressed URI. An open, inspectable substrate — not a closed orchestration platform.
 
 **Who it's for:** builders running more than one LLM who want them to *cooperate* instead of sitting in separate tabs — multi-agent systems across vendors, agnostic by design. A thin client over the [`swarph-mesh`](https://github.com/BrainSurfing-tech/swarph-mesh) substrate library.
@@ -79,6 +81,7 @@ swarph highlight "<x>"   log a highlight to the shared git-backed swarph timelin
 swarph spawn <role>      launch a long-lived agent session as a named mesh cell
 swarph daemon            foreground inbox-drain loop (the mesh doorbell)
 swarph watchdog          detect + recover stranded agent sessions (cron- or systemd-driven)
+swarph install-multiplexer   fetch the Windows tmux multiplexer (psmux) — pinned + checksum-verified
 swarph add <uri>         install a hook / MCP server / skill by content-addressed URI
 swarph hooks             install Claude Code hooks as reusable artifacts
 swarph onboard / ratify  bring a new peer into the mesh (mechanics + witness ratification)

{swarph_cli-0.19.0 → swarph_cli-0.20.0}/src/swarph_cli.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/swarph_cli/__init__.py
 src/swarph_cli/caller.py
 src/swarph_cli/cell.py
 src/swarph_cli/main.py
+src/swarph_cli/multiplexer.py
 src/swarph_cli.egg-info/PKG-INFO
 src/swarph_cli.egg-info/SOURCES.txt
 src/swarph_cli.egg-info/dependency_links.txt
@@ -35,6 +36,7 @@ src/swarph_cli/commands/hooks.py
 src/swarph_cli/commands/import_session.py
 src/swarph_cli/commands/init.py
 src/swarph_cli/commands/install_hook.py
+src/swarph_cli/commands/install_multiplexer.py
 src/swarph_cli/commands/lane.py
 src/swarph_cli/commands/mcp_server.py
 src/swarph_cli/commands/memory_sync.py
@@ -108,12 +110,14 @@ tests/test_hooks_merge.py
 tests/test_import_command.py
 tests/test_init_command.py
 tests/test_install_hook.py
+tests/test_install_multiplexer_command.py
 tests/test_lane_command.py
 tests/test_main.py
 tests/test_mcp_server.py
 tests/test_memory_sync.py
 tests/test_mesh_command.py
 tests/test_mesh_sidecar.py
+tests/test_multiplexer.py
 tests/test_onboard_command.py
 tests/test_protocol_handler.py
 tests/test_ratify_command.py

swarph_cli-0.20.0/tests/test_install_multiplexer_command.py

@@ -0,0 +1,77 @@
+"""Tests for ``swarph install-multiplexer`` — fetch the checksum-verified psmux
+binary on Windows; on Linux/macOS it just points at the native tmux.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+from swarph_cli.commands import install_multiplexer as im
+
+
+def test_install_multiplexer_registered_in_verb_handlers():
+    from swarph_cli.main import _VERB_HANDLERS
+    handler = _VERB_HANDLERS.get("install-multiplexer")
+    if handler is None:
+        pytest.skip("verb not yet registered by parent (main.py owned externally)")
+    assert handler == "swarph_cli.commands.install_multiplexer.run_install_multiplexer"
+
+
+def test_non_windows_prints_native_tmux_hint(monkeypatch, capsys):
+    # FORCE the non-Windows branch regardless of host — CI runs on Windows too,
+    # where the unforced verb would take the Windows path (host-dependent green).
+    monkeypatch.setattr(im.sys, "platform", "linux")
+    rc = im.run_install_multiplexer([])
+    assert rc == 0
+    err = capsys.readouterr().err.lower()
+    assert "tmux" in err
+    assert "apt" in err or "brew" in err
+
+
+def test_windows_already_present_returns_0(monkeypatch, capsys):
+    monkeypatch.setattr(im.sys, "platform", "win32")
+    monkeypatch.setattr(im, "find_multiplexer", lambda: "C:/tools/tmux.exe")
+    rc = im.run_install_multiplexer([])
+    assert rc == 0
+    assert "already present" in capsys.readouterr().out.lower()
+
+
+def test_windows_installs_when_absent(monkeypatch, capsys):
+    monkeypatch.setattr(im.sys, "platform", "win32")
+    monkeypatch.setattr(im, "find_multiplexer", lambda: None)
+    monkeypatch.setattr(im, "install_psmux",
+                        lambda d, **kw: "C:/Users/x/.swarph/bin/tmux.exe")
+    rc = im.run_install_multiplexer([])
+    assert rc == 0
+    assert "installed" in capsys.readouterr().out.lower()
+
+
+def test_windows_force_reinstalls_even_if_present(monkeypatch, capsys):
+    calls = {}
+    monkeypatch.setattr(im.sys, "platform", "win32")
+    monkeypatch.setattr(im, "find_multiplexer", lambda: "C:/tools/tmux.exe")
+
+    def fake_install(d, **kw):
+        calls["hit"] = True
+        return "C:/Users/x/.swarph/bin/tmux.exe"
+
+    monkeypatch.setattr(im, "install_psmux", fake_install)
+    rc = im.run_install_multiplexer(["--force"])
+    assert rc == 0
+    assert calls.get("hit") is True
+    assert "installed" in capsys.readouterr().out.lower()
+
+
+def test_windows_install_error_returns_1(monkeypatch, capsys):
+    monkeypatch.setattr(im.sys, "platform", "win32")
+    monkeypatch.setattr(im, "find_multiplexer", lambda: None)
+
+    def boom(d, **kw):
+        raise RuntimeError("psmux checksum mismatch")
+
+    monkeypatch.setattr(im, "install_psmux", boom)
+    rc = im.run_install_multiplexer([])
+    assert rc == 1
+    assert "checksum mismatch" in capsys.readouterr().err.lower()

swarph_cli-0.20.0/tests/test_multiplexer.py

@@ -0,0 +1,144 @@
+"""Tests for the multiplexer helper — detect tmux/psmux + the checksum-verified
+psmux fetcher.
+
+The load-bearing security property: ``install_psmux`` MUST verify the SHA-256 of
+the downloaded bytes BEFORE it writes or extracts anything, and it MUST never
+honor a path component inside the zip (zip-slip). A bad download or a malicious
+archive name therefore never reaches the filesystem outside ``dest_dir``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import zipfile
+
+import pytest
+
+from swarph_cli import multiplexer as mx
+
+
+# --- find_multiplexer -------------------------------------------------------
+
+def test_find_multiplexer_returns_path_when_tmux_present(monkeypatch):
+    monkeypatch.setattr(mx.shutil, "which",
+                        lambda name: "/usr/bin/tmux" if name == "tmux" else None)
+    assert mx.find_multiplexer() == "/usr/bin/tmux"
+
+
+def test_find_multiplexer_returns_none_when_nothing_found(monkeypatch):
+    monkeypatch.setattr(mx.shutil, "which", lambda name: None)
+    assert mx.find_multiplexer() is None
+
+
+def test_find_multiplexer_falls_back_to_psmux(monkeypatch):
+    monkeypatch.setattr(mx.shutil, "which",
+                        lambda name: "/c/psmux.exe" if name == "psmux" else None)
+    assert mx.find_multiplexer() == "/c/psmux.exe"
+
+
+# --- multiplexer_hint -------------------------------------------------------
+
+def test_hint_windows_mentions_install_verb(monkeypatch):
+    monkeypatch.setattr(mx.sys, "platform", "win32")
+    hint = mx.multiplexer_hint()
+    assert "install-multiplexer" in hint and "psmux" in hint
+
+
+def test_hint_posix_mentions_package_manager(monkeypatch):
+    monkeypatch.setattr(mx.sys, "platform", "linux")
+    hint = mx.multiplexer_hint()
+    assert "tmux" in hint and ("apt" in hint or "brew" in hint)
+
+
+# --- _detect_arch -----------------------------------------------------------
+
+@pytest.mark.parametrize("machine,expected", [
+    ("AMD64", "x64"), ("x86_64", "x64"),
+    ("ARM64", "arm64"), ("aarch64", "arm64"),
+    ("x86", "x86"), ("i686", "x86"), ("i386", "x86"),
+])
+def test_detect_arch_maps_known_machines(monkeypatch, machine, expected):
+    monkeypatch.setattr(mx.platform, "machine", lambda: machine)
+    assert mx._detect_arch() == expected
+
+
+def test_detect_arch_raises_on_unknown(monkeypatch):
+    monkeypatch.setattr(mx.platform, "machine", lambda: "sparc")
+    with pytest.raises(ValueError):
+        mx._detect_arch()
+
+
+# --- install_psmux helpers --------------------------------------------------
+
+def _zip_bytes(members):
+    """Build an in-memory zip: members is a list of (name, data)."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as zf:
+        for name, data in members:
+            zf.writestr(name, data)
+    return buf.getvalue()
+
+
+def _pin_arch(monkeypatch, filename, data):
+    """Force _detect_arch -> 'x64' and pin _ASSETS so the real sha matches."""
+    monkeypatch.setattr(mx, "_detect_arch", lambda: "x64")
+    sha = hashlib.sha256(data).hexdigest()
+    monkeypatch.setattr(mx, "_ASSETS", {"x64": (filename, sha)})
+    return sha
+
+
+# --- install_psmux: success -------------------------------------------------
+
+def test_install_psmux_success_writes_binary(monkeypatch, tmp_path):
+    data = _zip_bytes([("tmux.exe", b"FAKE")])
+    _pin_arch(monkeypatch, "psmux.zip", data)
+
+    out = mx.install_psmux(str(tmp_path), opener=lambda url: data)
+
+    assert os.path.basename(out).lower() == "tmux.exe"
+    assert os.path.isfile(out)
+    assert (tmp_path / "tmux.exe").read_bytes() == b"FAKE"
+
+
+# --- install_psmux: checksum mismatch (the load-bearing security test) ------
+
+def test_install_psmux_checksum_mismatch_writes_nothing(monkeypatch, tmp_path):
+    good = _zip_bytes([("tmux.exe", b"FAKE")])
+    _pin_arch(monkeypatch, "psmux.zip", good)
+    # opener returns DIFFERENT bytes whose hash won't match the pinned sha
+    tampered = _zip_bytes([("tmux.exe", b"EVIL-PAYLOAD")])
+
+    with pytest.raises(RuntimeError):
+        mx.install_psmux(str(tmp_path), opener=lambda url: tampered)
+
+    # nothing extracted/written: a bad download never reaches the filesystem
+    assert list(tmp_path.iterdir()) == []
+    assert not (tmp_path / "tmux.exe").exists()
+
+
+# --- install_psmux: zip-slip ------------------------------------------------
+
+def test_install_psmux_zip_slip_stays_in_dest(monkeypatch, tmp_path):
+    dest = tmp_path / "bin"
+    dest.mkdir()
+    # malicious member tries to escape dest_dir; hash matches so we test extract
+    data = _zip_bytes([("../evil.exe", b"FAKE"), ("tmux.exe", b"GOOD")])
+    _pin_arch(monkeypatch, "psmux.zip", data)
+
+    out = mx.install_psmux(str(dest), opener=lambda url: data)
+
+    # the escaped path was never honored
+    assert not (tmp_path / "evil.exe").exists()
+    assert not (dest.parent / "evil.exe").exists()
+    # the legitimate binary still lands inside dest
+    assert os.path.isfile(out)
+    assert (dest / "tmux.exe").exists()
+
+
+def test_install_psmux_no_binary_in_zip_raises(monkeypatch, tmp_path):
+    data = _zip_bytes([("README.txt", b"hi")])
+    _pin_arch(monkeypatch, "psmux.zip", data)
+    with pytest.raises(RuntimeError):
+        mx.install_psmux(str(tmp_path), opener=lambda url: data)