mcp(feat[pane_tools]): add respawn_pane for in-place shell recovery

why: when an agent wedges a shell (hung REPL, runaway process, bad
terminal mode) the only current recourse is kill_pane + split_window,
which destroys pane_id references the agent may still be holding and
reshuffles the layout. tmux's respawn-pane -k restarts the process
in place, preserving both pane_id and layout — the right primitive
for agent recovery flows.

what:
- Add respawn_pane(pane_id, session_name, session_id, window_id,
  kill=True, shell_command, start_directory, socket_name) returning
  PaneInfo. Default kill=True threads -k to tmux (matches the
  recovery-flow intent). Optional shell_command and start_directory
  map to tmux's respawn-pane positional arg and -c flag respectively;
  -e env is deliberately omitted (use set_environment if needed).
- Call pane.refresh() after the cmd so _serialize_pane reads the
  fresh pane_pid and pane_current_command.
- Register with ANNOTATIONS_MUTATING + TAG_MUTATING, placed next to
  kill_pane in the pane lifecycle module. Export from pane_tools
  __init__.
- Add two tests: test_respawn_pane_preserves_pane_id_and_refreshes_pid
  (pane_id survives, pane_pid changes) and
  test_respawn_pane_replaces_shell_command (shell_command override
  takes effect).
- Add docs/tools/pane/respawn-pane.md modeled on kill-pane.md plus
  relaunch-with-different-command example; add the page to the Pane
  tools index grid and toctree.
- Append respawn_pane to the README tool catalog Pane row.

Defer respawn_window until respawn_pane shows usage (audit §6.1).

Author: tony

README.md

@@ -18,7 +18,7 @@ Give your AI agent hands inside the terminal — create sessions, run commands,
 | **Server** | `list_sessions`, `create_session`, `kill_server`, `get_server_info` |
 | **Session** | `list_windows`, `get_session_info`, `create_window`, `rename_session`, `select_window`, `kill_session` |
 | **Window** | `list_panes`, `get_window_info`, `split_window`, `rename_window`, `select_layout`, `resize_window`, `move_window`, `kill_window` |
-| **Pane** | `send_keys`, `paste_text`, `capture_pane`, `snapshot_pane`, `search_panes`, `get_pane_info`, `wait_for_text`, `wait_for_content_change`, `display_message`, `select_pane`, `swap_pane`, `resize_pane`, `set_pane_title`, `clear_pane`, `pipe_pane`, `enter_copy_mode`, `exit_copy_mode`, `kill_pane` |
+| **Pane** | `send_keys`, `paste_text`, `capture_pane`, `snapshot_pane`, `search_panes`, `get_pane_info`, `wait_for_text`, `wait_for_content_change`, `display_message`, `select_pane`, `swap_pane`, `resize_pane`, `set_pane_title`, `clear_pane`, `pipe_pane`, `enter_copy_mode`, `exit_copy_mode`, `respawn_pane`, `kill_pane` |
 | **Options** | `show_option`, `set_option` |
 | **Environment** | `show_environment`, `set_environment` |
 

docs/tools/pane/index.md

@@ -81,6 +81,10 @@ Block until a tmux wait-for channel is signalled.
 Signal a waiting channel.
 :::
 
+:::{grid-item-card} {tooliconl}`respawn-pane`
+Restart a pane's process in place, preserving pane_id.
+:::
+
 :::{grid-item-card} {tooliconl}`kill-pane`
 Terminate a pane. Destructive.
 :::
@@ -110,5 +114,6 @@ wait-for-text
 wait-for-content-change
 wait-for-channel
 signal-channel
+respawn-pane
 kill-pane
 ```

docs/tools/pane/respawn-pane.md

@@ -0,0 +1,58 @@
+# Respawn pane
+
+```{fastmcp-tool} pane_tools.respawn_pane
+```
+
+**Use when** a pane's shell or command has wedged (hung REPL, runaway
+process, bad terminal mode) and you need a clean restart *without*
+destroying the `pane_id` references other tools or callers may still
+be holding. With `kill=True` (the default) tmux kills the current
+process first; optional `shell_command` relaunches with a different
+command; optional `start_directory` sets its cwd.
+
+**Avoid when** the pane genuinely needs to go away — use
+{tooliconl}`kill-pane` instead. Also avoid when you want to change
+the layout: `respawn-pane` preserves the pane in place.
+
+**Side effects:** Kills the current process (with `kill=True`) and
+starts a new one. **The `pane_id` is preserved** — that's the whole
+point of the tool. `pane_pid` updates to the new process.
+
+**Example — recover a wedged pane, relaunching the default shell:**
+
+```json
+{
+  "tool": "respawn_pane",
+  "arguments": {
+    "pane_id": "%5"
+  }
+}
+```
+
+**Example — relaunch with a different command and working directory:**
+
+```json
+{
+  "tool": "respawn_pane",
+  "arguments": {
+    "pane_id": "%5",
+    "shell_command": "pytest -x",
+    "start_directory": "/home/user/project"
+  }
+}
+```
+
+Response (PaneInfo):
+
+```json
+{
+  "pane_id": "%5",
+  "pane_pid": "98765",
+  "pane_current_command": "pytest",
+  "pane_current_path": "/home/user/project",
+  ...
+}
+```
+
+```{fastmcp-tool-input} pane_tools.respawn_pane
+```

src/libtmux_mcp/tools/pane_tools/__init__.py

@@ -36,6 +36,7 @@
 from libtmux_mcp.tools.pane_tools.lifecycle import (
     get_pane_info,
     kill_pane,
+    respawn_pane,
     set_pane_title,
 )
 from libtmux_mcp.tools.pane_tools.meta import display_message, snapshot_pane
@@ -61,6 +62,7 @@
     "pipe_pane",
     "register",
     "resize_pane",
+    "respawn_pane",
     "search_panes",
     "select_pane",
     "send_keys",
@@ -88,6 +90,11 @@ def register(mcp: FastMCP) -> None:
         annotations=ANNOTATIONS_DESTRUCTIVE,
         tags={TAG_DESTRUCTIVE},
     )(kill_pane)
+    mcp.tool(
+        title="Respawn Pane",
+        annotations=ANNOTATIONS_MUTATING,
+        tags={TAG_MUTATING},
+    )(respawn_pane)
     mcp.tool(
         title="Set Pane Title", annotations=ANNOTATIONS_MUTATING, tags={TAG_MUTATING}
     )(set_pane_title)

src/libtmux_mcp/tools/pane_tools/lifecycle.py

@@ -58,6 +58,84 @@ def kill_pane(
     return f"Pane killed: {pid}"
 
 
+@handle_tool_errors
+def respawn_pane(
+    pane_id: str | None = None,
+    session_name: str | None = None,
+    session_id: str | None = None,
+    window_id: str | None = None,
+    kill: bool = True,
+    shell_command: str | None = None,
+    start_directory: str | None = None,
+    socket_name: str | None = None,
+) -> PaneInfo:
+    """Restart a pane's process in place, preserving pane_id and layout.
+
+    Use when a shell wedges (hung REPL, runaway process, bad terminal
+    mode). The alternative — kill_pane + split_window — destroys
+    pane_id references the agent may still be holding, and rearranges
+    the layout. respawn-pane preserves both.
+
+    With ``kill=True`` (the default), tmux kills the existing process
+    before respawning. Optional ``shell_command`` replaces the
+    command tmux relaunches; ``start_directory`` sets the working
+    directory for the new process.
+
+    Parameters
+    ----------
+    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.
+    kill : bool
+        When True (default), pass ``-k`` to tmux so the current
+        process is killed before respawning. When False, respawn
+        fails if the pane already has a running process.
+    shell_command : str, optional
+        Replacement command for tmux to launch. When omitted, tmux
+        restarts the original shell/command.
+    start_directory : str, optional
+        Working directory for the relaunched command (maps to
+        ``respawn-pane -c``).
+    socket_name : str, optional
+        tmux socket name.
+
+    Returns
+    -------
+    PaneInfo
+        Serialized pane metadata after respawn. The pane_id is
+        preserved; pane_pid reflects the new process.
+    """
+    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,
+    )
+    argv: list[str] = ["-t", pane.pane_id or ""]
+    if kill:
+        argv.append("-k")
+    if start_directory is not None:
+        argv.extend(["-c", start_directory])
+    if shell_command is not None:
+        argv.append(shell_command)
+    result = pane.cmd("respawn-pane", *argv)
+    if result.stderr:
+        stderr = " ".join(result.stderr).strip()
+        msg = f"tmux respawn-pane failed: {stderr}"
+        raise ToolError(msg)
+    # Pick up fresh pane_pid and any command/path updates; tmux does
+    # not invalidate the underlying object on respawn.
+    pane.refresh()
+    return _serialize_pane(pane)
+
+
 @handle_tool_errors
 def set_pane_title(
     title: str,

tests/test_pane_tools.py

@@ -27,6 +27,7 @@
     paste_text,
     pipe_pane,
     resize_pane,
+    respawn_pane,
     search_panes,
     select_pane,
     send_keys,
@@ -231,6 +232,61 @@ def test_kill_pane(mcp_server: Server, mcp_session: Session) -> None:
     assert "killed" in result.lower()
 
 
+# ---------------------------------------------------------------------------
+# respawn_pane tests
+# ---------------------------------------------------------------------------
+
+
+def test_respawn_pane_preserves_pane_id_and_refreshes_pid(
+    mcp_server: Server, mcp_session: Session
+) -> None:
+    """respawn_pane keeps the same pane_id but picks up a new pane_pid.
+
+    Uses a fresh split so the caller-pane self-guard doesn't fire and
+    so the test is independent of what the main mcp_pane is running.
+    """
+    window = mcp_session.active_window
+    new_pane = window.split(shell="sleep 3600")
+    assert new_pane.pane_id is not None
+    # Force a read of the original pid before we respawn.
+    new_pane.refresh()
+    original_pid = new_pane.pane_pid
+
+    result = respawn_pane(
+        pane_id=new_pane.pane_id,
+        socket_name=mcp_server.socket_name,
+    )
+    assert result.pane_id == new_pane.pane_id, "pane_id must be preserved"
+    assert result.pane_pid is not None
+    assert result.pane_pid != original_pid, (
+        "pane_pid should reflect the new process after respawn"
+    )
+
+    # Cleanup
+    new_pane.kill()
+
+
+def test_respawn_pane_replaces_shell_command(
+    mcp_server: Server, mcp_session: Session
+) -> None:
+    """respawn_pane with shell_command relaunches with the new command."""
+    window = mcp_session.active_window
+    new_pane = window.split(shell="sleep 3600")
+    assert new_pane.pane_id is not None
+
+    result = respawn_pane(
+        pane_id=new_pane.pane_id,
+        shell_command="sleep 7200",
+        socket_name=mcp_server.socket_name,
+    )
+    assert result.pane_id == new_pane.pane_id
+    # pane_current_command reflects the relaunched command.
+    assert result.pane_current_command is not None
+    assert "sleep" in result.pane_current_command
+
+    new_pane.kill()
+
+
 # ---------------------------------------------------------------------------
 # search_panes tests
 # ---------------------------------------------------------------------------