@phnx-labs/agents-cli 1.18.3 → 1.18.5

package/dist/lib/browser/service.js

@@ -1,16 +1,52 @@
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
 import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from './cdp.js';
-import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, } from './profiles.js';
+import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
 import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
 import { connectLocal } from './drivers/local.js';
 import { connectSSH } from './drivers/ssh.js';
-import { generateTaskId, generateShortId, generateFunName, } from './types.js';
+import { clearProfileRuntime } from './runtime-state.js';
+import { generateTaskId, generateShortId, generateTaskName, } from './types.js';
 import { getRefs, resolveRefToCoords } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
 import { typeEditorText } from './editor.js';
 import { detectUploadPattern, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
 import { emit } from '../events.js';
+/**
+ * Read width/height from a JPEG buffer by walking SOF markers. Returns null
+ * if the buffer doesn't start with the JPEG SOI marker or no SOF segment is
+ * found. We use this on every screenshot so the CLI can surface the actual
+ * captured pixel dimensions (which differ from viewport size at non-1x DPR).
+ */
+function readPngDimensions(buf) {
+    // PNG signature (8 bytes) + IHDR chunk: length (4) + 'IHDR' (4) + width (4) + height (4)
+    if (buf.length < 24)
+        return null;
+    const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+    for (let i = 0; i < 8; i++)
+        if (buf[i] !== sig[i])
+            return null;
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+function readJpegDimensions(buf) {
+    if (buf.length < 4 || buf[0] !== 0xff || buf[1] !== 0xd8)
+        return null;
+    let i = 2;
+    while (i + 9 < buf.length) {
+        if (buf[i] !== 0xff)
+            return null;
+        const marker = buf[i + 1];
+        // SOF0–SOFn carry dimensions, except DHT (0xC4), JPG (0xC8), DAC (0xCC).
+        if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+            return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) };
+        }
+        i += 2 + buf.readUInt16BE(i + 2);
+    }
+    return null;
+}
 /**
  * Parse a `targetFilter` string into its kind + value, or return `null`
  * when the input is missing or malformed. Filter syntax:
@@ -92,7 +128,81 @@ export function pickWindowTarget(targets, filter) {
         return visible;
     return pages[0];
 }
+const execFileP = promisify(execFile);
+/**
+ * Parse a `--since`/`--until` value. Accepts ISO-8601 absolute timestamps
+ * or relative offsets like `30s`, `5m`, `2h`, `1d`.
+ */
+export function parseSinceUntil(s) {
+    const ms = Date.parse(s);
+    if (!isNaN(ms))
+        return new Date(ms);
+    const m = s.match(/^(\d+)([smhd])$/);
+    if (!m)
+        throw new Error(`Invalid since/until: ${s}`);
+    const n = parseInt(m[1], 10);
+    const unitMs = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+    return new Date(Date.now() - n * unitMs[m[2]]);
+}
+async function execSSH(host, cmd) {
+    const { stdout } = await execFileP('ssh', [host, cmd], {
+        timeout: 10_000,
+        maxBuffer: 10_000_000,
+    });
+    return stdout;
+}
+export function readNewestMatchingFile(dir, prefix, tailLines) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return '';
+    }
+    const candidates = entries
+        .filter((f) => f.startsWith(prefix) && f.endsWith('.jsonl'))
+        .map((f) => ({ f, mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime);
+    if (candidates.length === 0)
+        return '';
+    const lines = fs
+        .readFileSync(path.join(dir, candidates[0].f), 'utf8')
+        .split('\n')
+        .filter(Boolean);
+    return lines.slice(-tailLines).join('\n');
+}
+function expandHome(p) {
+    if (p.startsWith('~/'))
+        return path.join(os.homedir(), p.slice(2));
+    if (p === '~')
+        return os.homedir();
+    return p;
+}
+/**
+ * Probe a cached connection before reuse. A WebSocket can quietly transition
+ * to CLOSED without anyone noticing — most commonly when the user kills the
+ * browser process by hand. `Browser.getVersion` is the lightest CDP call we
+ * can make; if it doesn't round-trip within 1s the connection is dead.
+ */
+async function isConnHealthy(conn, timeoutMs = 1000) {
+    if (!conn.cdp.isOpen)
+        return false;
+    try {
+        await Promise.race([
+            conn.cdp.send('Browser.getVersion'),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('healthcheck timeout')), timeoutMs)),
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export class BrowserService {
+    static SOURCE_PREFIX = {
+        'rush-app': 'rush-app-',
+        'rush-cli': 'rush-cli-',
+    };
     connections = new Map();
     forkingProfiles = new Set();
     // Per-task storage for console, errors, network, downloads
@@ -106,39 +216,74 @@ export class BrowserService {
         if (!profile) {
             throw new Error(`Profile "${profileName}" not found`);
         }
-        const taskName = opts.taskName || generateFunName();
+        // Pick the endpoint preset. Throws with the candidate list if the user
+        // passed an unknown name. The composite identifier `<profile>@<endpoint>`
+        // is what the connection map + per-profile runtime dirs are keyed on, so
+        // a single YAML profile can run at multiple endpoints concurrently.
+        const resolved = resolveEndpoint(profile, opts.endpointName);
+        const composite = `${profileName}@${resolved.name}`;
+        const effectiveProfile = {
+            ...profile,
+            name: composite,
+            binary: resolved.binary,
+            targetFilter: resolved.targetFilter,
+        };
+        let taskName;
+        if (opts.taskName) {
+            if (this.hasTaskNamed(opts.taskName)) {
+                throw new Error(`Task "${opts.taskName}" already exists. Pick a different --task name or stop the existing one first.`);
+            }
+            taskName = opts.taskName;
+        }
+        else {
+            taskName = this.generateUniqueTaskName();
+        }
         const taskId = generateTaskId();
-        let conn = this.connections.get(profileName);
-        let effectiveProfileName = profileName;
+        let conn = this.connections.get(composite);
+        let effectiveProfileName = composite;
+        // If we have a cached connection, confirm it's still usable before any
+        // caller relies on it. A browser killed externally (Cmd-Q, crash, or a
+        // user clearing the profile by hand) leaves a closed WebSocket here.
+        // Without this check the next `cdp.send` throws "CDP connection not
+        // open" and the user has no way to recover short of killing the daemon.
+        if (conn && !(await isConnHealthy(conn))) {
+            try {
+                conn.cdp.close();
+            }
+            catch { /* already closed */ }
+            conn.cleanup?.();
+            this.connections.delete(composite);
+            conn = undefined;
+        }
         if (conn && conn.electron && conn.tasks.size > 0) {
-            if (this.forkingProfiles.has(profileName)) {
-                while (this.forkingProfiles.has(profileName)) {
+            if (this.forkingProfiles.has(composite)) {
+                while (this.forkingProfiles.has(composite)) {
                     await new Promise((r) => setTimeout(r, 50));
                 }
-                const existingFork = this.findAvailableFork(profileName);
+                const existingFork = this.findAvailableFork(composite);
                 if (existingFork) {
                     conn = existingFork.conn;
                     effectiveProfileName = existingFork.name;
                 }
                 else {
-                    throw new Error(`Fork in progress but no available fork found for "${profileName}"`);
+                    throw new Error(`Fork in progress but no available fork found for "${composite}"`);
                 }
             }
             else {
-                this.forkingProfiles.add(profileName);
+                this.forkingProfiles.add(composite);
                 try {
-                    const { forkName, connection } = await this.forkElectronProfile(profile);
+                    const { forkName, connection } = await this.forkElectronProfile(effectiveProfile);
                     conn = connection;
                     effectiveProfileName = forkName;
                 }
                 finally {
-                    this.forkingProfiles.delete(profileName);
+                    this.forkingProfiles.delete(composite);
                 }
             }
         }
         else if (!conn) {
-            conn = await this.connectProfile(profile);
-            this.connections.set(profileName, conn);
+            conn = await this.connectProfile(effectiveProfile, resolved.target);
+            this.connections.set(composite, conn);
         }
         const task = {
             id: taskId,
@@ -178,25 +323,7 @@ export class BrowserService {
             const result = await this.navigate(taskName, opts.url, effectiveProfileName);
             tabId = result.tabId;
         }
-        return { task: taskId, name: taskName, tabId };
-    }
-    /**
-     * Launch (or attach to) the profile's browser without creating a task. Used by
-     * `agents browser profiles launch <name>` so users can warm up the browser —
-     * including the first-run onboarding flow — before any automation starts.
-     */
-    async launchProfile(profileName) {
-        const profile = await getProfile(profileName);
-        if (!profile) {
-            throw new Error(`Profile "${profileName}" not found`);
-        }
-        let conn = this.connections.get(profileName);
-        if (!conn) {
-            conn = await this.connectProfile(profile);
-            this.connections.set(profileName, conn);
-        }
-        emit('browser.launch', { profile: profileName, task: '', pid: conn.pid });
-        return { port: conn.port, pid: conn.pid };
+        return { task: taskId, name: taskName, tabId, profile: effectiveProfileName };
     }
     async stop(taskName) {
         for (const [profileName, conn] of this.connections) {
@@ -239,6 +366,7 @@ export class BrowserService {
                 if (conn.forkedFrom && conn.tasks.size === 0) {
                     conn.cdp.close();
                     killChrome(conn.pid);
+                    conn.cleanup?.();
                     this.connections.delete(profileName);
                 }
                 return { ok: true, profile: profileName };
@@ -254,6 +382,7 @@ export class BrowserService {
         if (conn) {
             conn.cdp.close();
             killChrome(conn.pid);
+            conn.cleanup?.();
             this.connections.delete(profileName);
         }
         const runtimeDir = getProfileRuntimeDir(profileName);
@@ -455,7 +584,7 @@ export class BrowserService {
         }
         return result.result.value;
     }
-    async screenshot(taskId, tabHint, outputPath) {
+    async screenshot(taskId, tabHint, outputPath, quality = 'compressed') {
         const { conn, task } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
@@ -464,22 +593,201 @@ export class BrowserService {
             throw new Error(`Tab ${shortId} not found`);
         }
         const sessionId = await this.getSessionId(conn, target.targetId);
-        const { data } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 70 }, sessionId));
-        let buffer = Buffer.from(data, 'base64');
-        const MAX_SIZE = 100 * 1024;
-        if (buffer.length > MAX_SIZE) {
-            let quality = 50;
-            while (buffer.length > MAX_SIZE && quality > 10) {
-                const { data: resized } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality }, sessionId));
-                buffer = Buffer.from(resized, 'base64');
-                quality -= 10;
+        let buffer;
+        let extension;
+        if (quality === 'raw') {
+            // Pixel-faithful PNG, no downscale. For archived QA evidence where
+            // lossy JPEG would hide rendering bugs. Files run 0.5–3 MB.
+            const { data } = (await conn.cdp.send('Page.captureScreenshot', { format: 'png' }, sessionId));
+            buffer = Buffer.from(data, 'base64');
+            extension = 'png';
+        }
+        else {
+            // Default: JPEG quality 70, then iteratively downscale to keep the
+            // file under 100 KB so chat-injected screenshots stay token-cheap.
+            const { data } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 70 }, sessionId));
+            buffer = Buffer.from(data, 'base64');
+            const MAX_SIZE = 100 * 1024;
+            if (buffer.length > MAX_SIZE) {
+                let q = 50;
+                while (buffer.length > MAX_SIZE && q > 10) {
+                    const { data: resized } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: q }, sessionId));
+                    buffer = Buffer.from(resized, 'base64');
+                    q -= 10;
+                }
             }
+            extension = 'jpg';
         }
         const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
-        const finalPath = outputPath || path.join(sessionsDir, `${Date.now()}.jpg`);
+        const finalPath = outputPath || path.join(sessionsDir, `${Date.now()}.${extension}`);
         await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
         await fs.promises.writeFile(finalPath, buffer);
-        return finalPath;
+        const dims = (extension === 'png' ? readPngDimensions(buffer) : readJpegDimensions(buffer)) ??
+            { width: 0, height: 0 };
+        return { path: finalPath, bytes: buffer.length, width: dims.width, height: dims.height };
+    }
+    // ─── Recording ──────────────────────────────────────────────────────────────
+    //
+    // CDP `Page.startScreencast` emits a JPEG frame per `everyNthFrame`. We pipe
+    // those frames into ffmpeg's stdin (image2pipe) and encode to a webm/vp9 file
+    // under `sessions/<task>/recordings/`. A background watcher enforces the
+    // duration + size caps so a forgotten recording can't fill the disk.
+    recordings = new Map();
+    async recordStart(taskId, tabHint, opts = {}) {
+        if (this.recordings.has(taskId)) {
+            throw new Error(`Task "${taskId}" is already recording. Call record stop first.`);
+        }
+        const { conn, task } = await this.findTask(taskId);
+        const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
+        const cdpTargetId = this.getCdpTargetId(task, shortId);
+        const target = await this.getTarget(conn, cdpTargetId);
+        if (!target)
+            throw new Error(`Tab ${shortId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        const fps = opts.fps ?? 5;
+        const durationSec = opts.duration ?? 60;
+        const maxMb = opts.maxMb ?? 25;
+        if (fps < 1 || fps > 30)
+            throw new Error('--fps must be between 1 and 30');
+        if (durationSec < 1 || durationSec > 3600)
+            throw new Error('--duration must be between 1 and 3600 seconds');
+        if (maxMb < 1 || maxMb > 500)
+            throw new Error('--max-mb must be between 1 and 500');
+        const recordingsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name, 'recordings');
+        await fs.promises.mkdir(recordingsDir, { recursive: true });
+        const outputPath = path.join(recordingsDir, `${Date.now()}.webm`);
+        // Resolve ffmpeg lazily so non-recording paths don't pay the import cost.
+        const { spawn } = await import('child_process');
+        const ffmpeg = spawn('ffmpeg', [
+            '-loglevel', 'error',
+            '-f', 'image2pipe',
+            '-framerate', String(fps),
+            '-i', '-',
+            '-c:v', 'libvpx-vp9',
+            '-b:v', '1M',
+            '-pix_fmt', 'yuv420p',
+            '-y',
+            outputPath,
+        ], { stdio: ['pipe', 'ignore', 'pipe'] });
+        // Wait for the spawn to confirm (or fail) before we wire CDP frames into a
+        // dead pipe. ENOENT from a missing ffmpeg surfaces here as a real error
+        // instead of a silently empty .webm.
+        await new Promise((resolve, reject) => {
+            const onError = (err) => {
+                ffmpeg.off('spawn', onSpawn);
+                if (err.code === 'ENOENT') {
+                    reject(new Error('ffmpeg not found on PATH — install via `brew install ffmpeg`'));
+                }
+                else {
+                    reject(err);
+                }
+            };
+            const onSpawn = () => {
+                ffmpeg.off('error', onError);
+                resolve();
+            };
+            ffmpeg.once('error', onError);
+            ffmpeg.once('spawn', onSpawn);
+        });
+        // Surface ffmpeg's own diagnostics (encoder error, etc.) in case stderr
+        // arrives after spawn.
+        ffmpeg.stderr?.on('data', () => { });
+        ffmpeg.on('error', () => { });
+        // 30 fps is CDP's screencast cap; everyNthFrame = round(30/fps).
+        const everyNthFrame = Math.max(1, Math.round(30 / fps));
+        await conn.cdp.send('Page.startScreencast', { format: 'jpeg', quality: 60, everyNthFrame }, sessionId);
+        const frameHandler = (params) => {
+            const p = params;
+            try {
+                ffmpeg.stdin?.write(Buffer.from(p.data, 'base64'));
+            }
+            catch {
+                // ffmpeg exited; ignore writes
+            }
+            // Must ack every frame or CDP stops sending.
+            conn.cdp.send('Page.screencastFrameAck', { sessionId: p.sessionId }, sessionId).catch(() => { });
+        };
+        conn.cdp.on('Page.screencastFrame', frameHandler);
+        const durationMs = durationSec * 1000;
+        const maxBytes = maxMb * 1024 * 1024;
+        const state = {
+            outputPath,
+            startedAt: Date.now(),
+            fps,
+            durationMs,
+            maxBytes,
+            ffmpeg,
+            sessionId,
+            conn,
+            frameHandler,
+            durationTimer: setTimeout(() => {
+                this.recordStop(taskId, 'duration-cap').catch(() => { });
+            }, durationMs),
+            sizeCheckInterval: setInterval(async () => {
+                try {
+                    const st = await fs.promises.stat(outputPath);
+                    if (st.size >= maxBytes) {
+                        await this.recordStop(taskId, 'size-cap');
+                    }
+                }
+                catch {
+                    // File may not exist yet
+                }
+            }, 1000),
+        };
+        this.recordings.set(taskId, state);
+        return { path: outputPath, fps, durationCapSec: durationSec, maxMb };
+    }
+    async recordStop(taskId, reason = 'manual') {
+        const rec = this.recordings.get(taskId);
+        if (!rec) {
+            throw new Error(`Task "${taskId}" is not currently recording`);
+        }
+        if (rec.stopReason) {
+            // Already stopping (e.g. size-cap fired while user also called stop).
+            // Wait for in-flight finalize.
+            while (this.recordings.has(taskId)) {
+                await new Promise((r) => setTimeout(r, 25));
+            }
+        }
+        rec.stopReason = reason;
+        clearTimeout(rec.durationTimer);
+        clearInterval(rec.sizeCheckInterval);
+        rec.conn.cdp.off('Page.screencastFrame', rec.frameHandler);
+        try {
+            await rec.conn.cdp.send('Page.stopScreencast', {}, rec.sessionId);
+        }
+        catch {
+            // session may already be gone
+        }
+        // Close ffmpeg stdin so it flushes the output file cleanly.
+        await new Promise((resolve) => {
+            rec.ffmpeg.on('exit', () => resolve());
+            try {
+                rec.ffmpeg.stdin?.end();
+            }
+            catch {
+                resolve();
+            }
+            setTimeout(resolve, 5000); // Hard timeout if ffmpeg hangs
+        });
+        let bytes = 0;
+        try {
+            const st = await fs.promises.stat(rec.outputPath);
+            bytes = st.size;
+        }
+        catch {
+            // ffmpeg may have failed; file missing
+        }
+        const durationMs = Date.now() - rec.startedAt;
+        this.recordings.delete(taskId);
+        return { path: rec.outputPath, bytes, durationMs, reason };
+    }
+    async recordStatus(taskId) {
+        const rec = this.recordings.get(taskId);
+        if (!rec)
+            return { recording: false };
+        return { recording: true, path: rec.outputPath, elapsedMs: Date.now() - rec.startedAt };
     }
     refsCache = new Map();
     async refs(taskId, tabHint, opts = {}) {
@@ -868,6 +1176,46 @@ export class BrowserService {
         }
         throw new Error(`No response matching "${urlPattern}" within ${timeout}ms`);
     }
+    // ─── App Logs (source-side JSONL) ───────────────────────────────────────────
+    async getAppLogs(taskId, opts) {
+        const { task } = await this.findTask(taskId);
+        const baseProfileName = task.profile.split('@')[0];
+        const profile = await getProfile(baseProfileName);
+        if (!profile?.logDir) {
+            throw new Error(`Profile '${task.profile}' has no logDir set`);
+        }
+        const logDir = expandHome(profile.logDir);
+        const sources = opts.source ? [opts.source] : ['rush-app', 'rush-cli'];
+        const since = opts.since ? parseSinceUntil(opts.since) : null;
+        const until = opts.until ? parseSinceUntil(opts.until) : null;
+        const tailN = since ? 100_000 : (opts.lines ?? 200);
+        const raws = await Promise.all(sources.map(async (src) => {
+            const prefix = BrowserService.SOURCE_PREFIX[src];
+            if (!prefix)
+                return '';
+            if (profile.logHost) {
+                return execSSH(profile.logHost, `ls -1t ${logDir}/${prefix}*.jsonl 2>/dev/null | head -1 | xargs -r tail -n ${tailN}`);
+            }
+            return readNewestMatchingFile(logDir, prefix, tailN);
+        }));
+        const entries = raws
+            .flatMap((r) => r.split('\n').filter(Boolean))
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return { raw: line };
+            }
+        })
+            .filter((e) => !opts.level || e.level === opts.level)
+            .filter((e) => !opts.message || e.message === opts.message)
+            .filter((e) => !opts.filter || JSON.stringify(e).includes(opts.filter))
+            .filter((e) => !since || (e.timestamp && new Date(e.timestamp) >= since))
+            .filter((e) => !until || (e.timestamp && new Date(e.timestamp) <= until))
+            .sort((a, b) => new Date(a.timestamp ?? 0).getTime() - new Date(b.timestamp ?? 0).getTime());
+        return since ? entries : entries.slice(-(opts.lines ?? 200));
+    }
     // ─── Wait Conditions ─────────────────────────────────────────────────────────
     async wait(taskId, type, value, options = {}) {
         const timeout = options.timeout ?? 30000;
@@ -969,8 +1317,37 @@ export class BrowserService {
         return undefined;
     }
     async shutdown() {
+        // Drain any in-flight recordings first so we don't orphan ffmpeg processes
+        // or leak the duration/size-check timers when the daemon goes down.
+        for (const [taskId, rec] of this.recordings) {
+            clearTimeout(rec.durationTimer);
+            clearInterval(rec.sizeCheckInterval);
+            try {
+                rec.conn.cdp.off('Page.screencastFrame', rec.frameHandler);
+            }
+            catch { /* socket may be gone */ }
+            try {
+                rec.ffmpeg.stdin?.end();
+            }
+            catch { /* already closed */ }
+            // Give ffmpeg up to 1s to flush; then SIGKILL.
+            const exited = await new Promise((resolve) => {
+                let done = false;
+                rec.ffmpeg.once('exit', () => { done = true; resolve(true); });
+                setTimeout(() => { if (!done)
+                    resolve(false); }, 1000);
+            });
+            if (!exited) {
+                try {
+                    rec.ffmpeg.kill('SIGKILL');
+                }
+                catch { /* already dead */ }
+            }
+            this.recordings.delete(taskId);
+        }
         for (const [, conn] of this.connections) {
             conn.cdp.close();
+            conn.cleanup?.();
         }
         this.connections.clear();
     }
@@ -990,7 +1367,7 @@ export class BrowserService {
         const forkName = `${profile.name}.${forkNum}`;
         const port = allocatePort();
         const chromeOpts = { ...profile.chrome, viewport: profile.viewport };
-        const { pid, wsUrl } = await launchBrowser(forkName, profile.browser, port, chromeOpts, profile.secrets, profile.binary);
+        const { pid, wsUrl } = await launchBrowser(forkName, profile.browser, port, chromeOpts, profile.secrets, profile.binary, profile.electron === true);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
         await this.enableDomains(cdp);
@@ -1007,39 +1384,50 @@ export class BrowserService {
         this.connections.set(forkName, connection);
         return { forkName, connection };
     }
-    async connectProfile(profile) {
-        const existingInfo = getRunningChromeInfo(profile.name);
+    /**
+     * Connect to a profile at a specific endpoint preset. The caller has
+     * already resolved the endpoint and built the `effectiveProfile` with
+     * the per-endpoint binary/targetFilter overrides applied; we just use it.
+     *
+     * `effectiveProfile.name` is the composite identifier (`<profile>@<endpoint>`)
+     * so per-endpoint pid/port files don't collide when the same app runs
+     * locally and remotely at the same time.
+     */
+    async connectProfile(effectiveProfile, target) {
+        const existingInfo = getRunningChromeInfo(effectiveProfile.name);
         if (existingInfo) {
-            const { wsUrl, browser } = await discoverBrowserWsUrl(existingInfo.port);
-            verifyBrowserIdentity(browser, profile.browser, existingInfo.port);
-            const cdp = new CDPClient();
-            await cdp.connect(wsUrl);
-            await this.enableDomains(cdp);
-            const tasks = this.loadTaskState(profile.name);
-            return {
-                cdp,
-                port: existingInfo.port,
-                pid: existingInfo.pid,
-                electron: profile.electron,
-                targetFilter: profile.targetFilter,
-                tasks,
-                sessionCache: new Map(),
-            };
-        }
-        for (const endpoint of profile.endpoints) {
             try {
-                const conn = await this.connectEndpoint(profile, endpoint);
-                if (conn)
-                    return conn;
+                const { wsUrl, browser } = await discoverBrowserWsUrl(existingInfo.port);
+                verifyBrowserIdentity(browser, effectiveProfile.browser, existingInfo.port);
+                const cdp = new CDPClient();
+                await cdp.connect(wsUrl);
+                await this.enableDomains(cdp);
+                const tasks = this.loadTaskState(effectiveProfile.name);
+                return {
+                    cdp,
+                    port: existingInfo.port,
+                    pid: existingInfo.pid,
+                    electron: effectiveProfile.electron,
+                    targetFilter: effectiveProfile.targetFilter,
+                    tasks,
+                    sessionCache: new Map(),
+                };
             }
             catch (err) {
-                if (err instanceof Error && err.message.startsWith('Browser identity mismatch')) {
-                    throw err;
-                }
-                // Try next endpoint
+                // pid file says a process is alive on that port, but nothing is
+                // actually responding to CDP — most commonly because the user
+                // changed the configured endpoint port after a previous launch,
+                // or because the OS reused the pid for an unrelated process.
+                // Wipe the stale runtime files and fall through to a fresh
+                // connect against the profile's currently-configured endpoint.
+                clearProfileRuntime(effectiveProfile.name);
             }
         }
-        throw new Error(`Could not connect to any endpoint for profile "${profile.name}"`);
+        const conn = await this.connectEndpoint(effectiveProfile, target);
+        if (!conn) {
+            throw new Error(`Could not connect to endpoint ${target} for profile "${effectiveProfile.name}"`);
+        }
+        return conn;
     }
     async connectEndpoint(profile, endpoint) {
         const url = new URL(endpoint);
@@ -1067,6 +1455,7 @@ export class BrowserService {
                 targetFilter: profile.targetFilter,
                 tasks: new Map(),
                 sessionCache: new Map(),
+                cleanup: conn.cleanup,
             };
         }
         if (url.protocol === 'wss:' || url.protocol === 'ws:') {
@@ -1143,6 +1532,21 @@ export class BrowserService {
         conn.windowId = result.targetId;
         return result.targetId;
     }
+    hasTaskNamed(name) {
+        for (const conn of this.connections.values()) {
+            if (conn.tasks.has(name))
+                return true;
+        }
+        return false;
+    }
+    generateUniqueTaskName() {
+        for (let attempt = 0; attempt < 8; attempt++) {
+            const candidate = generateTaskName();
+            if (!this.hasTaskNamed(candidate))
+                return candidate;
+        }
+        throw new Error('Could not generate unique task name after 8 attempts');
+    }
     async findTask(taskId, profileName) {
         if (profileName) {
             const conn = this.connections.get(profileName);