Tag v0.1.0a19 (wait_for_text sees the entry cursor row)

Freeze the wait overhaul from the unreleased section into the dated
0.1.0a19 entry, and bump the package version across pyproject.toml,
__about__.py, and uv.lock.

The release carries breaking API changes -- `pattern` becomes
`patterns`, `wait_for_content_change` is removed, `WaitForTextResult`
reports an `outcome`, and the wait ceiling now applies to run_command
and wait_for_channel as well -- so MIGRATION gains a 0.1.0a19 section
covering each with before/after. That file had no unreleased heading to
retitle; the section is new, matching the per-version shape 0.1.0a6
established.

Author: tony

CHANGES

@@ -6,6 +6,10 @@
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+## libtmux-mcp 0.1.0a19 (2026-07-25)
+
+libtmux-mcp 0.1.0a19 makes {tooliconl}`wait-for-text` see the output it was asked to watch for, and puts a ceiling under every wait. The tool anchored one row below the cursor's position at entry, which on a quiescent pane is exactly where the next line lands, so the case it exists for — output you did not author, a daemon printing a single `ready` line — could not match at all. Waits are now bounded by a server ceiling, cancellable without orphaning their tmux child, and report an `outcome` that distinguishes a command that never ran from output that did not match from a pager owning the pane. The wait API changes shape in the process: `pattern` becomes `patterns`, `stop` markers end a wait early, and `wait_for_content_change` is removed in favour of `wait_for_text(patterns=null)`.
+
 ### Breaking changes
 
 **{tooliconl}`wait-for-text` takes a list of patterns, and no wait outruns the

MIGRATION

@@ -19,6 +19,65 @@ for the full release log.
    [tracker]: https://github.com/tmux-python/libtmux-mcp/discussions
 ```
 
+## libtmux-mcp 0.1.0a19 (2026-07-25)
+
+### `wait_for_text` takes `patterns`, and `wait_for_content_change` is gone
+
+`wait_for_text` accepted a single `pattern` string. It now takes `patterns`, a
+list — or `null` to wait for any new output at all. The schema rejects the old
+argument rather than silently ignoring it, so a call written against the old
+signature fails loudly with `Remove or correct the unrecognized argument(s):
+pattern`.
+
+#### Before
+
+```json
+{"tool": "wait_for_text", "arguments": {"pane_id": "%1", "pattern": "ready"}}
+```
+
+#### After
+
+```json
+{"tool": "wait_for_text", "arguments": {"pane_id": "%1", "patterns": ["ready"]}}
+```
+
+`wait_for_content_change` and its `ContentChangeResult` are removed. Pass
+`patterns: null` instead — it waits for any new output and additionally
+excludes pre-existing scrollback and stale paint from the change predicate,
+which the old tool did not.
+
+```json
+{"tool": "wait_for_text", "arguments": {"pane_id": "%1", "patterns": null}}
+```
+
+### Waits are capped by the server
+
+`wait_for_text`, `wait_for_channel`, and `run_command` are all bounded by
+`LIBTMUX_MCP_WAIT_MAX_SECONDS` (30 seconds by default, clamped to `[1, 120]`).
+An over-large `timeout` is **clamped, not rejected** — the call succeeds and
+reports the value actually enforced, so read `effective_timeout` rather than
+assuming your value was honoured. A wait that previously blocked for an hour
+now returns at the ceiling.
+
+Raise the ceiling with the environment variable if your workload needs it, or
+call again — the command keeps running in the pane between calls.
+
+### `WaitForTextResult` reports an `outcome`
+
+The result's loose booleans are replaced by one `outcome` field taking
+`matched`, `any_output`, `stopped`, `alternate_screen`, or `timeout`.
+`risk_band_warned` is removed; the history-limit trim signal is delivered as an
+MCP warning notification instead. Clients that cannot surface notifications
+should compose `tmux wait-for -S` into the command and use `wait_for_channel`,
+which does not read the pane at all.
+
+### Self-bounded tools cannot be batched
+
+`run_command`, `wait_for_text`, and `wait_for_channel` are rejected by the
+batch wrappers per operation, because batching one multiplied the wait ceiling
+by the operation count. Use `send_keys_batch` for command sequences, or call
+the tool directly.
+
 ## libtmux-mcp 0.1.0a6 (2026-05-09)
 
 ### Recommended registration slug: `libtmux` → `tmux`

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "libtmux-mcp"
-version = "0.1.0a18"
+version = "0.1.0a19"
 description = "MCP server for tmux, powered by libtmux"
 requires-python = ">=3.10,<4.0"
 authors = [

src/libtmux_mcp/__about__.py

@@ -4,7 +4,7 @@
 
 __title__ = "libtmux-mcp"
 __package_name__ = "libtmux_mcp"
-__version__ = "0.1.0a18"
+__version__ = "0.1.0a19"
 __description__ = "MCP server for tmux, powered by libtmux"
 __author__ = "Tony Narlock"
 __email__ = "tony@git-pull.com"