engine(api): Standardize hook signatures using stored context

Remove server_args parameter from all engine hooks:
- probe_server_alive() now uses self._server_context
- can_switch_client() now uses self._server_context
- Rename exclude_internal_sessions() to filter_sessions()

This eliminates the fragile try/except fallback pattern in server.py
where we had to handle different engine signatures. All engines now
use the bound ServerContext set during Server.__init__.

Net reduction: 16 lines of code removed.

Author: tony

src/libtmux/_internal/engines/base.py

@@ -201,12 +201,11 @@ def iter_notifications(
         return
 
     # Optional hooks ---------------------------------------------------
-    def probe_server_alive(
-        self,
-        server_args: tuple[str | int, ...],
-    ) -> bool | None:
+    def probe_server_alive(self) -> bool | None:
         """Probe if tmux server is alive without starting the engine.
 
+        Uses the bound :attr:`_server_context` for connection details.
+
         Returns
         -------
         bool | None
@@ -219,13 +218,11 @@ def probe_server_alive(
         """
         return None
 
-    def can_switch_client(
-        self,
-        *,
-        server_args: tuple[str | int, ...] | None = None,
-    ) -> bool:
+    def can_switch_client(self) -> bool:
         """Check if switch-client is meaningful for this engine.
 
+        Uses the bound :attr:`_server_context` for connection details.
+
         Returns
         -------
         bool
@@ -239,13 +236,24 @@ def internal_session_names(self) -> set[str]:
         """Names of sessions reserved for engine internals."""
         return set()
 
-    def exclude_internal_sessions(
+    def filter_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/management sessions from user lists."""
+    ) -> list[Session]:
+        """Filter sessions, hiding any internal/management sessions.
+
+        Uses the bound :attr:`_server_context` for connection details.
+
+        Parameters
+        ----------
+        sessions : list[Session]
+            All sessions from the server.
+
+        Returns
+        -------
+        list[Session]
+            Sessions after filtering out any engine-internal ones.
+        """
         return sessions
 
     def get_stats(self) -> EngineStats:  # pragma: no cover - default noop

src/libtmux/_internal/engines/control_mode.py

@@ -322,10 +322,7 @@ def internal_session_names(self) -> set[str]:
             return set()
         return {self._internal_session_name}
 
-    def probe_server_alive(
-        self,
-        server_args: tuple[str | int, ...],
-    ) -> bool | None:
+    def probe_server_alive(self) -> bool | None:
         """Check if tmux server is alive without starting control mode.
 
         Performs a direct subprocess check to avoid bootstrapping the control
@@ -340,33 +337,32 @@ def probe_server_alive(
         if tmux_bin is None:
             return False
 
+        server_args = self._server_context.to_args() if self._server_context else ()
         result = subprocess.run(
-            [tmux_bin, *[str(a) for a in server_args], "list-sessions"],
+            [tmux_bin, *server_args, "list-sessions"],
             check=False,
             capture_output=True,
         )
         return result.returncode == 0
 
-    def exclude_internal_sessions(
+    def filter_sessions(
         self,
         sessions: list[Session],
-        *,
-        server_args: tuple[str | int, ...] | None = None,
     ) -> 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)
-        effective_server_args = server_args or self._server_args or ()
+        server_args = self._server_context.to_args() if self._server_context else ()
 
         proc = self.run(
             "list-clients",
             cmd_args=(
                 "-F",
                 "#{client_pid} #{client_flags} #{session_name}",
             ),
-            server_args=effective_server_args,
+            server_args=server_args,
         )
         pid_map: dict[str, list[tuple[str, str]]] = {}
         for line in proc.stdout:
@@ -396,22 +392,18 @@ def exclude_internal_sessions(
 
         return filtered
 
-    def can_switch_client(
-        self,
-        *,
-        server_args: tuple[str | int, ...] | None = None,
-    ) -> bool:
+    def can_switch_client(self) -> bool:
         """Return True if there is at least one non-control client attached."""
         if self.process is None or self.process.pid is None:
             return False
 
         ctrl_pid = str(self.process.pid)
-        effective_server_args = server_args or self._server_args or ()
+        server_args = self._server_context.to_args() if self._server_context else ()
 
         proc = self.run(
             "list-clients",
             cmd_args=("-F", "#{client_pid} #{client_flags}"),
-            server_args=effective_server_args,
+            server_args=server_args,
         )
         for line in proc.stdout:
             parts = line.split()

src/libtmux/server.py

@@ -222,10 +222,8 @@ def is_alive(self) -> bool:
         >>> tmux = Server(socket_name="no_exist")
         >>> assert not tmux.is_alive()
         """
-        server_args = tuple(self._build_server_args())
-
         # Use engine hook to allow engines to probe without bootstrapping.
-        probe_result = self.engine.probe_server_alive(server_args)
+        probe_result = self.engine.probe_server_alive()
         if probe_result is not None:
             return probe_result
 
@@ -249,7 +247,7 @@ def raise_if_dead(self) -> None:
         server_args = tuple(self._build_server_args())
 
         # Use engine hook to allow engines to probe without bootstrapping.
-        probe_result = self.engine.probe_server_alive(server_args)
+        probe_result = self.engine.probe_server_alive()
         if probe_result is not None:
             if not probe_result:
                 tmux_bin_probe = shutil.which("tmux") or "tmux"
@@ -264,7 +262,7 @@ def raise_if_dead(self) -> None:
         if tmux_bin is None:
             raise exc.TmuxCommandNotFound
 
-        proc = self.engine.run("list-sessions", server_args=server_args)
+        proc = self.cmd("list-sessions")
         if proc.returncode is not None and proc.returncode != 0:
             raise subprocess.CalledProcessError(
                 returncode=proc.returncode,
@@ -386,19 +384,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, "exclude_internal_sessions", None)
-        if callable(filter_fn):
-            server_args = tuple(self._build_server_args())
-            try:
-                sessions = filter_fn(
-                    sessions,
-                    server_args=server_args,
-                )
-            except TypeError:
-                # Subprocess engine does not accept server_args; ignore.
-                sessions = filter_fn(sessions)
-
-        return sessions
+        return self.engine.filter_sessions(sessions)
 
     def has_session(self, target_session: str, exact: bool = True) -> bool:
         """Return True if session exists (excluding internal engine sessions).
@@ -494,11 +480,9 @@ def switch_client(self, target_session: str) -> None:
         """
         session_check_name(target_session)
 
-        server_args = tuple(self._build_server_args())
-
         # Use engine hook to check if switch-client is meaningful.
         # For control mode, this ensures there is at least one non-control client.
-        if not self.engine.can_switch_client(server_args=server_args):
+        if not self.engine.can_switch_client():
             msg = "no current client"
             raise exc.LibTmuxException(msg)