From c63744cf7c8115d0c5ea75707fba6b92869dcffa Mon Sep 17 00:00:00 2001
From: Taylor Ho <taylorkmho@gmail.com>
Date: Thu, 6 Aug 2026 16:52:38 -0700
Subject: [PATCH] fix(desktop): preserve routed onboarding after recovery

Co-authored-by: Taylor Ho <taylorkmho@gmail.com>
Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
---
 desktop/src/app/App.tsx                             |  2 +-
 .../src/features/communities/ui/WelcomeSetup.tsx    | 13 +++++++++++--
 .../src/features/onboarding/OnboardingHistory.tsx   | 11 +++++++----
 .../onboarding/ui/MachineOnboardingFlow.tsx         |  2 +-
 desktop/tests/e2e/community-rail.spec.ts            |  6 ++++++
 desktop/tests/e2e/identity-lost.spec.ts             | 10 ++++++++++
 6 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/desktop/src/app/App.tsx b/desktop/src/app/App.tsx
index 3075eb80a..df0507513 100644
--- a/desktop/src/app/App.tsx
+++ b/desktop/src/app/App.tsx
@@ -521,7 +521,7 @@ function CommunityApp({
     if (community.needsSetup) {
       // Show welcome setup for first-run users with no communities
       appContent = (
-<WelcomeSetup
+        <WelcomeSetup
           canReturnToMachineConfig={!isFindingCommunityAfterLeave}
           initialPage={resumeFirstCommunityPage ?? undefined}
         />
diff --git a/desktop/src/features/communities/ui/WelcomeSetup.tsx b/desktop/src/features/communities/ui/WelcomeSetup.tsx
index 39c425aa3..40754a73e 100644
--- a/desktop/src/features/communities/ui/WelcomeSetup.tsx
+++ b/desktop/src/features/communities/ui/WelcomeSetup.tsx
@@ -80,7 +80,14 @@ export function WelcomeSetup({
   React.useEffect(() => {
     const step = onboardingHistory.step;
     if (!step) {
-      onboardingHistory.replace(routeForWelcomePage(page));
+      if (canReturnToMachineConfig) {
+        onboardingHistory.replace(routeForWelcomePage(page));
+      } else {
+        // Leaving the final community starts a new discovery flow. Retire the
+        // app history behind it so browser Back cannot escape to a route that
+        // no longer has an active community.
+        onboardingHistory.reset(routeForWelcomePage(page));
+      }
       return;
     }
     if (isMachineOnboardingRouteStep(step)) return;
@@ -97,8 +104,10 @@ export function WelcomeSetup({
     setIsHostedSignInOpen(false);
     setPage(pageForWelcomeRoute(step));
   }, [
+    canReturnToMachineConfig,
     onboardingHistory.direction,
     onboardingHistory.replace,
+    onboardingHistory.reset,
     onboardingHistory.step,
     page,
   ]);
@@ -209,7 +218,7 @@ export function WelcomeSetup({
                   </button>
                 </Card>
               </div>
-{canReturnToMachineConfig ? (
+              {canReturnToMachineConfig ? (
                 <OnboardingFooter>
                   <Button
                     className="h-9 rounded-full bg-foreground/10 px-6 hover:bg-foreground/15"
diff --git a/desktop/src/features/onboarding/OnboardingHistory.tsx b/desktop/src/features/onboarding/OnboardingHistory.tsx
index 1baeb55af..b482b72ab 100644
--- a/desktop/src/features/onboarding/OnboardingHistory.tsx
+++ b/desktop/src/features/onboarding/OnboardingHistory.tsx
@@ -101,10 +101,13 @@ export function OnboardingHistoryProvider({
   const reset = React.useCallback((step: OnboardingRouteStep) => {
     const sessionId = crypto.randomUUID();
     sessionIdRef.current = sessionId;
-    router.history.replace(
-      onboardingRoutePath(step),
-      createOnboardingHistoryState(sessionId, 0),
-    );
+    const path = onboardingRoutePath(step);
+    const state = createOnboardingHistoryState(sessionId, 0);
+    // Replace the route being retired, then leave an equivalent current entry.
+    // Browser Back lands on the fresh session boundary instead of reviving the
+    // app or completed onboarding route that preceded it.
+    router.history.replace(path, state);
+    router.history.push(path, state);
   }, []);
 
   const backBy = React.useCallback(
diff --git a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
index 4d2788c32..da5384e46 100644
--- a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
@@ -431,7 +431,7 @@ export function MachineOnboardingFlow({
                 </div>
               </motion.div>
               <div className="buzz-onboarding-key-import-position w-full">
-<div className="flex flex-col items-center">
+                <div className="flex flex-col items-center">
                   <NostrKeyImportForm
                     backLabel="Back"
                     onBack={() => {
diff --git a/desktop/tests/e2e/community-rail.spec.ts b/desktop/tests/e2e/community-rail.spec.ts
index 0a4c8830e..d06e7636d 100644
--- a/desktop/tests/e2e/community-rail.spec.ts
+++ b/desktop/tests/e2e/community-rail.spec.ts
@@ -851,6 +851,12 @@ test.describe("community rail", () => {
       .click();
 
     await expect(page.getByText("Join or create a community")).toBeVisible();
+    await expect(page).toHaveURL(/#\/onboarding\/community$/);
+    await expect(page.getByTestId("welcome-setup-back")).toHaveCount(0);
+    await expect(page.getByTestId("community-choice-join")).toBeVisible();
+    await page.goBack();
+    await expect(page.getByText("Join or create a community")).toBeVisible();
+    await expect(page).toHaveURL(/#\/onboarding\/community$/);
     await expect(page.getByTestId("welcome-setup-back")).toHaveCount(0);
     await expect(page.getByTestId("community-choice-join")).toBeVisible();
     await expect
diff --git a/desktop/tests/e2e/identity-lost.spec.ts b/desktop/tests/e2e/identity-lost.spec.ts
index 2ab41cb52..5a19197f4 100644
--- a/desktop/tests/e2e/identity-lost.spec.ts
+++ b/desktop/tests/e2e/identity-lost.spec.ts
@@ -272,6 +272,7 @@ test("phone recovery continues to harness setup without creating or restarting",
     { skipOnboardingSeed: true },
   );
   await page.goto("/");
+  await expect(page).toHaveURL(/#\/onboarding\/key-import$/);
   await page.getByTestId("nostr-import-phone-link").click();
   await expect(page.getByTestId("identity-recovery-qr")).toBeVisible();
 
@@ -281,6 +282,15 @@ test("phone recovery continues to harness setup without creating or restarting",
     );
   });
 
+  await expect(
+    page.getByRole("heading", { name: "Set up your agent harnesses" }),
+  ).toBeVisible();
+  await expect(page).toHaveURL(/#\/onboarding\/agents$/);
+  await page.goBack();
+  await expect(page).toHaveURL(/#\/onboarding\/key-import$/);
+  await expect(page.getByTestId("nostr-import-card")).toBeVisible();
+  await page.goForward();
+  await expect(page).toHaveURL(/#\/onboarding\/agents$/);
   await expect(
     page.getByRole("heading", { name: "Set up your agent harnesses" }),
   ).toBeVisible();