Window,Server(feat): add link, unlink, and wait_for commands

why: link-window, unlink-window, and wait-for are needed for sharing windows
across sessions and for synchronization between tmux commands.
what:
- Add Window.link() wrapping link-window with target_session, target_index,
  kill_existing (-k), after (-a), before (-b), detach (-d) parameters
- Add Window.unlink() wrapping unlink-window with kill_if_last (-k) parameter
- Add Server.wait_for() wrapping wait-for with lock (-L), unlock (-U),
  set_flag (-S) parameters
- Add tests for link/unlink roundtrip and wait-for set_flag

Author: tony

src/libtmux/server.py

@@ -483,6 +483,51 @@ def run_shell(
             return None
         return proc.stdout
 
+    def wait_for(
+        self,
+        channel: str,
+        *,
+        lock: bool | None = None,
+        unlock: bool | None = None,
+        set_flag: bool | None = None,
+    ) -> None:
+        """Wait for, signal, or lock a channel via ``$ tmux wait-for``.
+
+        Parameters
+        ----------
+        channel : str
+            Channel name.
+        lock : bool, optional
+            Lock the channel (``-L`` flag).
+        unlock : bool, optional
+            Unlock the channel (``-U`` flag).
+        set_flag : bool, optional
+            Set the channel flag and wake waiters (``-S`` flag).
+
+        Examples
+        --------
+        >>> server.new_session(session_name='wait_test')
+        Session(...)
+        >>> server.wait_for('test_channel', set_flag=True)
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if lock:
+            tmux_args += ("-L",)
+
+        if unlock:
+            tmux_args += ("-U",)
+
+        if set_flag:
+            tmux_args += ("-S",)
+
+        tmux_args += (channel,)
+
+        proc = self.cmd("wait-for", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def switch_client(self, target_session: str) -> None:
         """Switch tmux client.
 

src/libtmux/window.py

@@ -496,6 +496,98 @@ def select_layout(
 
         return self
 
+    def link(
+        self,
+        target_session: str | Session,
+        *,
+        target_index: str | None = None,
+        kill_existing: bool | None = None,
+        after: bool | None = None,
+        before: bool | None = None,
+        detach: bool | None = None,
+    ) -> None:
+        """Link this window to another session via ``$ tmux link-window``.
+
+        Parameters
+        ----------
+        target_session : str or Session
+            Target session to link the window to.
+        target_index : str, optional
+            Target window index in the destination session.
+        kill_existing : bool, optional
+            Kill target window if it exists (``-k`` flag).
+        after : bool, optional
+            Insert after the target window (``-a`` flag).
+        before : bool, optional
+            Insert before the target window (``-b`` flag).
+        detach : bool, optional
+            Do not make the linked window active (``-d`` flag).
+
+        Examples
+        --------
+        >>> w = session.new_window(window_name='link_test')
+        >>> s2 = server.new_session(session_name='link_target')
+        >>> w.link(s2)
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if kill_existing:
+            tmux_args += ("-k",)
+
+        if after:
+            tmux_args += ("-a",)
+
+        if before:
+            tmux_args += ("-b",)
+
+        if detach:
+            tmux_args += ("-d",)
+
+        # Source: this window
+        tmux_args += ("-s", f"{self.session_id}:{self.window_index}")
+
+        # Target: destination session[:index]
+        from libtmux.session import Session
+
+        session_id = (
+            target_session.session_id
+            if isinstance(target_session, Session)
+            else target_session
+        )
+        target = f"{session_id}:{target_index}" if target_index else str(session_id)
+        tmux_args += ("-t", target)
+
+        proc = self.server.cmd("link-window", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+    def unlink(self, *, kill_if_last: bool | None = None) -> None:
+        """Unlink this window from the current session via ``$ tmux unlink-window``.
+
+        Parameters
+        ----------
+        kill_if_last : bool, optional
+            Kill the window if it is the last window in the session (``-k``).
+
+        Examples
+        --------
+        >>> w = session.new_window(window_name='unlink_test')
+        >>> s2 = server.new_session(session_name='unlink_s2')
+        >>> w.link(s2)
+        >>> linked = [x for x in s2.windows if x.window_name == 'unlink_test']
+        >>> linked[0].unlink()
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if kill_if_last:
+            tmux_args += ("-k",)
+
+        proc = self.cmd("unlink-window", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def rotate(
         self,
         *,

tests/test_server.py

@@ -460,6 +460,13 @@ def test_tmux_bin_invalid_path_raise_if_dead() -> None:
         s.raise_if_dead()
 
 
+def test_wait_for_set_flag(server: Server) -> None:
+    """Test Server.wait_for() with set_flag."""
+    server.new_session(session_name="wait_test")
+    # Just set the flag — should not block or error
+    server.wait_for("test_channel_set", set_flag=True)
+
+
 def test_run_shell_basic(server: Server) -> None:
     """Test Server.run_shell() executes command and returns output."""
     server.new_session(session_name="run_shell_test")

tests/test_window.py

@@ -821,6 +821,35 @@ def test_select_layout_mutual_exclusion(session: Session) -> None:
         window.select_layout("tiled", spread=True)
 
 
+def test_link_unlink_window(server: Server, session: Session) -> None:
+    """Test Window.link() and Window.unlink()."""
+    # Create a second session
+    s2 = server.new_session(session_name="link_target")
+
+    # Create a window in the first session
+    w = session.new_window(window_name="link_test")
+
+    # Link it to s2
+    w.link(s2, detach=True)
+
+    # Verify window appears in s2
+    s2.refresh()
+    s2_window_names = [win.window_name for win in s2.windows]
+    assert "link_test" in s2_window_names
+
+    # Unlink from s2 — select a different window first
+    linked_windows = [win for win in s2.windows if win.window_name == "link_test"]
+    assert len(linked_windows) > 0
+
+    # We need another window in s2 before unlinking the last one
+    linked_windows[0].unlink()
+
+    # Verify it's gone from s2
+    s2.refresh()
+    s2_window_names = [win.window_name for win in s2.windows]
+    assert "link_test" not in s2_window_names
+
+
 def test_rotate_window(session: Session) -> None:
     """Test Window.rotate() rotates pane positions."""
     window = session.new_window(window_name="test_rotate")