@parall/daemon 1.45.0 → 1.46.0

package/dist/clip-runtime/browser-profile-manager.js

@@ -5,6 +5,10 @@ import { createRequire } from 'node:module';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildBrowserDaemonEnv } from './browser-daemon-env.js';
+import { proxyCreateFields, proxyReconcileNeeded, reconcileAccountProxy, settlePendingCookieBackup, } from './browser-proxy-reconcile.js';
+import { appliedProxyFingerprint, clearCookieBackup, normalizeProxyConfig, proxyFingerprint, writeAppliedProxyFingerprint, } from './browser-proxy-state.js';
+import { assertOpenReady } from './browser-readiness.js';
+import { BrowserTargetError, BrowserTargetRegistry, TABLESS_COMMANDS, } from './browser-target-registry.js';
 import { BrowserViewerStreamer } from './browser-viewer-streamer.js';
 import { findFreePort, formatErrorForLog, sleep, waitForChildExit } from './subprocess.js';
 const BB_BROWSER_DAEMON_START_TIMEOUT_MS = 15_000;
@@ -31,9 +35,21 @@ export class BrowserProfileManager {
     // stop() began un-adoptable, so a late child can't be reassigned to this.daemon
     // and escape teardown.
     stopping = false;
+    // Three DISTINCT facts, tracked separately (do not conflate):
+    //  - ensuredAccounts: the bb-browser account EXISTS (created or confirmed).
+    //  - preparedAccounts: FIRST-USE preparation completed this session — desired
+    //    proxy reconciled to Parall's config AND readiness verified. A hydrated
+    //    (hosted, S3-restored) account exists but is NOT prepared until its first
+    //    invoke/viewer/open reconciles the proxy + probes readiness.
     ensuredAccounts = new Set();
+    preparedAccounts = new Set();
     ensuringAccounts = new Map();
+    preparingAccounts = new Map();
     reportedStatuses = new Map();
+    // Per-account owned-target binding: every tab-addressed command is pinned to a
+    // page in the profile's own BrowserContext (see browser-target-registry.ts for
+    // the account-blind-routing hazard this closes).
+    targets;
     // Live viewer orchestration (bb-viewer streamer subprocesses + viewer nav)
     // lives in BrowserViewerStreamer; the manager hands it the account-scoped
     // bb-browser command path via the host interface.
@@ -41,12 +57,16 @@ export class BrowserProfileManager {
     constructor(opts) {
         this.opts = opts;
         mkdirSync(this.opts.homeDir, { recursive: true });
+        this.targets = new BrowserTargetRegistry({
+            sendCommand: (request) => this.sendCommand(request),
+        });
         this.viewer = new BrowserViewerStreamer({
             log: this.opts.log,
             sendBrowserCommand: (request) => this.sendCommand(request),
-            ensureAccount: (account) => this.ensureAccount(account),
+            prepareForUse: (account) => this.prepareForUse(account).then(() => { }),
             withDaemonRecovery: (operation, label) => this.withDaemonRecovery(operation, label),
             cdpEndpoint: () => this.cdpEndpoint(),
+            targets: this.targets,
         });
     }
     async invoke({ profileId, account, command, input }) {
@@ -55,7 +75,7 @@ export class BrowserProfileManager {
         if (!account)
             throw new Error('browser account is required');
         try {
-            await this.withDaemonRecovery(() => this.prepareInvokeAccount(account), `prepare invoke ${command} for ${profileId}`);
+            await this.withDaemonRecovery(() => this.prepareForUse(account), `prepare invoke ${command} for ${profileId}`);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -72,9 +92,13 @@ export class BrowserProfileManager {
             }
             throw err;
         }
+        // Dispatch exactly once. A pinned tab that vanished between resolve and
+        // dispatch surfaces bb-browser's "Tab not found" as a hard error — the
+        // command is NEVER re-bound to a different tab and replayed (a click/type/
+        // eval retargeted mid-flight could act on a page the caller never meant).
+        // The next independent command re-establishes an owned target through the
+        // normal resolve path; that is the only recovery.
         try {
-            // Do not replay arbitrary forwarded browser commands: click/type/eval can
-            // have user-visible side effects if Chrome consumed the first attempt.
             const result = await this.sendCommand(request);
             this.reportStatus(profileId, 'running');
             return result;
@@ -100,7 +124,10 @@ export class BrowserProfileManager {
             this.reportedStatuses.delete(profileId);
         }
         try {
-            await this.withDaemonRecovery(() => this.ensureAccount(profileId), `ensure runtime for ${profileId}`);
+            // Shared first-use invariant. A steady reconcile tick (already prepared,
+            // not a pending-row recovery) takes the fast path inside prepareForUse;
+            // forceStatusReport forces a full re-prepare (proxy + readiness).
+            await this.withDaemonRecovery(() => this.prepareForUse(profileId, { force: opts.forceStatusReport }), `ensure runtime for ${profileId}`);
             this.reportStatus(profileId, 'running');
         }
         catch (err) {
@@ -121,8 +148,17 @@ export class BrowserProfileManager {
         const url = normalizeStartUrl(startUrl);
         try {
             await this.withDaemonRecovery(async () => {
-                const prepareResult = await this.prepareOpenProfile(profileId, url);
-                await this.openProfileTabOnce(profileId, url, prepareResult.accountCreated);
+                // Open is an explicit lifecycle action: FORCE a full first-use prepare so
+                // a proxy edit made while the profile was stopped takes effect now
+                // (cookie-preserving reconcile) and readiness is re-verified — never
+                // bb-browser's stored proxy. prepareForUse handles proxy + readiness; the
+                // readiness probe runs on a sacrificial tab, so landing the start URL on
+                // the primary owned tab afterward is independent.
+                const { accountCreated } = await this.prepareForUse(profileId, {
+                    startUrl: url,
+                    force: true,
+                });
+                await this.openProfileTabOnce(profileId, url, accountCreated);
             }, `open profile ${profileId}`);
             this.reportStatus(profileId, 'running');
         }
@@ -132,6 +168,19 @@ export class BrowserProfileManager {
             throw err;
         }
     }
+    /** Resolve + normalize/validate the desired proxy (fail closed on legacy-invalid
+     *  configs — see browser-proxy-state.ts). null = direct egress. */
+    async resolveDesiredProxy(profileId) {
+        const desired = this.opts.resolveProxy ? await this.opts.resolveProxy(profileId) : null;
+        return normalizeProxyConfig(desired);
+    }
+    assertReady(profileId, proxy) {
+        return assertOpenReady({
+            log: this.opts.log,
+            targets: this.targets,
+            sendCommand: (request) => this.sendCommand(request),
+        }, profileId, { proxy, probeUrl: this.opts.proxyProbeUrl });
+    }
     async stopProfile(profileId) {
         if (!profileId)
             throw new Error('browser profile id is required');
@@ -179,7 +228,9 @@ export class BrowserProfileManager {
         this.daemon = null;
         this.starting = null;
         this.ensuredAccounts.clear();
+        this.preparedAccounts.clear();
         this.ensuringAccounts.clear();
+        this.preparingAccounts.clear();
         this.reportedStatuses.clear();
         if (restarting) {
             try {
@@ -232,29 +283,60 @@ export class BrowserProfileManager {
         if (!host || typeof port !== 'number' || !Number.isFinite(port)) {
             throw new Error('bb-browser /status did not report a CDP endpoint');
         }
+        this.lastCdpEndpoint = { host, port };
         return { host, port };
     }
-    async prepareOpenProfile(profileId, url) {
-        const accountCreated = await this.ensureAccount(profileId, url !== 'about:blank' ? url : undefined);
-        await this.sendCommand({ method: 'tab_list', account: profileId });
-        return { accountCreated };
+    // Last CDP endpoint observed from /status — a PASSIVE record for shutdown-time
+    // checks (browser-quiescence): null when Chrome never started this run, and
+    // possibly stale after a daemon restart (a stale port refuses connections,
+    // which reads as "gone" — exactly the safe answer).
+    lastCdpEndpoint = null;
+    /** Process-group id of the last spawned bb-browser tree (the detached child's
+     *  pid). Survives the child's exit — quiescence probes it AFTER stop() to
+     *  confirm the orphaned Chrome is gone too. null = never spawned. */
+    lastPgid = null;
+    /** The browser tree's process-group id for the quiescence barrier. */
+    lastKnownProcessGroup() {
+        return this.lastPgid;
+    }
+    /** Peek the last known Chrome CDP endpoint WITHOUT starting anything. */
+    lastKnownCdpEndpoint() {
+        return this.lastCdpEndpoint;
     }
+    /**
+     * Land the profile on its start URL, idempotently, always inside its own
+     * context. A fresh account already opened `url` via `account_create`
+     * (accountCreated) — just bind it. Otherwise: reuse an owned tab already on
+     * the URL if any (repeated Open is a no-op), else NAVIGATE the profile's
+     * primary owned tab (`open {tabId}`) — never stack a new tab per Open.
+     */
     async openProfileTabOnce(profileId, url, accountCreated) {
-        if (accountCreated)
+        if (accountCreated) {
+            await this.targets.ensureOwnedTab(profileId);
             return;
-        if (await this.profileAlreadyHasOpenTab(profileId, url))
-            return;
-        await this.sendCommand({ method: 'tab_new', account: profileId, url });
+        }
+        if (url !== 'about:blank') {
+            const existing = await this.targets.findOwnedTabMatchingUrl(profileId, url);
+            if (existing !== undefined)
+                return;
+        }
+        const tabId = await this.targets.ensureOwnedTab(profileId);
+        if (url !== 'about:blank') {
+            await this.sendCommand({ method: 'open', account: profileId, tabId, url });
+        }
     }
     async resetProfileOnce(profileId) {
         if (await this.accountExists(profileId)) {
             await this.sendCommand({ method: 'account_delete', account: profileId });
         }
+        // Account gone → both cached facts invalidated (exists, prepared).
         this.ensuredAccounts.delete(profileId);
-    }
-    async prepareInvokeAccount(account) {
-        await this.ensureAccount(account);
-        await this.sendCommand({ method: 'tab_list', account });
+        this.preparedAccounts.delete(profileId);
+        // Reset means "erase this profile's persisted state". A proxy reconcile that
+        // crashed mid-flight left a pending cookie backup on disk; the next Open's
+        // ensureAccount would restore it into the fresh account and RESURRECT the very
+        // login state Reset just erased. Drop it so Reset is a true clean slate.
+        clearCookieBackup(this.opts.homeDir, profileId);
     }
     async recoverInvokeAvailability(label, profileId, err) {
         try {
@@ -268,18 +350,40 @@ export class BrowserProfileManager {
         }
     }
     async accountExists(account) {
+        return (await this.getAccountInfo(account)).exists;
+    }
+    /** One account_info round trip: existence + whether bb-browser holds a proxy for
+     *  the account (server/username only — bb-browser never returns the password). */
+    async getAccountInfo(account) {
         try {
-            await this.sendCommand({ method: 'account_info', account });
-            return true;
+            const result = await this.sendCommand({ method: 'account_info', account });
+            const accounts = Array.isArray(result.accounts)
+                ? result.accounts
+                : [];
+            const info = accounts.find((a) => a?.name === account) ?? accounts[0];
+            return { exists: true, showsProxy: info?.proxy != null };
         }
         catch (err) {
             if (isBrowserAccountInfoUnauthenticatedError(err))
-                return true;
+                return { exists: true, showsProxy: false };
             if (isBrowserAccountNotFoundError(err))
-                return false;
+                return { exists: false, showsProxy: false };
             throw err;
         }
     }
+    /**
+     * Build the wire request for a forwarded browser command, binding it to a
+     * page the profile's account OWNS. bb-browser's own routing is account-blind
+     * (tab-less → global current tab → `targets[0]`, which is the default-context
+     * `about:blank` Chrome launches with — no cookies, NO PROXY), so:
+     *
+     *  - a caller-supplied `tabId`/`tab` must resolve to one of the profile's own
+     *    tabs (numeric global indices are rejected outright);
+     *  - every other tab-addressed command gets the profile's primary owned tab
+     *    stamped in (recreated inside the profile's BrowserContext if its pages
+     *    were closed — never silently retargeted at another page);
+     *  - only genuinely tab-less commands (TABLESS_COMMANDS) go unpinned.
+     */
     async buildCommandRequest(account, command, input) {
         const body = input && typeof input === 'object' && !Array.isArray(input)
             ? { ...input }
@@ -287,106 +391,187 @@ export class BrowserProfileManager {
         const request = body;
         request.method = command;
         request.account = account;
-        if (command === 'eval' && typeof request.domain === 'string' && request.tabId === undefined) {
-            const tabRef = await this.resolveAccountDomainTab(account, request.domain);
-            if (tabRef !== undefined)
-                request.tabId = tabRef;
-        }
+        // Did the CALLER pin a specific tab? (`tabId`/`tab` present in the input.)
+        const ref = request.tabId ?? request.tab;
+        const explicitTarget = ref !== undefined && ref !== null && ref !== '';
+        // Domain-addressed eval resolves a page by domain — but ONLY when the caller
+        // pinned no explicit tab. An explicit `tab`/`tabId` (even alongside `domain`)
+        // wins; guarding on `!explicitTarget` (not just `tabId === undefined`) so a
+        // short `tab` ref isn't silently overridden.
+        if (command === 'eval' && typeof request.domain === 'string' && !explicitTarget) {
+            const tabRef = await this.targets.resolveDomainTab(account, request.domain);
+            if (tabRef === undefined) {
+                // Never fall through to bb-browser's account-blind domain resolution: it
+                // searches ALL contexts and creates missing tabs in the DEFAULT context
+                // (unproxied, cookie-less).
+                throw new BrowserTargetError(`could not resolve a ${request.domain} page inside browser profile ${account}`, 'BROWSER_TARGET_UNAVAILABLE');
+            }
+            request.tabId = tabRef;
+            return request;
+        }
+        if (command === 'site_run' && !explicitTarget) {
+            // bb-browser's site_run routes account-BLIND to the global current tab (the
+            // unowned, unproxied default-context about:blank → real-IP egress) when the
+            // adapter has no domain and no explicit tab. Decide safety from the ADAPTER's
+            // OWN metadata — its `domain` via site_info(siteName) — NEVER a caller-supplied
+            // request.domain (upstream site_run ignores that field, so it can't gate
+            // routing). Domain-ful adapter → pin an owned tab ON that domain; domain-less
+            // adapter → require an explicit owned tab, else fail closed.
+            const siteName = typeof request.siteName === 'string' ? request.siteName.trim() : '';
+            if (siteName === '') {
+                throw new BrowserTargetError(`site_run needs a siteName in browser profile ${account}`, 'BROWSER_TARGET_UNAVAILABLE');
+            }
+            const domain = await this.siteAdapterDomain(account, siteName);
+            if (domain === '') {
+                throw new BrowserTargetError(`site_run adapter "${siteName}" has no domain — it needs an explicit owned tab in browser profile ${account}, refusing account-blind global routing`, 'BROWSER_TARGET_UNAVAILABLE');
+            }
+            const tabRef = await this.targets.resolveDomainTab(account, domain);
+            if (tabRef === undefined) {
+                throw new BrowserTargetError(`could not resolve a ${domain} page for site_run "${siteName}" in browser profile ${account}`, 'BROWSER_TARGET_UNAVAILABLE');
+            }
+            // Pin the owned, on-domain tab so upstream executeSiteAdapter uses THIS tab
+            // (an explicit tabId short-circuits its own domain/global resolution).
+            request.tabId = tabRef;
+            return request;
+        }
+        if (TABLESS_COMMANDS.has(command)) {
+            // Pure account/list commands (site_info/site_list/account_*/tab_list/tab_new)
+            // take no pinned tab; an explicit ref still gets the ownership check below.
+            if (!explicitTarget)
+                return request;
+        }
+        request.tabId = await this.targets.resolveCommandTarget(account, ref);
+        delete request.tab;
         return request;
     }
     /**
-     * Account-scoped version of bb-browser's `resolveTabByDomain` (which is
-     * account-blind — the reason for this daemon-side preselection workaround).
-     * Two properties the bare `tab_new` + eval approach lacked, both caught on
-     * the staging closed-loop E2E (2026-06-04):
+     * The domain bb-browser's adapter metadata declares for `siteName` (via
+     * site_info), or '' when the adapter genuinely has no domain / does not exist.
+     * This is the ONLY trustworthy domain source for site_run routing — a
+     * caller-supplied request.domain is ignored by upstream site_run, so it can never
+     * gate account-safe routing.
      *
-     * 1. Reuse: an existing account tab already on the domain is reused instead
-     *    of opening a new tab per eval (upstream reuses matching tabs too).
-     * 2. Load wait: after creating a tab, wait for the navigation to commit
-     *    before eval — upstream waits (~10s poll + settle); without it the clip
-     *    script races `about:blank` and relative fetches fail
-     *    ("Failed to parse URL from /hot.json").
+     * Error handling is deliberately split: ONLY a genuine application-level answer
+     * from bb-browser ("no such site") yields '' → the caller fails closed. A
+     * RECOVERABLE daemon/CDP failure (or any transport error) RETHROWS, so
+     * buildCommandRequest's existing `isRecoverableBrowserDaemonError` →
+     * `recoverInvokeAvailability` restart+retry path handles it. Masking those as a
+     * domain-less adapter would turn a transient hiccup into a permanent
+     * BROWSER_TARGET_UNAVAILABLE. Note a BrowserCommandError can itself carry a
+     * recoverable message ("Chrome not connected"), so the recoverable check wins.
      */
-    async resolveAccountDomainTab(account, domain) {
-        const url = normalizeDomainUrl(domain);
-        let host = '';
+    async siteAdapterDomain(account, siteName) {
         try {
-            host = new URL(url).host;
-        }
-        catch {
-            /* fall through — tab_new with whatever bb-browser makes of it */
+            const info = await this.sendCommand({ method: 'site_info', siteName, account });
+            return typeof info.domain === 'string' ? info.domain.trim() : '';
         }
-        if (host) {
-            const existing = await this.findAccountTabOnHost(account, host);
-            if (existing !== undefined)
-                return existing;
-        }
-        const tab = await this.sendCommand({ method: 'tab_new', url, account });
-        const tabRef = (tab?.tab ?? tab?.tabId);
-        if (tabRef === undefined || !host)
-            return tabRef;
-        // Wait for the created tab to actually reach the domain (navigation
-        // committed). Mirrors upstream resolveTabByDomain's bounded wait + settle.
-        const deadline = Date.now() + 10_000;
-        while (Date.now() < deadline) {
-            const found = await this.findAccountTabOnHost(account, host, tabRef);
-            if (found !== undefined)
-                break;
-            await sleep(300);
-        }
-        await sleep(750); // post-commit settle (upstream uses a flat 2s)
-        return tabRef;
-    }
-    /** Find an account-owned tab whose URL host matches (optionally a specific tab). */
-    async findAccountTabOnHost(account, host, onlyTabRef) {
-        const list = await this.sendCommand({ method: 'tab_list', account });
-        const tabs = Array.isArray(list.tabs)
-            ? list.tabs
-            : [];
-        for (const t of tabs) {
-            if (t?.account !== account)
-                continue;
-            const ref = (t.tab ?? t.tabId);
-            if (onlyTabRef !== undefined && ref !== onlyTabRef && t.tabId !== onlyTabRef)
-                continue;
-            if (typeof t.url !== 'string')
-                continue;
-            try {
-                if (hostsMatch(new URL(t.url).host, host))
-                    return ref;
-            }
-            catch {
-                /* non-URL tab (about:blank etc.) — skip */
+        catch (err) {
+            if (err instanceof BrowserCommandError && !isRecoverableBrowserDaemonError(err)) {
+                return '';
             }
+            throw err;
         }
-        return undefined;
     }
-    async ensureAccount(account, accountUrl) {
-        if (this.ensuredAccounts.has(account))
+    /**
+     * First-use preparation — the SINGLE invariant shared by invoke, viewer, open,
+     * and ensureRuntime (fix #4). Runs ONCE per account per session:
+     *   1. resolve Parall's desired proxy (fail closed on invalid config);
+     *   2. ensure the account exists AND its applied proxy matches desired
+     *      (cookie-preserving reconcile if it drifted — e.g. a hydrated hosted
+     *      account created under an old proxy);
+     *   3. verify readiness (owned target answers; when proxied, a real request
+     *      traverses the proxy without a transport error).
+     * Subsequent calls take the steady fast path — no config fetch, no probe —
+     * unless `force` is set (explicit lifecycle open / pending-row recovery). A
+     * daemon restart, reset, or proxy reconcile clears the prepared marker so the
+     * next use re-prepares. Deduped so concurrent first-uses share one run.
+     */
+    prepareForUse(account, opts = {}) {
+        if (this.preparedAccounts.has(account) && !opts.force) {
+            // Steady path: confirm the account still exists + owns a tab (no-op once
+            // ensured); no desired-proxy fetch, no readiness probe.
+            return this.ensureAccount(account).then(() => ({ accountCreated: false }));
+        }
+        const inflight = this.preparingAccounts.get(account);
+        if (inflight && !opts.force)
+            return inflight;
+        // Serialize per account: even a FORCED prepare (openProfile) chains AFTER any
+        // in-flight one, so a proxy reconcile's account_delete/account_create can never
+        // run concurrently for the same account (which would corrupt its context /
+        // cookie jar). A non-forced caller dedups onto the in-flight promise above; a
+        // forced caller waits for it, then does its own (now-cheap, fingerprint-matched)
+        // pass. The prior error is swallowed so a failed prepare doesn't poison the next.
+        const prior = inflight ? inflight.catch(() => undefined) : Promise.resolve(undefined);
+        const run = prior.then(async () => {
+            // Drop any stale "prepared" fact up front: if this (possibly forced) full
+            // prepare fails at reconcile or readiness, the account must NOT stay marked
+            // prepared, or the next non-forced invoke would fast-path past proxy
+            // alignment + the probe and run on an old proxy / half-rebuilt account. The
+            // flag is re-added only after a fully successful prepare below.
+            this.preparedAccounts.delete(account);
+            const desired = await this.resolveDesiredProxy(account);
+            const accountCreated = await this.ensureAccount(account, {
+                desiredProxy: desired,
+                accountUrl: opts.startUrl && opts.startUrl !== 'about:blank' ? opts.startUrl : undefined,
+            });
+            await this.assertReady(account, desired);
+            this.preparedAccounts.add(account);
+            return { accountCreated };
+        });
+        this.preparingAccounts.set(account, run);
+        return run.finally(() => {
+            if (this.preparingAccounts.get(account) === run)
+                this.preparingAccounts.delete(account);
+        });
+    }
+    /**
+     * Ensure the profile's bb-browser account exists and honors the DESIRED proxy.
+     *
+     * `desiredProxy` semantics:
+     *   - undefined (invoke fast path): don't fetch/reconcile — create-only proxy
+     *     resolution via opts.resolveProxy when the account is missing. A proxy
+     *     change applies at the next open / first ensure.
+     *   - null / config (open + first ensure): Parall's config is the SSOT. A
+     *     missing account is created with it; an existing account whose APPLIED
+     *     fingerprint (Parall-owned sidecar) differs is rebuilt with cookies
+     *     preserved (reconcileAccountProxy) — bb-browser's persisted account proxy
+     *     never wins.
+     */
+    async ensureAccount(account, opts = {}) {
+        const { accountUrl, desiredProxy } = opts;
+        if (this.ensuredAccounts.has(account) && desiredProxy === undefined)
             return false;
         const inflight = this.ensuringAccounts.get(account);
         if (inflight)
             return inflight;
         const ensure = (async () => {
             let accountCreated = false;
-            try {
-                await this.sendCommand({ method: 'account_info', account });
+            const info = await this.getAccountInfo(account);
+            if (!info.exists) {
+                // Create with the desired proxy — pre-resolved by the caller, or resolved
+                // here (invoke path). Validation fails closed: no account rather than
+                // direct egress for a proxy-configured profile.
+                const proxy = desiredProxy !== undefined ? desiredProxy : await this.resolveDesiredProxy(account);
+                await this.sendCommand({
+                    method: 'account_create',
+                    account,
+                    ...(accountUrl ? { accountUrl } : {}),
+                    ...proxyCreateFields(proxy),
+                });
+                accountCreated = true;
+                // A proxy reconcile that crashed after account_delete left a cookie
+                // backup — this fresh account is its continuation. One shared settle
+                // tail (restore → clear backup → fingerprint LAST) finishes it.
+                await settlePendingCookieBackup(this.reconcileHost(), account, proxyFingerprint(proxy));
             }
-            catch (err) {
-                if (!isBrowserAccountInfoUnauthenticatedError(err)) {
-                    if (!isBrowserAccountNotFoundError(err))
-                        throw err;
-                    // Resolve the proxy ONLY here, at the single account-creation choke point.
-                    // A thrown resolve fails closed (no account rather than direct egress for a
-                    // proxy-configured profile). bb-browser binds the proxy at account_create.
-                    const proxy = this.opts.resolveProxy ? await this.opts.resolveProxy(account) : null;
-                    await this.sendCommand({
-                        method: 'account_create',
-                        account,
-                        ...(accountUrl ? { accountUrl } : {}),
-                        ...proxyCreateFields(proxy),
-                    });
-                    accountCreated = true;
+            else if (desiredProxy !== undefined) {
+                const recorded = appliedProxyFingerprint(this.opts.homeDir, account);
+                if (proxyReconcileNeeded(recorded, desiredProxy, info.showsProxy)) {
+                    await reconcileAccountProxy(this.reconcileHost(), account, desiredProxy);
+                }
+                else if (recorded === undefined) {
+                    // Both sides direct — adopt the fingerprint so later checks are exact.
+                    writeAppliedProxyFingerprint(this.opts.homeDir, account, proxyFingerprint(desiredProxy));
                 }
             }
             if (!accountUrl) {
@@ -403,47 +588,17 @@ export class BrowserProfileManager {
             this.ensuringAccounts.delete(account);
         }
     }
+    reconcileHost() {
+        return {
+            log: this.opts.log,
+            homeDir: this.opts.homeDir,
+            targets: this.targets,
+            sendCommand: (request) => this.sendCommand(request),
+            cdpEndpoint: () => this.cdpEndpoint(),
+        };
+    }
     async ensureAccountOwnedTab(account) {
-        if (await this.hasAccountOwnedTab(account))
-            return;
-        await this.sendCommand({ method: 'tab_new', account, url: 'about:blank' });
-    }
-    async profileAlreadyHasOpenTab(profileId, url) {
-        // Lifecycle `open` can be delivered more than once (WS + pending reconcile,
-        // retry, or duplicate user action). Treat only the requested target URL as
-        // already-open; a same-host different path is still a distinct user intent.
-        if (url === 'about:blank')
-            return this.hasAccountOwnedTab(profileId);
-        return this.findAccountTabMatchingUrl(profileId, url);
-    }
-    async hasAccountOwnedTab(account) {
-        const list = await this.sendCommand({ method: 'tab_list', account });
-        const tabs = Array.isArray(list.tabs)
-            ? list.tabs
-            : [];
-        return tabs.some((tab) => tab?.account === account);
-    }
-    async findAccountTabMatchingUrl(account, url) {
-        const expected = comparableUrl(url);
-        if (!expected)
-            return false;
-        const list = await this.sendCommand({ method: 'tab_list', account });
-        const tabs = Array.isArray(list.tabs)
-            ? list.tabs
-            : [];
-        for (const tab of tabs) {
-            if (tab?.account !== account || typeof tab.url !== 'string')
-                continue;
-            const actual = comparableUrl(tab.url);
-            if (!actual)
-                continue;
-            const sameResource = hostsMatch(actual.host, expected.host) && actual.target === expected.target;
-            const sameProtocol = actual.protocol === expected.protocol;
-            const redirectedUpgrade = expected.protocol === 'http:' && actual.protocol === 'https:';
-            if (sameResource && (sameProtocol || redirectedUpgrade))
-                return true;
-        }
-        return false;
+        await this.targets.ensureOwnedTab(account);
     }
     reportStatus(profileId, status, errorMsg) {
         const marker = `${status}\u0000${errorMsg ?? ''}`;
@@ -525,7 +680,9 @@ export class BrowserProfileManager {
         this.daemon = null;
         this.starting = null;
         this.ensuredAccounts.clear();
+        this.preparedAccounts.clear();
         this.ensuringAccounts.clear();
+        this.preparingAccounts.clear();
         this.opts.log.warn(`[bb-browser] ${label} hit an unavailable Chrome/CDP page target; restarting bb-browser-daemon (${formatErrorForLog(err)})`);
         if (!daemon)
             return;
@@ -597,7 +754,15 @@ export class BrowserProfileManager {
         ], {
             env: buildBrowserDaemonEnv(process.env, this.opts.homeDir),
             stdio: ['ignore', 'ignore', 'pipe'],
+            // detached: bb-browser becomes the LEADER of a fresh process group, and
+            // Chrome + its renderers (spawned by bb-browser with detached:false)
+            // inherit it. That group id (= this child's pid) is the daemon's owned
+            // handle on the whole browser tree — browser-quiescence.ts signals and
+            // awaits `-pgid` instead of scanning /proc for user-data-dir strings.
+            // Direct child management (waitForChildExit, child.kill) is unaffected.
+            detached: true,
         });
+        this.lastPgid = child.pid ?? null;
         // A spawn/exec failure (ENOENT, EACCES, …) emits 'error' on the child, which
         // — with no listener — Node re-throws as an uncaught exception and crashes
         // the daemon. Capture it so startup fails through the normal path instead.
@@ -659,17 +824,6 @@ export class BrowserProfileManager {
         }
     }
 }
-/** Host comparison tolerant of a `www.` prefix on either side. */
-function hostsMatch(a, b) {
-    const norm = (h) => h.toLowerCase().replace(/^www\./, '');
-    return norm(a) === norm(b);
-}
-function normalizeDomainUrl(domain) {
-    const trimmed = domain.trim();
-    if (!trimmed)
-        return 'about:blank';
-    return /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
-}
 function normalizeStartUrl(value) {
     const trimmed = value?.trim();
     if (!trimmed)
@@ -678,6 +832,11 @@ function normalizeStartUrl(value) {
         return trimmed;
     return /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
 }
+/**
+ * bb-browser's `ensurePageTarget` throws `Tab not found: <ref>` when a string
+ * ref no longer resolves — strictly BEFORE the command dispatch switch runs, so
+ * the command did not execute and a single re-resolve + retry is safe.
+ */
 function isBrowserAccountNotFoundError(err) {
     if (!(err instanceof BrowserCommandError) || err.method !== 'account_info')
         return false;
@@ -712,19 +871,6 @@ function isRecoverableBrowserDaemonError(err) {
         (lower.includes('bb-browser /command returned 503') &&
             (lower.includes('chrome') || lower.includes('cdp'))));
 }
-function comparableUrl(url) {
-    try {
-        const parsed = new URL(url);
-        return {
-            protocol: parsed.protocol,
-            host: parsed.host,
-            target: `${parsed.pathname}${parsed.search}${parsed.hash}`,
-        };
-    }
-    catch {
-        return null;
-    }
-}
 function resolveBbBrowserDaemonPath() {
     // Bundle channels (CDN self-update, desktop, npm bin — all run the flat
     // esbuild artifact with NO node_modules) ship bb-browser as a sibling flat
@@ -748,15 +894,3 @@ function resolveBbBrowserDaemonPath() {
 function randomToken() {
     return randomBytes(16).toString('hex');
 }
-/** Render a proxy config into bb-browser `account_create` fields (camelCase, the
- *  bb-browser-pro 0.15 contract). Empty when there is no proxy → direct egress. */
-function proxyCreateFields(proxy) {
-    if (!proxy?.server)
-        return {};
-    const fields = { proxyServer: proxy.server };
-    if (proxy.username)
-        fields.proxyUsername = proxy.username;
-    if (proxy.password)
-        fields.proxyPassword = proxy.password;
-    return fields;
-}