Pane(feat[join]): add join() wrapping tmux join-pane

why: join-pane is the inverse of break-pane, needed for programmatically
merging panes between windows.
what:
- Add join() method with vertical (-v/-h), detach (-d), full_window (-f),
  size (-l), before (-b) parameters
- Accept Pane, Window, or string target ID
- Use server.cmd with explicit -s/-t to avoid auto-target conflicts
- Add roundtrip test (break + join) and horizontal join test

Author: tony

src/libtmux/pane.py

@@ -1139,6 +1139,79 @@ def enter(self) -> Pane:
         self.cmd("send-keys", "Enter")
         return self
 
+    def join(
+        self,
+        target: str | Pane | Window,
+        *,
+        vertical: bool = True,
+        detach: bool = True,
+        full_window: bool | None = None,
+        size: str | int | None = None,
+        before: bool | None = None,
+    ) -> None:
+        """Join this pane into another window/pane via ``$ tmux join-pane``.
+
+        This is the inverse of :meth:`break_pane`.
+
+        Parameters
+        ----------
+        target : str, Pane, or Window
+            Target pane or window to join into.
+        vertical : bool, optional
+            Join vertically (``-v`` flag), default True. Set to False for
+            horizontal (``-h``).
+        detach : bool, optional
+            Do not switch to the target window (``-d`` flag), default True.
+        full_window : bool, optional
+            Join spanning the full window width/height (``-f`` flag).
+        size : str or int, optional
+            Size for the joined pane (``-l`` flag).
+        before : bool, optional
+            Place the pane before the target (``-b`` flag).
+
+        Examples
+        --------
+        >>> pane_to_join = window.split(shell='sleep 1m')
+        >>> new_window = pane_to_join.break_pane()
+        >>> pane_to_join.join(window)
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if vertical:
+            tmux_args += ("-v",)
+        else:
+            tmux_args += ("-h",)
+
+        if detach:
+            tmux_args += ("-d",)
+
+        if full_window:
+            tmux_args += ("-f",)
+
+        if size is not None:
+            tmux_args += (f"-l{size}",)
+
+        if before:
+            tmux_args += ("-b",)
+
+        # Determine target ID
+        from libtmux.window import Window
+
+        if isinstance(target, Pane):
+            target_id = str(target.pane_id)
+        elif isinstance(target, Window):
+            target_id = str(target.window_id)
+        else:
+            target_id = target
+
+        tmux_args += ("-s", str(self.pane_id), "-t", target_id)
+
+        # Use server.cmd to avoid auto-adding -t from self.cmd
+        proc = self.server.cmd("join-pane", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def break_pane(
         self,
         *,

tests/test_pane.py

@@ -740,6 +740,46 @@ def test_split_percentage_size_mutual_exclusion(session: Session) -> None:
         pane.split(size=10, percentage=50)
 
 
+def test_join_pane(session: Session) -> None:
+    """Test Pane.join() roundtrip with break_pane."""
+    window = session.new_window(window_name="test_join")
+    pane = window.active_pane
+    assert pane is not None
+
+    # Create a second pane and break it out
+    new_pane = pane.split(shell="sleep 1m")
+    assert len(window.panes) == 2
+
+    new_window = new_pane.break_pane()
+    window.refresh()
+    assert len(window.panes) == 1
+
+    # Join the pane back
+    new_pane.join(window)
+    window.refresh()
+    assert len(window.panes) == 2
+
+    # The new window should be gone (only had one pane)
+    session.refresh()
+    window_ids = [w.window_id for w in session.windows]
+    assert new_window.window_id not in window_ids
+
+
+def test_join_pane_horizontal(session: Session) -> None:
+    """Test Pane.join() with horizontal split."""
+    window = session.new_window(window_name="test_join_h")
+    window.resize(height=40, width=80)
+    pane = window.active_pane
+    assert pane is not None
+
+    new_pane = pane.split(shell="sleep 1m")
+    new_pane.break_pane()
+
+    new_pane.join(window, vertical=False)
+    window.refresh()
+    assert len(window.panes) == 2
+
+
 def test_break_pane_basic(session: Session) -> None:
     """Test Pane.break_pane() creates a new window."""
     window = session.new_window(window_name="test_break")