feat(Server): add connect() for simplified session management

Adds Server.connect(session_name) that returns an existing session or creates
a new detached session if it doesn't exist. This provides a cleaner API for
common session reuse patterns, working transparently with both subprocess and
control-mode engines.

Author: tony

src/libtmux/server.py

@@ -436,6 +436,78 @@ def attach_session(self, target_session: str | None = None) -> None:
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
 
+    def connect(self, session_name: str) -> Session:
+        """Connect to a session, creating if it doesn't exist.
+
+        Returns an existing session if found, otherwise creates a new detached session.
+
+        Parameters
+        ----------
+        session_name : str
+            Name of the session to connect to.
+
+        Returns
+        -------
+        :class:`Session`
+            The connected or newly created session.
+
+        Raises
+        ------
+        :exc:`exc.BadSessionName`
+            If the session name is invalid (contains '.' or ':').
+        :exc:`exc.LibTmuxException`
+            If tmux returns an error.
+
+        Examples
+        --------
+        >>> session = server.connect('my_session')
+        >>> session.name
+        'my_session'
+
+        Calling again returns the same session:
+
+        >>> session2 = server.connect('my_session')
+        >>> session2.session_id == session.session_id
+        True
+        """
+        session_check_name(session_name)
+
+        # Check if session already exists
+        if self.has_session(session_name):
+            session = self.sessions.get(session_name=session_name)
+            if session is None:
+                msg = "Session lookup failed after has_session passed"
+                raise exc.LibTmuxException(msg)
+            return session
+
+        # Session doesn't exist, create it
+        # Save and clear TMUX env var (same as new_session)
+        env = os.environ.get("TMUX")
+        if env:
+            del os.environ["TMUX"]
+
+        proc = self.cmd(
+            "new-session",
+            "-d",
+            f"-s{session_name}",
+            "-P",
+            "-F#{session_id}",
+        )
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+        session_id = proc.stdout[0]
+
+        # Restore TMUX env var
+        if env:
+            os.environ["TMUX"] = env
+
+        return Session.from_session_id(
+            server=self,
+            session_id=session_id,
+        )
+
     def new_session(
         self,
         session_name: str | None = None,

tests/test_server.py

@@ -11,6 +11,7 @@
 
 import pytest
 
+from libtmux import exc
 from libtmux.common import has_gte_version, has_version
 from libtmux.server import Server
 
@@ -164,6 +165,35 @@ def test_new_session_shell_env(server: Server) -> None:
         assert pane_start_command == cmd
 
 
+def test_connect_creates_new_session(server: Server) -> None:
+    """Server.connect creates a new session when it doesn't exist."""
+    session = server.connect("test_connect_new")
+    assert session.name == "test_connect_new"
+    assert session.session_id is not None
+
+
+def test_connect_reuses_existing_session(server: Server, session: Session) -> None:
+    """Server.connect reuses an existing session instead of creating a new one."""
+    # First call creates
+    session1 = server.connect("test_connect_reuse")
+    assert session1.name == "test_connect_reuse"
+    session_id_1 = session1.session_id
+
+    # Second call should return the same session
+    session2 = server.connect("test_connect_reuse")
+    assert session2.session_id == session_id_1
+    assert session2.name == "test_connect_reuse"
+
+
+def test_connect_invalid_name(server: Server) -> None:
+    """Server.connect raises BadSessionName for invalid session names."""
+    with pytest.raises(exc.BadSessionName):
+        server.connect("invalid.name")
+
+    with pytest.raises(exc.BadSessionName):
+        server.connect("invalid:name")
+
+
 @pytest.mark.skipif(has_version("3.2"), reason="Wrong width returned with 3.2")
 def test_new_session_width_height(server: Server) -> None:
     """Verify ``Server.new_session`` creates valid session running w/ dimensions."""