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

[tony]

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