Pane,Window(feat[respawn]): add respawn() wrapping tmux respawn-pane/respawn-window

why: respawn-pane and respawn-window are needed for restarting processes
in panes/windows without destroying and recreating them.
what:
- Add Pane.respawn() with shell, start_directory (-c), environment (-e),
  kill (-k) parameters wrapping respawn-pane
- Add Window.respawn() with same parameters wrapping respawn-window
- Add tests verifying respawn with kill on active panes and windows

Author: tony

src/libtmux/pane.py

@@ -1139,6 +1139,54 @@ def enter(self) -> Pane:
         self.cmd("send-keys", "Enter")
         return self
 
+    def respawn(
+        self,
+        *,
+        shell: str | None = None,
+        start_directory: StrPath | None = None,
+        environment: dict[str, str] | None = None,
+        kill: bool | None = None,
+    ) -> None:
+        """Respawn the pane process via ``$ tmux respawn-pane``.
+
+        Parameters
+        ----------
+        shell : str, optional
+            Shell command to run in the respawned pane.
+        start_directory : str or PathLike, optional
+            Working directory for the respawned pane (``-c`` flag).
+        environment : dict, optional
+            Environment variables (``-e`` flag).
+        kill : bool, optional
+            Kill the current process before respawning (``-k`` flag).
+            Required if the pane is still active.
+
+        Examples
+        --------
+        >>> pane = window.split(shell='sleep 1m')
+        >>> pane.respawn(kill=True, shell='sh')
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if kill:
+            tmux_args += ("-k",)
+
+        if start_directory is not None:
+            start_path = pathlib.Path(start_directory).expanduser()
+            tmux_args += ("-c", str(start_path))
+
+        if environment:
+            for k, v in environment.items():
+                tmux_args += (f"-e{k}={v}",)
+
+        if shell:
+            tmux_args += (shell,)
+
+        proc = self.cmd("respawn-pane", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def join(
         self,
         target: str | Pane | Window,

src/libtmux/window.py

@@ -9,6 +9,7 @@
 
 import dataclasses
 import logging
+import pathlib
 import shlex
 import typing as t
 import warnings
@@ -495,6 +496,54 @@ def select_layout(
 
         return self
 
+    def respawn(
+        self,
+        *,
+        shell: str | None = None,
+        start_directory: StrPath | None = None,
+        environment: dict[str, str] | None = None,
+        kill: bool | None = None,
+    ) -> None:
+        """Respawn the window process via ``$ tmux respawn-window``.
+
+        Parameters
+        ----------
+        shell : str, optional
+            Shell command to run in the respawned window.
+        start_directory : str or PathLike, optional
+            Working directory for the respawned window (``-c`` flag).
+        environment : dict, optional
+            Environment variables (``-e`` flag).
+        kill : bool, optional
+            Kill the current process before respawning (``-k`` flag).
+            Required if the window is still active.
+
+        Examples
+        --------
+        >>> window = session.new_window(window_name='respawn_test')
+        >>> window.respawn(kill=True, shell='sh')
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if kill:
+            tmux_args += ("-k",)
+
+        if start_directory is not None:
+            start_path = pathlib.Path(start_directory).expanduser()
+            tmux_args += ("-c", str(start_path))
+
+        if environment:
+            for k, v in environment.items():
+                tmux_args += (f"-e{k}={v}",)
+
+        if shell:
+            tmux_args += (shell,)
+
+        proc = self.cmd("respawn-window", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def swap(
         self,
         target: str | Window,

tests/test_pane.py

@@ -740,6 +740,20 @@ def test_split_percentage_size_mutual_exclusion(session: Session) -> None:
         pane.split(size=10, percentage=50)
 
 
+def test_respawn_pane_kill(session: Session) -> None:
+    """Test Pane.respawn() with kill flag on active pane."""
+    window = session.new_window(window_name="test_respawn")
+    pane = window.active_pane
+    assert pane is not None
+
+    # Respawn the active pane with kill
+    pane.respawn(kill=True, shell="sh")
+
+    # Pane should still exist and be alive
+    pane.refresh()
+    assert pane in window.panes
+
+
 def test_join_pane(session: Session) -> None:
     """Test Pane.join() roundtrip with break_pane."""
     window = session.new_window(window_name="test_join")

tests/test_window.py

@@ -821,6 +821,19 @@ def test_select_layout_mutual_exclusion(session: Session) -> None:
         window.select_layout("tiled", spread=True)
 
 
+def test_respawn_window(session: Session) -> None:
+    """Test Window.respawn() with kill flag."""
+    window = session.new_window(window_name="test_respawn_w")
+
+    # Respawn the window with kill
+    window.respawn(kill=True, shell="sh")
+
+    # Window should still exist
+    window.refresh()
+    session.refresh()
+    assert window.window_id in [w.window_id for w in session.windows]
+
+
 def test_swap_window(session: Session) -> None:
     """Test Window.swap() swaps two windows."""
     w1 = session.new_window(window_name="swap_w1")