A bridge browser launch that cannot begin is reported, not a daemon crash (#1332) (#1723)

Author: suleimansh

packages/framework/dashboard/components/BridgeBrowserSettings.SPEC.md

@@ -12,7 +12,7 @@ The settings line for the bridge browser: where the daemon's own browser stands,
 - **A launch names its step** - so a minutes-long download does not read as a hang.
 - **A running browser can be shown and hidden** - shown for the sign-in, hidden again after; the button offered is the one that applies.
 - **The sign-in is asked for by name** - when the browser's Driver tab reports claude.ai's sign-in page, the line says to show the window and sign in once.
-- **A stopped browser says why, and offers a restart** - the reason the daemon recorded, and a Restart button.
+- **A browser that is not running says why, and offers a restart** - the reason the daemon recorded — an exit, a failed launch step, or a launch that could not begin — and a Restart button.
 
 ## Business logic
 
@@ -56,15 +56,15 @@ The bridge browser is running but signed out, so nothing it does reaches a sessi
 
 When the daemon reports the browser running and its claude.ai tab on the sign-in page, the line says so and to show the window, sign in once, then hide it again; the show button is worded for the sign-in. Once the tab is on any other page, the prompt is gone. The daemon reads that page from its own browser, so the user's own Chrome reporting to the bridge at the same time cannot mask it.
 
-### A stopped browser says why, and offers a restart
+### A browser that is not running says why, and offers a restart
 
 #### User story
 
 See `## User story`: the browser was quit, or could not start.
 
 #### Business logic
 
-When the daemon reports the browser as stopped, the line quotes the reason — the exit signal, or the launch step that failed — and offers a Restart, which asks the daemon to launch it again.
+When the daemon reports the browser as stopped, the line says it is not running and quotes the reason — the exit signal, the launch step that failed, or why the launch could not begin (the bridge token the daemon reads at start-up is missing, so a restart is needed) — and offers a Restart, which asks the daemon to launch it again.
 
 ## Before modifying/creating SPEC.md files
 

packages/framework/dashboard/components/BridgeBrowserSettings.test.SPEC.md

@@ -3,7 +3,7 @@ What the bridge browser settings line's tests cover, against faked daemon reads
 - **A launch under way** - the line quotes the daemon's current step, download percentage included.
 - **The sign-in page** - a running, minimized browser whose Driver tab reported claude.ai's sign-in page gets the sign-in prompt and a show button worded for it; pressing it asks the daemon to show the window.
 - **A shown window** - offers to hide it, asking the daemon to; a Driver tab on any other page gets no sign-in prompt.
-- **A stopped browser** - the reason is quoted and Restart asks the daemon to launch again.
+- **A browser that is not running** - the reason is quoted and Restart asks the daemon to launch again.
 - **Switched off** - nothing is rendered and nothing is read.
 
 ## Before modifying/creating SPEC.md files

packages/framework/dashboard/components/BridgeBrowserSettings.test.tsx

@@ -43,7 +43,7 @@ describe('BridgeBrowserSettings (#1332)', () => {
   test('a browser that stopped says why and offers a restart, because quitting it was an act', async () => {
     onBridgeBrowser.mockResolvedValue({ state: 'stopped', detail: 'Chrome exited on SIGTERM' })
     render(<BridgeBrowserSettings enabled />)
-    const line = await screen.findByText(/The bridge browser stopped/)
+    const line = await screen.findByText(/The bridge browser is not running/)
     expect(line.textContent).toContain('Chrome exited on SIGTERM')
     fireEvent.click(screen.getByText('Restart'))
     expect(sendBridgeBrowser).toHaveBeenCalledWith('restart')

packages/framework/dashboard/components/BridgeBrowserSettings.tsx

@@ -48,7 +48,7 @@ export function BridgeBrowserSettings({ enabled }: { enabled: boolean }) {
       {status.state === 'starting' && <p className="text-muted-foreground">Starting the bridge browser: {status.detail}.</p>}
       {status.state === 'stopped' && (
         <p className="text-danger">
-          The bridge browser stopped: {status.detail}.{' '}
+          The bridge browser is not running: {status.detail}.{' '}
           <Button variant="outline" size="sm" onClick={() => act('restart')}>
             Restart
           </Button>

packages/framework/src/bridge-browser.SPEC.md

@@ -32,7 +32,7 @@ See `## User story`: cloud sessions are served whether or not the user's Chrome
 
 #### Business logic
 
-The daemon keeps at most one bridge browser. It launches it when the bridge browser preference is on and the dashboard is listening — the extension must be told the daemon's address — and only while the browser bridge itself is on, since without the bridge token there is nothing to hand the extension; with the bridge off, the launch fails saying to turn the bridge on and restart the dashboard. Switching the preference on launches the browser at once; switching it off closes it; stopping the daemon closes it. Asking for a launch while one is under way or a browser is running does nothing more. A stop that lands while a launch is under way closes the browser that launch then hands over, so a browser is never left running unowned.
+The daemon keeps at most one bridge browser. It launches it when the bridge browser preference is on and the dashboard is listening — the extension must be told the daemon's address — and only while the browser bridge itself is on, since without the bridge token there is nothing to hand the extension; the bridge token is read when the daemon starts, so a launch asked for without one fails saying what to do — restart the dashboard when the bridge was switched on after it started, turn the bridge on first when it is off. A launch that fails before it begins is reported exactly like one that fails on the way: as stopped, with the reason, never as an error that escapes the daemon. Switching the preference on launches the browser at once; switching it off closes it; stopping the daemon closes it. Asking for a launch while one is under way or a browser is running does nothing more. A stop that lands while a launch is under way closes the browser that launch then hands over, so a browser is never left running unowned.
 
 The dashboard reads where the browser stands: off; starting, with the step it is on; running, whether its window is shown, and whether its claude.ai tab is on the sign-in page (or the sign-out step that leads there) — read from the browser itself, not from the bridge, whose last report may be the user's own Chrome's; or stopped, with the reason. It can ask for the window to be shown or hidden, or for a restart (a stop, then a launch).
 

packages/framework/src/bridge-browser.test.SPEC.md

@@ -12,7 +12,7 @@ What the bridge browser's tests cover. Every launch runs against a fake Chrome (
 - **A failed set-up step** - the browser is asked to close and killed when it does not, and the launch fails naming the step.
 - **A worker that refuses the token** - fails the launch quoting the worker's answer.
 - **An exit on its own** - reported once with the signal; an exit the daemon's own close caused is not reported, and a browser already gone is not killed again.
-- **The owner** - reports the launch's step, then running (and whether shown), then stopped with the reason when the browser exits; show and hide do nothing once it is gone. A failed launch is stopped with the reason and a later start tries again. A stop during a launch closes the browser the launch hands over. Repeated starts are one launch; restart is a stop then a start.
+- **The owner** - reports the launch's step, then running (and whether shown), then stopped with the reason when the browser exits; show and hide do nothing once it is gone. A failed launch is stopped with the reason and a later start tries again — including a launch that fails before it begins, when the launcher throws outright. A stop during a launch closes the browser the launch hands over. Repeated starts are one launch; restart is a stop then a start.
 
 ## Before modifying/creating SPEC.md files
 

packages/framework/src/bridge-browser.test.ts

@@ -309,6 +309,19 @@ test('a failed launch is stopped with the reason; a second start tries again', a
   assert.equal((await owner.status()).state, 'running')
 })
 
+test('a launcher that throws before launching is a failed launch with the reason, not a crash (#1332)', async () => {
+  const lines: string[] = []
+  const owner = bridgeBrowserOwner(
+    () => {
+      throw new Error('turn the browser bridge on, then restart the dashboard')
+    },
+    line => lines.push(line),
+  )
+  await owner.start()
+  assert.deepEqual(await owner.status(), { state: 'stopped', detail: 'turn the browser bridge on, then restart the dashboard' })
+  assert.ok(lines.some(line => line.includes('could not start')))
+})
+
 test('a stop during a launch closes the browser the launch then hands over', async () => {
   const launch = controlledLaunch()
   const owner = bridgeBrowserOwner(launch.launch)

packages/framework/src/bridge-browser.ts

@@ -524,9 +524,18 @@ export function bridgeBrowserOwner(launch: BridgeBrowserLauncher, log: (line: st
     if (browser || launching) return launching
     const mine = ++generation
     current = { state: 'starting', detail: 'preparing' }
-    launching = launch(detail => {
-      if (generation === mine) current = { state: 'starting', detail }
-    })
+    // A launcher that throws before it has anything to await — the bridge token it needs does not
+    // exist — is a launch that failed, and goes the same way as one that failed later. Left as a
+    // plain call, that throw would escape `start()` as a rejection nobody handles, and an
+    // unhandled rejection ends the daemon process (#1332). The executor runs at once, so the
+    // launcher is still called synchronously and its first step is readable right away.
+    launching = new Promise<BridgeBrowser>(resolve =>
+      resolve(
+        launch(detail => {
+          if (generation === mine) current = { state: 'starting', detail }
+        }),
+      ),
+    )
       .then(async launched => {
         if (generation !== mine) {
           await launched.close()

packages/framework/src/daemon.ts

@@ -192,8 +192,17 @@ export async function runDaemon(cwd: string, opts: RunDaemonOptions = {}): Promi
   // so a web run no longer needs the user's Chrome open. Created here, launched only once the
   // dashboard listens (the extension is told the daemon's address) and the preference says so.
   // It needs the bridge: without the token there is nothing to hand the extension.
-  const bridgeBrowser = bridgeBrowserOwner(report => {
-    if (!bridgeToken || !daemonUrl) throw new Error('turn the browser bridge on and restart the dashboard first')
+  const bridgeBrowser = bridgeBrowserOwner(async report => {
+    if (!bridgeToken || !daemonUrl) {
+      // The token is minted at boot, from the bridge preference as it stood then (above). A bridge
+      // switched on since is a restart away; a bridge that is off wants switching on first.
+      const bridgeOnNow = (await readPreferences(undefined, env).catch((): Preferences => ({}))).bridge === true
+      throw new Error(
+        bridgeOnNow
+          ? 'the browser bridge was switched on after the dashboard started — restart the dashboard, and the browser launches on its own'
+          : 'turn the browser bridge on, then restart the dashboard',
+      )
+    }
     return (opts.bridgeBrowser ?? (o => startBridgeBrowser(o)))({ daemonUrl, token: bridgeToken, dir: bridgeBrowserDir(env), report })
   }, console.log)
   // Assigned below, read from the credentials store's `onChange` (#1095): the dashboard mount has