mcp(fix[wait_for]): Release an abandoned waiter

why: A killed wait-for client stays queued on its channel in tmux, so
the next signal was spent on the dead client and a later wait on that
channel timed out. libtmux's Server.wait_for already releases the
waiter by signalling it while alive.

what:
- Add release_argv to _run_tmux_bounded: expiry and cancellation signal
  the channel, wait for the client to exit, and kill it only if it does
  not
- Pass it from wait_for_channel and run_command
- Test signal-then-wait after a timeout and after a cancel; both fail
  when release_argv is not passed

Author: tony

CHANGES

@@ -8,6 +8,13 @@ _Notes on upcoming releases will be added here_
 
 ### Fixes
 
+**A timed-out or cancelled wait no longer swallows the channel's next signal**
+
+`wait_for_channel` and `run_command` used to kill the waiting tmux client when
+they gave up, which left it queued on the channel and spent the next signal on
+it. They now release the waiter first, so signalling the channel and waiting
+again succeeds.
+
 **`send_keys_batch`, `paste_text` and the buffer tools use libtmux's safe commands**
 
 Text that starts with `-` or ends with `;` reaches the pane verbatim in a timed

src/libtmux_mcp/_tmux_proc.py

@@ -31,6 +31,10 @@
 #: loop's child watcher reaps the pid whether or not we wait.
 _TMUX_REAP_SECONDS = 0.5
 
+#: Bound on each half of a waiter release: the ``wait-for -S`` that frees
+#: the channel, then the waiter's own exit.
+_RELEASE_GRACE_SECONDS = 1.0
+
 
 async def _kill_and_reap(
     proc: asyncio.subprocess.Process, task: asyncio.Future[t.Any]
@@ -62,8 +66,63 @@ async def _kill_and_reap(
         await asyncio.wait_for(proc.wait(), timeout=_TMUX_REAP_SECONDS)
 
 
+async def _release_waiter(
+    proc: asyncio.subprocess.Process,
+    task: asyncio.Future[t.Any],
+    release_argv: list[str],
+) -> None:
+    """End a ``wait-for`` client without leaving a ghost waiter.
+
+    tmux keeps a killed waiter queued on its channel and only remembers a
+    signal while nobody waits, so the channel's next signal would be spent
+    on the dead client. Signalling while the client is still alive makes
+    tmux dequeue it, leaving the channel clean. The client is killed only
+    when it does not exit, which is when the server is not answering.
+    Mirrors ``libtmux.common._release_waiter``.
+
+    Parameters
+    ----------
+    proc : asyncio.subprocess.Process
+        The ``tmux wait-for`` client.
+    task : asyncio.Future
+        The in-flight ``proc.communicate()`` future.
+    release_argv : list of str
+        Full command line that signals the waiter's channel.
+    """
+    with contextlib.suppress(OSError, TimeoutError):
+        releaser = await asyncio.create_subprocess_exec(
+            *release_argv,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        try:
+            await asyncio.wait_for(releaser.wait(), timeout=_RELEASE_GRACE_SECONDS)
+        except BaseException:
+            with contextlib.suppress(ProcessLookupError):
+                releaser.kill()
+            raise
+    with contextlib.suppress(TimeoutError):
+        await asyncio.wait_for(asyncio.shield(task), timeout=_RELEASE_GRACE_SECONDS)
+    await _kill_and_reap(proc, task)
+
+
+async def _end_child(
+    proc: asyncio.subprocess.Process,
+    task: asyncio.Future[t.Any],
+    release_argv: list[str] | None,
+) -> None:
+    """Release a ``wait-for`` waiter, or kill any other child."""
+    if release_argv is None:
+        await _kill_and_reap(proc, task)
+    else:
+        await _release_waiter(proc, task, release_argv)
+
+
 async def _run_tmux_bounded(
-    argv: list[str], *, timeout: float
+    argv: list[str],
+    *,
+    timeout: float,
+    release_argv: list[str] | None = None,
 ) -> tuple[int, bytes, bytes]:
     """Run one tmux argv under a hard bound, killing it on cancellation.
 
@@ -75,6 +134,10 @@ async def _run_tmux_bounded(
     timeout : float
         Wall-clock bound in seconds. On expiry the child is killed and
         reaped before ``TimeoutError`` is raised.
+    release_argv : list of str, optional
+        For a ``wait-for`` client: the command that signals its channel.
+        When given, expiry and cancellation release the waiter through
+        :func:`_release_waiter` instead of killing it outright.
 
     Returns
     -------
@@ -105,7 +168,7 @@ async def _run_tmux_bounded(
     try:
         done, _pending = await asyncio.wait({task}, timeout=timeout)
         if not done:
-            await _kill_and_reap(proc, task)
+            await _end_child(proc, task, release_argv)
             raise TimeoutError
         stdout, stderr = task.result()
     except asyncio.CancelledError:
@@ -115,7 +178,7 @@ async def _run_tmux_bounded(
         # above just as often as on ``task.result()``, so the guard
         # must span both — otherwise a cancel while waiting orphans the
         # child.
-        await _kill_and_reap(proc, task)
+        await _end_child(proc, task, release_argv)
         raise
     assert proc.returncode is not None
     return proc.returncode, stdout, stderr

src/libtmux_mcp/tools/pane_tools/io.py

@@ -428,7 +428,9 @@ async def run_command(
     stderr_bytes = b""
     try:
         returncode, _stdout, stderr_bytes = await _run_tmux_bounded(
-            wait_argv, timeout=effective_timeout
+            wait_argv,
+            timeout=effective_timeout,
+            release_argv=_tmux_argv(server, "wait-for", "-S", channel),
         )
     except TimeoutError:
         timed_out = True

src/libtmux_mcp/tools/wait_for_tools.py

@@ -204,6 +204,7 @@ async def wait_for_channel(
     cname = _validate_channel_name(channel)
     effective_timeout = min(timeout, _wait_ceiling_seconds())
     argv = _tmux_argv(server, "wait-for", cname)
+    release_argv = _tmux_argv(server, "wait-for", "-S", cname)
     # FastMCP direct-awaits async tools on its event loop, and ``tmux
     # wait-for`` blocks for the full timeout, so the child must not run
     # on the loop. It must not run on a worker thread either:
@@ -215,7 +216,7 @@ async def wait_for_channel(
     # :func:`~libtmux_mcp.tools.pane_tools.wait.wait_for_text` uses.
     try:
         returncode, _stdout, stderr = await _run_tmux_bounded(
-            argv, timeout=effective_timeout
+            argv, timeout=effective_timeout, release_argv=release_argv
         )
     except TimeoutError as e:
         msg = (

tests/test_wait_for_tools.py

@@ -458,11 +458,9 @@ def test_wait_for_channel_kills_tmux_child_on_cancel(mcp_server: Server) -> None
     child alive another 13 s; through a real agent TUI with the ceiling
     raised to 120 s and a 90 s timeout, ~61 s past the user's Esc.
 
-    Note the harm is the live process itself, not a stolen signal —
-    tmux keeps the server-side waiter registered even after the client
-    dies (verified against ``tmux wait-for``), so ``wait-for -S`` is
-    swallowed either way. Only the process is observable, so that is
-    what this asserts.
+    The channel itself is checked by
+    ``test_wait_for_channel_leaves_channel_reusable``; this one asserts the
+    process is gone.
     """
     channel = "wf_cancel_reap_test"
     socket_name = mcp_server.socket_name
@@ -502,3 +500,47 @@ async def _drive() -> list[int]:
         f"cancelled wait_for_channel orphaned tmux child(ren) {survivors}; "
         "the child outlives the cancellation for the rest of its timeout"
     )
+
+
+@pytest.mark.parametrize("how", ["timeout", "cancel"])
+@pytest.mark.usefixtures("mcp_session")
+def test_wait_for_channel_leaves_channel_reusable(mcp_server: Server, how: str) -> None:
+    """An abandoned wait must not leave a ghost waiter on the channel.
+
+    tmux remembers a signal only while nobody waits, and a killed client
+    stays queued as a waiter, so the next signal was spent on the dead
+    client: a later wait on the same channel then timed out although the
+    channel had been signalled first. Releasing the waiter by signalling
+    it while alive dequeues it, so signal-then-wait returns at once.
+    """
+    channel = f"wf_ghost_{how}"
+    socket_name = mcp_server.socket_name
+    assert socket_name is not None
+
+    async def _abandon() -> None:
+        if how == "timeout":
+            with pytest.raises(ToolError, match="timeout"):
+                await wait_for_channel(
+                    channel=channel, timeout=0.3, socket_name=socket_name
+                )
+            return
+        task = asyncio.create_task(
+            wait_for_channel(channel=channel, timeout=8.0, socket_name=socket_name)
+        )
+        await asyncio.sleep(0.5)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+    async def _drive() -> str:
+        await _abandon()
+        await signal_channel(channel=channel, socket_name=socket_name)
+        return await wait_for_channel(
+            channel=channel, timeout=2.0, socket_name=socket_name
+        )
+
+    started = time.monotonic()
+    result = asyncio.run(_drive())
+
+    assert "was signalled" in result
+    assert time.monotonic() - started < 1.9