Scoping a Server no longer kills it

[tony]

Breaking change. Read the Before / After below before merging.

Summary

• Fix with Server() as server: destroying a tmux daemon it had nothing to do with. __exit__ was if self.is_alive(): self.kill(), unconditionally — so a block that did no work at all took out the reader's default server and every session in it.
• Change the default: leaving the block kills nothing.
• Add kill_on_exit for when teardown is what you want.
• Document why a server differs from a session, window and pane, on Server, __exit__, and in docs/topics/context_managers.md.

Why scoping is not ownership

A Server is a handle on a socket, not a connection. The same handle addresses a daemon whether or not this process started it, and a bare Server() addresses the default socket — usually the tmux the reader has been working in all day. Entering a with block says "I want this scoped", not "I am entitled to destroy this".

Session, Window and Pane are different in kind, and stay as they are: you got them by calling new_session() or split(), so the block really did create them.

Before / After

Server(socket_name="my-work").new_session(session_name="important")

with Server(socket_name="my-work") as server:
    pass

Server(socket_name="my-work").is_alive()   # False — the session is gone

Server(socket_name="my-work").new_session(session_name="important")

with Server(socket_name="my-work") as server:
    pass

Server(socket_name="my-work").is_alive()   # True — nothing was asked for

Ask for teardown explicitly:

with Server(socket_name="build", kill_on_exit=True) as server:
    server.new_session(session_name="ci")

Design decisions

Inference was implemented, then rejected. An earlier revision of this branch had __enter__ record whether the daemon was already alive and __exit__ kill only one the block started. It reads well and has real precedent — zipfile._filePassed, tarfile._extfileobj, gzip.myfileobj all decide cleanup by whether they opened the resource. It was dropped for two reasons.

The first is a defect. The ownership signal was is_alive(), which catches bare Exception and returns False by contract — every way of failing to reach a server is a "no". So a transient tmux failure at __enter__ would have read as "this block started it", and __exit__ would have killed a daemon that predated the block. That is this issue's bug, reachable through a different door, and closing it would have meant hardening a deliberately lenient predicate into a strict one.

The second is that the stdlib's inference cases infer from provenance — what the object did — not from liveness. Server has no provenance to record: the socket does not say who started the daemon. Inference here was a guess wearing the costume of a fact.

Explicit opt-in has its own precedent, including in languages built around ownership. subprocess.Popen.__exit__ unambiguously owns its child and still does not kill it. sqlite3.Connection.__exit__ commits or rolls back and never closes. Rust's std::process::Child has no impl Drop at all — "The standard library does not automatically wait on child processes (not even if the Child is dropped), it is up to the application developer to do so."

kill_on_exit is a plain bool, not a tri-state. With no inference there is no third state to spell. It also matches the codebase: every one of libtmux's 188 bool | None parameters is consumed as if x is not None and x:, so None already means False here — a None meaning "maybe kill" would have inverted the house idiom in the destructive direction.

The name is action-shaped on purpose. libtmux already ships Pane.display_popup(close_on_exit=...), and tmux's own vocabulary is remain-on-exit, exit-empty. An ownership-shaped name (owns_server) would assert a fact libtmux cannot verify.

No temp_server() helper. temp_server is already a doc anchor for the TestServer fixture, which creates auto-cleaned servers. A scoped-server helper can be designed on its own merits later.

Test plan

• test_server_context_manager — the default leaves a server alive, including one the block started. This previously asserted the opposite; the change is the breaking change made visible in the suite
• test_server_context_manager_spares_pre_existing_server — a pre-existing server survives an empty block
• test_server_context_manager_spares_the_default_socket — a bare Server() under a monkeypatched $TMUX_TMPDIR. Every other test routes through the TestServer factory, which mints a private socket and structurally cannot reproduce this issue's shape
• test_server_context_manager_kill_on_exit_true — the opt-in kills a server the block did not start
• test_server_context_manager_kill_on_exit_true_when_block_started_it — and one it did
• Doctests on Server, __enter__, __exit__, plus the reworked docs/topics/context_managers.md — all collected and run
• Full suite clean, including libtmux.pytest_plugin, which leans on server teardown
• uv run ruff check . / uv run ruff format . / uv run mypy clean
• just build-docs clean

Follow-up, not in this PR

Session.from_session_id, Window.from_window_id and Pane.from_pane_id all exist, so a child handle can be obtained without creating the object — with Window.from_window_id(...) kills a window you did not make. Same bug class, smaller blast radius, and worth its own issue rather than widening this one.

Note for the merger

CHANGES will conflict with the sibling PRs for #723, #725 and #726, which all add to the same block — keep both sides. This one lands under ### Breaking changes.

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.35%. Comparing base (be7c8c1) to head (9114092).

Files with missing lines	Patch %	Lines
src/libtmux/server.py	50.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #728      +/-   ##
==========================================
- Coverage   52.45%   52.35%   -0.10%     
==========================================
  Files          26       26              
  Lines        3729     3732       +3     
  Branches      747      747              
==========================================
- Hits         1956     1954       -2     
- Misses       1469     1474       +5     
  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.

[tony]

Code review

Found 1 issue:

1. Two sections further down context_managers.md still promise the old behaviour, so the page now contradicts itself. The commit message says it reworked the page "which promised unconditional teardown for all four classes" — two of those promises survive.

libtmux/docs/topics/context_managers.md

Lines 117 to 141 in 7ea0444

	## Nested context managers
	For complex setups, you can nest contexts to build a whole tmux hierarchy at
	once and have every layer torn down for you:
	```python
	>>> with Server() as server:
	... with server.new_session() as session:
	... with session.new_window() as window:
	... with window.split() as pane:
	... pane.send_keys('echo "Hello"')
	... # Do work with the pane
	... # Everything is cleaned up automatically when exiting contexts
	```
	This ensures that:
	1. The pane is killed when exiting its context
	2. The window is killed when exiting its context
	3. The session is killed when exiting its context
	4. The server is killed when exiting its context
	The cleanup happens in reverse order (pane → window → session → server), ensuring proper resource management.

"Nested context managers" still says the block gives you "every layer torn down for you", and item 4 reads "The server is killed when exiting its context". The with Server() as server: example immediately above it now leaves the daemon running.

libtmux/docs/topics/context_managers.md

Lines 142 to 149 in 7ea0444

	## Benefits
	Reaching for a context manager buys you a few things. Resources clean themselves
	up the moment you leave the block, so you never manually call the
	{meth}`~libtmux.Server.kill`, {meth}`~libtmux.Session.kill`,
	{meth}`~libtmux.Window.kill`, or {meth}`~libtmux.Pane.kill` methods and the code
	stays uncluttered. Because cleanup runs on the way out of the block, it fires
	even when an exception unwinds the stack — so you don't leak a stray session or

"Benefits" then says "you never manually call the {meth}~libtmux.Server.kill ... methods", which is exactly what a reader now has to do.

The doctests cannot catch this: the nested block asserts no output, so the prose can drift from the behaviour silently. docs/AGENTS.md asks, in its pre-commit checklist, "Do the doctests run, and did you leave every code block, table, error string, and cross-reference exact?"

libtmux/docs/AGENTS.md

Lines 145 to 150 in 7ea0444

	named by concept instead?
	- Are the advanced and lower-level parts clearly marked opt-in?
	- Do the doctests run, and did you leave every code block, table, error
	string, and cross-reference exact?
	- Did `just build-docs` stay clean — no new warning, no broken
	cross-reference?

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}