Research tmux-continuum parity for headless autosave

Goal

Research tmux-continuum parity for pure-Python, headless autosave and startup restore behavior that does not require TPM, shell plugin loading, or status-right mutation. The target consumers are libtmux, tmuxp, and libtmux MCP/CLI surfaces.

A first experimental slice exists as a one-shot autosave gate: callers pass an engine, archive path, optional persisted state path, interval, and clock; libtmux decides whether to save and then delegates to the workspace archive API. This issue tracks the remaining parity and OS integration research.

Upstream baseline

• tmux-continuum's user-facing contract is continuous saving, automatic tmux start after computer/server boot, and automatic restore when tmux starts: https://github.com/tmux-plugins/tmux-continuum/blob/v3.1.0/README.md#L1-L43
• Autosave defaults to a 15-minute interval and the FAQ clarifies first save delay / interval semantics: https://github.com/tmux-plugins/tmux-continuum/blob/v3.1.0/README.md#L84-L118
• The plugin uses status-right as its scheduler carrier and only installs autosave when another tmux server is not running: https://github.com/tmux-plugins/tmux-continuum/blob/v3.1.0/continuum.tmux#L9-L77
• The save worker checks tmux compatibility, interval enabled, elapsed time, then delegates to tmux-resurrect's save script: https://github.com/tmux-plugins/tmux-continuum/blob/v3.1.0/scripts/continuum_save.sh#L13-L42
• The restore worker gates on @continuum-restore, a halt file, multi-server detection, and then delegates to tmux-resurrect's restore script: https://github.com/tmux-plugins/tmux-continuum/blob/v3.1.0/scripts/continuum_restore.sh#L8-L29

Research questions

• Should libtmux provide only a one-shot autosave_once() primitive, or also a small scheduler loop usable by CLIs/TUIs/MCP servers?
• What should the persisted autosave state format contain beyond last_saved_at: interval, selected sessions, socket identity, archive path, error counters, and last failure?
• How should startup restore be represented safely for headless callers: explicit command, opt-in config, environment variable, tmux hook, system service, launchd agent, or downstream responsibility?
• How should libtmux avoid cross-server archive clobbering for -L / -S sockets without relying on shell process-count heuristics?
• What OS integration should live in libtmux versus downstream packages: Linux systemd user units, macOS launchd, BSD rc/cron, Cygwin/MSYS task scheduler, and container/CI modes?

MVP/sprint proposal

1. Keep libtmux core as a headless one-shot API: should_autosave, autosave_once, read_autosave_state, write_autosave_state.
2. Add a tiny CLI/TUI/MCP-friendly wrapper that prints what happened: skipped, saved, next eligible save, archive path, and selected sessions.
3. Add socket-aware state keys so independent tmux servers do not overwrite each other's archives by default.
4. Add startup-restore as an explicit opt-in command first, not an implicit daemon side effect.
5. Research OS service templates as downstream recipes, not hard dependencies.

Tradeoffs

• A one-shot primitive is easiest to test headlessly and embed in tmuxp/MCP, but callers must schedule it themselves.
• A built-in scheduler loop improves batteries-included UX, but it needs lifecycle, logging, lock, and shutdown semantics.
• Avoiding status-right mutation removes a major upstream fragility, but loses tmux-native periodic execution unless users configure a hook or external scheduler.
• Boot integration is platform-specific. Keeping it outside the libtmux core avoids surprising daemon behavior and keeps the API portable.

Acceptance criteria

• Document a parity matrix against tmux-continuum v3.1.0.
• Decide whether libtmux owns a scheduler loop or only exposes one-shot primitives.
• Define socket-aware autosave state and archive naming rules.
• Define safe startup restore UX and halt/guard semantics.
• Validate the first implementation on Linux and macOS, with notes for BSD and Cygwin/MSYS feasibility.

Start with the existing one-shot autosave API and compare its behavior with tmux-continuum v3.1.0, especially continuum.tmux, scripts/continuum_save.sh, and scripts/continuum_restore.sh. Trace the current libtmux archive and state entry points, then document the parity matrix and decisions for scheduling, socket-aware state, restore guards, and OS integration. Done means the acceptance criteria are documented and the remaining implementation boundaries are explicit.