tony · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ['3.14']
-        tmux-version: ['3.2a', '3.3a', '3.4', '3.5', '3.6', '3.7a', '3.7b', 'master']
+        tmux-version: ['3.3a', '3.4', '3.5', '3.6', '3.7', '3.7a', '3.7b', '3.8', 'master']
     steps:
       - uses: actions/checkout@v7
 
@@ -90,6 +90,44 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  unsupported-versions:
+    # Real 3.2a and 3.3 daemons must be refused with no effects.
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.14
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Build supported and rejected native endpoints
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libevent-dev libncurses-dev bison
+          mkdir -p "$RUNNER_TEMP/tmux-versions"
+          for version in 3.2a 3.3 3.3a; do
+            git clone --quiet --depth=1 --branch "$version" https://github.com/tmux/tmux.git "$RUNNER_TEMP/tmux-versions/$version"
+            cd "$RUNNER_TEMP/tmux-versions/$version"
+            sh autogen.sh
+            ./configure --prefix="$RUNNER_TEMP/tmux-versions/$version/install"
+            make -j2
+            make install
+          done
+          echo "LIBTMUX_TEST_MINIMUM_TMUX=$RUNNER_TEMP/tmux-versions/3.3a/install/bin/tmux" >> "$GITHUB_ENV"
+          echo "LIBTMUX_TEST_UNSUPPORTED_TMUX=$RUNNER_TEMP/tmux-versions/3.2a/install/bin/tmux" >> "$GITHUB_ENV"
+          echo "LIBTMUX_TEST_UNPATCHED_TMUX=$RUNNER_TEMP/tmux-versions/3.3/install/bin/tmux" >> "$GITHUB_ENV"
+
+      - name: Refuse older daemons
+        run: uv run pytest tests/test_versions.py --reruns=0 -q
+
   release:
     runs-on: ubuntu-latest
     needs: build

diff --git a/AGENTS.md b/AGENTS.md
@@ -52,7 +52,7 @@ be stated twice, the file listed above is the one that governs.
 - A passing gate is evidence only once it has been shown capable of
   failing. Pair a new test with a deliberate break that proves it bites.
 
-tmux >= 3.2a is the compatibility floor (see `tests.yml`'s build
+tmux >= 3.3a is the compatibility floor (see `tests.yml`'s build
 matrix). `Server.sessions`, `Server.clients`, and
 `Server.attached_sessions` return an empty `QueryList` rather than
 raising when the underlying tmux list command fails for any reason —
@@ -61,6 +61,9 @@ list-shaped accessors are lenient by default; `Server.is_alive()` and
 `src/libtmux/AGENTS.md` for the full contract and this package's
 logging conventions.
 
+An unsupported tmux version raises `VersionTooLow`, including from lenient
+list accessors and query traversal. Version refusals are not empty results.
+
 ## References
 
 - Documentation: https://libtmux.git-pull.com/

diff --git a/CHANGES b/CHANGES
@@ -45,6 +45,104 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Breaking changes
+
+#### Minimum tmux 3.3a (#779)
+
+Minimum `tmux>=3.3a` (was `>=3.2a`). Ordinary reads, writes, batches, and raw
+commands raise {exc}`~libtmux.exc.VersionTooLow` for an older daemon, including
+3.3 without its patch letter. The daemon's version governs an existing
+endpoint; the executable's version governs creation on an absent endpoint.
+
+```text
+# Before
+tmux>=3.2a
+
+# After
+tmux>=3.3a
+```
+
+Upgrade tmux and restart existing daemons after saving their sessions.
+Updating the client executable alone does not upgrade a running daemon.
+A renamed tmux 3.3a executable still qualifies the minimum.
+The version check runs no user hooks, and each
+{class}`~libtmux.Server` probes its endpoint once, then relies on the version
+fence to notice a replaced daemon. Optional flags follow the daemon's release,
+not the client executable's. The version check reads the forms tmux reports
+(`3.3a`, `3.8-rc`, `next-3.9`) and refuses a development suffix on a release,
+`master` and leading zeros. {mod}`libtmux._internal.support`
+lets programs built on libtmux reuse the check.
+Binary version and help diagnostics remain available. {meth}`Server.kill() <libtmux.Server.kill>`
+remains a no-op for an absent endpoint. See {doc}`project/compatibility` for
+support and feature requirements.
+
+#### Optional tmux feature requirements
+
+On tmux 3.3a, literal `select-layout` refuses unknown names and malformed
+serialized headers before batch effects with
+{exc}`~libtmux.exc.InvalidLayout`, a {exc}`~libtmux.exc.LibTmuxException` that is
+also a `ValueError`; ordinary layouts retain the 3.3a minimum. Programs that run
+their own tmux subprocesses can apply these checks through
+{func}`libtmux._internal.support.require_commands`.
+
+Single-pane `Pane.break_pane()` returns its actual window on tmux 3.3a through
+3.5, whose native relink path succeeds without printing the requested ID.
+
+Core support remains tmux 3.3a+. {class}`ControlMode
+<libtmux._internal.control_mode.ControlMode>` requires a stable tmux 3.7+
+release and a local socket filesystem that permits a private hard link.
+Control acquisition validates the retained endpoint before starting its client;
+UTF-8 metadata and output remain usable under a C locale. Acquisition runs no
+user hooks before it validates the endpoint and names its client locally
+(`client-<pid>`), and any release ranking at or above 3.7, such as `3.8-rc2` or
+`next-3.8`, qualifies while `next-3.7` and `3.7-rc*` do not.
+
+Exact named-buffer deletion and rename require tmux 3.4+. Captured shell-job
+stdout from {meth}`Server.run_shell() <libtmux.Server.run_shell>` requires
+3.5+ and is refused before launching the job on older daemons. Background,
+pane-directed and native tmux-command execution remain available on 3.3a+.
+
+{meth}`Server.run_shell(target_pane=...) <libtmux.Server.run_shell>` now returns
+`None`, as its signature documents, instead of an empty list: the job's output
+goes to the pane, so there is no captured stdout to return. Code that iterates
+the result of a pane-directed call must handle `None`.
+
+On exact tmux 3.7, window and session names containing `:` or `.` are refused
+before dispatch (`new-window -n`, `new-session -s/-n`, `rename-window`,
+`rename-session`); 3.7a accepts them again.
+
+Percentage splits use portable `-l N%`. On exact tmux 3.7, raw `break-pane`
+and unnamed {meth}`Pane.break_pane() <libtmux.Pane.break_pane>` requests are
+refused. An explicit `window_name` uses the named break and rename repair;
+a failed rename can leave the completed break in place. Other supported
+releases retain ordinary naming. See {doc}`project/compatibility` for the
+operation boundaries and synchronization requirements.
+
+### Deprecations
+
+#### Executable version helpers warn (#779)
+
+{func}`~libtmux.common.get_version`, {func}`~libtmux.common.get_version_str`,
+{func}`~libtmux.common.has_version`, {func}`~libtmux.common.has_gt_version`,
+{func}`~libtmux.common.has_gte_version`, {func}`~libtmux.common.has_lte_version`,
+{func}`~libtmux.common.has_lt_version`, {func}`~libtmux.common.has_minimum_version`
+and the `TMUX_MIN_VERSION` and `TMUX_MAX_VERSION` constants now emit a
+{exc}`DeprecationWarning`. They read the tmux client executable, not the
+daemon a {class}`~libtmux.Server` is connected to, which can be a different
+release. All of them stay importable from `libtmux.common`.
+
+```python
+# Before
+from libtmux.common import has_gte_version
+
+has_gte_version("3.4")
+
+# After
+from libtmux._internal.support import is_at_least, server_version
+
+is_at_least(server_version(server), "3.4")
+```
+
 ### Documentation
 
 #### Cleaner `from_env` examples (#719)

diff --git a/README.md b/README.md
@@ -30,7 +30,13 @@ libtmux is a typed Python API over [tmux], the terminal multiplexer. Stop shelli
 
 ## Requirements & support
 
-- tmux: >= 3.2a
+- tmux: >= 3.3a
+
+Optional operations have separate requirements. Control acquisition requires a
+qualified tmux 3.7+ release and a retainable local socket; exact named-buffer
+deletion/rename require 3.4+, and captured shell stdout requires 3.5+.
+See the [compatibility policy](https://libtmux.git-pull.com/project/compatibility/)
+for exact-3.7 break-pane restrictions and the operations available on 3.3a.
 - Python: >= 3.10 (CPython and PyPy)
 
 Maintenance-only backports (no new fixes):

diff --git a/conftest.py b/conftest.py
@@ -17,10 +17,9 @@
 import pytest
 from _pytest.doctest import DoctestItem
 
-from libtmux._internal.control_mode import ControlMode
 from libtmux.client import Client
 from libtmux.pane import Pane
-from libtmux.pytest_plugin import USING_ZSH
+from libtmux.pytest_plugin import USING_ZSH, _control_mode_for_test
 from libtmux.server import Server
 from libtmux.session import Session
 from libtmux.window import Window
@@ -51,9 +50,9 @@ def add_doctest_fixtures(
         doctest_namespace["window"] = session.active_window
         doctest_namespace["pane"] = session.active_pane
         doctest_namespace["request"] = request
-        doctest_namespace["ControlMode"] = ControlMode
+        doctest_namespace["ControlMode"] = _control_mode_for_test
         doctest_namespace["control_mode"] = functools.partial(
-            ControlMode,
+            _control_mode_for_test,
             server=session.server,
             session=session,
         )

diff --git a/docs/internals/api/libtmux._internal.support.md b/docs/internals/api/libtmux._internal.support.md
@@ -0,0 +1,17 @@
+# Internal Support
+
+The {mod}`libtmux._internal.support` package holds the tmux version check that
+every command runs against the connected daemon.
+
+:::{warning}
+These APIs are private and are **not** covered by version policies. They can
+break or be removed between minor versions.
+:::
+
+```{eval-rst}
+.. automodule:: libtmux._internal.support
+   :members:
+
+.. automodule:: libtmux._internal.support.versions
+   :members:
+```
diff --git a/docs/internals/index.md b/docs/internals/index.md
@@ -37,6 +37,12 @@ Internal format strings and tmux constants.
 Sparse array data structure for tmux format parsing.
 :::
 
+:::{grid-item-card} Support
+:link: api/libtmux._internal.support
+:link-type: doc
+The tmux version check every command runs against the connected daemon.
+:::
+
 ::::
 
 ```{toctree}
@@ -47,6 +53,7 @@ api/libtmux._internal.dataclasses
 api/libtmux._internal.query_list
 api/libtmux._internal.constants
 api/libtmux._internal.sparse_array
+api/libtmux._internal.support
 ```
 
 ## Environmental variables

diff --git a/docs/project/compatibility.md b/docs/project/compatibility.md
@@ -8,10 +8,123 @@
 
 ## tmux
 
-- **Minimum**: tmux 3.2a
-- **Tested**: latest stable tmux release
-- libtmux uses tmux's format system and control mode -- older tmux versions
-  may lack required format variables
+Core operations require tmux **3.3a or newer**, including the patch letter.
+Tmux 3.3 is below the minimum. The CI matrix includes 3.3a and later releases;
+`master` is a development lane.
+
+Commands check the connected daemon, which can differ from the selected
+client executable. An absent endpoint uses the executable's fresh version
+report before startup. Raw commands, batches and liveness checks share this
+rule. An unsupported or unreadable version raises
+{exc}`~libtmux.exc.VersionTooLow` before the requested command runs.
+A replacement daemon is checked again before dispatch.
+{meth}`~libtmux.Server.kill` returns without dispatching when its endpoint is
+absent.
+
+Each {class}`~libtmux.Server` probes its endpoint once, bounded to five
+seconds, and reuses the checked release for later commands and optional-flag
+decisions. The version fence in every command catches a replaced daemon: it
+refuses with no effect and the next command probes again. A vanished daemon is
+detected and the next command checks the version again; {meth}`~libtmux.Server.kill` and
+an absent endpoint always read the endpoint directly. The query is `run-shell -C` with a marker format, which
+fires neither `after-*` hooks nor `command-error`, so a user's hooks never run
+for a version check. It exits 1 with the version in its error text. If a replaced
+daemon fails the fence on tmux 3.5 or newer, `command-error` fires once for
+that refusal, which reports a real error. Binary diagnostics through `tmux -V` and
+`tmux -h` remain available. Raw `tmux -c` shell execution is refused; use
+{meth}`~libtmux.Server.run_shell` with its documented output mode.
+
+The version check reads the forms tmux reports: a release with an optional patch
+letter (`3.3a`), a candidate (`3.8-rc`, `3.8-rc2`) and a development build
+(`next-3.9`). They order as `next-3.9` < `3.9-rc` < `3.9-rc2` < `3.9` < `3.9a`,
+and minor numbers compare numerically, so a candidate or development build is
+supported only when its release number is above the baseline. Such builds do not
+inherit stable feature qualification. Everything else is refused: an undated
+`master`, a development suffix on a release (`3.3a-dev`), a patch letter on a
+development build (`next-3.3a`), leading zeros and OpenBSD's own numbering. On
+OpenBSD, an existing daemon must report a qualified release; an executable
+without `-V` cannot start an absent endpoint.
+The synthetic values returned by legacy version helpers are diagnostic values
+and never authorize a command.
+
+If a checked daemon disappears before dispatch, that command fails without
+starting the configured executable. Retry against the absent endpoint to
+validate the executable before creating a replacement.
+
+Individual features can require a newer daemon. Their API documentation states
+those requirements. Raising the core floor does not qualify control startup,
+output synchronization or other optional behavior on every later release.
+
+### Optional features
+
+| Operation | Eligible daemon and behavior |
+|-----------|------------------------------|
+| Ordinary subprocess operations | 3.3a+. Core support continues independently of control availability. |
+| `ControlMode` and the pytest control fixture | Stable numbered releases from 3.7, with a local Unix socket whose filesystem permits a private hard link. Refused before control startup on older or unqualified development builds. |
+| Explicit named-buffer deletion and rename | 3.4+. On 3.3a, a missing name can select an unrelated top buffer, so these requests are refused before dispatch. |
+| Buffer reads, writes, unnamed deletion and explicit named paste-and-delete | Available on 3.3a+. Named paste-and-delete rejects a missing name before any paste or deletion. It does not replace temporary-buffer abort cleanup. |
+| Captured shell-job stdout from `Server.run_shell` | 3.5+. On 3.3a and 3.4, the method refuses the capture before the job starts. |
+| Background jobs, pane-directed output and `as_tmux_command=True` | Available on 3.3a+. Background and pane-directed calls return `None`; background launch does not promise job completion. |
+| `Pane.split(percentage=...)` | Available on 3.3a+, using `-l N%`. Direct `split-window -p` is refused on the affected 3.4 interval. |
+| `break-pane` on exact 3.7 | Raw calls and unnamed typed calls are refused. `Pane.break_pane(window_name=...)` applies the explicit name after the move. A later rename failure can leave the moved pane in its new window. |
+| `break-pane` on other supported releases | Native behavior is retained. The exact-3.7 restriction does not raise their minimum. |
+| Single-pane `break-pane` before 3.6 | Native success prints no window ID. The typed method rereads the pane's actual window after the command. |
+| Literal `select-layout` on 3.3a | Require a unique native preset or a serialized layout header before dispatch. Unknown names and malformed headers are refused before any batch effect; valid presets, layout cycling and undo remain available. |
+| Window names containing `:` or `.` | Exact 3.7 rejects creation before creating a window. Other tested supported releases retain those names. There is no automatic name substitution. |
+
+Eligibility comes from the selected daemon, including when a newer client is
+used. Native dispatch checks the release again before executing the
+operation. Feature guards cover direct literal native built-in command items,
+their native aliases, abbreviations and batches. They do not interpret opaque
+user-authored programs or expand configured command aliases; those contents
+remain outside this guarantee.
+Raw command stdout is native client output; it does not promise capture of a
+nested shell job's stdout.
+
+Programs that run their own tmux subprocesses can apply the same checks
+through {mod}`libtmux._internal.support`: `require_commands` refuses the literal
+commands in the table for a checked release. Each libtmux operation still
+checks its daemon, and control acquisition still checks its socket carrier.
+
+On 3.3a, the layout guard validates the preset or serialized header before any
+batch effect. Checksum, tree structure and pane-count errors retain native
+reporting. The native missing-error-cause defect is fixed from 3.4 by
+[the upstream layout repair](https://github.com/tmux/tmux/commit/f10854cfc5e43f646b02b3031bfc4bc3f5f6c513).
+
+The version check assumes library-owned metadata and guard commands retain tmux's
+built-in semantics. Owner `command-alias` redefinitions of commands such as
+`display-message` or `if-shell` are outside qualification: tmux expands aliases
+before resolving even a canonical built-in name.
+
+Control holds a private socket alias for the owned client's lifetime. Failure
+to retain or identify that socket refuses acquisition. The native alias and
+replacement checks have been exercised on Linux/WSL; other filesystem and
+platform combinations need their own qualification. A successful idle attach
+does not establish concurrent or sustained-load stability.
+
+Control also needs a natively compatible client. Native clients 3.3a, 3.4 and
+3.5 fail to register with an exact-3.7 daemon; the daemon remains alive. A
+newer compatible client can register with that same daemon. Ordinary client
+operations retain the 3.3a minimum.
+
+### Synchronization and testing
+
+Version eligibility does not remove readiness, buffering or completion waits.
+`ControlMode` waits for its own client registration. Shell automation should
+use a complete output marker or state predicate, and streams must retain their
+framing and cancellation handling. A background command's reply confirms launch.
+
+CI retains ordinary older-server coverage. Only tests and documentation examples
+that need an ineligible control client are skipped for that release; control
+refusal tests still run. Captured-stdout and named-buffer tests assert refusals
+on older daemons, and exact 3.7 tests exercise both single- and multi-pane naming.
+The percentage-split test also runs on 3.4 through the portable encoding.
+
+The release boundaries come from tmux's
+[3.3a buffer operations](https://github.com/tmux/tmux/blob/0b355ae8114511e1ff6359272b164f1cdf718e80/cmd-set-buffer.c),
+[3.4 repair](https://github.com/tmux/tmux/blob/9ae69c3795ab5ef6b4d760f6398cd9281151f632/cmd-set-buffer.c),
+[3.5 shell output](https://github.com/tmux/tmux/blob/ac44566c9c7e3e94d23be6def4c7ae83472543f5/cmd-run-shell.c),
+and [exact-3.7 break behavior](https://github.com/tmux/tmux/blob/81f88f8517c9fc5371b56cf117530c6b477c96ac/cmd-break-pane.c).
 
 ## Platforms
 

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -12,7 +12,7 @@ from inside a live tmux session.
 
 ## Requirements
 
-- [tmux] 3.2a or newer
+- [tmux] 3.3a or newer
 - [pip] - for this handbook's examples
 
 [tmux]: https://tmux.github.io/