tmux(fix[errors]): Keep resource errors native

why: The branch wrapped every unrelated launch OSError in
LibTmuxException. That changed trunk behavior for E2BIG and similar
failures even though only unavailable executables need normalization.

what:
- Re-raise unrelated launch OSError values unchanged from direct APIs
- Catch and log those errors only at lenient list boundaries
- Document direct and lenient exception behavior
- Cover all three list accessors and supported tmux builds

Author: tony

docs/topics/logging.md

@@ -105,13 +105,15 @@ failures remain exception data, so callers decide whether and where to log
 them. Expected probes such as {meth}`Server.is_alive()
 <libtmux.Server.is_alive>` also stay quiet.
 
-Executable launch failures use {exc}`~libtmux.exc.TmuxCommandNotFound`.
-When the operating system attempted the launch, the exception retains its
-message and cause. A failed `PATH` lookup has a factual message without a
-synthetic cause.
-
-Three list-shaped accessors intentionally hide
-{exc}`~libtmux.exc.LibTmuxException`:
+Missing, non-executable, and malformed tmux executables use
+{exc}`~libtmux.exc.TmuxCommandNotFound`. When the operating system attempted
+the launch, the exception retains its message and cause. A failed `PATH`
+lookup has a factual message without a synthetic cause. Other operating-system
+launch errors remain native exceptions at direct APIs.
+
+Three list-shaped accessors intentionally hide tmux execution failures,
+including {exc}`~libtmux.exc.LibTmuxException` and operating-system launch
+errors:
 
 - {attr}`Server.sessions <libtmux.Server.sessions>`;
 - {attr}`Server.attached_sessions <libtmux.Server.attached_sessions>`;

src/libtmux/AGENTS.md

@@ -71,14 +71,14 @@ an `ERROR` because probes use it to answer false.
 
 Normalize executable-launch `ENOENT`, `EACCES`, and `ENOEXEC` errors to
 `TmuxCommandNotFound`, preserving the operating-system message and cause.
-Keep unrelated `OSError` behavior caller-specific. A failed `PATH` preflight
-uses a factual message without inventing a cause.
+Keep unrelated `OSError` values native at direct loud APIs. A failed `PATH`
+preflight uses a factual message without inventing a cause.
 
 `Server.sessions` and `Server.clients` log once in
-`libtmux.server` when they convert `LibTmuxException` to an empty
-result. `Server.attached_sessions` inherits that behavior through
-`Server.sessions`. The boundary record includes the subcommand,
-socket, first 100 stderr lines, and total stderr line count.
+`libtmux.server` when they convert `LibTmuxException` or an OS launch failure
+to an empty result. `Server.attached_sessions` inherits that behavior through
+`Server.sessions`. The boundary record includes the subcommand, socket, first
+100 stderr lines, and total stderr line count.
 
 Deprecations and ignored arguments use `warnings.warn`, not a second
 log record. Applications can route them through

src/libtmux/common.py

@@ -296,6 +296,13 @@ class tmux_cmd:
 
         $ tmux new-session -s my session
 
+    Raises
+    ------
+    :exc:`~libtmux.exc.TmuxCommandNotFound`
+        When the tmux binary cannot be found or executed.
+    :class:`OSError`
+        When the operating system rejects the launch for another reason.
+
     Notes
     -----
     .. versionchanged:: 0.8
@@ -329,7 +336,7 @@ def __init__(self, *args: t.Any, tmux_bin: str | None = None) -> None:
             )
         except OSError as error:
             _raise_if_unusable_tmux(error)
-            raise exc.LibTmuxException(str(error)) from error
+            raise
 
         stdout, stderr = self.process.communicate()
         returncode = self.process.returncode

src/libtmux/server.py

@@ -92,7 +92,7 @@ def _fetch_or_empty(
 def _log_swallowed_list_error(
     server: Server,
     list_cmd: str,
-    error: exc.LibTmuxException,
+    error: Exception,
 ) -> None:
     """Record a list failure at the boundary that converts it to empty."""
     stderr = str(error).splitlines()
@@ -339,6 +339,8 @@ def raise_if_dead(self) -> None:
         :class:`subprocess.CalledProcessError`
             When the tmux server is not running (non-zero exit from
             ``list-sessions``).
+        :class:`OSError`
+            When the operating system rejects the launch for another reason.
 
         >>> tmux = Server(socket_name="no_exist")
         >>> try:
@@ -2473,7 +2475,7 @@ def sessions(self) -> QueryList[Session]:
                 Session(server=self, **obj)
                 for obj in fetch_objs(server=self, list_cmd="list-sessions")
             ]
-        except exc.LibTmuxException as error:
+        except (exc.LibTmuxException, OSError) as error:
             _log_swallowed_list_error(self, "list-sessions", error)
             return QueryList([])
         return QueryList(sessions)
@@ -2547,7 +2549,7 @@ def clients(self) -> QueryList[Client]:
                 Client(server=self, **obj)
                 for obj in fetch_objs(server=self, list_cmd="list-clients")
             ]
-        except exc.LibTmuxException as error:
+        except (exc.LibTmuxException, OSError) as error:
             _log_swallowed_list_error(self, "list-clients", error)
             return QueryList([])
         return QueryList(clients)

tests/test_logging.py

@@ -482,19 +482,49 @@ def test_lenient_accessors_log_unusable_tmux_diagnostics(
         assert str(tmux_path) in diagnostic
 
 
-def test_unrelated_tmux_launch_failure_preserves_diagnostics() -> None:
-    """A launch resource failure is not mislabeled as a missing executable."""
+def test_tmux_cmd_unrelated_launch_failure_stays_os_error() -> None:
+    """A direct launch resource failure retains trunk's native exception."""
     from libtmux import exc
     from libtmux.common import tmux_cmd
 
-    with pytest.raises(exc.LibTmuxException) as exc_info:
+    with pytest.raises(OSError) as exc_info:
         tmux_cmd("set-buffer", "x" * os.sysconf("SC_ARG_MAX"))
 
     assert not isinstance(exc_info.value, exc.TmuxCommandNotFound)
-    cause = exc_info.value.__cause__
-    assert isinstance(cause, OSError)
-    assert cause.errno == errno.E2BIG
-    assert str(exc_info.value) == str(cause)
+    assert exc_info.value.errno == errno.E2BIG
+
+
+@pytest.mark.parametrize(
+    ("accessor", "list_cmd"),
+    [
+        ("sessions", "list-sessions"),
+        ("attached_sessions", "list-sessions"),
+        ("clients", "list-clients"),
+    ],
+)
+def test_lenient_accessors_log_unrelated_launch_failure(
+    accessor: str,
+    list_cmd: str,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Lenient list boundaries still swallow a raw launch resource error."""
+    from libtmux.server import Server
+
+    def raise_e2big(*args: object, **kwargs: object) -> None:
+        raise OSError(errno.E2BIG, os.strerror(errno.E2BIG), "/configured/tmux")
+
+    monkeypatch.setattr("libtmux.common.subprocess.Popen", raise_e2big)
+    server = Server(tmux_bin="/configured/tmux")
+    with caplog.at_level(logging.ERROR, logger="libtmux.server"):
+        assert list(getattr(server, accessor)) == []
+
+    records = [record for record in caplog.records if record.levelno == logging.ERROR]
+    assert len(records) == 1
+    record = t.cast(t.Any, records[0])
+    assert record.tmux_subcommand == list_cmd
+    assert record.tmux_stderr_len == 1
+    assert os.strerror(errno.E2BIG) in record.tmux_stderr[0]
 
 
 def test_raise_if_dead_unrelated_launch_failure_stays_os_error() -> None: