docs(control-mode): Document engine usage, errors, env reqs, sandbox

Author: tony

docs/api/index.md

@@ -4,6 +4,12 @@
 
 # API Reference
 
+:::{note}
+Looking for the new control-mode engine? See {ref}`control-mode` for an
+experimental, protocol-focused entry point that still preserves the public
+``tmux_cmd`` return type.
+:::
+
 ```{toctree}
 
 properties

docs/pytest-plugin/index.md

@@ -137,6 +137,53 @@ def set_home(
     monkeypatch.setenv("HOME", str(user_path))
 ```
 
+## Selecting tmux engines (experimental)
+
+Fixtures can run against different execution engines. By default the
+`subprocess` engine is used. You can choose control mode globally:
+
+```console
+$ pytest --engine=control
+```
+
+Or per-test via the `engines` marker (uses parametrization) and the `engine_name`
+fixture:
+
+```python
+import pytest
+
+@pytest.mark.engines(["subprocess", "control"])
+def test_my_flow(server, engine_name):
+    # server uses the selected engine, engine_name reflects the current one
+    assert engine_name in {"subprocess", "control"}
+    assert server.is_alive()
+```
+
+`TestServer` also respects the selected engine. Control mode is experimental and
+its APIs may change between releases.
+
+### Control sandbox fixture (experimental)
+
+Use ``control_sandbox`` when you need a hermetic control-mode server for a test:
+
+```python
+import typing as t
+import pytest
+from libtmux.server import Server
+
+@pytest.mark.engines(["control"])
+def test_control_sandbox(control_sandbox: t.ContextManager[Server]):
+    with control_sandbox as server:
+        session = server.new_session(session_name="sandbox", attach=False)
+        out = server.cmd("display-message", "-p", "hi")
+        assert out.stdout == ["hi"]
+```
+
+The fixture:
+- Spins up a unique socket name and isolates ``HOME`` / ``TMUX_TMPDIR``
+- Clears inherited ``TMUX`` so it never attaches to the user's server
+- Uses ``ControlModeEngine`` and cleans up the server on exit
+
 ## Fixtures
 
 ```{eval-rst}

docs/quickstart.md

@@ -157,6 +157,23 @@ in your server object. `libtmux.Server(socket_name='mysocket')` is
 equivalent to `$ tmux -L mysocket`.
 :::
 
+### Optional: Control mode (experimental)
+
+Control mode keeps a persistent tmux client open and streams
+notifications. Enable it by injecting a control-mode engine:
+
+```python
+from libtmux._internal.engines.control_mode import ControlModeEngine
+from libtmux.server import Server
+
+engine = ControlModeEngine()
+server = Server(engine=engine)
+session = server.new_session(session_name="ctrl")
+print(session.name)
+```
+
+See {ref}`control-mode` for details, caveats, and notification handling.
+
 `server` is now a living object bound to the tmux server's Sessions,
 Windows and Panes.
 
@@ -263,6 +280,41 @@ Session($1 foo)
 
 to give us a `session` object to play with.
 
+## Connect to or create a session
+
+A simpler approach is to use {meth}`Server.connect()`, which returns an existing
+session or creates it if it doesn't exist:
+
+```python
+>>> session = server.connect('my_project')
+>>> session.name
+'my_project'
+
+>>> # Calling again returns the same session
+>>> session2 = server.connect('my_project')
+>>> session2.session_id == session.session_id
+True
+```
+
+This is particularly useful for:
+
+- Development workflows where you want to reuse existing sessions
+- Scripts that should create a session on first run, then reattach
+- Working with both subprocess and control-mode engines transparently
+
+Compare with the traditional approach:
+
+```python
+>>> # Traditional: check then create
+>>> if server.has_session('my_project'):
+...     session = server.sessions.get(session_name='my_project')
+... else:
+...     session = server.new_session('my_project')
+
+>>> # Simpler with connect()
+>>> session = server.connect('my_project')
+```
+
 ## Playing with our tmux session
 
 We now have access to `session` from above with all of the methods

docs/topics/control_mode.md

@@ -0,0 +1,191 @@
+---
+orphan: true
+---
+
+(control-mode)=
+
+# Control Mode Engine (experimental)
+
+:::{warning}
+This is an **experimental API**. Names and behavior may change between releases.
+Use with caution and pin your libtmux version if you depend on it.
+:::
+
+libtmux can drive tmux through a persistent Control Mode client. This keeps a
+single connection open, pipelines commands, and surfaces tmux notifications in a
+typed stream.
+
+## Why use Control Mode?
+
+- Lower overhead than spawning a tmux process per command
+- Access to live notifications: layout changes, window/link events, client
+  detach/attach, paste buffer updates, and more
+- Structured command results with timing/flag metadata
+
+## Using ControlModeEngine
+
+```python
+from __future__ import annotations
+
+from libtmux._internal.engines.control_mode import ControlModeEngine
+from libtmux.server import Server
+
+engine = ControlModeEngine(command_timeout=5)
+server = Server(engine=engine)
+
+session = server.new_session(session_name="ctrl-demo")
+print(session.name)
+
+# Consume notifications (non-blocking example)
+for notif in engine.iter_notifications(timeout=0.1):
+    print(notif.kind, notif.data)
+```
+
+:::{note}
+Control mode creates an internal session for connection management (default name:
+`libtmux_control_mode`). This session is automatically filtered from
+`Server.sessions` and `Server.has_session()` to maintain engine transparency.
+:::
+
+## Session management with Control Mode
+
+The {meth}`Server.connect()` method works seamlessly with control mode:
+
+```python
+from libtmux._internal.engines.control_mode import ControlModeEngine
+from libtmux.server import Server
+
+engine = ControlModeEngine()
+server = Server(engine=engine)
+
+# Reuses session if it exists, creates if it doesn't
+session = server.connect("dev-session")
+print(session.name)
+
+# Calling again returns the same session
+session2 = server.connect("dev-session")
+assert session2.session_id == session.session_id
+```
+
+This works transparently with both control mode and subprocess engines, making it
+easy to switch between them without changing your code.
+
+## Advanced Configuration
+
+### Custom Internal Session Name
+
+For testing or advanced scenarios, you can customize the internal session name:
+
+```python
+from libtmux._internal.engines.control_mode import ControlModeEngine
+from libtmux.server import Server
+
+engine = ControlModeEngine(internal_session_name="my_control_session")
+server = Server(engine=engine)
+
+# Internal session is still filtered
+user_session = server.new_session("my_app")
+len(server.sessions)  # 1 (only my_app visible)
+
+# But exists internally
+len(server._sessions_all())  # 2 (my_app + my_control_session)
+```
+
+### Attach to Existing Session
+
+For expert use cases, control mode can attach to an existing session instead of
+creating an internal one:
+
+```python
+# Create a session first
+server.new_session("shared")
+
+# Control mode attaches to it for its connection
+engine = ControlModeEngine(attach_to="shared")
+server = Server(engine=engine)
+
+# The shared session is visible (not filtered)
+len(server.sessions)  # 1 (shared session)
+```
+
+:::{warning}
+Attaching to active user sessions will generate notification traffic from pane
+output and layout changes. This increases protocol parsing overhead and may impact
+performance. Use only when you need control mode notifications for a specific session.
+:::
+
+## Parsing notifications directly
+
+The protocol parser can be used without tmux to understand the wire format.
+
+```python
+>>> from libtmux._internal.engines.control_protocol import ControlProtocol
+>>> proto = ControlProtocol()
+>>> proto.feed_line("%layout-change @1 abcd efgh 0")
+>>> notif = proto.get_notification()
+>>> notif.kind.name
+'WINDOW_LAYOUT_CHANGED'
+>>> notif.data['window_layout']
+'abcd'
+```
+
+## Fallback engine
+
+If control mode is unavailable, ``SubprocessEngine`` matches the same
+``Engine`` interface but runs one tmux process per command:
+
+```python
+from libtmux._internal.engines.subprocess_engine import SubprocessEngine
+from libtmux.server import Server
+
+server = Server(engine=SubprocessEngine())
+print(server.list_sessions())  # legacy behavior
+```
+
+## Key behaviors
+
+- Commands still return ``tmux_cmd`` objects for compatibility, but extra
+  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.

docs/topics/index.md

@@ -15,4 +15,5 @@ workspace_setup
 automation_patterns
 context_managers
 options_and_hooks
+control_mode
 ```