feat(Server,Session,Window,Pane): Resolve the pane you run inside (from_env)

[tony]

Refs #704 (addresses its self-location half; the papercuts in its §3 are untouched and still want owners). Supersedes #705.

Stacked on #713 — review that first; this PR's diff is only its own six commits. It cannot answer "which session am I in?" correctly without the resolution fix that #713 lands.

The problem

A process running inside tmux — a script in a split, a hook, a test harness, an agent — could not ask libtmux where it was. It had to hand-roll the answer, and the obvious hand-roll is wrong.

tmux exports two variables into every pane it spawns (environ.c:277-282, spawn.c:325):

TMUX="<socket_path>,<server_pid>,<session_id>"
TMUX_PANE="%3"

The trap is session_id. tmux writes these once, at spawn, and never revises them — grep 3.7b for every other reference and you find only reads. So that session id records where the process was launched, not where it is. Move the pane's window to another session and the id is simply wrong; the session may not even exist any more.

The parse is a trap too. split(",") splits from the left, so a socket path containing a comma — which tmux permits, via -S, -L or TMUX_TMPDIR — shears into garbage. The pid and session id are integers, so every comma but the last two belongs to the path: the only correct parse is rsplit(",", 2).

And if you do read the session id, tmux spells it bare (47) where libtmux spells the same session $47, so it needs normalising before it is good for anything. The conclusion this PR draws is simpler: don't read it.

The API

>>> Pane.from_env()        # the pane you are running in
>>> Window.from_env()      # the window that contains you
>>> Session.from_env()     # the session that holds you
>>> Server.from_env()      # the server you are on

Each takes an optional env mapping (defaulting to os.environ) so it is testable without a real pane.

from_env reads only the socket path out of TMUX, anchors on TMUX_PANE, and asks tmux for everything else. So the answer stays correct after a move-window, and for a window linked into several sessions it is the session tmux itself would act on — because tmux is what resolved it. Server.from_env() runs no tmux command at all; it is a pure read of the environment.

The session id in TMUX is never consulted. Not as a fallback, not as a tie-break.

Outside a pane, or with a TMUX that does not parse, the family raises NotInsideTmux rather than guessing.

Two details worth a reviewer's eye

Window.from_env resolves through cls.from_window_id, not by traversing off the pane. return Pane.from_env(env).window would have been shorter and would silently hand a base Window back to a subclass. test_from_env_returns_the_class_it_was_called_on pins this for all four constructors. Session.from_env mirrors it through cls.from_session_id, and both raise the same ValueError when the resolved pane names no parent — the guard that stands in for the assert a python -O run strips.

pane_id_from_env rejects a TMUX_PANE without its % sigil. The sigil is load-bearing: tmux's cmd_find routes a target to its pane slot by sigil, so a sigil-less value is matched against session names and silently resolves to the wrong object. Guessing here produces a wrong answer with no error, so it raises instead.

Also in this PR

Server.__init__ derived socket_path from TMUX_TMPDIR in a branch that could never execute: it required both socket_name is None and socket_name != "default", and socket_name is defaulted to "default" two lines above. Removed. Guessing the path would have been wrong anyway — tmux resolves a -L name against its own socket directory, honouring TMUX_TMPDIR, the per-uid directory, and platform overrides. Callers that need the real path ask tmux (#{socket_path}).

The -1 session id is documented for what it actually is. tmux writes it only when it builds an environment with no session, and the sole caller that passes none is the #() format job (format.c:417 → job_run(..., NULL, ...), and environ.c's environ_for_session() writes -1 exactly when s == NULL). run-shell hands job_run its target session (cmd-run-shell.c:208), so its children carry a real session id. Neither kind of job child gets TMUX_PANE — spawn.c:325 is the only place tmux sets it — so a process holding a pane id always has a real session beside it, and -1 can never reach from_env.

Not in this PR

Reading the spawn session — "which session launched me?", as distinct from "which session am I in?" — is a real question with a real audience, and it is deliberately out of scope here. Proposed separately in #712.

There is no Client.from_env(): a pane is not owned by a client, tmux exports no client id into one, and there may be zero clients attached or several. See the topic page.

Docs

New topic page, self_location, linked from the topics index and from traversal, plus front-page examples in the README and docs index, and TMUX / TMUX_PANE in the glossary.

It also corrects a claim in docs/AGENTS.md that costs real time: it said the code blocks on a docs page share one doctest session and that their order is load-bearing state. They do not — every fenced block is an independent pytest item with a fresh namespace and a fresh tmux server. (I re-proved this by walking straight into it while writing the new page.)

Verification

ruff · ruff format · mypy · pytest --reruns 0 · just build-docs — all green locally, and CI is green across the full matrix (3.2a → master).

Tests use parametrized NamedTuple fixtures with test_id, and cover the error paths as well as the happy one: malformed TMUX, a sigil-less TMUX_PANE, a comma in the socket path, a stale session id, a linked window, move-window, the containing window vs the active one, a pane that names no parent, a missing pane on a live server, a dead server, and subclass identity for all four constructors.

[codecov]

Codecov Report

❌ Patch coverage is 63.82979% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.14%. Comparing base (1102472) to head (a98a7fe).

Files with missing lines	Patch %	Lines
src/libtmux/_internal/env.py	66.66%	7 Missing ⚠️
src/libtmux/exc.py	60.00%	2 Missing ⚠️
src/libtmux/pane.py	50.00%	2 Missing ⚠️
src/libtmux/server.py	33.33%	2 Missing ⚠️
src/libtmux/session.py	71.42%	2 Missing ⚠️
src/libtmux/window.py	71.42%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #714      +/-   ##
==========================================
+ Coverage   51.85%   52.14%   +0.29%     
==========================================
  Files          25       26       +1     
  Lines        3645     3688      +43     
  Branches      735      741       +6     
==========================================
+ Hits         1890     1923      +33     
- Misses       1449     1461      +12     
+ Partials      306      304       -2     

☔ 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.