ControlMode(test[logging]): Add raw control client logging fixtures and diagnostics

why: Provide a real control-mode logging harness for debugging control stream issues.
what:
- Add control_client_logs fixture that spawns tmux -C with per-test stdout/stderr logs
- Add diagnostic tests parsing control stream with ControlProtocol
- Add control_sandbox contextmanager fixture and smoke test for isolated control server

Author: tony

conftest.py

@@ -13,6 +13,7 @@
 import contextlib
 import pathlib
 import shutil
+import subprocess
 import typing as t
 import uuid
 
@@ -118,6 +119,47 @@ def control_sandbox(
             server.kill()
 
 
+@pytest.fixture
+def control_client_logs(
+    control_sandbox: t.ContextManager[Server],
+    tmp_path_factory: pytest.TempPathFactory,
+) -> t.Iterator[tuple[subprocess.Popen[str], pathlib.Path, pathlib.Path]]:
+    """Spawn a raw tmux -C client against the sandbox and log stdout/stderr."""
+    base = tmp_path_factory.mktemp("ctrl_logs")
+    stdout_path = base / "control_stdout.log"
+    stderr_path = base / "control_stderr.log"
+
+    with control_sandbox as server:
+        cmd = [
+            "tmux",
+            "-L",
+            server.socket_name or "",
+            "-C",
+            "attach-session",
+            "-t",
+            "ctrltest",
+        ]
+        # Ensure ctrltest exists
+        server.cmd("new-session", "-d", "-s", "ctrltest")
+        proc = subprocess.Popen(
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=stdout_path.open("w+", buffering=1),
+            stderr=stderr_path.open("w+", buffering=1),
+            text=True,
+            bufsize=1,
+        )
+        try:
+            yield proc, stdout_path, stderr_path
+        finally:
+            with contextlib.suppress(Exception):
+                if proc.stdin:
+                    proc.stdin.write("kill-session -t ctrltest\n")
+                    proc.stdin.flush()
+            proc.terminate()
+            proc.wait(timeout=2)
+
+
 def pytest_addoption(parser: pytest.Parser) -> None:
     """Add CLI options for selecting tmux engine."""
     parser.addoption(

tests/test_control_client_logs.py

@@ -0,0 +1,52 @@
+"""Diagnostic tests using raw control client logs."""
+
+from __future__ import annotations
+
+import typing as t
+
+import pytest
+
+from libtmux._internal.engines.control_protocol import CommandContext, ControlProtocol
+
+
+@pytest.mark.engines(["control"])
+def test_control_client_lists_clients(
+    control_client_logs: tuple[t.Any, t.Any, t.Any],
+) -> None:
+    """Raw control client should report itself with control-mode flag."""
+    proc, stdout_path, _stderr_path = control_client_logs
+
+    assert proc.stdin is not None
+    proc.stdin.write('list-clients -F"#{client_pid} #{client_flags} #{session_name}"\n')
+    proc.stdin.flush()
+
+    # Read what the control client wrote
+    lines = stdout_path.read_text().splitlines()
+    assert any(len(line.split()) >= 2 and "C" in line.split()[1] for line in lines)
+
+
+@pytest.mark.engines(["control"])
+def test_control_client_capture_stream_parses(
+    control_client_logs: tuple[t.Any, t.Any, t.Any],
+) -> None:
+    """Ensure ControlProtocol can parse raw stream from the logged control client."""
+    proc, stdout_path, _stderr_path = control_client_logs
+    assert proc.stdin is not None
+
+    proc.stdin.write("display-message -p hello\n")
+    proc.stdin.flush()
+
+    lines = stdout_path.read_text().splitlines()
+
+    proto = ControlProtocol()
+    ctx = CommandContext(argv=["tmux", "display-message", "-p", "hello"])
+    proto.register_command(ctx)
+
+    # Feed lines; expect begin/payload/end
+    for line in lines:
+        proto.feed_line(line)
+
+    # If tmux emitted begin/end, ctx should be done
+    if ctx.done.is_set():
+        result = proto.build_result(ctx)
+        assert "hello" in result.stdout