Fix wait_for_text's blind spot and bound every wait

[tony]

Summary

• Fix a blind spot that made the tool useless for its own headline case. wait_for_text anchored one row below where the cursor sat when the call began — and on a quiescent pane that is exactly where the next line of output lands, because the cursor sits at the end of the prompt. A daemon printing a single ready line could not be matched at all: the wait burned its whole budget and then reported that the pane had been silent. The anchor now lands on that row, and the row's pre-existing content is suppressed by value instead of by index, so carriage-return spinners and single-line status updates become matchable too.
• Bound every wait, and let the caller see the bound. LIBTMUX_MCP_WAIT_MAX_SECONDS (30 s default, clamped to [1, 120]) caps wait_for_text, wait_for_channel and run_command. An over-large timeout is clamped rather than rejected, and the result reports what was actually enforced — the agent learns the policy from the result instead of from a failed call.
• Replace pattern: str with patterns: list[str] | None, and add stop. patterns=null waits for any new output, subsuming the removed wait_for_content_change. A stop list ends the wait in milliseconds on a known failure marker instead of burning the budget.
• Make the result explain itself. One outcome enum replaces a scatter of booleans, alongside which entry fired, whether anything new was written, whether the match was text already on screen at entry, and a byte-bounded tail. A timeout now distinguishes "the command never ran" from "output arrived and did not match" from "a pager owned the pane".
• Stop waits hanging, leaking, or reporting a result they did not get. A wedged tmux could hang the process and Ctrl-C indefinitely; a cancelled call left its tmux child running for the rest of its timeout; a retried or batched wait could exceed its own ceiling; and wait_for_channel reported success when the tmux server shut down without ever signalling, because tmux wait-for exits 0 for both.
• Make failures name what failed. A missing dependency, an unresolvable pane target, and the client behind a bad argument were all reported without naming the thing at fault.

Changes by area

src/libtmux_mcp/tools/pane_tools/wait.py

The core. Entry-row anchoring with content-based suppression of pre-existing text, patterns/stop handling, the alternate-screen guard, and every tmux call spawned as a deadline-bounded async subprocess rather than reaching tmux through a worker thread.

src/libtmux_mcp/_wait_policy.py, server.py

The ceiling policy, resolved from the environment and injected at tool-registration time, mirroring the existing history-default pattern. server.py also fails at startup rather than silently dropping the is_caller agent-context instructions when the MCP instruction budget is tight, while still degrading gracefully for pathological runtime values.

_utils.py, middleware.py, batch_tools.py, wait_for_tools.py

The self-bounded tag and its enforcement: excluded from readonly retry, rejected per-operation by every batch wrapper, and applied to wait_for_channel and run_command as well as wait_for_text. wait_for_channel gains the liveness re-probe that distinguishes a signal from a server that went away.

models.py, state.py

WaitForTextResult reshaped around the outcome enum; ContentChangeResult removed. _PaneState gains alternate_on, tolerant of older tmux that omits the field.

prompts/recipes.py, docs

The interrupt_gracefully recipe no longer treats a ^C echo as evidence that a program survived SIGINT — the terminal echoes it on delivery either way, so the marker fired on the success path and the recipe's next step is escalation. It now brackets the interrupt with get_pane_info and trusts pane_current_command. A new Waiting topic covers which wait to reach for, how the "is this new" predicate works, and what a wrong pattern costs.

Design decisions

• Thread-free, not just timeout-bounded. A private ThreadPoolExecutor with shutdown(wait=False) was considered and rejected: concurrent.futures.thread._python_exit joins every pool worker untimed regardless, so no thread-based arrangement survives a wedged tmux at interpreter exit. Only owning a killable subprocess does.
• Kill-then-cancel-then-bounded-reap. The textbook wait_for(communicate()) then kill() then await wait() deadlocks when a wedged tmux's grandchild still holds the stdout pipe. The reader task is torn down first and the final reap is time-boxed; the loop's child watcher reaps the pid regardless.
• Suppress the entry row by content, not by index. Skipping the row by index is what created the blind spot. Filtering it by the text that was on it at entry keeps stale paint from matching while letting genuinely new text on the same row through. Verified in both directions: a broad pattern still does not match the shell prompt that was already there.
• A stale match does not end the wait. matched_at_entry is known before the poll loop starts, so returning immediately looks like free latency. It would break the commonest agent loop — run, wait for marker, re-run, wait for the same marker — so the wait holds out for a fresh occurrence and says so in the result.
• The ceiling bounds the agent's turn, not the transport. The original rationale was that a long wait stalls the shared MCP connection. It does not: the wait tools await throughout and FastMCP serves the connection concurrently — measured, a tool awaiting 6 s served 58 interleaved calls at a 3.4 ms median, against exactly one at 6014 ms for a control that blocked the event loop. The ceiling is unchanged and still correct, but for the honest reason: MCP gives an agent no way to abandon a call mid-flight.
• outcome as one enum, not three booleans. The output schema is re-sent on every request, so a field no agent branches on is a permanent token tax.
• Background tasks were evaluated and rejected. Both the SEP-1686 shape and the SEP-2663 fastmcp-tasks alpha were trialled against this tool. Neither is reachable — no shipping client negotiates the capability — and both drop the numeric progress this tool emits. Recorded in the Waiting topic so it is not re-litigated from intuition.

Verification

No caller pattern reaches a tmux format string — tmux treats # and } structurally, so an ordinary regex quantifier would corrupt field parsing:

rg -n 'C/|display-message.*\{pattern' src/libtmux_mcp/tools/pane_tools/wait.py

Nothing on the wait path reaches tmux through a thread:

rg -n 'to_thread\(|subprocess\.run\(' src/libtmux_mcp/tools/pane_tools/wait.py

The removed tool and its result model are gone as symbols:

rg -n '^\s*(def|class)\s+(wait_for_content_change|ContentChangeResult)\b' src/ docs -g '!_build'

Test plan

• uv run ruff format --check ., uv run ruff check ., uv run mypy clean
• uv run pytest --reruns 0 green with flake-masking reruns disabled
• just build-docs succeeds; removing the wait-for-content-change page leaves no broken refs
• CI green across the full tmux matrix — 3.2a, 3.3a, 3.4, 3.5, 3.6 and master — so the grid arithmetic is not validated against one tmux only
• test_wait_for_text_sees_the_entry_cursor_row — a bare line, an unterminated prompt, a trailing-line case and a carriage-return rewrite all match on the entry row; two controls pin the other direction
• test_wait_for_text_does_not_match_the_prompt_on_the_entry_row — the falsifier: a broad pattern must not self-match the prompt that was already on the row
• test_wait_for_text_waits_for_a_fresh_occurrence — a stale match on screen does not short-circuit the wait
• test_wait_path_uses_no_worker_threads — the wait path spawns no threads
• test_wait_tools_do_not_block_event_loop — the loop survives a genuinely wedged tmux; mutation-tested to fail if a blocking spawn returns
• test_wait_for_text_bounds_every_tmux_call — every spawned tmux call is deadline-bounded
• test_wait_for_channel_detects_a_vanished_server — a clean kill-server and a SIGTERM are both reported as errors, with a live-server control that must still succeed
• test_wait_resolver_matches_the_canonical_resolver — the wait's private resolver agrees with _utils._resolve_pane on precedence and on the exception a miss raises
• A wedged tmux lets the process exit promptly, and under SIGINT, where the prior code hung indefinitely
• Native pane resolution verified equivalent to libtmux across all wait_for_text targeting cases, including the linked-window MultipleObjectsReturned trap
• Verified end to end over a real MCP stdio session and through a real CLI agent, with the mutation asserted independently against the target tmux socket rather than trusting the agent's report

[tony]

Code review

Found 6 issues (1 confirmed by repro):

1. Cancelling a wait orphans the in-flight tmux child. The cancellation lands at await asyncio.wait({task}, ...), which does not cancel task; the except asyncio.CancelledError only guards the synchronous task.result() below it, so _kill_and_reap never runs. I reproduced it against a wedged tmux: CancelledError propagated in 0.00s but ORPHANED fake-tmux alive: 1, and the leaked child re-introduces the interpreter-shutdown hang this PR set out to fix. The window is largest under a wedged tmux — exactly the target scenario. Wrap the await asyncio.wait(...) in try/except CancelledError (or try/finally) that reaps. (bug)

libtmux-mcp/src/libtmux_mcp/tools/pane_tools/wait.py

Lines 238 to 252 in 6bd82ce

	task = asyncio.ensure_future(proc.communicate())
	done, _pending = await asyncio.wait({task}, timeout=budget)
	if not done:
	await _kill_and_reap(proc, task)
	msg = (
	f"tmux {args[0]} did not return within "
	f"{budget:.2f}s; the tmux server is unresponsive"
	)
	raise ExpectedToolError(msg)
	try:
	stdout, stderr = task.result()
	except asyncio.CancelledError:
	# The whole call was cancelled (MCP client hung up). Tear the
	# child down before letting the cancellation through, or tmux
	# is orphaned.

2. interrupt_gracefully passes stop=["^C", ...] with regex=True. As a regex, ^C is start-anchored C: re.search("^C", "^C") is False (it never matches the literal ^C echo it targets) and re.search("^C", "Compiling") is True (it false-fires outcome="stopped" on any line starting with C). Escape it (\^C) or drop regex=True for that marker. (bug)

libtmux-mcp/src/libtmux_mcp/prompts/recipes.py

Lines 166 to 171 in 6bd82ce

	1. `send_keys(pane_id="{pane_id}", keys="C-c", literal=False,
	enter=False)` — tmux interprets `C-c` as SIGINT.
	2. `wait_for_text(pane_id="{pane_id}", patterns=["\\$ ", "\\# ", "\\% "],
	stop=["^C", "Interrupt"], regex=True, timeout=5.0)` — waits for a
	common shell prompt glyph. Adjust the patterns to match the user's
	shell theme. The `stop` list exits early on the markers many

3. build_dev_workspace step 5 tells the agent wait_for_text(patterns=null) confirms "a vim splash screen," but this PR's alternate-screen guard suppresses matching while alternate_on and returns outcome="alternate_screen", found=False. vim uses the alternate screen, so the stated guarantee is now false. (bug)

libtmux-mcp/src/libtmux_mcp/prompts/recipes.py

Lines 138 to 143 in 6bd82ce

	5. Optionally confirm each program drew its UI via
	`wait_for_text(pane_id="%A", patterns=null, timeout=3.0)`
	(and similarly for `%C`). Omitting `patterns` makes this a
	"did anything new get printed?" check — it works whether the
	pane shows a prompt glyph, a vim splash screen, or a log tail,
	so no shell-specific regex is needed.

4. The wait_for_text docstring tells the agent the result reports suppressed_stale_match, but no such field exists — the shipped field is matched_at_entry. (stale doc on a changed line)

libtmux-mcp/src/libtmux_mcp/tools/pane_tools/wait.py

Lines 517 to 520 in 6bd82ce

	below the cursor at entry — only rows written after the call began
	count. If a pattern was already on screen the result says so via
	``suppressed_stale_match``.

5. The same docstring states "Alternate screen / pagers are not handled ... this tool does not detect it," which contradicts the alternate-screen handling this PR adds. (stale doc on a changed line)

libtmux-mcp/src/libtmux_mcp/tools/pane_tools/wait.py

Lines 588 to 592 in 6bd82ce

	hang interpreter shutdown.
	**Alternate screen / pagers are not handled.** Inside ``less``,
	``capture-pane`` returns the pager's painted rows, so a wait for
	text the pager has drawn matches on paint. That is a false

6. The poll-loop comment still says the tmux reads are "blocking subprocess calls" pushed to "the default executor," but this PR makes the path a native async subprocess with no executor and no thread — the comment describes the code it replaced. (stale comment on a changed line)

libtmux-mcp/src/libtmux_mcp/tools/pane_tools/wait.py

Lines 712 to 716 in 6bd82ce

	# FastMCP direct-awaits async tools on the main event loop
	# and the tmux reads are blocking subprocess calls. Push
	# them to the default executor so concurrent tool calls are
	# not starved during long waits.
	state = await _bounded_pane_state(server, target, deadline=deadline)

🤖 Generated with Claude Code

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 89.71963% with 33 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.13%. Comparing base (d52c03c) to head (fbdbd74).

Files with missing lines	Patch %	Lines
src/libtmux_mcp/tools/pane_tools/wait.py	85.43%	14 Missing and 8 partials ⚠️
src/libtmux_mcp/tools/pane_tools/io.py	50.00%	4 Missing and 1 partial ⚠️
src/libtmux_mcp/server.py	57.14%	2 Missing and 1 partial ⚠️
src/libtmux_mcp/tools/wait_for_tools.py	90.00%	2 Missing ⚠️
src/libtmux_mcp/tools/pane_tools/capture_since.py	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #100      +/-   ##
==========================================
+ Coverage   85.58%   86.13%   +0.55%     
==========================================
  Files          44       46       +2     
  Lines        3379     3593     +214     
  Branches      477      516      +39     
==========================================
+ Hits         2892     3095     +203     
  Misses        354      354              
- Partials      133      144      +11     

☔ 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

Found 3 issues (re-checked against the current, rebased branch):

1. Cancelling a wait can orphan the in-flight tmux child. The except asyncio.CancelledError only wraps task.result(), not the await asyncio.wait({task}, timeout=budget) above it. When the MCP client hangs up mid-wait, cancellation almost always lands on that asyncio.wait call, so _kill_and_reap is skipped and the tmux subprocess (and its communicate() future) leaks -- the exact teardown this PR set out to guarantee.

libtmux-mcp/src/libtmux_mcp/tools/pane_tools/wait.py

Lines 238 to 254 in 2993411

	task = asyncio.ensure_future(proc.communicate())
	done, _pending = await asyncio.wait({task}, timeout=budget)
	if not done:
	await _kill_and_reap(proc, task)
	msg = (
	f"tmux {args[0]} did not return within "
	f"{budget:.2f}s; the tmux server is unresponsive"
	)
	raise ExpectedToolError(msg)
	try:
	stdout, stderr = task.result()
	except asyncio.CancelledError:
	# The whole call was cancelled (MCP client hung up). Tear the
	# child down before letting the cancellation through, or tmux
	# is orphaned.
	await _kill_and_reap(proc, task)
	raise

2. The wait_for_text docstring says alternate-screen panes are not detected, but this PR detects them. The Notes section states "this tool does not detect it," while the PR adds state.alternate_on handling that returns outcome="alternate_screen". The agent-facing docs now understate the tool's behavior.

libtmux-mcp/src/libtmux_mcp/tools/pane_tools/wait.py

Lines 589 to 594 in 2993411

	**Alternate screen / pagers are not handled.** Inside ``less``,
	``capture-pane`` returns the pager's painted rows, so a wait for
	text the pager has drawn matches on paint. That is a false
	positive, not a hang, and this tool does not detect it.

3. The docstring references a field that no longer exists. It reports a stale entry match via suppressed_stale_match, but this PR renamed that field to matched_at_entry in models.py, and suppressed_stale_match appears nowhere else in the codebase.

libtmux-mcp/src/libtmux_mcp/tools/pane_tools/wait.py

Lines 517 to 520 in 2993411

	below the cursor at entry — only rows written after the call began
	count. If a pattern was already on screen the result says so via
	``suppressed_stale_match``.

Generated with Claude Code

[tony]

Code review

Found 5 issues:

1. run_command honours the wait ceiling but is not tagged TAG_SELF_BOUNDED, so batches can still multiply it. This PR adds effective_timeout = min(timeout, _wait_ceiling_seconds()) to run_command, putting it in the same class as wait_for_text and wait_for_channel — both of which were given TAG_SELF_BOUNDED so batch_tools._get_allowed_tool_tier rejects them per-operation. run_command is still registered with tags={TAG_MUTATING} alone, so call_mutating_tools_batch / call_destructive_tools_batch accept it, and MAX_BATCH_OPERATIONS of them run serially with no aggregate deadline — up to 1000x the ceiling. That is exactly the multiplication the wait_for_tools.py rationale describes.

libtmux-mcp/src/libtmux_mcp/tools/pane_tools/__init__.py

Lines 93 to 97 in 3a95d89

	)(send_keys_batch)
	mcp.tool(title="Run Command", annotations=ANNOTATIONS_SHELL, tags={TAG_MUTATING})(
	run_command
	)
	mcp.tool(title="Capture Pane", annotations=ANNOTATIONS_RO, tags={TAG_READONLY})(

2. Still open from the first review round: interrupt_gracefully passes stop=["^C", "Interrupt"] with regex=True. As a regex, ^C is start-anchored C — re.search("^C", "^C") is False, so it never matches the literal ^C echo it targets, and re.search("^C", "Compiling") is True, so it false-fires outcome="stopped" on any line starting with C. Escape it (\^C) or drop regex=True for that marker.

libtmux-mcp/src/libtmux_mcp/prompts/recipes.py

Lines 167 to 172 in 3a95d89

	enter=False)` — tmux interprets `C-c` as SIGINT.
	2. `wait_for_text(pane_id="{pane_id}", patterns=["\\$ ", "\\# ", "\\% "],
	stop=["^C", "Interrupt"], regex=True, timeout=5.0)` — waits for a
	common shell prompt glyph. Adjust the patterns to match the user's
	shell theme. The `stop` list exits early on the markers many
	programs print when they catch SIGINT and keep running.

3. WaitForTextResult.risk_band_warned is removed but not documented under ### Breaking changes (AGENTS.md says "Buried breaking changes — they get their own subheading at the top of the entry"). The field was added for wait_for_text: expose risk_band_warned: bool in WaitForTextResult for clients that don't subscribe to log notifications #54 precisely because "clients that do not surface MCP warning notifications can still detect that matching was best-effort" — wait.py still computes warned_risk_band but no longer returns it, so those clients lose that signal silently. The unreleased breaking-changes section covers only the patterns rename and the wait_for_content_change removal.

libtmux-mcp/CHANGES

Lines 8 to 24 in 3a95d89

	### Breaking changes
	**{tooliconl}`wait-for-text` takes `patterns` (a list) instead of `pattern`**
	The single `pattern` string is now `patterns: list[str] | None`. Passing `null`
	waits for any new output at all, which subsumes the removed
	`wait_for_content_change` tool. A new `stop: list[str] | None` argument carries
	failure markers; a `stop` hit ends the wait immediately, and the result's
	`outcome` and `matched_index` report which entry fired.
	**`wait_for_content_change` and `ContentChangeResult` are removed**
	Replaced by `wait_for_text(patterns=null)`, which additionally filters
	pre-existing scrollback and stale below-cursor paint out of the change
	predicate.

4. The wait_for_channel comment says it mirrors wait_for_text, which this PR made false. Commit f62de4e rewrote the wait_for_text path to native asyncio subprocesses specifically because a thread blocked in libtmux's untimed Popen.communicate() cannot be cancelled and hangs interpreter shutdown. wait_for_channel still uses asyncio.to_thread(subprocess.run, ...) — the pattern that commit removed — directly under a comment claiming it mirrors the rewritten one.

libtmux-mcp/src/libtmux_mcp/tools/wait_for_tools.py

Lines 173 to 182 in 3a95d89

	# otherwise no other tool call, MCP ping, or cancellation can
	# be serviced for the duration of the wait. Mirror the pattern
	# used by :func:`~libtmux_mcp.tools.pane_tools.wait.wait_for_text`.
	await asyncio.to_thread(
	subprocess.run,
	argv,
	check=True,
	capture_output=True,
	timeout=effective_timeout,
	)

5. RunCommandResult.effective_timeout is cited with {class} instead of {attr} in CHANGES (AGENTS.md says "attributes use {attr}"). Precedent in the same file: {attr}`~libtmux_mcp.models.SessionInfo.active_pane_id`.

libtmux-mcp/CHANGES

Lines 76 to 78 in 3a95d89

	ceiling: {tooliconl}`run-command` reports the timeout it actually enforced on
	{class}`~libtmux_mcp.models.RunCommandResult.effective_timeout`, and
	{tooliconl}`wait-for-channel` reports it in its confirmation message.

Generated with Claude Code

[tony]

Code review

Fresh pass over the six commits since the last review (3a95d89..dd33e4d). The five findings from that round are all genuinely fixed — I re-verified each, including that the emitted recipe marker is \^C (single backslash, matches literal ^C, not Compiling) and that run_command is now rejected by all three batch wrappers.

Found 2 issues:

1. The new breaking-change entry ships migration advice that does not detect what it claims to. It offers outcome == "timeout" and not matched_at_entry as the "closest substitute" for the removed risk_band_warned, in a copyable # Before / # After block. But warned_risk_band is set from state.history_size >= risk_floor on any poll tick, independent of how the wait ends — so a wait that matches while polling through the trim-risk band is never flagged (the check requires outcome == "timeout"), an ordinary timeout on a pane nowhere near its history limit is flagged falsely, and panes with history_limit == 0 skip the risk-band check entirely while still satisfying the substitute. Suggest saying plainly that there is no result-field equivalent and pointing at the warning notification and wait-for-channel, rather than offering a check that does not correlate.

libtmux-mcp/CHANGES

Lines 45 to 62 in dd33e4d

	Callers that branched on the field have no equivalent test. The closest
	substitute is to escalate on an empty wait — an `outcome` of `timeout` with
	`matched_at_entry` false — and, where completion must be deterministic, to
	compose `tmux wait-for -S <channel>` into the command and call
	{tooliconl}`wait-for-channel` instead.
	```python
	# Before
	result = wait_for_text(patterns=["OK"])
	if result.risk_band_warned:
	...
	# After
	result = wait_for_text(patterns=["OK"])
	if result.outcome == "timeout" and not result.matched_at_entry:
	...
	```

2. Cancelling a wait still orphans the in-flight tmux child. Third round flagging this one, so noting it is still verbatim unchanged at head rather than re-arguing it: await asyncio.wait({task}, timeout=budget) on line 239 sits outside the try:, which opens on line 247 and guards only task.result(). A client hanging up mid-wait lands its cancellation on the asyncio.wait far more often than on the synchronous task.result(), so _kill_and_reap is skipped and the tmux subprocess leaks — the interpreter-shutdown hang this PR set out to remove. Wrapping the await asyncio.wait(...) in the same try (or a try/finally that reaps) closes it.

libtmux-mcp/src/libtmux_mcp/tools/pane_tools/wait.py

Lines 237 to 254 in dd33e4d

	# when cancelling it can actually succeed.
	task = asyncio.ensure_future(proc.communicate())
	done, _pending = await asyncio.wait({task}, timeout=budget)
	if not done:
	await _kill_and_reap(proc, task)
	msg = (
	f"tmux {args[0]} did not return within "
	f"{budget:.2f}s; the tmux server is unresponsive"
	)
	raise ExpectedToolError(msg)
	try:
	stdout, stderr = task.result()
	except asyncio.CancelledError:
	# The whole call was cancelled (MCP client hung up). Tear the
	# child down before letting the cancellation through, or tmux
	# is orphaned.
	await _kill_and_reap(proc, task)
	raise

Below the reporting threshold but still open, both in wait.py and both flagged in earlier rounds: the docstring Notes section still says alternate screen / pagers "are not handled" and "this tool does not detect it", and the poll-loop comment still describes pushing blocking reads to "the default executor" — three lines below a docstring stating nothing runs on a worker thread.

Generated with Claude Code