epic(workspaces): named save, restore, import, and export

[kordless]

Summary

Turn Hyperia's existing layout work into complete named workspaces that can be saved, restored, shared, and controlled by users or agents.

Upstream requests:

• Save window groups vercel/hyper#311
• Save and open multiple sessions vercel/hyper#6339
• Make Hyper REMEMBER Split panes and TABS configurations vercel/hyper#6626

Existing Hyperia work to coordinate rather than duplicate:

• Save window layout on close with modal prompt #82
• Restore window layouts on app launch #83
• Bind sticky notes to windows for per-window layout save/restore #85
• Reattach panes to live nemesis8 containers on launch (session survival, herdr answer) #133

Scope

A workspace should capture windows and geometry, tabs and BSP split trees, pane types and names, shell profiles, working directories, web-pane URLs, sticky-note associations, and reattachable container or remote-session metadata where supported.

Safety requirements

Restoring a workspace must not replay arbitrary shell commands. Missing directories, profiles, containers, or URLs should produce recoverable placeholders with a clear explanation.

Acceptance criteria

• Save the current state under a user-selected name.
• List, rename, overwrite, and delete saved workspaces.
• Restore a selected workspace, not only the last launch.
• Preview unavailable resources before restoration.
• Import and export a documented, versioned JSON representation.
• Expose list, save, preview, and restore through CLI and MCP.
• Corrupt or older workspace files fail safely and can be migrated.
• Automated tests cover mixed terminal, web, and sticky layouts.

Provenance

This epic consolidates long-standing Hyper session-group requests while building on Hyperia's existing layout tickets and live-session architecture.

[crobison]

Broken into individually-testable chunks (each one PR):

• feat(workspace): schema v1, correlated multi-window capture, save/list/delete/rename #167 — schema v1, correlated multi-window capture, save/list/delete/rename (keystone)
• feat(workspace): preview + runtime restore into new windows with placeholders #168 — preview + runtime restore into new windows with placeholders
• feat(workspace): import/export, migration framework, corruption hardening, format docs #169 — import/export, migration framework, corruption hardening, docs/workspace-format.md
• feat(workspace): sticky-note association + mixed-layout test matrix #170 — sticky-note association (Bind sticky notes to windows for per-window layout save/restore #85 groundwork) + mixed-layout test matrix
• feat(workspace): lifecycle — save-on-close/quit, restore-on-launch, legacy retirement #171 — lifecycle: save-on-close/quit + restore-on-launch (Save window layout on close with modal prompt #82/Restore window layouts on app launch #83), legacy savedLayoutState retirement
• feat(workspace): reattach live n8-* containers on restore (optional follow-up) #172 — (optional follow-up, outside acceptance criteria) live n8-* container reattach (Reattach panes to live nemesis8 containers on launch (session survival, herdr answer) #133)

Key decisions baked into the chunks: workspaces at ~/.hyperia/workspaces/<name>.json (one file each, sidecar-owned via the atomic writer); restore is additive — new windows, uids remapped, live windows never touched; lastCommand demoted to a display-only annotation with typing opt-in (default off); new workspace MCP door (terminal_layout is at the 9/10 cap) + hyperia workspace <verb> CLI.

[crobison]

All five chunks are built, tested, and up as a PR stack (chunks 2–5 drafted, each stacked on the previous — merge #173 first, then rebase forward):

• feat(workspace): schema v1, correlated multi-window capture, save/list/delete/rename #173 — schema v1, correlated capture, save/list/delete/rename (ready for review)
• feat(workspace): preview + runtime restore into new windows with placeholders #175 — preview + runtime restore into new windows with placeholders (draft)
• feat(workspace): import/export, migration framework, corruption hardening, format docs #176 — import/export, migration, corruption hardening, docs/workspace-format.md (draft)
• feat(workspace): sticky-note association + mixed-layout coverage #177 — sticky association + mixed-layout coverage (draft)
• feat(workspace): lifecycle — save-on-close/quit, restore-on-launch, legacy retirement #178 — lifecycle: save-on-close/quit + restore-on-launch, legacy retirement (draft)

Acceptance criteria → where:

• Save under a name; list/rename/overwrite/delete → feat(workspace): schema v1, correlated multi-window capture, save/list/delete/rename #173
• Restore a selected workspace (not only last launch) → feat(workspace): preview + runtime restore into new windows with placeholders #175
• Preview unavailable resources before restore → feat(workspace): preview + runtime restore into new windows with placeholders #175 (+ stickys in feat(workspace): sticky-note association + mixed-layout coverage #177)
• Import/export documented versioned JSON → feat(workspace): import/export, migration framework, corruption hardening, format docs #176 (docs/workspace-format.md)
• CLI + MCP for list/save/preview/restore → feat(workspace): schema v1, correlated multi-window capture, save/list/delete/rename #173–feat(workspace): import/export, migration framework, corruption hardening, format docs #176 (hyperia workspace <verb>, workspace_* door)
• Corrupt/older files fail safely, migrate → feat(workspace): import/export, migration framework, corruption hardening, format docs #176 (typed errors, v0 savedLayoutState adapter)
• Automated tests over mixed terminal/web/sticky layouts → feat(workspace): sticky-note association + mixed-layout coverage #177 e2e matrix + 26 cargo / 36 ava unit tests across the stack
• Safety: restore never replays commands (scraped command is a display-only annotation; re-typing is opt-in typeRestoredCommand, default off — note this changes legacy boot restore too); missing cwd/profile/sticky → loud placeholders (pane banner + preview report)

#172 (live n8-* container reattach) remains the optional follow-up on the annotations extension point.