Improve the archived workspace restore flow (#2002)

* fix(app): restore missing workspaces from History

Workspace and agent archival are separate lifecycles. Carry restore intent from History so closed agents can reopen archived workspaces without changing ordinary navigation.

* fix(app): wait for workspace hydration before restore

* fix(app): preserve History agent unarchive

* fix(app): reopen archived History agents outside active directory

History entries are not merged into the active session maps. Carry the row archive state through explicit restore intent so live workspaces still reopen without broadening ordinary navigation.

* fix(app): ignore stale History archive state for active agents

A cached History row can outlive a successful reopen. When the workspace exists, live session state now wins so an active agent is not interrupted by another refresh.

* fix(app): reopen every selected archived History agent

History entries without workspace IDs returned before restoration, and a second archived agent sharing an in-flight workspace restore was dropped. Preserve both agent-only and deferred reopen intent.

* fix(app): require explicit workspace recovery

* fix: preserve workspace recovery contracts

* fix: preserve workspace recovery compatibility

* fix: preserve recovered workspace session state

* fix: preserve terminal navigation timing

* fix(server): preserve successful workspace recovery

* fix: preserve workspace recovery intent

packages/app/e2e/archive-tab.spec.ts

@@ -15,7 +15,6 @@ import {
   expectWorkspaceArchiveOutcome,
   expectWorkspaceTabHidden,
   fetchAgentArchivedAt,
-  expectWorkspaceTabVisible,
   openSessions,
   openWorkspaceWithAgents,
   primeAdditionalPage,
@@ -123,7 +122,7 @@ test.describe("Archive tab reconciliation", () => {
     }
   });
 
-  test("clicking an archived session unarchives it and opens the agent", async ({ page }) => {
+  test("clicking an archived session navigates without unarchiving it", async ({ page }) => {
     const archived = await createIdleAgent(client, {
       cwd: tempRepo.path,
       workspaceId,
@@ -138,18 +137,17 @@ test.describe("Archive tab reconciliation", () => {
     await resetSeededPageState(page);
     await openWorkspaceWithAgents(page, [archived, surviving]);
     await archiveAgentFromDaemon(client, archived.id);
+    const archivedAt = await fetchAgentArchivedAt(client, archived.id);
+    expect(archivedAt).not.toBeNull();
     await openSessions(page);
     await expectSessionRowArchived(page, archived.title);
 
     await clickSessionRow(page, archived.title);
 
-    await expect
-      .poll(() => fetchAgentArchivedAt(client, archived.id), { timeout: 30_000 })
-      .toBeNull();
+    expect(await fetchAgentArchivedAt(client, archived.id)).toBe(archivedAt);
 
     await expect(page).toHaveURL(buildHostWorkspaceRoute(getServerId(), archived.workspaceId), {
       timeout: 30_000,
     });
-    await expectWorkspaceTabVisible(page, archived.id);
   });
 });

packages/app/e2e/helpers/archive-tab.ts

@@ -103,12 +103,6 @@ export async function fetchAgentArchivedAt(
   return result?.agent.archivedAt ?? null;
 }
 
-export function getWorktreeRestoreFeature(client: {
-  getLastServerInfoMessage(): { features?: { worktreeRestore?: boolean } | null } | null;
-}): boolean {
-  return client.getLastServerInfoMessage()?.features?.worktreeRestore === true;
-}
-
 export async function primeAdditionalPage(page: Page): Promise<void> {
   const seedNonce = randomUUID();
   const { daemon, preferences } = buildSeededStoragePayload();

packages/app/e2e/helpers/new-workspace.ts

@@ -17,6 +17,8 @@ type NewWorkspaceDaemonClient = Pick<
   | "fetchWorkspaces"
   | "getPaseoWorktreeList"
   | "getDaemonConfig"
+  | "inspectWorkspaceRecovery"
+  | "on"
   | "patchDaemonConfig"
   | "removeProject"
 >;

packages/app/e2e/helpers/schedule-fake-host.ts

@@ -156,7 +156,7 @@ export async function installFakeScheduleHost(input: {
               workspaceMultiplicity: true,
               projectAdd: true,
               projectRemove: true,
-              worktreeRestore: true,
+              workspaceRecovery: true,
             },
           }),
         );

packages/app/e2e/helpers/seed-client.ts

@@ -132,11 +132,15 @@ export interface SeedDaemonClient {
     timeout?: number,
   ): Promise<{ status: string; final?: { lastError?: string | null } | null }>;
   archiveAgent(agentId: string): Promise<{ archivedAt: string }>;
+  refreshAgent(agentId: string): Promise<unknown>;
   fetchAgent(options: {
     agentId: string;
   }): Promise<{ agent: { id: string; archivedAt?: string | null } } | null>;
   getLastServerInfoMessage(): {
-    features?: { projectAdd?: boolean; worktreeRestore?: boolean } | null;
+    features?: {
+      projectAdd?: boolean;
+      workspaceRecovery?: boolean;
+    } | null;
   } | null;
   fetchAgentHistory(options?: {
     page?: { limit: number };

packages/app/e2e/helpers/terminal-perf.ts

@@ -78,13 +78,8 @@ export async function navigateToTerminal(
     { timeout: 30_000 },
   );
 
-  // Wait for daemon connection (sidebar shows host label)
-  await page
-    .getByText("localhost", { exact: true })
-    .first()
-    .waitFor({ state: "visible", timeout: 30_000 });
-
   // The open intent should have prepared and focused the exact pre-created terminal tab.
+  // Its presence is the user-visible proof that workspace and terminal state have hydrated.
   // The tab reconciliation effect also auto-creates terminal tabs once hydration completes,
   // so we give it enough time for the full workspace hydration + tab creation cycle.
   const terminalTab = page.locator(`[data-testid="workspace-tab-terminal_${input.terminalId}"]`);

packages/app/e2e/worktree-restore.spec.ts

@@ -1,16 +1,25 @@
 import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { rename } from "node:fs/promises";
+import type { Page } from "@playwright/test";
+import { buildHostWorkspaceRoute } from "@/utils/host-routes";
 import { expect, test } from "./fixtures";
 import { gotoAppShell } from "./helpers/app";
 import {
-  archiveAgentFromDaemon,
+  expectWorkspaceBranch,
+  openChangesPanel,
+  switchBranchFromChangesPanel,
+} from "./helpers/branch-switcher";
+import {
   createIdleAgent,
-  expectSessionRowArchived,
+  expectSessionRowNotArchived,
   fetchAgentArchivedAt,
   openSessions,
 } from "./helpers/archive-tab";
 import {
   archiveWorkspaceFromDaemon,
+  archiveLocalWorkspaceFromDaemon,
   connectNewWorkspaceDaemonClient,
   createWorktreeViaDaemon,
   openProjectViaDaemon,
@@ -35,6 +44,63 @@ test.describe("Worktree restore", () => {
     tempRepo = await createTempGitRepo("wt-restore-");
   });
 
+  async function createArchivedMissingWorktree(prefix: string) {
+    const project = await openProjectViaDaemon(worktreeClient, tempRepo.path);
+    createdProjectIds.add(project.projectKey);
+    const worktree = await createWorktreeViaDaemon(worktreeClient, {
+      cwd: tempRepo.path,
+      slug: `${prefix}-${randomUUID().slice(0, 8)}`,
+    });
+    createdProjectIds.add(worktree.projectKey);
+    createdWorktreeDirectories.add(worktree.workspaceDirectory);
+    const agent = await createIdleAgent(client, {
+      cwd: worktree.workspaceDirectory,
+      workspaceId: worktree.workspaceId,
+      title: `${prefix}-${randomUUID().slice(0, 8)}`,
+    });
+
+    await archiveWorkspaceFromDaemon(worktreeClient, worktree.workspaceDirectory);
+    await expect
+      .poll(() => existsSync(worktree.workspaceDirectory), { timeout: 30_000 })
+      .toBe(false);
+
+    // Match the remote cloud-race record: workspace archived and absent, while
+    // the surviving closed agent record is not agent-archived. Refresh now owns
+    // only agent lifecycle, so its expected cwd failure cannot recover the workspace.
+    await client.refreshAgent(agent.id).catch(() => undefined);
+    await expect.poll(() => fetchAgentArchivedAt(client, agent.id), { timeout: 30_000 }).toBeNull();
+    expect(existsSync(worktree.workspaceDirectory)).toBe(false);
+
+    return { agent, worktree };
+  }
+
+  async function openArchivedWorkspaceFromHistory(page: Page, prefix: string) {
+    const seeded = await createArchivedMissingWorktree(prefix);
+    await gotoAppShell(page);
+    await waitForSidebarHydration(page);
+    await openSessions(page);
+    await expectSessionRowNotArchived(page, seeded.agent.title);
+    await page.getByTestId(`agent-row-${getServerId()}-${seeded.agent.id}`).click();
+    await expect(page.getByText("Workspace archived", { exact: true })).toBeVisible({
+      timeout: 30_000,
+    });
+    await expect(page.getByTestId("workspace-recovery-action")).toHaveText("Restore");
+    return seeded;
+  }
+
+  async function openArchivedAgentBeforeWorkspaceHydration(page: Page, prefix: string) {
+    const seeded = await createArchivedMissingWorktree(prefix);
+    const workspaceRoute = buildHostWorkspaceRoute(getServerId(), seeded.worktree.workspaceId);
+    const openAgent = encodeURIComponent(`agent:${seeded.agent.id}`);
+
+    await page.goto(`${workspaceRoute}?open=${openAgent}`);
+    await expect(page.getByText("Workspace archived", { exact: true })).toBeVisible({
+      timeout: 30_000,
+    });
+    await expect(page.getByTestId("workspace-recovery-action")).toHaveText("Restore");
+    return seeded;
+  }
+
   test.afterEach(async () => {
     for (const directory of createdWorktreeDirectories) {
       await archiveWorkspaceFromDaemon(worktreeClient, directory).catch(() => undefined);
@@ -49,7 +115,7 @@ test.describe("Worktree restore", () => {
     await tempRepo?.cleanup().catch(() => undefined);
   });
 
-  test("archiving an agent, then clicking it in History unarchives it in place (worktree dir untouched)", async ({
+  test("opening an active History agent navigates without restoring or unarchiving", async ({
     page,
   }) => {
     const serverId = getServerId();
@@ -69,70 +135,176 @@ test.describe("Worktree restore", () => {
     });
     expect(existsSync(worktree.workspaceDirectory)).toBe(true);
 
-    await archiveAgentFromDaemon(client, agent.id);
+    expect(await fetchAgentArchivedAt(client, agent.id)).toBeNull();
 
     await gotoAppShell(page);
     await waitForSidebarHydration(page);
     await openSessions(page);
-    await expectSessionRowArchived(page, agent.title);
+    await expectSessionRowNotArchived(page, agent.title);
 
     await page.getByTestId(`agent-row-${serverId}-${agent.id}`).click();
 
-    await expect.poll(() => fetchAgentArchivedAt(client, agent.id), { timeout: 30_000 }).toBeNull();
+    await expect(
+      page.getByTestId(`workspace-tab-agent_${agent.id}`).filter({ visible: true }).first(),
+    ).toBeVisible({ timeout: 30_000 });
+    await expect(page.getByRole("button", { name: "Unarchive" })).toHaveCount(0);
+    expect(await fetchAgentArchivedAt(client, agent.id)).toBeNull();
     expect(existsSync(worktree.workspaceDirectory)).toBe(true);
 
-    // The History list is a cached react-query snapshot, so the cleared Archived
-    // badge only renders after a cold refetch. Reload to remount the query fresh.
-    await page.reload();
-    await waitForSidebarHydration(page);
     await openSessions(page);
-    const row = page
-      .locator('[data-testid^="agent-row-"]')
-      .filter({ hasText: agent.title })
-      .first();
-    await expect(row).toBeVisible({ timeout: 30_000 });
-    await expect(row).not.toContainText("Archived", { timeout: 30_000 });
+    await expectSessionRowNotArchived(page, agent.title);
+    await page.getByTestId(`agent-row-${serverId}-${agent.id}`).click();
+
+    await expect(
+      page.getByTestId(`workspace-tab-agent_${agent.id}`).filter({ visible: true }).first(),
+    ).toBeVisible({ timeout: 30_000 });
+    await expect(
+      page.getByTestId(`workspace-deck-entry-${serverId}:${worktree.workspaceId}`),
+    ).toHaveCount(1);
+    expect(await fetchAgentArchivedAt(client, agent.id)).toBeNull();
   });
 
-  test("archiving a worktree (dir deleted), then clicking its agent in History recreates the worktree", async ({
+  test("opening a recoverable archived workspace shows an explicit Restore action without mutating it", async ({
     page,
   }) => {
-    const serverId = getServerId();
-    const project = await openProjectViaDaemon(worktreeClient, tempRepo.path);
-    createdProjectIds.add(project.projectKey);
-    const worktree = await createWorktreeViaDaemon(worktreeClient, {
+    const { agent, worktree } = await openArchivedWorkspaceFromHistory(page, "restore-ready");
+    expect(await fetchAgentArchivedAt(client, agent.id)).toBeNull();
+    expect(existsSync(worktree.workspaceDirectory)).toBe(false);
+    await expect(
+      worktreeClient.inspectWorkspaceRecovery(worktree.workspaceId),
+    ).resolves.toMatchObject({ kind: "recoverable", action: "restore" });
+  });
+
+  test("explicit Restore shows loading and opens the recreated workspace", async ({ page }) => {
+    const { agent, worktree } = await openArchivedAgentBeforeWorkspaceHydration(
+      page,
+      "restore-success",
+    );
+    await worktreeClient.fetchWorkspaces({
+      subscribe: { subscriptionId: `restore-secondary-${randomUUID()}` },
+    });
+    let updateTimeout: ReturnType<typeof setTimeout> | null = null;
+    let unsubscribeSecondaryWorkspaceUpdate = () => {};
+    const secondaryWorkspaceUpdate = new Promise<void>((resolve, reject) => {
+      updateTimeout = setTimeout(
+        () => reject(new Error("Secondary client did not receive the restored workspace")),
+        30_000,
+      );
+      unsubscribeSecondaryWorkspaceUpdate = worktreeClient.on("workspace_update", (message) => {
+        if (
+          message.payload.kind === "upsert" &&
+          message.payload.workspace.id === worktree.workspaceId
+        ) {
+          resolve();
+        }
+      });
+    });
+
+    try {
+      await page.getByTestId("workspace-recovery-action").click();
+
+      await expect(page.getByText("Restoring workspace", { exact: true })).toBeVisible();
+      await expect
+        .poll(() => existsSync(worktree.workspaceDirectory), { timeout: 30_000 })
+        .toBe(true);
+      await secondaryWorkspaceUpdate;
+      await waitForWorkspaceInSidebar(page, {
+        serverId: getServerId(),
+        workspaceId: worktree.workspaceId,
+      });
+      await expect(
+        page.getByTestId(`workspace-tab-agent_${agent.id}`).filter({ visible: true }).first(),
+      ).toBeVisible({ timeout: 30_000 });
+      await expect(page.getByTestId("workspace-recovery-action")).toHaveCount(0);
+      expect(await fetchAgentArchivedAt(client, agent.id)).toBeNull();
+    } finally {
+      unsubscribeSecondaryWorkspaceUpdate();
+      if (updateTimeout) {
+        clearTimeout(updateTimeout);
+      }
+    }
+
+    const switchedBranch = `restored-live-${randomUUID().slice(0, 8)}`;
+    execFileSync("git", ["branch", switchedBranch], {
       cwd: tempRepo.path,
-      slug: `restore-recreate-${randomUUID().slice(0, 8)}`,
+      stdio: "pipe",
     });
-    createdProjectIds.add(worktree.projectKey);
-    createdWorktreeDirectories.add(worktree.workspaceDirectory);
-
-    const agent = await createIdleAgent(client, {
-      cwd: worktree.workspaceDirectory,
-      workspaceId: worktree.workspaceId,
-      title: `restore-recreate-${randomUUID().slice(0, 8)}`,
+    await openChangesPanel(page);
+    await expectWorkspaceBranch(page, worktree.workspaceName);
+    await switchBranchFromChangesPanel(page, {
+      from: worktree.workspaceName,
+      to: switchedBranch,
     });
-    expect(existsSync(worktree.workspaceDirectory)).toBe(true);
+    await expectWorkspaceBranch(page, switchedBranch);
+    await expect(
+      page.getByTestId("workspace-header-title").filter({ visible: true }).first(),
+    ).toHaveText(switchedBranch, { timeout: 30_000 });
+  });
 
-    // Archive through the default production path the sidebar uses (no explicit
-    // scope). With the restore prune fix, this default path frees the kept branch
-    // so the daemon can re-check-out the worktree on restore.
-    await archiveWorkspaceFromDaemon(worktreeClient, worktree.workspaceDirectory);
-    await expect
-      .poll(() => existsSync(worktree.workspaceDirectory), { timeout: 30_000 })
-      .toBe(false);
+  test("restore failure stays visible and permits a successful retry", async ({ page }) => {
+    const { agent, worktree } = await openArchivedWorkspaceFromHistory(page, "restore-retry");
+    const displacedProjectPath = `${tempRepo.path}-temporarily-unavailable`;
+    await rename(tempRepo.path, displacedProjectPath);
 
-    await gotoAppShell(page);
-    await waitForSidebarHydration(page);
-    await openSessions(page);
-    await expectSessionRowArchived(page, agent.title);
-
-    await page.getByTestId(`agent-row-${serverId}-${agent.id}`).click();
+    try {
+      await page.getByTestId("workspace-recovery-action").click();
+      await expect(page.getByTestId("workspace-recovery-error")).toHaveText(
+        "The project directory needed to restore this worktree no longer exists.",
+      );
+      await expect(page.getByTestId("workspace-recovery-action")).toHaveText("Retry");
+      expect(existsSync(worktree.workspaceDirectory)).toBe(false);
+    } finally {
+      await rename(displacedProjectPath, tempRepo.path);
+    }
 
+    await page.getByTestId("workspace-recovery-action").click();
     await expect
       .poll(() => existsSync(worktree.workspaceDirectory), { timeout: 30_000 })
       .toBe(true);
-    await waitForWorkspaceInSidebar(page, { serverId, workspaceId: worktree.workspaceId });
+    await waitForWorkspaceInSidebar(page, {
+      serverId: getServerId(),
+      workspaceId: worktree.workspaceId,
+    });
+    await expect(
+      page.getByTestId(`workspace-tab-agent_${agent.id}`).filter({ visible: true }).first(),
+    ).toBeVisible({ timeout: 30_000 });
+  });
+
+  test("an unrecoverable missing workspace shows no misleading recovery action", async ({
+    page,
+  }) => {
+    const project = await openProjectViaDaemon(worktreeClient, tempRepo.path);
+    createdProjectIds.add(project.projectKey);
+    const agent = await createIdleAgent(client, {
+      cwd: project.workspaceDirectory,
+      workspaceId: project.workspaceId,
+      title: `unrecoverable-${randomUUID().slice(0, 8)}`,
+    });
+    await archiveLocalWorkspaceFromDaemon(worktreeClient, project.workspaceId);
+    await client.refreshAgent(agent.id).catch(() => undefined);
     await expect.poll(() => fetchAgentArchivedAt(client, agent.id), { timeout: 30_000 }).toBeNull();
+
+    const displacedProjectPath = `${tempRepo.path}-missing`;
+    await rename(tempRepo.path, displacedProjectPath);
+    try {
+      await gotoAppShell(page);
+      await waitForSidebarHydration(page);
+      await openSessions(page);
+      await expectSessionRowNotArchived(page, agent.title);
+      await page.getByTestId(`agent-row-${getServerId()}-${agent.id}`).click();
+
+      await expect(page.getByText("Workspace unavailable", { exact: true })).toBeVisible({
+        timeout: 30_000,
+      });
+      await expect(
+        page.getByText(
+          "The archived workspace directory no longer exists and cannot be recreated.",
+          { exact: true },
+        ),
+      ).toBeVisible();
+      await expect(page.getByTestId("workspace-recovery-action")).toHaveCount(0);
+    } finally {
+      await rename(displacedProjectPath, tempRepo.path);
+    }
   });
 });