mcp(docs[instructions]): Route pane exit waits and name next steps

why: An agent with a one-shot job in its own pane had no instruction
pointing at wait_for_pane_exit, split_window did not mention the
fan-out tool, and a wait_for_channel timeout gave no next step.

what:
- Name wait_for_pane_exit in the wait routing line, paid for by
  trimming the read-tools line; the 2048-byte budget tests still pass
- Point split_window at split_window_many
- Give wait_for_channel timeout and lost-server errors a suggestion

Author: tony

CHANGES

@@ -32,6 +32,12 @@ scrollback of the new session's panes before a long job starts.
 
 ### Fixes
 
+**Server instructions and wait errors name the right next tool**
+
+The server instructions route a pane's own process to `wait_for_pane_exit`,
+`split_window` points to `split_window_many`, and a `wait_for_channel` timeout
+or lost server says what to call next.
+
 **A socket tmux cannot open is an error, not an empty list**
 
 `list_sessions`, `list_windows` and `list_panes` used to answer `[]` when tmux

src/libtmux_mcp/server.py

@@ -90,17 +90,19 @@
 
 _INSTR_READ_TOOLS = (
     "Prefer snapshot_pane over capture_pane + get_pane_info; capture_since "
-    "for repeated observation/tailing; display_message for tmux variables."
+    "for tailing; display_message for tmux variables."
 )
 
 _INSTR_WAIT_NOT_POLL = (
-    "WAIT, DON'T POLL: run_command for authored commands needing "
-    "status; wait_for_channel for custom tmux wait-for; capture_since "
+    "WAIT, DON'T POLL: run_command for authored commands (status); "
+    "wait_for_pane_exit for shell= jobs; "
+    "wait_for_channel for custom wait-for; capture_since "
     "for tailing; wait_for_text for output you don't author "
     "(patterns=null=any output; stop=[] bails); "
     "send_keys_batch for raw input."
 )
 
+
 #: Gap-explainer: write-hook tools are intentionally absent. See module
 #: comment above for when to add another ``_GAP`` segment vs. push the
 #: explanation into a tool description.

src/libtmux_mcp/tools/wait_for_tools.py

@@ -223,7 +223,13 @@ async def wait_for_channel(
             f"wait-for timeout: channel {cname!r} was not signalled within "
             f"{effective_timeout}s"
         )
-        raise ExpectedToolError(msg) from e
+        raise ExpectedToolError(
+            msg,
+            suggestion=(
+                "The channel is still usable. Check the command that should "
+                "signal it with capture_since, then wait again or raise timeout."
+            ),
+        ) from e
     if returncode != 0:
         detail = stderr.decode(errors="replace").strip()
         msg = f"wait-for failed for channel {cname!r}: {detail or f'exit {returncode}'}"
@@ -253,7 +259,10 @@ async def wait_for_channel(
             "no longer running, so the channel was probably never signalled "
             "— tmux exits 0 for both. Re-check the work you were waiting on."
         )
-        raise ExpectedToolError(msg)
+        raise ExpectedToolError(
+            msg,
+            suggestion="Call get_server_info; create_session starts a new server.",
+        )
     return f"Channel {cname!r} was signalled (timeout {effective_timeout}s)"
 
 

src/libtmux_mcp/tools/window_tools.py

@@ -172,6 +172,7 @@ def split_window(
 
     Creates a new pane by splitting an existing one. Use direction to choose
     above/below/left/right. Returns the new pane's info including its pane_id.
+    To add several panes at once under one layout, use split_window_many.
 
     Parameters
     ----------

tests/test_server.py

@@ -413,6 +413,7 @@ def test_base_instructions_prefer_typed_completion_over_polling() -> None:
     """_BASE_INSTRUCTIONS names typed completion and observation primitives."""
     assert "run_command" in _BASE_INSTRUCTIONS
     assert "wait_for_channel" in _BASE_INSTRUCTIONS
+    assert "wait_for_pane_exit" in _BASE_INSTRUCTIONS
     assert "capture_since" in _BASE_INSTRUCTIONS
     assert "wait_for_text" in _BASE_INSTRUCTIONS
     # The catch-all form replaced the separate wait_for_content_change

tests/test_wait_for_tools.py

@@ -544,3 +544,23 @@ async def _drive() -> str:
 
     assert "was signalled" in result
     assert time.monotonic() - started < 1.9
+
+
+@pytest.mark.usefixtures("mcp_session")
+def test_wait_for_channel_timeout_error_carries_a_next_step(
+    mcp_server: Server,
+) -> None:
+    """A timed-out wait tells the agent the channel is reusable and what to read."""
+    from libtmux_mcp._utils import ExpectedToolError
+
+    with pytest.raises(ExpectedToolError) as excinfo:
+        asyncio.run(
+            wait_for_channel(
+                channel="wf_hint_test",
+                timeout=0.3,
+                socket_name=mcp_server.socket_name,
+            )
+        )
+
+    assert "still usable" in (excinfo.value.suggestion or "")
+    assert "capture_since" in (excinfo.value.suggestion or "")