API(feat): Add owned scopes and command results

.github/CONTRIBUTING.md

@@ -62,6 +62,16 @@ Test:
 $ uv run pytest
 ```
 
+Start coverage before pytest so plugin imports and worker processes are
+measured:
+
+```console
+$ uv run coverage erase && \
+    uv run coverage run -m pytest -n auto && \
+    uv run coverage combine && \
+    uv run coverage xml
+```
+
 Documentation is a gate, not a courtesy. Examples in docstrings,
 documentation pages, and `README.md` are executed by `pytest`; the
 doctest flags live in `pyproject.toml`, so there is no separate doctest
@@ -128,6 +138,24 @@ Include doctests in the watch loop:
 $ uv run ptw . --now --doctest-modules
 ```
 
+## Benchmarks
+
+`benchmarks/` holds [pytest-benchmark] microbenchmarks for command
+dispatch, listing, snapshot capture, and format decoding. It is not a
+gate — performance work is a separate tier from the gates above, not
+part of them — and it is not in `testpaths`, so a plain `uv run pytest`
+never runs it.
+
+```console
+$ just bench
+```
+
+Report a regression with the printed numbers, not a guess. A number
+that lands in a commit message or `CHANGES` is a measurement someone
+ran, not a target to defend in the next one.
+
+[pytest-benchmark]: https://pytest-benchmark.readthedocs.io/
+
 ## Debugging
 
 Stuck in a debugging loop: pause and acknowledge it rather than trying

.github/WRITING.md

@@ -190,10 +190,10 @@ cannot pass, fix the example or fix the code.
 doctest in the suite runs, so a block never needs an import or a setup
 preamble to reach these names: `server`, `session`, `window`, `pane`,
 `Server`, `Session`, `Window`, `Pane`, `Client`, `ControlMode`,
-`control_mode`, `monkeypatch`, `request`. It only does this inside an
-actual doctest item and only when `tmux` is on `PATH` — a doctest that
-uses one of these names with no `tmux` binary available fails with a
-`NameError`, not a skip.
+`control_mode`, `retry_until`, `monkeypatch`, `request`. It only does
+this inside an actual doctest item and only when `tmux` is on `PATH` —
+a doctest that uses one of these names with no `tmux` binary available
+fails with a `NameError`, not a skip.
 
 **The `Server` trap.** `conftest.py` assigns `doctest_namespace["Server"]`
 twice: first to the real `libtmux.server.Server` class, then — a few

.github/workflows/tests.yml

@@ -20,6 +20,7 @@ jobs:
         uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
+          save-cache: ${{ strategy.job-index == 0 }}
 
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
@@ -36,24 +37,41 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras --dev
 
+      - name: Resolve tmux revision
+        id: tmux-source
+        env:
+          TMUX_REF: ${{ matrix.tmux-version }}
+        run: |
+          if [[ "$TMUX_REF" == master ]]; then
+            ref=refs/heads/master
+          else
+            ref="refs/tags/$TMUX_REF"
+          fi
+          revision=$(git ls-remote --refs https://github.com/tmux/tmux.git "$ref")
+          revision=${revision%%[[:space:]]*}
+          [[ "$revision" =~ ^[0-9a-f]{40}$ ]]
+          printf 'revision=%s\n' "$revision" >> "$GITHUB_OUTPUT"
+
       - name: Setup tmux build cache for tmux ${{ matrix.tmux-version }}
         id: tmux-build-cache
         uses: actions/cache@v6
         with:
           path: ~/tmux-builds/tmux-${{ matrix.tmux-version }}
-          key: tmux-${{ matrix.tmux-version }}
+          key: tmux-${{ runner.os }}-${{ runner.arch }}-${{ matrix.tmux-version }}-${{ steps.tmux-source.outputs.revision }}
 
       - name: Build tmux ${{ matrix.tmux-version }}
         if: steps.tmux-build-cache.outputs.cache-hit != 'true'
+        env:
+          TMUX_REVISION: ${{ steps.tmux-source.outputs.revision }}
         run: |
           sudo apt install libevent-dev libncurses5-dev libtinfo-dev libutempter-dev bison
           mkdir ~/tmux-builds
           mkdir ~/tmux-src
           git clone https://github.com/tmux/tmux.git ~/tmux-src/tmux-${{ matrix.tmux-version }}
           cd ~/tmux-src/tmux-${{ matrix.tmux-version }}
-          git checkout ${{ matrix.tmux-version }}
+          git checkout "$TMUX_REVISION"
           sh autogen.sh
-          ./configure --prefix=$HOME/tmux-builds/tmux-${{ matrix.tmux-version }} && make && make install
+          ./configure --prefix="$HOME/tmux-builds/tmux-${{ matrix.tmux-version }}" && make && make install
           export PATH=$HOME/tmux-builds/tmux-${{ matrix.tmux-version }}/bin:$PATH
           cd ~
           tmux -V
@@ -73,17 +91,15 @@ jobs:
           uv run python -V
 
       - name: Test with pytest
-        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
-          ls $HOME/tmux-builds/tmux-${{ matrix.tmux-version }}/bin
+          ls "$HOME/tmux-builds/tmux-${{ matrix.tmux-version }}/bin"
           tmux -V
-          uv run py.test --cov=./ --cov-append --cov-report=xml -n auto --verbose
-        env:
-          COV_CORE_SOURCE: .
-          COV_CORE_CONFIG: .coveragerc
-          COV_CORE_DATAFILE: .coverage.eager
+          uv run coverage erase
+          uv run coverage run -m pytest -n auto --verbose
+          uv run coverage combine
+          uv run coverage xml
       - uses: codecov/codecov-action@v7
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

AGENTS.md

@@ -55,11 +55,19 @@ be stated twice, the file listed above is the one that governs.
 tmux >= 3.2a 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 —
-list-shaped accessors are lenient by default; `Server.is_alive()` and
-`Server.raise_if_dead()` are the explicit, loud-failure primitives. See
-`src/libtmux/AGENTS.md` for the full contract and this package's
-logging conventions.
+raising when the underlying tmux list invocation fails for any reason.
+This does not generalize to every list-shaped accessor: `Server.windows`
+and `Server.panes` are lenient only for a not-yet-started daemon or a
+missing socket, and `Session.windows`, `Session.panes`, `Window.panes`,
+and `Window.search_panes` are not lenient at all — any tmux failure
+there raises. `Server.is_alive()` and `Server.raise_if_dead()` are the
+explicit, loud-failure primitives; a dead server reading as an empty
+live one through the lenient accessors never implies a `Session`/
+`Window` relation obtained beforehand will also read empty rather than
+raise. A parse failure (`exc.TmuxRecordParseError`) or a timeout
+(`exc.TmuxTimeout`) still propagates through the lenient ones — see
+`src/libtmux/AGENTS.md` for the full, precise contract and this
+package's logging conventions.
 
 ## References
 

CHANGES

@@ -45,6 +45,86 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### Completed command results (#758)
+
+{func}`~libtmux.common.run_command` returns captured output and exit status
+as a {class}`~libtmux.common.CommandResult`, including nonzero exits.
+
+#### Optional command timeouts (#758)
+
+{attr}`~libtmux.Server.timeout` bounds commands, listings and liveness
+checks. {meth}`~libtmux.Server.cmd` and {meth}`~libtmux.Server.wait_for`
+accept per-call overrides. Expiry raises {exc}`~libtmux.exc.TmuxTimeout`;
+a timed-out command may already have taken effect.
+
+#### Signal a waiting channel (#758)
+
+Use `signal=True` with {meth}`~libtmux.Server.wait_for` to wake waiters.
+The previous `set_flag` keyword remains a deprecated alias.
+
+#### Temporary servers and sessions (#758)
+
+{meth}`~libtmux.Server.owned` creates a private server scope;
+{meth}`~libtmux.Server.owned_session` creates a temporary session on an
+existing server. Both clean up their own resources on scope exit and
+report cleanup failures. See {doc}`topics/context_managers`.
+
+#### Decoded captured fields (#758)
+
+Pane and window properties expose dimensions and activity as numbers and
+booleans. Panes also expose position and {attr}`~libtmux.Pane.is_dead`;
+sessions expose {attr}`~libtmux.Session.attached_count`. Values come from
+the last capture; refresh the object for current state.
+
+#### Public local queries (#758)
+
+Import {class}`~libtmux.QueryList` from the package root. Required lookups
+and lookups with defaults preserve their distinct result types.
+
+### Fixes
+
+#### Invalid layouts are rejected before dispatch (#758)
+
+{meth}`~libtmux.Window.select_layout` rejects invalid or flag-like values
+before they can affect the server. Use a preset, an unambiguous preset
+prefix or a saved layout; use `None` to omit the layout instead of `""`.
+
+#### Leading-dash arguments remain literal (#758)
+
+Command text, names, messages and paths beginning with `-` are passed as
+values instead of being interpreted as tmux flags.
+
+#### Pane operations report tmux refusals (#758)
+
+{meth}`~libtmux.Pane.send_keys`, {meth}`~libtmux.Pane.capture_pane`,
+{meth}`~libtmux.Pane.enter`, {meth}`~libtmux.Pane.reset` and
+{meth}`~libtmux.Pane.split` raise {exc}`~libtmux.exc.LibTmuxException`
+when tmux refuses the operation.
+
+#### Listings preserve paths containing newlines (#758)
+
+Newlines in paths no longer break listings or
+{meth}`~libtmux.Server.new_session`. Unparseable records raise
+{exc}`~libtmux.exc.TmuxRecordParseError`, including in otherwise lenient
+server listings.
+
+#### Refresh clears fields that became empty (#758)
+
+Refreshing a pane, window, session or client clears fields tmux now
+reports empty instead of retaining their previous values.
+
+#### Additional tmux hooks decode correctly (#758)
+
+Reading hooks recognizes additional pane, window, client and command
+events supported by newer tmux releases.
+
+#### Server access accepts flags with a user (#758)
+
+{meth}`~libtmux.Server.server_access` accepts calls that combine access
+flags with a user instead of failing with an argument error.
+
 ### Documentation
 
 #### Cleaner `from_env` examples (#719)
@@ -57,6 +137,12 @@ environment-setup plumbing, so each example leads with the constructor call it
 demonstrates instead of the socket-path and `$TMUX` boilerplate needed to run
 it.
 
+#### Runnable automation examples (#758)
+
+Standalone scripts cover command results, temporary resources and
+polling for changes. Each uses its own server, leaving existing sessions
+alone. See {doc}`topics/examples`.
+
 ### Development
 
 #### CI actions updated to current majors
@@ -87,6 +173,11 @@ parsers, {meth}`Server.is_alive() <libtmux.Server.is_alive>`, and the Sphinx
 config carry scoped per-file ignores where catching everything is the intended
 contract.
 
+#### Benchmarks for library operations (#758)
+
+Run `just bench` to measure command dispatch, listings, captures and
+format decoding separately from the test suite.
+
 ## libtmux 0.62.0 (2026-07-12)
 
 libtmux 0.62.0 teaches libtmux objects to locate themselves and to resolve

README.md

@@ -116,6 +116,10 @@ Server(socket_path=/tmp/tmux-.../default)
 **Tip:** You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your
 current tmux server / session / window / pane.
 
+Prefer a script over a REPL? [`examples/`][examples] holds standalone,
+runnable programs — `python examples/quickstart.py` and no existing session
+required.
+
 [ptpython]: https://github.com/prompt-toolkit/ptpython
 [ipython]: https://ipython.org/
 [`tmuxp shell`]: https://tmuxp.git-pull.com/cli/shell/
@@ -125,8 +129,9 @@ current tmux server / session / window / pane.
 Every object has a `.cmd()` escape hatch that honors socket name and path:
 
 ```python
->>> server = Server(socket_name='libtmux_doctest')
->>> server.cmd('display-message', 'hello world')
+>>> from libtmux.server import Server
+>>> with Server(socket_name='libtmux_doctest') as server:
+...     server.cmd('display-message', 'hello world')
 <libtmux...>
 ```
 
@@ -314,7 +319,8 @@ def test_my_tmux_tool(session):
 [Workspace Setup](https://libtmux.git-pull.com/topics/workspace_setup/) ·
 [Automation Patterns](https://libtmux.git-pull.com/topics/automation_patterns/) ·
 [Context Managers](https://libtmux.git-pull.com/topics/context_managers/) ·
-[Options & Hooks](https://libtmux.git-pull.com/topics/options_and_hooks/)
+[Options & Hooks](https://libtmux.git-pull.com/topics/options_and_hooks/) ·
+[Examples](https://libtmux.git-pull.com/topics/examples/)
 
 **Reference:**
 [Docs][docs] ·
@@ -350,3 +356,4 @@ Contributions are welcome. Please open an issue or PR if you find a bug or want
 [tao]: https://leanpub.com/the-tao-of-tmux
 [tmuxp]: https://tmuxp.git-pull.com
 [tmux]: https://github.com/tmux/tmux
+[examples]: https://github.com/tmux-python/libtmux/tree/master/examples

benchmarks/bench_capture.py

@@ -0,0 +1,51 @@
+"""Benchmark: Pane.capture_pane() snapshot capture.
+
+Run with::
+
+    $ just bench
+
+Equivalent to::
+
+    $ uv run pytest benchmarks/ -o python_files='bench_*.py' --benchmark-only
+
+Not part of ``pytest``'s default run -- see bench_dispatch.py.
+"""
+
+from __future__ import annotations
+
+import pytest
+import pytest_benchmark.fixture
+
+from libtmux.pane import Pane
+from libtmux.session import Session
+from libtmux.test.retry import retry_until
+
+_SCROLLBACK_LINES = 200
+
+
+@pytest.fixture
+def pane_with_scrollback(session: Session) -> Pane:
+    """Return a pane with a full screen of numbered scrollback lines."""
+    window = session.new_window(window_name="bench-capture", window_shell="sh")
+    pane = window.active_pane
+    assert pane is not None
+    fill_command = (
+        f"i=0; while [ $i -lt {_SCROLLBACK_LINES} ]; do "
+        "echo line-$i; i=$((i+1)); done; echo capture-bench-done"
+    )
+    pane.send_keys(fill_command)
+    retry_until(
+        lambda: any(
+            line.rstrip(" ") == "capture-bench-done" for line in pane.capture_pane()
+        ),
+        raises=True,
+    )
+    return pane
+
+
+def test_bench_capture_pane(
+    benchmark: pytest_benchmark.fixture.BenchmarkFixture,
+    pane_with_scrollback: Pane,
+) -> None:
+    """capture_pane(): one list-panes read plus the visible screen text."""
+    benchmark(pane_with_scrollback.capture_pane)

benchmarks/bench_dispatch.py

@@ -0,0 +1,29 @@
+"""Benchmark: Server.cmd() dispatch, the primitive every wrapper method uses.
+
+Run with::
+
+    $ just bench
+
+Equivalent to::
+
+    $ uv run pytest benchmarks/ -o python_files='bench_*.py' --benchmark-only
+
+Not part of ``pytest``'s default run -- ``benchmarks/`` is not in
+``testpaths``, and performance work is a separate tier from the test-loop
+budgets in CONTRIBUTING.md, not part of them.
+"""
+
+from __future__ import annotations
+
+import pytest_benchmark.fixture
+
+from libtmux.session import Session
+
+
+def test_bench_command_dispatch(
+    benchmark: pytest_benchmark.fixture.BenchmarkFixture,
+    session: Session,
+) -> None:
+    """One round trip through Server.cmd(): fork, exec, read, parse exit."""
+    server = session.server
+    benchmark(server.cmd, "display-message", "-p", "#{session_name}")