feat(engine): Add tmux control mode command runner

Implement ControlModeCommandRunner as alternative to subprocess execution,
enabling persistent connection to tmux server for improved performance.

Key features:
- Protocol-based design with CommandResult interface
- Thread-safe command execution with Lock
- Auto-consumption of initial session creation blocks
- Argument filtering for control mode compatibility (-L, -S, -f, -F, -2, -8)
- Context manager support for automatic cleanup

Implementation:
- ControlModeResult: Duck-types as tmux_cmd for backward compatibility
- ProtocolParser: Parses %begin/%end/%error response blocks
- ControlModeCommandRunner: Manages persistent tmux -C connection

Updated all cmd() methods (Server, Session, Window, Pane) to return
CommandResult protocol instead of concrete tmux_cmd type.

Known limitation: Control mode doesn't support custom format strings (-F),
so these flags are filtered out during command execution.

Author: tony

src/libtmux/_internal/command_runner.py

@@ -6,7 +6,7 @@
 from typing import Protocol
 
 if t.TYPE_CHECKING:
-    from libtmux.common import tmux_cmd
+    pass
 
 
 class CommandResult(Protocol):
@@ -64,7 +64,7 @@ class CommandRunner(Protocol):
     >>> assert hasattr(result, 'returncode')
     """
 
-    def run(self, *args: str) -> tmux_cmd:
+    def run(self, *args: str) -> CommandResult:
         """Execute a tmux command.
 
         Parameters

src/libtmux/_internal/engines/__init__.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
-__all__ = ("SubprocessCommandRunner",)
+__all__ = ("ControlModeCommandRunner", "SubprocessCommandRunner")
 
+from libtmux._internal.engines.control_mode import ControlModeCommandRunner
 from libtmux._internal.engines.subprocess_engine import SubprocessCommandRunner

src/libtmux/_internal/engines/control_mode/__init__.py

@@ -0,0 +1,8 @@
+"""Control mode command execution engine."""
+
+from __future__ import annotations
+
+__all__ = ("ControlModeCommandRunner", "ControlModeResult")
+
+from libtmux._internal.engines.control_mode.result import ControlModeResult
+from libtmux._internal.engines.control_mode.runner import ControlModeCommandRunner

src/libtmux/_internal/engines/control_mode/parser.py

@@ -0,0 +1,108 @@
+"""Control mode protocol parser."""
+
+from __future__ import annotations
+
+from typing import IO
+
+from .result import ControlModeResult
+
+
+class ProtocolParser:
+    r"""Parser for tmux control mode protocol.
+
+    Handles %begin/%end/%error blocks and notifications.
+
+    The tmux control mode protocol format:
+    - Commands produce output blocks
+    - Blocks start with %begin and end with %end or %error
+    - Format: %begin timestamp cmd_num flags
+    - Notifications (%session-changed, etc.) can appear between blocks
+
+    Examples
+    --------
+    >>> import io
+    >>> stdout = io.StringIO(
+    ...     "%begin 1234 1 0\n"
+    ...     "session1\n"
+    ...     "%end 1234 1 0\n"
+    ... )
+    >>> parser = ProtocolParser(stdout)
+    >>> result = parser.parse_response(["list-sessions"])
+    >>> result.stdout
+    ['session1']
+    >>> result.returncode
+    0
+    """
+
+    def __init__(self, stdout: IO[str]) -> None:
+        self.stdout = stdout
+        self.notifications: list[str] = []
+
+    def parse_response(self, cmd: list[str]) -> ControlModeResult:
+        """Parse a single command response.
+
+        Parameters
+        ----------
+        cmd : list[str]
+            The command that was executed (for result.cmd)
+
+        Returns
+        -------
+        ControlModeResult
+            Parsed result with stdout, stderr, returncode
+
+        Raises
+        ------
+        ConnectionError
+            If connection closes unexpectedly
+        ProtocolError
+            If protocol format is unexpected
+        """
+        stdout_lines: list[str] = []
+        stderr_lines: list[str] = []
+        returncode = 0
+
+        # State machine
+        in_response = False
+
+        while True:
+            line = self.stdout.readline()
+            if not line:  # EOF
+                msg = "Control mode connection closed unexpectedly"
+                raise ConnectionError(msg)
+
+            line = line.rstrip("\n")
+
+            # Parse line type
+            if line.startswith("%begin"):
+                # %begin timestamp cmd_num flags
+                in_response = True
+                continue
+
+            elif line.startswith("%end"):
+                # Success - response complete
+                return ControlModeResult(stdout_lines, stderr_lines, returncode, cmd)
+
+            elif line.startswith("%error"):
+                # Error - command failed
+                returncode = 1
+                # Note: error details are in stdout_lines already
+                return ControlModeResult(stdout_lines, stderr_lines, returncode, cmd)
+
+            elif line.startswith("%"):
+                # Notification - queue for future processing
+                self.notifications.append(line)
+                # Don't break - keep reading for our response
+                continue
+
+            else:
+                # Regular output line
+                if in_response:
+                    stdout_lines.append(line)
+                # else: orphaned line before %begin (should not happen in practice)
+
+
+class ProtocolError(Exception):
+    """Raised when control mode protocol is violated."""
+
+    pass

src/libtmux/_internal/engines/control_mode/result.py

@@ -0,0 +1,57 @@
+"""Result type for control mode command execution."""
+
+from __future__ import annotations
+
+
+class ControlModeResult:
+    """Result from control mode execution.
+
+    Duck-types as tmux_cmd for backward compatibility.
+    Has identical interface: stdout, stderr, returncode, cmd.
+
+    Attributes
+    ----------
+    stdout : list[str]
+        Command standard output, split by lines
+    stderr : list[str]
+        Command standard error, split by lines
+    returncode : int
+        Command return code (0 = success, 1 = error)
+    cmd : list[str]
+        The command that was executed (for debugging)
+
+    Examples
+    --------
+    >>> result = ControlModeResult(
+    ...     stdout=["session1", "session2"],
+    ...     stderr=[],
+    ...     returncode=0,
+    ...     cmd=["tmux", "-C", "list-sessions"]
+    ... )
+    >>> result.stdout
+    ['session1', 'session2']
+    >>> result.returncode
+    0
+    >>> bool(result.stderr)
+    False
+    """
+
+    __slots__ = ("cmd", "returncode", "stderr", "stdout")
+
+    def __init__(
+        self,
+        stdout: list[str],
+        stderr: list[str],
+        returncode: int,
+        cmd: list[str],
+    ) -> None:
+        self.stdout = stdout
+        self.stderr = stderr
+        self.returncode = returncode
+        self.cmd = cmd
+
+    def __repr__(self) -> str:
+        return (
+            f"ControlModeResult(returncode={self.returncode}, "
+            f"stdout_lines={len(self.stdout)}, stderr_lines={len(self.stderr)})"
+        )