ControlModeEngine(api): Rename attach_to to control_session

Rename parameter for clarity and consistency with libtmux naming:
- `attach_to` was ambiguous (what are we attaching to?)
- `control_session` clearly indicates: existing session for control
  client to attach to

Updated in:
- control_mode.py: parameter, internal variable, docstrings
- pytest_plugin.py: _build_engine() parameter
- docs/topics/control_mode.md: example code
- Tests: test names and assertions
- CHANGES: release notes

Author: tony

CHANGES

@@ -44,7 +44,7 @@ _Future release notes will be placed here_
   `Server.has_session()`; advanced users can inspect all sessions via
   `Server._sessions_all()`.
 - `ControlModeEngine` accepts `internal_session_name` (default `libtmux_control_mode`)
-  and `attach_to` for advanced connection strategies.
+  and `control_session` for advanced connection strategies.
 
 Example:
 

docs/topics/control_mode.md

@@ -101,7 +101,7 @@ creating an internal one:
 server.new_session("shared")
 
 # Control mode attaches to it for its connection
-engine = ControlModeEngine(attach_to="shared")
+engine = ControlModeEngine(control_session="shared")
 server = Server(engine=engine)
 
 # The shared session is visible (not filtered)

src/libtmux/_internal/engines/control_mode.py

@@ -89,7 +89,7 @@ def __init__(
         command_timeout: float | None = 10.0,
         notification_queue_size: int = 4096,
         internal_session_name: str | None = None,
-        attach_to: str | None = None,
+        control_session: str | None = None,
         process_factory: _ProcessFactory | None = None,
         max_retries: int = 1,
         start_threads: bool = True,
@@ -109,7 +109,7 @@ def __init__(
             The internal session is used for connection management and is
             automatically filtered from user-facing APIs. A unique name is
             generated automatically to avoid collisions with user sessions.
-        attach_to : str, optional
+        control_session : str, optional
             Attach to existing session instead of creating internal one.
             When set, control mode attaches to this session for its connection.
 
@@ -142,7 +142,7 @@ def __init__(
         self._internal_session_name = (
             internal_session_name or f"libtmux_ctrl_{uuid.uuid4().hex[:8]}"
         )
-        self._attach_to = attach_to
+        self._control_session = control_session
         self._process_factory = process_factory
         self._max_retries = max(0, max_retries)
         self._start_threads = start_threads
@@ -273,7 +273,7 @@ def drain_notifications(
 
         This helper is useful when you need to wait for notification activity
         to settle after an operation that may generate multiple notifications
-        (e.g., attach-session in attach_to mode).
+        (e.g., attach-session in control_session mode).
 
         Parameters
         ----------
@@ -318,7 +318,7 @@ def get_stats(self) -> EngineStats:
     @property
     def internal_session_names(self) -> set[str]:
         """Session names reserved for the engine's control connection."""
-        if self._attach_to:
+        if self._control_session:
             return set()
         return {self._internal_session_name}
 
@@ -376,8 +376,8 @@ def filter_sessions(
             sess_name = sess_obj.session_name or ""
 
             # 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._internal_session_name:
+            # control client when control_session is unset.
+            if not self._control_session and sess_name == self._internal_session_name:
                 continue
 
             clients = pid_map.get(sess_name, [])
@@ -444,22 +444,22 @@ def _start_process(self, server_args: tuple[str | int, ...]) -> None:
         )
 
         # Build command based on configuration
-        if self._attach_to:
+        if self._control_session:
             # Fail fast if attach target is missing before starting control mode.
             has_session_cmd = [
                 tmux_bin,
                 *[str(a) for a in server_args],
                 "has-session",
                 "-t",
-                self._attach_to,
+                self._control_session,
             ]
             probe = subprocess.run(
                 has_session_cmd,
                 capture_output=True,
                 text=True,
             )
             if probe.returncode != 0:
-                msg = f"attach_to session not found: {self._attach_to}"
+                msg = f"control_session not found: {self._control_session}"
                 raise exc.ControlModeConnectionError(msg)
 
             # Attach to existing session (advanced mode)
@@ -469,14 +469,14 @@ def _start_process(self, server_args: tuple[str | int, ...]) -> None:
                 "-C",
                 "attach-session",
                 "-t",
-                self._attach_to,
+                self._control_session,
             ]
             bootstrap_argv = [
                 tmux_bin,
                 *[str(a) for a in server_args],
                 "attach-session",
                 "-t",
-                self._attach_to,
+                self._control_session,
             ]
         else:
             # Create or attach to internal session (default)

src/libtmux/neo.py

@@ -198,7 +198,7 @@ def fetch_objs(
 
     Routes all commands through the server's engine, enabling:
     - Control mode persistent connection for fetch operations
-    - Engine-specific validation (e.g., attach_to preflight checks)
+    - Engine-specific validation (e.g., control_session preflight checks)
     - Consistent error handling across all tmux operations
     """
     formats = list(Obj.__dataclass_fields__.keys())

src/libtmux/pytest_plugin.py

@@ -157,7 +157,7 @@ def server(
             check=False,  # Ignore if already exists
             capture_output=True,
         )
-        engine = _build_engine(engine_name, attach_to="tmuxp")
+        engine = _build_engine(engine_name, control_session="tmuxp")
     else:
         engine = _build_engine(engine_name)
 
@@ -349,16 +349,16 @@ def engine_name(request: pytest.FixtureRequest) -> str:
         return "subprocess"
 
 
-def _build_engine(engine_name: str, attach_to: str | None = None) -> Engine:
+def _build_engine(engine_name: str, control_session: str | None = None) -> Engine:
     """Return engine instance by name.
 
     Parameters
     ----------
     engine_name : str
         Name of engine: "control" or "subprocess"
-    attach_to : str, optional
+    control_session : str, optional
         For control mode: session name to attach to instead of creating internal session
     """
     if engine_name == "control":
-        return ControlModeEngine(attach_to=attach_to)
+        return ControlModeEngine(control_session=control_session)
     return SubprocessEngine()

tests/test_control_mode_engine.py

@@ -193,7 +193,7 @@ def test_control_mode_custom_session_name(tmp_path: pathlib.Path) -> None:
     engine.process.wait(timeout=2)
 
 
-def test_control_mode_attach_to_existing(tmp_path: pathlib.Path) -> None:
+def test_control_mode_control_session_existing(tmp_path: pathlib.Path) -> None:
     """Control mode can attach to existing session (advanced opt-in)."""
     socket_path = tmp_path / "tmux-attach-test"
 
@@ -209,7 +209,7 @@ def test_control_mode_attach_to_existing(tmp_path: pathlib.Path) -> None:
     server1.new_session(session_name="shared_session")
 
     # Control mode attaches to existing session (no internal session created)
-    control_engine = ControlModeEngine(attach_to="shared_session")
+    control_engine = ControlModeEngine(control_session="shared_session")
     server2 = Server(socket_path=socket_path, engine=control_engine)
 
     # Should see the shared session

tests/test_control_mode_regressions.py

@@ -32,10 +32,10 @@ class TrailingOutputFixture(t.NamedTuple):
 
 
 class AttachFixture(t.NamedTuple):
-    """Fixture for attach_to behaviours."""
+    """Fixture for control_session behaviours."""
 
     test_id: str
-    attach_to: str
+    control_session: str
     expect_attached: bool
     expect_notification: bool = False
 
@@ -779,31 +779,31 @@ def test_internal_session_name_collision(case: InternalNameCollisionFixture) ->
     [
         AttachFixture(
             test_id="attach_existing",
-            attach_to="shared_session",
+            control_session="shared_session",
             expect_attached=True,
             expect_notification=True,
         ),
         AttachFixture(
             test_id="attach_missing",
-            attach_to="missing_session",
+            control_session="missing_session",
             expect_attached=False,
         ),
     ],
     ids=lambda c: c.test_id,
 )
-def test_attach_to_existing_session(case: AttachFixture) -> None:
-    """Control mode attach_to should not create/hide a management session."""
+def test_control_session_existing(case: AttachFixture) -> None:
+    """Control mode control_session should not create/hide a management session."""
     socket_name = f"libtmux_test_{uuid.uuid4().hex[:8]}"
     bootstrap = Server(socket_name=socket_name)
     try:
         if case.expect_attached:
             # Create the target session via subprocess engine
             bootstrap.new_session(
-                session_name=case.attach_to,
+                session_name=case.control_session,
                 attach=False,
                 kill_session=True,
             )
-        engine = ControlModeEngine(attach_to=case.attach_to)
+        engine = ControlModeEngine(control_session=case.control_session)
         server = Server(socket_name=socket_name, engine=engine)
         if not case.expect_attached:
             with pytest.raises(exc.ControlModeConnectionError):
@@ -812,7 +812,7 @@ def test_attach_to_existing_session(case: AttachFixture) -> None:
 
         sessions = server.sessions
         assert len(sessions) == 1
-        assert sessions[0].session_name == case.attach_to
+        assert sessions[0].session_name == case.control_session
 
         # Only the control client is attached; attached_sessions should be empty
         # because we filter control clients from "attached" semantics.
@@ -823,7 +823,7 @@ def test_attach_to_existing_session(case: AttachFixture) -> None:
             # Drain notifications to confirm control stream is flowing.
             notif = next(server.engine.iter_notifications(timeout=0.5), None)
             if notif is None:
-                pytest.xfail("attach_to did not emit notification within timeout")
+                pytest.xfail("control_session did not emit notification within timeout")
     finally:
         with contextlib.suppress(Exception):
             bootstrap.kill()
@@ -863,25 +863,25 @@ def test_list_clients_control_flag_filters_attached() -> None:
 
 
 @pytest.mark.engines(["control"])
-def test_attach_to_can_drain_notifications() -> None:
-    """drain_notifications() provides explicit sync point for attach_to notifications.
+def test_control_session_can_drain_notifications() -> None:
+    """drain_notifications() provides explicit sync for control_session notifications.
 
-    When using attach_to mode, the control client may receive many notifications
-    from pane output. The drain_notifications() helper waits until the notification
-    queue is idle, providing a deterministic sync point.
+    When using control_session mode, the control client may receive many
+    notifications from pane output. The drain_notifications() helper waits until
+    the notification queue is idle, providing a deterministic sync point.
     """
     socket_name = f"libtmux_test_{uuid.uuid4().hex[:8]}"
     bootstrap = Server(socket_name=socket_name)
     try:
-        # Create a session for attach_to to connect to
+        # Create a session for control_session to connect to
         bootstrap.new_session(
             session_name="drain_test",
             attach=False,
             kill_session=True,
         )
 
         # Control mode will attach to existing session
-        engine = ControlModeEngine(attach_to="drain_test")
+        engine = ControlModeEngine(control_session="drain_test")
         server = Server(socket_name=socket_name, engine=engine)
 
         # Start the engine by accessing sessions