feat(tmux) Client, typed fields, native filter (#672)

libtmux 0.57.0 broadens tmux coverage. It introduces Client as a
first-class typed object, threads tmux's native -f filter through
the typed listing methods so callers can push predicates into the
tmux server, adds typed access to many more format tokens with
scope-and-version-gated -F templates, and propagates subcommand
context through LibTmuxException so downstream tools can dispatch
on which tmux command produced an error.

What's new:

- **Client object and Server.clients accessor.** New typed
  dataclass for attached terminals. client_name is the stable
  identifier; session_id / window_id / pane_id are attached-view
  snapshots hydrated via tmux's downward format_defaults cascade.
  attached_session / attached_window / attached_pane re-read
  list-clients before resolving; attached_pane is session-scope
  (cascade), not the client's CLIENT_ACTIVEPANE focus.

- **Server.display_message and Window.display_message.** Server
  reads like #{version} and #{socket_path} work without a pane
  handle; window reads (#{window_zoomed_flag},
  #{window_active_clients_list}) auto-bind to the window's id.
  All three display_message wrappers (including the existing
  Pane.display_message) surface tmux stderr via warnings.warn
  rather than dropping it silently. Callers that want to
  escalate can wrap in warnings.catch_warnings with
  filterwarnings("error").

- **Native filter on typed listing methods.**
  Server.search_panes / search_windows / search_sessions plus the
  Session and Window analogues take a filter= kwarg routed to
  tmux's -f flag. tmux evaluates the predicate and drops
  non-matching rows before any Python instance is constructed.
  Caveat: tmux silently expands a malformed predicate to empty,
  which the format engine treats as false — a typo looks
  identical to "no matches".

- **Scope-and-version-aware -F templates.** The format string
  libtmux sends each list-* subcommand is now scope- and
  version-aware. A Session row hydrates active-window and
  active-pane fields via tmux's downward cascade; a Client row
  likewise hydrates the client's attached session, window, and
  active pane. Tokens introduced after tmux 3.2a are gated
  through FIELD_VERSION so the -F template stays safe on the
  project's minimum supported tmux. Unknown tokens stay None on
  the typed surface — no crash, no warning.

- **Typed Pane / Window / Session / Client format-token fields
  for the 3.2a set.** Pane state (pane_dead, pane_in_mode,
  pane_marked, pane_synchronized, pane_path, pane_pipe …), window
  state (window_zoomed_flag, window_silence_flag, window_flags …),
  session state (session_marked …), and client view
  (client_session, client_readonly, client_termtype …).

- **Server.run_shell(cwd=, show_stderr=).** New kwargs map to
  tmux's -c (3.4+) and -E (3.6+) flags. Older tmux warns and
  ignores the kwarg instead of erroring.

- **Pane.send_keys(cmd=None, …) flag-only invocation.** Pass
  cmd=None together with reset=True or repeat=N to invoke tmux's
  flag-only send-keys -R / send-keys -N <n> form without any
  trailing key argument.

- **Server.list_buffers(format_string=, filter=).** Project a
  chosen -F template or push a buffer-name match expression
  through tmux's format engine.

- **Pane.capture_pane(pending=True).** Return bytes tmux has
  read from the pane but not yet committed to the terminal —
  useful for diagnosing programs whose output stalls mid-sequence.

Fixes:

- Pane.reset() now clears pane scrollback. The history clear
  silently no-op'd in 0.56.0, leaving the scrollback intact
  (#650).

- Server.sessions / Server.clients / Server.search_sessions now
  distinguish a fresh server (no daemon yet) from a real tmux
  failure (permission denied, malformed daemon response). The
  former still returns an empty QueryList; the latter raises
  LibTmuxException instead of being swallowed.

Breaking changes:

- **LibTmuxException string form gains a subcommand prefix.**
  str(exc) now begins with the originating tmux subcommand name
  followed by ": ". An error from Session.last_window() used to
  render as "can't find window" and now renders as "last-window:
  can't find window". The wrapped-stderr type also changed:
  exc.args[0] is now str (joined with "\n" when tmux emitted
  multiple stderr lines); previously it was list[str]. Substring
  matches and unanchored re.search patterns continue to work
  unchanged.

- **Server.sessions, Server.clients, and Server.search_sessions
  raise on tmux errors.** Previously, a tmux command failure was
  swallowed by a bare except Exception: pass, returning an empty
  QueryList indistinguishable from "no sessions/clients" or
  "filter matched nothing". The wrappers now let LibTmuxException
  propagate; only "no server running" / "error connecting to" on
  a fresh server remain empty-result cases.

Deferred to follow-up shipments:

- Typed Obj fields for tokens tmux added in 3.4 / 3.5 / 3.6 and
  the forward-looking set from tmux master. Held until tmux 3.7
  reaches a tagged release.

- Per-client active-pane resolution via tmux's CLIENT_ACTIVEPANE
  flag. Client.attached_pane currently follows the cascade
  (session's current window's active pane); the two diverge once
  a client has used select-pane -P to set its own active pane.

- A predictable error contract for display_message
  (version-gated raise, per-call raise_on_stderr kwarg, or
  kept-permanent warn).

Fixes #650.
Refs #670 (umbrella).
Companion: tmux-python/libtmux-mcp#48.

Author: tony

CHANGES

@@ -45,10 +45,222 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+libtmux 0.57.0 broadens tmux support around attached clients, tmux-native
+filtering, and format-token fields. {class}`~libtmux.Client` gives callers a
+typed object for attached terminals, `search_*()` methods let tmux return only
+matching sessions, windows, and panes, and more tmux format tokens are exposed
+as typed attributes. {exc}`~libtmux.exc.LibTmuxException` now records which
+tmux subcommand failed, making command errors easier to handle downstream.
+
+### Breaking changes
+
+#### `LibTmuxException` string form gains a subcommand prefix (#672)
+
+When {exc}`~libtmux.exc.LibTmuxException` is raised from a libtmux method,
+``str(exc)`` now begins with the originating tmux subcommand name followed
+by ``": "``. For example, an error from
+{meth}`~libtmux.Session.last_window` used to render as ``"can't find
+window"`` and now renders as ``"last-window: can't find window"``.
+
+``exc.args[0]`` still carries the original tmux error text, and the new
+{attr}`~libtmux.exc.LibTmuxException.subcommand` attribute exposes
+the tmux subcommand name as a separate field.
+{func}`~libtmux.common.raise_if_stderr` is the shared helper that
+populates both.
+
+The error-payload *type* changed: ``exc.args[0]`` is now ``str``,
+joined with ``"\n"`` when tmux emitted multiple stderr lines.
+Previously it was ``list[str]``.
+
+This is a serialization-format change: code that pattern-matches on
+``str(exc)`` exactly, anchors a regex with ``^`` against the old
+shape, or indexes ``exc.args[0]`` element-by-element will no longer
+match.
+
+```python
+# Before
+try:
+    session.last_window()
+except LibTmuxException as exc:
+    if str(exc) == "can't find window":
+        ...
+
+# After — dispatch on the typed attribute
+try:
+    session.last_window()
+except LibTmuxException as exc:
+    if exc.subcommand == "last-window":
+        ...
+
+# Or — match against the original tmux error text without the prefix
+try:
+    session.last_window()
+except LibTmuxException as exc:
+    if exc.args and exc.args[0] == "can't find window":
+        ...
+```
+
+Substring matches (``"can't find" in str(exc)``) and unanchored
+``re.search`` patterns continue to work unchanged.
+
+#### `Server.sessions`, `Server.clients`, and `Server.search_sessions` raise on tmux errors (#672)
+
+Previously, a tmux command failure under
+{attr}`~libtmux.Server.sessions`, {attr}`~libtmux.Server.clients`, or
+{meth}`~libtmux.Server.search_sessions` could return an empty
+{class}`~libtmux._internal.query_list.QueryList` indistinguishable
+from "no sessions / no clients attached" or "filter matched nothing".
+Those accessors now let {exc}`~libtmux.exc.LibTmuxException` propagate
+for real tmux failures.
+
+Genuine empty results — a server with no attached clients, or a
+filter that matched zero sessions — still return an empty
+``QueryList``. A missing or not-yet-started tmux server is also still
+treated as an empty result, preserving the historic contract that a fresh
+{class}`~libtmux.Server` can be safely introspected before its daemon is
+up. Other tmux errors, such as socket permission failures or unsupported
+flags, now surface.
+
+```python
+# Before — silent on tmux failure
+if not server.clients:
+    log("no clients")  # also runs when tmux itself crashed
+
+# After — distinguish the two cases
+try:
+    clients = server.clients
+except LibTmuxException as exc:
+    log(f"list-clients failed: {exc}")
+else:
+    if not clients:
+        log("no clients")
+```
+
+### What's new
+
+#### `Client` object and `Server.clients` accessor (#672)
+
+New {class}`~libtmux.Client` and {attr}`~libtmux.Server.clients` support tmux's
+attached-client model directly. Reads like ``client.client_readonly`` and
+``client.client_session`` work on the client object without dropping down to
+{meth}`~libtmux.Server.cmd`.
+
+Note that ``client.session_id`` / ``client.window_id`` / ``client.pane_id``
+reflect the client's attached view when the object was read —
+{meth}`~libtmux.Client.refresh` re-reads them after the client switches focus.
+``client.client_name`` is the client's stable identifier.
+
+For typed access to the live attachment, use
+{attr}`~libtmux.Client.attached_session`,
+{attr}`~libtmux.Client.attached_window`, and
+{attr}`~libtmux.Client.attached_pane`. Each property re-reads the
+client from ``list-clients`` before resolving; if tmux no longer
+reports that ``client_name``, such as after the client detaches, the
+property returns ``None``. Otherwise, the returned
+{class}`~libtmux.Session` / {class}`~libtmux.Window` /
+{class}`~libtmux.Pane` reflects where the client is attached *now*,
+not where it was when the {class}`~libtmux.Client` was constructed.
+Direct {meth}`~libtmux.Client.refresh` and
+{meth}`~libtmux.Client.from_client_name` calls still surface missing
+client lookup errors.
+
+{attr}`~libtmux.Client.attached_pane` follows the attached session's current
+window. That can differ from the per-client active pane set by
+``select-pane -P``; see {attr}`~libtmux.Client.attached_pane` for the exact
+behavior.
+
+#### `Server.display_message` and `Window.display_message` (#672)
+
+{meth}`~libtmux.Server.display_message` and
+{meth}`~libtmux.Window.display_message` join the existing
+{meth}`~libtmux.Pane.display_message`. Server reads like
+``#{version}`` and ``#{socket_path}`` work without a pane handle;
+window reads (``#{window_zoomed_flag}``, ``#{window_active_clients_list}``)
+auto-bind to the window's id.
+
+All three wrappers surface tmux stderr via :func:`warnings.warn`
+rather than dropping it silently. tmux uses stderr for both genuine
+errors and informational messages on some versions, so the wrappers
+warn rather than raise; callers that want to escalate can wrap the
+call in :func:`warnings.catch_warnings` with
+``filterwarnings("error")``. See {doc}`migration` for the escalation
+pattern.
+
+#### tmux-native filtering with `search_*()` (#672)
+
+{meth}`~libtmux.Server.search_panes`,
+{meth}`~libtmux.Server.search_windows`,
+{meth}`~libtmux.Server.search_sessions`, and the Session/Window
+analogues take a ``filter=`` kwarg routed to tmux's ``-f`` flag. tmux
+evaluates the expression and returns only matching objects.
+
+Caveat: tmux silently expands a malformed filter expression to empty, which
+it treats as false — a typo looks identical to "no matches". Verify filter
+syntax against the FORMATS section of ``tmux(1)``.
+
+#### `Pane.send_keys(cmd=None, …)` flag-only invocation (#672)
+
+{meth}`~libtmux.Pane.send_keys` accepts ``cmd=None`` together with
+``reset=True`` or ``repeat=N`` to invoke tmux's flag-only
+``send-keys -R`` / ``send-keys -N <n>`` form without any trailing
+key argument.
+
+#### `Server.list_buffers(format_string=, filter=)` (#672)
+
+{meth}`~libtmux.Server.list_buffers` gains ``format_string`` (``-F``)
+and ``filter`` (``-f``) kwargs. Callers can ask tmux to return selected
+fields (e.g. ``"#{buffer_name}"``) or only buffers matching an expression —
+same bad-filter caveat as the ``search_*`` methods.
+
+#### `Server.run_shell(cwd=, show_stderr=)` (#672)
+
+{meth}`~libtmux.Server.run_shell` gains ``cwd`` (``-c``) to set the
+shell command's working directory and ``show_stderr`` (``-E``) to
+merge the command's stderr into the captured output. Both kwargs are
+version-gated; older tmux warns and ignores the flag instead of
+erroring.
+
+#### `Pane.capture_pane(pending=True)` (#672)
+
+{meth}`~libtmux.Pane.capture_pane` gains a ``pending`` kwarg that
+returns bytes tmux has read from the pane but not yet committed to
+the terminal — useful for diagnosing programs whose output stalls
+mid-sequence.
+
+#### More format-token fields on tmux objects (#672)
+
+libtmux now asks each ``list-*`` subcommand for the format tokens that make
+sense for that object and tmux version. Tokens the running tmux does not
+support stay ``None`` instead of making the listing fail.
+
+{class}`~libtmux.Pane`, {class}`~libtmux.Window`,
+{class}`~libtmux.Session`, and {class}`~libtmux.Client` expose more typed
+attributes for pane state (``pane_dead``, ``pane_in_mode``, ``pane_marked``,
+``pane_synchronized``, ``pane_path``, ``pane_pipe``), window state
+(``window_zoomed_flag``, ``window_silence_flag``, ``window_flags``), session
+state (``session_marked``), and client state (``client_session``,
+``client_readonly``, ``client_termtype``). Some fields describe the active
+child object tmux reports with the row: for example, ``session.pane_id`` is
+the active pane in the session's current window, not a separate "session
+pane." See {ref}`format-tokens` for details.
+
+### Fixes
+
+- {meth}`~libtmux.Pane.reset` now clears pane scrollback. In 0.56.0
+  the history clear silently no-op'd, leaving the scrollback intact
+  (#650).
+
+### Documentation
+
+- New API page: {doc}`api/libtmux.client`.
+- New {ref}`format-tokens` topic explains why some fields describe an active
+  child object, such as ``session.pane_id`` reflecting the active pane in the
+  session's current window (#672).
+
 ## libtmux 0.56.0 (2026-05-10)
 
 libtmux 0.56.0 is the tmux command-parity release. It adds more than
-50 wrappers across {class}`~libtmux.Server`, {class}`~libtmux.Session`,
+50 commands across {class}`~libtmux.Server`, {class}`~libtmux.Session`,
 {class}`~libtmux.Window`, and {class}`~libtmux.Pane`, filling in many
 commands that previously required raw {meth}`~libtmux.Server.cmd` calls.
 It also adds attached-client test support so interactive tmux commands can be
@@ -58,7 +270,7 @@ covered in headless test suites.
 
 #### Interactive tmux commands are now scriptable (#653)
 
-libtmux now exposes Python wrappers for tmux commands that normally depend on
+libtmux now exposes Python commands for tmux that normally depend on
 an attached client: {meth}`~libtmux.Pane.display_popup`,
 {meth}`~libtmux.Server.display_menu`,
 {meth}`~libtmux.Server.command_prompt`,
@@ -80,7 +292,7 @@ The `detach-client` API is split by the same scopes tmux actually honors:
 `tmux detach-client -a [-t <keep>]`. This keeps each method to one tmux flag
 group and one subprocess call.
 
-#### tmux buffer I/O has first-class wrappers (#653)
+#### tmux buffer I/O has first-class support (#653)
 
 Named tmux buffers can now be used from libtmux without hand-built commands.
 {meth}`~libtmux.Server.set_buffer`,
@@ -94,7 +306,7 @@ inter-process handoff workflows.
 
 #### Server commands cover key bindings, clients, shell execution, and access (#653)
 
-{class}`~libtmux.Server` gains wrappers for key-binding inspection and mutation
+{class}`~libtmux.Server` gains support for key-binding inspection and mutation
 ({meth}`~libtmux.Server.bind_key`,
 {meth}`~libtmux.Server.unbind_key`,
 {meth}`~libtmux.Server.list_keys`,
@@ -137,7 +349,7 @@ Navigation helpers fill in the surrounding topology:
 {meth}`~libtmux.Session.next_window`, and
 {meth}`~libtmux.Session.previous_window`.
 
-#### Existing wrappers expose more tmux flags (#653)
+#### Improvements (#653)
 
 Several established methods now surface tmux flags that were previously only
 available by dropping to raw commands. Highlights include
@@ -196,7 +408,7 @@ old hardcoded socket paths. Fixes #664.
 
 #### tmux 3.7 is within the known-version range (#653)
 
-{data}`~libtmux.common.TMUX_MAX_VERSION` is now `"3.7"`, enabling wrappers and
+{data}`~libtmux.common.TMUX_MAX_VERSION` is now `"3.7"`, enabling support and
 tests for version-gated tmux 3.7 flags such as
 {meth}`~libtmux.Server.command_prompt` `bspace_exit` and
 {meth}`~libtmux.Server.show_messages` `terminals` / `jobs`. Installations on
@@ -343,7 +555,7 @@ surface from Make to Just.
 
 ### Fixes
 
-#### `Server.new_session()` no longer races its own hydration query (#625)
+#### `Server.new_session()` no longer races its own initialization query (#625)
 
 {meth}`~libtmux.Server.new_session` now parses all required session fields from
 the `tmux new-session -P` output instead of creating the session and then