Server,Session(fix[version_guard,detach_scope]): raise on unsupported -b; scope detach-client to session

why: Warn-and-skip for -b would silently change semantics to blocking, hanging
     the caller indefinitely. Session.detach_client() without -s was not actually
     session-scoped, making it wrong on multi-session servers.
what:
- confirm_before / command_prompt: replace warnings.warn with LibTmuxException
  when tmux < 3.3; -b is not optional, dropping it hangs the command queue
- Session.detach_client(): restructure arg building so no-target uses
  -s self.session_id, target_client+all_clients uses -a -t, target_client
  alone uses -t
- Update docstring: no-target now says "detaches all clients in this session"
- Update tests: test_detach_client and renamed test now assert 0 clients
  remain (all session clients detached) rather than before-1

Author: tony

src/libtmux/server.py

@@ -866,19 +866,16 @@ def confirm_before(
         ...     server.cmd('show-options', '-gv', '@cf_test').stdout[0]
         'yes'
         """
-        import warnings
-
         from libtmux.common import has_gte_version
 
-        tmux_args: tuple[str, ...] = ()
-
-        if has_gte_version("3.3", tmux_bin=self.tmux_bin):
-            tmux_args += ("-b",)
-        else:
-            warnings.warn(
-                "confirm_before -b requires tmux 3.3+, ignoring",
-                stacklevel=2,
+        if not has_gte_version("3.3", tmux_bin=self.tmux_bin):
+            msg = (
+                "confirm_before requires tmux 3.3+: -b is always used to avoid "
+                "blocking the command queue and is not available on this tmux version"
             )
+            raise exc.LibTmuxException(msg)
+
+        tmux_args: tuple[str, ...] = ("-b",)
 
         if prompt is not None:
             tmux_args += ("-p", prompt)
@@ -953,19 +950,16 @@ def command_prompt(
         ...     server.cmd('show-options', '-gv', '@cp_test').stdout[0]
         'hi'
         """
-        import warnings
-
         from libtmux.common import has_gte_version
 
-        tmux_args: tuple[str, ...] = ()
-
-        if has_gte_version("3.3", tmux_bin=self.tmux_bin):
-            tmux_args += ("-b",)
-        else:
-            warnings.warn(
-                "command_prompt -b requires tmux 3.3+, ignoring",
-                stacklevel=2,
+        if not has_gte_version("3.3", tmux_bin=self.tmux_bin):
+            msg = (
+                "command_prompt requires tmux 3.3+: -b is always used to avoid "
+                "blocking the command queue and is not available on this tmux version"
             )
+            raise exc.LibTmuxException(msg)
+
+        tmux_args: tuple[str, ...] = ("-b",)
 
         if one_key:
             tmux_args += ("-1",)

src/libtmux/session.py

@@ -269,11 +269,12 @@ def detach_client(
         Parameters
         ----------
         target_client : str, optional
-            Target client to detach (``-t`` flag). If omitted, detaches
-            the most recently active client.
+            Target client to detach (``-t`` flag). If omitted, all clients
+            attached to this session are detached (``-s`` session scoping).
         all_clients : bool, optional
-            Detach all clients attached to this session (``-a`` flag). If
-            combined with ``target_client``, tmux keeps that client attached.
+            When combined with ``target_client``, detach all clients except
+            the specified one (``-a -t`` flags). Has no additional effect
+            when ``target_client`` is omitted.
         shell_command : str, optional
             Run a shell command after detaching (``-E`` flag).
 
@@ -284,14 +285,18 @@ def detach_client(
         """
         tmux_args: tuple[str, ...] = ()
 
-        if all_clients:
-            tmux_args += ("-a",)
-
         if shell_command is not None:
             tmux_args += ("-E", shell_command)
 
-        if target_client is not None:
+        if all_clients and target_client is not None:
+            # Keep target_client attached; detach all others from session
+            tmux_args += ("-a", "-t", target_client)
+        elif target_client is not None:
             tmux_args += ("-t", target_client)
+        else:
+            # No target specified: scope to this session so behavior is
+            # deterministic regardless of how many sessions exist on the server
+            tmux_args += ("-s", str(self.session_id))
 
         proc = self.server.cmd("detach-client", *tmux_args)
 

tests/test_session.py

@@ -586,30 +586,36 @@ def test_detach_client(
     session: Session,
     server: Server,
 ) -> None:
-    """Test Session.detach_client() detaches the control-mode client."""
+    """Test Session.detach_client() detaches all session clients when no target given.
+
+    Without target_client, -s session_id scopes the operation to this session.
+    """
     with control_mode():
         before = len(server.list_clients())
         assert before > 0
         session.detach_client()
         after = len(server.list_clients())
-        assert after == before - 1
+        assert after == 0
 
 
-def test_detach_client_only_detaches_one_client(
+def test_detach_client_no_target_detaches_all_session_clients(
     control_mode: t.Callable[..., t.Any],
     session: Session,
     server: Server,
 ) -> None:
-    """Test Session.detach_client() without a target detaches one client."""
+    """Test Session.detach_client() without a target detaches all session clients.
+
+    Without a target_client, the method uses ``-s session_id`` to scope the
+    operation to this session, detaching all attached clients.
+    """
     with control_mode(), control_mode():
         before = server.cmd("list-clients", "-F", "#{client_name}").stdout
         assert len(before) == 2
 
         session.detach_client()
 
         after = server.cmd("list-clients", "-F", "#{client_name}").stdout
-        assert len(after) == 1
-        assert set(after) < set(before)
+        assert len(after) == 0
 
 
 def test_detach_client_target_client(