mcp(feat[pane_tools]): Add wait_for_text tool for terminal automation

why: Terminal automation requires waiting for specific output to appear
(e.g., build completion, prompt return). Agents currently must poll
`capture_pane` repeatedly, consuming tokens and turns. A dedicated tool
saves both by encapsulating the poll loop server-side.

Uses libtmux's existing `retry_until` infrastructure (8s default timeout,
50ms poll interval) and the same regex pattern matching as `search_panes`.

Refs:
- #651
what:
- Add WaitForTextResult Pydantic model to models.py
- Add wait_for_text() tool using retry_until internally
- Returns structured result with found/timed_out/matched_lines/elapsed
- Tagged TAG_READONLY with ANNOTATIONS_RO (read-only, idempotent)
- Add parametrized WaitForTextFixture tests (found + timeout cases)
- Add test_wait_for_text_invalid_regex for bad pattern handling

Closes #651

Author: tony

src/libtmux/mcp/models.py

@@ -120,3 +120,16 @@ class EnvironmentSetResult(BaseModel):
     name: str = Field(description="Variable name")
     value: str = Field(description="Value that was set")
     status: str = Field(description="Operation status")
+
+
+class WaitForTextResult(BaseModel):
+    """Result of waiting for text to appear in a pane."""
+
+    found: bool = Field(description="Whether the pattern was found before timeout")
+    matched_lines: list[str] = Field(
+        default_factory=list,
+        description="Lines matching the pattern (empty if not found)",
+    )
+    pane_id: str = Field(description="Pane ID that was polled")
+    elapsed_seconds: float = Field(description="Time spent waiting in seconds")
+    timed_out: bool = Field(description="Whether the timeout was reached")

src/libtmux/mcp/tools/pane_tools.py

@@ -20,7 +20,7 @@
     _serialize_pane,
     handle_tool_errors,
 )
-from libtmux.mcp.models import PaneContentMatch, PaneInfo
+from libtmux.mcp.models import PaneContentMatch, PaneInfo, WaitForTextResult
 
 if t.TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -497,6 +497,107 @@ def search_panes(
     return matches
 
 
+@handle_tool_errors
+def wait_for_text(
+    pattern: str,
+    pane_id: str | None = None,
+    session_name: str | None = None,
+    session_id: str | None = None,
+    window_id: str | None = None,
+    timeout: float = 8.0,
+    interval: float = 0.05,
+    match_case: bool = False,
+    content_start: int | None = None,
+    content_end: int | None = None,
+    socket_name: str | None = None,
+) -> WaitForTextResult:
+    """Wait for text to appear in a tmux pane.
+
+    Polls the pane content at regular intervals until the pattern is found
+    or the timeout is reached. Use this instead of polling capture_pane
+    manually — it saves agent tokens and turns.
+
+    Parameters
+    ----------
+    pattern : str
+        Text or regex pattern to wait for.
+    pane_id : str, optional
+        Pane ID (e.g. '%1').
+    session_name : str, optional
+        Session name for pane resolution.
+    session_id : str, optional
+        Session ID (e.g. '$1') for pane resolution.
+    window_id : str, optional
+        Window ID for pane resolution.
+    timeout : float
+        Maximum seconds to wait. Default 8.0.
+    interval : float
+        Seconds between polls. Default 0.05 (50ms).
+    match_case : bool
+        Whether to match case. Default False (case-insensitive).
+    content_start : int, optional
+        Start line for capture. Negative values reach into scrollback.
+    content_end : int, optional
+        End line for capture.
+    socket_name : str, optional
+        tmux socket name.
+
+    Returns
+    -------
+    WaitForTextResult
+        Result with found status, matched lines, and timing info.
+    """
+    import time
+
+    from fastmcp.exceptions import ToolError
+
+    from libtmux.test.retry import retry_until
+
+    flags = 0 if match_case else re.IGNORECASE
+    try:
+        compiled = re.compile(pattern, flags)
+    except re.error as e:
+        msg = f"Invalid regex pattern: {e}"
+        raise ToolError(msg) from e
+
+    server = _get_server(socket_name=socket_name)
+    pane = _resolve_pane(
+        server,
+        pane_id=pane_id,
+        session_name=session_name,
+        session_id=session_id,
+        window_id=window_id,
+    )
+
+    assert pane.pane_id is not None
+    matched_lines: list[str] = []
+    start_time = time.monotonic()
+
+    def _check() -> bool:
+        lines = pane.capture_pane(start=content_start, end=content_end)
+        hits = [line for line in lines if compiled.search(line)]
+        if hits:
+            matched_lines.extend(hits)
+            return True
+        return False
+
+    found = retry_until(
+        _check,
+        seconds=timeout,
+        interval=interval,
+        raises=False,
+    )
+
+    elapsed = time.monotonic() - start_time
+    return WaitForTextResult(
+        found=found,
+        matched_lines=matched_lines,
+        pane_id=pane.pane_id,
+        elapsed_seconds=round(elapsed, 3),
+        timed_out=not found,
+    )
+
+
 def register(mcp: FastMCP) -> None:
     """Register pane-level tools with the MCP instance."""
     mcp.tool(title="Send Keys", annotations=ANNOTATIONS_CREATE, tags={TAG_MUTATING})(
@@ -525,3 +626,6 @@ def register(mcp: FastMCP) -> None:
     mcp.tool(title="Search Panes", annotations=ANNOTATIONS_RO, tags={TAG_READONLY})(
         search_panes
     )
+    mcp.tool(title="Wait For Text", annotations=ANNOTATIONS_RO, tags={TAG_READONLY})(
+        wait_for_text
+    )

tests/mcp/test_pane_tools.py

@@ -7,7 +7,7 @@
 import pytest
 from fastmcp.exceptions import ToolError
 
-from libtmux.mcp.models import PaneContentMatch
+from libtmux.mcp.models import PaneContentMatch, WaitForTextResult
 from libtmux.mcp.tools.pane_tools import (
     capture_pane,
     clear_pane,
@@ -17,6 +17,7 @@
     search_panes,
     send_keys,
     set_pane_title,
+    wait_for_text,
 )
 from libtmux.test.retry import retry_until
 
@@ -413,3 +414,80 @@ def test_search_panes_is_caller(
     match = next((r for r in result if r.pane_id == mcp_pane.pane_id), None)
     assert match is not None
     assert match.is_caller is expected_is_caller
+
+
+# ---------------------------------------------------------------------------
+# wait_for_text tests
+# ---------------------------------------------------------------------------
+
+
+class WaitForTextFixture(t.NamedTuple):
+    """Test fixture for wait_for_text."""
+
+    test_id: str
+    command: str | None
+    pattern: str
+    timeout: float
+    expected_found: bool
+
+
+WAIT_FOR_TEXT_FIXTURES: list[WaitForTextFixture] = [
+    WaitForTextFixture(
+        test_id="text_found",
+        command="echo WAIT_MARKER_abc123",
+        pattern="WAIT_MARKER_abc123",
+        timeout=2.0,
+        expected_found=True,
+    ),
+    WaitForTextFixture(
+        test_id="timeout_not_found",
+        command=None,
+        pattern="NEVER_EXISTS_xyz999",
+        timeout=0.3,
+        expected_found=False,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    WaitForTextFixture._fields,
+    WAIT_FOR_TEXT_FIXTURES,
+    ids=[f.test_id for f in WAIT_FOR_TEXT_FIXTURES],
+)
+def test_wait_for_text(
+    mcp_server: Server,
+    mcp_pane: Pane,
+    test_id: str,
+    command: str | None,
+    pattern: str,
+    timeout: float,
+    expected_found: bool,
+) -> None:
+    """wait_for_text polls pane content for a pattern."""
+    if command is not None:
+        mcp_pane.send_keys(command, enter=True)
+
+    result = wait_for_text(
+        pattern=pattern,
+        pane_id=mcp_pane.pane_id,
+        timeout=timeout,
+        socket_name=mcp_server.socket_name,
+    )
+    assert isinstance(result, WaitForTextResult)
+    assert result.found is expected_found
+    assert result.timed_out is (not expected_found)
+    assert result.pane_id == mcp_pane.pane_id
+    assert result.elapsed_seconds >= 0
+
+    if expected_found:
+        assert len(result.matched_lines) >= 1
+
+
+def test_wait_for_text_invalid_regex(mcp_server: Server, mcp_pane: Pane) -> None:
+    """wait_for_text raises ToolError on invalid regex."""
+    with pytest.raises(ToolError, match="Invalid regex pattern"):
+        wait_for_text(
+            pattern="[invalid",
+            pane_id=mcp_pane.pane_id,
+            socket_name=mcp_server.socket_name,
+        )