devharness 0.8.0

package/build/chrome-launcher.js

@@ -0,0 +1,1071 @@
+/**
+ * Chrome Launcher
+ * Utilities for launching Chrome with debugging enabled
+ */
+import { spawn } from 'child_process';
+import * as os from 'os';
+import * as path from 'path';
+import * as net from 'net';
+import * as fs from 'fs';
+import { randomBytes } from 'crypto';
+import { debugLog } from './debug-logger.js';
+/**
+ * Prefix used for all launcher-created temporary Chrome profile directories.
+ * The startup sweep only ever considers directories with this prefix.
+ */
+export const EPHEMERAL_PROFILE_PREFIX = 'chrome-debug-profile-';
+/**
+ * Legal characters for a named persistent profile (issue 13).
+ *
+ * Deliberately strict: the name becomes a directory under the profile root, so
+ * anything that could escape it (`/`, `..`, leading dot) or confuse the startup
+ * sweep is rejected rather than sanitised - silently renaming a profile would
+ * hand the caller a different identity than they asked for.
+ */
+export const PROFILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Thrown when a profile name is not a safe single directory segment. */
+export class InvalidProfileNameError extends Error {
+    profile;
+    constructor(profile) {
+        super(`Invalid profile name "${profile}". Use 1-64 characters: letters, digits, dot, dash or underscore, starting with a letter or digit.`);
+        this.profile = profile;
+        this.name = 'InvalidProfileNameError';
+    }
+}
+/** Thrown when an operation would disturb a profile a live Chrome is holding. */
+export class ProfileInUseError extends Error {
+    profile;
+    port;
+    constructor(profile, port) {
+        super(`Profile "${profile}" is in use by the Chrome running on port ${port}.`);
+        this.profile = profile;
+        this.port = port;
+        this.name = 'ProfileInUseError';
+    }
+}
+/**
+ * Thrown when a profile is held by a Chrome this process did not launch -
+ * typically another cdp-tools session on the same machine, because the default
+ * persistent profile root (`~/.cdp-tools/profiles`) is global.
+ *
+ * Detected from the profile's Chrome `SingletonLock`, so we know the holding
+ * PID but not which debug port it listens on.
+ *
+ * LIMITATION: the check is POSIX-only. `SingletonLock` is a symlink on
+ * macOS/Linux; on Windows Chrome uses a plain lock file we cannot read a PID
+ * from, so this error is never raised there and the cross-session races it
+ * guards against remain possible.
+ */
+export class ProfileLockedError extends Error {
+    profile;
+    pid;
+    dir;
+    constructor(profile, pid, dir) {
+        super(`Profile "${profile}" is locked by a Chrome started by another process (PID ${pid}, ${dir}). ` +
+            `Only one live Chrome may hold a profile; quit that browser (or use a different profile name) and retry.`);
+        this.profile = profile;
+        this.pid = pid;
+        this.dir = dir;
+        this.name = 'ProfileLockedError';
+    }
+}
+/**
+ * Validate a persistent profile name, returning it trimmed.
+ * @throws InvalidProfileNameError
+ */
+export function normalizeProfileName(name) {
+    const trimmed = (name ?? '').trim();
+    if (!PROFILE_NAME_PATTERN.test(trimmed) || trimmed.startsWith(EPHEMERAL_PROFILE_PREFIX)) {
+        throw new InvalidProfileNameError(name);
+    }
+    return trimmed;
+}
+/**
+ * Decide which port a launchChrome call should use (bug-005).
+ *
+ * Extracted from the MCP handler so the decision is testable without a browser
+ * or an MCP server: src/index.ts calls main() on import, so anything left
+ * inline there can only be "tested" by grepping the source.
+ *
+ * Rules:
+ *  - An explicit `port` is always honoured, never silently relocated.
+ *  - `forceNewInstance` must produce a fresh process, so an explicit port that
+ *    is already occupied is an error rather than a hand-off to whatever is
+ *    listening; occupancy is only consulted in that case.
+ *  - `forceNewInstance` without a port picks a known-free port instead of the
+ *    reserved one, which an existing instance may already be using.
+ */
+export async function resolveLaunchPort(req) {
+    const { explicitPort, forceNewInstance, reservedPort } = req;
+    if (!forceNewInstance) {
+        return { decision: 'use', port: explicitPort ?? reservedPort };
+    }
+    if (explicitPort !== undefined) {
+        if (await req.isPortOccupied(explicitPort)) {
+            return { decision: 'forced-port-in-use', port: explicitPort };
+        }
+        return { decision: 'use', port: explicitPort };
+    }
+    return { decision: 'use', port: await req.findFreePort() };
+}
+/**
+ * Decide whether a launchChrome call may reuse an existing Chrome, given the
+ * named profile it asked for (issue 13 / bug: profile pre-check ordering).
+ *
+ * The ordering this encodes is the whole point: a live instance already running
+ * the requested profile is REUSED, exactly as it would be without a profile, so
+ * the idempotent `launchChrome({ profile, reference })` "make sure it's up"
+ * pattern keeps working. "Profile in use" is only an error when the call would
+ * have to put a SECOND Chrome on a profile another instance holds.
+ */
+export function decideProfileReuse(req) {
+    const { wantedProfileDir, existing, holderPort } = req;
+    if (!wantedProfileDir) {
+        return { decision: 'ok' };
+    }
+    if (!existing) {
+        // We would spawn - a holder elsewhere means a second Chrome on one profile.
+        return holderPort !== undefined ? { decision: 'in-use', port: holderPort } : { decision: 'ok' };
+    }
+    if (existing.profileDir === wantedProfileDir) {
+        return { decision: 'ok' }; // same profile, same browser - plain reuse
+    }
+    if (holderPort !== undefined && holderPort !== existing.port) {
+        // Reuse is out (wrong profile) and spawning is out (someone holds it).
+        return { decision: 'in-use', port: holderPort };
+    }
+    return { decision: 'mismatch', port: existing.port, actualProfile: existing.profileDir };
+}
+export class ChromeLauncher {
+    chromeProcesses = new Map();
+    launchLocks = new Map();
+    /** profile name -> in-flight launch for that profile (see launch()) */
+    profileLaunchLocks = new Map();
+    lastCloseEvents = [];
+    maxCloseEvents = 10; // Keep last 10 close events
+    pendingCloseReason = new Map(); // Track reason before kill
+    onExitCallback = null;
+    /** port -> profile dir currently in use by the Chrome on that port */
+    profileDirs = new Map();
+    profileRoot;
+    persistentProfileRootOption;
+    staleProfileMaxAgeMs;
+    /** Resolves once the startup sweep (if any) has finished. Exposed for tests. */
+    startupSweep;
+    constructor(options = {}) {
+        this.profileRoot = options.profileRoot ?? os.tmpdir();
+        this.persistentProfileRootOption =
+            options.persistentProfileRoot ?? path.join(os.homedir(), '.cdp-tools', 'profiles');
+        this.staleProfileMaxAgeMs = options.staleProfileMaxAgeMs ?? 60 * 60 * 1000;
+        // Sweep profiles left behind by crashed/killed sessions. Fire-and-forget:
+        // a failure here must never prevent the launcher from being usable.
+        this.startupSweep = options.sweepStaleProfilesOnStartup === false
+            ? Promise.resolve([])
+            : this.sweepStaleProfiles().catch((error) => {
+                debugLog('ChromeLauncher', `Startup profile sweep failed: ${error}`).catch(() => { });
+                return [];
+            });
+    }
+    /**
+     * Set a callback to be invoked when any Chrome process exits.
+     * Used for cleanup (closing stale connections) and port re-reservation.
+     */
+    setOnExitCallback(callback) {
+        this.onExitCallback = callback;
+    }
+    /**
+     * Get the Chrome executable path for the current platform
+     */
+    getChromePath() {
+        const platform = os.platform();
+        switch (platform) {
+            case 'darwin': // macOS
+                return '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+            case 'win32': // Windows
+                return 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe';
+            case 'linux':
+                // Try common Linux paths
+                return '/usr/bin/google-chrome';
+            default:
+                throw new Error(`Unsupported platform: ${platform}`);
+        }
+    }
+    /**
+     * Create Chrome preferences file that disables password manager popups
+     * This is required because command-line flags alone don't reliably disable
+     * the "Change your password" leak detection popup
+     */
+    createChromePreferences(userDataDir, overwrite = true) {
+        const defaultDir = path.join(userDataDir, 'Default');
+        const prefsPath = path.join(defaultDir, 'Preferences');
+        // Create Default directory if it doesn't exist
+        if (!fs.existsSync(defaultDir)) {
+            fs.mkdirSync(defaultDir, { recursive: true });
+        }
+        // Persistent/named profiles (issue 13) only get the seed once. Rewriting
+        // Preferences on every launch would throw away everything the profile has
+        // accumulated - which is the entire point of a persistent profile.
+        if (!overwrite && fs.existsSync(prefsPath)) {
+            debugLog('ChromeLauncher', `Keeping existing Chrome preferences at ${prefsPath}`);
+            return;
+        }
+        // Chrome preferences to disable password-related popups
+        const preferences = {
+            credentials_enable_service: false,
+            profile: {
+                password_manager_enabled: false,
+                password_manager_leak_detection: false,
+            },
+            safebrowsing: {
+                enabled: false,
+                enhanced: false,
+            },
+            autofill: {
+                profile_enabled: false,
+                credit_card_enabled: false,
+            },
+        };
+        fs.writeFileSync(prefsPath, JSON.stringify(preferences, null, 2));
+        debugLog('ChromeLauncher', `Created Chrome preferences at ${prefsPath} with password manager disabled`);
+    }
+    /**
+     * Check if a port is already in use using TCP connection
+     */
+    async isPortInUse(port) {
+        await debugLog('ChromeLauncher', `isPortInUse() checking port ${port}`);
+        return new Promise((resolve) => {
+            try {
+                const socket = new net.Socket();
+                socket.setTimeout(500);
+                socket.on('connect', () => {
+                    socket.destroy();
+                    debugLog('ChromeLauncher', `isPortInUse() port ${port} is in use`).catch(() => { });
+                    resolve(true);
+                });
+                socket.on('timeout', () => {
+                    socket.destroy();
+                    debugLog('ChromeLauncher', `isPortInUse() timeout checking port ${port}, assuming free`).catch(() => { });
+                    resolve(false);
+                });
+                socket.on('error', (err) => {
+                    socket.destroy();
+                    if (err.code === 'ECONNREFUSED') {
+                        // Port is not in use
+                        debugLog('ChromeLauncher', `isPortInUse() port ${port} is free (ECONNREFUSED)`).catch(() => { });
+                        resolve(false);
+                    }
+                    else {
+                        // Other error, assume port is in use to be safe
+                        debugLog('ChromeLauncher', `isPortInUse() error checking port ${port}: ${err.code}, assuming in use`).catch(() => { });
+                        resolve(true);
+                    }
+                });
+                try {
+                    socket.connect(port, 'localhost');
+                }
+                catch (connectError) {
+                    debugLog('ChromeLauncher', `isPortInUse() socket.connect() threw for port ${port}: ${connectError}`).catch(() => { });
+                    socket.destroy();
+                    resolve(true); // Assume in use to be safe
+                }
+            }
+            catch (error) {
+                debugLog('ChromeLauncher', `isPortInUse() unexpected error for port ${port}: ${error}`).catch(() => { });
+                resolve(true); // Assume in use to be safe
+            }
+        });
+    }
+    /**
+     * Wait for Chrome debugging port to become ready
+     * Polls the /json/version endpoint until Chrome is inspectable
+     */
+    async waitForChromeReady(port, maxAttempts = 15) {
+        for (let i = 0; i < maxAttempts; i++) {
+            try {
+                // Use a race between fetch and timeout
+                const fetchPromise = fetch(`http://localhost:${port}/json/version`);
+                const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 1000));
+                const response = await Promise.race([fetchPromise, timeoutPromise]);
+                if (response.ok) {
+                    // Validate it's actually Chrome responding, not the port reserver
+                    const text = await response.text();
+                    if (text.trim() === 'chrome-not-running') {
+                        await debugLog('ChromeLauncher', `Port ${port} is reserved by PortReserver, Chrome failed to bind`);
+                        throw new Error(`Port ${port} is reserved by another MCP instance. Chrome cannot bind to this port.`);
+                    }
+                    // Valid Chrome response
+                    await debugLog('ChromeLauncher', `Chrome ready on port ${port} after ${i + 1} attempts`);
+                    return;
+                }
+            }
+            catch (error) {
+                // Re-throw port reservation errors immediately
+                if (error instanceof Error && error.message.includes('reserved by another MCP instance')) {
+                    throw error;
+                }
+                // Chrome not ready yet, continue polling
+                // Only log every 5 attempts to reduce noise
+                if (i % 5 === 0) {
+                    await debugLog('ChromeLauncher', `Waiting for Chrome on port ${port} (attempt ${i + 1}/${maxAttempts}) - error: ${error}`);
+                }
+            }
+            // Exponential backoff: 500ms + (attempt * 200ms)
+            await new Promise(resolve => setTimeout(resolve, 500 + i * 200));
+        }
+        throw new Error(`Chrome debugging port ${port} failed to become inspectable within timeout. Chrome may have crashed during startup.`);
+    }
+    /**
+     * Launch Chrome with debugging enabled
+     * Uses atomic release-and-launch to prevent race conditions
+     * Waits for Chrome to actually bind to the port before resolving
+     */
+    async launch(port = 9222, url, portReserver, headless = false, extraArgs = [], profileName) {
+        if (profileName === undefined) {
+            return this.launchOnPort(port, url, portReserver, headless, extraArgs, profileName);
+        }
+        // Named profiles are serialised by NAME as well as by port (bug-006 follow-up).
+        // The per-port lock does not help here: two launches for the same profile on
+        // different ports both pass the "is this profile held?" guard while the first
+        // Chrome is still spawning (findPortForProfile requires isRunning(), which is
+        // false during that window). Chrome then hands the second process off to the
+        // first singleton and it exits, surfacing as a generic spawn failure.
+        const name = normalizeProfileName(profileName);
+        for (let i = 0; i < 50; i++) {
+            const inFlight = this.profileLaunchLocks.get(name);
+            if (!inFlight)
+                break;
+            await debugLog('ChromeLauncher', `Another launch is in progress for profile "${name}", waiting...`);
+            // Its failure is its caller's problem, not ours - we just need it settled.
+            const result = await inFlight.then(r => r, () => undefined);
+            if (result && result.port === port && this.isRunning(port)) {
+                // Same port, same profile: this is the per-port hand-off case, so give
+                // both callers the one launch instead of "already running on port X".
+                return result;
+            }
+        }
+        const launchPromise = this.launchOnPort(port, url, portReserver, headless, extraArgs, name);
+        this.profileLaunchLocks.set(name, launchPromise);
+        try {
+            return await launchPromise;
+        }
+        finally {
+            if (this.profileLaunchLocks.get(name) === launchPromise) {
+                this.profileLaunchLocks.delete(name);
+            }
+        }
+    }
+    /**
+     * Port-scoped half of launch(): the per-port lock, the "already running" and
+     * profile-ownership guards, and the spawn itself.
+     */
+    async launchOnPort(port, url, portReserver, headless = false, extraArgs = [], profileName) {
+        await debugLog('ChromeLauncher', `launch() called with port ${port}, portReserver=${!!portReserver}, isReserved=${portReserver?.isReserved()}`);
+        // CRITICAL: Check if another launch is in progress for this port
+        // This prevents race conditions where two launch() calls happen simultaneously
+        const existingLaunch = this.launchLocks.get(port);
+        if (existingLaunch) {
+            await debugLog('ChromeLauncher', `Another launch is in progress for port ${port}, waiting for it to complete...`);
+            return existingLaunch; // Return the same promise, so both callers wait for the same launch
+        }
+        // Use isRunning() to verify the process is actually alive (handles external kills)
+        if (this.isRunning(port)) {
+            throw new Error(`Chrome is already running on port ${port}. Use killChrome() to stop it first, or specify a different port.`);
+        }
+        // Create a promise for this launch and store it in the lock map
+        // This prevents concurrent launches on the same port
+        // A named profile can only be held by one live Chrome - a second launch on
+        // the same user-data-dir is handed off to the first process and ours exits.
+        if (profileName !== undefined) {
+            const name = normalizeProfileName(profileName);
+            const holder = this.findPortForProfile(name);
+            if (holder !== undefined) {
+                throw new ProfileInUseError(name, holder);
+            }
+            // ...and the same profile may be held by a Chrome belonging to ANOTHER
+            // cdp-tools session (the persistent profile root is global by default),
+            // which our own maps know nothing about. Without this the launch "works",
+            // Chrome hands off to the existing singleton, and the caller gets an
+            // unexplained spawn failure. POSIX-only - see ProfileLockedError.
+            const lockPid = await this.findProfileLockHolder(name);
+            if (lockPid !== undefined) {
+                throw new ProfileLockedError(name, lockPid, this.getPersistentProfilePath(name));
+            }
+        }
+        const launchPromise = this.performLaunch(port, url, portReserver, headless, extraArgs, profileName);
+        this.launchLocks.set(port, launchPromise);
+        try {
+            const result = await launchPromise;
+            return result;
+        }
+        finally {
+            // Always clean up the lock when done (success or failure)
+            this.launchLocks.delete(port);
+        }
+    }
+    /**
+     * Internal method that performs the actual Chrome launch
+     * Separated from launch() to allow mutex/locking logic
+     */
+    async performLaunch(port, url, portReserver, headless = false, extraArgs = [], profileName) {
+        await debugLog('ChromeLauncher', `performLaunch() starting for port ${port}`);
+        // Check if port is in use by something OTHER than our port reserver
+        // This prevents multiple Chrome instances from being launched on the same port
+        let isPortInUse;
+        try {
+            isPortInUse = await this.isPortInUse(port);
+            await debugLog('ChromeLauncher', `performLaunch() isPortInUse check completed: ${isPortInUse}`);
+        }
+        catch (portCheckError) {
+            await debugLog('ChromeLauncher', `performLaunch() isPortInUse check failed: ${portCheckError}`);
+            throw new Error(`Failed to check port availability: ${portCheckError}`);
+        }
+        const isOurReservation = portReserver && portReserver.isReserved() && portReserver.getPort() === port;
+        if (isPortInUse && !isOurReservation) {
+            // Port is in use by something else (not our reservation)
+            throw new Error(`Port ${port} is already in use by another process or MCP instance. Please choose a different port.`);
+        }
+        if (!isPortInUse && !isOurReservation) {
+            // Port is free but not reserved by us - this is fine, we can use it
+            await debugLog('ChromeLauncher', `Port ${port} is free and not reserved, proceeding with launch`);
+        }
+        const chromePath = this.getChromePath();
+        // Unique by construction: the port can only be held by one live Chrome at a
+        // time, and the random suffix covers same-millisecond relaunches on the same
+        // port. Using Date.now() alone let two concurrent launches on *different*
+        // ports share a profile (launchLocks only serialises per-port) - bug-006.
+        const profile = this.createProfileRecord(port, profileName);
+        const userDataDir = profile.dir;
+        this.profileDirs.set(port, profile);
+        await debugLog('ChromeLauncher', `Using ${profile.ephemeral ? 'ephemeral' : 'persistent'} profile ${userDataDir} for port ${port}`);
+        if (!profile.ephemeral) {
+            // First use of a named profile: the directory does not exist yet.
+            await fs.promises.mkdir(userDataDir, { recursive: true });
+        }
+        // Create Chrome preferences file to disable password manager popups
+        // This is more reliable than command-line flags alone
+        this.createChromePreferences(userDataDir, profile.ephemeral);
+        const args = [
+            `--remote-debugging-port=${port}`,
+            `--user-data-dir=${userDataDir}`,
+            '--no-first-run',
+            '--no-default-browser-check',
+            '--disable-popup-blocking',
+            '--disable-prompt-on-repost',
+            '--disable-background-timer-throttling',
+            '--disable-backgrounding-occluded-windows',
+            '--disable-renderer-backgrounding',
+            // Disable password manager and related popups that can block automation
+            '--password-store=basic',
+            '--use-mock-keychain',
+            '--disable-save-password-bubble',
+            '--disable-features=PasswordLeakDetection,PasswordCheck,PasswordImport,PasswordManagerOnboarding',
+        ];
+        // Add headless mode if requested (prevents focus stealing)
+        if (headless) {
+            args.push('--headless=new'); // Use new headless mode
+        }
+        else {
+            args.push('--start-minimized'); // Launch minimized to reduce focus stealing
+        }
+        // Pass-through: any extra Chrome flags from the launchChrome call (extraArgs)
+        // and/or the CDP_TOOLS_EXTRA_CHROME_ARGS env var (space-separated). Merged
+        // after the managed defaults and before the URL (Chrome treats the trailing
+        // positional arg as the page to open). Lets callers enable things like a fake
+        // camera (--use-fake-device-for-media-stream) without patching this file.
+        const envExtra = (process.env.CDP_TOOLS_EXTRA_CHROME_ARGS || '').split(/\s+/).filter(Boolean);
+        const passthrough = [...extraArgs, ...envExtra];
+        if (passthrough.length) {
+            await debugLog('ChromeLauncher', `Passing through extra Chrome args: ${passthrough.join(' ')}`);
+            args.push(...passthrough);
+        }
+        if (url) {
+            args.push(url);
+        }
+        // Track whether we released the reservation (so we can re-reserve on failure)
+        let didReleaseReservation = false;
+        try {
+            // ATOMIC OPERATION: Release port reservation immediately before spawning Chrome
+            // This minimizes the race condition window to just a few milliseconds
+            if (isOurReservation) {
+                await debugLog('ChromeLauncher', `Releasing port reservation for ${port} immediately before spawn`);
+                await portReserver.release();
+                didReleaseReservation = true;
+                await debugLog('ChromeLauncher', `Port ${port} released, spawning Chrome immediately...`);
+            }
+            await debugLog('ChromeLauncher', `Spawning Chrome process on port ${port}...`);
+            const chromeProcess = spawn(chromePath, args, {
+                stdio: 'ignore',
+            });
+            const pid = chromeProcess.pid;
+            await debugLog('ChromeLauncher', `Chrome process spawned with PID ${pid}`);
+            // CRITICAL FIX: Add to tracking map IMMEDIATELY after spawn to prevent orphans
+            // This ensures the process is tracked even if waitForChromeReady fails
+            this.chromeProcesses.set(port, chromeProcess);
+            await debugLog('ChromeLauncher', `Added Chrome process (PID: ${pid}) to tracking map for port ${port}`);
+            // Set up auto-cleanup when process exits (BEFORE waitForChromeReady)
+            // This ensures cleanup happens even if the launch fails later
+            chromeProcess.once('exit', (code, signal) => {
+                debugLog('ChromeLauncher', `Chrome process on port ${port} (PID: ${pid}) exited (code: ${code}, signal: ${signal}), removing from tracking`);
+                this.chromeProcesses.delete(port);
+                // Record the close event with reason
+                const pendingReason = this.pendingCloseReason.get(port);
+                this.pendingCloseReason.delete(port);
+                let reason;
+                if (pendingReason) {
+                    reason = pendingReason;
+                }
+                else if (signal) {
+                    reason = 'signal';
+                }
+                else if (code !== 0 && code !== null) {
+                    reason = 'crash';
+                }
+                else {
+                    reason = 'external'; // Closed externally (user closed browser, etc.)
+                }
+                const closeEvent = this.recordCloseEvent(port, pid || -1, reason, code, signal);
+                // Remove the throwaway profile now that its Chrome is gone. Covers
+                // external closes and crashes as well as killInstance() - bug-007.
+                this.removeProfileDir(port, profile).catch(() => { });
+                // Invoke the exit callback if set (for port re-reservation)
+                if (this.onExitCallback) {
+                    debugLog('ChromeLauncher', `Invoking onExit callback for port ${port}`);
+                    // Don't await - fire and forget to avoid blocking exit handler
+                    Promise.resolve(this.onExitCallback(closeEvent)).catch((err) => {
+                        debugLog('ChromeLauncher', `onExit callback error: ${err}`);
+                    });
+                }
+            });
+            // Handle process errors and unexpected exits
+            let processExited = false;
+            const exitHandler = () => {
+                processExited = true;
+            };
+            chromeProcess.once('exit', exitHandler);
+            chromeProcess.once('error', exitHandler);
+            // Wait for Chrome to actually start and bind to the port
+            await debugLog('ChromeLauncher', `Waiting for Chrome to become ready on port ${port}...`);
+            try {
+                await this.waitForChromeReady(port);
+            }
+            catch (waitError) {
+                await debugLog('ChromeLauncher', `waitForChromeReady failed: ${waitError}`);
+                // Re-reserve the port if we released it (cleanup after failure)
+                if (didReleaseReservation && portReserver) {
+                    try {
+                        await debugLog('ChromeLauncher', `Re-reserving port ${port} after Chrome launch failure`);
+                        await portReserver.reserve(port);
+                        await debugLog('ChromeLauncher', `Successfully re-reserved port ${port}`);
+                    }
+                    catch (reserveError) {
+                        await debugLog('ChromeLauncher', `Failed to re-reserve port ${port}: ${reserveError}`);
+                    }
+                }
+                // Clean up if Chrome failed to start - use SIGKILL for immediate termination
+                if (chromeProcess && !chromeProcess.killed && pid) {
+                    await debugLog('ChromeLauncher', `Force killing orphaned Chrome process (PID: ${pid})`);
+                    try {
+                        chromeProcess.kill('SIGKILL');
+                        // Wait a moment to ensure kill completes
+                        await new Promise(resolve => setTimeout(resolve, 100));
+                    }
+                    catch (killError) {
+                        await debugLog('ChromeLauncher', `Failed to kill orphaned process: ${killError}`);
+                    }
+                }
+                // Remove from tracking map since we're about to throw
+                // (exit handler will also remove it when process dies, but this is defensive)
+                this.chromeProcesses.delete(port);
+                await this.removeProfileDir(port, profile);
+                throw waitError;
+            }
+            // Check if process exited during startup
+            if (processExited) {
+                // Remove from tracking since process is dead
+                this.chromeProcesses.delete(port);
+                throw new Error('Chrome process exited unexpectedly during startup');
+            }
+            // Remove temporary exit handler now that Chrome is confirmed running
+            // (The permanent exit handler was already set up earlier)
+            chromeProcess.removeListener('exit', exitHandler);
+            chromeProcess.removeListener('error', exitHandler);
+            await debugLog('ChromeLauncher', `Chrome successfully started on port ${port} with PID ${pid}`);
+            return { port, pid: pid || -1 };
+        }
+        catch (error) {
+            await debugLog('ChromeLauncher', `Failed to launch Chrome: ${error}`);
+            // Re-reserve the port if we released it (cleanup after any failure)
+            if (didReleaseReservation && portReserver) {
+                try {
+                    await debugLog('ChromeLauncher', `Re-reserving port ${port} after outer catch block failure`);
+                    await portReserver.reserve(port);
+                    await debugLog('ChromeLauncher', `Successfully re-reserved port ${port}`);
+                }
+                catch (reserveError) {
+                    await debugLog('ChromeLauncher', `Failed to re-reserve port ${port}: ${reserveError}`);
+                }
+            }
+            throw new Error(`Failed to launch Chrome: ${error}`);
+        }
+    }
+    /**
+     * Check if a process with the given PID is actually running
+     * This handles the case where Chrome is killed externally (e.g., Activity Monitor, kill command)
+     */
+    isProcessAlive(pid) {
+        try {
+            // process.kill with signal 0 doesn't kill the process, just checks if it exists
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            // ESRCH = No such process, EPERM = exists but no permission (still alive)
+            return false;
+        }
+    }
+    /**
+     * Check if Chrome is running on a specific port, or if any Chrome instance is running
+     * This verifies the process is actually alive, not just tracked
+     */
+    isRunning(port) {
+        if (port !== undefined) {
+            const chromeProcess = this.chromeProcesses.get(port);
+            if (!chromeProcess || chromeProcess.killed) {
+                return false;
+            }
+            // Verify the process is actually alive (handles external kills)
+            const pid = chromeProcess.pid;
+            if (!pid || !this.isProcessAlive(pid)) {
+                // Process is dead but we didn't know - clean up tracking
+                this.chromeProcesses.delete(port);
+                this.recordCloseEvent(port, pid || -1, 'external', null, null);
+                return false;
+            }
+            return true;
+        }
+        // Check if any Chrome instance is running - verify each one
+        for (const [p, chromeProcess] of this.chromeProcesses.entries()) {
+            const pid = chromeProcess.pid;
+            if (pid && this.isProcessAlive(pid)) {
+                return true;
+            }
+            else {
+                // Clean up dead process
+                this.chromeProcesses.delete(p);
+                this.recordCloseEvent(p, pid || -1, 'external', null, null);
+            }
+        }
+        return false;
+    }
+    /**
+     * Get all running Chrome ports
+     */
+    getRunningPorts() {
+        return Array.from(this.chromeProcesses.keys());
+    }
+    /**
+     * Kill Chrome process(es)
+     * If port is specified, kills only that instance. Otherwise kills all instances.
+     * First attempts graceful shutdown with SIGTERM, then force kills with SIGKILL if needed
+     */
+    async kill(port) {
+        if (port !== undefined) {
+            // Kill specific instance
+            await this.killInstance(port);
+        }
+        else {
+            // Kill all instances
+            const ports = Array.from(this.chromeProcesses.keys());
+            await debugLog('ChromeLauncher', `Killing all Chrome instances (${ports.length} total)`);
+            for (const p of ports) {
+                await this.killInstance(p);
+            }
+        }
+    }
+    /**
+     * Kill a specific Chrome instance by port
+     */
+    async killInstance(port) {
+        // Snapshot the profile we are killing *now*: a relaunch on this port can
+        // land between profileDirs.set() and chromeProcesses.set() in
+        // performLaunch(), and deleting whatever profile happens to be tracked by
+        // the time we get around to it would wipe the new launch's fresh dir.
+        // Passing the snapshot as `expected` makes every deletion below a no-op
+        // once someone else owns the port.
+        const profile = this.profileDirs.get(port);
+        const chromeProcess = this.chromeProcesses.get(port);
+        if (!chromeProcess || chromeProcess.killed) {
+            // Nothing to kill, but a profile may still be tracked (e.g. the process
+            // was reaped externally) - make sure it does not leak.
+            if (profile)
+                await this.removeProfileDir(port, profile);
+            return;
+        }
+        const pid = chromeProcess.pid;
+        if (!pid) {
+            this.chromeProcesses.delete(port);
+            if (profile)
+                await this.removeProfileDir(port, profile);
+            return;
+        }
+        await debugLog('ChromeLauncher', `Killing Chrome process on port ${port} (PID: ${pid})`);
+        // Try graceful shutdown first (SIGTERM)
+        try {
+            chromeProcess.kill('SIGTERM');
+            await debugLog('ChromeLauncher', `Sent SIGTERM to Chrome on port ${port} (PID: ${pid})`);
+        }
+        catch (error) {
+            await debugLog('ChromeLauncher', `Failed to send SIGTERM: ${error}`);
+        }
+        // Wait 500ms for graceful shutdown, then force kill if needed
+        await new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                try {
+                    // Check if process still exists using signal 0 (doesn't actually kill)
+                    process.kill(pid, 0);
+                    // Process still exists, force kill
+                    debugLog('ChromeLauncher', `Chrome on port ${port} didn't exit gracefully, sending SIGKILL (PID: ${pid})`);
+                    try {
+                        chromeProcess.kill('SIGKILL');
+                        debugLog('ChromeLauncher', `Sent SIGKILL to Chrome on port ${port} (PID: ${pid})`);
+                    }
+                    catch (killError) {
+                        debugLog('ChromeLauncher', `Failed to send SIGKILL: ${killError}`);
+                    }
+                }
+                catch {
+                    // Process already dead (signal 0 threw error)
+                    debugLog('ChromeLauncher', `Chrome on port ${port} exited gracefully (PID: ${pid})`);
+                }
+                resolve();
+            }, 500);
+            // If process exits before timeout, clear the timeout
+            chromeProcess.once('exit', () => {
+                clearTimeout(timeout);
+                debugLog('ChromeLauncher', `Chrome process on port ${port} exited (PID: ${pid})`);
+                resolve();
+            });
+        });
+        this.chromeProcesses.delete(port);
+        // Chrome is gone (or was force-killed) - drop its throwaway profile,
+        // unless a relaunch has already claimed this port (see snapshot above).
+        if (profile)
+            await this.removeProfileDir(port, profile);
+        await debugLog('ChromeLauncher', `Chrome cleanup complete for port ${port}`);
+    }
+    /**
+     * Build the profile record for a launch on `port`.
+     *
+     * The name embeds the port (only one live Chrome can hold a debug port, so
+     * this alone separates concurrent launches) plus a timestamp and 4 random
+     * bytes (so sequential relaunches on the same port within one millisecond
+     * still differ). Naming on Date.now() alone let same-millisecond launches on
+     * different ports share a profile - bug-006.
+     *
+     * With `profileName` (issue 13) the record is a stable directory under the
+     * persistent profile root and is marked `ephemeral: false`, which every
+     * cleanup path skips. The port is deliberately NOT part of a named profile's
+     * directory: the profile is the identity, the port is just where this run of
+     * it happens to listen.
+     */
+    createProfileRecord(port, profileName) {
+        if (profileName !== undefined) {
+            return { dir: this.getPersistentProfilePath(profileName), ephemeral: false };
+        }
+        const name = `${EPHEMERAL_PROFILE_PREFIX}p${port}-${Date.now()}-${randomBytes(4).toString('hex')}`;
+        return { dir: path.join(this.profileRoot, name), ephemeral: true };
+    }
+    /**
+     * Directory named persistent profiles live under (see
+     * `chrome.persistentProfileRoot`; defaults to `~/.cdp-tools/profiles`).
+     */
+    getPersistentProfileRoot() {
+        return typeof this.persistentProfileRootOption === 'function'
+            ? this.persistentProfileRootOption()
+            : this.persistentProfileRootOption;
+    }
+    /**
+     * Absolute path of a named persistent profile. Does not create it.
+     * @throws InvalidProfileNameError
+     */
+    getPersistentProfilePath(profileName) {
+        return path.join(this.getPersistentProfileRoot(), normalizeProfileName(profileName));
+    }
+    /**
+     * Port of the live Chrome currently holding a named profile, if any.
+     * @throws InvalidProfileNameError
+     */
+    findPortForProfile(profileName) {
+        const dir = this.getPersistentProfilePath(profileName);
+        for (const [port, record] of this.profileDirs.entries()) {
+            if (record.dir === dir && this.isRunning(port)) {
+                return port;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * PID of a live Chrome holding a named persistent profile, if the profile's
+     * SingletonLock says so. Unlike findPortForProfile() this sees Chromes we did
+     * NOT launch (other cdp-tools sessions sharing the global profile root, or a
+     * Chrome started by hand on the same user-data-dir).
+     *
+     * LIMITATION: POSIX-only. It reads the SingletonLock symlink target, which
+     * Windows Chrome does not create - there it always reports "not locked", so
+     * callers must treat a negative result as "no evidence of a holder" rather
+     * than proof the profile is free.
+     *
+     * @throws InvalidProfileNameError
+     */
+    async findProfileLockHolder(profileName) {
+        const dir = this.getPersistentProfilePath(profileName);
+        return this.readProfileLockPid(dir);
+    }
+    /**
+     * Names of persistent profiles that exist on disk.
+     */
+    async listPersistentProfiles() {
+        try {
+            const entries = await fs.promises.readdir(this.getPersistentProfileRoot(), { withFileTypes: true });
+            return entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Wipe a named persistent profile and recreate it empty, so the next launch
+     * starts from a clean browser (no cookies, no IndexedDB, no enrolment).
+     *
+     * Refuses while a Chrome we launched still holds the profile: deleting a
+     * live user-data-dir corrupts the running browser and the deletion would be
+     * partly undone as Chrome flushes state back out on exit. Kill that instance
+     * (`killChrome({ port })`) first.
+     *
+     * Also refuses when the profile's Chrome SingletonLock names a live PID we
+     * did not launch. The default profile root is global (`~/.cdp-tools/profiles`),
+     * so another cdp-tools session may be running this exact profile; without the
+     * lock check this call would rm -rf a live browser's user-data-dir and destroy
+     * the very identity persistent profiles exist to preserve. That check is
+     * POSIX-only (see ProfileLockedError) - on Windows this remains unguarded.
+     *
+     * @throws InvalidProfileNameError | ProfileInUseError | ProfileLockedError
+     */
+    async resetPersistentProfile(profileName) {
+        const name = normalizeProfileName(profileName);
+        const holder = this.findPortForProfile(name);
+        if (holder !== undefined) {
+            throw new ProfileInUseError(name, holder);
+        }
+        const lockPid = await this.findProfileLockHolder(name);
+        if (lockPid !== undefined) {
+            throw new ProfileLockedError(name, lockPid, this.getPersistentProfilePath(name));
+        }
+        const dir = this.getPersistentProfilePath(name);
+        const existed = fs.existsSync(dir);
+        await fs.promises.rm(dir, { recursive: true, force: true });
+        await fs.promises.mkdir(dir, { recursive: true });
+        await debugLog('ChromeLauncher', `Reset persistent profile "${name}" at ${dir} (existed: ${existed})`);
+        return { profile: name, path: dir, existed };
+    }
+    /**
+     * Profile directory currently tracked for a port (if any).
+     */
+    getProfileDir(port) {
+        return this.profileDirs.get(port)?.dir;
+    }
+    /**
+     * All tracked profiles, keyed by port. Persistent profiles are included but
+     * are never deleted by the launcher.
+     */
+    getProfiles() {
+        return new Map(this.profileDirs);
+    }
+    /**
+     * Stop tracking a port's profile and, if it is ephemeral, delete it from disk.
+     *
+     * `expected` guards against a late exit event from a previous Chrome deleting
+     * the freshly created profile of a relaunch on the same port: if the tracked
+     * record is no longer the one we started with, nothing is touched.
+     */
+    async removeProfileDir(port, expected) {
+        const record = this.profileDirs.get(port);
+        if (!record) {
+            return;
+        }
+        if (expected && record !== expected) {
+            // A newer launch owns this port now - leave its profile alone.
+            return;
+        }
+        this.profileDirs.delete(port);
+        if (!record.ephemeral) {
+            // Persistent/named profile (issue 13) - tracking only, never delete.
+            await debugLog('ChromeLauncher', `Keeping persistent profile ${record.dir} for port ${port}`);
+            return;
+        }
+        try {
+            await fs.promises.rm(record.dir, { recursive: true, force: true });
+            await debugLog('ChromeLauncher', `Removed ephemeral profile ${record.dir} for port ${port}`);
+        }
+        catch (error) {
+            await debugLog('ChromeLauncher', `Failed to remove profile ${record.dir}: ${error}`);
+        }
+    }
+    /**
+     * Delete ephemeral profile directories left behind by previous sessions
+     * (crashes, SIGKILL, machine restart). Returns the directories removed.
+     *
+     * Conservative on purpose - a directory is skipped when:
+     *  - it is younger than staleProfileMaxAgeMs (another MCP instance may be
+     *    launching Chrome into it right now), or
+     *  - its Chrome SingletonLock names a PID that is still alive, or
+     *  - it is currently tracked by this launcher.
+     */
+    async sweepStaleProfiles() {
+        const removed = [];
+        let entries;
+        try {
+            entries = await fs.promises.readdir(this.profileRoot, { withFileTypes: true });
+        }
+        catch (error) {
+            await debugLog('ChromeLauncher', `Profile sweep could not read ${this.profileRoot}: ${error}`);
+            return removed;
+        }
+        const inUse = new Set(Array.from(this.profileDirs.values()).map(r => r.dir));
+        const now = Date.now();
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !entry.name.startsWith(EPHEMERAL_PROFILE_PREFIX)) {
+                continue;
+            }
+            const dir = path.join(this.profileRoot, entry.name);
+            if (inUse.has(dir)) {
+                continue;
+            }
+            try {
+                const stats = await fs.promises.stat(dir);
+                if (now - stats.mtimeMs < this.staleProfileMaxAgeMs) {
+                    continue; // Too fresh - may belong to a launch in progress elsewhere
+                }
+            }
+            catch {
+                continue; // Vanished or unreadable - leave it alone
+            }
+            if (await this.isProfileLocked(dir)) {
+                await debugLog('ChromeLauncher', `Profile sweep skipping ${dir} - still locked by a live Chrome`);
+                continue;
+            }
+            try {
+                await fs.promises.rm(dir, { recursive: true, force: true });
+                removed.push(dir);
+            }
+            catch (error) {
+                await debugLog('ChromeLauncher', `Profile sweep failed to remove ${dir}: ${error}`);
+            }
+        }
+        if (removed.length) {
+            await debugLog('ChromeLauncher', `Profile sweep removed ${removed.length} stale profile(s)`);
+        }
+        return removed;
+    }
+    /**
+     * Is a profile directory still held by a running Chrome?
+     * Chrome writes a SingletonLock symlink whose target is "<hostname>-<pid>".
+     * Unreadable/absent lock means "not locked" (Windows uses a plain lockfile).
+     */
+    async isProfileLocked(dir) {
+        return (await this.readProfileLockPid(dir)) !== undefined;
+    }
+    /**
+     * PID named by a profile directory's Chrome SingletonLock, if that process is
+     * still alive. POSIX-only: on Windows the lock is a plain file with no
+     * readable PID, so this always returns undefined ("no evidence of a holder").
+     */
+    async readProfileLockPid(dir) {
+        try {
+            const target = await fs.promises.readlink(path.join(dir, 'SingletonLock'));
+            const pid = Number(target.split('-').pop());
+            return Number.isInteger(pid) && pid > 0 && this.isProcessAlive(pid) ? pid : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Reset the launcher state (useful if Chrome was closed externally)
+     */
+    reset(port) {
+        // Note: profile dirs are only untracked here, never deleted - reset() is a
+        // "forget my state" escape hatch and the Chrome holding the profile may
+        // still be alive. Anything orphaned this way is picked up by the startup
+        // sweep on the next run.
+        if (port !== undefined) {
+            this.chromeProcesses.delete(port);
+            this.profileDirs.delete(port);
+        }
+        else {
+            this.chromeProcesses.clear();
+            this.profileDirs.clear();
+        }
+    }
+    /**
+     * Record a Chrome close event
+     */
+    recordCloseEvent(port, pid, reason, exitCode, signal) {
+        const event = {
+            port,
+            pid,
+            reason,
+            timestamp: new Date(),
+            exitCode,
+            signal,
+        };
+        this.lastCloseEvents.push(event);
+        // Keep only the last N events
+        if (this.lastCloseEvents.length > this.maxCloseEvents) {
+            this.lastCloseEvents.shift();
+        }
+        debugLog('ChromeLauncher', `Recorded close event: port=${port}, pid=${pid}, reason=${reason}, exitCode=${exitCode}, signal=${signal}`);
+        return event;
+    }
+    /**
+     * Get the last close events
+     */
+    getLastCloseEvents() {
+        return [...this.lastCloseEvents];
+    }
+    /**
+     * Get Chrome launcher status for all instances
+     * Verifies each process is actually alive and cleans up dead ones
+     */
+    getStatus() {
+        const instances = [];
+        const deadPorts = [];
+        for (const [port, chromeProcess] of this.chromeProcesses.entries()) {
+            const pid = chromeProcess.pid || -1;
+            const alive = pid > 0 && this.isProcessAlive(pid);
+            if (!alive) {
+                deadPorts.push(port);
+            }
+            instances.push({ port, pid, running: alive });
+        }
+        // Clean up dead processes
+        for (const port of deadPorts) {
+            const chromeProcess = this.chromeProcesses.get(port);
+            const pid = chromeProcess?.pid || -1;
+            this.chromeProcesses.delete(port);
+            this.recordCloseEvent(port, pid, 'external', null, null);
+        }
+        // Return only alive instances
+        return {
+            instances: instances.filter(i => i.running),
+            lastCloseEvents: this.lastCloseEvents
+        };
+    }
+    /**
+     * Set the pending close reason for a port (call before killing)
+     */
+    setPendingCloseReason(port, reason) {
+        this.pendingCloseReason.set(port, reason);
+    }
+}
+//# sourceMappingURL=chrome-launcher.js.map