pi-agent-browser-native 0.9.3 → 0.9.5

package/dist/extensions/agent-browser/lib/electron/launch.js

@@ -1,63 +1,52 @@
-import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { open, readFile, rm } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fetchCdpJson, parseCdpTargets, parseCdpVersion, } from "./cdp.js";
+import { rm } from "node:fs/promises";
 import { discoverElectronApps, inspectElectronAppPath, inspectElectronExecutablePath, } from "./discovery.js";
 import { createSecureTempDirectory, preserveSecureTempDirectory } from "../temp.js";
-export const ELECTRON_LAUNCH_RECORD_VERSION = 1;
-const ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS = 15_000;
-const ELECTRON_LAUNCH_MAX_TIMEOUT_MS = 120_000;
-const DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
-export const ELECTRON_PROFILE_DIR_PREFIX = "electron-profile-";
-const ELECTRON_DEFAULT_APP_ARGS = ["--disable-extensions", "--no-first-run", "--no-default-browser-check"];
-const ELECTRON_DEVTOOLS_POLL_INTERVAL_MS = 100;
-// ponytail: bound failure reads, not lifetime log growth; noisy long-lived apps need rotation if that becomes a problem.
-const ELECTRON_OUTPUT_TAIL_BYTES = 4096;
+import { stringifyUnknown } from "../results/text.js";
+import { readProcessStartIdentity } from "../process-identity.js";
+import { isElectronLaunchAborted, pollCdpMetadata, pollDevToolsActivePort, } from "./launch-monitor.js";
+import { ElectronLaunchProcess } from "./launch-process.js";
+import { ELECTRON_LAUNCH_RECORD_VERSION, ELECTRON_PROFILE_DIR_PREFIX, } from "./launch-types.js";
+export { ELECTRON_LAUNCH_RECORD_VERSION, ELECTRON_PROFILE_DIR_PREFIX } from "./launch-types.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_TIMEOUT_MS = 120_000;
+const DEFAULT_APP_ARGS = ["--disable-extensions", "--no-first-run", "--no-default-browser-check"];
 function normalizeTimeoutMs(timeoutMs) {
-    if (!Number.isSafeInteger(timeoutMs) || (timeoutMs ?? 0) <= 0)
-        return ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS;
-    return Math.min(timeoutMs, ELECTRON_LAUNCH_MAX_TIMEOUT_MS);
-}
-function sleep(ms, signal) {
-    if (signal?.aborted)
-        return Promise.resolve();
-    return new Promise((resolve) => {
-        const timer = setTimeout(done, ms);
-        function done() {
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", done);
-            resolve();
-        }
-        signal?.addEventListener("abort", done, { once: true });
-    });
+    if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+        return DEFAULT_TIMEOUT_MS;
+    }
+    return Math.min(timeoutMs, MAX_TIMEOUT_MS);
 }
 function normalizeIdentifier(value) {
     const trimmed = value?.trim().toLowerCase();
-    return trimmed && trimmed.length > 0 ? trimmed : undefined;
-}
-function appIdentifiers(app) {
-    return [app.name, app.bundleId, app.desktopId, app.appPath, app.executablePath]
-        .filter((value) => typeof value === "string" && value.trim().length > 0);
+    return trimmed !== undefined && trimmed.length > 0 ? trimmed : undefined;
 }
 function policyEntryMatchesApp(entry, app) {
-    const normalizedEntry = normalizeIdentifier(entry);
-    if (!normalizedEntry)
+    const normalized = normalizeIdentifier(entry);
+    if (normalized === undefined) {
         return false;
-    return appIdentifiers(app).some((identifier) => identifier.toLowerCase().includes(normalizedEntry));
+    }
+    const identifiers = [
+        app.name,
+        app.bundleId,
+        app.desktopId,
+        app.appPath,
+        app.executablePath,
+    ].filter((value) => typeof value === "string" && value.trim().length > 0);
+    return identifiers.some((identifier) => identifier.toLowerCase().includes(normalized));
 }
-function evaluateElectronLaunchPolicy(options) {
-    const denyEntry = options.deny?.find((entry) => policyEntryMatchesApp(entry, options.target));
-    if (denyEntry) {
+function evaluateLaunchPolicy(options, target) {
+    const denyEntry = options.deny?.find((entry) => policyEntryMatchesApp(entry, target));
+    if (denyEntry !== undefined && denyEntry.length > 0) {
         return {
             entry: denyEntry,
             list: "deny",
             message: `Electron launch blocked by caller deny policy: ${denyEntry}`,
         };
     }
-    if (options.allow && options.allow.length > 0) {
-        const allowEntry = options.allow.find((entry) => policyEntryMatchesApp(entry, options.target));
-        if (!allowEntry) {
+    if (options.allow !== undefined && options.allow.length > 0) {
+        const allowEntry = options.allow.find((entry) => policyEntryMatchesApp(entry, target));
+        if (allowEntry === undefined || allowEntry.length === 0) {
             return {
                 list: "allow",
                 message: "Electron launch blocked because the resolved app did not match caller allow policy.",
@@ -66,157 +55,38 @@ function evaluateElectronLaunchPolicy(options) {
     }
     return undefined;
 }
-async function resolveElectronLaunchTarget(options) {
-    if (options.appPath)
+async function resolveLaunchTarget(options) {
+    if (options.appPath !== undefined && options.appPath.length > 0) {
         return inspectElectronAppPath(options.appPath);
-    if (options.executablePath)
-        return inspectElectronExecutablePath(options.executablePath);
-    const query = options.bundleId ?? options.appName;
-    const discovery = await discoverElectronApps({ maxResults: 200, query });
-    if (options.bundleId) {
-        const normalizedBundleId = normalizeIdentifier(options.bundleId);
-        return discovery.apps.find((app) => normalizeIdentifier(app.bundleId) === normalizedBundleId);
-    }
-    if (options.appName) {
-        const normalizedName = normalizeIdentifier(options.appName);
-        return discovery.apps.find((app) => normalizeIdentifier(app.name) === normalizedName) ?? discovery.apps[0];
-    }
-    return undefined;
-}
-function targetMatchesType(target, targetType) {
-    return targetType === undefined || targetType === "any" || target.type === targetType;
-}
-function selectElectronConnectArg(options) {
-    const targetWebSocket = options.targets.find((target) => targetMatchesType(target, options.targetType) && target.webSocketDebuggerUrl)?.webSocketDebuggerUrl;
-    return targetWebSocket ?? options.version.webSocketDebuggerUrl ?? String(options.port);
-}
-async function readDevToolsActivePort(userDataDir) {
-    const path = `${userDataDir}/${DEVTOOLS_ACTIVE_PORT_FILE}`;
-    try {
-        const text = await readFile(path, "utf8");
-        const [portLine] = text.split(/\r?\n/);
-        const port = Number(portLine?.trim());
-        return {
-            found: true,
-            path,
-            port: Number.isSafeInteger(port) && port > 0 && port <= 65_535 ? port : undefined,
-            ...(Number.isSafeInteger(port) && port > 0 && port <= 65_535 ? {} : { error: "DevToolsActivePort did not contain a valid TCP port." }),
-        };
     }
-    catch (error) {
-        const code = error.code;
-        return {
-            error: code && code !== "ENOENT" ? `${code}: ${error instanceof Error ? error.message : String(error)}` : undefined,
-            found: false,
-            path,
-        };
-    }
-}
-async function pollDevToolsActivePort(options) {
-    let devToolsActivePort;
-    while (Date.now() <= options.deadlineMs) {
-        if (options.signal?.aborted)
-            return { devToolsActivePort, failure: "aborted" };
-        const spawnError = options.getSpawnError();
-        if (spawnError)
-            return { devToolsActivePort, failure: "spawn-error", spawnError };
-        devToolsActivePort = await readDevToolsActivePort(options.userDataDir);
-        if (devToolsActivePort.port)
-            return { devToolsActivePort, port: devToolsActivePort.port };
-        const exit = options.getChildExit();
-        if (exit.code !== null || exit.signal !== null) {
-            return { devToolsActivePort, failure: exit.code === 0 ? "single-instance-conflict" : "spawn-error" };
-        }
-        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS, options.signal);
-    }
-    return { devToolsActivePort, failure: "timeout" };
-}
-async function pollCdpMetadata(port, deadlineMs, signal) {
-    while (Date.now() <= deadlineMs) {
-        if (signal?.aborted)
-            return { aborted: true };
-        const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`, signal));
-        if (signal?.aborted)
-            return { aborted: true };
-        if (version) {
-            const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`, signal));
-            return signal?.aborted ? { aborted: true } : { aborted: false, metadata: { targets, version } };
-        }
-        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS, signal);
-    }
-    return { aborted: false };
-}
-function buildLaunchArgs(userDataDir, appArgs) {
-    return [
-        ...appArgs,
-        `--user-data-dir=${userDataDir}`,
-        "--remote-debugging-port=0",
-        ...ELECTRON_DEFAULT_APP_ARGS,
-    ];
-}
-async function waitForLaunchChildExit(child, deadlineMs) {
-    while (Date.now() <= deadlineMs) {
-        if (child.exitCode !== null || child.signalCode !== null)
-            return true;
-        await sleep(50);
+    if (options.executablePath !== undefined && options.executablePath.length > 0) {
+        return inspectElectronExecutablePath(options.executablePath);
     }
-    return child.exitCode !== null || child.signalCode !== null;
+    const discovery = await discoverElectronApps({
+        maxResults: 200,
+        query: options.bundleId ?? options.appName,
+    });
+    return selectDiscoveredTarget(discovery.apps, options);
 }
-function isLaunchChildPidAlive(child) {
-    if (!child.pid)
-        return undefined;
-    if (child.exitCode !== null || child.signalCode !== null)
-        return false;
-    try {
-        process.kill(child.pid, 0);
-        return true;
+function selectDiscoveredTarget(apps, options) {
+    if ((options.bundleId ?? "").length > 0) {
+        const bundleId = normalizeIdentifier(options.bundleId);
+        return apps.find((app) => normalizeIdentifier(app.bundleId) === bundleId);
     }
-    catch (error) {
-        return error.code === "EPERM";
+    if ((options.appName ?? "").length > 0) {
+        const name = normalizeIdentifier(options.appName);
+        return apps.find((app) => normalizeIdentifier(app.name) === name) ?? apps.at(0);
     }
+    return undefined;
 }
-async function terminateLaunchChild(child) {
-    if (!child.pid || child.exitCode !== null || child.signalCode !== null)
-        return undefined;
-    try {
-        child.kill("SIGTERM");
-    }
-    catch (error) {
-        return error instanceof Error ? error.message : String(error);
-    }
-    if (await waitForLaunchChildExit(child, Date.now() + 1_000))
-        return undefined;
-    try {
-        child.kill("SIGKILL");
-    }
-    catch (error) {
-        return error instanceof Error ? error.message : String(error);
-    }
-    if (await waitForLaunchChildExit(child, Date.now() + 1_000))
-        return undefined;
-    return `PID ${child.pid} remained alive after failed Electron launch cleanup.`;
+function targetMatchesType(target, type) {
+    return type === undefined || type === "any" || target.type === type;
 }
-function buildLaunchRecord(options) {
-    return {
-        appName: options.target.name,
-        appPath: options.target.appPath,
-        bundleId: options.target.bundleId,
-        cleanupState: "active",
-        createdAtMs: options.createdAtMs,
-        desktopId: options.target.desktopId,
-        executablePath: options.target.executablePath,
-        launchId: `electron-${randomUUID()}`,
-        launchedByWrapper: true,
-        packageSource: options.target.packageSource,
-        pid: options.pid,
-        platform: options.target.platform,
-        port: options.port,
-        processGroupId: process.platform === "win32" ? undefined : options.pid,
-        targetType: options.targetType,
-        userDataDir: options.userDataDir,
-        version: ELECTRON_LAUNCH_RECORD_VERSION,
-        webSocketDebuggerUrl: options.version.webSocketDebuggerUrl,
-    };
+function selectConnectArg(port, metadata, type) {
+    const targetSocket = metadata.targets.find((target) => targetMatchesType(target, type) &&
+        target.webSocketDebuggerUrl !== undefined &&
+        target.webSocketDebuggerUrl.length > 0)?.webSocketDebuggerUrl;
+    return targetSocket ?? metadata.version.webSocketDebuggerUrl ?? String(port);
 }
 function launchFailureMessage(reason, target, detail) {
     const label = target ? `${target.name} (${target.appPath ?? target.executablePath})` : "target";
@@ -224,7 +94,7 @@ function launchFailureMessage(reason, target, detail) {
         case "aborted":
             return `Electron launch was aborted${target ? ` before ${label} finished starting` : " before the app started"}.`;
         case "non-electron-target":
-            return `Electron launch rejected: ${label} does not have Electron framework evidence.`;
+            return `Electron launch rejected: ${label} does not have the required Electron runtime and app payload evidence.`;
         case "policy-blocked":
             return detail ?? `Electron launch blocked by caller policy for ${label}.`;
         case "single-instance-conflict":
@@ -232,203 +102,239 @@ function launchFailureMessage(reason, target, detail) {
         case "port-not-found":
             return `Electron launch found a DevToolsActivePort for ${label}, but /json/version never returned a valid CDP payload.`;
         case "spawn-error":
-            return `Electron launch failed while starting ${label}${detail ? `: ${detail}` : "."}`;
+            return `Electron launch failed while starting ${label}${detail !== undefined && detail.length > 0 ? `: ${detail}` : "."}`;
         case "timeout":
             return `Electron launch timed out waiting for DevToolsActivePort for ${label}.`;
     }
 }
-export async function launchElectronApp(options) {
-    const appArgs = options.appArgs ?? [];
-    if (options.signal?.aborted)
-        return { ok: false, failure: { appArgs, error: launchFailureMessage("aborted", undefined), reason: "aborted" } };
-    const target = await resolveElectronLaunchTarget(options);
-    if (options.signal?.aborted)
-        return { ok: false, failure: { appArgs, error: launchFailureMessage("aborted", target), reason: "aborted", target } };
-    if (!target) {
+/** Owns one profile and process attempt; only a successful result transfers them to the host. */
+class ElectronLaunchAttempt {
+    options;
+    target;
+    userDataDir;
+    process;
+    startedAtMs;
+    timeoutMs;
+    deadlineMs;
+    appArgs;
+    startIdentity;
+    constructor(options, target, userDataDir, timing) {
+        this.options = options;
+        this.target = target;
+        this.userDataDir = userDataDir;
+        this.process = new ElectronLaunchProcess(userDataDir);
+        this.startedAtMs = timing.startedAtMs;
+        this.timeoutMs = timing.timeoutMs;
+        this.deadlineMs = timing.startedAtMs + timing.timeoutMs;
+        this.appArgs = options.appArgs ?? [];
+    }
+    diagnostics(observation) {
         return {
-            ok: false,
-            failure: {
-                appArgs,
-                error: launchFailureMessage("non-electron-target", undefined),
-                reason: "non-electron-target",
-            },
+            ...observation,
+            elapsedMs: Math.max(0, Date.now() - this.startedAtMs),
+            exitCode: this.process.exitCode,
+            exitSignal: this.process.exitSignal,
+            outputCaptured: this.process.outputCaptured,
+            pid: this.process.child?.pid,
+            pidAlive: this.process.child === undefined ? undefined : this.process.pidAlive(),
+            port: observation.port ?? observation.devToolsActivePort?.port,
+            timeoutMs: this.timeoutMs,
+            userDataDir: this.userDataDir,
         };
     }
-    const policy = evaluateElectronLaunchPolicy({ allow: options.allow, deny: options.deny, target });
-    if (policy) {
+    async cleanupProfile(processError) {
+        try {
+            if (processError !== undefined && processError.length > 0) {
+                await preserveSecureTempDirectory(this.userDataDir);
+            }
+            else {
+                await rm(this.userDataDir, { force: true, recursive: true });
+            }
+            return undefined;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : stringifyUnknown(error);
+            return processError !== undefined && processError.length > 0
+                ? `Profile preservation failed: ${message}`
+                : message;
+        }
+    }
+    async fail(reason, detail, observation = {}) {
+        const diagnostics = this.diagnostics(observation);
+        const processError = await this.process.terminate();
+        const output = await this.process.readOutput();
+        const profileError = await this.cleanupProfile(processError);
+        const cleanupErrors = [processError, this.process.cleanupError, profileError].filter((value) => value !== undefined);
+        const cleanupError = cleanupErrors.join("; ");
         return {
             ok: false,
             failure: {
-                appArgs,
-                error: launchFailureMessage("policy-blocked", target, policy.message),
-                policy,
-                reason: "policy-blocked",
-                target,
+                appArgs: this.appArgs,
+                cleanupError: cleanupError.length === 0 ? undefined : cleanupError,
+                diagnostics: { ...diagnostics, ...output.evidence },
+                error: [launchFailureMessage(reason, this.target, detail), ...output.lines].join("\n"),
+                reason,
+                target: this.target,
+                userDataDir: this.userDataDir,
             },
         };
     }
-    const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
-    const startedAtMs = Date.now();
-    const deadlineMs = startedAtMs + timeoutMs;
-    const userDataDir = await createSecureTempDirectory(ELECTRON_PROFILE_DIR_PREFIX);
-    if (options.signal?.aborted) {
-        let cleanupError;
-        try {
-            await rm(userDataDir, { force: true, recursive: true });
+    record(port, version) {
+        const pid = this.process.child?.pid;
+        return {
+            appName: this.target.name,
+            appPath: this.target.appPath,
+            bundleId: this.target.bundleId,
+            cleanupState: "active",
+            createdAtMs: Date.now(),
+            desktopId: this.target.desktopId,
+            executablePath: this.target.executablePath,
+            launchId: `electron-${randomUUID()}`,
+            launchedByWrapper: true,
+            packageSource: this.target.packageSource,
+            pid,
+            platform: this.target.platform,
+            port,
+            processGroupId: process.platform === "win32" ? undefined : pid,
+            startIdentity: this.startIdentity,
+            targetType: this.options.targetType,
+            userDataDir: this.userDataDir,
+            version: ELECTRON_LAUNCH_RECORD_VERSION,
+            webSocketDebuggerUrl: version.webSocketDebuggerUrl,
+        };
+    }
+    async run() {
+        const args = [
+            ...this.appArgs,
+            `--user-data-dir=${this.userDataDir}`,
+            "--remote-debugging-port=0",
+            ...DEFAULT_APP_ARGS,
+        ];
+        await this.process.spawn(this.target.executablePath, args, this.options.signal);
+        if (this.process.child === undefined) {
+            return this.fail(isElectronLaunchAborted(this.options.signal) ? "aborted" : "spawn-error", this.process.spawnError?.message);
         }
-        catch (error) {
-            cleanupError = error instanceof Error ? error.message : String(error);
+        const pid = this.process.child.pid;
+        this.startIdentity =
+            pid === undefined
+                ? undefined
+                : await readProcessStartIdentity(pid, process.platform, {
+                    deadline: this.deadlineMs,
+                    signal: this.options.signal,
+                });
+        const portResult = await pollDevToolsActivePort({
+            deadlineMs: this.deadlineMs,
+            getChildExit: this.process.childExit,
+            getSpawnError: this.process.childSpawnError,
+            signal: this.options.signal,
+            userDataDir: this.userDataDir,
+        });
+        if (portResult.port === undefined) {
+            return this.fail(portResult.failure ?? "timeout", portResult.spawnError?.message, {
+                devToolsActivePort: portResult.devToolsActivePort,
+            });
+        }
+        return this.connect(portResult.port, portResult.devToolsActivePort);
+    }
+    async connect(port, devToolsActivePort) {
+        const metadataResult = await pollCdpMetadata(port, this.deadlineMs, this.options.signal);
+        if (metadataResult.aborted) {
+            return this.fail("aborted", undefined, { devToolsActivePort, port });
+        }
+        const metadata = metadataResult.metadata;
+        if (metadata === undefined) {
+            return this.fail("port-not-found", undefined, {
+                cdpVersionReached: false,
+                devToolsActivePort,
+                port,
+            });
+        }
+        const child = this.process.child;
+        if (child === undefined) {
+            throw new Error("Electron launch lost its child handle before handoff.");
         }
-        return { ok: false, failure: { appArgs, cleanupError, error: launchFailureMessage("aborted", target), reason: "aborted", target, userDataDir } };
+        return {
+            ok: true,
+            value: {
+                appArgs: this.appArgs,
+                child,
+                connectArg: selectConnectArg(port, metadata, this.options.targetType),
+                record: this.record(port, metadata.version),
+                target: this.target,
+                targets: metadata.targets,
+                version: metadata.version,
+            },
+        };
     }
+}
+async function abortedProfileResult(userDataDir, options, target) {
     let cleanupError;
-    let spawnError;
-    let exitCode = null;
-    let exitSignal = null;
-    const args = buildLaunchArgs(userDataDir, appArgs);
-    let child;
-    let outputCaptured = false;
-    const outputFiles = [];
     try {
-        for (const stream of ["stdout", "stderr"])
-            outputFiles.push(await open(join(userDataDir, `${stream}.log`), "wx", 0o600));
-        options.signal?.throwIfAborted();
-        child = spawn(target.executablePath, args, {
-            cwd: dirname(target.executablePath),
-            detached: process.platform !== "win32",
-            stdio: ["ignore", outputFiles[0].fd, outputFiles[1].fd],
-        });
-        outputCaptured = true;
-        child.once("error", (error) => {
-            spawnError = error;
-        });
-        child.once("exit", (code, signal) => {
-            exitCode = code;
-            exitSignal = signal;
-        });
-        child.unref();
+        await rm(userDataDir, { force: true, recursive: true });
     }
     catch (error) {
-        spawnError = error instanceof Error ? error : new Error(String(error));
+        cleanupError = error instanceof Error ? error.message : stringifyUnknown(error);
     }
-    finally {
-        for (const file of outputFiles) {
-            await file.close().catch((error) => {
-                cleanupError = [cleanupError, `Output handle close failed: ${error instanceof Error ? error.message : String(error)}`].filter(Boolean).join("; ");
-            });
-        }
+    return {
+        ok: false,
+        failure: {
+            appArgs: options.appArgs ?? [],
+            cleanupError,
+            error: launchFailureMessage("aborted", target),
+            reason: "aborted",
+            target,
+            userDataDir,
+        },
+    };
+}
+export async function launchElectronApp(options) {
+    const appArgs = options.appArgs ?? [];
+    if (isElectronLaunchAborted(options.signal)) {
+        return {
+            ok: false,
+            failure: { appArgs, error: launchFailureMessage("aborted", undefined), reason: "aborted" },
+        };
     }
-    const buildFailureDiagnostics = (options = {}) => ({
-        cdpVersionReached: options.cdpVersionReached,
-        devToolsActivePort: options.devToolsActivePort,
-        elapsedMs: Math.max(0, Date.now() - startedAtMs),
-        exitCode,
-        exitSignal,
-        outputCaptured,
-        pid: child?.pid,
-        pidAlive: child ? isLaunchChildPidAlive(child) : undefined,
-        port: options.port ?? options.devToolsActivePort?.port,
-        timeoutMs,
-        userDataDir,
-    });
-    const fail = async (reason, detail, diagnosticOptions) => {
-        const diagnostics = buildFailureDiagnostics(diagnosticOptions);
-        const processCleanupError = child ? await terminateLaunchChild(child) : undefined;
-        const outputLines = [];
-        if (outputCaptured) {
-            for (const stream of ["stdout", "stderr"]) {
-                let file;
-                try {
-                    file = await open(join(userDataDir, `${stream}.log`), "r");
-                    const { size } = await file.stat();
-                    const buffer = Buffer.alloc(Math.min(size, ELECTRON_OUTPUT_TAIL_BYTES));
-                    const { bytesRead } = await file.read(buffer, 0, buffer.length, Math.max(0, size - buffer.length));
-                    diagnostics[`${stream}Tail`] = buffer.subarray(0, bytesRead).toString("utf8");
-                    diagnostics[`${stream}Truncated`] = size > buffer.length;
-                }
-                catch (error) {
-                    diagnostics[`${stream}Error`] = error instanceof Error ? error.message : String(error);
-                }
-                finally {
-                    await file?.close().catch((error) => {
-                        diagnostics[`${stream}Error`] = [diagnostics[`${stream}Error`], `Output reader close failed: ${error instanceof Error ? error.message : String(error)}`].filter(Boolean).join("; ");
-                    });
-                }
-                const tail = diagnostics[`${stream}Tail`];
-                if (tail !== undefined)
-                    outputLines.push(`App ${stream}${diagnostics[`${stream}Truncated`] ? ` (last ${ELECTRON_OUTPUT_TAIL_BYTES} bytes)` : ""}: ${tail || "(empty)"}`);
-                if (diagnostics[`${stream}Error`])
-                    outputLines.push(`App ${stream} capture error: ${diagnostics[`${stream}Error`]}`);
-            }
-        }
-        try {
-            if (processCleanupError)
-                await preserveSecureTempDirectory(userDataDir);
-            else
-                await rm(userDataDir, { force: true, recursive: true });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            cleanupError = [cleanupError, processCleanupError ? `Profile preservation failed: ${message}` : message].filter(Boolean).join("; ");
-        }
-        cleanupError = [processCleanupError, cleanupError].filter((value) => value !== undefined).join("; ") || undefined;
+    const target = await resolveLaunchTarget(options);
+    if (isElectronLaunchAborted(options.signal)) {
         return {
             ok: false,
             failure: {
                 appArgs,
-                cleanupError,
-                diagnostics,
-                error: [launchFailureMessage(reason, target, detail), ...outputLines].join("\n"),
-                reason,
+                error: launchFailureMessage("aborted", target),
+                reason: "aborted",
                 target,
-                userDataDir,
             },
         };
-    };
-    if (!child)
-        return fail(options.signal?.aborted ? "aborted" : "spawn-error", spawnError?.message);
-    const portResult = await pollDevToolsActivePort({
-        deadlineMs,
-        getChildExit: () => ({ code: exitCode, signal: exitSignal }),
-        getSpawnError: () => spawnError,
-        signal: options.signal,
-        userDataDir,
-    });
-    if (!portResult.port) {
-        return fail(portResult.failure ?? "timeout", portResult.spawnError?.message, { devToolsActivePort: portResult.devToolsActivePort });
     }
-    const metadataResult = await pollCdpMetadata(portResult.port, deadlineMs, options.signal);
-    if (metadataResult.aborted)
-        return fail("aborted", undefined, { devToolsActivePort: portResult.devToolsActivePort, port: portResult.port });
-    if (!metadataResult.metadata) {
-        return fail("port-not-found", undefined, { cdpVersionReached: false, devToolsActivePort: portResult.devToolsActivePort, port: portResult.port });
+    if (target === undefined) {
+        return {
+            ok: false,
+            failure: {
+                appArgs,
+                error: launchFailureMessage("non-electron-target", undefined),
+                reason: "non-electron-target",
+            },
+        };
     }
-    const metadata = metadataResult.metadata;
-    const record = buildLaunchRecord({
-        createdAtMs: Date.now(),
-        pid: child.pid,
-        port: portResult.port,
-        target,
-        targetType: options.targetType,
-        userDataDir,
-        version: metadata.version,
-    });
-    const connectArg = selectElectronConnectArg({
-        port: portResult.port,
-        targets: metadata.targets,
-        targetType: options.targetType,
-        version: metadata.version,
-    });
-    return {
-        ok: true,
-        value: {
-            appArgs,
-            child,
-            connectArg,
-            record,
-            target,
-            targets: metadata.targets,
-            version: metadata.version,
-        },
-    };
+    const policy = evaluateLaunchPolicy(options, target);
+    if (policy !== undefined) {
+        return {
+            ok: false,
+            failure: {
+                appArgs,
+                error: launchFailureMessage("policy-blocked", target, policy.message),
+                policy,
+                reason: "policy-blocked",
+                target,
+            },
+        };
+    }
+    const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
+    const startedAtMs = Date.now();
+    const userDataDir = await createSecureTempDirectory(ELECTRON_PROFILE_DIR_PREFIX);
+    if (isElectronLaunchAborted(options.signal)) {
+        return abortedProfileResult(userDataDir, options, target);
+    }
+    return new ElectronLaunchAttempt(options, target, userDataDir, { timeoutMs, startedAtMs }).run();
 }