Research tmux-resurrect parity for workspace archives

Goal

Research tmux-resurrect parity for a pure-Python libtmux workspace archive API that does not require TPM or shell plugin scripts. The target consumers are libtmux itself, tmuxp, and agent/MCP surfaces that need headless save/restore behavior.

A first experimental slice exists in libtmux's workspace layer: capture tmux state through list-panes -a -F, persist canonical Workspace IR as JSON, and restore through WorkspaceSet. This issue tracks the remaining parity research and product decisions.

Upstream baseline

• tmux-resurrect documents parity as sessions, windows, panes, order, cwd, layouts, active focus, grouped sessions, and running programs, plus optional pane contents and editor/session restoration: https://github.com/tmux-plugins/tmux-resurrect/blob/v4.0.0/README.md#L32-L56
• The save script serializes pane/window/state data from tmux formats and captures full command data through strategy scripts: https://github.com/tmux-plugins/tmux-resurrect/blob/v4.0.0/scripts/save.sh#L35-L112
• The save flow writes grouped sessions, panes, windows, state, optional pane contents, optional shell history, and rotates old backups: https://github.com/tmux-plugins/tmux-resurrect/blob/v4.0.0/scripts/save.sh#L285-L310
• The restore flow creates only missing topology, preserves scratch-restore behavior, restores layouts/window properties, and then restores pane processes/focus: https://github.com/tmux-plugins/tmux-resurrect/blob/v4.0.0/scripts/restore.sh#L190-L320

Research questions

• What should libtmux's archive schema guarantee beyond canonical Workspace IR: grouped sessions, alternate windows/sessions, zoom state, pane titles, automatic-rename, shell history, pane contents, and full process command lines?
• Should libtmux support import/export compatibility with tmux-resurrect's tab-delimited save files, or keep JSON Workspace IR as the native format and provide a separate converter?
• Which process restore policies belong in libtmux core versus tmuxp or downstream tools: conservative whitelist, per-command strategy plugins, inline restore commands, or no process restore by default?
• How should archive writes handle rotation and last pointers portably without assuming POSIX symlinks?
• What is the minimum live integration matrix: Linux, macOS, BSD, Cygwin/MSYS, nested tmux, custom -L/-S sockets, and headless CI?

MVP/sprint proposal

1. Keep the current MVP as the base: one tmux read, canonical WorkspaceSet JSON, atomic write, restore through existing engines.
2. Add a typed archive metadata/version layer with explicit capability flags so future readers can know which parity features were captured.
3. Add focused tests for layout, focus, selected-session capture, archive read/write, restore-on-existing policy, and no-TMP/no-TPM operation.
4. Prototype optional tmux-resurrect file import as a converter, not the primary persisted format.
5. Prototype command-capture providers separately from restore policy so Linux /proc, macOS ps, and Cygwin process discovery can evolve independently.

Tradeoffs

• Native JSON Workspace IR is idiomatic Python and easy for tmuxp/MCP to consume, but it is not drop-in compatible with existing tmux-resurrect save files.
• tmux-resurrect row compatibility helps migration, but it imports shell-era escaping and plugin-specific process strategy semantics.
• Pure Python archive/restore is feasible for topology, cwd, layout, and focus on systems with tmux available. Full process resurrection is OS-specific and should be opt-in.
• Pane contents and shell history are valuable but risk large archives and privacy-sensitive payloads; they need explicit enablement and size controls.

Acceptance criteria

• Document the parity matrix against tmux-resurrect v4.0.0.
• Decide native archive schema vs tmux-resurrect-compatible schema vs converter split.
• Identify the first supported OS/process-capture strategy matrix.
• Produce tests that run headlessly in CI without TPM.
• Leave enough API surface for tmuxp and MCP callers to save, inspect, restore, and dry-run archives.

Start with the existing workspace-layer capture using list-panes -a -F, canonical WorkspaceSet JSON, and the restore path through WorkspaceSet. Compare the upstream scripts/save.sh and scripts/restore.sh, then define the parity matrix, archive schema decision, OS/process strategy matrix, and headless CI tests required by the acceptance criteria.