Bound a tmux command that may never return

[tony]

Closes #732. Stacked on #734, which owns docs/topics/automation_patterns.md.

What this does

Server.wait_for() wraps tmux wait-for, a rendezvous with no clock on it. When whatever was going to signal the channel dies first — the command is killed, the shell exits, the window closes — the wait never ends, and there was no ceiling anywhere beneath it either: communicate() was called without one.

pane.send_keys(f"make; tmux wait-for -S {channel}")
server.wait_for(channel, timeout=60)

timeout is keyword-only and available on wait_for() and on cmd() for Server, Session, Window and Pane, forwarding to tmux_cmd. Every entry point defaults to None, which is unbounded, so no existing call changes behaviour.

Why the bound rides on the call

An instance-level default (Server(timeout=30)) was built and measured before this was chosen. It works, and it breaks blocking-by-design commands: on Server(timeout=1.0), server.cmd("attach-session", ...) is killed at ~1.06s. Mitigating it needs a hand-maintained deny-list that by construction cannot cover a command a user dispatches themselves.

The reason is that the analogy to HTTP clients does not hold. httpx gets away with a client-level timeout because requests are homogeneous; tmux's command set is not. display-message should take milliseconds and attach-session should take hours, so no single per-server number is correct, and it is wrong precisely where being wrong hurts most.

Per-call also stays well-defined under batching, which matters for the engine work: a timeout carried by the request has an unambiguous meaning in a batch, where an engine-level default or an ambient scope has to choose between bounding the batch and bounding each command in it.

Killing is not enough

communicate() does not kill the child when its timeout expires, and kill() alone leaves a zombie. Both are covered, because the difference is invisible to the obvious assertion — os.kill(pid, 0) succeeds against a zombie. The test pins returncode == -SIGKILL and that os.waitpid raises ChildProcessError.

TmuxCommandTimeout carries the killed command line and the bound it exceeded. It subclasses WaitTimeout, so handlers that already catch libtmux's timeout keep working, and it deliberately does not subclass subprocess.TimeoutExpired — the stdlib type never crosses the library boundary, including by chaining.

Two tmux behaviours documented

Both were measured against tmux 3.7b while building this, and both are properties of the rendezvous rather than of this change.

A wait that times out is abandoned rather than withdrawn. tmux only remembers a signal when nothing is waiting for the channel (cmd-wait-for.c#L148), so the next signal is spent waking the abandoned wait — one signal, after which the channel behaves normally. A fresh channel name per rendezvous avoids it.

A returning wait is also weaker evidence than it looks. tmux releases every waiter when the server shuts down (cmd-wait-for.c#L244), and does so exactly as if the channel had been signalled, so a pane that died and a command that finished are indistinguishable from the wait alone. When the outcome matters, have the command report its own exit status.

Verification

ruff check, ruff format, mypy (69 files), py.test --reruns 0 (1468 passed, 1 skipped) and just build-docs all clean.

[codecov]

Codecov Report

❌ Patch coverage is 77.27273% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.56%. Comparing base (8d35933) to head (2a58783).

Files with missing lines	Patch %	Lines
src/libtmux/common.py	75.00%	2 Missing and 1 partial ⚠️
src/libtmux/exc.py	60.00%	2 Missing ⚠️

Additional details and impacted files

@@                        Coverage Diff                        @@
##           docs/lift-automation-patterns     #735      +/-   ##
=================================================================
+ Coverage                          52.40%   52.56%   +0.16%     
=================================================================
  Files                                 26       26              
  Lines                               3729     3744      +15     
  Branches                             747      749       +2     
=================================================================
+ Hits                                1954     1968      +14     
  Misses                              1472     1472              
- Partials                             303      304       +1     

☔ 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

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

Found 1 issue, fixed in d172f7c:

1. "no orphan survives" overstated what is reaped. The kill covers the tmux client libtmux spawned; the pane's foreground process and the tmux server keep running, so a caller reading that could believe a timeout stopped the work.

https://github.com/tmux-python/libtmux/blob/39e87af1d0a4c8b2e5f7a9c1b3d6e8f0a2c4d5e6/src/libtmux/exc.py#L361-L365

Both TmuxCommandTimeout and tmux_cmd's Raises section now say the call leaves no child of its own behind, and that work the command started is unaffected.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

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

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

Found 1 issue, fixed in 9378bed:

1. The previous round's correction to what a timeout actually kills landed in exc.py and common.py but not in the four public cmd() docstrings or CHANGES, which still said the timeout kills "tmux" and that "an expiry leaves nothing behind".

https://github.com/tmux-python/libtmux/blob/e4e1f920d3b8a5c7f9e1d2a4b6c8e0f2a4c6d8e0/CHANGES#L64-L68

All five now say the same thing: the kill covers the tmux client libtmux spawned, and work the command started keeps running.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}