Tests(feat[arena]): Audit two documentation pages on one lent server

why: an artifact could bind several pages but none did, so the capability was
unexercised and the cost it exists to avoid — one server per page — was still
being paid. Sharing a server also raises the question the single-page gate
never had to answer: whether the server a page finishes on is the one it
started on.

what:
- `python-workspace-and-location` audits `workspace_setup.md` and
  `self_location.md` together. Both take the server the fixture hands them.
- `context_managers.md` is excluded by name and reason, not by omission: every
  example there opens `with Server()`, which under the arena resolves to the
  lent socket, so leaving the block stops the borrowed server. An import-time
  guard refuses to load if any artifact ever names an excluded page, and the
  request is rejected before tmux is touched.
- The server's identity — pid, socket and challenge — is proved after each
  page, not only at the end, and a change names the page it happened after.
- Teardown reaps only the sessions the run created, diffed against a baseline
  taken before it, and only while the identity still matches. It never stops
  the server.
- A destructive test reproduces the failure this is for: a wrapper that stops
  the server between pages makes the run exit nonzero with no evidence, naming
  the page. Its control runs the two pages and proves identity between them.

Author: tony

conftest.py

@@ -21,7 +21,7 @@
 import pytest
 from _pytest.doctest import DoctestItem
 
-from libtmux._arena import ArenaSpec
+from libtmux._arena import ARENA_EXCLUDED_SOURCES, ArenaSpec
 from libtmux._internal.control_mode import ControlMode
 from libtmux.client import Client
 from libtmux.pane import Pane
@@ -33,6 +33,11 @@
 pytest_plugins = ["pytester"]
 
 ARENA_EVIDENCE_PREFIX = "LIBTMUX_ARENA_EVIDENCE="
+# One round-trip answers identity and the challenge together: pid and
+# socket_path prove *which* server answered, @libtmux_arena_challenge proves
+# it is still configured as the one that was lent (a silently spawned
+# replacement starts with no such option set).
+ARENA_IDENTITY_FORMAT = "#{pid}\t#{socket_path}\t#{@libtmux_arena_challenge}"
 ARENA_SPEC_KEY: pytest.StashKey[ArenaSpec] = pytest.StashKey()
 # A set rather than one path: an artifact may audit several pages, and the
 # supervisor then expects one evidence record per page.
@@ -49,6 +54,16 @@
 ARENA_PASSED_KEY: pytest.StashKey[dict[pathlib.Path, frozenset[str]]] = (
     pytest.StashKey()
 )
+# The identity captured once, before any page runs, so every later query has
+# something fixed to compare against rather than just "looks fine to itself".
+ARENA_IDENTITY_KEY: pytest.StashKey[tuple[int, str, str]] = pytest.StashKey()
+# Session names already on the lend before this run touched it, so teardown
+# can reap exactly what the run's own examples left behind and nothing else.
+ARENA_BASELINE_SESSIONS_KEY: pytest.StashKey[frozenset[str]] = pytest.StashKey()
+# The last node id collected per source, in the order pytest will actually
+# run them -- how the per-page identity check knows a page has finished
+# without guessing at item counts.
+ARENA_LAST_NODEID_KEY: pytest.StashKey[dict[pathlib.Path, str]] = pytest.StashKey()
 
 
 def _arena_spec(config: pytest.Config) -> ArenaSpec | None:
@@ -61,6 +76,75 @@ def _arena_targets(config: pytest.Config) -> frozenset[pathlib.Path] | None:
     return config.stash.get(ARENA_TARGETS_KEY, None)
 
 
+def _query_arena_identity(spec: ArenaSpec) -> tuple[int, str, str]:
+    """Return (pid, socket_path, challenge) for the endpoint ``spec`` names.
+
+    ``display-message`` only ever answers a server already listening on the
+    requested socket -- unlike ``new-session``, tmux does not spawn one to
+    service it (verified: a `list-sessions`/`display-message` against a
+    socket with nothing listening just errors, it never creates the socket
+    file). So this query itself can never be what silently starts the
+    replacement server a stopped lend produces.
+    """
+    server = Server(socket_path=spec.socket_path, tmux_bin=spec.tmux_bin)
+    result = server.cmd("display-message", "-p", ARENA_IDENTITY_FORMAT).stdout
+    if len(result) != 1:
+        msg = "arena server identity query returned an unexpected result"
+        raise RuntimeError(msg)
+    parts = result[0].split("\t", 2)
+    if len(parts) != 3 or parts[1] != spec.socket_path or not parts[2]:
+        msg = "arena server identity does not match the requested endpoint"
+        raise RuntimeError(msg)
+    return int(parts[0]), parts[1], parts[2]
+
+
+def _verify_arena_identity(
+    spec: ArenaSpec,
+    baseline: tuple[int, str, str],
+    where: str,
+) -> None:
+    """Raise, naming ``where``, if the lent server's identity has moved on.
+
+    ``where`` is the source whose examples just finished running, or "the
+    run" for the check just before evidence is published -- so a break is
+    attributed to the page after which it was detected, rather than only
+    discovered once every requested page has already run against whatever
+    answered next.
+    """
+    try:
+        observed = _query_arena_identity(spec)
+    except RuntimeError as exc_info:
+        msg = f"arena server identity check failed after {where!r}: {exc_info}"
+        raise RuntimeError(msg) from exc_info
+    if observed != baseline:
+        msg = (
+            f"arena server identity changed after {where!r}: expected "
+            f"pid/socket/challenge {baseline!r}, got {observed!r}"
+        )
+        raise RuntimeError(msg)
+
+
+def _reap_arena_sessions(spec: ArenaSpec, baseline_sessions: frozenset[str]) -> None:
+    """Kill every session this run's own examples left behind.
+
+    Idempotent: a session already gone (already reaped, or never existed)
+    is not an error. Scoped to the diff against ``baseline_sessions`` -- the
+    lend's own sessions from before this run touched it -- so a session that
+    predates the run, such as its hold session, is never a candidate.
+    """
+    server = Server(socket_path=spec.socket_path, tmux_bin=spec.tmux_bin)
+    current = {s.session_name for s in server.sessions if s.session_name is not None}
+    for name in sorted(current - baseline_sessions):
+        cleanup = server.cmd("kill-session", target=name)
+        already_gone = cleanup.returncode != 0 and any(
+            "can't find session" in line or "session not found" in line
+            for line in cleanup.stderr
+        )
+        if cleanup.returncode != 0 and not already_gone:
+            msg = f"arena teardown could not reap leaked session {name!r}"
+            raise RuntimeError(msg)
+
+
 def pytest_addoption(parser: pytest.Parser) -> None:
     """Register the source(s) selected by the arena adapter.
 
@@ -86,6 +170,22 @@ def pytest_configure(config: pytest.Config) -> None:
         return
 
     raw_targets = frozenset(config.getoption("libtmux_arena_target") or [])
+    excluded = {
+        source: ARENA_EXCLUDED_SOURCES[source]
+        for source in raw_targets
+        if source in ARENA_EXCLUDED_SOURCES
+    }
+    if excluded:
+        # Checked before the artifact's own tuple is even consulted: a
+        # source like this must be refused by name, not merely absent from
+        # ARENA_ARTIFACT_TARGETS -- the two look identical from outside a
+        # mismatch error otherwise.
+        reasons = "; ".join(
+            f"{source!r} ({reason})" for source, reason in sorted(excluded.items())
+        )
+        msg = f"arena refuses excluded source(s): {reasons}"
+        raise pytest.UsageError(msg)
+
     expected_relative = frozenset(
         p.as_posix() for p in spec.targets_for(pathlib.Path())
     )
@@ -97,6 +197,20 @@ def pytest_configure(config: pytest.Config) -> None:
     config.stash[ARENA_SPEC_KEY] = spec
     config.stash[ARENA_TARGETS_KEY] = targets
 
+    # Baseline, captured before any page runs: what "the lent server" and
+    # "its sessions" mean for the rest of this run. Every later identity
+    # check compares against this rather than against its own last query, so
+    # a slow drift across several pages cannot pass by always comparing
+    # favorably to the most recent (possibly already-wrong) reading.
+    try:
+        config.stash[ARENA_IDENTITY_KEY] = _query_arena_identity(spec)
+    except RuntimeError as exc_info:
+        raise pytest.UsageError(str(exc_info)) from exc_info
+    baseline_server = Server(socket_path=spec.socket_path, tmux_bin=spec.tmux_bin)
+    config.stash[ARENA_BASELINE_SESSIONS_KEY] = frozenset(
+        s.session_name for s in baseline_server.sessions if s.session_name is not None
+    )
+
 
 def pytest_collection_finish(session: pytest.Session) -> None:
     """Reject selections that include anything besides the audited sources."""
@@ -121,6 +235,17 @@ def pytest_collection_finish(session: pytest.Session) -> None:
         raise pytest.UsageError(msg)
     session.config.stash[ARENA_COLLECTED_KEY] = dict(discovered)
 
+    # The last node id per source, in the order pytest is actually about to
+    # run them (not the order they happened to be discovered in). This is
+    # how the per-page identity check recognizes "a page just finished"
+    # without hard-coding how many items any given page collects.
+    last_nodeid_by_path: dict[pathlib.Path, str] = {}
+    for item in session.items:
+        item_path = item.path.resolve()
+        if item_path in targets:
+            last_nodeid_by_path[item_path] = item.nodeid
+    session.config.stash[ARENA_LAST_NODEID_KEY] = last_nodeid_by_path
+
 
 def pytest_itemcollected(item: pytest.Item) -> None:
     """Record every arena item before pytest applies filters."""
@@ -218,6 +343,26 @@ def add_doctest_fixtures(
                 msg = "arena session cleanup failed"
                 raise RuntimeError(msg)
 
+            # Prove identity survived this page before the next one starts
+            # to run against whatever answers next. Only the item that is
+            # last (in run order) for its source checks -- an earlier item
+            # in the same page would just repeat a check its own page
+            # hasn't finished yet, and the page boundary is exactly where a
+            # doctest-content break (like the excluded context_managers.md's
+            # `with Server()`) would land.
+            last_nodeid_by_path = request.config.stash.get(
+                ARENA_LAST_NODEID_KEY,
+                {},
+            )
+            item_path = request._pyfuncitem.path.resolve()
+            if last_nodeid_by_path.get(item_path) == request._pyfuncitem.nodeid:
+                baseline = request.config.stash.get(ARENA_IDENTITY_KEY, None)
+                if baseline is not None:
+                    source = item_path.relative_to(
+                        request.config.rootpath,
+                    ).as_posix()
+                    _verify_arena_identity(spec, baseline, source)
+
 
 @pytest.fixture(autouse=True)
 def set_home(
@@ -248,9 +393,17 @@ def setup_session(
 
 
 def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
-    """Publish one evidence record per audited source, after all of them pass.
+    """Reap the run's stray sessions, then publish evidence once all pass.
 
-    fail-closed is preserved because ``exitstatus`` is only
+    Reaping runs whenever the identity captured at ``pytest_configure`` still
+    matches -- regardless of ``exitstatus`` -- so a run that fails for an
+    unrelated reason does not leave the lend dirtier than it found it.
+    It is skipped, not attempted against a guess, the moment identity no
+    longer matches: after a break (or a silent replacement) the socket may
+    not even be answering for the server this run was lent, and teardown
+    does not touch a tmux server it cannot first prove is that one.
+
+    fail-closed is preserved for evidence because ``exitstatus`` is only
     ``pytest.ExitCode.OK`` when every collected item passed; since collection
     already required every target to contribute at least one item
     (``pytest_collection_finish``), ``collected_by_target`` and
@@ -260,38 +413,42 @@ def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
     """
     spec = _arena_spec(session.config)
     targets = _arena_targets(session.config)
-    if spec is None or targets is None or exitstatus != pytest.ExitCode.OK:
+    if spec is None or targets is None:
         return
+
+    baseline_identity = session.config.stash.get(ARENA_IDENTITY_KEY, None)
+    baseline_sessions = session.config.stash.get(ARENA_BASELINE_SESSIONS_KEY, None)
+    try:
+        observed_identity = _query_arena_identity(spec)
+    except RuntimeError:
+        observed_identity = None
+    identity_intact = (
+        baseline_identity is not None and observed_identity == baseline_identity
+    )
+    if identity_intact and baseline_sessions is not None:
+        _reap_arena_sessions(spec, baseline_sessions)
+
     collected_by_target = session.config.stash.get(ARENA_COLLECTED_KEY, {})
     passed_by_target = session.config.stash.get(ARENA_PASSED_KEY, {})
     if (
-        not collected_by_target
+        exitstatus != pytest.ExitCode.OK
+        or not collected_by_target
         or collected_by_target.keys() != targets
         or passed_by_target != collected_by_target
         or session.config.getoption("collectonly")
     ):
         return
 
-    server = Server(socket_path=spec.socket_path, tmux_bin=spec.tmux_bin)
-    result = server.cmd(
-        "display-message",
-        "-p",
-        "#{pid}\t#{socket_path}\t#{@libtmux_arena_challenge}",
-    ).stdout
-    if len(result) != 1:
-        msg = "arena server identity query returned an unexpected result"
-        raise RuntimeError(msg)
-    parts = result[0].split("\t", 2)
-    if len(parts) != 3 or parts[1] != spec.socket_path or not parts[2]:
+    if baseline_identity is None or not identity_intact:
         msg = "arena server identity does not match the requested endpoint"
         raise RuntimeError(msg)
     for target in sorted(targets, key=lambda p: p.as_posix()):
         evidence = {
             "artifact": spec.artifact,
-            "challenge": parts[2],
+            "challenge": baseline_identity[2],
             "schema": 1,
-            "server_pid": int(parts[0]),
-            "socket_path": parts[1],
+            "server_pid": baseline_identity[0],
+            "socket_path": baseline_identity[1],
             "source": target.relative_to(session.config.rootpath).as_posix(),
         }
         print(

src/libtmux/_arena.py

@@ -9,8 +9,55 @@
 ARENA_ARTIFACT_TARGETS = {
     "python-exact-binary": ("docs/topics/workspace_setup.md",),
     "python-workspace-setup": ("docs/topics/workspace_setup.md",),
+    # The first artifact to actually exercise several sources against one
+    # lent server. Both pages only ever touch the `server`/`session` the
+    # arena fixture hands them -- neither constructs its own `Server()`, so
+    # neither can reach the lent daemon's own kill-server (see
+    # ARENA_EXCLUDED_SOURCES below for the page that does).
+    "python-workspace-and-location": (
+        "docs/topics/workspace_setup.md",
+        "docs/topics/self_location.md",
+    ),
 }
 
+# A source that must never run under the arena: its examples stop the lent
+# server rather than a private one. Named here so the refusal is a specific,
+# visible reason rather than an absence from ARENA_ARTIFACT_TARGETS -- the
+# two would otherwise look identical from the outside (a source rejected for
+# not matching the requested artifact's tuple looks like a typo, not a
+# safety rule).
+ARENA_EXCLUDED_SOURCES: dict[str, str] = {
+    "docs/topics/context_managers.md": (
+        "every example opens `with Server()`; in arena mode the doctest "
+        "namespace's `Server` name is bound to a factory pinned to the "
+        "lent socket path, so leaving the block runs Server.__exit__ -> "
+        "Server.kill() -> `kill-server` against the borrowed daemon "
+        "itself, not a private one"
+    ),
+}
+
+
+def _assert_no_excluded_targets(
+    artifact_targets: t.Mapping[str, tuple[str, ...]],
+) -> None:
+    """Refuse at import time if any artifact ever names an excluded source.
+
+    A mapping edit that adds an excluded page back in would otherwise only
+    surface the first time someone ran that artifact against a real lent
+    server -- by which point it may already have stopped it.
+    """
+    conflicts = {
+        artifact: sorted(overlap)
+        for artifact, sources in artifact_targets.items()
+        if (overlap := frozenset(sources) & ARENA_EXCLUDED_SOURCES.keys())
+    }
+    if conflicts:
+        msg = f"artifact(s) name an excluded arena source: {conflicts!r}"
+        raise AssertionError(msg)
+
+
+_assert_no_excluded_targets(ARENA_ARTIFACT_TARGETS)
+
 
 @dataclasses.dataclass(frozen=True)
 class ArenaSpec: