fix(app): wait for the server before running the one-time imports

Found testing an upgrade against a real profile. The database migration
worked and the extension storage was intact, yet no providers or scheduled
tasks appeared, and the run looked like data loss.

The imports run when the background starts, which is the same moment the
server starts. They fired into a socket nothing was listening on yet and
threw. Because a failed run leaves its marker unset, the next launch lost
the same race, so the data never arrived at all while the database
migration looked like it had succeeded. Roughly six seconds passed between
the browser launching and the server answering.

The existing retry did not help because it retried the wrong thing.
resolveAgentServerUrlWithRetry retries getAgentServerUrl, which only reads
a preference and effectively never fails, so the budget was spent before
the request that needed it. The request itself had one attempt.

The imports now wait on the health endpoint first, so they wait for their
dependency rather than race it. Giving up returns false rather than
throwing, which leaves the markers unset deliberately for the next start,
and failures are reported through Sentry instead of swallowed: silence is
what made this look like lost data rather than a slow start.

Author: DaniAkash

packages/browseros-agent/apps/app/modules/local-first-migration/start-local-first-migration.ts

@@ -12,6 +12,7 @@ import {
   scheduledJobRunStorage,
   scheduledJobStorage,
 } from '@/lib/schedules/scheduleStorage'
+import { sentry } from '@/lib/sentry/sentry'
 import { resolveAgentServerUrlWithRetry } from '@/modules/browseros/agent-server-url.helpers'
 import { putDefaultProvider } from '@/modules/llm-providers/llm-providers.api'
 import { importScheduledJobRuns } from '@/modules/schedules/schedules.api'
@@ -25,6 +26,7 @@ import {
   parseProviderBackup,
   type ScheduledJobImport,
 } from './local-first-migration.helpers'
+import { waitForAgentServer } from './wait-for-agent-server'
 
 /**
  * Per profile, because extension storage is per profile. Losing it costs a
@@ -83,35 +85,77 @@ async function importScheduledJobs(jobs: ScheduledJobImport[]): Promise<void> {
   }
 }
 
-/** Fire and forget from the background; a failure retries on next startup. */
+/**
+ * Runs the one-time imports once the server is up.
+ *
+ * Everything here happens when the background starts, which is also when the
+ * server starts, so firing straight away meant importing into a socket nothing
+ * was listening on. Each import then failed, and because a failed run leaves
+ * its marker unset it lost the same race on the next launch too, so a user
+ * upgrading saw their providers and scheduled tasks simply never arrive while
+ * the database migration looked like it had worked.
+ *
+ * Waiting on health first removes the race. A failure past that point is worth
+ * seeing rather than swallowing: it is the difference between a slow start and
+ * data that never came across.
+ */
 export function startLocalFirstMigration(): void {
-  // The default is chained onto the provider import rather than fired
-  // alongside it: the id it names has to exist server side before it can be
-  // made default. The run history is independent and does not wait.
-  void runLocalFirstMigration({
-    isDone: () => migrationDoneStorage.getValue(),
-    markDone: () => migrationDoneStorage.setValue(true),
-    loadStoredProviders: async () => (await providersStorage.getValue()) ?? [],
-    loadBackupProviders,
-    loadScheduledJobs: async () => (await scheduledJobStorage.getValue()) ?? [],
-    importProviders,
-    importScheduledJobs,
-  })
-    .then(() =>
-      runDefaultProviderMigration({
+  void (async () => {
+    if (!(await waitForAgentServer())) {
+      sentry.captureException(
+        new Error('Agent server unreachable before the local-first import'),
+        {
+          extra: {
+            message:
+              'Imports deferred to the next start; markers remain unset so they will run again',
+          },
+        },
+      )
+      return
+    }
+
+    // The default is chained onto the provider import rather than run
+    // alongside it: the id it names has to exist server side before it can be
+    // made default. The run history is independent and does not wait.
+    try {
+      await runLocalFirstMigration({
+        isDone: () => migrationDoneStorage.getValue(),
+        markDone: () => migrationDoneStorage.setValue(true),
+        loadStoredProviders: async () =>
+          (await providersStorage.getValue()) ?? [],
+        loadBackupProviders,
+        loadScheduledJobs: async () =>
+          (await scheduledJobStorage.getValue()) ?? [],
+        importProviders,
+        importScheduledJobs,
+      })
+      await runDefaultProviderMigration({
         isDone: () => defaultMigrationDoneStorage.getValue(),
         markDone: () => defaultMigrationDoneStorage.setValue(true),
         loadStoredDefaultId: async () =>
           (await defaultProviderIdStorage.getValue()) || null,
         setDefault: putDefaultProvider,
-      }),
-    )
-    .catch(() => null)
+      })
+    } catch (error) {
+      // Reported rather than swallowed: a silent failure here is
+      // indistinguishable from the user's data having vanished, which is
+      // exactly how this went unnoticed.
+      sentry.captureException(error, {
+        extra: { message: 'Provider and scheduled job import failed' },
+      })
+    }
 
-  void runScheduledRunsMigration({
-    isDone: () => runsMigrationDoneStorage.getValue(),
-    markDone: () => runsMigrationDoneStorage.setValue(true),
-    loadRuns: async () => (await scheduledJobRunStorage.getValue()) ?? [],
-    importRuns: importScheduledJobRuns,
-  }).catch(() => null)
+    try {
+      await runScheduledRunsMigration({
+        isDone: () => runsMigrationDoneStorage.getValue(),
+        markDone: () => runsMigrationDoneStorage.setValue(true),
+        loadRuns: async () => (await scheduledJobRunStorage.getValue()) ?? [],
+        importRuns: importScheduledJobRuns,
+      })
+    } catch (error) {
+      sentry.captureException(error, {
+        extra: { message: 'Scheduled run history import failed' },
+      })
+    }
+  })()
 }

packages/browseros-agent/apps/app/modules/local-first-migration/wait-for-agent-server.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'bun:test'
+import { waitForAgentServer } from './wait-for-agent-server'
+
+function harness(healthyAfter: number) {
+  let calls = 0
+  let clock = 0
+  return {
+    calls: () => calls,
+    elapsed: () => clock,
+    opts: {
+      isHealthy: async () => {
+        calls += 1
+        return calls > healthyAfter
+      },
+      now: () => clock,
+      sleep: async (ms: number) => {
+        clock += ms
+      },
+      timeoutMs: 60_000,
+      intervalMs: 1_000,
+    },
+  }
+}
+
+describe('waitForAgentServer', () => {
+  it('returns immediately when the server is already up', async () => {
+    const h = harness(0)
+
+    expect(await waitForAgentServer(h.opts)).toBe(true)
+    expect(h.calls()).toBe(1)
+    expect(h.elapsed()).toBe(0)
+  })
+
+  // The case this exists for: the background starts at the same moment as the
+  // server, so the first few probes find nothing listening.
+  it('waits out a server that is still starting', async () => {
+    const h = harness(6)
+
+    expect(await waitForAgentServer(h.opts)).toBe(true)
+    expect(h.calls()).toBe(7)
+    expect(h.elapsed()).toBe(6_000)
+  })
+
+  // Six seconds is roughly what was observed between the browser launching and
+  // the server answering, and the previous behaviour gave up inside two.
+  it('outlasts the gap that made the import fail', async () => {
+    const h = harness(6)
+    await waitForAgentServer(h.opts)
+
+    expect(h.elapsed()).toBeGreaterThan(1_500)
+  })
+
+  // Giving up rather than throwing is what lets the caller leave the markers
+  // unset, so the next start tries again.
+  it('reports failure rather than throwing when the server never answers', async () => {
+    const h = harness(Number.POSITIVE_INFINITY)
+
+    expect(await waitForAgentServer(h.opts)).toBe(false)
+  })
+
+  it('stops probing once the deadline passes', async () => {
+    const h = harness(Number.POSITIVE_INFINITY)
+    await waitForAgentServer(h.opts)
+
+    expect(h.elapsed()).toBeLessThanOrEqual(60_000)
+    expect(h.calls()).toBeLessThanOrEqual(62)
+  })
+
+  // Connection refused is the expected state early on, so a probe that throws
+  // has to read as not reachable rather than end the wait.
+  it('treats a throwing probe as not reachable and keeps waiting', async () => {
+    let calls = 0
+    let clock = 0
+
+    const result = await waitForAgentServer({
+      isHealthy: async () => {
+        calls += 1
+        if (calls < 3) throw new Error('connection refused')
+        return true
+      },
+      now: () => clock,
+      sleep: async (ms) => {
+        clock += ms
+      },
+      timeoutMs: 60_000,
+      intervalMs: 1_000,
+    })
+
+    expect(result).toBe(true)
+    expect(calls).toBe(3)
+    expect(clock).toBe(2_000)
+  })
+})

packages/browseros-agent/apps/app/modules/local-first-migration/wait-for-agent-server.ts

@@ -0,0 +1,67 @@
+import { getHealthCheckUrl } from '@/lib/browseros/helpers'
+
+/**
+ * Long enough to cover a cold start where the server is booting alongside the
+ * browser and has migrations of its own to apply, short enough that a genuinely
+ * absent server does not keep a background task alive all session.
+ */
+export const SERVER_WAIT_TIMEOUT_MS = 60_000
+export const SERVER_WAIT_INTERVAL_MS = 1_000
+
+export interface WaitForAgentServerOptions {
+  isHealthy?: () => Promise<boolean>
+  timeoutMs?: number
+  intervalMs?: number
+  now?: () => number
+  sleep?: (ms: number) => Promise<void>
+}
+
+async function defaultIsHealthy(): Promise<boolean> {
+  try {
+    const response = await fetch(await getHealthCheckUrl())
+    return response.ok
+  } catch {
+    return false
+  }
+}
+
+const defaultSleep = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+/**
+ * Waits until the local server answers, or gives up.
+ *
+ * The one-time import runs when the background starts, which is the same moment
+ * the server starts. It used to fire straight into a socket nothing was
+ * listening on yet and fail, and because a failed run leaves its marker unset
+ * it simply lost the same race on the next launch, so the imported data never
+ * appeared at all.
+ *
+ * Polling health first is what makes the import wait for its dependency rather
+ * than race it. Returning false rather than throwing keeps the caller's
+ * decision explicit: leave the markers unset and try again next start.
+ */
+export async function waitForAgentServer({
+  isHealthy = defaultIsHealthy,
+  timeoutMs = SERVER_WAIT_TIMEOUT_MS,
+  intervalMs = SERVER_WAIT_INTERVAL_MS,
+  now = Date.now,
+  sleep = defaultSleep,
+}: WaitForAgentServerOptions = {}): Promise<boolean> {
+  const deadline = now() + timeoutMs
+
+  while (true) {
+    // A probe that throws means not reachable, not a reason to abandon the
+    // wait. The default one already swallows fetch errors; catching here means
+    // any probe behaves the same way.
+    let healthy = false
+    try {
+      healthy = await isHealthy()
+    } catch {
+      healthy = false
+    }
+    if (healthy) return true
+    if (now() >= deadline) return false
+    await sleep(intervalMs)
+  }
+}