docs(CHANGES): Bounded tmux commands

what:
- Record the `timeout` parameter on `wait_for` and the `cmd` chain, and
  the `TmuxCommandTimeout` it raises, under `What's new`.

Author: tony

CHANGES

@@ -45,6 +45,29 @@ $ 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
+
+#### Bounded tmux commands (#735)
+
+{meth}`Server.wait_for() <libtmux.Server.wait_for>` takes a `timeout` in seconds.
+A tmux channel is a rendezvous with no clock on it: when the pane that was going
+to signal is killed, exits early, or has its window closed, the waiter blocks for
+the life of the process. `server.wait_for(channel, timeout=60)` turns that into
+a {exc}`~libtmux.exc.TmuxCommandTimeout` you can catch. It subclasses
+{exc}`~libtmux.exc.WaitTimeout`, so existing handlers keep working, and it
+carries the command that was killed and the bound it exceeded.
+
+The bound is available to any tmux command, not just `wait-for`.
+{meth}`Server.cmd() <libtmux.Server.cmd>`,
+{meth}`Session.cmd() <libtmux.Session.cmd>`,
+{meth}`Window.cmd() <libtmux.Window.cmd>`,
+{meth}`Pane.cmd() <libtmux.Pane.cmd>`, and
+{class}`~libtmux.common.tmux_cmd` beneath them all accept `timeout`, and all
+kill and reap the tmux process before raising, so an expiry leaves nothing
+behind. The default, `None`, waits as long as tmux takes.
+
+See {ref}`automation-patterns` for waiting on a channel instead of polling.
+
 ### Documentation
 
 #### Automation patterns waits for tmux instead of guessing (#734)

docs/topics/automation_patterns.md

@@ -126,8 +126,9 @@ block on that channel with {meth}`~libtmux.Server.wait_for`. tmux remembers a si
 sent before the waiter starts, so this has no lost-wakeup race. It also avoids
 confusing the shell's echoed command with the command's output.
 
-{meth}`~libtmux.Server.wait_for` has no timeout. Make sure every expected exit path
-reaches `tmux wait-for -S` so a failed command cannot leave your script blocked.
+{meth}`~libtmux.Server.wait_for` waits indefinitely unless you give it a `timeout`.
+Either make sure every expected exit path reaches `tmux wait-for -S`, or bound the
+wait, so a failed command cannot leave your script blocked.
 Channels are server-wide, so give each in-flight command a distinct channel name.
 
 ```python