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/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