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

No files, entry points, or tests are named. Read this consolidated roadmap and its superseded issues (#630–#634), then select a narrowly scoped contract or documentation item before starting. Done requires an explicit API or compatibility expectation, with regression tests where the selected item calls for them.

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:

• #630

• #631

• #632

• #633

• #634