@parall/daemon 1.34.0 → 1.36.0

package/dist/clip-runtime/browser-viewer-streamer.js

@@ -0,0 +1,691 @@
+import { spawn } from 'node:child_process';
+import { findFreePort, formatErrorForLog, sleep } from './subprocess.js';
+const BB_VIEWER_HEALTH_TIMEOUT_MS = 10_000;
+const BB_VIEWER_COMMAND_TIMEOUT_MS = 15_000;
+// A streamer whose session never received a stream.answer is abandoned: the
+// client vanished mid-handshake (hard tab close before its session id arrived)
+// and can never send a scoped stream.close. Reap it so the bb-viewer process +
+// CDP screencast don't park until the next stream.start. The handshake
+// (answer follows start by seconds once the client has the offer) finishes
+// far inside this window even on a cold pod.
+const BB_VIEWER_UNANSWERED_REAP_MS = 90_000;
+// Grace between SIGTERM and the SIGKILL escalation in killChild.
+const BB_VIEWER_TERM_GRACE_MS = 5_000;
+/**
+ * bb-viewer's /command control plane is UNAUTHENTICATED, so on the shared agents
+ * cluster its bind host MUST be loopback — a 0.0.0.0 / pod-IP / typo'd value would
+ * silently re-open it cross-tenant. Only these exact loopback forms are accepted;
+ * anything else is rejected (fail fast) at spawn.
+ */
+export function isLoopbackBindHost(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '[::1]';
+}
+/**
+ * Whether a kick targets the CURRENT live streamer (so its process is torn down). A
+ * kick with no explicit target hits whoever is live; an explicit target tears down the
+ * current streamer ONLY when it matches — a stale/replayed session_id must not kill a
+ * newer live viewer (it is only recorded for straggler rejection). currentSessionId
+ * undefined (no live streamer) → never a current-kill.
+ */
+export function kickHitsCurrentSession(requested, currentSessionId) {
+    if (currentSessionId === undefined)
+        return false;
+    return requested === undefined || requested === currentSessionId;
+}
+export class BrowserViewerStreamer {
+    host;
+    // Live bb-viewer (WebRTC streamer) subprocess per profile. One per profile;
+    // see StreamerState. Cleaned up on stream.close, stopProfile, resetProfile,
+    // and stop().
+    streamers = new Map();
+    // The most-recently server-side-kicked viewer session per profile (design §3.6
+    // PR7). After a kick the streamer is gone, so the session-staleness guards
+    // (which key off a live streamer) can no longer reject the kicked viewer's
+    // straggler nav commands — this map does. Reset whenever the profile's streamer
+    // is (re)killed via killProfileStreamer, so a fresh stream.start clears it. One
+    // entry per profile (overwritten per kick); bounded, no leak.
+    kickedSessions = new Map();
+    // Set by shutdown(): an in-flight spawnStreamer has no map entry yet, so a
+    // shutdown during its health poll would otherwise let the bb-viewer child
+    // survive daemon stop (on BYOC nothing else reaps it).
+    stopping = false;
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * Handle a viewer control command for a profile. Throws on any failure (the
+     * supervisor maps a throw to a `{error:{message}}` reply); never returns a
+     * partial result. `data.input` / `data.turn` / `data.session_id` come from
+     * MachineBrowserProfileViewerData.
+     */
+    async handleViewerCommand(profileId, sessionId, command, input, turn) {
+        if (!profileId)
+            throw new Error('browser profile id is required');
+        // Reject a kicked viewer's straggler commands (design §3.6 PR7). After a kick
+        // there is no streamer, so the per-command staleness guards (which compare
+        // against a live streamer's sessionId) would let a kicked viewer keep driving
+        // nav. A fresh stream.start re-establishes a session (killProfileStreamer
+        // clears the marker), so it is exempt.
+        if (command !== 'stream.start' &&
+            sessionId &&
+            this.kickedSessions.get(profileId) === sessionId) {
+            throw new Error('viewer session was terminated');
+        }
+        switch (command) {
+            case 'stream.start':
+                return this.viewerStreamStart(profileId, sessionId, turn);
+            case 'stream.answer':
+                return this.viewerStreamAnswer(profileId, sessionId, input);
+            case 'stream.close':
+                return this.viewerStreamClose(profileId, sessionId, input);
+            case 'stream.switch':
+                return this.viewerStreamSwitch(profileId, sessionId, input);
+            case 'kick':
+                return this.viewerKick(profileId, sessionId, input);
+            case 'close':
+                return this.viewerCloseTab(profileId, sessionId, input);
+            case 'tab_list':
+            case 'tab_new':
+            case 'open':
+            case 'reload':
+            case 'back':
+            case 'forward':
+                return this.viewerForwardNav(profileId, sessionId, command, input);
+            default:
+                throw new Error(`unknown viewer command: ${command}`);
+        }
+    }
+    /**
+     * kick — server-side per-viewer disconnect (design §3.6 PR7). Terminates ONE
+     * viewer's WebRTC session: stop its bb-viewer streamer (killing the process
+     * tears down the peer connection + datachannel) and reject the kicked session's
+     * subsequent commands — while bb-browser + Chromium (the agent's live browser)
+     * keep running. This is explicitly DISTINCT from stopping the pod / profile,
+     * which would kill the agent's browser too; a viewer session is a sub-session of
+     * the profile lease, so a kick does NOT release the lease.
+     *
+     * Targets `input.session_id` if given, else the current streamer's session.
+     * Idempotent: kicking with no live streamer still records the kicked session.
+     */
+    viewerKick(profileId, sessionId, input) {
+        const streamer = this.streamers.get(profileId);
+        const requested = typeof input?.session_id === 'string' ? input.session_id : undefined;
+        const target = requested || streamer?.sessionId || sessionId;
+        // Only tear down the LIVE streamer when the kick targets the current session — a
+        // replayed/delayed stale session_id must not kill a newer live viewer. A kick with
+        // no explicit target (kick "whoever is live") also tears it down. A stale target is
+        // still recorded so its straggler commands are rejected by the staleness guard.
+        const killsCurrent = kickHitsCurrentSession(requested, streamer?.sessionId);
+        if (killsCurrent) {
+            // killProfileStreamer clears the kick marker, so record the target AFTER it.
+            this.killProfileStreamer(profileId);
+        }
+        if (target)
+            this.kickedSessions.set(profileId, target);
+        this.host.log.info(`[bb-viewer] kicked viewer session ${target || '(none)'} for profile ${profileId}; pod + agent browser keep running`);
+        return target ? { ok: true, kicked: true, session_id: target } : { ok: true, kicked: true };
+    }
+    /**
+     * stream.start — spawn a FRESH bb-viewer for this profile (killing any prior
+     * one), resolve the profile's account-scoped page-target CDP ws URL, and run
+     * the streamer's `connect` command. Records sessionId on the streamer entry.
+     */
+    async viewerStreamStart(profileId, sessionId, turn) {
+        // Fresh streamer per stream.start: a leftover viewer would still hold the
+        // single-viewer slot inside bb-viewer (connect cleans up its prior viewer,
+        // but we also want a clean process + sessionId per server-side session).
+        this.killProfileStreamer(profileId);
+        // Wrap the bb-browser CDP resolution in the same auto-recovery the agent
+        // invoke path uses: a disconnected Chrome/CDP restarts bb-browser + retries
+        // rather than failing the viewer outright.
+        const cdpUrl = await this.host.withDaemonRecovery(() => this.resolveAccountPageCdpUrl(profileId), `viewer stream.start ${profileId}`);
+        // CDP screencast only emits frames for the tab Chrome is compositing (the
+        // foreground tab of its window). With multiple account tabs the streamed
+        // target is often backgrounded → 0 frames → black viewer. Activate it first.
+        await this.bringTargetToFront(cdpUrl);
+        const streamer = await this.spawnStreamer(profileId, sessionId, turn);
+        try {
+            const result = await this.streamerCommand(streamer, 'connect', { cdpUrl });
+            // Tell the client the EXACT tab being streamed so it targets nav commands
+            // (open/back/forward/reload) at the same tab — no client-side guessing.
+            streamer.streamedTabId = targetIdFromCdpUrl(cdpUrl);
+            // Reap an abandoned (never-answered) streamer — identity-checked so a
+            // kill/respawn in the meantime is never affected. unref: the timer must
+            // not hold the daemon process open.
+            const reapTimer = setTimeout(() => {
+                const current = this.streamers.get(profileId);
+                if (current === streamer && !current.answered) {
+                    this.host.log.warn(`[bb-viewer] no stream.answer for ${profileId} within ${BB_VIEWER_UNANSWERED_REAP_MS / 1000}s; reaping abandoned streamer`);
+                    this.killProfileStreamer(profileId);
+                }
+            }, BB_VIEWER_UNANSWERED_REAP_MS);
+            reapTimer.unref?.();
+            return { ...result, streamed_tab_id: streamer.streamedTabId };
+        }
+        catch (err) {
+            // connect failed → don't leave a dead/idle streamer parked on the profile.
+            this.killProfileStreamer(profileId);
+            throw err;
+        }
+    }
+    /**
+     * stream.answer — apply the client's WebRTC answer to the profile's streamer.
+     * Rejects if the streamer's sessionId no longer matches (a stale viewer
+     * session from a superseded stream.start).
+     */
+    async viewerStreamAnswer(profileId, sessionId, input) {
+        const streamer = this.streamers.get(profileId);
+        if (!streamer)
+            throw new Error('no active viewer streamer for profile');
+        if (streamer.sessionId !== sessionId)
+            throw new Error('stale viewer session');
+        // Mark BEFORE the (up to 15s) bb-viewer await: an answer accepted near the
+        // reap deadline must not be torn down mid-processing by the timer. A failed
+        // answer leaves the streamer un-reaped, which is fine — the client surfaces
+        // the error and the next stream.start replaces the streamer anyway.
+        streamer.answered = true;
+        return this.streamerCommand(streamer, 'answer', input ?? {});
+    }
+    /**
+     * stream.close — best-effort stop the streamer, then kill + remove it. A
+     * stale session's close (independent HTTP legs can arrive out of order after
+     * a retry) must NOT tear down a successor session's live streamer, so a
+     * mismatched sessionId is ignored. An EMPTY sessionId gets the same stale
+     * treatment — a client closed mid-handshake never received a session id, and
+     * its unscoped close racing the next session's stream.start would kill that
+     * session's live streamer (React StrictMode's dev double-mount exercises
+     * exactly this ordering). The only unscoped close is an explicit
+     * `{force:true}` input, reserved for a server-initiated admin disconnect.
+     */
+    async viewerStreamClose(profileId, sessionId, input) {
+        const streamer = this.streamers.get(profileId);
+        if (streamer) {
+            const force = input?.force === true;
+            if (!force && streamer.sessionId !== sessionId) {
+                return { ok: true, stale: true };
+            }
+            try {
+                await this.streamerCommand(streamer, 'stop', {});
+            }
+            catch (err) {
+                this.host.log.warn(`[bb-viewer] stop command failed for ${profileId} (killing anyway): ${formatErrorForLog(err)}`);
+            }
+            this.killProfileStreamer(profileId);
+        }
+        return { ok: true };
+    }
+    /**
+     * stream.switch — point the existing streamer at a different account-scoped
+     * tab. input {tab} is the bb-browser short tab id / target id. Guarded by
+     * sessionId like stream.answer: a superseded session must not steer the
+     * current streamer, and an EMPTY sessionId is rejected the same way — every
+     * real caller has its session id by the time it can switch (it arrives with
+     * the stream.start response), so a session-less switch is by definition not
+     * the current viewer.
+     */
+    async viewerStreamSwitch(profileId, sessionId, input) {
+        const streamer = this.streamers.get(profileId);
+        if (!streamer)
+            throw new Error('no active viewer streamer for profile');
+        if (!sessionId || streamer.sessionId !== sessionId)
+            throw new Error('stale viewer session');
+        const tab = input?.tab;
+        if (tab === undefined || tab === null || tab === '') {
+            throw new Error('stream.switch requires input.tab');
+        }
+        const cdpUrl = await this.host.withDaemonRecovery(() => this.resolveAccountPageCdpUrl(profileId, tab), `viewer stream.switch ${profileId}`);
+        // Foreground the new tab so Chrome composites it (see viewerStreamStart).
+        await this.bringTargetToFront(cdpUrl);
+        const result = await this.streamerCommand(streamer, 'switch', { cdpUrl });
+        streamer.streamedTabId = targetIdFromCdpUrl(cdpUrl);
+        return { ...result, streamed_tab_id: streamer.streamedTabId };
+    }
+    /**
+     * close — close an account tab via bb-browser, then, if the closed tab was
+     * the one being streamed, re-point the streamer at the profile's next active
+     * tab. Without the re-switch the streamer stays bound to a destroyed CDP
+     * target and the viewer goes black. Returns `streamed_tab_id` when a
+     * re-switch happened so the client can adopt the new active tab.
+     */
+    async viewerCloseTab(profileId, sessionId, input) {
+        // Resolve the client's ref to the canonical full target id BEFORE closing:
+        // streamedTabId stores the full id, so comparing the raw input (possibly a
+        // short `tab` ref) would close the right tab but skip the re-switch and
+        // leave the stream on a destroyed target. A ref-less close pins to the
+        // account's active tab, matching viewerForwardNav's ref-less behavior.
+        const ref = viewerTabRef(input ?? {});
+        const closedTargetId = ref !== undefined
+            ? await this.accountTabTargetId(profileId, ref)
+            : await this.accountActivePageTargetId(profileId);
+        const result = await this.viewerForwardNav(profileId, sessionId, 'close', {
+            ...(input ?? {}),
+            tabId: closedTargetId,
+        });
+        const streamer = this.streamers.get(profileId);
+        if (!streamer || !streamer.streamedTabId || streamer.streamedTabId !== closedTargetId) {
+            return result;
+        }
+        const cdpUrl = await this.host.withDaemonRecovery(() => this.resolveAccountPageCdpUrl(profileId), `viewer close re-switch ${profileId}`);
+        await this.bringTargetToFront(cdpUrl);
+        const sw = await this.streamerCommand(streamer, 'switch', { cdpUrl });
+        streamer.streamedTabId = targetIdFromCdpUrl(cdpUrl);
+        return { ...result, ...sw, streamed_tab_id: streamer.streamedTabId };
+    }
+    /**
+     * Bring a CDP page target to the foreground via Chrome's DevTools HTTP
+     * endpoint (`/json/activate/{targetId}`, same host:port as the CDP ws). Chrome
+     * does not composite backgrounded tabs, so `Page.startScreencast` on a
+     * background tab yields zero frames (black viewer). Best-effort: a failure
+     * must not block the stream. host:port + targetId are parsed from the cdpUrl
+     * (`ws://host:port/devtools/page/<targetId>`) to avoid an extra /status call.
+     */
+    async bringTargetToFront(cdpUrl) {
+        const m = /^ws:\/\/([^/]+)\/devtools\/page\/(.+)$/.exec(cdpUrl);
+        if (!m)
+            return;
+        const [, hostPort, targetId] = m;
+        try {
+            const resp = await fetch(`http://${hostPort}/json/activate/${targetId}`, {
+                method: 'GET',
+                signal: AbortSignal.timeout(5_000),
+            });
+            if (!resp.ok) {
+                this.host.log.warn(`[bb-viewer] activate target ${targetId} returned ${resp.status} (continuing)`);
+            }
+        }
+        catch (err) {
+            this.host.log.warn(`[bb-viewer] activate target ${targetId} failed (continuing): ${formatErrorForLog(err)}`);
+        }
+    }
+    /**
+     * Forward a navigation command (tab_list/tab_new/open/reload/back/forward/
+     * close) to bb-browser scoped to the profile's account. This lets the human
+     * in the live viewer navigate and handle OAuth popups directly. Reuses the
+     * same account-scoped sendCommand path the agent invokes use.
+     *
+     * SECURITY — the `account` field alone does NOT scope tab addressing:
+     * bb-browser's ensurePageTarget resolves a client-supplied tab/tabId against
+     * EVERY page target in the shared Chrome (all accounts), and tab_list
+     * returns every tab with `account` as a mere annotation (verified in
+     * @pinixai/bb-browser-pro@0.15.0 dist/daemon.js ensurePageTarget/tab_list).
+     * On a multi-profile host that would let one profile's viewer list,
+     * navigate, and close other profiles' logged-in tabs. So before forwarding:
+     * (a) any tab ref must resolve through accountTabTargetId, which throws on
+     * tabs the profile's account does not own; (b) ref-less tab-addressed
+     * commands are pinned to the profile's own active tab instead of
+     * bb-browser's account-blind global current tab; (c) tab_list output is
+     * filtered to the profile's own rows; and (d) open/tab_new URLs must be
+     * http(s)/about:blank — file:// or chrome:// would read the host
+     * filesystem / browser internals straight into the video stream.
+     */
+    async viewerForwardNav(profileId, sessionId, command, input) {
+        // Takeover isolation: when a live streamer exists, mutating nav/tab
+        // commands must come from ITS session — a superseded viewer tab (older or
+        // missing session id) must not keep steering the profile after a newer
+        // stream.start took over. Read-only tab_list stays unscoped. With no live
+        // streamer there is no takeover to protect (server-side profile authz
+        // already gates the caller).
+        if (command !== 'tab_list') {
+            const streamer = this.streamers.get(profileId);
+            if (streamer && streamer.sessionId !== sessionId) {
+                throw new Error('stale viewer session');
+            }
+        }
+        return this.host.withDaemonRecovery(async () => {
+            await this.host.ensureAccount(profileId);
+            const request = { ...(input ?? {}) };
+            if (command === 'open' || command === 'tab_new') {
+                assertViewerNavigableUrl(request.url);
+            }
+            const ref = viewerTabRef(request);
+            if (ref !== undefined) {
+                request.tabId = await this.accountTabTargetId(profileId, ref);
+                delete request.tab;
+            }
+            else if (REFLESS_PIN_NAV.has(command)) {
+                // `open` without a ref creates a tab inside the account context
+                // (bb-browser createTabInContext) — safe without pinning.
+                request.tabId = await this.accountActivePageTargetId(profileId);
+            }
+            const result = await this.host.sendBrowserCommand({
+                ...request,
+                method: command,
+                account: profileId,
+            });
+            return command === 'tab_list' ? filterTabListToAccount(result, profileId) : result;
+        }, `viewer ${command} ${profileId}`);
+    }
+    /**
+     * Resolve `ws://<cdpHost>:<cdpPort>/devtools/page/<targetId>` for a PAGE
+     * target owned by THIS profile's account — NOT bb-browser's global current
+     * tab (which `getCurrentTabCdpUrl`/`getTabCdpUrl` in the bundled daemon use
+     * via `cdp.currentTargetId`, an account-blind global; see daemon.js
+     * line ~10389/10410). When `tabRef` is given (stream.switch) we resolve that
+     * specific account tab; otherwise the profile's active page tab.
+     *
+     * Evidence from the installed @pinixai/bb-browser-pro@0.15.0 dist/daemon.js:
+     *  - GET /status (handleStatus, line ~1659-1668) returns `cdpHost` + `cdpPort`
+     *    — the CDP host/port the daemon's Chrome listens on.
+     *  - The CDP page ws URL format is `ws://<cdp.host>:<cdp.port>/devtools/page/<page.id>`
+     *    (getCurrentTabCdpUrl, line ~10392), where `page.id` is the full CDP
+     *    targetId (getTargets maps `t.targetId` → `.id`, line ~2461-2466).
+     *  - tab_list (command handler, line ~1041-1059) returns per-tab
+     *    `{ tabId: t.id, tab: <shortId>, account: <accountName>, url, ... }`, so
+     *    `tabId` is exactly the full targetId for the devtools URL and `account`
+     *    is the per-tab attribution we filter on (reused by findAccountTabOnHost).
+     */
+    async resolveAccountPageCdpUrl(profileId, tabRef) {
+        await this.host.ensureAccount(profileId);
+        const { host, port } = await this.host.cdpEndpoint();
+        const targetId = tabRef !== undefined
+            ? await this.accountTabTargetId(profileId, tabRef)
+            : await this.accountActivePageTargetId(profileId);
+        return `ws://${host}:${port}/devtools/page/${targetId}`;
+    }
+    /**
+     * Full CDP targetId of the profile account's active page tab (the owned tab
+     * Chrome marks active, else the first owned tab). If the account owns no
+     * page tab yet, open `about:blank` for it first (mirrors the agent-invoke
+     * path's "always give a fresh account an owned tab" rule).
+     */
+    async accountActivePageTargetId(profileId) {
+        let targetId = await this.firstAccountPageTargetId(profileId);
+        if (targetId !== undefined)
+            return targetId;
+        await this.host.sendBrowserCommand({
+            method: 'tab_new',
+            account: profileId,
+            url: 'about:blank',
+        });
+        targetId = await this.firstAccountPageTargetId(profileId);
+        if (targetId === undefined) {
+            throw new Error(`no page tab found for profile account ${profileId}`);
+        }
+        return targetId;
+    }
+    /**
+     * Full CDP targetId (`tabId`) of the account's active page tab: the owned tab
+     * Chrome marks `active` when it belongs to this account, else the first owned
+     * tab (the global active flag is account-blind — another profile's tab may
+     * hold it, which must not leak here).
+     */
+    async firstAccountPageTargetId(profileId) {
+        const tabs = await this.accountTabs(profileId);
+        let firstOwned;
+        for (const t of tabs) {
+            if (t.account !== profileId)
+                continue;
+            const tabId = t.tabId;
+            if (typeof tabId !== 'string' || !tabId)
+                continue;
+            if (t.active === true)
+                return tabId;
+            firstOwned ??= tabId;
+        }
+        return firstOwned;
+    }
+    /**
+     * Full CDP targetId for a specific account tab, addressed by the bb-browser
+     * short tab id (`tab`) or full target id (`tabId`). Used by stream.switch.
+     */
+    async accountTabTargetId(profileId, tabRef) {
+        const ref = String(tabRef);
+        const tabs = await this.accountTabs(profileId);
+        for (const t of tabs) {
+            if (t.account !== profileId)
+                continue;
+            const tabId = typeof t.tabId === 'string' ? t.tabId : undefined;
+            const shortTab = t.tab === undefined ? undefined : String(t.tab);
+            if ((tabId && tabId === ref) || (shortTab && shortTab === ref)) {
+                if (!tabId)
+                    break;
+                return tabId;
+            }
+        }
+        throw new Error(`tab ${ref} not found for profile account ${profileId}`);
+    }
+    /** `tab_list {account}` rows, typed to the fields we read (tabId/tab/account/active). */
+    async accountTabs(profileId) {
+        const list = await this.host.sendBrowserCommand({ method: 'tab_list', account: profileId });
+        return Array.isArray(list.tabs)
+            ? list.tabs
+            : [];
+    }
+    // ---- bb-viewer streamer lifecycle ----
+    /**
+     * Spawn a bb-viewer streamer for the profile and wait until healthy. Binary
+     * is PRLL_BB_VIEWER_BIN (our image sets it to /usr/local/bin/bb-viewer),
+     * defaulting to `bb-viewer` on PATH — we NEVER download it. A free port is
+     * allocated per streamer. Stores the entry in `this.streamers` once healthy.
+     */
+    async spawnStreamer(profileId, sessionId, turn) {
+        if (this.stopping)
+            throw new Error('viewer streamer is shutting down');
+        const bin = process.env.PRLL_BB_VIEWER_BIN ?? 'bb-viewer';
+        const port = await findFreePort();
+        const args = ['--api-only', '--port', String(port)];
+        // Bind bb-viewer's HTTP control surface (/command + /health) to a specific
+        // host when the image opts in via PRLL_BB_VIEWER_HOST (the hosted browser pod
+        // sets it to 127.0.0.1; design §3.6 PR7). The streamer ALWAYS reaches
+        // bb-viewer over loopback (streamerCommand + the health poll below both use
+        // 127.0.0.1), so a loopback bind never breaks the in-pod path — it only
+        // removes the 0.0.0.0 exposure that, on the shared agents cluster, would let
+        // another tenant's pod re-point this streamer or start its own stream. Left
+        // unset (no --host) for BYOC and the current pinned bb-viewer, which has no
+        // --host flag — see deploy/browser-docker/AGENTS.md "bb-viewer loopback bind".
+        const bindHost = process.env.PRLL_BB_VIEWER_HOST?.trim();
+        if (bindHost) {
+            // SECURITY: bb-viewer's /command is unauthenticated, so on the shared agents
+            // cluster its bind host MUST be loopback — a 0.0.0.0 / pod-IP / typo'd value would
+            // silently re-open the cross-tenant control plane this env exists to close. Fail
+            // fast on anything non-loopback rather than pass it through to --host.
+            if (!isLoopbackBindHost(bindHost)) {
+                throw new Error(`PRLL_BB_VIEWER_HOST must be loopback (127.0.0.1, localhost, ::1, [::1]) — refusing to bind bb-viewer's unauthenticated /command to ${bindHost}`);
+            }
+            args.push('--host', bindHost);
+        }
+        if (turn?.url) {
+            args.push('--turn-url', turn.url, '--turn-user', turn.username ?? '', '--turn-cred', turn.credential ?? '');
+        }
+        // Do NOT inherit the daemon's full env: it carries the machine key
+        // (PRLL_API_KEY = mck_) plus provider/cloud creds that bb-viewer must never
+        // see. bb-viewer only talks to a localhost CDP ws URL + its own HTTP port
+        // (via flags/commands), so a minimal allowlist is sufficient.
+        const streamerEnv = {};
+        for (const key of ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'DISPLAY']) {
+            const val = process.env[key];
+            if (val !== undefined)
+                streamerEnv[key] = val;
+        }
+        this.host.log.info(`[bb-viewer] spawning for profile ${profileId} on port ${port}`);
+        const child = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'], env: streamerEnv });
+        // Capture spawn failure (ENOENT/EACCES) so startup fails through the normal
+        // path instead of crashing the daemon on an unhandled 'error' event.
+        let childError = null;
+        child.once('error', (err) => {
+            childError = err;
+        });
+        // A streamer that dies AFTER passing health (bb-viewer crash) must not
+        // leave a stale entry behind — later stream.answer/switch would hammer a
+        // dead port until the next stream.start. Only clear the entry if it still
+        // points at THIS child (killProfileStreamer deletes first, and a respawn
+        // may have replaced it).
+        child.once('exit', () => {
+            const current = this.streamers.get(profileId);
+            if (current?.child === child) {
+                this.streamers.delete(profileId);
+                this.host.log.warn(`[bb-viewer] streamer for ${profileId} exited; cleared stale entry`);
+            }
+        });
+        child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString('utf8').trim();
+            if (text)
+                this.host.log.info(`[bb-viewer] ${text}`);
+        });
+        child.stderr?.on('data', (chunk) => {
+            const text = chunk.toString('utf8').trim();
+            if (text)
+                this.host.log.warn(`[bb-viewer] ${text}`);
+        });
+        const deadline = Date.now() + BB_VIEWER_HEALTH_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            if (this.stopping) {
+                this.killChild(child, 'streamer for stopping daemon');
+                throw new Error('viewer streamer is shutting down');
+            }
+            if (childError) {
+                throw childError;
+            }
+            if (child.exitCode !== null || child.signalCode !== null) {
+                throw new Error('bb-viewer exited during startup');
+            }
+            try {
+                const resp = await fetch(`http://127.0.0.1:${port}/health`, {
+                    signal: AbortSignal.timeout(2_000),
+                });
+                if (resp.ok) {
+                    const streamer = { child, port, sessionId };
+                    this.streamers.set(profileId, streamer);
+                    this.host.log.info(`[bb-viewer] ready for profile ${profileId} on port ${port}`);
+                    return streamer;
+                }
+            }
+            catch {
+                /* not up yet */
+            }
+            await sleep(200);
+        }
+        this.killChild(child, 'unhealthy streamer');
+        throw new Error('bb-viewer did not become healthy in time');
+    }
+    /**
+     * SIGTERM with a SIGKILL escalation: a bb-viewer that hangs or ignores TERM
+     * would otherwise outlive its teardown holding the port + CDP session (the
+     * shell-level pattern-kill only exists on the hosted pod, not BYOC). The
+     * escalation timer is unref'd so it never holds the daemon open; it is
+     * cleared on exit. Caveat: a daemon process that exits immediately after
+     * shutdown() abandons the timer — acceptable, the TERM was still sent.
+     */
+    killChild(child, label) {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            return; /* already gone */
+        }
+        const killTimer = setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) {
+                this.host.log.warn(`[bb-viewer] ${label} ignored SIGTERM; escalating to SIGKILL`);
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }, BB_VIEWER_TERM_GRACE_MS);
+        killTimer.unref?.();
+        child.once('exit', () => clearTimeout(killTimer));
+    }
+    /**
+     * POST a command to the profile's bb-viewer `/command` endpoint. Parses the
+     * `{result}` / `{error:{message}}` envelope (bb-viewer api.go) and returns
+     * the inner result, throwing the error message on failure.
+     */
+    async streamerCommand(streamer, method, params) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), BB_VIEWER_COMMAND_TIMEOUT_MS);
+        try {
+            const resp = await fetch(`http://127.0.0.1:${streamer.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ method, params }),
+                signal: controller.signal,
+            });
+            const text = await resp.text();
+            const parsed = (text ? JSON.parse(text) : {});
+            if (parsed.error) {
+                throw new Error(parsed.error.message || `bb-viewer ${method} failed`);
+            }
+            if (!resp.ok) {
+                throw new Error(`bb-viewer ${method} returned ${resp.status}: ${text}`);
+            }
+            return parsed.result ?? {};
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Kill + remove the profile's bb-viewer streamer, if any. Idempotent. Also
+     * clears any kick marker for the profile: a (re)kill establishes a clean
+     * streamer slot, so a subsequent stream.start starts un-kicked. viewerKick
+     * re-records the kicked session AFTER calling this.
+     */
+    killProfileStreamer(profileId) {
+        this.kickedSessions.delete(profileId);
+        const streamer = this.streamers.get(profileId);
+        if (!streamer)
+            return;
+        this.streamers.delete(profileId);
+        this.killChild(streamer.child, `streamer for ${profileId}`);
+    }
+    /**
+     * Tear down every profile streamer and refuse new spawns (daemon stop).
+     * Idempotent.
+     */
+    shutdown() {
+        this.stopping = true;
+        for (const profileId of [...this.streamers.keys()]) {
+            this.killProfileStreamer(profileId);
+        }
+    }
+}
+/** Extract the full CDP target id from a `ws://host:port/devtools/page/<id>` URL. */
+function targetIdFromCdpUrl(cdpUrl) {
+    return /\/devtools\/page\/(.+)$/.exec(cdpUrl)?.[1];
+}
+/**
+ * Tab-addressed nav commands that, when called WITHOUT an explicit tab ref,
+ * must be pinned to the profile's own active tab — bb-browser would otherwise
+ * fall back to its account-blind global current tab (another profile's).
+ */
+const REFLESS_PIN_NAV = new Set(['reload', 'back', 'forward', 'close']);
+/** Client-supplied tab reference (full target id preferred, short id fallback). */
+function viewerTabRef(request) {
+    for (const key of ['tabId', 'tab']) {
+        const v = request[key];
+        if ((typeof v === 'string' && v !== '') || typeof v === 'number')
+            return String(v);
+    }
+    return undefined;
+}
+const VIEWER_NAVIGABLE_PROTOCOLS = new Set(['http:', 'https:']);
+/** open/tab_new URL gate: http(s) or about:blank only (see viewerForwardNav). */
+function assertViewerNavigableUrl(raw) {
+    // Presence/emptiness is bb-browser's contract to enforce ("Missing url").
+    if (raw === undefined || raw === null || raw === '')
+        return;
+    if (typeof raw !== 'string')
+        throw new Error('url must be a string');
+    if (raw === 'about:blank')
+        return;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`invalid url: ${raw}`);
+    }
+    if (!VIEWER_NAVIGABLE_PROTOCOLS.has(parsed.protocol)) {
+        throw new Error(`url scheme not allowed in the live viewer: ${parsed.protocol.replace(/:$/, '')}`);
+    }
+}
+/** tab_list rows are account-annotated but unfiltered — keep only the profile's own. */
+function filterTabListToAccount(result, account) {
+    const tabs = Array.isArray(result.tabs) ? result.tabs : [];
+    const owned = tabs.filter((t) => t?.account === account);
+    return { ...result, tabs: owned, activeIndex: owned.findIndex((t) => t?.active === true) };
+}