[Agentic DX] libtmux: consolidated roadmap (core + async + engines) #629

Current preparation status — 2026-11-01. Seven independent PRs are open across Python and TypeScript, with every required hosted check passing at their recorded heads; the existing Python ownership PR is reused. Each new PR builds from current master with sibling branches absent. This records PR preparation and bounded qualification, not completion of the feature train. Every unresolved canonical issue remains open.

Verified bases: Python 886b1cd4862cbddcadffe3d82db0495f4e0594f8; TypeScript d2b149beddb84326d79d3fabbdb99429646f22e5. No new generic engine contracts or merge dependencies were added. Python seconds/code-point counts and TypeScript milliseconds/UTF-16 or filtered-UTF-8 units remain explicitly named by each API.

The remaining helpers receive concrete qualification findings rather than a production PR under the limited delivery rule. Current-master TypeScript probes retain the original three failures (mutable frames, pending disposal, stringified errors); private repairs pass all 16 declared assertions on Bun 1.4.2 and emitted Node 22.23.3 with the recorded tmux 3.8a binary. The first Node bundle had a missing-fixture packaging failure before feature assertions; that failure remains recorded, and the identical fixture was placed beside the moved bundle without changing assertions or timers.

The refreshed Python private consumer passes its 13 declared cases, while stronger controls fail native worker cleanup, selected-engine observer routing and nested frame immutability. Earlier 12-trial receipts remain tied to their original hashes; the changed current Python prototype was tested separately. No prototype PASS is treated as merged implementation. Local complete Python suites retain the same 18 failures reproduced on unchanged master; new PR-head hosted lanes pass.

No new issues, closures or merge dependencies result from this pass. No macOS jobs, runners, fixture lanes, debugging or qualification work are added; existing support and coverage remain, and unrun behavior is UNVERIFIED without becoming a gate. Python's core minimum stays 3.2a; its minimum-version issue #777 and proposal PR #779 are outside scope. NEVER write to tmux/tmux; references use pinned source code only.

Linked trackers: Python roadmap, Python project, environment profiles, TypeScript roadmap, TypeScript project. Each gap has its canonical issue or explicit research owner; no aliases become extra feature requests.

Context

The previous issues #630, #631, #632, and #633 came from local worktree experiments and should be treated as one consolidated roadmap with core libtmux API work.

This issue is the canonical tracker for Agentic/DX improvements across:

• core API contracts
• async support direction
• concurrency/state semantics
• engine/backend architecture

Goal

Strengthen API contracts and machine-readable behavior for agent-safe automation without fragmenting the project into parallel tracks.

Low-lift ideas

• Publish explicit stable API boundary and deprecation schedule (safe public imports and behaviors).
• Add a concise exception/error contract table for command failures.
• Publish sync-vs-async parity notes (supported / planned / out-of-scope).
• Define/document engine selection semantics and baseline capability fields.

Medium-lift ideas

• Add contract tests for public behavior and tmux-version compatibility.
• Add async cancellation/timeout/backpressure semantics and tests.
• Clarify concurrency/state refresh guarantees for pane/window/session objects.
• Add shared response/event parsing contracts across subprocess/control-mode backends.

High-lift ideas

• Publish machine-readable capability metadata (tmux version matrix + backend capabilities).
• Add versioned structured contracts for machine output/diagnostics.
• Add inspect/plan-style, non-mutating orchestration preview interfaces.

Done when

• Public API and compatibility expectations are explicit.
• Async + concurrency + backend behaviors are documented and regression-tested.
• Automation clients can rely on stable, machine-readable contracts.

Consolidation note

Supersedes and consolidates:

• [Agentic DX] Async prototype roadmap (libtmux-asyncio-2-chatgpt-2025-10x) #630

• [Agentic DX] Async prototype roadmap (libtmux-asyncio-psycopg) #631

• [Agentic DX] Async prototype roadmap (libtmux-asyncio-sqlalchemy) #632

• [Agentic DX] Engine/control-mode roadmap (libtmux-control-mode-2025-10x-chatgpt) #633

• [Agentic DX] Rust acceleration roadmap (libtmux-rust prototype) #634

Delivery plan

The independent-PR contract below supersedes any earlier implication of a required merge sequence.

Deliver rmux-inspired helpers through stock tmux capabilities, with explicit observation, cancellation, ownership, and recovery contracts. Track the work in the libtmux project. This plan reuses twelve existing issues and adds six focused proposals.

Work can proceed independently where its required contract exists. Text surfaces do not wait for styled cells. A minimal immutable observation can unblock wait diagnostics before a full snapshot graph. The cancellation and reply-correlation slice of #689 can land before its broader workspace, lazy-operation, and MCP work.

• Settle the command deadline, cancellation, unknown-outcome, and owned-client cleanup contract in Operationalize typed operations and engines (follow-up to #688) #689; expose bounded channel waits through Server.wait_for() has no timeout, so a pane that never signals hangs forever #732.
• Resolve existing server ownership in Server.__exit__ kills any live server, including one it did not start #724 and independent feature admission in Gate unsafe optional tmux features independently #778.
• Deliver byte-preserving subscriptions in Observe pane output as bytes with explicit subscription gaps #800 and state the distinct observation/completion guarantees in feat: Add Non-polling Waiters (Deterministic Channels & Delta-Polling) #673.
• Deliver capture cursors in feature: upstream capture_since #740 with Investigate libtmux-side trim detection for scrollback consumers #671's explicit loss and uncertainty behavior.
• Deliver immutable observation values in Snapshot / frame dataclass #370 and retained timeout diagnostics in Waiter v3.0: Requirements #584.
• Deliver sampled surface_stream frames in Add sampled surface_stream frames with explicit resets #801; add qualified styled cells through Expose typed cell captures for qualified tmux export formats #802.
• Deliver ordered PaneSet results and bounded any/all waits in Add PaneSet operations with per-target outcomes #803.
• Deliver owned create/reuse and compensating cleanup in Create or reuse tmux resources with explicit cleanup ownership #804.
• Specify recording coverage, retention, and persistence in record(), .stop() : capture and for object info #420; qualify optional leases separately in Qualify token-fenced leases for owned tmux sessions #805.
• Publish the environment qualification and counterexamples in Bullet proofing for capture_pane #456 with each implementation's supported profile.

Research basis and limits

The audit classified 558 explicit rmux SDK declarations into 22 capability families. That inventory includes constructors and conversions; it is not a target of 558 Python methods. Source evidence is pinned to rmux 1f4571e7, tmux 3.8 at 7f2a35ad, and the Python baseline at 886b1cd4.

Local prototypes exercised Python and TypeScript against tmux 3.8 and a pinned development checkout, with twelve declared trials. Those are exploratory observations, not public implementation acceptance: the fixtures and results must be included in reviewable implementation work before closing these issues. The stronger TypeScript byte-identity contract failed through its decoded string stream; that belongs in the TypeScript port. Engine cancellation implementations were inspected, but their suites were not rerun for this planning audit.

The source evidence establishes different guarantees:

• rmux retains a bounded output ring. A Python recorder can retain what it observes after installation; it cannot recreate bytes that nobody retained.
• rmux registers an observer at the same locked boundary as capture. Separate tmux capture and metadata commands provide sampled observations, even when metadata matches before and after.
• rmux recovery includes pending bytes, active and saved attributes, cursor state, and parser state. Exported visible cells do not provide every state needed to interpret the next byte.
• tmux's diagnostic grid route bypasses ordinary text-history selection. Cell parsing therefore needs format qualification and honest resource limits.
• rmux's state journal and lease handlers own server-side state. Library implementations need explicit observer coverage and ownership qualification.

Neither bounded in-memory retention nor a captured frame establishes durability across arbitrary daemon restarts. Disk recording can preserve acknowledged records under a specified storage policy; missing observations remain gaps. Quiet output, a matched prompt, and successful key submission do not establish command completion in an arbitrary shell.

The train covers library work using current tmux capabilities. Complete hidden-state export, replay of never-recorded bytes, browser authentication/sharing, and a native Windows PTY backend remain outside this delivery scope. No upstream tracker changes are part of this work.

Independent PR delivery and compatibility

Each bounded deliverable gets a minimal PR against master that builds, tests, and provides useful behavior with every other feature branch absent. Parent issues organize the work; cross-links identify shared contracts and later integration points. They do not impose a PR merge order.

Use existing trunk primitives and a small private adapter where a shared implementation has not landed. Do not import unmerged modules, vendor the engine framework, add another public CommandRequest or CommandResult, or require a foundation PR before delivering a helper. A needed public symbol has one owning issue; other features consume a narrow structural contract or preserve a private representation until a public consumer needs it.

Preserve these contracts across all PRs:

• Existing synchronous methods, blocking defaults, return values, and exception behavior remain compatible. Deadlines are opt-in; async cancellation stays on explicit async operations.
• At the engine boundary, preserve request argv, explicit connection ownership, timeout/input semantics, raw return code and output, and one attributable result per request. Reuse the selected engine's canonical request/result classes when available. Do not infer success from the mere presence of output or silently change the engine's error policy.
• At the operation layer, map outcomes to complete, failed, skipped, or unknown. Cancellation before submission is skipped with a reason; an uncertain submitted mutation is unknown. Keep the underlying engine result available and never retry an uncertain mutation automatically.
• Preserve bytes before decoding; scope identity to the server and pane lifetime; distinguish unsupported or unknown capabilities; invalidate observer continuity on loss. Sampled captures cannot become exact replay or complete terminal checkpoints through an adapter.
• Cleanup affects only positively owned resources. Borrowed engines and servers remain usable; cancellation of a client does not imply cancellation of the pane's process.
• Snapshot values are immutable; text offsets and terminal columns remain distinct. Optional future data needs a compatible extension path. Serialized records carry a version and an explicit policy for unknown event kinds and fields.

Before implementation, record the exact reviewed engine-ops, request-timeout, async-subprocess, and hardening refs and compare their real interfaces. Resolve differences in a contract note; an old issue's illustrative type or exception name is not an authoritative interface. Tests for each PR should validate its adapter against that recorded contract without requiring another feature PR to be installed.

The independence gate is a fresh checkout of the PR's actual master base plus only that PR's changes. Verify its focused tests, types, docs, and an end-to-end consumer there. Prove the critical test fails when its protection is removed. A sidecar check against the selected engine implementation is integration evidence, not a build dependency. Test interacting features once both exist, without making every unrelated pair a prerequisite.

Trim each first PR to the useful slice below. Keep the remaining issue criteria open and explicit. Later PRs may use functionality already merged into master; they must not depend on another unmerged branch.

#629 and #456 coordinate the roadmap and environment qualification. They do not require umbrella implementation PRs. Each feature PR carries its own controlled-fixture tests, declared environment limits, and relevant documentation. A passing first slice does not close the issue while deferred acceptance criteria remain.