Add experimental typed chain API for tmux command sequences

[tony]

Summary

• Add libtmux._experimental.chain, an experimental typed API for composing an ordered set of tmux commands that runs as one native tmux ... \; ... invocation instead of one subprocess per command. Promotes the converged design from the Explore typed chainable tmux command APIs #684 research survey into real, documented, typed modules. Refs Typed command descriptors for native tmux command chains #683.
• Add five layers over one substrate: an argv intermediate representation, a target-safe deferred query/expression layer, an async facade, a live-tmux connection layer (sync + async), and a chainability contract.
• Add a live-tmux connection layer so an expression resolves and dispatches against a real Session in one invocation — sync (SessionPlanExecutor) and async (AsyncSessionPlanExecutor, via asyncio.to_thread).
• Add pytest-asyncio, configured the way pytest-asyncio itself and sibling projects do (asyncio_mode = "auto", asyncio_default_fixture_loop_scope = "function").
• Document everything under a new docs/experiment/ tree (mirroring docs/internals/) with runnable doctest examples; the package is explicitly outside the versioning policy and not re-exported from top-level libtmux.

Changes by area

Experimental package — src/libtmux/_experimental/chain/

Module	Role
ir.py	Immutable argv IR: CommandCall, CommandSequence (argv/argvs/>>/run), CommandSpec, runner protocols, ;-escaping
plan.py	Typed targets, command values, PaneRef rows with bound .cmd/.window, lazy PaneQuery with .map (data-only rows) and .commands (one-or-more commands per row), CommandPlan (pure to_sequence(snapshot) + one-dispatch run)
_async.py	Async facade mirroring the query/dispatch API; reuses the sync compile path so one expression still yields one CommandSequence
_connection.py	Live-tmux bridge: snapshot_from_session, SessionPlanExecutor, AsyncSessionPlanExecutor
batch.py	Chainability contract: COMMAND_SPECS / is_chainable + DeferredCommandResult / ChainabilityError

Tooling — pyproject.toml

• Add pytest-asyncio to the dev and testing groups; set asyncio_mode = "auto" and asyncio_default_fixture_loop_scope = "function".

Plugin doctests — src/libtmux/pytest_plugin.py, tests/test_pytest_plugin.py

• Pass -p no:asyncio to the plugin's pytester-based inner pytest runs. Those inner sessions are synchronous; disabling the now-installed async plugin there keeps them from emitting pytest-asyncio's loop-scope deprecation. Edits live in hidden doctest blocks, so the rendered plugin docs are unchanged.

Docs — docs/experiment/, docs/index.md, docs/project/public-api.md

• Add an experiment landing page plus a per-module autodoc page; wire experiment/index into the toctree; mark libtmux._experimental.* not-public.

Design decisions

• One substrate, layered API: everything compiles down to ir.CommandSequence, so the IR, expressions, async, and connection layers all share one dispatch path and one set of guarantees.
• Mutation-only sequences: a semicolon sequence returns one merged result, so structured-output commands (capture-pane, show-option) stay individual typed calls rather than being forced into a chain.
• Async as a thin facade: _async reuses the sync to_sequence, so construction stays synchronous and one expression still compiles to exactly one invocation; AsyncSessionPlanExecutor offloads the sync core via asyncio.to_thread.
• Typed targets: PaneRef rows carry PaneTarget / WindowTarget / SessionTarget, so a row-bound command cannot mis-target.
• Query verbs name their output: PaneQuery keeps .map for data-only row transforms and .commands(mapper) for the deferred, one-or-more-commands-per-row plan. The verb names what the call yields — a CommandPlan — and pairs with .map so the data path and the command path read distinctly at the call site (panes().filter(active=True).commands(lambda p: p.cmd.send_keys(...))).
• Module names follow common Python conventions: ir for the intermediate representation (mypy mypyc/ir, polars plans/ir), plan for the deferred form (datafusion LogicalPlan), batch for fold-into-one-dispatch (dask), and _connection + *Executor for the live bridge (django db/backends, dagster Executor.execute(plan), stdlib concurrent.futures.Executor) rather than adapter — which conventionally means interface/value conversion.
• -p no:asyncio over a warnings filter: inner pytester sessions are configured to not load the async plugin (matching how the ecosystem scopes inner runs) instead of muting a deprecation globally.

Test plan

• uv run ruff check . --fix --show-fixes — clean
• uv run ruff format . — clean
• uv run mypy — clean (strict, over src + tests)
• uvx ty check src/libtmux/_experimental tests/_experimental — clean
• uv run pytest --reruns 0 — passes (incl. new doctests, async tests, and live-tmux integration)
• just build-docs — builds (experiment toctree + autodoc resolve)

Refs #683. Builds on the API survey in #684.

[codecov]

Codecov Report

❌ Patch coverage is 94.03846% with 31 lines in your changes missing coverage. Please review.
✅ Project coverage is 56.83%. Comparing base (dae83de) to head (6021f9c).

Files with missing lines	Patch %	Lines
src/libtmux/_experimental/chain/plan.py	89.13%	13 Missing and 7 partials ⚠️
src/libtmux/_experimental/chain/_async.py	90.56%	5 Missing ⚠️
src/libtmux/_experimental/chain/ir.py	92.85%	2 Missing and 2 partials ⚠️
src/libtmux/_experimental/chain/_connection.py	91.30%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #685      +/-   ##
==========================================
+ Coverage   51.29%   56.83%   +5.54%     
==========================================
  Files          25       36      +11     
  Lines        3488     4008     +520     
  Branches      686      716      +30     
==========================================
+ Hits         1789     2278     +489     
- Misses       1404     1425      +21     
- Partials      295      305      +10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code