fix(web): keep VPS IP out of normal wizard URLs

The Create VPS step told users their VPS IP stayed on-device, but the normal localStorage path also wrote the IP into the URL query string. That made ordinary wizard navigation carry the IP in browser-visible URLs even though URL state is only needed for storage-blocked browsers.

Change setVPSIP so successful localStorage persistence removes any stale ip query parameter, while storage failures still use the query string fallback. Update the page copy to describe that fallback accurately.

Pin the behavior with unit tests for both persistence paths, and update the wizard E2E expectations so normal flows require the IP to stay out of the URL while the no-localStorage flow still carries it.

Also fixed the VPS persistence E2E setup to unlock steps 1-4 before visiting create-vps, matching the route guard contract instead of racing a redirect.

Verified with: git diff --check; bun test lib/progressPersistence.test.ts; CI=1 PW_WORKERS=1 PW_PORT=3117 bun run test -- e2e/wizard-flow.spec.ts --grep 'Create VPS|LocalStorage Persistence|No localStorage|complete full wizard flow' --project=chromium --reporter=line; CI=1 PW_WORKERS=1 PW_PORT=3119 bun run test -- e2e/wizard-flow.spec.ts --grep 'State Persistence|Complete Wizard Flow Integration' --project=chromium --reporter=line; ubs apps/web/lib/userPreferences.ts apps/web/app/wizard/create-vps/page.tsx apps/web/e2e/wizard-flow.spec.ts apps/web/lib/progressPersistence.test.ts; bun run type-check; bun run lint; bun run build.

Author: Dicklesworthstone

apps/web/app/wizard/create-vps/page.tsx

@@ -353,8 +353,8 @@ export default function CreateVPSPage() {
                 Your data stays on your device
               </p>
               <p className="text-[12px] leading-relaxed text-muted-foreground sm:text-[13px]">
-                This IP address is stored <strong className="text-foreground/80">only in your browser&apos;s local storage</strong>. It&apos;s
-                never sent to our servers or any third party. The{" "}
+                This IP address is stored <strong className="text-foreground/80">in your browser&apos;s local storage</strong>.
+                If browser storage is blocked, the wizard keeps it in the page URL so the next step still works. The{" "}
                 <a
                   href="https://github.com/Dicklesworthstone/agentic_coding_flywheel_setup"
                   target="_blank"

apps/web/e2e/wizard-flow.spec.ts

@@ -271,7 +271,7 @@ test.describe("Wizard Flow", () => {
     await expect(page).toHaveURL(urlPathWithOptionalQuery("/wizard/ssh-connect"));
     const step6Url = new URL(page.url());
     expect(step6Url.searchParams.get("os")).toBe("mac");
-    expect(step6Url.searchParams.get("ip")).toBe("192.168.1.100");
+    expect(step6Url.searchParams.get("ip")).toBeNull();
   });
 });
 
@@ -428,9 +428,9 @@ test.describe("State Persistence", () => {
 
   test("should persist VPS IP across page reloads", async ({ page }) => {
     // Set up prerequisite state
-    await page.goto("/");
-    await page.evaluate(() => {
-      localStorage.setItem("agent-flywheel-user-os", "mac");
+    await setupWizardState(page, {
+      os: "mac",
+      completedSteps: [1, 2, 3, 4],
     });
 
     await page.goto("/wizard/create-vps");
@@ -464,8 +464,8 @@ test.describe("State Persistence", () => {
     const ip = await page.evaluate(() => localStorage.getItem("agent-flywheel-vps-ip"));
     expect(ip).toBe("10.0.0.50");
 
-    // URL query string should also reflect the IP
-    expect(new URL(page.url()).searchParams.get("ip")).toBe("10.0.0.50");
+    // When localStorage works, the IP should stay out of the URL.
+    expect(new URL(page.url()).searchParams.get("ip")).toBeNull();
   });
 });
 
@@ -669,7 +669,7 @@ test.describe("Complete Wizard Flow Integration", () => {
     await expect(page).toHaveURL(urlPathWithOptionalQuery("/wizard/ssh-connect"));
     const sshConnectUrl = new URL(page.url());
     expect(sshConnectUrl.searchParams.get("os")).toBe("mac");
-    expect(sshConnectUrl.searchParams.get("ip")).toBe("192.168.1.100");
+    expect(sshConnectUrl.searchParams.get("ip")).toBeNull();
 
     // Step 6: SSH Connect - THE CRITICAL TEST
     // This should NOT get stuck on a loading spinner

apps/web/lib/progressPersistence.test.ts

@@ -21,33 +21,65 @@ import {
   CREATE_VPS_CHECKLIST_KEY,
   getACFSRef,
   getCreateVPSChecklist,
+  getVPSIP,
   setACFSRef,
   setCreateVPSChecklist,
+  setVPSIP,
 } from "./userPreferences";
 
 type StorageController = {
   dispatchCalls: Event[];
+  getCurrentUrl: () => string | null;
   getStoredValue: (key: string) => string | null;
 };
 
 const originalWindow = globalThis.window;
 const originalLocalStorage = globalThis.localStorage;
+const VPS_IP_TEST_KEY = "agent-flywheel-vps-ip";
 
 function installMockBrowser(options?: {
   failSetItemForKey?: string;
   initialValues?: Record<string, string>;
+  url?: string;
 }): StorageController {
   const dispatchCalls: Event[] = [];
   const storage = new Map(Object.entries(options?.initialValues ?? {}));
+  let currentUrl = options?.url ? new URL(options.url) : null;
+  let historyState: unknown = null;
+
+  const windowValue = {
+    dispatchEvent(event: Event) {
+      dispatchCalls.push(event);
+      return true;
+    },
+  };
+
+  if (currentUrl) {
+    Object.defineProperty(windowValue, "location", {
+      configurable: true,
+      get() {
+        return currentUrl;
+      },
+    });
+    Object.defineProperty(windowValue, "history", {
+      configurable: true,
+      value: {
+        get state() {
+          return historyState;
+        },
+        replaceState(state: unknown, _unused: string, url?: string | URL | null) {
+          historyState = state;
+          if (url) {
+            currentUrl = new URL(String(url), currentUrl?.href);
+          }
+        },
+      },
+    });
+  }
 
   Object.defineProperty(globalThis, "window", {
     configurable: true,
-    value: {
-      dispatchEvent(event: Event) {
-        dispatchCalls.push(event);
-        return true;
-      },
-    },
+    value: windowValue,
   });
 
   Object.defineProperty(globalThis, "localStorage", {
@@ -70,6 +102,9 @@ function installMockBrowser(options?: {
 
   return {
     dispatchCalls,
+    getCurrentUrl() {
+      return currentUrl?.toString() ?? null;
+    },
     getStoredValue(key: string) {
       return storage.get(key) ?? null;
     },
@@ -187,6 +222,31 @@ describe("progress persistence guards", () => {
     expect(failingBrowser.dispatchCalls).toHaveLength(0);
   });
 
+  test("VPS IP stays out of the URL when localStorage works", () => {
+    const browser = installMockBrowser({
+      url: "https://example.test/wizard/create-vps?os=mac&ip=192.0.2.10",
+    });
+
+    expect(setVPSIP("10.0.0.50")).toBe(true);
+    expect(browser.getStoredValue(VPS_IP_TEST_KEY)).toBe("10.0.0.50");
+    expect(new URL(browser.getCurrentUrl() ?? "").searchParams.get("ip")).toBeNull();
+    expect(getVPSIP()).toBe("10.0.0.50");
+    expect(browser.dispatchCalls).toHaveLength(1);
+  });
+
+  test("VPS IP uses the URL only when localStorage is blocked", () => {
+    const browser = installMockBrowser({
+      failSetItemForKey: VPS_IP_TEST_KEY,
+      url: "https://example.test/wizard/create-vps?os=mac",
+    });
+
+    expect(setVPSIP("10.0.0.50")).toBe(true);
+    expect(browser.getStoredValue(VPS_IP_TEST_KEY)).toBeNull();
+    expect(new URL(browser.getCurrentUrl() ?? "").searchParams.get("ip")).toBe("10.0.0.50");
+    expect(getVPSIP()).toBe("10.0.0.50");
+    expect(browser.dispatchCalls).toHaveLength(1);
+  });
+
   test("ACFS ref persistence rejects invalid refs without clearing the saved ref", () => {
     const browser = installMockBrowser({
       initialValues: {

apps/web/lib/userPreferences.ts

@@ -185,7 +185,7 @@ export function detectOS(): OperatingSystem | null {
 }
 
 /**
- * Get the user's VPS IP address from localStorage.
+ * Get the user's VPS IP address from the URL fallback or localStorage.
  */
 export function getVPSIP(): string | null {
   const fromQuery = getQueryParam(VPS_IP_QUERY_KEY);
@@ -203,16 +203,15 @@ export function getVPSIP(): string | null {
 
 /**
  * Save the user's VPS IP address to localStorage.
- * Only saves if the IP is valid to prevent storing malformed data.
- * Returns true if saved successfully, false otherwise.
+ * Only keeps the IP in the URL when localStorage is unavailable.
  */
 export function setVPSIP(ip: string): boolean {
   const normalized = ip.trim();
   if (!isValidIP(normalized)) {
     return false;
   }
   const storedOk = safeSetItem(VPS_IP_KEY, normalized);
-  const urlOk = setQueryParam(VPS_IP_QUERY_KEY, normalized);
+  const urlOk = setQueryParam(VPS_IP_QUERY_KEY, storedOk ? null : normalized);
   if (storedOk || urlOk) {
     emitUserPreferencesUpdate();
   }