@aexol/spectral 0.9.211 → 0.9.215

package/dist/extensions/browser/browser-service.js

@@ -1,7 +1,210 @@
 import { createRequire } from "node:module";
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { registerSessionResourceCleanup } from "../../sdk/ai/session-resources.js";
 import { getBrowserConfig } from "./config.js";
 const _require = createRequire(import.meta.url);
+/**
+ * Unique switch added to every browser we launch. Playwright's `Browser` does
+ * not expose its child process (`process()` only exists on BrowserServer), so
+ * this marker lets us find the exact Chromium process tree we spawned (and
+ * nothing else) with `ps` when we have to SIGKILL it.
+ */
+const BROWSER_MARKER = "--spectral-browser-token=";
+/** `ps -eo pid,ppid,args` easily exceeds execSync's 1 MB default (ENOBUFS). */
+const PS_MAX_BUFFER = 32 * 1024 * 1024;
+/**
+ * How long a launch-time marker verification stays trustworthy on platforms
+ * that cannot re-verify synchronously (no `/proc`, i.e. macOS/Windows). Past
+ * that point the exit handler skips the SIGKILL: an orphaned browser window is
+ * annoying, SIGKILLing an unrelated process that reused the pid is not.
+ */
+const PID_VERIFY_TTL_MS = 15 * 60 * 1000;
+function newBrowserToken() {
+    return `${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/** Windows has no `ps`; probed once and cached. */
+let psAvailable = null;
+let psWarned = false;
+function hasPs() {
+    if (psAvailable !== null)
+        return psAvailable;
+    try {
+        execSync(`ps -o pid= -p ${process.pid}`, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 64 * 1024,
+        });
+        psAvailable = true;
+    }
+    catch {
+        psAvailable = false;
+        process.stderr.write("[browser] `ps` is unavailable on this platform — browser processes cannot be located by marker; only graceful close is possible.\n");
+    }
+    return psAvailable;
+}
+function warnPsFailure(err) {
+    if (psWarned)
+        return;
+    psWarned = true;
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[browser] Could not read the process table (${msg}).\n`);
+}
+/** Never SIGKILL init/pid 1, ourselves, our parent or garbage pids. */
+function isKillablePid(pid) {
+    return (typeof pid === "number" &&
+        Number.isFinite(pid) &&
+        pid > 1 &&
+        pid !== process.pid &&
+        pid !== process.ppid);
+}
+/**
+ * Identity check performed immediately before a SIGKILL: confirms the pid still
+ * runs *our* browser (pid reuse would otherwise make us kill an unrelated
+ * process). Without `ps` we cannot verify and fall back to a best-effort kill.
+ */
+function pidHasMarker(pid, marker) {
+    if (!hasPs())
+        return true;
+    try {
+        const out = execSync(`ps -o args= -p ${pid}`, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: PS_MAX_BUFFER,
+        });
+        return out.includes(marker);
+    }
+    catch {
+        // ESRCH (gone) or EPERM — in both cases we must not signal it.
+        return false;
+    }
+}
+/**
+ * Liveness probe only — no subprocess, no signal delivered. Used to skip the
+ * (expensive) marker lookups for pids that are already gone, which is the
+ * normal case after a graceful `browser.close()`.
+ */
+function pidAlive(pid) {
+    if (!isKillablePid(pid))
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Marker verification without `execSync`, so it is usable from an `exit`
+ * handler: reads `/proc/<pid>/cmdline` (Linux). Returns `null` when the
+ * platform cannot answer synchronously (no `/proc`) — the caller then decides
+ * whether the launch-time evidence is still good enough.
+ */
+let procfsAvailable = null;
+function hasProcfs() {
+    if (procfsAvailable !== null)
+        return procfsAvailable;
+    try {
+        procfsAvailable = readFileSync("/proc/self/cmdline", "utf8").length > 0;
+    }
+    catch {
+        procfsAvailable = false;
+    }
+    return procfsAvailable;
+}
+function pidHasMarkerSync(pid, marker) {
+    if (!hasProcfs())
+        return null;
+    try {
+        // argv is NUL-separated there; a substring match is enough for our marker.
+        return readFileSync(`/proc/${pid}/cmdline`, "utf8").includes(marker);
+    }
+    catch {
+        // ENOENT/ESRCH/EPERM — never signal what we cannot confirm is ours.
+        return false;
+    }
+}
+/**
+ * SIGKILL `pid` if it is still alive. Never throws and never spawns a child
+ * process, so it is safe from `process.on("exit")` / signal handlers.
+ */
+function killPidSync(pid) {
+    if (!pidAlive(pid))
+        return;
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        /* it died between the probe and the kill — nothing to do */
+    }
+}
+/** SIGKILL `pid` if it is alive and (when `marker` is given) still ours. */
+function killPid(pid, marker) {
+    // Free probe first: a dead pid needs no `ps` lookup at all.
+    if (!pidAlive(pid))
+        return;
+    if (marker && !pidHasMarker(pid, marker))
+        return;
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        /* it died between the probe and the kill — nothing to do */
+    }
+}
+/** Snapshot of the process table. Returns [] (and never throws) when `ps` is missing. */
+function psRows() {
+    if (!hasPs())
+        return [];
+    let out = "";
+    try {
+        out = execSync("ps -eo pid,ppid,args", {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: PS_MAX_BUFFER,
+            timeout: 10_000,
+        });
+    }
+    catch (err) {
+        warnPsFailure(err);
+        return [];
+    }
+    const rows = [];
+    for (const line of out.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // First column must be a pid — skips the header row and wrapped lines.
+        const firstSpace = trimmed.indexOf(" ");
+        if (firstSpace <= 0)
+            continue;
+        const pid = Number.parseInt(trimmed.slice(0, firstSpace), 10);
+        if (!Number.isFinite(pid))
+            continue;
+        const rest = trimmed.slice(firstSpace + 1).trimStart();
+        const secondSpace = rest.indexOf(" ");
+        if (secondSpace <= 0)
+            continue;
+        const ppid = Number.parseInt(rest.slice(0, secondSpace), 10);
+        if (!Number.isFinite(ppid))
+            continue;
+        rows.push({ pid, ppid, args: rest.slice(secondSpace + 1) });
+    }
+    return rows;
+}
+/**
+ * Argv for a launch. Chromium ignores unknown switches, so the marker is
+ * harmless there; Firefox/WebKit parse argv strictly and may refuse to start on
+ * an unknown switch, so they get plain args (they can then only be killed
+ * through graceful close or a pid exposed by `browser.process()`).
+ */
+function launchArgsFor(browserName, token) {
+    const base = ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"];
+    if (browserName !== "chromium" || !token)
+        return base;
+    return [`${BROWSER_MARKER}${token}`, ...base];
+}
 let _pw = null;
 let _pwError = null;
 let _preflightResult = null;
@@ -28,6 +231,95 @@ let unregisterInstanceCleanup = null;
 // cannot itself await (it is invoked synchronously from session.dispose()).
 let pendingClose = null;
 let closeAllPromise = null;
+function isBrowserConnected(browser) {
+    if (!browser)
+        return false;
+    try {
+        return browser.isConnected();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * All live owners, not a single slot: two BrowserService instances (e.g. after
+ * resetInstance()) must both be cleaned up, otherwise the older browser is left
+ * orphaned when the newer one detaches the shared handler.
+ */
+const processCleanups = new Set();
+let cleanupHandlersAttached = false;
+let cleanupOnExit = null;
+let cleanupOnSignal = null;
+/**
+ * Safety net: synchronously SIGKILL the browser process if the host process
+ * exits (or is interrupted) while a browser is still attached — otherwise the
+ * Chromium window survives the CLI. Only one set of handlers is ever attached
+ * (shared by every owner) and it is detached again once the last owner is
+ * released, so no listeners accumulate.
+ */
+function attachProcessCleanup(owner, kill) {
+    for (const existing of processCleanups) {
+        if (existing.owner === owner) {
+            existing.kill = kill;
+            return;
+        }
+    }
+    processCleanups.add({ owner, kill });
+    if (cleanupHandlersAttached)
+        return;
+    cleanupHandlersAttached = true;
+    cleanupOnExit = () => {
+        runProcessCleanup();
+    };
+    cleanupOnSignal = (sig) => {
+        runProcessCleanup();
+        // Never swallow the signal: if nothing else handles it, re-raise it so the
+        // process still terminates exactly like it would without our handler.
+        if (process.listenerCount(sig) === 0) {
+            try {
+                process.kill(process.pid, sig);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    };
+    process.once("exit", cleanupOnExit);
+    process.once("SIGINT", cleanupOnSignal);
+    process.once("SIGTERM", cleanupOnSignal);
+}
+function runProcessCleanup() {
+    for (const entry of [...processCleanups]) {
+        try {
+            entry.kill();
+        }
+        catch {
+            /* never let cleanup throw */
+        }
+    }
+}
+function releaseProcessCleanup(owner) {
+    if (owner) {
+        for (const entry of [...processCleanups]) {
+            if (entry.owner === owner)
+                processCleanups.delete(entry);
+        }
+    }
+    else {
+        processCleanups.clear();
+    }
+    if (processCleanups.size > 0 || !cleanupHandlersAttached)
+        return;
+    if (cleanupOnExit)
+        process.off("exit", cleanupOnExit);
+    if (cleanupOnSignal) {
+        process.off("SIGINT", cleanupOnSignal);
+        process.off("SIGTERM", cleanupOnSignal);
+    }
+    cleanupHandlersAttached = false;
+    cleanupOnExit = null;
+    cleanupOnSignal = null;
+}
 export class BrowserService {
     browser = null;
     context = null;
@@ -41,6 +333,33 @@ export class BrowserService {
     _recording = null;
     closePromise = null;
     launchLock = null;
+    /** Unique marker identifying the process tree of the current launch. */
+    launchToken = null;
+    /**
+     * Token of the current *or previous* launch — only cleared by the next
+     * launch. Post-close fallbacks (`forceKillBrowserProcess()` / `browser_quit`)
+     * still need it to find the process tree after `close()` nulled launchToken.
+     * Every kill through this token is marker-verified first, so a recycled pid
+     * is never signalled.
+     */
+    lastLaunchToken = null;
+    /**
+     * Root pid + full marker-matched tree, resolved once after a successful
+     * launch (single `ps` call) so exit/signal handlers can SIGKILL without
+     * running `execSync` from inside the handler.
+     */
+    browserPid = null;
+    browserPids = [];
+    /**
+     * Evidence for the synchronous teardown path: the pids that were matched by
+     * *our* marker at launch time, when they were matched and under which token.
+     * `killBrowserProcessSync()` may only signal pids listed here — a pid that we
+     * never marker-verified (or that no longer carries the marker) can belong to
+     * somebody else by now.
+     */
+    verifiedBrowserPids = [];
+    verifiedBrowserPidsAt = 0;
+    verifiedBrowserPidsToken = null;
     constructor(config) {
         this.config = { ...getBrowserConfig(), ...config };
     }
@@ -71,11 +390,24 @@ export class BrowserService {
     static resetInstance() {
         unregisterInstanceCleanup?.();
         unregisterInstanceCleanup = null;
+        const previous = instance;
         instance = null;
         pendingClose = null;
         closeAllPromise = null;
         _preflightResult = null;
         _pwError = null;
+        // Never orphan the browser owned by the discarded instance: SIGKILL its
+        // process tree and detach its process handlers synchronously (the old
+        // instance is unreachable afterwards, so graceful close would never run).
+        if (previous) {
+            try {
+                previous.killBrowserProcess();
+            }
+            catch {
+                /* never let cleanup throw */
+            }
+            releaseProcessCleanup(previous);
+        }
     }
     /**
      * Close the active browser singleton (if any) and await completion. Unlike
@@ -162,13 +494,11 @@ export class BrowserService {
         const doLaunch = async () => {
             await this.close();
             const pw = loadPlaywright();
+            this.launchToken = newBrowserToken();
+            this.lastLaunchToken = this.launchToken;
             const launchOptions = {
                 headless: this.config.headless,
-                args: [
-                    "--no-sandbox",
-                    "--disable-setuid-sandbox",
-                    "--disable-dev-shm-usage",
-                ],
+                args: launchArgsFor(this.config.browserName, this.launchToken),
             };
             switch (this.config.browserName) {
                 case "firefox":
@@ -180,6 +510,10 @@ export class BrowserService {
                 default:
                     this.browser = await pw.chromium.launch(launchOptions);
             }
+            // Guarantee the browser process is killed even if the host process dies
+            // before close() ever runs.
+            this.resolveBrowserPids(this.launchToken);
+            attachProcessCleanup(this, () => this.killBrowserProcessSync());
             this.context = await this.browser.newContext({
                 viewport: this.config.viewport,
             });
@@ -241,16 +575,51 @@ export class BrowserService {
         return { url: page.url(), title: await page.title() };
     }
     async closePage() {
+        const openBlankPage = async () => {
+            if (!this.context) {
+                this.pages = [];
+                this.activePageIndex = 0;
+                return;
+            }
+            try {
+                const newPage = await this.context.newPage();
+                this.trackNetworkRequest(newPage);
+                this.installDialogInterceptor(newPage);
+                this.pages = [newPage];
+            }
+            catch {
+                this.pages = [];
+            }
+            this.activePageIndex = 0;
+        };
+        // Nothing is open — do not blow up with "cannot read property close of
+        // undefined"; just make sure a blank page is available again.
+        if (this.pages.length === 0) {
+            await openBlankPage();
+            return;
+        }
+        if (this.activePageIndex < 0 || this.activePageIndex >= this.pages.length) {
+            this.activePageIndex = 0;
+        }
         const page = this.pages[this.activePageIndex];
-        await page.close();
+        if (!page) {
+            await openBlankPage();
+            return;
+        }
+        try {
+            await page.close();
+        }
+        catch (e) {
+            // The page/window may already be gone (closed by the user or the tab
+            // crashed) — keep cleaning up instead of surfacing a confusing error.
+            process.stderr.write(`[browser] closePage: ${e.message}\n`);
+        }
         this.pages.splice(this.activePageIndex, 1);
-        if (this.pages.length === 0 && this.context) {
-            const newPage = await this.context.newPage();
-            this.pages = [newPage];
-            this.activePageIndex = 0;
+        if (this.pages.length === 0) {
+            await openBlankPage();
         }
         else {
-            this.activePageIndex = Math.min(this.activePageIndex, this.pages.length - 1);
+            this.activePageIndex = Math.max(0, Math.min(this.activePageIndex, this.pages.length - 1));
         }
     }
     async resize(width, height) {
@@ -378,39 +747,224 @@ export class BrowserService {
         if (this.closePromise)
             return this.closePromise;
         this.closePromise = (async () => {
-            const withTimeout = async (promise, ms, label) => {
+            const withTimeout = async (promise, ms, label, onTimeout) => {
+                let timer;
                 try {
                     return await Promise.race([
                         promise,
-                        new Promise((_, reject) => setTimeout(() => reject(new Error(`Timed out after ${ms}ms: ${label}`)), ms))
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => reject(new Error(`Timed out after ${ms}ms: ${label}`)), ms);
+                        })
                     ]);
                 }
                 catch (e) {
-                    process.stderr.write(`[browser] close ${label}: ${e.message}\n`);
+                    const msg = e.message ?? "";
+                    // A timeout is a failed close too: browser.close() is still hanging
+                    // and the process must be SIGKILLed, exactly like a rejection.
+                    if (msg.startsWith("Timed out after"))
+                        onTimeout?.();
+                    process.stderr.write(`[browser] close ${label}: ${msg}\n`);
+                }
+                finally {
+                    if (timer)
+                        clearTimeout(timer);
                 }
             };
             const closeTimeout = 5000; // 5 seconds per operation
-            for (const page of [...this.pages]) {
-                await withTimeout(page.close().catch(() => { }), closeTimeout, 'page.close()');
-            }
-            this.pages = [];
-            this.activePageIndex = 0;
+            const browser = this.browser;
             const context = this.context;
-            this.context = null;
-            if (context) {
-                await withTimeout(context.close().catch(() => { }), closeTimeout, 'context.close()');
+            let browserCloseFailed = false;
+            try {
+                for (const page of [...this.pages]) {
+                    await withTimeout(page.close().catch(() => { }), closeTimeout, 'page.close()');
+                }
+                this.pages = [];
+                this.activePageIndex = 0;
+                this.context = null;
+                if (context) {
+                    await withTimeout(context.close().catch(() => { }), closeTimeout, 'context.close()');
+                }
+                this.browser = null;
+                if (browser) {
+                    await withTimeout(browser.close().catch((e) => {
+                        browserCloseFailed = true;
+                        process.stderr.write(`[browser] close browser.close(): ${e.message}\n`);
+                    }), closeTimeout, 'browser.close()', () => {
+                        browserCloseFailed = true;
+                    });
+                }
             }
-            const browser = this.browser;
-            this.browser = null;
-            if (browser) {
-                await withTimeout(browser.close().catch(() => { }), closeTimeout, 'browser.close()');
+            finally {
+                // browser.close() may have thrown, timed out or been abandoned — in
+                // that case the Chromium process is still alive and would be left
+                // orphaned, so SIGKILL it directly. A known launch token alone is not
+                // evidence of a live process, but the browser object may still expose
+                // one, so the kill is still attempted — just without the expensive
+                // process-table scan (see `scanProcessTable`).
+                const token = this.launchToken ?? this.lastLaunchToken;
+                const hasKnownPids = this.browserPid !== null || this.browserPids.length > 0;
+                // Anything in here means "there may still be a browser process".
+                const mayStillBeAlive = browserCloseFailed || isBrowserConnected(browser) || hasKnownPids;
+                if (browser && (mayStillBeAlive || token)) {
+                    this.killBrowserProcess(browser, { scanProcessTable: mayStillBeAlive });
+                }
+                // Graceful close confirmed: forget the resolved pids so a later exit
+                // handler can never SIGKILL a recycled pid.
+                if (!browserCloseFailed && !isBrowserConnected(browser)) {
+                    this.browserPid = null;
+                    this.browserPids = [];
+                    this.verifiedBrowserPids = [];
+                    this.verifiedBrowserPidsAt = 0;
+                    this.verifiedBrowserPidsToken = null;
+                }
+                releaseProcessCleanup(this);
+                this.pages = [];
+                this.activePageIndex = 0;
+                this.context = null;
+                this.browser = null;
+                this.launchToken = null;
+                // lastLaunchToken is intentionally kept (see field docs).
+                this._recording = null;
             }
-            this._recording = null;
         })().finally(() => {
             this.closePromise = null;
         });
         return this.closePromise;
     }
+    /**
+     * Last-resort teardown used by the `browser_quit` tool: SIGKILL the browser
+     * process without waiting for a graceful close. Safe to call at any time.
+     */
+    forceKillBrowserProcess() {
+        this.killBrowserProcess();
+    }
+    /**
+     * SIGKILL the browser process behind `browser` (defaults to the live one).
+     * `browser.close()` can hang, be rejected or be abandoned while the host
+     * process is shutting down, which leaves a visible Chromium window behind.
+     *
+     * `opts.scanProcessTable === false` skips `findBrowserPids()` (a `ps -eo`
+     * fork) — use it when nothing indicates a live browser. Only pids we already
+     * know about (or the one `browser.process()` exposes) are then signalled,
+     * each still marker-verified before the SIGKILL.
+     */
+    killBrowserProcess(browser = this.browser, opts) {
+        try {
+            const token = this.launchToken ?? this.lastLaunchToken;
+            const marker = token ? `${BROWSER_MARKER}${token}` : undefined;
+            // `process()` only exists on BrowserServer/ElectronApplication, but keep
+            // using it whenever it is available.
+            const proc = browser
+                ?.process?.();
+            const directPid = proc?.pid ?? null;
+            // Locate the whole tree via the unique marker we passed to launch() —
+            // children (renderer/GPU/utility) inherit the switch, so they die too.
+            // Never kill unrelated Chrome instances: killPid() re-checks the marker.
+            const targets = new Set(this.browserPids);
+            if (opts?.scanProcessTable !== false) {
+                for (const found of this.findBrowserPids())
+                    targets.add(found);
+            }
+            const root = directPid ?? this.browserPid;
+            if (root)
+                targets.add(root);
+            // Children first, root last: the root cannot respawn anything after it
+            // receives SIGKILL.
+            const ordered = [...targets].sort((a, b) => Number(b === root) - Number(a === root));
+            for (const pid of ordered)
+                killPid(pid, marker);
+            this.browserPid = null;
+            this.browserPids = [];
+        }
+        catch {
+            /* never let cleanup throw */
+        }
+    }
+    /**
+     * Exit/signal-handler path: SIGKILL the pids resolved right after launch.
+     * Deliberately execSync-free — spawning `ps` from inside an `exit` handler is
+     * unreliable (and can silently no-op).
+     *
+     * Never signals a pid that may not be ours: only pids whose marker was
+     * verified at launch time are eligible, and each candidate still has to pass
+     * a synchronous identity check — a `process.kill(pid, 0)` probe plus, where
+     * the platform allows it, a `/proc/<pid>/cmdline` read. Where no synchronous
+     * verification exists (no `/proc`), the launch-time evidence is trusted only
+     * while it is fresh (`PID_VERIFY_TTL_MS`): an orphaned browser window is
+     * preferable to SIGKILLing a recycled pid that now belongs to someone else.
+     */
+    killBrowserProcessSync() {
+        try {
+            const verified = new Set(this.verifiedBrowserPids);
+            if (verified.size === 0)
+                return;
+            const token = this.verifiedBrowserPidsToken ?? this.launchToken ?? this.lastLaunchToken;
+            if (!token)
+                return;
+            const marker = `${BROWSER_MARKER}${token}`;
+            const fresh = this.verifiedBrowserPidsAt > 0 &&
+                Date.now() - this.verifiedBrowserPidsAt <= PID_VERIFY_TTL_MS;
+            const pids = new Set(this.browserPids);
+            if (this.browserPid !== null)
+                pids.add(this.browserPid);
+            for (const pid of pids) {
+                // Resolved by anything other than our own marker match → hands off.
+                if (!verified.has(pid))
+                    continue;
+                // Already gone: the free probe short-circuits, no subprocess at all.
+                if (!pidAlive(pid))
+                    continue;
+                const stillOurs = pidHasMarkerSync(pid, marker);
+                // `/proc` answered and it is not our browser (pid reuse) → skip.
+                if (stillOurs === false)
+                    continue;
+                // Cannot verify on this platform → trust only a recent verification.
+                if (stillOurs === null && !fresh)
+                    continue;
+                killPidSync(pid);
+            }
+        }
+        catch {
+            /* never let cleanup throw */
+        }
+    }
+    /**
+     * Resolve the browser's pids once, right after a successful launch, so the
+     * synchronous teardown path never has to inspect the process table again.
+     */
+    resolveBrowserPids(token) {
+        this.browserPid = null;
+        this.browserPids = [];
+        this.verifiedBrowserPids = [];
+        this.verifiedBrowserPidsAt = 0;
+        this.verifiedBrowserPidsToken = null;
+        if (!token)
+            return;
+        const marker = `${BROWSER_MARKER}${token}`;
+        const rows = psRows().filter((r) => r.args.includes(marker) && isKillablePid(r.pid));
+        if (rows.length === 0)
+            return;
+        this.browserPids = rows.map((r) => r.pid);
+        // The root is the child of this process; fall back to the lowest pid (ps
+        // prints ascending pids and the root is spawned first).
+        const root = rows.find((r) => r.ppid === process.pid) ?? rows[0];
+        this.browserPid = root?.pid ?? null;
+        // Evidence for killBrowserProcessSync(): these pids were matched by our own
+        // marker right after launch, so the sync path may signal them.
+        this.verifiedBrowserPids = [...this.browserPids];
+        this.verifiedBrowserPidsAt = Date.now();
+        this.verifiedBrowserPidsToken = token;
+    }
+    /** Find the pids of the browser processes we spawned (marker match). */
+    findBrowserPids() {
+        const token = this.launchToken ?? this.lastLaunchToken;
+        if (!token)
+            return [];
+        const marker = `${BROWSER_MARKER}${token}`;
+        return psRows()
+            .filter((r) => r.args.includes(marker) && isKillablePid(r.pid))
+            .map((r) => r.pid);
+    }
     // ── Recording ──────────────────────────────────────────────
     async startRecording(opts) {
         if (this._recording) {
@@ -437,11 +991,13 @@ export class BrowserService {
         // Create new browser+context with recording enabled
         const pw = loadPlaywright();
         const recordHeadless = this.config.recordHeadless;
-        const launchOpts = {
-            headless: recordHeadless,
-            args: ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"],
-        };
         if (!this.browser?.isConnected()) {
+            this.launchToken = newBrowserToken();
+            this.lastLaunchToken = this.launchToken;
+            const launchOpts = {
+                headless: recordHeadless,
+                args: launchArgsFor(this.config.browserName, this.launchToken),
+            };
             switch (this.config.browserName) {
                 case "firefox":
                     this.browser = await pw.firefox.launch(launchOpts);
@@ -453,6 +1009,8 @@ export class BrowserService {
                     this.browser = await pw.chromium.launch(launchOpts);
                     break;
             }
+            this.resolveBrowserPids(this.launchToken);
+            attachProcessCleanup(this, () => this.killBrowserProcessSync());
         }
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
         const base = opts?.filename
@@ -482,7 +1040,13 @@ export class BrowserService {
         this._recording = { dir, startedAt: Date.now(), outputPath, filename: opts?.filename };
         return { outputPath, startedAt: this._recording.startedAt };
     }
-    async stopRecording() {
+    /**
+     * @param opts.relaunch Re-open a fresh non-recording context afterwards
+     *   (default true, what `browser_record_stop` needs). Pass `false` when the
+     *   session is shutting down — otherwise a brand new Chromium window is
+     *   spawned only to be closed again immediately.
+     */
+    async stopRecording(opts = {}) {
         if (!this._recording) {
             throw new Error("No active recording.");
         }
@@ -519,8 +1083,10 @@ export class BrowserService {
             catch { /* ignore rename failure, keep real path */ }
         }
         this._recording = null;
-        // Create a fresh non-recording context for continued use
-        await this.ensureBrowser();
+        // Create a fresh non-recording context for continued use (skipped on
+        // shutdown — see the `relaunch` option above).
+        if (opts.relaunch !== false)
+            await this.ensureBrowser();
         return { outputPath: finalPath, durationSeconds };
     }
     getRecordStatus() {