feat(desktop): archive v2 workspaces instead of deleting, with undo and a settings page
Links
- ExecPlan:
apps/desktop/plans/done/20260722-v2-workspace-archive.md(includes retrospective + deltas)
Summary
- Replaces the v2 workspace delete dialog with an instant, reversible archive: one click hides the workspace, shows an Undo toast, and leaves the worktree/branch untouched on disk. Permanent deletion moves to a new Settings → Archived workspaces page (Unarchive / Delete / Delete all, with the existing force/teardown-failed paths).
- Terminal sessions survive the undo window: archive touches nothing, and the terminal reaper later suspends an archived workspace's sessions (PTY killed, row kept respawnable), so unarchiving restores panes via the existing lost-PTY respawn path instead of dead-ending.
Why / Context
PostHog data (two weeks) showed v2 users rage-click ~50% more per active user than v1, and the single worst named hotspot was the "Also delete local branch" checkbox in the delete dialog (108 rage clicks / 85 users on v2). The dialog forced a destructive, blocking decision on every delete. Archiving removes the decision entirely: the common case is one click + undo; the destructive decision lives in Settings where it's deliberate.
How It Works
- Host-service: new host-local
archived_atcolumn on the SQLiteworkspacestable (migration0012, auto-applies at boot; no cloud/Postgres change — the Electric fallback analysis is in the plan doc). NewworkspaceCleanup.archive/unarchivemutations only flip the flag and broadcast;destroyis unchanged. - Terminal lifecycle: the reaper's pass suspends live sessions of archived workspaces (
suspendSessionAndWait: kill PTY, keep rowactive/unstamped, drop the terminal-agent binding). A later attach takes the existing adopt→respawn path with the "Session Contents Restored" separator. Undo within the toast window (or before the next reap pass) gets fully warm terminals. - Renderer:
useHostWorkspacessplitsworkspaces(active) fromarchivedWorkspacesat the source, so every existing consumer hides archived rows with no per-consumer changes. All five delete entry points (sidebar row + context menu, Cmd+W, command palette, workspaces page, missing-worktree screen) now call one archive flow with an optimistic cache update and the Undo toast. The old dialog is deleted exceptTeardownFailedPane, which the settings page reuses for force-delete. - Analytics:
workspace_archived/workspace_unarchivedevents (withsource) so the rage-click impact is measurable;workspace_deletedstill fires only on permanent delete.
Manual QA Checklist
Archive & Undo
- Archive from sidebar hover button / context menu / Cmd+W / palette / workspaces page — row hides instantly, toast appears
- Undo restores the workspace in its prior sidebar position with warm terminals
- Toast "View archived workspaces in Settings" link deep-links to the page
- Main (
local) workspaces cannot be archived
Settings page
- Archived list shows name/branch/project/date across hosts; empty state when none
- Unarchive restores; reopening the workspace respawns terminals with the restored-notice separator (after a reaper pass has suspended them)
- Permanent Delete removes the worktree from disk; local branch deleted iff the Git setting is on
- Dirty worktree → silent force retry; failing teardown.sh → TeardownFailedPane with "Delete anyway"
- Delete all runs sequentially and reports partial failures per-row
- Offline-host rows are dimmed with actions disabled
Migration
- Existing host.db migrates cleanly at boot (additive
archived_atcolumn) - Archived state survives host-service restart
Testing
bun run typecheck,bun run lint— cleanbun testinpackages/host-service(931 tests) — archive/unarchive router tests, reaper suspend-policy tests- Renderer unit tests for the active/archived split and broadcast field preservation
- Real-daemon e2e (
terminal.adoption.node-test.ts): suspend kills the PTY, keeps the row respawnable, drops the agent binding, adoptOnly fails, respawn is a fresh interactive shell with the restored notice (20/21 suite pass; the 1 failure is a pre-existingreplayOnAdoptionfailure reproduced on main) - A 5-perspective automated review ran on this branch; all high-confidence findings were fixed in
fix(desktop,host-service): address archive-flow review findings
Design Decisions
- Deferred suspend via the reaper instead of killing PTYs at archive time: the immediate kill deleted session rows, which permanently broke reopened panes ("session not found" with no respawn). The reaper pass gives an undo grace window for free, is idempotent, and its boot pass covers host restarts — no timer/cancellation machinery.
archivedAtis host-local only: the archiving machine always has live/snapshot host data, so the Electric cloud fallback can't resurrect archived rows there; the only leak is another machine that never fetched that host's list while it's offline (rendered unreachable anyway, and the fallback is scheduled for removal in R3).
Known Limitations
- CLI/SDK are archive-unaware:
superset workspaces list/openstill include archived workspaces (workspace.listintentionally returns all rows; filtering is renderer-side). archive/unarchivedon't participate in thedestroysInFlightguard; a cross-window unarchive-during-destroy converges (destroy wins via broadcast) but can briefly show a restore that then vanishes.TeardownFailedPanestill lives in the retired dialog's folder;DeletingWorkspacesProvider's mark/clear tracking is now unused.
Follow-ups
- CLI: filter or badge archived workspaces, add archive/unarchive verbs
- Relocate
TeardownFailedPane, remove deadDeletingWorkspacesProvidertracking - Consider
destroysInFlightchecks in archive/unarchive
https://claude.ai/code/session_01XzSu5oDicpKVn5geBwXTaq
Summary by cubic
Replaces v2 workspace delete with an instant, undoable archive to reduce friction and avoid accidental data loss. Adds a Settings page to manage archived workspaces, while keeping worktrees/branches and terminal sessions intact for fast restore.
-
New Features
- One-click archive replaces delete across sidebar, hotkey, palette, list, and missing-worktree; shows an Undo toast with a link to Settings.
- Archived workspaces are hidden; unarchive or permanently delete in Settings → Archived workspaces (per-row and Delete all, with force/teardown handling). Main (local) workspaces cannot be archived.
- Terminal lifecycle: archive touches nothing; the reaper later suspends PTYs so unarchive restores panes via the existing respawn path.
- Renderer splits active vs archived at the source; adds a command palette entry for “Archived workspaces.”
- Analytics: workspace_archived and workspace_unarchived events.
-
Migration
- Adds host-local SQLite column workspaces.archived_at; migration auto-applies at boot.
- No cloud/Postgres change; archived state persists across restarts.
Summary by CodeRabbit
-
New Features
- Workspaces can now be archived instantly from the sidebar, workspace list, command palette, keyboard shortcut, and missing-worktree view.
- Added an Archived Workspaces settings page with search, unarchive, permanent delete, and Delete all actions.
- Added archive confirmation toasts with Undo and a link to archived workspaces.
- Archived workspace terminal sessions are cleaned up while preserving session data for later restoration.
-
Bug Fixes
- Improved handling and display of archive and permanent-deletion errors, including force-delete recovery.