feat(desktop,host-service): archive v2 workspaces instead of deleting, with undo and an Archived view

AV
1mo ago
+5577-692

Links

Summary

This PR replaces "Delete" as the primary way to close a v2 workspace with a reversible Archive, in four parts:

  1. Host data plane — the user's Archive is the existing archived_at + archive_reason pair with a third reason, user (no migration), behind workspaceCleanup.archive/unarchive mutations with host-side analytics. Every reader that meant "destroyed" now asks isTombstoned instead of "archived_at is set".
  2. Terminal suspend — a reaper pass suspends an archived workspace's terminals after a 60 s grace using a new durable suspended row status that respawns on attach; the earlier attempts left rows active and lost every terminal after one reaper tick.
  3. 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.
  4. 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.ts owns the reason union, the predicates isTombstoned (stamped with any reason but user, including a reason-less stamp) and isUserArchived, and their SQL twins tombstoned / userArchived / notTombstoned. archive_reason is plain text, so no migration; the branch does not touch drizzle/.
  • Every host reader that meant "destroyed" switched to the predicates: workspace.list's default filter and worktreeExists, branch reuse in workspaces.create and 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 (tombstoneLocalWorkspace returns 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/unarchive refuse main workspaces and tombstoned rows, are idempotent via conditional UPDATE … WHERE archived_at IS NULL (two requests in one tick broadcast and count once), broadcast a normal updated event (clients move the row between lists instead of dropping it), and emit workspace_archived / workspace_unarchived with a source (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.create unarchives 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 / archiveReason ride the WorkspaceSnapshot wire type and the workspace.list row. workspace.list hides 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

  • killSessionRuntime is extracted from disposeSessionAndWait; suspendSessionAndWait calls it and, only after a confirmed kill, marks the row suspended and ends its agent binding as terminal-exited in one transaction. The binding is ended, never deleted: a surviving agentSessionId with 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 to active.
  • The reaper's pure planArchivedSuspends suspends 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. loadArchivedWorkspaces lists 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.status was audited (table in the plan); sweepDefunct gained suspended as belt and braces.

Part 3: Renderer

What / How

  • useHostWorkspaces splits the same cached rows into workspaces and archivedWorkspaces by the user reason (a tombstone stays on the live side, where the board expects it on includeArchived), and exposes findWorkspace(id) for the few consumers that must see archived rows (delete dialogs, host resolution, the workspace route, the archive flow). Every other consumer reads workspaces and hides archived rows with no further change. The event patcher treats archivedAt: null as a real value (an unarchive) and only an absent field as "keep the cached one". isTombstonedWorkspace / isUserArchivedWorkspace are 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 headless ArchiveWorkspaceMount next to DeleteWorkspaceMount, 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

  • V2WorkspacesViewMode gains "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=archived are 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.
  • useAccessibleV2Workspaces gains archivedView (rows from the archived split, with the same PR/agent/project enrichment) and archivedCount.
  • V2WorkspacesArchived lists rows newest-first with name, font-mono branch, project (or "Sessions"), the PR chip, a localized "Archived {relative time}", and hover-revealed Unarchive / Delete. Per-row Delete pushes into useDeleteWorkspaceIntent; Delete all pushes into useBulkDeleteWorkspacesIntent (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 on isReady and explains itself when filters hide everything.
  • WorkspaceArchivedState renders for a deep link to an archived workspace with Unarchive and "View archived workspaces".

Key decisions

DecisionChoiceRationale
Columnsarchived_at + archive_reason = "user", no shelved_atreview wanted one archive concept; the cost (every "destroyed" reader must ask isTombstoned) is paid once in archive-state.ts and tested
Suspended terminal rownew suspended status, binding ended not deletedthe stale-active sweep only touches active; terminal-exited + surviving session id = resume candidate
Suspend timingreaper 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 pointsone intent queue + one mountthe flow needs the navigate-away helper (flattens the sidebar); per-row hooks would be O(rows²)
Analyticshost-side only, with sourceCLI/MCP archives count; no double-emission from the renderer
Archived homethird view on the Workspaces pagesettled in live review; whether it should move to Settings is still being discussed on the page
Deleteonly from the Archived view (host workspaces)review saw no purpose in Delete next to Archive; one destructive path behind one deliberate step
Cloud sandboxeskeep Delete as their closearchive is host-local; cloud archive is a follow-up Satya takes

Keyboard shortcuts

ShortcutBeforeAfter
⌘⇧⌫ Close Workspace (v2 local/remote host)opens the delete dialogarchives, no dialog
⌘⇧⌫ on v1 or a cloud sandboxdelete dialogunchanged (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_MS and REAP_INTERVAL_MS locally), 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 test in packages/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 unchanged
  • bun test in apps/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's tsconfig, 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 unarchive commands) instead of unarchiving it; open on the review page.
  • A server-side flag on workspace.list so superset workspaces list and MCP workspaces_list can hide user-archived rows by default; rows already carry archivedAt / 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 archive answers the new mutation with BAD_REQUEST; the flow rolls back and toasts. An older host omits archiveReason from 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_at migration 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, run UPDATE workspaces SET archived_at = NULL, archive_reason = NULL WHERE archive_reason = 'user' on each host database, or unarchive everything from the Archived view first. Any suspended terminal row respawns on attach exactly like a daemon-lost active row 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 rollback
  • packages/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 to isTombstoned
  • packages/host-service/src/terminal/{terminal,attach-plan}.ts, terminal/reaper/reaper.ts, terminal-agents/persistence.ts — suspend, attach planner, reaper pass
  • apps/desktop/src/renderer/hooks/host-workspaces/useHostWorkspaces/* — the split, the predicates, findWorkspace
  • apps/desktop/src/renderer/lib/workspaces/useArchiveWorkspaceFlow/*, stores/archive-workspace-intent.ts, commandPalette/ui/ArchiveWorkspaceMount/* — the flow
  • apps/desktop/src/renderer/routes/_authenticated/_dashboard/components/DashboardSidebar/**, commandPalette/modules/**, _dashboard/layout.tsx, hotkeys/registry.ts — entry points, Delete removed from menus
  • apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/** — header, store, Archived view, search parser, board column derivation
  • apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/** — deep-link archived state
  • apps/mobile/hooks/** — archived rows hidden on the phone
  • packages/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_reason destroy tombstone pair with a third reason, user, so no migration and drizzle/ is untouched.
  • Every host reader that meant "destroyed" now asks a shared isTombstoned predicate in archive-state.ts, so a user archive never reads as an interrupted delete.
  • workspaceCleanup.archive/unarchive stamp 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 suspended status; 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 archive answers BAD_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.