Experiment: Control mode

.github/workflows/tests.yml

@@ -84,6 +84,13 @@ jobs:
           COV_CORE_SOURCE: .
           COV_CORE_CONFIG: .coveragerc
           COV_CORE_DATAFILE: .coverage.eager
+      - name: Test with pytest (control engine)
+        continue-on-error: ${{ matrix.tmux-version == 'master' }}
+        run: |
+          sudo apt install libevent-2.1-7
+          export PATH=$HOME/tmux-builds/tmux-${{ matrix.tmux-version }}/bin:$PATH
+          tmux -V
+          uv run py.test --engine=control -n auto --verbose
       - uses: codecov/codecov-action@v6
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

CHANGES

@@ -1022,6 +1022,61 @@ The 0.50.0 option/hook deprecations remain soft warnings for now:
 | `set_window_option()`, `show_window_option()`, `show_window_options()` | {meth}`~libtmux.Window.set_option`, {meth}`~libtmux.Window.show_option`, {meth}`~libtmux.Window.show_options` | 0.50.0 | Window |
 | `g` option parameter | `global_` on {meth}`~libtmux.options.OptionsMixin.set_option`, {meth}`~libtmux.options.OptionsMixin.show_option`, {meth}`~libtmux.options.OptionsMixin.show_options` | 0.50.0 | Options and hooks |
 
+### Features
+
+#### Control mode engine (experimental) (#605)
+- Control-mode–first engine stack with structured `CommandResult`, notification parsing
+  (%layout-change, unlinked window add/close/rename, client session change/detach, paste buffer),
+  and stats, while keeping the public `cmd` API returning `tmux_cmd`.
+- Internal control session is automatically filtered from `Server.sessions` /
+  `Server.has_session()`; advanced users can inspect all sessions via
+  `Server._sessions_all()`.
+- `ControlModeEngine` accepts `internal_session_name` (default `libtmux_ctrl_XXXXXXXX`)
+  and `control_session` for advanced connection strategies.
+
+Example:
+
+```python
+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")
+for notif in engine.iter_notifications(timeout=0.1):
+    print(notif.kind, notif.data)
+```
+
+#### Convenience APIs (#605)
+- `Server.connect()` returns an existing session or creates a new detached one,
+  working with both subprocess and control-mode engines.
+
+#### Diagnostics and resilience (#605)
+- Bounded notification queue with drop counting; exposed via engine stats.
+- Expanded exceptions: `ControlModeTimeout`, `ControlModeProtocolError`,
+  `ControlModeConnectionError`, `SubprocessTimeout`; documented retry/timeout behaviour.
+- Control-mode capture-pane trims trailing whitespace-only lines to mirror subprocess
+  semantics; first capture after send-keys briefly retries to avoid prompt races.
+
+#### Testing utilities (#605)
+- Control sandbox fixture provides a hermetic control-mode tmux server (isolated HOME,
+  TMUX_TMPDIR, unique socket); handy for integration-style tests.
+  Example:
+
+  ```python
+  @pytest.mark.engines(["control"])
+  def test_control_sandbox(control_sandbox):
+      with control_sandbox as server:
+          out = server.cmd("display-message", "-p", "hi")
+          assert out.stdout == ["hi"]
+  ```
+
+### Compatibility
+
+- Control mode internal session filtering is engine-driven; callers no longer need
+  to manually exclude `libtmux_ctrl_*`. APIs stay unchanged; additional metadata
+  is attached for advanced users. (#605)
+
 ## libtmux 0.50.1 (2025-12-06)
 
 libtmux 0.50.1 is a documentation repair release for the 0.50 option and hook

docs/api/index.md

@@ -163,6 +163,13 @@ Active deprecations and migration guidance.
 
 ::::
 
+
+:::{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}
 :hidden:
 :maxdepth: 1

docs/api/testing/pytest-plugin/usage.md

@@ -127,6 +127,53 @@ This is particularly useful when testing interactions between multiple tmux serv
 ...     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
+
 [pytest]: https://docs.pytest.org/en/stable/
 [pytest-tmux]: https://pytest-tmux.readthedocs.io/
 [tmuxp]: https://tmuxp.git-pull.com/

docs/pytest-plugin/index.md

@@ -0,0 +1,65 @@
+---
+myst:
+  html_meta:
+    description: "libtmux pytest plugin for testing tmux applications with pytest"
+    keywords: "tmux, pytest, plugin, testing, libtmux"
+---
+
+(pytest_plugin)=
+
+# tmux `pytest` plugin
+
+```{toctree}
+:hidden:
+:maxdepth: 2
+
+getting-started
+fixtures
+usage-examples
+advanced-techniques
+```
+
+libtmux provides pytest fixtures for tmux, making it easy to test tmux-related functionality with complete isolation. The plugin automatically manages setup and teardown of independent tmux servers, sessions, windows, and panes.
+
+```{admonition} Connect with us!
+:class: seealso
+
+Do you want more flexibility? Correctness? Power? Defaults changed? [Connect with us](https://github.com/tmux-python/libtmux/discussions) on the tracker. We want to know your use case and won't stabilize APIs until we're sure everything is by the book.
+```
+
+## Benefits at a glance
+
+- **Isolated Testing Environment**: Each test gets a fresh tmux server that won't interfere with other tests
+- **Automatic Cleanup**: Servers, sessions, and other resources are automatically cleaned up after tests
+- **Simplified Setup**: Common fixtures for server, session, window, and pane management
+- **Reliable Testing**: Consistent environment for reproducible test results
+- **Custom Configuration**: Easily test with different tmux configurations and settings
+
+## Quick installation
+
+Install `libtmux` via the Python package manager of your choice:
+
+```{code-block} console
+$ pip install libtmux
+```
+
+The pytest plugin will be automatically detected by pytest, and the fixtures will be available in your test environment.
+
+## See real-world examples
+
+View libtmux's own [tests/](https://github.com/tmux-python/libtmux/tree/master/tests) as well as tmuxp's [tests/](https://github.com/tmux-python/tmuxp/tree/master/tests) for real-world examples.
+
+For detailed code examples and usage patterns, refer to the {ref}`usage-examples` page.
+
+## Module reference
+
+```{module} libtmux.pytest_plugin
+```
+
+```{eval-rst}
+.. automodule:: libtmux.pytest_plugin
+    :members:
+    :inherited-members:
+    :private-members:
+    :show-inheritance:
+    :member-order: bysource

docs/quickstart.md

@@ -171,6 +171,26 @@ equivalent to `$ tmux -L mysocket`.
 {class}`~libtmux.Session`, {class}`~libtmux.Window`, and
 {class}`~libtmux.Pane` objects.
 
+### 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.
+
 ## Raw, contextual commands
 
 New session:
@@ -283,6 +303,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