fix(util,cli[stop]): Require pane resolution for destructive get_session

Add require_pane_resolution parameter to get_session(). When True,
raises SessionNotFound instead of falling back to server.sessions[0]
when TMUX_PANE is unset/stale. tmuxp stop now uses strict mode to
prevent killing an unrelated session. Non-destructive commands
(shell, freeze) retain the fallback behavior.

Author: tony

conftest.py

@@ -102,6 +102,7 @@ def socket_name(request: pytest.FixtureRequest) -> str:
 DOCTEST_NEEDS_TMUX = {
     "tmuxp.cli.load",
     "tmuxp.cli.stop",
+    "tmuxp.util",
     "tmuxp.workspace.builder",
 }
 

src/tmuxp/cli/stop.py

@@ -112,7 +112,7 @@ def command_stop(
                 default=None,
             )
         elif os.environ.get("TMUX"):
-            session = util.get_session(server)
+            session = util.get_session(server, require_pane_resolution=True)
         else:
             tmuxp_echo(
                 colors.error("No session name given and not inside tmux."),

src/tmuxp/util.py

@@ -212,28 +212,57 @@ def get_session(
     server: Server,
     session_name: str | None = None,
     current_pane: Pane | None = None,
+    require_pane_resolution: bool = False,
 ) -> Session:
-    """Get tmux session for server by session name, respects current pane, if passed."""
-    session: Session | None = None
+    """Get tmux session for server by session name, respects current pane, if passed.
+
+    Parameters
+    ----------
+    server : Server
+        tmux server to search.
+    session_name : str, optional
+        Explicit session name to look up.
+    current_pane : Pane, optional
+        Pane to infer session from.
+    require_pane_resolution : bool
+        If True, raise SessionNotFound when TMUX_PANE cannot be resolved
+        instead of falling back to server.sessions[0]. Use for destructive
+        operations like ``tmuxp stop``.
+
+    Examples
+    --------
+    >>> from tmuxp.util import get_session
+    >>> get_session(server, session_name=session.name) == session
+    True
+    """
+    session_result: Session | None = None
     try:
         if session_name:
-            session = server.sessions.get(session_name=session_name)
+            session_result = server.sessions.get(session_name=session_name)
         elif current_pane is not None:
-            session = server.sessions.get(session_id=current_pane.session_id)
+            session_result = server.sessions.get(
+                session_id=current_pane.session_id,
+            )
         else:
             current_pane = get_current_pane(server)
             if current_pane:
-                session = server.sessions.get(session_id=current_pane.session_id)
+                session_result = server.sessions.get(
+                    session_id=current_pane.session_id,
+                )
+            elif require_pane_resolution:
+                pass  # session_result stays None → raises below
+            elif server.sessions:
+                session_result = server.sessions[0]
     except Exception as e:
         if session_name:
             raise exc.SessionNotFound(session_name) from e
         raise exc.SessionNotFound from e
 
-    if session is None:
+    if session_result is None:
         if session_name:
             raise exc.SessionNotFound(session_name)
         raise exc.SessionNotFound
-    return session
+    return session_result
 
 
 def get_window(

tests/test_util.py

@@ -162,20 +162,33 @@ def test_get_session_should_default_to_local_attached_session(
     assert get_session(server) == second_session
 
 
-def test_get_session_raises_when_no_active_pane(
+def test_get_session_falls_back_to_first_when_no_pane(
     server: Server,
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    """get_session() should raise SessionNotFound when TMUX_PANE is unset."""
-    # Clear outer tmux environment to ensure no active pane interferes
+    """get_session() falls back to first session when TMUX_PANE is unset."""
+    monkeypatch.delenv("TMUX_PANE", raising=False)
+    monkeypatch.delenv("TMUX", raising=False)
+
+    first_session = server.new_session(session_name="myfirstsession")
+    server.new_session(session_name="mysecondsession")
+
+    assert get_session(server) == first_session
+
+
+def test_get_session_strict_raises_when_no_active_pane(
+    server: Server,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """get_session(require_pane_resolution=True) raises when TMUX_PANE unset."""
     monkeypatch.delenv("TMUX_PANE", raising=False)
     monkeypatch.delenv("TMUX", raising=False)
 
     server.new_session(session_name="myfirstsession")
     server.new_session(session_name="mysecondsession")
 
     with pytest.raises(exc.SessionNotFound):
-        get_session(server)
+        get_session(server, require_pane_resolution=True)
 
 
 def test_get_pane_logs_debug_on_failure(