refactor(control-mode): Clarify internal session naming and filters

Author: tony

CHANGES

@@ -43,8 +43,8 @@ _Future release notes will be placed here_
 - Control mode engine's internal connection session is now automatically filtered from
   `Server.sessions` and `Server.has_session()`, making engine choice transparent to
   users. Advanced users can access all sessions via `Server._sessions_all()`. (#605)
-- `ControlModeEngine` accepts optional `session_name` and `attach_to` parameters for
-  advanced session management scenarios. (#605)
+- `ControlModeEngine` accepts optional `internal_session_name` and `attach_to`
+  parameters for advanced session management scenarios. (#605)
 - `Server.connect()`: New convenience method for session management. Returns an
   existing session if found, otherwise creates a new detached session. Simplifies
   common session reuse patterns and works transparently with both subprocess and

docs/topics/control_mode.md

@@ -80,7 +80,7 @@ For testing or advanced scenarios, you can customize the internal session name:
 from libtmux._internal.engines.control_mode import ControlModeEngine
 from libtmux.server import Server
 
-engine = ControlModeEngine(session_name="my_control_session")
+engine = ControlModeEngine(internal_session_name="my_control_session")
 server = Server(engine=engine)
 
 # Internal session is still filtered

src/libtmux/_internal/engines/base.py

@@ -161,11 +161,18 @@ def iter_notifications(
         return
 
     # Optional hooks ---------------------------------------------------
-    def filter_attached_sessions(
+    @property
+    def internal_session_names(self) -> set[str]:
+        """Names of sessions reserved for engine internals."""
+        return set()
+
+    def exclude_internal_sessions(
         self,
         sessions: list[Session],
+        *,
+        server_args: tuple[str | int, ...] | None = None,
     ) -> list[Session]:  # pragma: no cover - overridden by control mode
-        """Allow engines to hide internal clients from attached session lists."""
+        """Allow engines to hide internal/management sessions from user lists."""
         return sessions
 
     def get_stats(self) -> EngineStats:  # pragma: no cover - default noop

src/libtmux/_internal/engines/control_mode.py

@@ -44,7 +44,7 @@ def __init__(
         self,
         command_timeout: float | None = 10.0,
         notification_queue_size: int = 4096,
-        session_name: str | None = None,
+        internal_session_name: str | None = None,
         attach_to: str | None = None,
     ) -> None:
         """Initialize control mode engine.
@@ -55,7 +55,7 @@ def __init__(
             Timeout for tmux commands in seconds. Default: 10.0
         notification_queue_size : int
             Size of notification queue. Default: 4096
-        session_name : str, optional
+        internal_session_name : str, optional
             Custom name for internal control session.
             Default: "libtmux_control_mode"
 
@@ -81,7 +81,7 @@ def __init__(
             notification_queue_size=notification_queue_size,
         )
         self._restarts = 0
-        self._session_name = session_name or "libtmux_control_mode"
+        self._internal_session_name = internal_session_name or "libtmux_control_mode"
         self._attach_to = attach_to
 
     # Lifecycle ---------------------------------------------------------
@@ -183,7 +183,14 @@ def get_stats(self) -> EngineStats:
         """Return diagnostic statistics for the engine."""
         return self._protocol.get_stats(restarts=self._restarts)
 
-    def filter_attached_sessions(
+    @property
+    def internal_session_names(self) -> set[str]:
+        """Session names reserved for the engine's control connection."""
+        if self._attach_to:
+            return set()
+        return {self._internal_session_name}
+
+    def exclude_internal_sessions(
         self,
         sessions: list[Session],
         *,
@@ -217,7 +224,7 @@ def filter_attached_sessions(
 
             # Never expose the internal control session we create to hold the
             # control client when attach_to is unset.
-            if not self._attach_to and sess_name == self._session_name:
+            if not self._attach_to and sess_name == self._internal_session_name:
                 continue
 
             clients = pid_map.get(sess_name, [])
@@ -314,15 +321,15 @@ def _start_process(self, server_args: tuple[str | int, ...]) -> None:
                 "new-session",
                 "-A",
                 "-s",
-                self._session_name,
+                self._internal_session_name,
             ]
             bootstrap_argv = [
                 tmux_bin,
                 *[str(a) for a in server_args],
                 "new-session",
                 "-A",
                 "-s",
-                self._session_name,
+                self._internal_session_name,
             ]
 
         logger.debug("Starting Control Mode process: %s", cmd)

src/libtmux/server.py

@@ -362,7 +362,7 @@ def attached_sessions(self) -> list[Session]:
         sessions = list(self.sessions.filter(session_attached__noeq="1"))
 
         # Let the engine hide its own internal client if it wants to.
-        filter_fn = getattr(self.engine, "filter_attached_sessions", None)
+        filter_fn = getattr(self.engine, "exclude_internal_sessions", None)
         if callable(filter_fn):
             server_args = tuple(self._build_server_args())
             try:
@@ -743,23 +743,14 @@ def new_session(
     # Relations
     #
     def _get_internal_session_names(self) -> set[str]:
-        """Get session names used internally by the engine.
-
-        These sessions are used for engine management (e.g., control mode
-        connection) and should be hidden from user-facing APIs.
-
-        Returns
-        -------
-        set[str]
-            Set of internal session names to filter.
-        """
-        from libtmux._internal.engines.control_mode import ControlModeEngine
-
-        if isinstance(self.engine, ControlModeEngine) and not self.engine._attach_to:
-            # Only filter if not attaching to user session
-            return {self.engine._session_name}
-
-        return set()
+        """Get session names used internally by the engine for management."""
+        internal_names: set[str] = set(
+            getattr(self.engine, "internal_session_names", set()),
+        )
+        try:
+            return set(internal_names)
+        except Exception:  # pragma: no cover - defensive
+            return set()
 
     @property
     def sessions(self) -> QueryList[Session]:

tests/test_control_mode_engine.py

@@ -115,7 +115,7 @@ def fake_start(server_args: t.Sequence[str | int] | None) -> None:
 def test_control_mode_custom_session_name(tmp_path: pathlib.Path) -> None:
     """Control mode engine can use custom internal session name."""
     socket_path = tmp_path / "tmux-custom-session-test"
-    engine = ControlModeEngine(session_name="my_control_session")
+    engine = ControlModeEngine(internal_session_name="my_control_session")
     server = Server(socket_path=socket_path, engine=engine)
 
     # Cleanup if exists