feat(desktop,host-service): archive v2 workspaces instead of deleting, with undo and an Archived view
Links
- ExecPlan:
apps/desktop/plans/done/20260905-0755-archive-delete-experience.md(decision log, terminal-status audit table, both review rounds) - Review page with screenshots and the open decisions (org-internal): https://app.superset.sh/page/archive-not-delete-v2-workspace-close-review-z6c6fy
- Supersedes PR #6011 and the unpushed
archive-workspace-experiencebranch (both rebuilt against currentmain)
Summary
This PR replaces "Delete" as the primary way to close a v2 workspace with a reversible Archive, in four parts:
- Host data plane — the user's Archive is the existing
archived_at+archive_reasonpair with a third reason,user(no migration), behindworkspaceCleanup.archive/unarchivemutations with host-side analytics. Every reader that meant "destroyed" now asksisTombstonedinstead of "archived_at is set". - Terminal suspend — a reaper pass suspends an archived workspace's terminals after a 60 s grace using a new durable
suspendedrow status that respawns on attach; the earlier attempts left rowsactiveand lost every terminal after one reaper tick. - Renderer — archived rows are split out of the live host-workspaces list at one seam; one shared flow (intent queue + headless mount) archives from every entry point with an optimistic update and an 8 s Undo toast.
- Archived view — a third List / Board / Archived view on the Workspaces page with Unarchive, Delete, and Delete all (reusing the existing delete dialogs), plus an archived state for deep links. For host workspaces this view is now the only place Delete lives.
Also includes: the Display menu's tombstone lookback is relabelled "History"; the mobile home list hides archived rows; 25 new strings translated in all 16 non-English locales.
Changed by the page review (round 2): the separate shelved_at column and its migration are gone in favour of the unified pair; Delete left the live menus; suspend timing stays on the reaper sweep (a toast-tied timer was built and dropped); cloud-sandbox archive is a follow-up Satya takes. Details in the plan's Decision Log.
Why / Context
PostHog rage-click analysis shows v2 users rage-click about 50% more per user than v1, and the single worst hotspot in the app is the "Also delete local branch" checkbox in the v2 delete-workspace dialog. People who just want a workspace out of the way are pushed through a scary, irreversible decision with a destructive checkbox attached. The fix is the Gmail/Slack pattern: make the common action (getting something out of the way) instant and reversible, and move the rare destructive one somewhere deliberate. The checkbox stays in the delete dialog (it is a persisted preference and that is the deliberate place); it just stops being what you meet when you tidy up.
The product decisions (no dialog, Undo toast, third view on the Workspaces page rather than a Settings page, no sidebar "Archived" entry, Delete only from the Archived view) come from two rounds of live review of the earlier attempts and the page review of this one.
Part 1: Host data plane
Why
workspaces.archived_at + archive_reason already existed as the destroy tombstone (merged | deleted): set first by destroy so the row vanishes instantly, put back if the delete fails, finished by a startup reconciler after a crash, kept forever for the board's Merged/Deleted columns. The first version of this PR added a separate shelved_at so that stayed untouched; review preferred one archive concept, so the reversible archive is the same pair with reason user.
What / How
- New
packages/host-service/src/workspaces/archive-state.tsowns the reason union, the predicatesisTombstoned(stamped with any reason butuser, including a reason-less stamp) andisUserArchived, and their SQL twinstombstoned/userArchived/notTombstoned.archive_reasonis plain text, so no migration; the branch does not touchdrizzle/. - Every host reader that meant "destroyed" switched to the predicates:
workspace.list's default filter andworktreeExists, branch reuse inworkspaces.createand the adopt path (both unarchive a user-archived match), the boot reconciler (never treats a user archive as an interrupted delete), PR syncing, the git watcher,get-linked-workspace, worktree/branch listing, and the usage history. - Destroy captures the row's previous archive state (
tombstoneLocalWorkspacereturns it) and a failed delete restores it (restoreLocalWorkspaceTombstone), so a delete from the Archived view that fails leaves the row archived rather than reviving it in the sidebar. A failed retry of an existing tombstone still revives it live, as before. archive/unarchiverefuse main workspaces and tombstoned rows, are idempotent via conditionalUPDATE … WHERE archived_at IS NULL(two requests in one tick broadcast and count once), broadcast a normalupdatedevent (clients move the row between lists instead of dropping it), and emitworkspace_archived/workspace_unarchivedwith asource(sidebar | sidebar-menu | hotkey | command-palette | workspaces-page | bulk;undo-toast | workspaces-page | deep-link | terminal-create | workspace-create). Host-side emission means CLI/MCP archives count too; these events are how we measure whether rage clicks drop.- Using an archived workspace brings it back: opening a new listed terminal in it (CLI, MCP, automation) or re-creating its branch via
workspaces.createunarchives it, so nothing runs hidden and the reaper never kills a shell someone just started. Agent activity never unarchives. (Open question on the review page: fail instead, until an explicit Unarchive.) archivedAt/archiveReasonride theWorkspaceSnapshotwire type and theworkspace.listrow.workspace.listhides only tombstones by default; user-archived rows are served with the stamp (see Follow-ups).
Part 2: Terminal suspend
Why
Archive must be non-destructive at the moment it happens (Undo inside the toast gets the very same processes back), but archived workspaces should not keep shells and dev servers alive forever.
The trap the earlier attempts fell into
The reaper's stale-active sweep flips any active terminal row the pty-daemon no longer owns (older than 60 s) to exited, and an exited row dead-ends the next attach with session-gone. Suspending by killing the PTY and leaving the row active works for five minutes and then makes every unarchived terminal unrestorable.
What / How
killSessionRuntimeis extracted fromdisposeSessionAndWait;suspendSessionAndWaitcalls it and, only after a confirmed kill, marks the rowsuspendedand ends its agent binding asterminal-exitedin one transaction. The binding is ended, never deleted: a survivingagentSessionIdwith that end reason is exactly what makes the agent a resume candidate.- The attach decision is a pure, tested
planTerminalAttach:disposed/exited→ session-gone,active→ adopt (or respawn if the daemon lost the PTY),suspended→ respawn with the "Session Contents Restored" notice. The row upsert on respawn flips it back toactive. - The reaper's pure
planArchivedSuspendssuspends live sessions of workspaces archived ≥ 60 s, skips anything the orphan pass already condemns (dispose supersedes suspend), skips sessions created after the archive, and is idempotent for free.loadArchivedWorkspaceslists user-archived rows only (a tombstone's sessions belong to destroy). Before each kill the pass re-reads the workspace state and skips sessions a renderer is attached to; suspends run four at a time. - Every reader of
terminal_sessions.statuswas audited (table in the plan);sweepDefunctgainedsuspendedas belt and braces.
Part 3: Renderer
What / How
useHostWorkspacessplits the same cached rows intoworkspacesandarchivedWorkspacesby the user reason (a tombstone stays on the live side, where the board expects it onincludeArchived), and exposesfindWorkspace(id)for the few consumers that must see archived rows (delete dialogs, host resolution, the workspace route, the archive flow). Every other consumer readsworkspacesand hides archived rows with no further change. The event patcher treatsarchivedAt: nullas a real value (an unarchive) and only an absent field as "keep the cached one".isTombstonedWorkspace/isUserArchivedWorkspaceare the renderer's twins of the host predicates; the board's column derivation, the board card, and the pin filter use the former.- One flow,
useArchiveWorkspaceFlow: resolve rows at call time, refuse main and cloud, navigate away if the workspace is open, optimistic cache patch, host mutation, and on failure put the captured row back before invalidating. Toast keyed by workspace id with Undo (and "Undo all" for bulk) plus a "View archived workspaces" link; Undo navigates back when the archived workspace was the one on screen. Every imperative entry point files a request through a small intent queue drained by one headlessArchiveWorkspaceMountnext toDeleteWorkspaceMount, so the flow exists once app-wide and the palette (outside React) can use it. - Sidebar section, pin, and pane layout are never touched by archive, so Undo restores the workspace exactly where it was; they are cleaned up only on permanent delete, as before.
- Delete left the live surfaces for host workspaces: the sidebar context menu, the Workspaces page menus, the bulk toolbar and bulk menu, and the palette no longer offer it. Cloud sandboxes (no archive) keep Delete everywhere, with the hotkey; the missing-worktree screen keeps its Delete.
Part 4: Archived view and deep link
What / How
V2WorkspacesViewModegains"archived"; the header's fieldset gets a third button with a muted count. Archived is a per-visit mode: the List/Board choice is what persists, and a bare return to the page lands on it. In-app links to?view=archivedare followed even when the page is already mounted. The Display menu hides in this mode, and its tombstone-lookback group is relabelled History so two "Archived" controls never share a toolbar.useAccessibleV2WorkspacesgainsarchivedView(rows from the archived split, with the same PR/agent/project enrichment) andarchivedCount.V2WorkspacesArchivedlists rows newest-first with name,font-monobranch, project (or "Sessions"), the PR chip, a localized "Archived {relative time}", and hover-revealed Unarchive / Delete. Per-row Delete pushes intouseDeleteWorkspaceIntent; Delete all pushes intouseBulkDeleteWorkspacesIntent(its target type narrowed to the four fields the dialog reads; the mount moved to the dashboard layout so it works with the sidebar closed). A failed destroy leaves the row archived. Offline remote-host rows are badged with disabled, tooltip-wrapped actions. The empty state is gated onisReadyand explains itself when filters hide everything.WorkspaceArchivedStaterenders for a deep link to an archived workspace with Unarchive and "View archived workspaces".
Key decisions
| Decision | Choice | Rationale |
|---|---|---|
| Columns | archived_at + archive_reason = "user", no shelved_at | review wanted one archive concept; the cost (every "destroyed" reader must ask isTombstoned) is paid once in archive-state.ts and tested |
| Suspended terminal row | new suspended status, binding ended not deleted | the stale-active sweep only touches active; terminal-exited + surviving session id = resume candidate |
| Suspend timing | reaper sweep, 60 s grace (1–6 min to suspend) | no extra lifecycle code; a toast-tied host timer was built, then dropped in review |
| Entry points | one intent queue + one mount | the flow needs the navigate-away helper (flattens the sidebar); per-row hooks would be O(rows²) |
| Analytics | host-side only, with source | CLI/MCP archives count; no double-emission from the renderer |
| Archived home | third view on the Workspaces page | settled in live review; whether it should move to Settings is still being discussed on the page |
| Delete | only from the Archived view (host workspaces) | review saw no purpose in Delete next to Archive; one destructive path behind one deliberate step |
| Cloud sandboxes | keep Delete as their close | archive is host-local; cloud archive is a follow-up Satya takes |
Keyboard shortcuts
| Shortcut | Before | After |
|---|---|---|
⌘⇧⌫ Close Workspace (v2 local/remote host) | opens the delete dialog | archives, no dialog |
⌘⇧⌫ on v1 or a cloud sandbox | delete dialog | unchanged (description now says so) |
Manual QA Checklist
Verified in a dev instance of this branch (over CDP, before round 2)
- Host-service boots and every sidebar row shows the archive hover icon and "Archive workspace" tooltip.
- Archive from the hover button: sidebar 80 → 79 rows, toast
Archived "…"with Undo and the view link; Undo → 80 rows, no trace left in the host database. - Archived view renders a real archived row (name, branch, project, relative time), the count badge, Delete all, hidden Display menu.
Still to verify by hand
- The round trip above again on the unified columns; the trimmed menus (no Delete for host rows; Delete with the shortcut on a cloud row).
- Archive with two running terminals, one running an agent, then Undo: same processes, no "Session Contents Restored" banner, agent status intact.
- Archive, wait past the grace and one reap pass (shorten
ARCHIVE_SUSPEND_GRACE_MSandREAP_INTERVAL_MSlocally), unarchive, open: both shells respawn with the banner and the agent is offered for resume. - Open a terminal in an archived workspace from the CLI: the workspace unarchives and the shell survives the next reap pass.
- Archive the open workspace: clean navigate-away; Undo returns to it.
- Hotkey, palette "Archive workspace", list row, board card, bulk toolbar and bulk menu all archive; palette "Archived workspaces" and the toast link land on the view, including from the Workspaces page itself.
- Archived view: search and filters, Unarchive with the "Restored" toast and Open, per-row Delete opens the existing dialog, a failed delete leaves the row archived, Delete all runs the bulk dialog (also with the sidebar closed), offline remote rows disabled with tooltip, empty state only after hosts settle, light and dark.
- Deep link to an archived workspace shows the archived state; board Merged/Deleted columns and the History lookback still work; every existing delete surface unchanged; v1 unaffected.
Testing
bun run typecheck(root, 38/38 packages)bun run lint(root; Biome warnings fail here)bun run check:i18n(all 17 locales compile)bun testinpackages/host-service:workspace-cleanup.archive.test.ts(router cases plus tombstone-over-archive rollback),archive-state.test.ts(predicates and SQL),attach-plan.test.ts,reaper.test.ts(planner cases, loader, suspend-survives-stale-sweep),test/integration/workspace.integration.test.ts(list tombstone semantics); the suite's 3 pre-existing environment-only failures (unbundled pty-daemon binary, agent-launch config leak) are unchangedbun testinapps/desktop: 3525 pass; the 1 pre-existing env-sensitive failure (LeaderboardRank, marketing URL) is unchanged- Not run:
lint:check-node-imports(script no longer exists in the repo) and a packaged desktop build.
Code review
Three passes were run before opening this PR: an orchestrated review with eight angle reviewers, the orchestrator's own pass, and a fresh-context reviewer given only the plan and the diff. Their verified findings and outcomes are on the review page; the fixes are the two fix: commits. The page review (Satya, Avi) then produced the round-2 commits.
Known Limitations
- The hotkey no longer shows the old "process still running" prompt before closing; archive is reversible and a suspended agent is offered for resume, so this is intentional, but it is a product call.
- A second window still attached to an archived workspace when the reaper suspends it sees that pane close without reconnecting, the same as today's dispose; the archiving window navigates away first.
- Suspension lands between 1 and about 6 minutes after archiving (60 s grace, 5 min reaper cadence); a dev server in an archived workspace keeps its port for up to that long.
packages/host-service/test/is outside the package'stsconfig, so a rename there only fails at test time; the integration test was updated by hand.
Follow-ups
- Whether opening a terminal in an archived workspace should fail until an explicit Unarchive (with CLI/MCP
unarchivecommands) instead of unarchiving it; open on the review page. - A server-side flag on
workspace.listsosuperset workspaces listand MCPworkspaces_listcan hide user-archived rows by default; rows already carryarchivedAt/archiveReason. - Archive for cloud sandboxes (Satya).
- Whether the Archived view should live under Settings rather than the Workspaces page.
- Splitting destroy's in-progress marker from the permanent history record the board reads (raised in review; deliberate today, since a delete must survive a crash).
- Snapshotting or reclaiming archived worktrees from disk and auto-deleting old archives; sharing the reaper's status-flip transaction with the suspend marker; a batch archive endpoint for bulk.
Compatibility
- Desktop ↔ host-service: an older host without
archiveanswers the new mutation withBAD_REQUEST; the flow rolls back and toasts. An older host omitsarchiveReasonfrom events; the renderer treats an absent field as "keep the cached value". - Mobile derives its row type from the host router and filters archived rows.
- A host database that applied the earlier
shelved_atmigration from this branch keeps a harmless unused column; drizzle's migrator compares timestamps, so the dropped journal entry is never re-applied.
Deployment / Rollout
- No feature flag, no migration. Ships desktop and host-service together as usual (shared version).
Rollback
- Revert the PR. A row left with
archive_reason = "user"reads as a tombstone to the reverted code (it hides from the list and the board files it under Deleted), so before reverting, runUPDATE workspaces SET archived_at = NULL, archive_reason = NULL WHERE archive_reason = 'user'on each host database, or unarchive everything from the Archived view first. Anysuspendedterminal row respawns on attach exactly like a daemon-lostactiverow would have.
Files changed (orientation)
packages/host-service/src/db/schema.ts,workspaces/{archive-state,archive-sources,local-workspace-store}.ts,trpc/router/workspace-cleanup/workspace-cleanup.ts— the archive state, the predicates, archive/unarchive, destroy rollbackpackages/host-service/src/runtime/{archived-workspace-reconcile,pull-requests/pull-requests}.ts,events/git-watcher.ts,trpc/router/{workspace,workspaces,workspace-creation,pull-requests,usage}/**— readers switched toisTombstonedpackages/host-service/src/terminal/{terminal,attach-plan}.ts,terminal/reaper/reaper.ts,terminal-agents/persistence.ts— suspend, attach planner, reaper passapps/desktop/src/renderer/hooks/host-workspaces/useHostWorkspaces/*— the split, the predicates,findWorkspaceapps/desktop/src/renderer/lib/workspaces/useArchiveWorkspaceFlow/*,stores/archive-workspace-intent.ts,commandPalette/ui/ArchiveWorkspaceMount/*— the flowapps/desktop/src/renderer/routes/_authenticated/_dashboard/components/DashboardSidebar/**,commandPalette/modules/**,_dashboard/layout.tsx,hotkeys/registry.ts— entry points, Delete removed from menusapps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/**— header, store, Archived view, search parser, board column derivationapps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/**— deep-link archived stateapps/mobile/hooks/**— archived rows hidden on the phonepackages/i18n/locales/*/messages.po— translations
https://claude.ai/code/session_01NJPxYdV4S3Tx6Di58kbkqz
Summary by cubic
Replaces "Delete" as the primary way to close a v2 workspace with a reversible Archive: every close surface now archives instantly with an 8s Undo toast, and a new Archived view on the Workspaces page handles Unarchive and permanent Delete. Closing previously meant an irreversible destroy dialog with an "Also delete local branch" checkbox — the app's worst rage-click hotspot. Cloud sandboxes and v1 workspaces keep Delete, and an archived workspace's terminals are suspended after a grace period, then respawn on next attach.
Host service
- The user's Archive reuses the existing
archived_at+archive_reasondestroy tombstone pair with a third reason,user, so no migration anddrizzle/is untouched. - Every host reader that meant "destroyed" now asks a shared
isTombstonedpredicate inarchive-state.ts, so a user archive never reads as an interrupted delete. workspaceCleanup.archive/unarchivestamp and clear the pair, refuse main and tombstoned rows, and are idempotent under concurrent requests; a failed delete restores the row's previous state.- The reaper suspends an archived workspace's live terminals via a new durable
suspendedstatus; attach respawns them instead of dead-ending with session-gone. - Opening a terminal in an archived workspace or re-creating its branch unarchives it automatically, and the PR-to-workspace lookup never sends a prompt to an archived row.
- Archive/unarchive events are emitted host-side with the source (sidebar, hotkey, CLI, MCP, ...), so CLI/MCP archives count toward the rage-click metric.
- An older host without
archiveanswersBAD_REQUEST, and the renderer rolls back with a toast; desktop and host ship together with no feature flag.
Renderer
- One shared archive flow behind an intent queue serves every entry point: sidebar hover and context menu, hotkey, command palette, Workspaces page, and bulk selection.
- The
⌘⇧⌫hotkey now archives instead of opening the delete dialog. Delete left the live surfaces for host workspaces entirely — sidebar menus, page menus, bulk selection, and palette — and survives only on cloud sandboxes and in the Archived view. - A third Archived view on the Workspaces page lists archived rows newest-first with Unarchive, Delete, and Delete all, reusing the existing dialogs.
- Deep links to an archived workspace render an archived state with Unarchive rather than the workspace UI or not-found.
- Mobile filters archived rows out of the home list.
Summary by CodeRabbit
- New Features
- Workspaces can be archived and restored instead of immediately deleted; cloud workspaces and main workspaces retain their existing restrictions.
- Added an Archived Workspaces view with counts, filtering, sorting by archive date, and per-workspace restore or permanent-delete actions.
- Archive actions are available from the sidebar, context menus, command palette, keyboard shortcut, and bulk selection.
- Successful archives can be undone. Archived workspace links offer restoration options instead of showing a missing-workspace screen.
- Archived workspaces on offline hosts are marked, with actions unavailable until the host is online.
- Localization
- Added translations for archive, restore, deletion, offline, and empty states across supported languages.