mcp(fix[list]): Fail when tmux cannot be asked, not list nothing

why: Server.sessions, windows and panes answer an empty list when the
list command fails, so a socket the user may not open looked like a
server with nothing on it and an agent created a duplicate workspace.

what:
- List through libtmux's strict fetch_sessions, fetch_windows and
  fetch_panes; a socket with no server behind it is still empty
- Any other failure raises ListCommandFailed, mapped to a tool error
  that says the server is unreachable, not empty
- Test both; the permission test fails on the lenient listing

Author: tony

CHANGES

@@ -32,6 +32,14 @@ scrollback of the new session's panes before a long job starts.
 
 ### Fixes
 
+**A socket tmux cannot open is an error, not an empty list**
+
+`list_sessions`, `list_windows` and `list_panes` used to answer `[]` when tmux
+could not be asked at all, such as a socket without read permission, so an
+agent concluded there was nothing to attach to. They now fail with the tmux
+message and a hint, and keep returning `[]` for a socket with no server behind
+it.
+
 **`capture_since` reports a flood that scrolls the cursor out of a full history**
 
 When a burst of output fills the scrollback and discards the row the cursor

src/libtmux_mcp/_utils.py

@@ -18,7 +18,7 @@
 
 from fastmcp.exceptions import ToolError
 from libtmux import exc
-from libtmux._internal.query_list import LOOKUP_NAME_MAP
+from libtmux._internal.query_list import LOOKUP_NAME_MAP, QueryList
 from libtmux.server import Server
 
 if t.TYPE_CHECKING:
@@ -925,6 +925,37 @@ def _coerce_dict_arg(
     return value
 
 
+#: Fragments of a ``list-*`` failure that mean "no server is running here".
+#: That is a normal, empty state for a socket nobody started; any other
+#: failure (permission denied, a server that died mid-call) is not.
+_NO_SERVER_MARKERS = (
+    "no server running",
+    "No such file or directory",
+    "Connection refused",
+)
+
+
+def _list_objects(fetch: t.Callable[[], list[t.Any]]) -> QueryList[t.Any]:
+    """Run one of libtmux's strict ``fetch_*`` listings as a ``QueryList``.
+
+    ``Server.sessions`` and friends return an empty list when tmux cannot be
+    asked, so a socket the user may not open looks like a server with
+    nothing on it. A socket with no server behind it is still empty here;
+    every other failure raises.
+
+    Raises
+    ------
+    libtmux.exc.ListCommandFailed
+        When tmux fails for a reason other than "no server is running".
+    """
+    try:
+        return QueryList(fetch())
+    except exc.ListCommandFailed as e:
+        if any(marker in str(e) for marker in _NO_SERVER_MARKERS):
+            return QueryList([])
+        raise
+
+
 def _apply_filters(
     items: t.Any,
     filters: dict[str, str] | str | None,

src/libtmux_mcp/tools/server_tools.py

@@ -24,6 +24,7 @@
     _get_caller_identity,
     _get_server,
     _invalidate_server,
+    _list_objects,
     _prepare_start_directory,
     _serialize_session,
     handle_tool_errors,
@@ -62,7 +63,7 @@ def list_sessions(
         List of session objects.
     """
     server = _get_server(socket_name=socket_name)
-    sessions = server.sessions
+    sessions = _list_objects(server.fetch_sessions)
     return _apply_filters(sessions, filters, _serialize_session)
 
 

src/libtmux_mcp/tools/session_tools.py

@@ -20,6 +20,7 @@
     _escape_tmux_format,
     _get_caller_identity,
     _get_server,
+    _list_objects,
     _prepare_start_directory,
     _resolve_session,
     _serialize_session,
@@ -71,7 +72,7 @@ def list_windows(
         )
         windows = session.windows
     else:
-        windows = server.windows
+        windows = _list_objects(server.fetch_windows)
     return _apply_filters(windows, filters, _serialize_window)
 
 

src/libtmux_mcp/tools/window_tools.py

@@ -20,6 +20,7 @@
     _escape_tmux_format,
     _get_caller_identity,
     _get_server,
+    _list_objects,
     _prepare_start_directory,
     _resolve_pane,
     _resolve_session,
@@ -97,7 +98,7 @@ def list_panes(
         )
         panes = session.panes
     else:
-        panes = server.panes
+        panes = _list_objects(server.fetch_panes)
     return _apply_filters(panes, filters, _serialize_pane)
 
 

tests/test_middleware.py

@@ -658,9 +658,9 @@ def _fail(_self: Server) -> list[t.Any]:
         nonlocal calls
         calls += 1
         msg = "forced failure"
-        raise libtmux_exc.LibTmuxException(msg)
+        raise libtmux_exc.ListCommandFailed(msg, list_cmd="list-sessions")
 
-    monkeypatch.setattr(Server, "sessions", property(_fail))
+    monkeypatch.setattr(Server, "fetch_sessions", _fail)
 
     async def _call() -> t.Any:
         async with Client(build_mcp_server()) as client:

tests/test_server_tools.py

@@ -505,3 +505,44 @@ def test_create_session_history_limit_reaches_the_pane(mcp_server: Server) -> No
     pane = session.active_pane
     assert pane is not None
     assert pane.display_message("#{history_limit}", get_text=True) == ["123"]
+
+
+def test_list_tools_treat_a_socket_without_a_server_as_empty() -> None:
+    """A socket nobody started lists nothing instead of failing."""
+    from libtmux_mcp.tools.server_tools import list_sessions
+    from libtmux_mcp.tools.session_tools import list_windows
+    from libtmux_mcp.tools.window_tools import list_panes
+
+    socket_name = "libtmux_mcp_never_started"
+    assert list_sessions(socket_name=socket_name) == []
+    assert list_windows(socket_name=socket_name) == []
+    assert list_panes(socket_name=socket_name) == []
+
+
+@pytest.mark.skipif(os.geteuid() == 0, reason="root ignores directory permissions")
+def test_list_sessions_reports_a_socket_it_cannot_open(
+    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """An unreadable socket is an error, not an empty server.
+
+    ``Server.sessions`` answers ``[]`` here, so an agent would conclude there
+    is nothing to attach to and create a duplicate workspace.
+    """
+    from fastmcp.exceptions import ToolError
+
+    from libtmux_mcp._utils import _server_cache
+    from libtmux_mcp.tools.server_tools import list_sessions
+
+    socket_dir = tmp_path / f"tmux-{os.geteuid()}"
+    socket_dir.mkdir()
+    (socket_dir / "locked").touch()
+    socket_dir.chmod(0o000)
+    monkeypatch.setenv("TMUX_TMPDIR", str(tmp_path))
+    _server_cache.clear()
+    try:
+        with pytest.raises(ToolError, match="Permission denied") as excinfo:
+            list_sessions(socket_name="locked")
+        assert "unreachable" in (getattr(excinfo.value, "suggestion", None) or "")
+    finally:
+        socket_dir.chmod(0o700)
+        _server_cache.clear()