ControlMode(core): Engine hook for hiding control client from attached sessions

why: Keep control-mode client filtering inside the engine instead of server and avoid teardown failures.
what:
- Add engine hook filter_attached_sessions and implement in ControlModeEngine using list-clients
- Server.attached_sessions delegates to engine hook
- Keep lints/types/tests green

Author: tony

src/libtmux/_internal/engines/base.py

@@ -9,6 +9,9 @@
 
 from libtmux.common import tmux_cmd
 
+if t.TYPE_CHECKING:
+    from libtmux.session import Session
+
 
 class ExitStatus(enum.Enum):
     """Exit status returned by tmux control mode commands."""
@@ -157,6 +160,14 @@ def iter_notifications(
             yield timeout
         return
 
+    # Optional hooks ---------------------------------------------------
+    def filter_attached_sessions(
+        self,
+        sessions: list[Session],
+    ) -> list[Session]:  # pragma: no cover - overridden by control mode
+        """Allow engines to hide internal clients from attached session lists."""
+        return sessions
+
     def get_stats(self) -> EngineStats:  # pragma: no cover - default noop
         """Return engine diagnostic stats."""
         return EngineStats(

src/libtmux/_internal/engines/control_mode.py

@@ -22,6 +22,9 @@
     ControlProtocol,
 )
 
+if t.TYPE_CHECKING:
+    from libtmux.session import Session
+
 logger = logging.getLogger(__name__)
 
 
@@ -175,6 +178,31 @@ def get_stats(self) -> EngineStats:
         """Return diagnostic statistics for the engine."""
         return self._protocol.get_stats(restarts=self._restarts)
 
+    def filter_attached_sessions(self, sessions: list[Session]) -> list[Session]:
+        """Hide sessions that are only attached via the control-mode client."""
+        if self.process is None or self.process.pid is None:
+            return sessions
+
+        ctrl_pid = str(self.process.pid)
+
+        proc = self.run("list-clients", cmd_args=("-F#{client_pid} #{session_name}",))
+        pid_map: dict[str, list[str]] = {}
+        for line in proc.stdout:
+            parts = line.split()
+            if len(parts) >= 2:
+                pid, sess_name = parts[0], parts[1]
+                pid_map.setdefault(sess_name, []).append(pid)
+
+        filtered: list[Session] = []
+        for sess_obj in sessions:
+            pids = pid_map.get(sess_obj.session_name or "", [])
+            # If the only attached client is the control client, hide it.
+            if len(pids) == 1 and ctrl_pid in pids:
+                continue
+            filtered.append(sess_obj)
+
+        return filtered
+
     # Internals ---------------------------------------------------------
     def _ensure_process(self, server_args: tuple[str | int, ...]) -> None:
         if self.process is None:

src/libtmux/server.py

@@ -361,14 +361,10 @@ def attached_sessions(self) -> list[Session]:
         """
         sessions = list(self.sessions.filter(session_attached__noeq="1"))
 
-        # Hide internal control-mode client attachment.
-        from libtmux._internal.engines.control_mode import ControlModeEngine
-
-        if isinstance(self.engine, ControlModeEngine):
-            internal_names = self._get_internal_session_names()
-            if self.engine._attach_to:
-                internal_names.add(self.engine._attach_to)
-            sessions = [s for s in sessions if s.session_name not in internal_names]
+        # Let the engine hide its own internal client if it wants to.
+        filter_fn = getattr(self.engine, "filter_attached_sessions", None)
+        if callable(filter_fn):
+            sessions = filter_fn(sessions)
 
         return sessions