Server.wait_for() has no timeout, so a pane that never signals hangs forever #732

Filed against tmux-python/libtmux v0.62.0, tmux 3.7b.

What happens

Server.wait_for() blocks until the channel is signalled, with no way to bound the wait. If the pane that was going to signal dies first — the command was killed, the shell exited, the window was closed — the call blocks forever.

There is no ceiling anywhere below it either. tmux_cmd calls communicate() with no timeout:

src/libtmux/common.py#L339

So the hang is process-wide and not interruptible except by signal.

wait-for blocking indefinitely is correct tmux behaviour, not a tmux bug — the command is a rendezvous and has no timeout flag:

cmd-wait-for.c#L34-L38

.args = { "LSU", 1, 1, NULL },
.usage = "[-L|-S|-U] channel",

The gap is that libtmux exposes the rendezvous without exposing a way to give up on it.

Why it matters now

wait-for is the exact, poll-free way to wait for a command a caller authored: the command signals a channel when it finishes and the caller blocks on that channel. Measured on tmux 3.7b — a pane running sleep 1.5; tmux wait-for -S <ch> released the waiter after 1.506 s, with zero polling and no round trips. A signal sent before the waiter starts is remembered, so there is no lost-wakeup race: signalling first and then waiting returned in 3 ms.

That makes it the right thing to teach in documentation for "run a command, then read its output", replacing the time.sleep() guesses currently in the topic pages. The blocker is that every such example either carries subprocess timeout ceremony or teaches a hang.

Concretely, the shape wanted in a doc example is:

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

and today the second line cannot be written.

Reproduction

A pane that never signals, because the keys were typed but never entered:

pane.send_keys(f"echo READY; tmux wait-for -S {channel}", enter=False)
server.wait_for(channel)   # blocks forever

The bound is achievable one level down, which is why this is a missing parameter rather than a missing capability:

subprocess.run(["tmux", "-S", socket_path, "wait-for", channel], timeout=1.0)
# raises subprocess.TimeoutExpired after 1.00s

What a fix needs

1. Add timeout: float | None = None to Server.wait_for(). A parameter on an existing method rather than new API surface. On expiry, kill the child and raise — libtmux.exc.WaitTimeout already exists and is the natural type, which keeps this consistent with retry_until.
2. Decide where the timeout is enforced. Either add timeout= to tmux_cmd — a load-bearing path used by every command in the library, so a wider blast radius — or have wait_for bypass it with a direct timeout-bounded subprocess call for this one command. The second is narrower and reversible.
3. A killed child must not leave a stray wait-for process holding the channel. Terminate it on expiry and verify no process survives the raise.
4. Document that a signal already sent is remembered, so ordering between signaller and waiter does not matter. That property is what makes the pattern race-free and it is not obvious from the tmux manual.

Default stays None, so existing callers are unaffected.

Related

Server.wait_for() has shipped since it was added and currently has no callers anywhere in the library, its tests, or its documentation. The waiting problem it solves is instead worked around with time.sleep() in the topic pages, which is the discoverability half of the same gap.

Delivery contract from the rmux helper audit

Reuse the existing missing-timeout report. Route Server.wait_for(timeout=...) through the selected command deadline mechanism, retaining its existing default and return behavior. A narrow implementation can ship before the full async/ops roadmap if it honors the same cleanup and exception contract.

Use a unique channel per operation and explicit server addressing. A remembered signal can avoid a lost wakeup, but channel reuse can consume stale state. A timeout is not proof that a producer did not execute; it means the waiting client did not observe completion within its bound.

Acceptance: no signal, signal before waiter, signal after waiter registration, producer death, cancellation, and an ordinary command after timeout. Verify cleanup of the owned waiting client. Current tmux wait-channel code is source evidence, not a reason to require new tmux behavior.

Delivery links: #689, #673. Track this work under #629 in the libtmux project.

Independent PR delivery

Follow the minimal slice and shared compatibility contract in #629. Build and test against master with every other unmerged feature branch absent. Cross-links above identify semantic contracts and future consumers; use a private adapter where needed instead of introducing a merge dependency. Preserve existing facade behavior and the inspected engine-ops interfaces. Leave deferred acceptance criteria open after an MVP lands.