Create or reuse tmux resources with explicit cleanup ownership #804

Problem

Repeating setup must identify an existing resource without attaching to it, changing its creation settings, or acquiring permission to delete it. A successful native command does not always return a newly created ID, and a lookup followed by creation can race another creator.

Example

Two callers both find no session named build. One creates it before the other submits creation. The second caller should recover the exact matching session from that expected conflict and report reuse; it must preserve unrelated errors. If a later setup step fails, cleanup must preserve the reused session. Separately, a window that already exists can make native new-window -S -P succeed without returning creation output; parsing that result as a newly created window is incorrect.

These are separate native paths: tmux 3.8's new-session -A invokes attachment when it finds an existing session. Its new-window -S returns early on reuse, before the later -P creation output. Neither shortcut alone supplies the proposed Python ownership result.

Potential solution

Provide explicit create-only, reuse-only, and create-or-reuse helpers. Use one resolved server endpoint throughout the operation. Return stable identity plus explicit created/reused disposition. Re-read after an expected creation conflict, with a bounded reconciliation attempt; do not retry unrelated or uncertain mutations. Apply creation options only to newly created resources. Cleanup requires positive creation provenance and a sufficiently established resource lifetime, not a matching name. The broader candidates in #771 and #758 require qualification against this scope.

#724 covers the existing Server context-manager destruction bug. This proposal covers creation results and compensating cleanup for multi-step builders; it does not replace or broaden that bug fix.

Evidence

The existing Python session-creation entry point supplies the underlying operation. rmux's ensure helpers and owned-session handle separate reuse from ownership.

#689 explicitly defers rollback semantics for multi-operation plans. The useful library-level promise is cleanup of known newly created resources, with retained failure information.

Requirements and acceptance

Return a result identifying the server incarnation, stable tmux ID, and whether the operation created or reused the resource.

• Use exact lookup and reconcile an expected creation conflict by re-reading the winner. Preserve unrelated errors.
• Apply creation configuration only when creation succeeds. Reuse does not reconcile environment, command, layout, or options unless a separate explicit operation requests that.
• Track resources actually created by each builder step. On failure, clean up owned descendants in dependency order.
• Preserve borrowed sessions, windows, panes, engines, and pre-existing pipes or buffers.
• Keep the original failure and cleanup failures available together.
• Treat a timeout after submission as uncertain. Reconcile only from verifiable identity or operation provenance; do not destroy a resource merely because its name matches.
• Invalidate handles on detected server replacement. Names, tags, and numeric IDs alone are insufficient ownership proof across replacement.
• Provide explicit cleanup and preserve/detach operations. Finalizers are best effort and must not be the only cleanup mechanism.
• Keep existing constructors and context-manager behavior governed by their own compatibility decisions.

Acceptance covers concurrent creators with one winner and reuse results; resource deletion between lookup and creation; failure after creating a child in a borrowed session; cleanup failure; and ambiguous command completion. The borrowed parent must survive every cleanup path.

Independent MVP: Deliver exact session create/reuse results and cleanup only for sessions this helper created. Use existing creation commands and explicit ownership; avoid the legacy Server context manager so #724 is not a prerequisite. Preserve #689 outcome semantics through a private adapter; multi-step builders remain follow-up scope.

Alternatives

Callers can continue using primitive creation methods. A builder should expose compensation results rather than advertise transaction or rollback of arbitrary shell effects.

Related independent work

#821 records the existing Session.new_window(select_existing=True) IndexError, reproduced against the published v0.62.0 source and current master with tmux 3.8a. Its native reuse succeeded with empty output and left the original window alive. Fixing that method remains independent of this issue's session-only ownership MVP.

#822 owns pane-program argument preservation. #823 composes creation ownership with a fresh program's exit evidence and cleanup; its native event-wait path may require tmux 3.8+. Neither changes this issue's session-only first slice or makes another unmerged branch a prerequisite.

References

• Server.__exit__ kills any live server, including one it did not start #724 and Scoping a Server no longer kills it #728: server ownership bug and proposed correction.
• Operationalize typed operations and engines (follow-up to #688) #689: deferred multi-operation compensation.
• Expose tmux spawn provenance: a typed libtmux.env (TmuxEnv, spawn_session, is_inside_tmux) #712: spawn provenance differs from current live location.
• rmux owned-session API.

Delivery links: #629 (roadmap), #724 (existing server ownership), and #805 (optional lease qualification). Basic create/reuse does not depend on the lease.

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.