feat: respawn_pane, get_*_info reads, mcp_swap dev script (#27)

Three follow-up tracks ship together: a destructive-but-recoverable pane
lifecycle tool, single-object info reads that complete the
get_*_info hierarchy, and a cross-CLI dev script that points Claude /
Codex / Cursor / Gemini at a local checkout in one command. Server
instructions, audit redaction, and the safety topic are extended in
lockstep.

**New tools**

- **`respawn_pane`** — restart a wedged pane in place, preserving
  `pane_id` and the window layout where the kill-and-resplit
  alternative would invalidate references and rearrange the layout.
  Refuses to respawn the MCP server's own pane (mirroring the
  existing `kill_*` self-guards), requires explicit `pane_id` (no
  hierarchical fallback), and carries `destructiveHint=true` /
  `idempotentHint=false` annotations while staying in the
  `mutating` tier so default-profile agents can still reach it for
  shell recovery.
- **`get_session_info`**, **`get_window_info`** — targeted
  single-object metadata reads, completing the four-level
  `get_*_info` hierarchy alongside `get_server_info` /
  `get_pane_info`. Buffers, hooks, and options have existing read
  paths and are intentionally excluded.

**New dev script: `scripts/mcp_swap.py`**

- One command (`just mcp-use-local`) rewrites each detected CLI's
  global config to run the local repo via `uv`; `just mcp-revert`
  restores from a timestamped backup. `just mcp-detect` and
  `just mcp-status` report install state.
- Atomic writes (tempfile + `os.replace`) with re-validation,
  layout-shape guard before mutating Claude's per-project config,
  per-CLI state file at `$XDG_STATE_HOME/libtmux-mcp-dev/swap/`,
  env preservation on replacement, `--dry-run` mode that prints a
  unified diff. Scope is global configs only — workspace configs
  remain the CLI's native responsibility (`cursor mcp add`,
  `gemini mcp add`).

**Audit redaction**

`shell` (string) and `environment` (dict) on `respawn_pane` join the
existing redaction set. Dict-shaped values keep their *keys* visible
(env var names like `DATABASE_URL` are operator-debug-useful) but
digest each *value* via `{len, sha256_prefix}`. Documented limitation:
values may briefly appear in the OS process table while tmux spawns
the new process — the audit log redaction does not cover that
window.

**LLM discoverability and server instructions**

- `display_message` retitled to "Evaluate tmux Format String" with a
  docstring leading with read-only format expansion. Eliminates the
  naming clash with tmux's `display-message` verb that pushed agents
  toward the wrong affordance.
- `pipe_pane` docstring leads with the concrete
  `output_path="/tmp/pane.log"` logging use case.
- `_BASE_INSTRUCTIONS` decomposed into named segments with
  module-level guidance on when to add a new gap-explainer vs. push
  the explanation into a tool docstring. New segments: hooks are
  read-only by design (`HOOKS ARE READ-ONLY`), buffer lifecycle plus
  why `list_buffers` is intentionally absent, `is_caller` workflow
  inside tmux, qualified `socket_name` contract that names
  `list_servers` as the documented exception. A contract test
  enforces that every registered tool except `list_servers` accepts
  `socket_name` so prose and signatures cannot drift.

**Documentation**

- Topic pages added for `respawn-pane`, `get-session-info`, and
  `get-window-info`.
- `safety.md` adds a `respawn-pane` Footgun section alongside
  `pipe-pane` and `set-environment`. The macOS `TMUX_TMPDIR`
  caveat is rewritten to reflect shipped behaviour — tmux's
  three-step socket-path resolution is documented, so operators
  no longer need to set `TMUX_TMPDIR` explicitly to chase a
  problem that's already solved.
- README tool index updated for the three new tools.

**Pre-release decisions (no migration path needed for users)**

- `respawn_pane` parameter renamed `shell_command` → `shell` to
  align with `split_window(shell=…)` and the upstream
  `Pane.respawn(shell=…)` API.
- `respawn_pane` drops the `session_id` / `session_name` /
  `window_id` resolver fallbacks. The runtime guard rejected any
  call missing `pane_id` anyway; validation now lives at the
  FastMCP schema boundary.

**Stopgap noted in source**

`respawn_pane` emits a literal `pane.cmd("respawn-pane", *argv)`
because libtmux 0.55.x has no `Pane.respawn()` yet. The argv shape
mirrors the upstream `tmux-parity` branch: `-k`, `-c <dir>`,
repeated `-eKEY=VALUE` (joined form), then optional trailing
shell. When the libtmux release line picks it up, swap to
`pane.respawn(...)` and drop the stderr branch.

**State path**

`scripts/mcp_swap.py` writes to
`$XDG_STATE_HOME/libtmux-mcp-dev/swap/state.json` (default
`~/.local/state/libtmux-mcp-dev/swap/state.json`). The `-dev`
namespace makes the dev-tooling status loud and avoids the
collision with the runtime package name. No migration shim —
pre-alpha, dev-only, single-user surface.

Author: tony

CHANGES

@@ -6,6 +6,30 @@
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### New tool: `respawn_pane`
+
+Restart a wedged pane in place — preserves `pane_id` and the window layout (the alternative `kill_pane` + `split_window` invalidates pane references and rearranges the window). Required `pane_id`; optional `kill` (default true), `shell`, `start_directory`, `environment`. Refuses to respawn the MCP server's own pane, mirroring the existing `kill_*` self-guards. Annotations honestly mark it `destructiveHint=true` / `idempotentHint=false` while staying in the `mutating` tier so default-profile agents can use it for shell recovery. Audit log redacts the `shell` argument and digests `environment` values (keys stay visible). (#27)
+
+#### New tools: `get_session_info`, `get_window_info`
+
+Targeted single-object metadata reads — no more `list_*` + filter when you have an ID. Completes the four-level `get_*_info` hierarchy (server / session / window / pane); buffers, hooks, and options have existing read paths and are deliberately excluded. (#27)
+
+#### New dev script: `scripts/mcp_swap.py`
+
+Point Claude / Codex / Cursor / Gemini at a local checkout in one command. `just mcp-use-local` rewrites each CLI's global config to run the local repo via `uv`; `just mcp-revert` restores from a timestamped backup. `just mcp-detect` and `just mcp-status` report install state. Atomic writes, `--dry-run` mode, per-CLI state file, env preservation on replacement, layout-shape guard before mutating Claude's per-project config. Scope is global configs only — see `scripts/README.md`. (#27)
+
+### Documentation
+
+- {ref}`safety` adds a {tooliconl}`respawn-pane` "Footgun" subsection alongside {tooliconl}`pipe-pane` and {tooliconl}`set-environment`: `kill=true` default, non-idempotent retries, explicit-`pane_id` requirement, OS-process-table visibility for `shell` / `environment`. The macOS `TMUX_TMPDIR` caveat is rewritten to reflect shipped behaviour — tmux's three-step socket-path resolution is documented, so operators no longer need to set `TMUX_TMPDIR` explicitly to chase a problem that's already solved. (#27)
+- LLM-facing discoverability tightened: {tooliconl}`display-message` retitled "Evaluate tmux Format String" with a docstring that leads with read-only format expansion (the tool wraps `display-message -p` but `-p` expands rather than displays), {tooliconl}`pipe-pane` leads with the `/tmp/pane.log` logging use case, and the server instructions explain why hooks are read-only and why there is no `list_buffers` tool. The `socket_name` contract is tightened to acknowledge {tooliconl}`list-servers` as the documented exception. (#27)
+- Topic pages added for {tooliconl}`respawn-pane`, {tooliconl}`get-session-info`, and {tooliconl}`get-window-info`. (#27)
+
+### API decisions (pre-release)
+
+- {tooliconl}`respawn-pane` settles on `shell` (renamed from `shell_command`) to align with {tooliconl}`split-window` and upstream `Pane.respawn(shell=)`, and drops the `session_name` / `session_id` / `window_id` resolver fallbacks — the runtime guard rejected any call missing `pane_id` anyway. Validation now lives at the FastMCP schema boundary. (#27)
+
 ## libtmux-mcp 0.1.0a3 (2026-04-19)
 
 _Post-0.1.0a2 smoke-test fixes and `libtmux` floor bump_

README.md

@@ -16,9 +16,9 @@ Give your AI agent hands inside the terminal — create sessions, run commands,
 | Module | Tools |
 |--------|-------|
 | **Server** | `list_sessions`, `create_session`, `kill_server`, `get_server_info` |
-| **Session** | `list_windows`, `create_window`, `rename_session`, `select_window`, `kill_session` |
-| **Window** | `list_panes`, `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` |
+| **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`, `respawn_pane`, `kill_pane` |
 | **Options** | `show_option`, `set_option` |
 | **Environment** | `show_environment`, `set_environment` |
 

docs/_ext/__init__.py

@@ -0,0 +1,3 @@
+"""Sphinx extensions bundled with the project documentation."""
+
+from __future__ import annotations

docs/_widgets/mcp-install/widget.html

@@ -4,7 +4,8 @@
   MCPInstallWidget.context() / the directive's option merge.
 
   Each code block runs through the `highlight` filter (defined in
-  widgets._base.make_highlight_filter) which wraps Sphinx's PygmentsBridge —
+  docs._ext.widgets._base.make_highlight_filter) which wraps Sphinx's
+  PygmentsBridge —
   so the output is byte-identical to a native ``.. code-block::`` block,
   meaning sphinx-copybutton + its prompt-strip regex work automatically.
 #}

docs/conf.py

@@ -19,8 +19,8 @@
 project_root = cwd.parent
 project_src = project_root / "src"
 
+sys.path.insert(0, str(project_root))
 sys.path.insert(0, str(project_src))
-sys.path.insert(0, str(cwd / "_ext"))
 
 # package data
 about: dict[str, str] = {}
@@ -40,7 +40,7 @@
         "sphinx_autodoc_api_style",
         "sphinx.ext.todo",
         "sphinx_autodoc_fastmcp",
-        "widgets",
+        "docs._ext.widgets",
     ],
     intersphinx_mapping={
         "python": ("https://docs.python.org/", None),

docs/tools/pane/display-message.md

@@ -1,11 +1,13 @@
-# Display message
+# Evaluate tmux format string (display_message)
 
 ```{fastmcp-tool} pane_tools.display_message
 ```
 
 **Use when** you need to query arbitrary tmux variables — zoom state, pane
 dead flag, client activity, or any `#{format}` string that isn't covered by
-other tools.
+other tools. Despite the historical name (`display_message` is the tmux verb
+it wraps), this tool does **not** display anything to the user; it expands
+the format string with `display-message -p` and returns the value.
 
 **Avoid when** a dedicated tool already provides the information — e.g. use
 {tooliconl}`snapshot-pane` for cursor position and mode, or
@@ -33,5 +35,3 @@ zoomed=0 dead=0
 
 ```{fastmcp-tool-input} pane_tools.display_message
 ```
-
-## Act

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,83 @@
+# 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` relaunches with a different command;
+optional `start_directory` sets its cwd; optional `environment` adds
+per-process env vars (one `-e KEY=VALUE` flag per entry).
+
+**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.
+
+**Tip:** Call {tooliconl}`get-pane-info` first if you need to capture
+`pane_current_command` before respawn — the new process loses its argv.
+Omitting `shell` makes tmux replay the original argv (good default for
+shells; may differ for processes spawned via custom shell at split
+time).
+
+**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": "pytest -x",
+    "start_directory": "/home/user/project"
+  }
+}
+```
+
+**Example — relaunch with extra environment variables:**
+
+```json
+{
+  "tool": "respawn_pane",
+  "arguments": {
+    "pane_id": "%5",
+    "shell": "pytest -x",
+    "environment": {
+      "PYTHONPATH": "/home/user/project/src",
+      "DATABASE_URL": "postgres://localhost/test"
+    }
+  }
+}
+```
+
+The audit log redacts each `environment` *value* via `{len, sha256_prefix}` digests but keeps the keys visible (env var names like `DATABASE_URL` are operator-debug-useful, while their values are the secret). Note that values may still appear briefly in the OS process table while tmux spawns the new process — see {ref}`safety` for details.
+
+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
+```

docs/tools/session/get-session-info.md

@@ -0,0 +1,51 @@
+# Get session info
+
+```{fastmcp-tool} session_tools.get_session_info
+```
+
+**Use when** you need metadata for a single session (ID, name, window
+count, attachment status, activity timestamp) and you already know its
+`session_id` or `session_name`. Avoids the `list_sessions` + filter dance.
+
+**Avoid when** you need every session — call `list_sessions` or iterate
+via the `tmux://sessions` resource.
+
+**Side effects:** None. Readonly.
+
+**Example:**
+
+```json
+{
+  "tool": "get_session_info",
+  "arguments": {
+    "session_id": "$0"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "session_id": "$0",
+  "session_name": "dev",
+  "window_count": 3,
+  "session_attached": "1",
+  "session_created": "1713600000",
+  "active_pane_id": "%0"
+}
+```
+
+Resolve by name when only the session_name is known:
+
+```json
+{
+  "tool": "get_session_info",
+  "arguments": {
+    "session_name": "dev"
+  }
+}
+```
+
+```{fastmcp-tool-input} session_tools.get_session_info
+```

docs/tools/session/index.md

@@ -9,6 +9,10 @@ Session-scoped tools — enumerate windows, rename or kill a session, switch win
 Enumerate windows inside a session.
 :::
 
+:::{grid-item-card} {tooliconl}`get-session-info`
+Read metadata for one session.
+:::
+
 :::{grid-item-card} {tooliconl}`select-window`
 Switch to a window by id, index, or direction.
 :::
@@ -32,6 +36,7 @@ Terminate a session. Destructive.
 :maxdepth: 1
 
 list-windows
+get-session-info
 select-window
 create-window
 rename-session