fix(wait_for_tools): unblock event loop via asyncio.to_thread

[tony]

Summary

• Convert wait_for_channel and signal_channel from sync def → async def.
• Wrap subprocess.run(...) in await asyncio.to_thread(...) so the FastMCP event loop is not starved for the duration of the wait.
• Swap @handle_tool_errors → @handle_tool_errors_async.

Before the fix, any MCP client whose stdio keepalive was shorter than the wait_for_channel timeout could disconnect mid-wait, and no other tool call could be serviced while a wait was pending. This mirrors the fix applied to wait_for_text / wait_for_content_change in 0.1.0a2 (commit 0a408fe) — the channel pair was missed.

The narrow subprocess.TimeoutExpired / CalledProcessError except blocks plus handle_tool_errors_async's Exception-only catch mean asyncio.CancelledError propagates naturally — locked in as a regression test.

Test plan

• uv run ruff check . --fix --show-fixes
• uv run ruff format .
• uv run mypy
• uv run py.test --reruns 0 -vvv (366 passed)
• just build-docs

New regression tests in tests/test_wait_for_tools.py:

• test_channel_tools_are_coroutines — pins async def surface.
• test_wait_for_channel_does_not_block_event_loop — ticker-based discriminator: fires a 10 ms-tick coroutine in parallel with a 500 ms unsignalled wait; asserts ≥ 20 ticks (≈ 0 ticks pre-fix).
• test_wait_for_channel_propagates_cancellation — cancels an in-flight wait with task.cancel(), asserts CancelledError bubbles (not wrapped as ToolError).

Existing sync-call tests converted to asyncio.run(...) since the function signatures changed. One caller in tests/test_pane_tools.py similarly updated.

Companion PRs

Part of a batch of post-0.1.0a2 smoke-test fixes. Each PR is independent and can land in any order:

• fix(wait_for_tools): unblock event loop via asyncio.to_thread #21 — event-loop block in channel waits (this PR, closes wait_for_channel and signal_channel block the FastMCP event loop (sync subprocess.run) #18)
• fix(_utils): scope is_caller annotation to caller's socket #22 — is_caller socket-blind false positive (closes is_caller annotation gives false positives across tmux sockets #19)
• test(conftest): reap leaked libtmux_test* sockets after session #23 — pytest leaks libtmux_test* sockets (closes list_servers exposes dozens of leaked libtmux_test* tmux daemons after test runs #20)

Closes #18

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.67%. Comparing base (22323a2) to head (9546080).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #21      +/-   ##
==========================================
- Coverage   86.85%   86.67%   -0.18%     
==========================================
  Files          38       38              
  Lines        1719     1719              
  Branches      204      204              
==========================================
- Hits         1493     1490       -3     
- Misses        167      169       +2     
- Partials       59       60       +1     

☔ View full report in Codecov by Sentry.
📢 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 AGENTS.md compliance (repo has AGENTS.md, no CLAUDE.md).

Scope:

• AGENTS.md namespace-import rule and testing conventions.
• Shallow bug scan on the diff (decorator swap, asyncio.to_thread hand-off, exception propagation).
• Git blame / history — verified the change matches the pattern established by commit 0a408fe (the analogous wait_for_text async fix) and that handle_tool_errors_async at src/libtmux_mcp/_utils.py correctly preserves the CancelledError-propagation contract locked in by the new test.
• Prior PR review comments on wait_for_tools.py / pane_tools/wait.py (PRs feat(tools): Add 11 new MCP tools for agent workflows #11, FastMCP alignment: new tools, prompts, and middleware #15) — no applicable guidance.
• Code comments in modified files — the Safety docstring's timeout invariant at src/libtmux_mcp/tools/wait_for_tools.py is preserved.

🤖 Generated with Claude Code

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