fix(tools): Isolate paste_text tmux buffer and tighten temp-file lifecycle

why: paste_text had three related state-management issues on the same
function:

1. Buffer clobber/leak. load-buffer with no -b wrote into tmux's
   default unnamed buffer. In any interactive session this overwrote
   whatever the operator had yanked. And if pane.cmd("paste-buffer",
   "-d", ...) failed for any reason (pane dead, server error), the -d
   never ran and the buffer leaked on the tmux server.

2. Temp-file disk leak on write failure. The with-block bound
   tmppath = f.name *after* f.write(text). If f.write raised (OSError
   disk full / quota), tmppath was never assigned, the subsequent
   try/finally block was never reached, and the temp file created by
   NamedTemporaryFile(delete=False) stayed on disk.

3. Silent stderr on subprocess failure. subprocess.run(..., check=True,
   capture_output=True) raised CalledProcessError with tmux's stderr
   attached, but the message agents saw was just "non-zero exit status
   1" — no tmux diagnostic.

what:
- Generate a unique named buffer per call (mcp_paste_<uuid4 hex>) and
  load into that. paste-buffer uses -b NAME -d so the delete only
  affects the named buffer, leaving the user's unnamed buffer intact.
- Bind tmppath = f.name BEFORE f.write so cleanup always has a path.
- Use pathlib.Path(...).unlink(missing_ok=True) in finally.
- Wrap delete-buffer in contextlib.suppress(Exception) as a defensive
  best-effort cleanup if paste-buffer raised before -d ran.
- Catch CalledProcessError on load-buffer and surface tmux's stderr
  as a ToolError for actionable agent diagnostics.
- Add imports: contextlib (stdlib, module top), uuid (stdlib, module
  top), namespace style per AGENTS.md §Imports.
- Add test_paste_text_does_not_clobber_unnamed_buffer: pre-populates
  the unnamed buffer with a sentinel, calls paste_text, then asserts
  the unnamed buffer still contains the sentinel AND no mcp_paste_*
  named buffer leaks remain on the server.

Author: tony

src/libtmux_mcp/tools/pane_tools.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import contextlib
 import pathlib
 import re
 import shlex
 import typing as t
+import uuid
 
 from libtmux_mcp._utils import (
     ANNOTATIONS_CREATE,
@@ -1172,6 +1174,8 @@ def paste_text(
     import subprocess
     import tempfile
 
+    from fastmcp.exceptions import ToolError
+
     server = _get_server(socket_name=socket_name)
     pane = _resolve_pane(
         server,
@@ -1181,31 +1185,49 @@ def paste_text(
         window_id=window_id,
     )
 
-    # Write text to a temp file and load into tmux buffer
-    # (libtmux's cmd() doesn't support stdin)
-    with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as f:
-        f.write(text)
-        tmppath = f.name
-
+    # Use a unique named tmux buffer so we don't clobber the user's
+    # unnamed paste buffer, and so we can reliably clean up on error
+    # paths (paste-buffer -b NAME -d deletes the named buffer).
+    buffer_name = f"mcp_paste_{uuid.uuid4().hex}"
+    tmppath: str | None = None
     try:
-        # Build tmux command args for loading buffer
+        # Write text to a temp file and load into tmux buffer
+        # (libtmux's cmd() doesn't support stdin).
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as f:
+            tmppath = f.name  # bind first so cleanup works even if write fails
+            f.write(text)
+
+        # Build tmux command args for loading the named buffer
         tmux_bin: str = getattr(server, "tmux_bin", None) or "tmux"
         load_args: list[str] = [tmux_bin]
         if server.socket_name:
             load_args.extend(["-L", server.socket_name])
         if server.socket_path:
             load_args.extend(["-S", str(server.socket_path)])
-        load_args.extend(["load-buffer", tmppath])
-        subprocess.run(load_args, check=True, capture_output=True)
-
-        # Paste from buffer into pane
-        paste_args = ["-d"]  # delete buffer after paste
+        load_args.extend(["load-buffer", "-b", buffer_name, tmppath])
+
+        try:
+            subprocess.run(load_args, check=True, capture_output=True)
+        except subprocess.CalledProcessError as e:
+            stderr = e.stderr.decode(errors="replace").strip() if e.stderr else ""
+            msg = f"load-buffer failed: {stderr or e}"
+            raise ToolError(msg) from e
+
+        # Paste from the named buffer. -d deletes only that named buffer,
+        # leaving any unnamed user buffer intact.
+        paste_args = ["-b", buffer_name, "-d"]
         if bracket:
             paste_args.append("-p")  # bracketed paste mode
         paste_args.extend(["-t", pane.pane_id or ""])
         pane.cmd("paste-buffer", *paste_args)
     finally:
-        pathlib.Path(tmppath).unlink()
+        if tmppath is not None:
+            pathlib.Path(tmppath).unlink(missing_ok=True)
+        # Defensive: the buffer should already be gone (paste-buffer -d
+        # deletes it), but if paste-buffer failed before -d took effect
+        # we leak an entry in the tmux server. Best-effort delete.
+        with contextlib.suppress(Exception):
+            server.cmd("delete-buffer", "-b", buffer_name)
 
     return f"Text pasted to pane {pane.pane_id}"
 

tests/test_pane_tools.py

@@ -912,3 +912,35 @@ def test_paste_text(mcp_server: Server, mcp_pane: Pane) -> None:
         2,
         raises=True,
     )
+
+
+def test_paste_text_does_not_clobber_unnamed_buffer(
+    mcp_server: Server, mcp_pane: Pane
+) -> None:
+    """paste_text must not overwrite the user's unnamed tmux paste buffer.
+
+    Regression guard for the pre-fix behavior: load-buffer without -b
+    writes into tmux's default unnamed buffer, clobbering whatever the
+    user had there. The fix uses a unique named buffer per call.
+    """
+    sentinel = "USER_UNNAMED_BUFFER_SENTINEL_777"
+    mcp_server.cmd("set-buffer", sentinel)
+
+    paste_text(
+        text="echo BUFFER_ISOLATION_test",
+        pane_id=mcp_pane.pane_id,
+        socket_name=mcp_server.socket_name,
+    )
+
+    # The user's unnamed buffer should still contain the sentinel.
+    result = mcp_server.cmd("show-buffer")
+    assert result.stdout and sentinel in "\n".join(result.stdout), (
+        "paste_text clobbered the user's unnamed paste buffer"
+    )
+
+    # And no mcp_paste_* named buffer should linger on the server.
+    listing = mcp_server.cmd("list-buffers", "-F", "#{buffer_name}")
+    buffer_names = "\n".join(listing.stdout or [])
+    assert "mcp_paste_" not in buffer_names, (
+        f"paste_text leaked a named buffer: {buffer_names!r}"
+    )