local-operator-ui 0.34.32 → 0.34.34

package/out/main/index.js

@@ -4618,6 +4618,55 @@ const serverChannelVerdict = ({
     return { status: "restart-required", state: "restart-required" };
   return { status: "current", state: "current" };
 };
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const isInstallerWheel = (entry, version, platform) => {
+  if (!entry || typeof entry !== "object") return false;
+  const file = entry;
+  if (file.packagetype !== "bdist_wheel" || file.yanked) return false;
+  if (typeof file.url !== "string") return false;
+  let url;
+  try {
+    url = new URL(file.url);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "https:" || url.hostname !== "files.pythonhosted.org")
+    return false;
+  const digests = file.digests;
+  const sha256 = digests && typeof digests === "object" ? digests.sha256 : null;
+  if (typeof sha256 !== "string" || !SHA256_HEX.test(sha256)) return false;
+  if (typeof file.filename !== "string") return false;
+  if (!file.filename.startsWith(`local_operator-${version}-`)) return false;
+  return platform === "darwin" ? file.filename.endsWith("-py3-none-macosx_11_0_universal2.whl") : file.filename.endsWith("-py3-none-any.whl");
+};
+const pypiReleaseReading = (payload, platform) => {
+  const unreadable = {
+    namedVersion: null,
+    readyVersion: null
+  };
+  if (!payload || typeof payload !== "object") return unreadable;
+  const info = payload.info;
+  if (!info || typeof info !== "object") return unreadable;
+  const version = info.version;
+  if (typeof version !== "string" || !version.trim()) return unreadable;
+  const trimmed = version.trim();
+  const downloadable = (files) => Array.isArray(files) && files.some((entry) => isInstallerWheel(entry, trimmed, platform));
+  let ready = downloadable(payload.urls);
+  if (!ready) {
+    const releases = payload.releases;
+    if (releases && typeof releases === "object") {
+      ready = downloadable(releases[trimmed]);
+    }
+  }
+  return { namedVersion: trimmed, readyVersion: ready ? trimmed : null };
+};
+const readPypiReleaseBody = (body, platform) => {
+  try {
+    return pypiReleaseReading(JSON.parse(body), platform);
+  } catch {
+    return { namedVersion: null, readyVersion: null };
+  }
+};
 const updateCheckVerdict = (channels) => ({
   app: channels.app,
   server: channels.server,
@@ -8043,6 +8092,21 @@ async function withUserShellPath(env, userShellPath2) {
   if (!path2) return { ...env };
   return { ...env, PATH: mergeShellPath(path2, env.PATH) };
 }
+const AGENT_SHELL_ENV = "LOCAL_OPERATOR_AGENT_SHELL";
+const MAY_DELEGATE_ENV = "LOCAL_OPERATOR_AGENT_MAY_DELEGATE";
+const ALLOW_NESTED_SESSION_ENV = "LOCAL_OPERATOR_ALLOW_NESTED_SESSION";
+const AGENT_SHELL_MARKERS = [
+  AGENT_SHELL_ENV,
+  MAY_DELEGATE_ENV,
+  ALLOW_NESTED_SESSION_ENV
+];
+function withoutAgentShellMarker(env) {
+  const stripped = { ...env };
+  for (const name of AGENT_SHELL_MARKERS) {
+    delete stripped[name];
+  }
+  return stripped;
+}
 const launchEnv = {
   ...process.env
 };
@@ -10540,7 +10604,7 @@ class BackendServiceManager {
    * operator (see the comment on that entry, and `./notification-launch`).
    */
   backendSpawnEnv() {
-    return {
+    return withoutAgentShellMarker({
       ...withPythonBytecodeCache(this.shellEnv, this.appDataPath),
       // Managed starts rotate the token; set after the spread so the spawn
       // can never inherit a stale one from the shell environment. `start()`
@@ -10563,7 +10627,7 @@ class BackendServiceManager {
        * unstated key is left alone.
        */
       ...resolveNotificationLaunch(launchEnv)
-    };
+    });
   }
   /**
    * Load environment variables from macOS shell configuration files
@@ -14800,12 +14864,14 @@ class BrowserStateWriter {
     this.onError = options.onError ?? (() => {
     });
     this.appVersion = options.appVersion;
+    this.instanceId = options.instanceId;
   }
   now;
   onError;
   timer = null;
   written = false;
   appVersion;
+  instanceId;
   /** Publish the record and start the heartbeat. The heartbeat is the
    * difference between "the app is running and can open a tab on demand" and a
    * record that names a process that died without cleaning up. */
@@ -14837,6 +14903,7 @@ class BrowserStateWriter {
         proto: PROTO_VERSION,
         host: "ui",
         app_version: this.appVersion,
+        ...this.instanceId && { instance_id: this.instanceId },
         profile_dir: facts.profileDir,
         // Advertised from the ONE list the `/health` route also reads (§6.3), so the
         // record a session reads and the probe Python acquits a stale record with
@@ -24117,6 +24184,57 @@ function restrictMode(path2, log2) {
     );
   }
 }
+class StartupRollback {
+  owners = [];
+  add(cleanup) {
+    this.owners.push(cleanup);
+  }
+  commit() {
+    this.owners = [];
+  }
+  async run(log2) {
+    for (const cleanup of this.owners.splice(0).reverse()) {
+      try {
+        await cleanup();
+      } catch (error) {
+        log2(`[browser] startup cleanup failed: ${String(error)}`);
+      }
+    }
+  }
+}
+const MAX_START_ATTEMPTS = 3;
+async function startWithRetries(options) {
+  let failure = new Error("The browser window closed before startup.");
+  for (let attempt = 1; attempt <= MAX_START_ATTEMPTS; attempt += 1) {
+    if (options.cancelled()) break;
+    options.publish({
+      status: attempt === 1 ? "starting" : "retrying",
+      attempt,
+      maxAttempts: MAX_START_ATTEMPTS,
+      message: null,
+      canRetry: false
+    });
+    try {
+      return await options.start();
+    } catch (error) {
+      failure = error;
+      options.log(
+        `[browser] startup attempt ${attempt}/${MAX_START_ATTEMPTS} failed: ${String(error)}`
+      );
+    }
+  }
+  options.publish({
+    status: "unavailable",
+    attempt: MAX_START_ATTEMPTS,
+    maxAttempts: MAX_START_ATTEMPTS,
+    message: "The browser could not start. Your saved tabs and site approvals are kept; sessions you were signed into may need signing in again.",
+    // The window is still open and no host is running once the sequence
+    // exhausts, so the renderer may offer a retry. `startBrowserHost` is
+    // idempotent on re-registration, which is what makes the control safe.
+    canRetry: true
+  });
+  throw failure;
+}
 const BROWSER_IPC_CHANNELS = [
   "browser-state",
   "browser-new-tab",
@@ -24138,19 +24256,53 @@ const BROWSER_IPC_CHANNELS = [
   "browser-clear-data",
   "browser-webauthn-respond",
   "browser-webauthn-pending",
-  "browser-reveal-downloads"
+  "browser-reveal-downloads",
+  /** The user's own recovery click on the `unavailable` state (round 1, D1a).
+   * Named here so the namespace stays the one place that lists its channels. */
+  "browser-retry"
 ];
 function registerBrowserIpc(options) {
-  function authorize(event) {
+  function authorizeSender(event) {
     const owner = options.window();
     if (!owner || owner.isDestroyed() || event.sender !== owner.webContents || event.senderFrame !== owner.webContents.mainFrame || !trustedDesktopFrame(event.senderFrame.url, options.expectedUrl)) {
       throw new Error("This window cannot use the browser controls.");
     }
+  }
+  function authorize(event) {
+    authorizeSender(event);
     const host = options.host();
-    if (!host) throw new Error("The browser host is not running.");
+    if (!host)
+      throw new Error("browser_unavailable: The browser is not ready.");
     return host;
   }
-  electron.ipcMain.handle("browser-state", (event) => authorize(event).chromeState());
+  electron.ipcMain.handle("browser-state", (event) => {
+    authorizeSender(event);
+    const host = options.host();
+    const availability = options.availability?.();
+    if (host)
+      return { ...host.chromeState(), ...availability && { availability } };
+    return {
+      tabs: [],
+      activeTabId: null,
+      url: "",
+      title: "",
+      loading: false,
+      canGoBack: false,
+      canGoForward: false,
+      pendingConsent: [],
+      approvals: [],
+      navFailure: null,
+      availability: availability ?? {
+        status: "unavailable",
+        attempt: 0,
+        maxAttempts: MAX_START_ATTEMPTS,
+        message: "The browser is not running.",
+        // No host invokes this fallback (it is the pre-start projection), and
+        // there is nothing to retry before a start was asked for.
+        canRetry: false
+      }
+    };
+  });
   electron.ipcMain.handle("browser-new-tab", async (event, sessionId2) => {
     const host = authorize(event);
     return host.newTab(optionalConversationOrThrow(sessionId2));
@@ -24276,6 +24428,13 @@ function registerBrowserIpc(options) {
       );
     return { opened: message === "", message };
   });
+  electron.ipcMain.handle("browser-retry", async (event) => {
+    authorizeSender(event);
+    if (!options.retry)
+      throw new Error("browser_unavailable: Retry is not available.");
+    await options.retry();
+    return { retried: true };
+  });
 }
 function unregisterBrowserIpc() {
   for (const channel of BROWSER_IPC_CHANNELS) electron.ipcMain.removeHandler(channel);
@@ -24698,7 +24857,7 @@ function installBrowserSessionHandlers(browserSession, hooks = {}) {
       return false;
     }
   );
-  browserSession.on("will-download", (event, item, webContents) => {
+  const onDownload = (event, item, webContents) => {
     const webContentsId = webContents?.id ?? -1;
     const decision = hooks.onDownload?.(item, webContentsId) ?? {
       cancel: true,
@@ -24718,7 +24877,11 @@ function installBrowserSessionHandlers(browserSession, hooks = {}) {
       );
     }
     hooks.onDownloadDecided?.(outcome);
-  });
+  };
+  browserSession.on("will-download", onDownload);
+  return () => {
+    browserSession.removeListener("will-download", onDownload);
+  };
 }
 async function clearBrowsingData(browserSession, what) {
   browserSession.flushStorageData();
@@ -24769,6 +24932,7 @@ function flushBrowserStorage(browserSession) {
 const RPC_PATH = "/rpc";
 const HEALTH_PATH = "/health";
 const KEY_HEADER = "x-bridge-key";
+const INSTANCE_HEADER = "x-ui-browser-instance";
 const MAX_BODY_BYTES = 1 << 20;
 const LOOPBACK_HOST = "127.0.0.1";
 function send(res, status2, body, contentType = "application/json") {
@@ -24895,6 +25059,7 @@ async function handle(req, res, options) {
         host: "ui",
         proto: PROTO_VERSION,
         pid: process.pid,
+        ...options.instanceId && { instance_id: options.instanceId },
         // Additive: an older reader requires `host` and `pid` and ignores the
         // rest, and a newer one learns whether the console is up without a
         // second probe (design 10.1). `false` when nobody reported a
@@ -24921,6 +25086,11 @@ async function handle(req, res, options) {
       send(res, 401, { detail: "unauthorized" });
       return;
     }
+    const expectedInstance = req.headers[INSTANCE_HEADER];
+    if (expectedInstance !== void 0 && expectedInstance !== options.instanceId) {
+      send(res, 409, { detail: "host instance changed" });
+      return;
+    }
     let raw;
     try {
       raw = JSON.parse(await readBody(req));
@@ -26040,13 +26210,28 @@ function refusesNavigation(rawUrl) {
 let activeHost = null;
 let stopping = null;
 function browserHostStopPending() {
-  return activeHost !== null || stopping !== null;
+  return activeHost !== null || stopping !== null || starting !== null;
 }
 async function stopBrowserHost() {
   if (stopping) return stopping;
+  if (starting) {
+    cancelStartup = true;
+    stopping = starting.catch(() => null).then(async () => {
+      const current = activeHost;
+      activeHost = null;
+      if (current) await current.stop();
+      else unregisterBrowserIpc();
+    }).finally(() => {
+      stopping = null;
+    });
+    return stopping;
+  }
   const handle2 = activeHost;
   activeHost = null;
-  if (!handle2) return;
+  if (!handle2) {
+    unregisterBrowserIpc();
+    return;
+  }
   stopping = handle2.stop().finally(() => {
     stopping = null;
   });
@@ -26056,524 +26241,650 @@ function browserHostEnabled(env = process.env) {
   const flag = env.LOCAL_OPERATOR_UI_BROWSER_HOST?.trim().toLowerCase();
   return !(flag === "0" || flag === "false" || flag === "off");
 }
-async function startBrowserHost(options) {
-  const { log: log2 } = options;
-  const browserSession = resolveBrowserSession();
-  let registryForDownloads = null;
-  const downloads = new DownloadArmer({
-    tabForWebContents: (webContentsId) => registryForDownloads?.byWebContents(webContentsId)?.tabId ?? null,
-    // WHO OWNED THE TAB, recorded on the decision (review round 2, U10). Read from
-    // the registry at the moment the note is written, because the row may render it
-    // after the tab is closed — and "· on another tab" about a tab that no longer
-    // exists is a marker pointing at nothing. `null` when the lookup cannot answer
-    // (a tab already gone), which the row renders the old way rather than guessing.
-    ownerKindFor: (tabId) => registryForDownloads?.get(tabId)?.owner ?? null,
-    log: log2,
-    onActivity: () => {
-      if (options.window.isDestroyed()) return;
-      options.window.webContents.send("browser-state-changed");
-    }
-  });
-  installBrowserSessionHandlers(browserSession, {
-    onPermissionRequested: (details) => {
-      log2(
-        `[browser] denied a ${details.permission} permission request from ${details.origin || "(unknown origin)"}`
-      );
-    },
-    onDownload: (item, webContentsId) => downloads.decide(item, webContentsId),
-    onDownloadDecided: (outcome) => {
-      if (outcome.savePath) {
-        log2(
-          `[browser] saved a download from ${outcome.url} to ${outcome.savePath}`
-        );
-      }
-    },
-    log: log2
-  });
-  configurePslRules(PSL_RULES);
-  await installWebauthn({ log: log2 });
-  const describeSource = (frame) => {
-    if (!frame || typeof frame !== "object") {
-      return { tabId: null, pageTitle: null };
-    }
-    const contents = electron.webContents.fromFrame(frame);
-    const record = contents === void 0 ? void 0 : registry.byWebContentsId(contents.id);
-    if (!record) return { tabId: null, pageTitle: null };
-    const title = record.view.webContents.isDestroyed() ? "" : record.view.webContents.getTitle();
-    return { tabId: record.tabId, pageTitle: title || null };
-  };
-  const webauthn = new WebauthnChooser({
-    notify: (request) => {
-      if (options.window.isDestroyed()) return;
-      options.window.webContents.send("browser-webauthn-request", request);
-    },
-    /*
-     * AND THE OTHER DIRECTION: every settle is pushed, not only every arrival.
-     *
-     * Without this the renderer cannot tell a live request from one main has
-     * already cancelled, so a chooser whose request expired while the user was
-     * away stays on screen offering rows that can no longer do anything (design
-     * round 1, D2) — and the click is then discarded silently. The outcome travels
-     * with the push because the two cases differ for the user: their own answer is
-     * already off the screen, an expiry has to be explained.
-     */
-    onSettled: (requestId2, outcome) => {
-      if (options.window.isDestroyed()) return;
-      options.window.webContents.send("browser-webauthn-settled", {
-        requestId: requestId2,
-        outcome
-      });
-    },
-    describeSource,
-    log: log2
-  });
-  const detachWebauthn = attachWebauthnChooser(browserSession, webauthn, log2);
-  const cookieJar = createHiddenCookieJarTarget(
-    new electron.WebContentsView({
-      webPreferences: { ...HIDDEN_COOKIE_JAR_WEB_PREFERENCES }
-    })
-  );
-  const sessionCookies = new SessionCookieVault({
-    jar: cookieJar.jar,
-    cipher: browserProfileCipher(),
-    ...sessionCookiePaths(options.userDataDir),
-    flushStore: () => browserSession.cookies.flushStore(),
-    clearSessionData: (what) => clearBrowsingData(browserSession, what),
-    log: log2
-  });
-  let restoreReport = null;
-  try {
-    restoreReport = await sessionCookies.restore();
-  } catch (error) {
-    log2(`[browser] session cookies: the restore failed (${String(error)})`);
-  }
-  const cdp = new CdpPool({ log: log2 });
-  const views = /* @__PURE__ */ new Map();
-  let stateWriter = null;
-  const sessionStore = new BrowserSessionStore({
-    dir: path$1.join(options.userDataDir, "browser"),
-    log: log2
-  });
-  const consentNotifier = new ConsentNotifier({
-    show: options.windowShow,
-    /*
-     * The click's own rule lives in `consentClickHandler` (see it: the delivered
-     * payload, the order, and the raise are all asserted there), and this is the
-     * wiring that gives it the real window and the real plan. `windowShow` is the
-     * plan the click comes forward under — this module still never decides whether a
-     * window comes forward (design 11.4), it hands the plan to `window-raise.ts`.
-     */
-    onAttention: consentClickHandler({
-      /*
-       * THE WINDOW IS ASKED FOR, NOT CAPTURED, and the difference is the U2 fix:
-       * this host is stopped the moment its window closes (`src/main/index.ts`'s
-       * `closed` hook), but a banner already raised is still in Notification
-       * Center and its click still lands here. A captured window would be a
-       * destroyed one by then, and reading it throws.
-       */
-      window: () => options.window,
-      show: options.windowShow,
-      report: options.reportRaise,
-      reopen: options.reopenConsent
-    }),
-    log: log2
-  });
-  const captureSession = () => {
-    sessionStore.record(
-      captureTabs(
-        registry.list(),
-        registry.activeTab?.tabId ?? null,
-        host.failedTabIds()
-      )
-    );
-  };
-  const notifyChanged = () => {
-    stateWriter?.publishNow();
-    options.window.webContents.send("browser-state-changed");
-    captureSession();
-  };
-  const registry = new TabRegistry(
-    (_createOptions, tabId) => {
-      const view = buildView(options.window);
-      views.set(tabId, view);
-      wireView(view, tabId);
-      return view;
-    },
-    releaseTab,
-    notifyChanged
-  );
-  registryForDownloads = registry;
-  function releaseTab(tabId, webContentsId) {
-    const view = views.get(tabId);
-    views.delete(tabId);
-    downloads.forget(tabId);
-    void cdp.detach(webContentsId).finally(() => {
-      releaseView(options.window, view);
+const hostInstanceId = node_crypto.randomUUID();
+let starting = null;
+let startingWindow = null;
+let cancelStartup = false;
+function startBrowserHost(options) {
+  if (starting) {
+    if (startingWindow === options.window) return starting;
+    return starting.catch(() => null).then(async () => {
+      await stopBrowserHost();
+      return startBrowserHost(options);
     });
   }
-  const ownership = new OwnershipLedger({
-    mayAdopt: (token, requester) => {
-      const record = registry.requireSurface(token);
-      return record.handedTo === requester.slice("session:".length) && !record.allocationId;
-    },
-    closeTab: async (token) => {
-      try {
-        const record = registry.requireSurface(token);
-        approvals.forgetDocument(token);
-        registry.destroy(record.tabId);
-      } catch {
-      }
-      return true;
-    },
-    isLive: (token) => {
-      try {
-        registry.requireSurface(token);
-        return true;
-      } catch {
-        return false;
-      }
-    }
-  });
-  const approvals = new ApprovalStore({
-    dir: path$1.join(options.userDataDir, "browser"),
-    onChanged: () => {
-      options.window.webContents.send("browser-consent-changed");
-      consentNotifier.announce(approvals.pendingEntries());
-    },
-    log: log2
-  });
-  const profileDir = browserStoragePath(browserSession) ?? "";
-  const facts = {
-    proto: 1,
-    appVersion: options.appVersion,
-    profileDir,
-    profilePersistent: browserSession.isPersistent(),
-    userAgent: browserUserAgent(),
-    domainScope: domainScopeAvailable()
+  if (stopping) return stopping.then(() => startBrowserHost(options));
+  if (activeHost) return Promise.resolve(activeHost);
+  cancelStartup = false;
+  startingWindow = options.window;
+  let availability = {
+    status: "starting",
+    attempt: 1,
+    maxAttempts: MAX_START_ATTEMPTS,
+    message: null,
+    canRetry: false
   };
-  const host = new BrowserHost({
-    registry,
-    cdp,
-    approvals,
-    ownership,
-    downloads,
-    log: log2,
-    onChanged: notifyChanged,
-    facts: () => facts,
-    forgetSiteData: (origin) => clearOriginData(browserSession, origin)
-  });
-  const recorded = readSession(sessionStore.filePath, log2);
-  host.restoreTabs(recorded);
-  if (recorded.length) {
-    log2(
-      `[browser] restored ${recorded.length} tab(s) from ${SESSION_FILENAME}; every restored tab is user-owned and holds no handle (design 7.3)`
-    );
-  }
-  const consoleStartup = await startConsoleHost({
-    window: options.window,
-    expectedUrl: options.expectedUrl,
-    appVersion: options.appVersion,
-    notifier: options.notifier,
-    /*
-     * The capture view's document and preload, forwarded rather than re-derived:
-     * only the app knows where its own bundle lives, and a console host that
-     * guessed would answer a screenshot with a blank frame rather than with its
-     * own typed refusal. WITHOUT THESE TWO the host builds no capture view at all,
-     * which the live proof rig caught as `capture_unavailable` on a surface with
-     * no displayed pane — the exact shape of a seam that is wired in tests and
-     * forgotten in the one call site that matters.
-     */
-    consoleCaptureUrl: options.consoleCaptureUrl,
-    preloadPath: options.preloadPath,
-    userShellPath: options.userShellPath,
-    log: log2
-  });
-  const sessionKey = mintSessionKey();
-  const server = await startRpcServer({
-    key: sessionKey,
-    dispatch: async (method, params, requestId2) => {
-      if (!isConsoleDispatchMethod(method)) {
-        return host.dispatch(method, params, requestId2);
-      }
-      if (!consoleStartup.ok) {
-        throw new ConsoleError(
-          "console_unavailable",
-          `this app's console is not available (${consoleStartup.reason}): ${consoleStartup.detail}`,
-          { reason: consoleStartup.reason }
-        );
-      }
-      return consoleStartup.dispatch(method, params);
-    },
-    log: log2,
-    capabilities: () => ({ console: consoleStartup.ok })
-  });
-  stateWriter = new BrowserStateWriter(
-    stateFilePath(),
-    () => {
-      const consoleCounts = consoleStartup.ok ? consoleStartup.counts() : { total: 0, agent: 0 };
-      return {
-        tabs: registry.count(),
-        agentTabs: registry.agentTabCount(),
-        profileDir,
-        console: consoleStartup.ok,
-        consoleSurfaces: consoleCounts.total,
-        consoleAgentSurfaces: consoleCounts.agent
-      };
-    },
-    {
-      appVersion: options.appVersion,
-      onError: (error) => log2(`[browser] state file: ${String(error)}`)
-    }
-  );
-  stateWriter.start(server.port, sessionKey);
+  const bindings = {};
+  const notify = () => {
+    if (!options.window.isDestroyed())
+      options.window.webContents.send("browser-state-changed");
+  };
+  unregisterBrowserIpc();
   registerBrowserIpc({
     window: () => options.window,
     expectedUrl: options.expectedUrl,
-    host: () => host,
-    webauthn: () => webauthn,
-    clearData: (what) => sessionCookies.clearBrowsingData(what),
-    // THE REVEAL TAKES NO PATH FROM THE RENDERER (§16.4): it opens the directory the
-    // host is actually writing into, so the one place a page-derived string could
-    // have become a path stays out of the IPC surface as well. `shell.openPath`
-    // answers "" on success and a message on failure, which is returned rather than
-    // thrown: a reveal that fails is a Finder problem, not a fault in the agent's
-    // download.
+    host: () => bindings.host?.() ?? null,
+    webauthn: () => bindings.webauthn?.() ?? null,
+    availability: () => availability,
+    clearData: async (what) => {
+      if (!bindings.clearData)
+        throw new Error("browser_unavailable: The browser is not ready.");
+      return bindings.clearData(what);
+    },
     revealDownloads: async () => {
-      const dir = downloads.downloadDir();
-      if (!dir) return "no download directory yet";
-      return electron.shell.openPath(dir);
+      if (!bindings.revealDownloads)
+        throw new Error("browser_unavailable: The browser is not ready.");
+      return bindings.revealDownloads();
     },
-    log: log2
+    // The recovery click on the `unavailable` state (round 1, D1a). It restarts
+    // THIS module's host for the same window — the same call `createWindow`
+    // makes — so the retry travels the one lifecycle path rather than a second,
+    // parallel start. A doubled click needs no guard of its own:
+    // `startBrowserHost` is already single-flight (a second call for the same
+    // window returns the in-flight `starting` promise), which QA's concurrent
+    // probe confirmed — three simultaneous retries produced ONE startup
+    // sequence. Adding a local guard beside that would be a second mechanism
+    // for a rule the module already owns (round 2, Q-R2-2).
+    retry: async () => {
+      await startBrowserHost(options).catch(() => {
+      });
+    },
+    log: options.log
   });
-  log2(
-    `[browser] host on ${server.address}:${server.port} (proto ${facts.proto}), profile ${profileDir || "(in-memory)"}, agent tabs ${registry.agentTabCount()}/${8}, console ${consoleStartup.ok ? `on (${consoleStartup.counts().total} surface(s))` : `off (${consoleStartup.reason})`}`
-  );
-  const handle2 = {
-    host,
-    port: server.port,
-    profileDir,
-    agentTabs: () => registry.agentTabCount(),
-    sessionCookies: () => restoreReport,
-    stop: async () => {
-      const atStop = captureTabs(
-        registry.list(),
-        registry.activeTab?.tabId ?? null,
-        host.failedTabIds()
-      );
-      const decision = sessionStore.commitStopCapture(atStop);
-      if (!decision.write) {
-        log2(
-          `[browser] not overwriting ${SESSION_FILENAME} at stop: ${decision.reason}`
-        );
-      }
-      sessionStore.flush();
-      registry.destroyAll();
-      await cdp.close();
-      await server.close();
-      await consoleStartup.stop();
-      unregisterBrowserIpc();
-      detachWebauthn();
-      webauthn.dispose();
-      stateWriter?.clear();
-      approvals.resetPending();
-      ownership.clear();
-      flushBrowserStorage(browserSession);
-      try {
-        await sessionCookies.snapshot();
-      } catch (error) {
-        log2(
-          `[browser] session cookies: the snapshot failed (${String(error)})`
-        );
-      }
-      cookieJar.dispose();
-      log2("[browser] host stopped");
+  starting = startWithRetries({
+    cancelled: () => cancelStartup || options.window.isDestroyed(),
+    publish: (next) => {
+      availability = next;
+      notify();
+    },
+    log: options.log,
+    start: async () => {
+      const handle2 = await initializeBrowserHost(options, bindings);
+      availability = {
+        ...availability,
+        status: "ready",
+        message: null,
+        canRetry: false
+      };
+      notify();
+      return handle2;
     }
+  }).finally(() => {
+    starting = null;
+    startingWindow = null;
+  });
+  return starting;
+}
+async function initializeBrowserHost(options, bindings) {
+  const { log: log2 } = options;
+  const rollback = new StartupRollback();
+  let published = false;
+  const checkpoint = () => {
+    if (cancelStartup || options.window.isDestroyed())
+      throw new Error("The browser window closed during startup.");
   };
-  activeHost = handle2;
-  return handle2;
-  function buildView(window) {
-    const view = new electron.WebContentsView({
-      webPreferences: {
-        partition: BROWSER_PARTITION,
-        contextIsolation: true,
-        nodeIntegration: false,
-        webSecurity: true,
-        allowRunningInsecureContent: false,
-        sandbox: true
-        // No `preload`: a driven page has no bridge to anything.
-      }
-    });
-    window.contentView.addChildView(view);
-    view.setBounds(BACKGROUND_VIEWPORT);
-    view.setVisible(false);
-    return view;
-  }
-  function wireView(view, tabId) {
-    const contents = view.webContents;
-    const popupChildren = /* @__PURE__ */ new Set();
-    contents.setWindowOpenHandler((details) => {
-      const decision = decidePopup(
-        { url: details.url, disposition: details.disposition },
-        { mode: options.windowShow, live: popupChildren.size }
-      );
-      if (!decision.allow) {
+  try {
+    let releaseTab = function(tabId, webContentsId) {
+      const view = views.get(tabId);
+      views.delete(tabId);
+      downloads.forget(tabId);
+      const release = cdp.detach(webContentsId).finally(() => releaseView(options.window, view));
+      releases.add(release);
+      void release.catch(() => {
+      }).finally(() => releases.delete(release));
+    }, buildView = function(window) {
+      const view = new electron.WebContentsView({
+        webPreferences: {
+          partition: BROWSER_PARTITION,
+          contextIsolation: true,
+          nodeIntegration: false,
+          webSecurity: true,
+          allowRunningInsecureContent: false,
+          sandbox: true
+          // No `preload`: a driven page has no bridge to anything.
+        }
+      });
+      window.contentView.addChildView(view);
+      view.setBounds(BACKGROUND_VIEWPORT);
+      view.setVisible(false);
+      return view;
+    }, wireView = function(view, tabId) {
+      const contents = view.webContents;
+      const popupChildren = /* @__PURE__ */ new Set();
+      contents.setWindowOpenHandler((details) => {
+        const decision = decidePopup(
+          { url: details.url, disposition: details.disposition },
+          { mode: options.windowShow, live: popupChildren.size }
+        );
+        if (!decision.allow) {
+          log2(
+            `[browser] refused a popup from a driven page: ${details.url} (${decision.reason})`
+          );
+          return { action: "deny" };
+        }
         log2(
-          `[browser] refused a popup from a driven page: ${details.url} (${decision.reason})`
+          `[browser] tab ${tabId} opened a popup: ${details.url} (disposition=${details.disposition}, presentation=${decision.presentation})`
         );
-        return { action: "deny" };
-      }
-      log2(
-        `[browser] tab ${tabId} opened a popup: ${details.url} (disposition=${details.disposition}, presentation=${decision.presentation})`
-      );
-      return {
-        action: "allow",
-        overrideBrowserWindowOptions: {
-          width: 640,
-          height: 720,
-          minWidth: 480,
-          minHeight: 560,
-          center: true,
-          frame: true,
-          autoHideMenuBar: true,
-          // Nothing shows itself: presentation happens only through
-          // `presentPopupWindow` (window-raise.ts), under the launch plan's own
-          // gate. Under `never` the window exists hidden and drivable over CDP.
-          show: false,
-          // Defence in depth beside the plan gate: a window that will never be
-          // shown must also not be focusable — the same pairing `window-mode.ts`
-          // applies to the main window in `headless`.
-          focusable: decision.presentation !== "never",
-          backgroundColor: "#FFFFFF",
-          webPreferences: {
-            /*
-             * EXPLICIT, and load-bearing (design 2.3): `partition` is NOT among the
-             * security-related prefs Electron merges from the parent, and a popup
-             * created in a different session is not RELATED to its opener —
-             * Chromium severs `window.opener`, which is the entire contract a
-             * popup-based sign-in needs. The `about:blank` case lands in this same
-             * session by prefs-copy instead of by this line.
-             */
-            partition: BROWSER_PARTITION,
-            sandbox: true,
-            contextIsolation: true,
-            nodeIntegration: false,
-            webSecurity: true,
-            allowRunningInsecureContent: false,
-            spellcheck: false,
-            navigateOnDragDrop: false,
-            // Not security-inherited either: a hidden popup must render like a
-            // shown one so a capture of it is evidence (design 2.5).
-            backgroundThrottling: options.backgroundThrottling
-            // No `preload` — a popup has no bridge to anything, like the view.
+        return {
+          action: "allow",
+          overrideBrowserWindowOptions: {
+            width: 640,
+            height: 720,
+            minWidth: 480,
+            minHeight: 560,
+            center: true,
+            frame: true,
+            autoHideMenuBar: true,
+            // Nothing shows itself: presentation happens only through
+            // `presentPopupWindow` (window-raise.ts), under the launch plan's own
+            // gate. Under `never` the window exists hidden and drivable over CDP.
+            show: false,
+            // Defence in depth beside the plan gate: a window that will never be
+            // shown must also not be focusable — the same pairing `window-mode.ts`
+            // applies to the main window in `headless`.
+            focusable: decision.presentation !== "never",
+            backgroundColor: "#FFFFFF",
+            webPreferences: {
+              /*
+               * EXPLICIT, and load-bearing (design 2.3): `partition` is NOT among the
+               * security-related prefs Electron merges from the parent, and a popup
+               * created in a different session is not RELATED to its opener —
+               * Chromium severs `window.opener`, which is the entire contract a
+               * popup-based sign-in needs. The `about:blank` case lands in this same
+               * session by prefs-copy instead of by this line.
+               */
+              partition: BROWSER_PARTITION,
+              sandbox: true,
+              contextIsolation: true,
+              nodeIntegration: false,
+              webSecurity: true,
+              allowRunningInsecureContent: false,
+              spellcheck: false,
+              navigateOnDragDrop: false,
+              // Not security-inherited either: a hidden popup must render like a
+              // shown one so a capture of it is evidence (design 2.5).
+              backgroundThrottling: options.backgroundThrottling
+              // No `preload` — a popup has no bridge to anything, like the view.
+            }
           }
+        };
+      });
+      contents.on("did-create-window", (child, details) => {
+        wirePopup(child, details, popupChildren);
+      });
+      const onWillNavigate = (event, rawUrl) => {
+        if (refusesNavigation(rawUrl)) {
+          event.preventDefault();
+          log2(`[browser] refused a navigation to ${rawUrl}`);
         }
       };
-    });
-    contents.on("did-create-window", (child, details) => {
-      wirePopup(child, details, popupChildren);
-    });
-    const onWillNavigate = (event, rawUrl) => {
-      if (refusesNavigation(rawUrl)) {
+      contents.on("will-navigate", onWillNavigate);
+      contents.on("will-redirect", onWillNavigate);
+      contents.on("before-input-event", (event, input) => {
+        const direction = paneNavigationDirection(input);
+        if (!direction) return;
+        event.preventDefault();
+        host.historyActive(direction);
+      });
+      const notifyChrome = () => {
+        options.window.webContents.send("browser-state-changed");
+      };
+      contents.on("did-start-loading", () => {
+        host.clearLoadFailure(tabId);
+        notifyChrome();
+      });
+      contents.on("did-stop-loading", notifyChrome);
+      contents.on("page-title-updated", notifyChrome);
+      contents.on(
+        "did-fail-load",
+        (_event, code, description, url, isMainFrame) => {
+          if (!isMainFrame) return;
+          if (isReportableLoadFailure(code)) {
+            host.recordLoadFailure(tabId, {
+              code,
+              description,
+              url
+            });
+          }
+          notifyChrome();
+        }
+      );
+      contents.on("will-attach-webview", (event) => {
+        event.preventDefault();
+        log2("[browser] refused a webview attachment inside a driven page");
+      });
+      contents.on("did-navigate", (_event, url) => {
+        registry.bumpEpoch(tabId);
+        host.clearLoadFailure(tabId);
+        stopLogCapture(contents.id);
+        startLogCapture(contents.id);
+        log2(`[browser] tab ${tabId} navigated to ${url}`);
+        notifyChanged();
+      });
+      contents.on("did-navigate-in-page", (_event, url, isMainFrame) => {
+        if (!isMainFrame) return;
+        registry.bumpEpoch(tabId, false);
+        log2(`[browser] tab ${tabId} navigated in page to ${url}`);
+        notifyChanged();
+      });
+      contents.on("destroyed", () => {
+        const record = registry.get(tabId);
+        if (record) {
+          const token = surfaceToken(record);
+          if (token) approvals.forgetDocument(token);
+          registry.forget(tabId);
+        }
+        host.clearLoadFailure(tabId);
+        releaseTab(tabId, contents.id);
+      });
+    }, wirePopup = function(child, details, popupChildren) {
+      popupChildren.add(child);
+      child.on("closed", () => popupChildren.delete(child));
+      const childContents = child.webContents;
+      childContents.setWindowOpenHandler((childDetails) => {
+        log2(`[browser] refused a popup from a popup: ${childDetails.url}`);
+        return { action: "deny" };
+      });
+      const onWillNavigate = (event, rawUrl) => {
+        if (refusesNavigation(rawUrl)) {
+          event.preventDefault();
+          log2(`[browser] refused a popup navigation to ${rawUrl}`);
+        }
+      };
+      childContents.on("will-navigate", onWillNavigate);
+      childContents.on("will-redirect", onWillNavigate);
+      childContents.on("will-attach-webview", (event) => {
+        event.preventDefault();
+        log2("[browser] refused a webview attachment inside a popup");
+      });
+      childContents.on("before-input-event", (event, input) => {
+        const direction = paneNavigationDirection(input);
+        if (!direction) return;
         event.preventDefault();
-        log2(`[browser] refused a navigation to ${rawUrl}`);
+        const navigation = childContents.navigationHistory;
+        if (direction === "back") navigation.goBack();
+        else navigation.goForward();
+      });
+      if (!options.backgroundThrottling) {
+        childContents.setBackgroundThrottling(false);
       }
+      presentPopupWindow(
+        child,
+        effectivePresentation(options.windowShow, details.disposition),
+        { trigger: "popup-open", report: options.reportRaise }
+      );
     };
-    contents.on("will-navigate", onWillNavigate);
-    contents.on("will-redirect", onWillNavigate);
-    contents.on("before-input-event", (event, input) => {
-      const direction = paneNavigationDirection(input);
-      if (!direction) return;
-      event.preventDefault();
-      host.historyActive(direction);
+    const browserSession = resolveBrowserSession();
+    let registryForDownloads = null;
+    const downloads = new DownloadArmer({
+      tabForWebContents: (webContentsId) => registryForDownloads?.byWebContents(webContentsId)?.tabId ?? null,
+      // WHO OWNED THE TAB, recorded on the decision (review round 2, U10). Read from
+      // the registry at the moment the note is written, because the row may render it
+      // after the tab is closed — and "· on another tab" about a tab that no longer
+      // exists is a marker pointing at nothing. `null` when the lookup cannot answer
+      // (a tab already gone), which the row renders the old way rather than guessing.
+      ownerKindFor: (tabId) => registryForDownloads?.get(tabId)?.owner ?? null,
+      log: log2,
+      onActivity: () => {
+        if (options.window.isDestroyed()) return;
+        options.window.webContents.send("browser-state-changed");
+      }
+    });
+    const detachSessionHandlers = installBrowserSessionHandlers(
+      browserSession,
+      {
+        onPermissionRequested: (details) => {
+          log2(
+            `[browser] denied a ${details.permission} permission request from ${details.origin || "(unknown origin)"}`
+          );
+        },
+        onDownload: (item, webContentsId) => downloads.decide(item, webContentsId),
+        onDownloadDecided: (outcome) => {
+          if (outcome.savePath) {
+            log2(
+              `[browser] saved a download from ${outcome.url} to ${outcome.savePath}`
+            );
+          }
+        },
+        log: log2
+      }
+    );
+    rollback.add(detachSessionHandlers);
+    configurePslRules(PSL_RULES);
+    await installWebauthn({ log: log2 });
+    checkpoint();
+    const describeSource = (frame) => {
+      if (!frame || typeof frame !== "object") {
+        return { tabId: null, pageTitle: null };
+      }
+      const contents = electron.webContents.fromFrame(frame);
+      const record = contents === void 0 ? void 0 : registry.byWebContentsId(contents.id);
+      if (!record) return { tabId: null, pageTitle: null };
+      const title = record.view.webContents.isDestroyed() ? "" : record.view.webContents.getTitle();
+      return { tabId: record.tabId, pageTitle: title || null };
+    };
+    const webauthn = new WebauthnChooser({
+      notify: (request) => {
+        if (options.window.isDestroyed()) return;
+        options.window.webContents.send("browser-webauthn-request", request);
+      },
+      /*
+       * AND THE OTHER DIRECTION: every settle is pushed, not only every arrival.
+       *
+       * Without this the renderer cannot tell a live request from one main has
+       * already cancelled, so a chooser whose request expired while the user was
+       * away stays on screen offering rows that can no longer do anything (design
+       * round 1, D2) — and the click is then discarded silently. The outcome travels
+       * with the push because the two cases differ for the user: their own answer is
+       * already off the screen, an expiry has to be explained.
+       */
+      onSettled: (requestId2, outcome) => {
+        if (options.window.isDestroyed()) return;
+        options.window.webContents.send("browser-webauthn-settled", {
+          requestId: requestId2,
+          outcome
+        });
+      },
+      describeSource,
+      log: log2
+    });
+    rollback.add(() => webauthn.dispose());
+    const detachWebauthn = attachWebauthnChooser(browserSession, webauthn, log2);
+    rollback.add(detachWebauthn);
+    const cookieJar = createHiddenCookieJarTarget(
+      new electron.WebContentsView({
+        webPreferences: { ...HIDDEN_COOKIE_JAR_WEB_PREFERENCES }
+      })
+    );
+    rollback.add(() => cookieJar.dispose());
+    const sessionCookies = new SessionCookieVault({
+      jar: cookieJar.jar,
+      cipher: browserProfileCipher(),
+      ...sessionCookiePaths(options.userDataDir),
+      flushStore: () => browserSession.cookies.flushStore(),
+      clearSessionData: (what) => clearBrowsingData(browserSession, what),
+      log: log2
+    });
+    let restoreReport = null;
+    try {
+      restoreReport = await sessionCookies.restore();
+    } catch (error) {
+      log2(`[browser] session cookies: the restore failed (${String(error)})`);
+    }
+    checkpoint();
+    const cdp = new CdpPool({ log: log2 });
+    rollback.add(() => cdp.close());
+    const views = /* @__PURE__ */ new Map();
+    const releases = /* @__PURE__ */ new Set();
+    let stateWriter = null;
+    const sessionStore = new BrowserSessionStore({
+      dir: path$1.join(options.userDataDir, "browser"),
+      log: log2
     });
-    const notifyChrome = () => {
+    const consentNotifier = new ConsentNotifier({
+      show: options.windowShow,
+      /*
+       * The click's own rule lives in `consentClickHandler` (see it: the delivered
+       * payload, the order, and the raise are all asserted there), and this is the
+       * wiring that gives it the real window and the real plan. `windowShow` is the
+       * plan the click comes forward under — this module still never decides whether a
+       * window comes forward (design 11.4), it hands the plan to `window-raise.ts`.
+       */
+      onAttention: consentClickHandler({
+        /*
+         * THE WINDOW IS ASKED FOR, NOT CAPTURED, and the difference is the U2 fix:
+         * this host is stopped the moment its window closes (`src/main/index.ts`'s
+         * `closed` hook), but a banner already raised is still in Notification
+         * Center and its click still lands here. A captured window would be a
+         * destroyed one by then, and reading it throws.
+         */
+        window: () => options.window,
+        show: options.windowShow,
+        report: options.reportRaise,
+        reopen: options.reopenConsent
+      }),
+      log: log2
+    });
+    const captureSession = () => {
+      if (!published) return;
+      sessionStore.record(
+        captureTabs(
+          registry.list(),
+          registry.activeTab?.tabId ?? null,
+          host.failedTabIds()
+        )
+      );
+    };
+    const notifyChanged = () => {
+      stateWriter?.publishNow();
       options.window.webContents.send("browser-state-changed");
+      captureSession();
     };
-    contents.on("did-start-loading", () => {
-      host.clearLoadFailure(tabId);
-      notifyChrome();
+    const registry = new TabRegistry(
+      (_createOptions, tabId) => {
+        const view = buildView(options.window);
+        views.set(tabId, view);
+        wireView(view, tabId);
+        return view;
+      },
+      releaseTab,
+      notifyChanged
+    );
+    registryForDownloads = registry;
+    rollback.add(async () => {
+      published = false;
+      sessionStore.discard();
+      registry.destroyAll();
+      await Promise.allSettled([...releases]);
     });
-    contents.on("did-stop-loading", notifyChrome);
-    contents.on("page-title-updated", notifyChrome);
-    contents.on(
-      "did-fail-load",
-      (_event, code, description, url, isMainFrame) => {
-        if (!isMainFrame) return;
-        if (isReportableLoadFailure(code)) {
-          host.recordLoadFailure(tabId, {
-            code,
-            description,
-            url
-          });
+    const ownership = new OwnershipLedger({
+      mayAdopt: (token, requester) => {
+        const record = registry.requireSurface(token);
+        return record.handedTo === requester.slice("session:".length) && !record.allocationId;
+      },
+      closeTab: async (token) => {
+        try {
+          const record = registry.requireSurface(token);
+          approvals.forgetDocument(token);
+          registry.destroy(record.tabId);
+        } catch {
+        }
+        return true;
+      },
+      isLive: (token) => {
+        try {
+          registry.requireSurface(token);
+          return true;
+        } catch {
+          return false;
         }
-        notifyChrome();
       }
-    );
-    contents.on("will-attach-webview", (event) => {
-      event.preventDefault();
-      log2("[browser] refused a webview attachment inside a driven page");
     });
-    contents.on("did-navigate", (_event, url) => {
-      registry.bumpEpoch(tabId);
-      host.clearLoadFailure(tabId);
-      stopLogCapture(contents.id);
-      startLogCapture(contents.id);
-      log2(`[browser] tab ${tabId} navigated to ${url}`);
-      notifyChanged();
+    const approvals = new ApprovalStore({
+      dir: path$1.join(options.userDataDir, "browser"),
+      onChanged: () => {
+        options.window.webContents.send("browser-consent-changed");
+        consentNotifier.announce(approvals.pendingEntries());
+      },
+      log: log2
     });
-    contents.on("did-navigate-in-page", (_event, url, isMainFrame) => {
-      if (!isMainFrame) return;
-      registry.bumpEpoch(tabId, false);
-      log2(`[browser] tab ${tabId} navigated in page to ${url}`);
-      notifyChanged();
+    const profileDir = browserStoragePath(browserSession) ?? "";
+    const facts = {
+      proto: 1,
+      appVersion: options.appVersion,
+      profileDir,
+      profilePersistent: browserSession.isPersistent(),
+      userAgent: browserUserAgent(),
+      domainScope: domainScopeAvailable()
+    };
+    const host = new BrowserHost({
+      registry,
+      cdp,
+      approvals,
+      ownership,
+      downloads,
+      log: log2,
+      onChanged: notifyChanged,
+      facts: () => facts,
+      forgetSiteData: (origin) => clearOriginData(browserSession, origin)
     });
-    contents.on("destroyed", () => {
-      const record = registry.get(tabId);
-      if (record) {
-        const token = surfaceToken(record);
-        if (token) approvals.forgetDocument(token);
-        registry.forget(tabId);
-      }
-      host.clearLoadFailure(tabId);
-      releaseTab(tabId, contents.id);
+    const recorded = readSession(sessionStore.filePath, log2);
+    host.restoreTabs(recorded);
+    if (recorded.length) {
+      log2(
+        `[browser] restored ${recorded.length} tab(s) from ${SESSION_FILENAME}; every restored tab is user-owned and holds no handle (design 7.3)`
+      );
+    }
+    const consoleStartup = await startConsoleHost({
+      window: options.window,
+      expectedUrl: options.expectedUrl,
+      appVersion: options.appVersion,
+      notifier: options.notifier,
+      /*
+       * The capture view's document and preload, forwarded rather than re-derived:
+       * only the app knows where its own bundle lives, and a console host that
+       * guessed would answer a screenshot with a blank frame rather than with its
+       * own typed refusal. WITHOUT THESE TWO the host builds no capture view at all,
+       * which the live proof rig caught as `capture_unavailable` on a surface with
+       * no displayed pane — the exact shape of a seam that is wired in tests and
+       * forgotten in the one call site that matters.
+       */
+      consoleCaptureUrl: options.consoleCaptureUrl,
+      preloadPath: options.preloadPath,
+      userShellPath: options.userShellPath,
+      log: log2
     });
-  }
-  function wirePopup(child, details, popupChildren) {
-    popupChildren.add(child);
-    child.on("closed", () => popupChildren.delete(child));
-    const childContents = child.webContents;
-    childContents.setWindowOpenHandler((childDetails) => {
-      log2(`[browser] refused a popup from a popup: ${childDetails.url}`);
-      return { action: "deny" };
+    rollback.add(() => consoleStartup.stop());
+    checkpoint();
+    const sessionKey = mintSessionKey();
+    const server = await startRpcServer({
+      key: sessionKey,
+      instanceId: hostInstanceId,
+      dispatch: async (method, params, requestId2) => {
+        if (!isConsoleDispatchMethod(method)) {
+          return host.dispatch(method, params, requestId2);
+        }
+        if (!consoleStartup.ok) {
+          throw new ConsoleError(
+            "console_unavailable",
+            `this app's console is not available (${consoleStartup.reason}): ${consoleStartup.detail}`,
+            { reason: consoleStartup.reason }
+          );
+        }
+        return consoleStartup.dispatch(method, params);
+      },
+      log: log2,
+      capabilities: () => ({ console: consoleStartup.ok })
     });
-    const onWillNavigate = (event, rawUrl) => {
-      if (refusesNavigation(rawUrl)) {
-        event.preventDefault();
-        log2(`[browser] refused a popup navigation to ${rawUrl}`);
+    rollback.add(() => server.close());
+    checkpoint();
+    stateWriter = new BrowserStateWriter(
+      stateFilePath(),
+      () => {
+        const consoleCounts = consoleStartup.ok ? consoleStartup.counts() : { total: 0, agent: 0 };
+        return {
+          tabs: registry.count(),
+          agentTabs: registry.agentTabCount(),
+          profileDir,
+          console: consoleStartup.ok,
+          consoleSurfaces: consoleCounts.total,
+          consoleAgentSurfaces: consoleCounts.agent
+        };
+      },
+      {
+        appVersion: options.appVersion,
+        instanceId: hostInstanceId,
+        onError: (error) => log2(`[browser] state file: ${String(error)}`)
       }
-    };
-    childContents.on("will-navigate", onWillNavigate);
-    childContents.on("will-redirect", onWillNavigate);
-    childContents.on("will-attach-webview", (event) => {
-      event.preventDefault();
-      log2("[browser] refused a webview attachment inside a popup");
-    });
-    childContents.on("before-input-event", (event, input) => {
-      const direction = paneNavigationDirection(input);
-      if (!direction) return;
-      event.preventDefault();
-      const navigation = childContents.navigationHistory;
-      if (direction === "back") navigation.goBack();
-      else navigation.goForward();
+    );
+    rollback.add(() => stateWriter?.clear());
+    stateWriter.start(server.port, sessionKey);
+    Object.assign(bindings, {
+      window: () => options.window,
+      expectedUrl: options.expectedUrl,
+      host: () => host,
+      webauthn: () => webauthn,
+      clearData: (what) => sessionCookies.clearBrowsingData(what),
+      // THE REVEAL TAKES NO PATH FROM THE RENDERER (§16.4): it opens the directory the
+      // host is actually writing into, so the one place a page-derived string could
+      // have become a path stays out of the IPC surface as well. `shell.openPath`
+      // answers "" on success and a message on failure, which is returned rather than
+      // thrown: a reveal that fails is a Finder problem, not a fault in the agent's
+      // download.
+      revealDownloads: async () => {
+        const dir = downloads.downloadDir();
+        if (!dir) return "no download directory yet";
+        return electron.shell.openPath(dir);
+      },
+      log: log2
     });
-    if (!options.backgroundThrottling) {
-      childContents.setBackgroundThrottling(false);
-    }
-    presentPopupWindow(
-      child,
-      effectivePresentation(options.windowShow, details.disposition),
-      { trigger: "popup-open", report: options.reportRaise }
+    log2(
+      `[browser] host on ${server.address}:${server.port} (proto ${facts.proto}), profile ${profileDir || "(in-memory)"}, agent tabs ${registry.agentTabCount()}/${8}, console ${consoleStartup.ok ? `on (${consoleStartup.counts().total} surface(s))` : `off (${consoleStartup.reason})`}`
     );
+    const handle2 = {
+      host,
+      port: server.port,
+      profileDir,
+      agentTabs: () => registry.agentTabCount(),
+      sessionCookies: () => restoreReport,
+      stop: async () => {
+        const atStop = captureTabs(
+          registry.list(),
+          registry.activeTab?.tabId ?? null,
+          host.failedTabIds()
+        );
+        const decision = sessionStore.commitStopCapture(atStop);
+        if (!decision.write) {
+          log2(
+            `[browser] not overwriting ${SESSION_FILENAME} at stop: ${decision.reason}`
+          );
+        }
+        sessionStore.flush();
+        registry.destroyAll();
+        await Promise.allSettled([...releases]);
+        await cdp.close();
+        await server.close();
+        await consoleStartup.stop();
+        unregisterBrowserIpc();
+        detachSessionHandlers();
+        detachWebauthn();
+        webauthn.dispose();
+        stateWriter?.clear();
+        approvals.resetPending();
+        ownership.clear();
+        flushBrowserStorage(browserSession);
+        try {
+          await sessionCookies.snapshot();
+        } catch (error) {
+          log2(
+            `[browser] session cookies: the snapshot failed (${String(error)})`
+          );
+        }
+        cookieJar.dispose();
+        log2("[browser] host stopped");
+      }
+    };
+    checkpoint();
+    published = true;
+    activeHost = handle2;
+    rollback.commit();
+    return handle2;
+  } catch (error) {
+    published = false;
+    for (const key of Object.keys(bindings))
+      delete bindings[key];
+    await rollback.run(log2);
+    throw error;
   }
 }
 function releaseView(window, view) {
@@ -37741,6 +38052,15 @@ class UpdateService {
    * so it is kept rather than fetched again on the click (review U17).
    */
   lastPublishedBackendVersion = null;
+  /**
+   * The version PyPI most recently NAMED whose files were not yet
+   * downloadable, or null. Kept beside the published reading because the
+   * manual check's sentence depends on the distinction (UX round 1, U1):
+   * "a release is still publishing" and "the version could not be
+   * determined" are different facts with different next steps, and the
+   * gated read alone collapses them into one null.
+   */
+  pendingPypiVersion = null;
   /** Path of the artifact this run downloaded, when the updater reported one. */
   downloadedArtifactPath = null;
   /**
@@ -40550,8 +40870,17 @@ ${heal.removed.join("\n")}`,
     return (await this.readRunningBackend()).version;
   }
   /**
-   * Get the latest version from PyPI
-   * @returns Promise resolving to the latest version string or null if unable to fetch
+   * Get the latest READY version from PyPI: the newest release whose
+   * platform wheel an installer can actually download, per
+   * `readPypiReleaseBody`. A version PyPI has named but whose files have
+   * not finished uploading resolves null — the same answer as an
+   * unreadable response, because both mean do not offer yet; the next
+   * scheduled check re-reads. The named-but-not-ready version is kept on
+   * `pendingPypiVersion` so the manual check can say which state it is
+   * in. Reading only `info.version` here was the 2026-10-12 race: the
+   * offer appeared minutes after publication and `lop update` exited 1
+   * against artifacts that were not on PyPI yet.
+   * @returns Promise resolving to the latest ready version string or null if unable to fetch
    */
   getLatestPypiVersion() {
     return new Promise((resolve) => {
@@ -40567,14 +40896,26 @@ ${heal.removed.join("\n")}`,
         { timeout: PYPI_VERSION_READ_TIMEOUT_MS },
         (res) => {
           let data = "";
+          const settleAborted = () => {
+            this.pendingPypiVersion = null;
+            resolve(null);
+          };
+          res.on("error", settleAborted);
+          res.on("aborted", settleAborted);
           res.on("data", (chunk) => {
             data += chunk;
           });
           res.on("end", () => {
             try {
-              const packageInfo = JSON.parse(data);
-              const latestVersion = packageInfo.info?.version;
-              resolve(latestVersion || null);
+              const reading = readPypiReleaseBody(data, process.platform);
+              this.pendingPypiVersion = reading.readyVersion === null ? reading.namedVersion : null;
+              if (reading.readyVersion === null && reading.namedVersion) {
+                logger.info(
+                  `PyPI names version ${reading.namedVersion} but its release has no downloadable wheel for this platform yet; not offering it. The next check will re-read.`,
+                  LogFileType.UPDATE_SERVICE
+                );
+              }
+              resolve(reading.readyVersion);
             } catch (error) {
               logger.error(
                 "Error parsing PyPI response:",
@@ -40594,6 +40935,7 @@ ${heal.removed.join("\n")}`,
         );
       });
       request.on("error", (error) => {
+        this.pendingPypiVersion = null;
         logger.error(
           "Error fetching from PyPI:",
           LogFileType.UPDATE_SERVICE,
@@ -41028,7 +41370,19 @@ ${heal.removed.join("\n")}`,
         );
         if (reportFailure) {
           this.sendToRenderer("backend-update-error", {
-            message: "Unable to determine backend version.",
+            /*
+             * The not-ready state earns its own sentence (UX round 1, U1):
+             * PyPI answered and named a release whose files are still
+             * publishing, which is a wait, not a fault — the generic
+             * sentence below reads as an installation problem and sends
+             * the reader to debug one. Same producer-sentence shape as
+             * the unreadable-install branch below. No retry action is
+             * attached: the shared classifier gives authored sentences
+             * no control (it names its own next step), and this sentence
+             * does — check again in a few minutes, from the same control
+             * the reader just used.
+             */
+            message: installedVersion && this.pendingPypiVersion ? `A new server release (${this.pendingPypiVersion}) is still publishing, so no update was offered yet. Check again in a few minutes.` : "Unable to determine backend version.",
             phase: "check",
             logPath: serverUpdateLogPath()
           });