@minionry/minion 0.7.36

package/dist/server/services/browser/host.js

@@ -0,0 +1,1067 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { spawn as defaultSpawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { childEnvOverrides, chromiumLaunchFlags, withoutCoreDumps } from './chromium-launch-spec.js';
+import { browserLog } from './debug-log.js';
+import { BOOT_PACKAGE_VERSION, buildChildEnv, checkSpawnPreconditions, classifyCrash, DEFAULT_INITIAL_URL, DEFAULT_VIEWPORT, describeSpawnError, extractCandidate, extractLeaseExpired, LIFECYCLE_EVENTS, MAX_RESTARTS, RECOVER_THROTTLE_MS, RESTART_BACKOFFS_MS, resolveDefaultAppDir, resolveDefaultElectronBinary, resolveSdkStubPath, SIGTERM_GRACE_MS, STARTUP_TIMEOUT_MS, TabInfoCache, } from './host-internal.js';
+import { PipeWireSinkSupervisor } from './pipewire-sink.js';
+import { ChromiumSandboxPolicy } from './sandbox-policy.js';
+import { shouldForwardStderrLine } from './stderr-noise-filter.js';
+import { XvfbSupervisor } from './xvfb-supervisor.js';
+const log = browserLog('host');
+const IPC_DEADLINE_SLACK_MS = 5_000;
+function ipcDeadlineFor(opTimeoutMs) {
+    return typeof opTimeoutMs === 'number' && opTimeoutMs > 0
+        ? { timeoutMs: opTimeoutMs + IPC_DEADLINE_SLACK_MS }
+        : undefined;
+}
+const STDERR_TAIL_LINES = 5;
+function readOutboundSignal(kind, payload) {
+    if (!payload || typeof payload !== 'object') {
+        log.error('signal.out.malformed', `kind=${kind} payload=${typeof payload}`);
+        return null;
+    }
+    const obj = payload;
+    if (typeof obj.sessionId !== 'string' || !obj.sessionId) {
+        log.error('signal.out.noSession', `kind=${kind} — dropped`);
+        return null;
+    }
+    return { obj, sessionId: obj.sessionId };
+}
+function readSelectedCandidateType(raw) {
+    if (raw === null)
+        return null;
+    return raw === 'host' || raw === 'srflx' || raw === 'prflx' || raw === 'relay' ? raw : undefined;
+}
+function describeControllerState(obj) {
+    const reason = typeof obj.reason === 'string' ? obj.reason : '-';
+    const path = typeof obj.selectedCandidateType === 'string' ? obj.selectedCandidateType : '-';
+    return ` state=${String(obj.state)} reason=${reason} path=${path}`;
+}
+export class ElectronBrowserHost extends EventEmitter {
+    spawnFn;
+    now;
+    setTimeoutFn;
+    clearTimeoutFn;
+    ipcClientFactory;
+    resolvedAppDir;
+    electronBinaryOverride;
+    checkPreconditions;
+    bootVersion;
+    resolvedElectronBinary = null;
+    platform;
+    env;
+    xvfbSupervisor;
+    pipewireSinkSupervisor;
+    sandboxPolicy;
+    sidecarRelease = Promise.resolve();
+    lifecycleEpoch = 0;
+    state = 'idle';
+    url = null;
+    viewport = null;
+    child = null;
+    childPid = null;
+    childExited = false;
+    helloSeen = false;
+    ipc = null;
+    childFailure = null;
+    crashedTabs = new Map();
+    childStderrTail = [];
+    stopRequested = false;
+    restartAttempts = 0;
+    restartTimer = null;
+    lastRecoverAt = 0;
+    lastCrashReason = null;
+    lastStartOptions = null;
+    startPromise = null;
+    startResolve = null;
+    startReject = null;
+    startTimer = null;
+    tabInfoCache = new TabInfoCache();
+    currentTabId = null;
+    agentTabAliases = new Map();
+    dom;
+    js;
+    sdk;
+    constructor(options = {}) {
+        super();
+        this.spawnFn = options.spawn ?? defaultSpawn;
+        this.now = options.now ?? Date.now;
+        this.setTimeoutFn = options.timers?.setTimeout ?? setTimeout;
+        this.clearTimeoutFn = options.timers?.clearTimeout ?? clearTimeout;
+        this.ipcClientFactory = options.ipcClientFactory ?? null;
+        this.resolvedAppDir = options.appDir ?? resolveDefaultAppDir();
+        this.electronBinaryOverride = options.electronBinaryPath ?? null;
+        this.checkPreconditions = options.checkPreconditions ?? checkSpawnPreconditions;
+        this.bootVersion = options.bootVersion === undefined ? BOOT_PACKAGE_VERSION : options.bootVersion;
+        this.platform = options.platform ?? process.platform;
+        this.env = options.env ?? process.env;
+        this.xvfbSupervisor = options.xvfbSupervisor ?? new XvfbSupervisor();
+        this.pipewireSinkSupervisor =
+            options.pipewireSinkSupervisor ?? new PipeWireSinkSupervisor();
+        this.sandboxPolicy =
+            options.sandboxPolicy ?? new ChromiumSandboxPolicy({ env: this.env, platform: this.platform });
+        if (this.sandboxPolicy.parsed.invalid !== undefined) {
+            console.warn(`[ElectronBrowserHost] MINIONRY_CHROMIUM_SANDBOX=${JSON.stringify(this.sandboxPolicy.parsed.invalid)} is not one of auto|on|off — treating it as "on" (sandbox required, no fallback)`);
+        }
+        this.dom = this.buildDomSurface();
+        this.js = this.buildJsSurface();
+        this.sdk = this.buildSdkSurface();
+    }
+    emit(event, ...args) {
+        const result = super.emit(event, ...args);
+        if (LIFECYCLE_EVENTS.has(event)) {
+            super.emit('status', this.getStatus());
+        }
+        return result;
+    }
+    async start(opts) {
+        log('start.enter', `state=${this.state} orchestra=${opts.orchestraId}`);
+        if (this.state === 'ready' || this.state === 'starting') {
+            if (this.startPromise === null) {
+                log.warn('start.invariant', `state=${this.state} but startPromise is null`);
+                return Promise.reject(new Error(`ElectronBrowserHost.start: invariant violated — state=${this.state} but startPromise is null. ` +
+                    'This can only happen if startPromise was externally reset.'));
+            }
+            log('start.idempotent', `state=${this.state} returning existing startPromise`);
+            return this.startPromise;
+        }
+        if (this.child !== null) {
+            log.warn('start.childStillExiting', `state=${this.state} pid=${this.childPid ?? 'none'}`);
+            return Promise.reject(new Error('ElectronBrowserHost.start: the previous browser process is still exiting — try again in a moment'));
+        }
+        this.stopRequested = false;
+        this.lifecycleEpoch += 1;
+        this.lastStartOptions = opts;
+        this.viewport = opts.viewport ?? DEFAULT_VIEWPORT;
+        this.url = opts.initialUrl ?? DEFAULT_INITIAL_URL;
+        this.state = 'starting';
+        const startPromise = new Promise((res, rej) => {
+            this.startResolve = res;
+            this.startReject = rej;
+        });
+        this.startPromise = startPromise;
+        this.resolvedElectronBinary = this.electronBinaryOverride ?? resolveDefaultElectronBinary();
+        const blocker = this.checkPreconditions({
+            electronBinary: this.resolvedElectronBinary,
+            appDir: this.resolvedAppDir,
+            bootVersion: this.bootVersion,
+        });
+        if (blocker !== null) {
+            log.error('start.precondition', blocker);
+            this.transitionToCrashed(null, null, `cannot start the browser: ${blocker}`, { permanent: true });
+            return startPromise;
+        }
+        this.launch(opts.orchestraId);
+        return startPromise;
+    }
+    launch(orchestraId) {
+        if (this.startTimer) {
+            this.clearTimeoutFn(this.startTimer);
+            this.startTimer = null;
+        }
+        this.pipewireSinkSupervisor.start(orchestraId, (err) => this.emit('error', err));
+        try {
+            this.spawnChild();
+        }
+        catch (err) {
+            log.error('start.spawnFailed', err);
+            const message = err instanceof Error ? err.message : String(err);
+            this.releaseChild();
+            this.transitionToCrashed(null, null, `spawn failed — ${message}`, { permanent: true });
+            return;
+        }
+        this.startTimer = this.setTimeoutFn(() => {
+            this.startTimer = null;
+            const tail = this.childStderrTail.length > 0
+                ? ` — last stderr: ${this.childStderrTail.join(' | ')}`
+                : '';
+            const err = new Error(`ElectronBrowserHost.start: child did not signal ready within ${STARTUP_TIMEOUT_MS}ms${tail}`);
+            this.state = 'crashed';
+            this.lastCrashReason = err.message;
+            this.emit('crashed', { code: null, signal: null, reason: err.message });
+            this.failStart(err);
+            this.terminateChild();
+        }, STARTUP_TIMEOUT_MS);
+    }
+    async stop() {
+        if (this.state === 'idle' || this.state === 'stopped') {
+            this.state = 'stopped';
+            return;
+        }
+        this.stopRequested = true;
+        this.lifecycleEpoch += 1;
+        this.cancelPendingRestart();
+        this.failStart(new Error('ElectronBrowserHost.start: aborted by stop()'));
+        if (!this.child) {
+            this.state = 'stopped';
+            this.emit('stopped');
+            return;
+        }
+        const exited = this.waitForChildExit();
+        await this.gracefulShutdown();
+        await exited;
+        this.state = 'stopped';
+        this.emit('stopped');
+    }
+    async restart(opts) {
+        const next = opts ?? this.lastStartOptions;
+        if (!next) {
+            throw new Error('ElectronBrowserHost.restart: no prior start options to reuse');
+        }
+        this.state = 'restarting';
+        this.emit('restarting');
+        await this.stop();
+        this.stopRequested = false;
+        await this.start(next);
+    }
+    async recover(opts) {
+        const next = opts ?? this.lastStartOptions;
+        if (!next) {
+            throw new Error('ElectronBrowserHost.recover: no prior start options to reuse');
+        }
+        log('recover.enter', `state=${this.state} prevAttempts=${this.restartAttempts} hasTimer=${this.restartTimer !== null}`);
+        if (this.state === 'ready') {
+            log('recover.noop', 'state=ready');
+            return;
+        }
+        if (this.state === 'starting') {
+            log('recover.joinInflight', 'state=starting');
+            return this.startPromise ?? Promise.resolve();
+        }
+        if (this.state === 'restarting' && this.restartTimer === null) {
+            log('recover.joinInflight', 'state=restarting (start in flight)');
+            return this.startPromise ?? Promise.resolve();
+        }
+        if (this.child !== null) {
+            log('recover.awaitChildExit', `state=${this.state} pid=${this.childPid ?? 'none'}`);
+            await this.waitForChildExit();
+            return this.recover(next);
+        }
+        const nowMs = this.now();
+        const sinceLast = nowMs - this.lastRecoverAt;
+        if (this.lastRecoverAt !== 0 && sinceLast < RECOVER_THROTTLE_MS) {
+            const retryInMs = RECOVER_THROTTLE_MS - sinceLast;
+            log('recover.throttled.noop', `retryInMs=${retryInMs} → silent no-op`);
+            return;
+        }
+        this.lastRecoverAt = nowMs;
+        const prevAttempts = this.restartAttempts;
+        this.cancelPendingRestart();
+        this.restartAttempts = 0;
+        this.childStderrTail.length = 0;
+        this.stopRequested = false;
+        log('recover.transition', `prevAttempts=${prevAttempts} → starting`);
+        this.emit('recovering', { prevAttempts });
+        return this.start(next);
+    }
+    async navigate(url, tabId) {
+        log('navigate', `${url}${tabId ? ` tab=${tabId.slice(0, 8)}` : ''}`);
+        this.ensureReady('navigate');
+        if (tabId) {
+            await this.ipc.call('tab.navigate', {
+                id: tabId,
+                url,
+            });
+        }
+        else {
+            await this.ipc.call('view.navigate', { url });
+        }
+        this.url = url;
+    }
+    async setBounds(bounds, sessionId) {
+        log('setBounds', `${bounds.width}x${bounds.height} at (${bounds.x},${bounds.y})${bounds.mobile ? ' mobile' : ''}${sessionId ? ` session=${sessionId.slice(0, 8)}` : ''}`);
+        this.ensureReady('setBounds');
+        await this.ipc.call('view.setBounds', { ...bounds, sessionId });
+        this.viewport = { width: bounds.width, height: bounds.height };
+    }
+    async setTabDeviceProfile(tabId, profile) {
+        log('setTabDeviceProfile', `tab=${tabId.slice(0, 8)} ${profile.formFactor} ${profile.width}x${profile.height}`);
+        this.ensureReady('setTabDeviceProfile');
+        this.tabInfoCache.upsert(tabId, { deviceProfile: profile });
+        await this.ipc.call('tab.setDeviceProfile', {
+            tabId,
+            profile: {
+                formFactor: profile.formFactor,
+                width: profile.width,
+                height: profile.height,
+            },
+        });
+        this.emitTabs();
+    }
+    async forwardInput(ev, sessionId, tabId) {
+        this.ensureReady('forwardInput');
+        const session = sessionId ? { sessionId } : {};
+        this.ipc.notify('input.forward', tabId ? { type: 'browser_input', tabId, data: ev, ...session } : { ...ev, ...session });
+    }
+    async signal(envelope) {
+        log('signal.in', `kind=${envelope.kind} sessionId=${envelope.sessionId.slice(0, 8)}`);
+        this.ensureReady('signal');
+        switch (envelope.kind) {
+            case 'offer':
+                return;
+            case 'answer':
+                await this.ipc.call('webrtc.answer', { sessionId: envelope.sessionId, sdp: envelope.sdp });
+                return;
+            case 'ice':
+                await this.ipc.call('webrtc.ice', { sessionId: envelope.sessionId, candidate: envelope.candidate });
+                return;
+            case 'state':
+                if (envelope.state === 'closed') {
+                    await this.closeCaptureFor(envelope.sessionId);
+                }
+                return;
+        }
+    }
+    async openTab(url) {
+        log('openTab.enter', url);
+        this.ensureReady('openTab');
+        const tab = await this.ipc.call('tab.create', { url });
+        log.info('openTab.created', `id=${tab.id.slice(0, 8)} url=${url}`);
+        this.tabInfoCache.upsert(tab.id, { url });
+        this.currentTabId = tab.id;
+        this.emitTabs();
+        return tab;
+    }
+    async closeTab(id) {
+        log('closeTab', id.slice(0, 8));
+        this.ensureReady('closeTab');
+        await this.ipc.call('tab.close', { id });
+        this.crashedTabs.delete(id);
+        if (this.tabInfoCache.has(id)) {
+            this.tabInfoCache.delete(id);
+            if (this.currentTabId === id) {
+                this.currentTabId = this.pickNextFocused();
+            }
+            this.emitTabs();
+        }
+    }
+    async switchTab(id) {
+        log('switchTab', id.slice(0, 8));
+        this.ensureReady('switchTab');
+        await this.ipc.call('tab.switch', { id });
+        if (this.tabInfoCache.has(id) && this.currentTabId !== id) {
+            this.currentTabId = id;
+            this.emitTabs();
+        }
+    }
+    async switchViewerTab(sessionId, tabId) {
+        log('switchViewerTab', `session=${sessionId.slice(0, 8)} tab=${tabId.slice(0, 8)}`);
+        this.ensureReady('switchViewerTab');
+        await this.ipc.call('webrtc.switchTab', { sessionId, tabId });
+    }
+    async goBack(tabId) {
+        this.ensureReady('goBack');
+        await this.ipc.call('view.back', { tabId });
+    }
+    async goForward(tabId) {
+        this.ensureReady('goForward');
+        await this.ipc.call('view.forward', { tabId });
+    }
+    async reload(tabId) {
+        this.ensureReady('reload');
+        await this.ipc.call('view.reload', { tabId });
+    }
+    async stopLoading(tabId) {
+        this.ensureReady('stopLoading');
+        await this.ipc.call('view.stop', { tabId });
+    }
+    async setIceConfig(iceServers) {
+        log.info('setIceConfig', `servers=${iceServers.length}`);
+        this.ensureReady('setIceConfig');
+        await this.ipc.call('webrtc.setConfig', { iceServers });
+    }
+    async startCapture(sessionId, tabId) {
+        log.info('startCapture', `session=${sessionId.slice(0, 8)} tab=${tabId.slice(0, 8)} state=${this.state}`);
+        this.ensureReady('startCapture');
+        await this.ipc.call('webrtc.offer', { sessionId, tabId });
+    }
+    async closeCaptureFor(sessionId) {
+        log.info('closeCaptureFor', `session=${sessionId.slice(0, 8)} state=${this.state}`);
+        if (this.state !== 'ready' || !this.ipc)
+            return;
+        try {
+            await this.ipc.call('webrtc.closeOne', { sessionId });
+        }
+        catch (err) {
+            log.warn('closeCaptureFor.err', err instanceof Error ? err.message : String(err));
+        }
+    }
+    async leaseTab(req) {
+        this.ensureReady('leaseTab');
+        const tabId = this.resolveAgentTabId(req.tabId);
+        return this.ipc.call('agent.tab.lease', tabId === req.tabId ? req : { ...req, tabId });
+    }
+    async releaseTab(req) {
+        this.ensureReady('releaseTab');
+        const tabId = this.resolveAgentTabId(req.tabId);
+        return this.ipc.call('agent.tab.release', tabId === req.tabId ? req : { ...req, tabId });
+    }
+    async heartbeat(req) {
+        this.ensureReady('heartbeat');
+        const tabIds = req.tabIds.map((id) => this.resolveAgentTabId(id));
+        const changed = tabIds.some((id, i) => id !== req.tabIds[i]);
+        return this.ipc.call('agent.tab.heartbeat', changed ? { ...req, tabIds } : req);
+    }
+    async listLeases(filter) {
+        this.ensureReady('listLeases');
+        return this.ipc.call('agent.tab.list', filter);
+    }
+    async releasePlan(planId) {
+        this.ensureReady('releasePlan');
+        return this.ipc.call('agent.plan.release', { planId });
+    }
+    getTabInfo(tabId) {
+        return this.tabInfoCache.get(tabId);
+    }
+    buildDomSurface() {
+        const call = async (method, params, opts) => {
+            this.ensureReady(`dom.${method.slice(4)}`);
+            const tabId = this.resolveAgentTabId(params.tabId);
+            return this.ipc.call(method, tabId === params.tabId ? params : { ...params, tabId }, opts);
+        };
+        return {
+            snapshot: (args) => call('dom.snapshot', args),
+            click: (args) => call('dom.click', args),
+            type: (args) => call('dom.type', args),
+            hover: (args) => call('dom.hover', args),
+            pressKey: (args) => call('dom.press_key', args),
+            selectOption: (args) => call('dom.select_option', args),
+            fillForm: (args) => call('dom.fill_form', args),
+            dragDrop: (args) => call('dom.drag_drop', args),
+            fileUpload: (args) => call('dom.file_upload', args),
+            handleDialog: (args) => call('dom.handle_dialog', args),
+            waitFor: (args) => call('dom.wait_for', args, ipcDeadlineFor(args.timeoutMs)),
+            screenshot: (args) => call('dom.screenshot', args),
+            console: (args) => call('dom.console', args),
+            network: (args) => call('dom.network', args),
+        };
+    }
+    buildJsSurface() {
+        return {
+            evaluate: async (args) => {
+                this.ensureReady('js.evaluate');
+                const tabId = this.resolveAgentTabId(args.tabId);
+                return this.ipc.call('js.evaluate', tabId === args.tabId ? args : { ...args, tabId }, ipcDeadlineFor(args.timeoutMs));
+            },
+        };
+    }
+    buildSdkSurface() {
+        return {
+            deliver: async (args) => {
+                this.ensureReady('sdk.deliver');
+                await this.ipc.call('sdk.deliver', args);
+            },
+        };
+    }
+    getStatus() {
+        return {
+            state: this.state,
+            url: this.url,
+            viewport: this.viewport,
+            ...(this.state === 'crashed' && this.lastCrashReason
+                ? { reason: this.lastCrashReason }
+                : {}),
+        };
+    }
+    isReady() {
+        return this.state === 'ready';
+    }
+    getState() {
+        return this.state;
+    }
+    spawnChild() {
+        const xvfb = this.xvfbSupervisor.start((err) => this.emit('error', err));
+        const envOverrides = childEnvOverrides({
+            platform: this.platform,
+            env: this.env,
+            xvfbDisplayNumber: xvfb.displayNumber,
+            sdkStubPath: resolveSdkStubPath(),
+            audioSinkOverrides: this.pipewireSinkSupervisor.envOverrides(),
+        });
+        const sandbox = this.sandboxPolicy.decide();
+        if (sandbox.reason === 'auto-root')
+            console.warn(`[ElectronBrowserHost] ${sandbox.detail}`);
+        const chromiumFlags = chromiumLaunchFlags({
+            platform: this.platform,
+            env: this.env,
+            xvfbDisplayNumber: xvfb.displayNumber,
+            sandboxEnabled: sandbox.enabled,
+        });
+        const binary = this.resolvedElectronBinary;
+        if (binary === null) {
+            throw new Error('ElectronBrowserHost.spawnChild: no Electron binary resolved — start() runs the preconditions first');
+        }
+        const exec = withoutCoreDumps(this.platform, binary, [this.resolvedAppDir, '--minionry-host', ...chromiumFlags]);
+        const child = this.spawnFn(exec.command, exec.args, {
+            cwd: this.resolvedAppDir,
+            stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
+            env: buildChildEnv(this.env, envOverrides),
+            detached: false,
+            windowsHide: true,
+        });
+        child.once('error', (err) => {
+            if (this.child === child)
+                this.onChildError(err);
+        });
+        this.child = child;
+        this.childPid = typeof child.pid === 'number' ? child.pid : null;
+        this.childExited = false;
+        this.helloSeen = false;
+        this.childFailure = null;
+        this.childStderrTail.length = 0;
+        if (this.childPid === null) {
+            log.warn('spawn.noPid', `binary=${binary} — awaiting the spawn error event`);
+            return;
+        }
+        log.info('spawn', `pid=${child.pid} binary=${binary} via=${exec.command === binary ? 'direct' : exec.command} appDir=${this.resolvedAppDir} flags=[${chromiumFlags.join(' ')}] xvfb=${xvfb.displayNumber ?? 'none'} sandbox=${sandbox.reason}`);
+        this.wireChildStdio(child);
+        if (this.ipcClientFactory) {
+            const readFromChild = child.stdio[4];
+            const writeToChild = child.stdio[3];
+            if (!readFromChild || !writeToChild) {
+                throw new Error('Electron child did not expose the expected fd3/fd4 RPC pipes');
+            }
+            const ipc = this.ipcClientFactory({
+                readFromChild,
+                writeToChild,
+                onFatal: (err) => {
+                    if (this.child !== child)
+                        return;
+                    log.error('ipc.unreadable', err);
+                    this.childFailure = `the RPC stream from the browser process became unreadable (${err.message})`;
+                    this.terminateChild();
+                },
+            });
+            this.ipc = ipc;
+            this.subscribeIpcEvents(ipc);
+        }
+    }
+    wireChildStdio(child) {
+        child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString('utf8').trimEnd();
+            if (text)
+                console.log(`[electron-host] ${text}`);
+        });
+        child.stderr?.on('data', (chunk) => this.onChildStderr(child, chunk));
+        child.once('exit', (code, signal) => {
+            if (this.child !== child) {
+                log.warn('child.staleExit', `pid=${child.pid ?? 'none'} code=${code} signal=${signal}`);
+                return;
+            }
+            this.childExited = true;
+            this.onChildExit(code, signal);
+        });
+    }
+    onChildStderr(child, chunk) {
+        const debug = this.env.MINIONRY_BROWSER_DEBUG === '1';
+        const lines = chunk
+            .toString('utf8')
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && shouldForwardStderrLine(line, { debug }));
+        if (lines.length === 0)
+            return;
+        console.error(`[electron-host err] ${lines.join('\n')}`);
+        if (this.child !== child)
+            return;
+        this.childStderrTail.push(...lines);
+        this.childStderrTail.splice(0, Math.max(0, this.childStderrTail.length - STDERR_TAIL_LINES));
+    }
+    subscribeIpcEvents(ipc) {
+        ipc.on('host.hello', () => this.onChildHello());
+        ipc.on('host.capture_ready', () => this.onCaptureReady());
+        ipc.on('status.change', (payload) => this.onStatusChangeIpc(payload));
+        ipc.on('webrtc.offer', (payload) => this.relayOutboundSignal('offer', payload));
+        ipc.on('webrtc.ice', (payload) => this.relayOutboundSignal('ice', payload));
+        ipc.on('webrtc.state', (payload) => this.relayOutboundSignal('state', payload));
+        ipc.on('lease.expired', (payload) => this.onLeaseExpired(payload));
+        ipc.on('tab.created', (payload) => this.onTabCreatedIpc(payload));
+        ipc.on('tab.navigated', (payload) => this.onTabNavigatedIpc(payload));
+        ipc.on('tab.failed', (payload) => this.onTabFailedIpc(payload));
+        ipc.on('tab.titleChanged', (payload) => this.onTabTitleChangedIpc(payload));
+        ipc.on('tab.closed', (payload) => this.onTabClosedIpc(payload));
+        ipc.on('tab.crashed', (payload) => this.onTabCrashedIpc(payload));
+        ipc.on('browser.inputFocus', (payload) => this.onInputFocusIpc(payload));
+        ipc.on('sdk.request', (payload) => this.onSdkRequestIpc(payload));
+    }
+    onChildHello() {
+        log.info('childHello', `state=${this.state} pid=${this.childPid ?? 'none'}`);
+        this.helloSeen = true;
+        if (this.state !== 'starting' && this.state !== 'restarting')
+            return;
+        if (this.startTimer) {
+            this.clearTimeoutFn(this.startTimer);
+            this.startTimer = null;
+        }
+        this.state = 'ready';
+        this.restartAttempts = 0;
+        this.lastCrashReason = null;
+        this.emit('ready');
+        this.startResolve?.();
+        this.startResolve = null;
+        this.startReject = null;
+    }
+    onCaptureReady() {
+        log.info('captureReady', `state=${this.state}`);
+    }
+    onStatusChangeIpc(payload) {
+        if (!payload || typeof payload !== 'object')
+            return;
+        const obj = payload;
+        const state = typeof obj.state === 'string' ? obj.state : String(obj.state);
+        const reason = typeof obj.reason === 'string' ? obj.reason : undefined;
+        if (state === 'controller_crashed') {
+            this.childFailure = `capture controller failed: ${reason ?? 'no reason given'}`;
+            log.error('child.status', `state=${state} reason=${reason ?? '-'} — the child is exiting`);
+            return;
+        }
+        if (reason)
+            log.info('child.status', `state=${state} reason=${reason}`);
+        else
+            log('child.status', `state=${state}`);
+    }
+    onTabCrashedIpc(payload) {
+        if (!payload || typeof payload !== 'object')
+            return;
+        const obj = payload;
+        const tabId = typeof obj.tabId === 'string' ? obj.tabId : null;
+        if (!tabId)
+            return;
+        const reason = typeof obj.reason === 'string' ? obj.reason : 'unknown';
+        const willRestart = obj.willRestart === true;
+        log.info('ipc.tabCrashed', `id=${tabId.slice(0, 8)} reason=${reason} willRestart=${willRestart}`);
+        if (willRestart || !this.tabInfoCache.has(tabId))
+            return;
+        this.crashedTabs.set(tabId, `This tab crashed (${reason}) and was not restarted. Reload it to try again.`);
+        this.emitTabs();
+    }
+    relayOutboundSignal(kind, payload) {
+        const signal = readOutboundSignal(kind, payload);
+        if (!signal)
+            return;
+        const { obj, sessionId } = signal;
+        const stateDetail = kind === 'state' ? describeControllerState(obj) : '';
+        (kind === 'ice' ? log : log.info)('signal.out', `kind=${kind} session=${sessionId.slice(0, 8)}${stateDetail}`);
+        switch (kind) {
+            case 'offer':
+            case 'answer': {
+                const sdp = typeof obj.sdp === 'string' ? obj.sdp : null;
+                if (!sdp) {
+                    log.error('signal.out.noSdp', `kind=${kind} session=${sessionId.slice(0, 8)} — dropped`);
+                    return;
+                }
+                this.emit('signal', { kind, sessionId, sdp });
+                return;
+            }
+            case 'ice': {
+                const candidate = extractCandidate(obj.candidate);
+                this.emit('signal', { kind, sessionId, candidate });
+                return;
+            }
+            case 'state': {
+                const state = obj.state;
+                if (state !== 'negotiating' &&
+                    state !== 'connected' &&
+                    state !== 'failed' &&
+                    state !== 'closed') {
+                    log.error('signal.out.badState', `session=${sessionId.slice(0, 8)} state=${String(state)} — dropped`);
+                    return;
+                }
+                const reason = typeof obj.reason === 'string' ? obj.reason : undefined;
+                const selectedCandidateType = readSelectedCandidateType(obj.selectedCandidateType);
+                this.emit('signal', {
+                    kind,
+                    sessionId,
+                    state,
+                    reason,
+                    ...(selectedCandidateType !== undefined ? { selectedCandidateType } : {}),
+                });
+                return;
+            }
+        }
+    }
+    onLeaseExpired(payload) {
+        const event = extractLeaseExpired(payload);
+        if (event === null)
+            return;
+        this.emit('leaseExpired', event);
+    }
+    onInputFocusIpc(payload) {
+        if (!payload || typeof payload !== 'object')
+            return;
+        const obj = payload;
+        if (typeof obj.sessionId !== 'string' || typeof obj.focused !== 'boolean') {
+            return;
+        }
+        this.emit('inputFocus', {
+            sessionId: obj.sessionId,
+            ...(typeof obj.tabId === 'string' ? { tabId: obj.tabId } : {}),
+            focused: obj.focused,
+        });
+    }
+    onSdkRequestIpc(payload) {
+        if (!payload || typeof payload !== 'object')
+            return;
+        const obj = payload;
+        if (typeof obj.pageId !== 'number' ||
+            typeof obj.tabId !== 'string' ||
+            typeof obj.sessionId !== 'string' ||
+            typeof obj.origin !== 'string' ||
+            obj.origin === '' ||
+            typeof obj.payload !== 'string') {
+            log.warn('sdk.request.malformed', 'dropped an sdk.request IPC payload with missing/invalid fields');
+            return;
+        }
+        const event = {
+            pageId: obj.pageId,
+            tabId: obj.tabId,
+            sessionId: obj.sessionId,
+            origin: obj.origin,
+            payload: obj.payload,
+        };
+        this.emit('sdkRequest', event);
+    }
+    onTabCreatedIpc(payload) {
+        if (!payload || typeof payload !== 'object')
+            return;
+        const obj = payload;
+        const id = typeof obj.id === 'string' ? obj.id : null;
+        if (!id)
+            return;
+        const url = typeof obj.url === 'string' ? obj.url : '';
+        const isNew = !this.tabInfoCache.has(id);
+        log('ipc.tabCreated', `id=${id.slice(0, 8)} url=${url} isNew=${isNew}`);
+        this.tabInfoCache.upsert(id, { url, title: '' });
+        if (isNew) {
+            if (this.currentTabId === null)
+                this.currentTabId = id;
+            this.emitTabs();
+        }
+    }
+    onTabNavigatedIpc(payload) {
+        if (!payload || typeof payload !== 'object')
+            return;
+        const obj = payload;
+        const tabId = typeof obj.tabId === 'string' ? obj.tabId : null;
+        const url = typeof obj.url === 'string' ? obj.url : null;
+        if (!tabId || url === null)
+            return;
+        const canGoBack = obj.canGoBack === true;
+        const canGoForward = obj.canGoForward === true;
+        log('ipc.tabNavigated', `id=${tabId.slice(0, 8)} url=${url} back=${canGoBack} fwd=${canGoForward}`);
+        const recovered = this.crashedTabs.delete(tabId);
+        const prev = this.tabInfoCache.get(tabId);
+        if (!recovered && prev?.url === url && prev?.canGoBack === canGoBack && prev?.canGoForward === canGoForward) {
+            return;
+        }
+        this.tabInfoCache.upsert(tabId, { url, canGoBack, canGoForward });
+        this.emitTabs();
+    }
+    onTabFailedIpc(payload) {
+        if (!payload || typeof payload !== 'object')
+            return;
+        const obj = payload;
+        const tabId = typeof obj.tabId === 'string' ? obj.tabId : null;
+        const url = typeof obj.url === 'string' ? obj.url : null;
+        if (!tabId || url === null)
+            return;
+        const errorCode = typeof obj.errorCode === 'number' ? obj.errorCode : 0;
+        log('ipc.tabFailed', `id=${tabId.slice(0, 8)} url=${url} code=${errorCode}`);
+        if (!this.tabInfoCache.has(tabId))
+            return;
+        const prev = this.tabInfoCache.get(tabId);
+        if (prev?.url === url)
+            return;
+        this.tabInfoCache.upsert(tabId, { url });
+        this.emitTabs();
+    }
+    onTabTitleChangedIpc(payload) {
+        if (!payload || typeof payload !== 'object')
+            return;
+        const obj = payload;
+        const tabId = typeof obj.tabId === 'string' ? obj.tabId : null;
+        const title = typeof obj.title === 'string' ? obj.title : null;
+        if (!tabId || title === null)
+            return;
+        log('ipc.tabTitle', `id=${tabId.slice(0, 8)} title="${title}"`);
+        const prev = this.tabInfoCache.get(tabId);
+        if (prev?.title === title)
+            return;
+        this.tabInfoCache.upsert(tabId, { title });
+        this.emitTabs();
+    }
+    onTabClosedIpc(payload) {
+        if (!payload || typeof payload !== 'object')
+            return;
+        const obj = payload;
+        const id = typeof obj.id === 'string' ? obj.id : null;
+        if (!id)
+            return;
+        log('ipc.tabClosed', `id=${id.slice(0, 8)} cached=${this.tabInfoCache.has(id)}`);
+        this.crashedTabs.delete(id);
+        if (!this.tabInfoCache.has(id))
+            return;
+        this.tabInfoCache.delete(id);
+        if (this.currentTabId === id) {
+            this.currentTabId = this.pickNextFocused();
+        }
+        this.emitTabs();
+    }
+    buildTabsSnapshot() {
+        const entries = this.tabInfoCache.entries();
+        const tabs = entries.map((e) => {
+            const crashed = this.crashedTabs.get(e.id);
+            return {
+                id: e.id,
+                url: e.url,
+                title: e.title,
+                ...(e.faviconUrl !== undefined ? { favicon: e.faviconUrl } : {}),
+                isLoading: false,
+                canGoBack: e.canGoBack ?? false,
+                canGoForward: e.canGoForward ?? false,
+                ...(e.deviceProfile !== undefined ? { deviceProfile: e.deviceProfile } : {}),
+                ...(crashed !== undefined ? { error: crashed } : {}),
+            };
+        });
+        const focused = this.currentTabId && this.tabInfoCache.has(this.currentTabId)
+            ? this.currentTabId
+            : null;
+        return { tabs, currentTabId: focused };
+    }
+    emitTabs() {
+        const snapshot = this.buildTabsSnapshot();
+        log('emitTabs', `count=${snapshot.tabs.length} current=${this.currentTabId?.slice(0, 8) ?? 'null'}`);
+        this.emit('tabs', snapshot);
+    }
+    getTabsSnapshot() {
+        return this.buildTabsSnapshot();
+    }
+    pickNextFocused() {
+        const entries = this.tabInfoCache.entries();
+        return entries[0]?.id ?? null;
+    }
+    resolveAgentTabId(tabId) {
+        if (this.tabInfoCache.has(tabId))
+            return tabId;
+        const aliased = this.agentTabAliases.get(tabId);
+        if (aliased && this.tabInfoCache.has(aliased))
+            return aliased;
+        const current = this.currentTabId;
+        if (current && this.tabInfoCache.has(current)) {
+            log('resolveAgentTabId.adopt', `unknown=${tabId.slice(0, 8)} -> current=${current.slice(0, 8)}`);
+            this.agentTabAliases.set(tabId, current);
+            return current;
+        }
+        return tabId;
+    }
+    onChildError(err) {
+        if (this.childPid === null) {
+            const reason = `spawn failed — ${describeSpawnError(err, this.resolvedElectronBinary ?? 'electron', this.resolvedAppDir)}`;
+            this.releaseChild();
+            this.transitionToCrashed(null, null, reason, { permanent: true });
+            return;
+        }
+        this.childFailure = `spawn error: ${err.message}`;
+        this.terminateChild();
+    }
+    onChildExit(code, signal) {
+        const wasIntentional = this.stopRequested;
+        const failure = this.childFailure;
+        this.childFailure = null;
+        this.releaseChild();
+        if (wasIntentional) {
+            return;
+        }
+        const exit = signal ? `child terminated by ${signal}` : `child exited with code ${code ?? 'unknown'}`;
+        this.transitionToCrashed(code, signal, failure ? `${exit} — ${failure}` : exit);
+    }
+    transitionToCrashed(code, signal, reason, opts = {}) {
+        if (this.state === 'stopped' || this.stopRequested)
+            return;
+        const verdict = classifyCrash(reason, this.childStderrTail);
+        let remedy = verdict.hint;
+        let retryUnsandboxed = false;
+        if (verdict.sandboxFailure !== null && !this.helloSeen) {
+            const failure = this.sandboxPolicy.recordFailure(verdict.sandboxFailure);
+            if (failure.fallBack && this.state === 'starting' && this.child === null && this.lastStartOptions) {
+                this.relaunchWithoutSandbox(this.lastStartOptions.orchestraId, reason, failure.notice);
+                return;
+            }
+            remedy = failure.notice;
+            if (failure.fallBack && this.child === null)
+                retryUnsandboxed = true;
+        }
+        const permanent = opts.permanent === true || (verdict.permanent && !retryUnsandboxed);
+        const tail = this.childStderrTail.length > 0
+            ? ` — last stderr: ${this.childStderrTail.join(' | ')}`
+            : '';
+        const hint = remedy ? ` — ${remedy}` : '';
+        const fullReason = `${reason}${tail}${hint}`;
+        log.error('crashed', `prevState=${this.state} code=${code} signal=${signal} permanent=${permanent} reason=${fullReason}`);
+        this.state = 'crashed';
+        this.lastCrashReason = fullReason;
+        this.emit('crashed', { code, signal, reason: fullReason });
+        this.failStart(new Error(`ElectronBrowserHost: ${fullReason}`));
+        if (permanent) {
+            console.error(`[ElectronBrowserHost] not retrying — the failure is not transient: ${fullReason}`);
+            return;
+        }
+        this.scheduleRestartIfBudgetRemains();
+    }
+    relaunchWithoutSandbox(orchestraId, reason, notice) {
+        const tail = this.childStderrTail.length > 0
+            ? ` — last stderr: ${this.childStderrTail.join(' | ')}`
+            : '';
+        log.warn('sandbox.fallback', `${reason}${tail}`);
+        console.warn(`[ElectronBrowserHost] ${notice}`);
+        this.childStderrTail.length = 0;
+        const epoch = this.lifecycleEpoch;
+        void this.sidecarRelease.then(() => {
+            if (epoch !== this.lifecycleEpoch ||
+                this.stopRequested ||
+                this.state !== 'starting' ||
+                this.child !== null) {
+                return;
+            }
+            try {
+                this.launch(orchestraId);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                this.releaseChild();
+                this.transitionToCrashed(null, null, `sandbox fallback relaunch failed — ${message}`, { permanent: true });
+            }
+        });
+    }
+    scheduleRestartIfBudgetRemains() {
+        if (!this.lastStartOptions)
+            return;
+        if (this.restartAttempts >= MAX_RESTARTS) {
+            console.error(`[ElectronBrowserHost] restart budget exhausted (attempts=${this.restartAttempts}); host stays crashed`);
+            return;
+        }
+        const delay = RESTART_BACKOFFS_MS[this.restartAttempts] ?? RESTART_BACKOFFS_MS.at(-1) ?? 1_000;
+        this.restartAttempts += 1;
+        console.warn(`[ElectronBrowserHost] scheduling restart attempt ${this.restartAttempts}/${MAX_RESTARTS} in ${delay}ms`);
+        this.state = 'restarting';
+        this.emit('restarting');
+        this.cancelPendingRestart();
+        this.restartTimer = this.setTimeoutFn(() => {
+            this.restartTimer = null;
+            if (this.stopRequested)
+                return;
+            void this.start(this.lastStartOptions).catch(() => {
+            });
+        }, delay);
+    }
+    cancelPendingRestart() {
+        if (this.restartTimer) {
+            this.clearTimeoutFn(this.restartTimer);
+            this.restartTimer = null;
+        }
+    }
+    async gracefulShutdown() {
+        if (!this.child)
+            return;
+        const ipc = this.ipc;
+        try {
+            if (ipc) {
+                await Promise.race([
+                    ipc.call('host.shutdown', undefined),
+                    this.delay(SIGTERM_GRACE_MS),
+                ]);
+            }
+        }
+        catch {
+        }
+        if (!this.childExited && this.childPid !== null) {
+            this.killChild('SIGTERM');
+            await Promise.race([this.waitForChildExit(), this.delay(SIGTERM_GRACE_MS)]);
+            if (!this.childExited) {
+                this.killChild('SIGKILL');
+            }
+        }
+        try {
+            await ipc?.close();
+        }
+        catch {
+        }
+    }
+    killChild(signal) {
+        if (!this.child)
+            return;
+        try {
+            this.child.kill(signal);
+        }
+        catch {
+        }
+    }
+    terminateChild() {
+        const child = this.child;
+        if (!child)
+            return;
+        this.killChild('SIGTERM');
+        const escalation = this.setTimeoutFn(() => {
+            if (this.child !== child)
+                return;
+            log.warn('child.sigkill', `pid=${child.pid ?? 'none'} — still alive ${SIGTERM_GRACE_MS}ms after SIGTERM`);
+            this.killChild('SIGKILL');
+        }, SIGTERM_GRACE_MS);
+        child.once('exit', () => this.clearTimeoutFn(escalation));
+    }
+    waitForChildExit() {
+        if (!this.child)
+            return Promise.resolve();
+        return new Promise((res) => {
+            this.child.once('exit', () => res());
+        });
+    }
+    releaseChild() {
+        if (this.startTimer) {
+            this.clearTimeoutFn(this.startTimer);
+            this.startTimer = null;
+        }
+        this.child = null;
+        this.childPid = null;
+        const ipc = this.ipc;
+        this.ipc = null;
+        void ipc?.close().catch(() => undefined);
+        this.sidecarRelease = Promise.allSettled([
+            this.xvfbSupervisor.stop(),
+            this.pipewireSinkSupervisor.stop(),
+        ]).then(() => undefined);
+        const hadTabs = this.tabInfoCache.entries().length > 0;
+        this.tabInfoCache.clear();
+        this.crashedTabs.clear();
+        this.currentTabId = null;
+        this.agentTabAliases.clear();
+        if (hadTabs)
+            this.emitTabs();
+    }
+    failStart(err) {
+        if (this.startTimer) {
+            this.clearTimeoutFn(this.startTimer);
+            this.startTimer = null;
+        }
+        if (this.startReject) {
+            this.startReject(err);
+            this.startResolve = null;
+            this.startReject = null;
+        }
+    }
+    ensureReady(op) {
+        if (this.state !== 'ready') {
+            throw new Error(`ElectronBrowserHost.${op}: host is not ready (state=${this.state})`);
+        }
+        if (!this.ipc) {
+            throw new Error(`ElectronBrowserHost.${op}: no IPC client configured — wire ipcClientFactory (IS-018)`);
+        }
+    }
+    delay(ms) {
+        return new Promise((res) => this.setTimeoutFn(res, ms));
+    }
+}
+export const BrowserHostService = ElectronBrowserHost;
+export { MockBrowserHost } from './host-mock.js';