ControlMode(test[fixtures]): Add control_sandbox contextmanager fixture and smoke test

why: Provide an isolated, typed control-mode server for debugging and future tests.
what:
- Add contextmanager fixture control_sandbox with per-test socket/HOME/TMUX_TMPDIR
- Smoke test that exercises control-mode server creation and a simple command

Author: tony

conftest.py

@@ -10,8 +10,11 @@
 
 from __future__ import annotations
 
+import contextlib
+import pathlib
 import shutil
 import typing as t
+import uuid
 
 import pytest
 from _pytest.doctest import DoctestItem
@@ -75,6 +78,46 @@ def setup_session(
         request.getfixturevalue("zshrc")
 
 
+# ---------------------------------------------------------------------------
+# Control-mode sandbox helper
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+@contextlib.contextmanager
+def control_sandbox(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path_factory: pytest.TempPathFactory,
+) -> t.Iterator[Server]:
+    """Provide an isolated control-mode server for a test.
+
+    - Creates a unique tmux socket name per invocation
+    - Isolates HOME and TMUX_TMPDIR under a per-test temp directory
+    - Clears TMUX env var to avoid inheriting user sessions
+    - Uses ControlModeEngine; on exit, kills the server best-effort
+    """
+    socket_name = f"libtmux_test_{uuid.uuid4().hex[:8]}"
+    base = tmp_path_factory.mktemp("ctrl_sandbox")
+    home = base / "home"
+    tmux_tmpdir = base / "tmux"
+    home.mkdir()
+    tmux_tmpdir.mkdir()
+
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("TMUX_TMPDIR", str(tmux_tmpdir))
+    monkeypatch.delenv("TMUX", raising=False)
+
+    from libtmux._internal.engines.control_mode import ControlModeEngine
+
+    server = Server(socket_name=socket_name, engine=ControlModeEngine())
+
+    try:
+        yield server
+    finally:
+        with contextlib.suppress(Exception):
+            server.kill()
+
+
 def pytest_addoption(parser: pytest.Parser) -> None:
     """Add CLI options for selecting tmux engine."""
     parser.addoption(

tests/test_control_sandbox.py

@@ -0,0 +1,26 @@
+"""Sanity checks for the control_sandbox context-manager fixture."""
+
+from __future__ import annotations
+
+import typing as t
+
+import pytest
+
+from libtmux.server import Server
+
+
+@pytest.mark.engines(["control"])
+def test_control_sandbox_smoke(control_sandbox: t.ContextManager[Server]) -> None:
+    """Control sandbox should spin up an isolated server and run commands."""
+    with control_sandbox as server:
+        session = server.new_session(
+            session_name="sandbox_session",
+            attach=False,
+            kill_session=True,
+        )
+        assert session.name == "sandbox_session"
+        assert server.has_session("sandbox_session")
+
+        # Run a simple command to ensure control mode path works.
+        out = server.cmd("display-message", "-p", "hi")
+        assert out.stdout == ["hi"]