Session,Window(feat): add last_window, next_window, previous_window, rotate

why: Window navigation commands (last/next/previous) and pane rotation are
commonly needed for programmatic window management workflows.
what:
- Add Session.last_window() wrapping last-window
- Add Session.next_window() wrapping next-window
- Add Session.previous_window() wrapping previous-window
- Add Window.rotate() wrapping rotate-window with direction_up (-U),
  keep_zoom (-Z) parameters
- Add tests for all navigation commands and rotation

Author: tony

src/libtmux/session.py

@@ -245,6 +245,76 @@ def cmd(
     Commands (tmux-like)
     """
 
+    def last_window(self) -> Window:
+        """Select the last (previously selected) window.
+
+        Wraps ``$ tmux last-window``.
+
+        Returns
+        -------
+        :class:`Window`
+            The newly active window.
+
+        Examples
+        --------
+        >>> w1 = session.new_window(window_name='lw_a')
+        >>> w2 = session.new_window(window_name='lw_b', attach=True)
+        >>> session.last_window()
+        Window(...)
+        """
+        proc = self.cmd("last-window")
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+        return self.active_window
+
+    def next_window(self) -> Window:
+        """Select the next window.
+
+        Wraps ``$ tmux next-window``.
+
+        Returns
+        -------
+        :class:`Window`
+            The newly active window.
+
+        Examples
+        --------
+        >>> w = session.new_window(window_name='nw_test')
+        >>> session.next_window()
+        Window(...)
+        """
+        proc = self.cmd("next-window")
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+        return self.active_window
+
+    def previous_window(self) -> Window:
+        """Select the previous window.
+
+        Wraps ``$ tmux previous-window``.
+
+        Returns
+        -------
+        :class:`Window`
+            The newly active window.
+
+        Examples
+        --------
+        >>> w = session.new_window(window_name='pw_test')
+        >>> session.previous_window()
+        Window(...)
+        """
+        proc = self.cmd("previous-window")
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+        return self.active_window
+
     def select_window(self, target_window: str | int) -> Window:
         """Select window and return the selected window.
 

src/libtmux/window.py

@@ -496,6 +496,50 @@ def select_layout(
 
         return self
 
+    def rotate(
+        self,
+        *,
+        direction_up: bool | None = None,
+        keep_zoom: bool | None = None,
+    ) -> Window:
+        """Rotate pane positions in the window via ``$ tmux rotate-window``.
+
+        Parameters
+        ----------
+        direction_up : bool, optional
+            Rotate upward (``-U`` flag). Default is downward (``-D``).
+        keep_zoom : bool, optional
+            Keep the window zoomed if zoomed (``-Z`` flag).
+
+        Returns
+        -------
+        :class:`Window`
+            Self, for method chaining.
+
+        Examples
+        --------
+        >>> pane1 = window.active_pane
+        >>> pane2 = window.split()
+        >>> window.rotate()
+        Window(...)
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if direction_up:
+            tmux_args += ("-U",)
+        else:
+            tmux_args += ("-D",)
+
+        if keep_zoom:
+            tmux_args += ("-Z",)
+
+        proc = self.cmd("rotate-window", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+        return self
+
     def respawn(
         self,
         *,

tests/test_session.py

@@ -576,6 +576,42 @@ def patched_cmd(cmd_name: str, *args: t.Any, **kwargs: t.Any) -> tmux_cmd:
         test_session.attach()
 
 
+def test_last_window(session: Session) -> None:
+    """Test Session.last_window() selects previous window."""
+    w1 = session.new_window(window_name="last_a", attach=True)
+    w2 = session.new_window(window_name="last_b", attach=True)
+    session.refresh()
+    assert session.active_window.window_id == w2.window_id
+
+    result = session.last_window()
+    assert result.window_id == w1.window_id
+
+
+def test_next_window(session: Session) -> None:
+    """Test Session.next_window() selects next window."""
+    w1 = session.new_window(window_name="next_a", attach=True)
+    session.new_window(window_name="next_b", attach=False)
+
+    # Active is w1, next should go to next_b
+    session.refresh()
+    assert session.active_window.window_id == w1.window_id
+
+    result = session.next_window()
+    # Should have moved to a different window
+    assert result.window_id != w1.window_id
+
+
+def test_previous_window(session: Session) -> None:
+    """Test Session.previous_window() selects previous window."""
+    w1 = session.new_window(window_name="prev_a", attach=True)
+    w2 = session.new_window(window_name="prev_b", attach=True)
+    session.refresh()
+    assert session.active_window.window_id == w2.window_id
+
+    result = session.previous_window()
+    assert result.window_id == w1.window_id
+
+
 def test_new_window_kill_existing(session: Session) -> None:
     """Test Session.new_window() with kill_existing flag."""
     # Create a window at a specific index

tests/test_window.py

@@ -821,6 +821,30 @@ def test_select_layout_mutual_exclusion(session: Session) -> None:
         window.select_layout("tiled", spread=True)
 
 
+def test_rotate_window(session: Session) -> None:
+    """Test Window.rotate() rotates pane positions."""
+    window = session.new_window(window_name="test_rotate")
+    window.resize(height=40, width=80)
+    pane1 = window.active_pane
+    assert pane1 is not None
+    pane2 = pane1.split()
+    pane3 = pane2.split()
+
+    pane1.refresh()
+    pane2.refresh()
+    pane3.refresh()
+    idx_before = (pane1.pane_index, pane2.pane_index, pane3.pane_index)
+
+    window.rotate()
+
+    pane1.refresh()
+    pane2.refresh()
+    pane3.refresh()
+    idx_after = (pane1.pane_index, pane2.pane_index, pane3.pane_index)
+
+    assert idx_before != idx_after
+
+
 def test_respawn_window(session: Session) -> None:
     """Test Window.respawn() with kill flag."""
     window = session.new_window(window_name="test_respawn_w")