feat(desktop): archive v2 workspaces instead of deleting, with undo and a settings page

AV
2mo ago
+2672-782

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_at column on the SQLite workspaces table (migration 0012, auto-applies at boot; no cloud/Postgres change — the Electric fallback analysis is in the plan doc). New workspaceCleanup.archive/unarchive mutations only flip the flag and broadcast; destroy is unchanged.
  • Terminal lifecycle: the reaper's pass suspends live sessions of archived workspaces (suspendSessionAndWait: kill PTY, keep row active/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: useHostWorkspaces splits workspaces (active) from archivedWorkspaces at 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 except TeardownFailedPane, which the settings page reuses for force-delete.
  • Analytics: workspace_archived / workspace_unarchived events (with source) so the rage-click impact is measurable; workspace_deleted still 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_at column)
  • Archived state survives host-service restart

Testing

  • bun run typecheck, bun run lint — clean
  • bun test in packages/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-existing replayOnAdoption failure 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.
  • archivedAt is 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/open still include archived workspaces (workspace.list intentionally returns all rows; filtering is renderer-side).
  • archive/unarchive don't participate in the destroysInFlight guard; a cross-window unarchive-during-destroy converges (destroy wins via broadcast) but can briefly show a restore that then vanishes.
  • TeardownFailedPane still 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 dead DeletingWorkspacesProvider tracking
  • Consider destroysInFlight checks in archive/unarchive

https://claude.ai/code/session_01XzSu5oDicpKVn5geBwXTaq


Open in Stage

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.