ControlMode(core): Normalize output, probe safely, and hide control client

why: Align control-mode behaviour with subprocess engine and eliminate bootstrap side effects.
what:
- Trim trailing blank lines in control protocol results and treat kill-server EOF as success
- Add non-bootstrapping liveness probe for control engine; use it in is_alive/raise_if_dead
- Filter control client sessions from attached_sessions and add shared server-arg builder
- Update regressions: mark passing cases as normal tests

Author: tony

src/libtmux/_internal/engines/control_protocol.py

@@ -23,6 +23,14 @@
 logger = logging.getLogger(__name__)
 
 
+def _trim_lines(lines: list[str]) -> list[str]:
+    """Remove trailing empty strings to mirror subprocess behaviour."""
+    trimmed = list(lines)
+    while trimmed and trimmed[-1] == "":
+        trimmed.pop()
+    return trimmed
+
+
 @dataclasses.dataclass
 class CommandContext:
     """Tracks state for a single in-flight control-mode command."""
@@ -273,8 +281,15 @@ def mark_dead(self, reason: str) -> None:
         err = exc.ControlModeConnectionError(reason)
 
         if self._current:
-            self._current.error = err
-            self._current.signal_done()
+            # Special-case kill-server: tmux will close the control socket
+            # immediately after executing the command. Treat that as success.
+            if "kill-server" in self._current.argv:
+                self._current.exit_status = ExitStatus.OK
+                self._current.end_time = time.monotonic()
+                self._current.signal_done()
+            else:
+                self._current.error = err
+                self._current.signal_done()
             self._current = None
 
         while self._pending:
@@ -311,8 +326,8 @@ def build_result(self, ctx: CommandContext) -> CommandResult:
         exit_status = ctx.exit_status or ExitStatus.OK
         return CommandResult(
             argv=ctx.argv,
-            stdout=ctx.stdout,
-            stderr=ctx.stderr,
+            stdout=_trim_lines(ctx.stdout),
+            stderr=_trim_lines(ctx.stderr),
             exit_status=exit_status,
             cmd_id=ctx.cmd_id,
             start_time=ctx.start_time,

src/libtmux/server.py

@@ -201,6 +201,12 @@ def is_alive(self) -> bool:
         >>> tmux = Server(socket_name="no_exist")
         >>> assert not tmux.is_alive()
         """
+        # Avoid spinning up control-mode just to probe.
+        from libtmux._internal.engines.control_mode import ControlModeEngine
+
+        if isinstance(self.engine, ControlModeEngine):
+            return self._probe_server() == 0
+
         try:
             res = self.cmd("list-sessions")
         except Exception:
@@ -217,18 +223,23 @@ def raise_if_dead(self) -> None:
         ...     print(type(e))
         <class 'subprocess.CalledProcessError'>
         """
+        from libtmux._internal.engines.control_mode import ControlModeEngine
+
+        if isinstance(self.engine, ControlModeEngine):
+            rc = self._probe_server()
+            if rc != 0:
+                tmux_bin_probe = shutil.which("tmux") or "tmux"
+                raise subprocess.CalledProcessError(
+                    returncode=rc,
+                    cmd=[tmux_bin_probe, *self._build_server_args(), "list-sessions"],
+                )
+            return
+
         tmux_bin = shutil.which("tmux")
         if tmux_bin is None:
             raise exc.TmuxCommandNotFound
 
-        server_args: list[str] = []
-        if self.socket_name:
-            server_args.append(f"-L{self.socket_name}")
-        if self.socket_path:
-            server_args.append(f"-S{self.socket_path}")
-        if self.config_file:
-            server_args.append(f"-f{self.config_file}")
-
+        server_args = self._build_server_args()
         proc = self.engine.run("list-sessions", server_args=server_args)
         if proc.returncode is not None and proc.returncode != 0:
             raise subprocess.CalledProcessError(
@@ -239,6 +250,30 @@ def raise_if_dead(self) -> None:
     #
     # Command
     #
+    def _build_server_args(self) -> list[str]:
+        """Return tmux server args based on socket/config settings."""
+        server_args: list[str] = []
+        if self.socket_name:
+            server_args.append(f"-L{self.socket_name}")
+        if self.socket_path:
+            server_args.append(f"-S{self.socket_path}")
+        if self.config_file:
+            server_args.append(f"-f{self.config_file}")
+        return server_args
+
+    def _probe_server(self) -> int:
+        """Check server liveness without bootstrapping control mode."""
+        tmux_bin = shutil.which("tmux")
+        if tmux_bin is None:
+            raise exc.TmuxCommandNotFound
+
+        result = subprocess.run(
+            [tmux_bin, *self._build_server_args(), "list-sessions"],
+            check=False,
+            capture_output=True,
+        )
+        return result.returncode
+
     def cmd(
         self,
         cmd: str,
@@ -324,7 +359,18 @@ def attached_sessions(self) -> list[Session]:
         -------
         list of :class:`Session`
         """
-        return self.sessions.filter(session_attached__noeq="1")
+        sessions = list(self.sessions.filter(session_attached__noeq="1"))
+
+        # Hide internal control-mode client attachment.
+        from libtmux._internal.engines.control_mode import ControlModeEngine
+
+        if isinstance(self.engine, ControlModeEngine):
+            internal_names = self._get_internal_session_names()
+            if self.engine._attach_to:
+                internal_names.add(self.engine._attach_to)
+            sessions = [s for s in sessions if s.session_name not in internal_names]
+
+        return sessions
 
     def has_session(self, target_session: str, exact: bool = True) -> bool:
         """Return True if session exists (excluding internal engine sessions).

tests/test_control_mode_regressions.py

@@ -44,10 +44,6 @@ class TrailingOutputFixture(t.NamedTuple):
             expected_stdout=["line1"],
         ),
         id="one_blank",
-        marks=pytest.mark.xfail(
-            reason="control-mode preserves trailing blank stdout lines",
-            strict=True,
-        ),
     ),
     pytest.param(
         TrailingOutputFixture(
@@ -56,10 +52,6 @@ class TrailingOutputFixture(t.NamedTuple):
             expected_stdout=["line1"],
         ),
         id="many_blanks",
-        marks=pytest.mark.xfail(
-            reason="control-mode preserves trailing blank stdout lines",
-            strict=True,
-        ),
     ),
 ]
 
@@ -85,10 +77,6 @@ def test_control_protocol_trims_trailing_blank_lines(
     assert result.stdout == case.expected_stdout
 
 
-@pytest.mark.xfail(
-    reason="kill-server EOF currently surfaces as ControlModeConnectionError",
-    strict=True,
-)
 def test_kill_server_eof_marks_success() -> None:
     """EOF during kill-server should be treated as a successful completion."""
     proto = ControlProtocol()
@@ -104,10 +92,6 @@ def test_kill_server_eof_marks_success() -> None:
     assert result.exit_status is ExitStatus.OK
 
 
-@pytest.mark.xfail(
-    reason="control-mode bootstrap currently makes is_alive start a server",
-    strict=True,
-)
 def test_is_alive_does_not_bootstrap_control_mode() -> None:
     """is_alive should not spin up control-mode process for an unknown socket."""
     socket_name = f"libtmux_test_{uuid.uuid4().hex[:8]}"
@@ -385,10 +369,6 @@ def test_capture_pane_variants(case: CapturePaneFixture) -> None:
             server.kill()
 
 
-@pytest.mark.xfail(
-    reason="control-mode is_alive bootstrap hides missing-server errors",
-    strict=True,
-)
 def test_raise_if_dead_raises_on_missing_server() -> None:
     """raise_if_dead should raise when tmux server does not exist."""
     socket_name = f"libtmux_test_{uuid.uuid4().hex[:8]}"
@@ -399,10 +379,6 @@ def test_raise_if_dead_raises_on_missing_server() -> None:
         server.raise_if_dead()
 
 
-@pytest.mark.xfail(
-    reason="TestServer with control engine starts server eagerly",
-    strict=True,
-)
 def test_testserver_is_alive_false_before_use() -> None:
     """TestServer should report not alive before first use."""
     engine = ControlModeEngine()