ControlModeEngine(core): UUID session names, control-mode flag, drain helper

- Use UUID-based internal session names (libtmux_ctrl_{uuid}) to avoid
  collisions when multiple control engines run simultaneously
- Fix control flag detection: use "control-mode" string (confirmed from
  tmux C source server-client.c:3776) instead of "C" letter
- Add drain_notifications() helper for explicit sync points when using
  attach_to mode or waiting for notification activity to settle
- Use wait_for_line() synchronization for capture-pane tests to avoid
  timing races with shell output
- Enhance exception docstrings: ControlModeTimeout is terminal (not
  retried), ControlModeConnectionError is retriable
- Propagate ControlModeConnectionError/Timeout in _sessions_all()
- Remove 7 xfails that now pass after synchronization fixes

Note: 3 ScriptedProcess/ProcessFactory tests remain failing due to
threading model issues (daemon threads + tuple stdout = race condition).
These will be addressed in subsequent commits.

Author: tony

src/libtmux/_internal/engines/control_mode.py

@@ -8,6 +8,7 @@
 import subprocess
 import threading
 import typing as t
+import uuid
 
 from libtmux import exc
 from libtmux._internal.engines.base import (
@@ -67,10 +68,20 @@ class ControlModeEngine(Engine):
     By default, creates an internal session for connection management.
     This session is hidden from user-facing APIs like Server.sessions.
 
-    Commands raise :class:`~libtmux.exc.ControlModeTimeout` or
-    :class:`~libtmux.exc.ControlModeConnectionError` on stalls/disconnects; a
-    bounded notification queue (default 4096) records out-of-band events with
-    drop counting when consumers fall behind.
+    Error Handling
+    --------------
+    Connection errors (BrokenPipeError, EOF) raise
+    :class:`~libtmux.exc.ControlModeConnectionError` and are automatically
+    retried up to ``max_retries`` times (default: 1).
+
+    Timeouts raise :class:`~libtmux.exc.ControlModeTimeout` and are NOT retried.
+    If operations frequently timeout, increase ``command_timeout``.
+
+    Notifications
+    -------------
+    A bounded notification queue (default 4096) records out-of-band events with
+    drop counting when consumers fall behind. Use :meth:`iter_notifications` to
+    consume events or :meth:`drain_notifications` to wait for idle state.
     """
 
     def __init__(
@@ -93,10 +104,11 @@ def __init__(
             Size of notification queue. Default: 4096
         internal_session_name : str, optional
             Custom name for internal control session.
-            Default: "libtmux_control_mode"
+            Default: Auto-generated unique name (libtmux_ctrl_XXXXXXXX)
 
             The internal session is used for connection management and is
-            automatically filtered from user-facing APIs.
+            automatically filtered from user-facing APIs. A unique name is
+            generated automatically to avoid collisions with user sessions.
         attach_to : str, optional
             Attach to existing session instead of creating internal one.
             When set, control mode attaches to this session for its connection.
@@ -127,7 +139,9 @@ def __init__(
             notification_queue_size=notification_queue_size,
         )
         self._restarts = 0
-        self._internal_session_name = internal_session_name or "libtmux_control_mode"
+        self._internal_session_name = (
+            internal_session_name or f"libtmux_ctrl_{uuid.uuid4().hex[:8]}"
+        )
         self._attach_to = attach_to
         self._process_factory = process_factory
         self._max_retries = max(0, max_retries)
@@ -229,6 +243,54 @@ def iter_notifications(
                 return
             yield notif
 
+    def drain_notifications(
+        self,
+        *,
+        idle_duration: float = 0.1,
+        timeout: float = 8.0,
+    ) -> list[Notification]:
+        """Drain notifications until the queue is idle.
+
+        This helper is useful when you need to wait for notification activity
+        to settle after an operation that may generate multiple notifications
+        (e.g., attach-session in attach_to mode).
+
+        Parameters
+        ----------
+        idle_duration : float, optional
+            Consider the queue idle after this many seconds of silence.
+            Default: 0.1 (100ms)
+        timeout : float, optional
+            Maximum time to wait for idle state. Default: 8.0
+            Matches RETRY_TIMEOUT_SECONDS from libtmux.test.retry.
+
+        Returns
+        -------
+        list[Notification]
+            All notifications received before idle state.
+
+        Raises
+        ------
+        TimeoutError
+            If timeout is reached before idle state.
+        """
+        import time
+
+        collected: list[Notification] = []
+        deadline = time.monotonic() + timeout
+
+        while time.monotonic() < deadline:
+            notif = self._protocol.get_notification(timeout=idle_duration)
+            if notif is None:
+                # Queue was idle for idle_duration - we're done
+                return collected
+            if notif.kind.name == "EXIT":
+                return collected
+            collected.append(notif)
+
+        msg = f"Notification queue did not become idle within {timeout}s"
+        raise TimeoutError(msg)
+
     def get_stats(self) -> EngineStats:
         """Return diagnostic statistics for the engine."""
         return self._protocol.get_stats(restarts=self._restarts)
@@ -281,7 +343,7 @@ def exclude_internal_sessions(
             non_control_clients = [
                 (pid, flags)
                 for pid, flags in clients
-                if "C" not in flags and pid != ctrl_pid
+                if "control-mode" not in flags and pid != ctrl_pid
             ]
 
             if non_control_clients:
@@ -310,7 +372,7 @@ def can_switch_client(
             parts = line.split()
             if len(parts) >= 2:
                 pid, flags = parts[0], parts[1]
-                if "C" not in flags and pid != ctrl_pid:
+                if "control-mode" not in flags and pid != ctrl_pid:
                     return True
 
         return False

src/libtmux/exc.py

@@ -95,9 +95,27 @@ class WaitTimeout(LibTmuxException):
 class ControlModeTimeout(LibTmuxException):
     """tmux control-mode command did not return before the configured timeout.
 
+    This is a **terminal failure** - the operation took too long and is NOT
+    automatically retried. If you expect slow operations, increase the timeout
+    parameter when creating the engine or calling commands.
+
+    This is distinct from :class:`ControlModeConnectionError`, which indicates
+    a transient connection failure (like BrokenPipeError) and IS automatically
+    retried up to ``max_retries`` times.
+
     Raised by :class:`~libtmux._internal.engines.control_mode.ControlModeEngine`
-    when a command block fails to finish. The engine will close and restart the
-    control client after emitting this error.
+    when a command block fails to finish within the timeout. The engine will
+    close and restart the control client after emitting this error, but will NOT
+    retry the timed-out command.
+
+    If commands timeout frequently, increase the timeout::
+
+        engine = ControlModeEngine(command_timeout=30.0)
+        server = Server(engine=engine)
+
+    Or override per-command::
+
+        server.cmd("slow-command", timeout=60.0)
     """
 
 
@@ -110,7 +128,18 @@ class ControlModeProtocolError(LibTmuxException):
 
 
 class ControlModeConnectionError(LibTmuxException):
-    """Control-mode connection was lost unexpectedly (EOF/broken pipe)."""
+    """Control-mode connection was lost unexpectedly (EOF/broken pipe).
+
+    This is a **retriable error** - the engine will automatically retry the
+    command up to ``max_retries`` times (default: 1) after restarting the
+    control client connection.
+
+    This is distinct from :class:`ControlModeTimeout`, which indicates the
+    operation took too long and is NOT automatically retried.
+
+    Raised when writing to the control-mode process fails with BrokenPipeError
+    or when unexpected EOF is encountered.
+    """
 
 
 class SubprocessTimeout(LibTmuxException):

src/libtmux/server.py

@@ -799,7 +799,11 @@ def _sessions_all(self) -> QueryList[Session]:
                 server=self,
             ):
                 sessions.append(Session(server=self, **obj))  # noqa: PERF401
+        except (exc.ControlModeConnectionError, exc.ControlModeTimeout):
+            # Propagate control mode connection/timeout errors
+            raise
         except Exception:
+            # Catch other exceptions (e.g., no sessions exist)
             pass
 
         return QueryList(sessions)

tests/test_control_mode_engine.py

@@ -48,8 +48,12 @@ def test_control_mode_engine_basic(tmp_path: pathlib.Path) -> None:
     # Verify bootstrap session exists but is filtered (use internal method)
     all_sessions = server._sessions_all()
     all_session_names = [s.name for s in all_sessions]
-    assert "libtmux_control_mode" in all_session_names
-    assert len(all_sessions) == 2  # test_sess + libtmux_control_mode
+    # Internal session now uses UUID-based name: libtmux_ctrl_XXXXXXXX
+    assert any(
+        name is not None and name.startswith("libtmux_ctrl_")
+        for name in all_session_names
+    )
+    assert len(all_sessions) == 2  # test_sess + libtmux_ctrl_*
 
     # run a command that returns output
     output_cmd = server.cmd("display-message", "-p", "hello")