Qualify token-fenced leases for owned tmux sessions #805

Summary

Qualify an opt-in, server-lifetime lease for sessions owned by libtmux. Keep the feature experimental until acquisition, renewal, expiry, and stale-owner fencing meet the declared contract.

Motivation

A context manager can clean up when Python exits normally. It cannot guarantee cleanup after the owning client disappears. A lease can arrange eventual cleanup while the tmux server remains alive, but it needs stronger identity and race handling than a tag plus a local timer.

Evidence

rmux implements a session lease store with separate create, renew, and release handlers. A facade over stock tmux must supply that protocol using admitted tmux operations or an explicitly owned supervisor.

The current tmux conditional command implementation and run-shell timer implementation provide primitives to investigate. Their availability alone does not prove atomic lease acquisition or expiry under suspension.

Proposal

Implement only against a session created and owned by the helper. Scope the lease to the server incarnation, stable session identity, and a unique ownership generation.

• Specify the linearization point for acquisition and renewal. Prove that two contenders cannot both become the current owner under the supported concurrency model.
• Expiry and release must check the current ownership generation before destruction. A stale timer or former owner must not destroy a renewed or transferred session.
• A preserve operation relinquishes automatic cleanup and leaves the session alive.
• If cleanup must survive Python process death, arrange the timer in the server or an explicitly independent supervisor. An asyncio timer alone does not satisfy that contract.
• Document clock behavior, server suspension, restart, option edits, and external deletion. Report lease loss or unsupported behavior rather than implying perpetual ownership.
• Define the supported cooperation model. Public tmux options are coordination state, not protection against another client with access to the same server.
• Do not equate attachment count or destroy-unattached with lease ownership.
• Capability-gate timer and command behavior through Gate unsafe optional tmux features independently #778.

Acceptance requires simultaneous acquisition, renewed expiry, stale release, preserve, owning-client death, server replacement, suspension or a declared unsupported case, and cleanup failure. Use controlled event barriers and injected clocks where possible; a longer sleep or rerun does not establish correctness.

Independent MVP: Qualify an experimental lease for a session created by this helper through existing primitives. Include its own minimal ownership and capability checks, aligned with #804 and #778, without requiring those PRs. Keep the stable lease API gated on the declared concurrency and failure tests.

Alternatives

Explicit cleanup remains available without a lease. An independent recorder or supervisor can offer a separately specified persistence policy. No version of this proposal promises recovery after the tmux server and its session have been lost.

References

• [Agentic DX] libtmux: consolidated roadmap (core + async + engines) #629: automation and concurrency contracts.
• Server.__exit__ kills any live server, including one it did not start #724: shared-server ownership hazard.
• Gate unsafe optional tmux features independently #778: feature-specific admission.
• rmux lease implementation.

Delivery links: #629 (roadmap), #804 (owned create/reuse), and #778 (feature qualification). Lease qualification does not block the other helper APIs.

Implementation contract: ship this MVP in one PR against master, with other feature branches absent. Follow #629's shared API, type ownership, serialization, and engine-ops conformance rules. The original acceptance criteria remain the issue's full scope; deferred capabilities stay open.