[tony]

Discover local tmux servers when their socket names are not known. TmuxLobby.servers returns a QueryList[TmuxLobbyServer] with socket paths, owner IDs, liveness, PID/version metadata, and access to sessions, windows, and panes. Failed probes remain queryable with an error diagnostic.

from libtmux.contrib.lobby import TmuxLobby

servers = TmuxLobby.servers.filter(alive=True)
lobby = TmuxLobby(paths=["~/.local/run/tmux"], patterns=["~/projects/**/.tmux.sock"])
servers = lobby.servers.filter(socket_name__startswith="work")

Default discovery searches the current user's tmux socket directories under /tmp and TMUX_TMPDIR, plus the socket in TMUX. Custom paths and patterns extend those locations; include_defaults=False replaces them. Each access rescans, resolves socket aliases, deduplicates paths, and probes candidates sequentially without starting servers. A failed probe does not establish whether the socket belongs to tmux.

Probes have a configurable one-second timeout. The supporting Server.cmd and tmux_cmd timeout kills and reaps the expired client while preserving the server. The probe timeout does not apply to subsequent object queries.

The introduction, API reference, and executable examples live under docs/contrib/lobby/.

Validation:

• Full pytest run: 1,495 passed, 1 skipped, 1 rerun with two workers.
• Focused lobby tests and documentation examples: 40 passed on tmux 3.2a and 3.7d.
• Ruff formatting/lint, strict mypy, Sphinx with warnings treated as errors, and wheel/sdist builds passed.
• Deliberate breaks in liveness, socket detection, deduplication, and client reaping each failed their targeted test. A broken documentation reference failed the strict documentation build.

A four-worker run hit the unchanged marker-capture automation doctest. That page passed separately on both the baseline and this branch; the complete two-worker run passed.

[codecov]

Codecov Report

❌ Patch coverage is 98.31933% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 53.83%. Comparing base (500f99b) to head (5f46b54).

Files with missing lines	Patch %	Lines
src/libtmux/common.py	77.77%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #764      +/-   ##
==========================================
+ Coverage   52.37%   53.83%   +1.46%     
==========================================
  Files          26       28       +2     
  Lines        3729     3845     +116     
  Branches      747      765      +18     
==========================================
+ Hits         1953     2070     +117     
+ Misses       1472     1471       -1     
  Partials      304      304              

☔ View full report in Codecov by Harness.
📢 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.