docs(control-mode-code): Clarify exceptions, queue semantics, env test notes

Author: tony

src/libtmux/_internal/engines/control_mode.py

@@ -33,6 +33,11 @@ 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.
     """
 
     def __init__(

src/libtmux/_internal/engines/control_protocol.py

@@ -159,7 +159,13 @@ def _parse_notification(line: str, parts: list[str]) -> Notification:
 
 
 class ControlProtocol:
-    """Parse the tmux control-mode stream into commands and notifications."""
+    """Parse the tmux control-mode stream into commands and notifications.
+
+    Maintains a FIFO queue of pending :class:`CommandContext` objects that are
+    matched to `%begin/%end/%error` blocks, plus a bounded notification queue
+    (default 4096) for out-of-band events. When the queue is full, additional
+    notifications are dropped and counted so callers can detect backpressure.
+    """
 
     def __init__(self, *, notification_queue_size: int = 4096) -> None:
         self.state = ParserState.IDLE

src/libtmux/exc.py

@@ -93,19 +93,28 @@ class WaitTimeout(LibTmuxException):
 
 
 class ControlModeTimeout(LibTmuxException):
-    """tmux control mode command did not return within the timeout."""
+    """tmux control-mode command did not return before the configured timeout.
+
+    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.
+    """
 
 
 class ControlModeProtocolError(LibTmuxException):
-    """Protocol-level error while parsing control mode stream."""
+    """Protocol-level error while parsing the control-mode stream.
+
+    Indicates malformed `%begin/%end/%error` framing or an unexpected parser
+    state. The control client is marked dead and must be restarted.
+    """
 
 
 class ControlModeConnectionError(LibTmuxException):
-    """Control mode connection was lost unexpectedly."""
+    """Control-mode connection was lost unexpectedly (EOF/broken pipe)."""
 
 
 class SubprocessTimeout(LibTmuxException):
-    """tmux subprocess exceeded the allowed timeout."""
+    """tmux subprocess exceeded the allowed timeout for the invoked command."""
 
 
 class VariableUnpackingError(LibTmuxException):

tests/test_control_mode_regressions.py

@@ -218,7 +218,11 @@ class EnvPropagationFixture(t.NamedTuple):
 
 @pytest.mark.parametrize("case", ENV_PROP_CASES)
 def test_environment_propagation(case: EnvPropagationFixture) -> None:
-    """Environment variables should be visible inside panes."""
+    """Environment vars should surface inside panes (tmux >= 3.2 for -e support).
+
+    Uses ``wait_for_line`` to allow control-mode capture to observe the shell
+    output after send-keys; older tmux releases ignore ``-e`` and are skipped.
+    """
     if has_lt_version("3.2"):
         pytest.skip("tmux < 3.2 ignores -e in this environment")
 
@@ -510,7 +514,7 @@ class EnvMultiFixture(t.NamedTuple):
 
 @pytest.mark.parametrize("case", ENV_MULTI_CASES)
 def test_environment_multi_var_propagation(case: EnvMultiFixture) -> None:
-    """Multiple -e flags should all be delivered inside the pane."""
+    """Multiple ``-e`` flags should all be delivered inside the pane (tmux >= 3.2)."""
     if has_lt_version("3.2"):
         pytest.skip("tmux < 3.2 ignores -e in this environment")