docs(control-mode): Document errors, queue drops, env reqs, sandbox

Author: tony

docs/topics/control_mode.md

@@ -148,3 +148,44 @@ print(server.list_sessions())  # legacy behavior
   metadata (``exit_status``, ``cmd_id``, ``tmux_time``) is attached.
 - Notifications are queued; drops are counted when consumers fall behind.
 - Timeouts raise ``ControlModeTimeout`` and restart the control client.
+
+## Errors, timeouts, and retries
+
+- ``ControlModeTimeout`` — command block did not finish before
+  ``command_timeout``. The engine closes and restarts the control client.
+- ``ControlModeConnectionError`` — control socket died (EOF/broken pipe). The
+  engine restarts and replays the pending command once.
+- ``ControlModeProtocolError`` — malformed ``%begin/%end/%error`` framing; the
+  client is marked dead and must be restarted.
+- ``SubprocessTimeout`` — subprocess fallback exceeded its timeout.
+
+## Notifications and backpressure
+
+- Notifications are enqueued in a bounded queue (default 4096). When the queue
+  fills, additional notifications are dropped and the drop counter is reported
+  via :class:`~libtmux._internal.engines.base.EngineStats`.
+- Consume notifications via :meth:`ControlModeEngine.iter_notifications` to
+  avoid drops; use a small timeout (e.g., 0.1s) for non-blocking loops.
+
+## Environment propagation requirements
+
+- tmux **3.2 or newer** is required for ``-e KEY=VAL`` on ``new-session``,
+  ``new-window``, and ``split-window``. Older tmux versions ignore ``-e``; the
+  library emits a warning and tests skip these cases.
+- Environment tests and examples may wait briefly after ``send-keys`` so the
+  shell prompt/output reaches the pane before capture.
+
+## Capture-pane normalization
+
+- Control mode trims trailing *whitespace-only* lines from ``capture-pane`` to
+  match subprocess behaviour. If you request explicit ranges (``-S/-E``) or use
+  ``-N/-J``, output is left untouched.
+- In control mode, the first capture after ``send-keys`` can race the shell;
+  libtmux retries briefly to ensure the prompt/output is visible.
+
+## Control sandbox (tests/diagnostics)
+
+The pytest fixture ``control_sandbox`` provides an isolated control-mode tmux
+server with a unique socket, HOME/TMUX_TMPDIR isolation, and automatic cleanup.
+It is used by the regression suite and can be reused in custom tests when you
+need a hermetic control-mode client.