Skip to content

Server(fix[sessions,clients]): Return empty on tmux errors#677

Merged
tony merged 4 commits into
masterfrom
listing-behavior
May 18, 2026
Merged

Server(fix[sessions,clients]): Return empty on tmux errors#677
tony merged 4 commits into
masterfrom
listing-behavior

Conversation

@tony
Copy link
Copy Markdown
Member

@tony tony commented May 18, 2026

Summary

  • Restore lenient-by-default behavior for Server.sessions and Server.clients: tmux failures (socket permission errors, subprocess crashes, missing daemon, malformed output) once again yield an empty QueryList, matching the contract Server.sessions has carried since 0.17.0.
  • Revert a change in 0.57.0 that made these accessors raise LibTmuxException. Code written for 0.57.0 with try/except LibTmuxException around these accessors keeps working — the except clause just becomes unreachable.
  • Leave Server.search_sessions, Server.search_windows, and Server.search_panes raising — they take a caller-supplied filter, where a tmux error carries meaningful signal.
  • Codify the convention in AGENTS.md so future list-returning accessors don't drift toward loud-failure by default.

Behavior

Before (0.57.0):

try:
    clients = server.clients
except LibTmuxException as exc:
    log(f"list-clients failed: {exc}")
else:
    if not clients:
        log("no clients attached")

After (this PR):

if not server.clients:
    log("no clients attached or tmux unreachable")

For an explicit connectivity signal, callers use Server.is_alive() or Server.raise_if_dead() — both available since 0.17.0.

Scope

Accessor Behavior on tmux error
Server.sessions empty QueryList (restored)
Server.clients empty QueryList (restored)
Server.search_sessions raises LibTmuxException (unchanged from 0.57.0)
Server.search_windows raises LibTmuxException (unchanged from 0.57.0)
Server.search_panes raises LibTmuxException (unchanged from 0.57.0)

Test plan

  • test_server_sessions_returns_empty_on_tmux_errorServer.sessions returns QueryList([]) on simulated LibTmuxException
  • test_server_clients_returns_empty_on_tmux_error — same for Server.clients
  • test_server_sessions_permission_error_returns_empty — connection errors absorbed into the empty contract
  • test_server_sessions_missing_socket_returns_empty — fresh Server(socket_path=...) against a non-existent path returns empty (unchanged)
  • test_server_search_sessions_propagates_errorssearch_* methods still raise (unchanged)
  • uv run ruff check .
  • uv run mypy
  • uv run pytest --reruns 0
  • just build-docs

tony added 4 commits May 18, 2026 17:19
why: A change in 0.57.0 made Server.sessions and Server.clients
propagate LibTmuxException on any tmux failure (socket permission
errors, subprocess crashes, malformed output). That broke the
contract Server.sessions had carried since 0.17.0 and the one
Server.clients was born with: a list-shaped accessor returns an empty
QueryList when tmux cannot answer, and callers reach for
Server.is_alive() / Server.raise_if_dead() when they need an explicit
connectivity signal.

Restore that contract for both accessors. Server.search_sessions,
Server.search_windows, and Server.search_panes still raise; they take
a caller-supplied filter, so a tmux failure there is signal, not noise.

what:
- Wrap Server.sessions and Server.clients bodies in
  try/except LibTmuxException → QueryList([]). Both now call
  fetch_objs directly instead of routing through _fetch_or_empty —
  the broader try/except already absorbs the daemon-not-up case the
  helper exists for.
- Drop the Raises clause on Server.sessions; add prose pointing at
  is_alive/raise_if_dead for connectivity checks.
why: Lock in the lenient-by-default contract restored in the preceding
commit. A tmux failure under Server.sessions or Server.clients yields
an empty QueryList; connectivity checks go through Server.is_alive() /
Server.raise_if_dead().

what:
- Replace test_server_sessions_propagates_errors,
  test_server_clients_propagates_errors, and
  test_server_sessions_permission_error_propagates with
  test_server_sessions_returns_empty_on_tmux_error,
  test_server_clients_returns_empty_on_tmux_error, and
  test_server_sessions_permission_error_returns_empty.
- Leave the daemon-not-up and missing-socket tests unchanged.
why: Surface the revert in the unreleased section so the user-facing
release notes reflect the restored contract when the next version
ships.

what:
- Add a "Lenient Server.sessions and Server.clients accessors"
  deliverable under the unreleased entry placeholder.
- Add a "Stricter search_* methods" deliverable noting that the newer
  search_* accessors continue to raise.
- Leave the 0.57.0 entry intact — it accurately records what 0.57.0
  shipped.
why: 0.57.0's brief detour into raise-on-tmux-error for Server.sessions
and Server.clients (reverted in the preceding commits) showed the
convention isn't written down anywhere. Make it explicit so future
list-returning accessors don't drift toward loud-failure by default.

what:
- Add a "List-returning accessors: empty by default on tmux errors"
  subsection under tmux-Specific Considerations. States the contract
  for Server.sessions / Server.clients / Server.attached_sessions,
  points at Server.is_alive() / Server.raise_if_dead() as the
  explicit-check primitives, and asks any future loud-failure mode to
  be a scoped opt-in instead of a baked-in raise on a new accessor.
@codecov
Copy link
Copy Markdown

codecov Bot commented May 18, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 51.37%. Comparing base (4acee52) to head (874108f).

Additional details and impacted files
@@            Coverage Diff             @@
##           master     #677      +/-   ##
==========================================
+ Coverage   51.26%   51.37%   +0.11%     
==========================================
  Files          25       25              
  Lines        3482     3488       +6     
  Branches      686      686              
==========================================
+ Hits         1785     1792       +7     
+ Misses       1403     1401       -2     
- Partials      294      295       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@tony tony merged commit 90359dd into master May 18, 2026
13 checks passed
@tony tony deleted the listing-behavior branch May 18, 2026 22:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant