@aitne/daemon 0.1.8 → 0.1.10

package/dist/services/browser-history/lifecycle/supervisor.js

@@ -0,0 +1,334 @@
+import { readBrowserLifecycleState, writeBrowserHistoryCapabilities, writeBrowserHistoryLastIngestAt, writeBrowserLifecycleState, } from "../../../db/browser-history-store.js";
+import { createLogger } from "../../../logging.js";
+import { computeBrowserHistoryIngestEnabled, detectBrowserHistoryCapabilities, serializeBrowserHistoryCapabilities, browserHistoryCacheRoot, } from "../detectors/registry.js";
+import { createHostProfile } from "./platform.js";
+import { checkBrowserProfileHealth } from "./health-check.js";
+import { launchChromiumProfile, terminateLaunchedChromium } from "./chromium-launcher.js";
+import { nextBrowserLifecycleState } from "./failure-escalation.js";
+import { cleanupStaleBrowserHistorySnapshots, createBrowserHistorySnapshot, } from "../readers/snapshot.js";
+import { assertChromiumHistorySchema } from "../readers/chromium-reader.js";
+const logger = createLogger("browser-lifecycle-supervisor");
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseClock(value) {
+    const match = /^(\d{2}):(\d{2})$/.exec(value);
+    if (!match)
+        return null;
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    if (hour > 23 || minute > 59)
+        return null;
+    return hour * 60 + minute;
+}
+function isQuietHoursNow(config) {
+    const start = parseClock(config.quietHoursStart);
+    const end = parseClock(config.quietHoursEnd);
+    if (start === null || end === null || start === end)
+        return false;
+    const now = new Date();
+    const minute = now.getHours() * 60 + now.getMinutes();
+    if (start < end)
+        return minute >= start && minute < end;
+    return minute >= start || minute < end;
+}
+function profileAllowed(config, profile) {
+    const perBrowser = config.per_browser[profile.browser];
+    if (perBrowser?.enabled === false)
+        return false;
+    const tracked = perBrowser?.profiles_to_track ?? [];
+    return tracked.length === 0 || tracked.includes(profile.profileName);
+}
+function waitSecondsForProfile(config, profile) {
+    if (profile.browser === "comet" || profile.browser === "atlas") {
+        return config.per_browser[profile.browser]?.sync_flush_wait_seconds ?? 5;
+    }
+    return config.per_browser[profile.browser]?.sync_flush_wait_seconds ?? 60;
+}
+async function runWithConcurrency(items, limit, task) {
+    const boundedLimit = Math.max(1, Math.floor(limit));
+    for (let index = 0; index < items.length; index += boundedLimit) {
+        await Promise.all(items.slice(index, index + boundedLimit).map(task));
+    }
+}
+export class BrowserLifecycleSupervisor {
+    db;
+    config;
+    name = "browser-lifecycle-supervisor";
+    timer = null;
+    host;
+    detectionResults = [];
+    running = false;
+    tickInFlight = false;
+    constructor(db, config, host = createHostProfile()) {
+        this.db = db;
+        this.config = config;
+        this.host = host;
+    }
+    async start() {
+        this.running = true;
+        // Drop any `history-*` snapshot dirs the previous process left
+        // behind on a crash. The directories are private to the daemon and
+        // their contents are regenerable from the live browser profile, so
+        // this is safe; errors here are non-fatal — bootstrap continues.
+        try {
+            const removed = await cleanupStaleBrowserHistorySnapshots(browserHistoryCacheRoot(this.config.dataDir));
+            if (removed > 0) {
+                logger.info({ removed }, "Removed stale browser-history snapshot directories");
+            }
+        }
+        catch (err) {
+            logger.warn({ err }, "Boot-time stale snapshot cleanup failed");
+        }
+        await this.redetect();
+        void this.tick();
+        this.timer = setInterval(() => void this.tick(), this.config.browserHistoryLifecycle.check_interval_minutes * 60 * 1000);
+        this.timer.unref?.();
+        logger.info({
+            intervalMinutes: this.config.browserHistoryLifecycle.check_interval_minutes,
+        }, "Browser lifecycle supervisor started");
+    }
+    async stop() {
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        logger.info("Browser lifecycle supervisor stopped");
+    }
+    async redetect() {
+        const { capabilities, results } = await detectBrowserHistoryCapabilities({
+            db: this.db,
+            config: this.config,
+            host: this.host,
+        });
+        this.detectionResults = results;
+        writeBrowserHistoryCapabilities(this.db, capabilities);
+    }
+    refreshCapabilities() {
+        const ingestEnabled = computeBrowserHistoryIngestEnabled(this.db, this.config, this.detectionResults);
+        const capabilities = serializeBrowserHistoryCapabilities(new Date().toISOString(), this.detectionResults, ingestEnabled);
+        writeBrowserHistoryCapabilities(this.db, capabilities);
+    }
+    async tick() {
+        if (!this.running || this.tickInFlight)
+            return;
+        this.tickInFlight = true;
+        try {
+            this.refreshCapabilities();
+            if (!this.config.browserHistoryLifecycle.enabled)
+                return;
+            const ingestEnabled = computeBrowserHistoryIngestEnabled(this.db, this.config, this.detectionResults);
+            if (ingestEnabled.length === 0)
+                return;
+            const quiet = this.config.browserHistoryLifecycle.respect_quiet_hours
+                && isQuietHoursNow(this.config);
+            const profilesToSync = [];
+            for (const browser of ingestEnabled) {
+                const result = this.detectionResults.find((entry) => entry.browser === browser);
+                if (!result)
+                    continue;
+                const profiles = result.profiles.filter((profile) => profileAllowed(this.config.browserHistoryLifecycle, profile));
+                profilesToSync.push(...profiles);
+            }
+            await runWithConcurrency(profilesToSync, this.config.browserHistoryLifecycle.max_concurrent_launches, (profile) => this.runProfileCycle(profile, quiet));
+        }
+        catch (err) {
+            logger.error({ err }, "Browser lifecycle tick failed");
+        }
+        finally {
+            this.tickInFlight = false;
+        }
+    }
+    async runProfileCycle(profile, quiet) {
+        const started = Date.now();
+        const lifecycle = readBrowserLifecycleState(this.db);
+        const prior = lifecycle[profile.browser];
+        if (prior?.state === "lifecycle_paused"
+            && prior.pausedUntil
+            && prior.pausedUntil > started) {
+            this.recordTelemetry({
+                browser: profile.browser,
+                stateBefore: "paused",
+                actionTaken: "skip",
+                syncMtimeBefore: profile.lastHistoryMtimeMs,
+                syncMtimeAfter: profile.lastHistoryMtimeMs,
+                syncAgeAtIngestSeconds: null,
+                rowsIngested: 0,
+                durationMs: 0,
+                outcome: "paused",
+            });
+            return;
+        }
+        const healthBefore = await checkBrowserProfileHealth(this.host, profile, started);
+        let actionTaken = "noop";
+        let outcome = "success";
+        let error;
+        // Captured when the supervisor spawned Chromium itself (vs. found
+        // it already running). The `finally` block below terminates this
+        // PID — without it the daemon-launched Chrome lingers in the
+        // user's dock after every cycle and 24h later starts producing
+        // `sync_unresponsive` events because no actual browsing advances
+        // the History mtime.
+        //
+        // Scope of this recovery: this only covers Chromes the supervisor
+        // launched during *this* cycle. Pre-existing Chromes (launched by
+        // an earlier daemon process and orphaned across a restart, or
+        // started by the user / a LaunchAgent) are left alone — we have
+        // no in-memory PID to verify they were ours, and killing a
+        // user-launched Chrome would be unacceptable. Users in that state
+        // recover by quitting Chrome once manually, after which subsequent
+        // supervisor launches self-clean.
+        let spawnedPid = null;
+        try {
+            if (!healthBefore.running && quiet) {
+                actionTaken = "skip";
+                outcome = "skipped";
+            }
+            else if (!healthBefore.running) {
+                actionTaken = "launch";
+                const launched = await launchChromiumProfile(this.host, profile);
+                if (launched.outcome === "missing_binary") {
+                    outcome = "launch_failed";
+                }
+                else if (launched.outcome === "already_running") {
+                    // The pre-launch health probe raced a user-initiated start
+                    // (Finder / Dock / restored-session). Chromium is up but we
+                    // did not spawn it, so the mtime advancement gate below would
+                    // false-positive `sync_unresponsive`. Treat as a noop — the
+                    // next tick will see the live SingletonLock through
+                    // `checkBrowserProfileHealth` and route via the running path.
+                    actionTaken = "noop";
+                }
+                else {
+                    spawnedPid = launched.pid;
+                    await sleep(waitSecondsForProfile(this.config.browserHistoryLifecycle, profile) * 1000);
+                    // BROWSER_HISTORY_INTEGRATION_PLAN.md §7.4.3 — post-launch
+                    // mtime advancement gate. If the History file has not been
+                    // touched after the configured flush window the browser
+                    // process is up but cloud sync has not made progress; surface
+                    // this as `sync_unresponsive` so failure-escalation kicks in
+                    // after the design's three consecutive-failures threshold.
+                    // Pre-launch mtime captured in `healthBefore.historyMtimeMs`
+                    // is the baseline; a NULL there means the History file did
+                    // not exist yet, in which case any non-NULL after-mtime is
+                    // progress.
+                    const postLaunchHealth = await checkBrowserProfileHealth(this.host, profile, Date.now());
+                    const beforeMtime = healthBefore.historyMtimeMs;
+                    const afterMtime = postLaunchHealth.historyMtimeMs;
+                    const advanced = afterMtime !== null
+                        && (beforeMtime === null || afterMtime > beforeMtime);
+                    if (!advanced)
+                        outcome = "sync_unresponsive";
+                }
+            }
+            else if (healthBefore.stale) {
+                outcome = "sync_unresponsive";
+            }
+            if (outcome === "success") {
+                await this.validateSnapshot(profile);
+                writeBrowserHistoryLastIngestAt(this.db, Date.now());
+            }
+            const healthAfter = await checkBrowserProfileHealth(this.host, profile, Date.now());
+            this.applyLifecycleState(profile.browser, outcome, actionTaken, started);
+            this.recordTelemetry({
+                browser: profile.browser,
+                stateBefore: healthBefore.running
+                    ? (healthBefore.stale ? "stale" : "running")
+                    : "stopped",
+                actionTaken,
+                syncMtimeBefore: healthBefore.historyMtimeMs,
+                syncMtimeAfter: healthAfter.historyMtimeMs,
+                syncAgeAtIngestSeconds: healthAfter.syncAgeSeconds,
+                rowsIngested: 0,
+                durationMs: Date.now() - started,
+                outcome,
+            });
+        }
+        catch (err) {
+            error = err instanceof Error ? err.message : "browser lifecycle failed";
+            outcome = "error";
+            this.applyLifecycleState(profile.browser, outcome, actionTaken, started);
+            this.recordTelemetry({
+                browser: profile.browser,
+                stateBefore: healthBefore.running
+                    ? (healthBefore.stale ? "stale" : "running")
+                    : "stopped",
+                actionTaken,
+                syncMtimeBefore: healthBefore.historyMtimeMs,
+                syncMtimeAfter: null,
+                syncAgeAtIngestSeconds: null,
+                rowsIngested: 0,
+                durationMs: Date.now() - started,
+                outcome,
+                error,
+            });
+        }
+        finally {
+            if (spawnedPid !== null) {
+                const terminationResult = await terminateLaunchedChromium(this.host, profile, spawnedPid).catch((err) => {
+                    logger.warn({ err, browser: profile.browser, spawnedPid }, "Chromium terminate threw");
+                    return "failed";
+                });
+                if (terminationResult === "ownership_changed") {
+                    logger.info({ browser: profile.browser, spawnedPid }, "Skipping Chromium terminate — SingletonLock owner changed mid-flush (user opened the browser)");
+                }
+                else if (terminationResult === "failed") {
+                    logger.warn({ browser: profile.browser, spawnedPid }, "Daemon-launched Chromium failed to exit after SIGKILL — will retry next tick");
+                }
+            }
+        }
+    }
+    async validateSnapshot(profile) {
+        const snapshot = await createBrowserHistorySnapshot(profile.historyPath, browserHistoryCacheRoot(this.config.dataDir));
+        try {
+            return assertChromiumHistorySchema(snapshot.mainPath).visitCount;
+        }
+        finally {
+            await snapshot.cleanup();
+        }
+    }
+    applyLifecycleState(browser, outcome, actionTaken, nowMs) {
+        const state = readBrowserLifecycleState(this.db);
+        const prior = state[browser];
+        const next = nextBrowserLifecycleState({
+            state: prior?.state ?? "stopped",
+            consecutiveFailures: prior?.consecutiveFailures ?? 0,
+            nowMs,
+            outcome,
+        });
+        state[browser] = {
+            ...prior,
+            ...next,
+            lastLaunchAt: actionTaken === "launch" ? nowMs : (prior?.lastLaunchAt ?? next.lastLaunchAt),
+            lastSuccessfulSyncAt: next.lastSuccessfulSyncAt ?? prior?.lastSuccessfulSyncAt ?? null,
+        };
+        writeBrowserLifecycleState(this.db, state);
+    }
+    recordTelemetry(telemetry) {
+        try {
+            this.db
+                .prepare(`INSERT INTO agent_actions
+             (action_type, trigger, result, detail, duration_ms, completed_at, source_kind)
+           VALUES (?, ?, ?, ?, ?, CURRENT_TIMESTAMP, ?)`)
+                .run(`browser_lifecycle.${telemetry.browser}`, "browser_lifecycle", telemetry.outcome === "success" || telemetry.outcome === "skipped"
+                ? "success"
+                : telemetry.outcome === "paused"
+                    ? "skipped"
+                    : "failed", JSON.stringify({
+                state_before: telemetry.stateBefore,
+                action_taken: telemetry.actionTaken,
+                sync_mtime_before: telemetry.syncMtimeBefore,
+                sync_mtime_after: telemetry.syncMtimeAfter,
+                sync_age_at_ingest_seconds: telemetry.syncAgeAtIngestSeconds,
+                rows_ingested: telemetry.rowsIngested,
+                duration_ms: telemetry.durationMs,
+                outcome: telemetry.outcome,
+                ...(telemetry.error ? { error: telemetry.error } : {}),
+            }), telemetry.durationMs, "cron");
+        }
+        catch (err) {
+            logger.warn({ err, telemetry }, "Failed to write browser lifecycle telemetry");
+        }
+    }
+}

package/dist/services/browser-history/managed-chromium/cdp-connect.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Playwright `connectOverCDP` shim for Instance A.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §5.3, §8.2.
+ *
+ * The daemon owns Chromium's process lifecycle (`instance-a-launcher`).
+ * Playwright drives the **already-running** browser via the DevTools
+ * Protocol — so we use `chromium.connectOverCDP(endpoint)` rather than
+ * Playwright's `chromium.launch()`, which would manage its own bundled
+ * Chromium and skip our sandbox wrapping.
+ *
+ * Lifecycle binding:
+ *   1. Launch Instance A → get `LaunchedInstanceA` handle.
+ *   2. Connect Playwright over CDP at the handle's endpoint.
+ *   3. Create a fresh `BrowserContext` for the workflow.
+ *   4. Install the CDP route interception layer (`cdp-network-interception`)
+ *      with the workflow's allowlist regex.
+ *   5. Return a `ManagedPlaywrightHandle` whose `release()` closes the
+ *      context, disconnects the Playwright browser, and tears down
+ *      Instance A.
+ *
+ * Excluded from the 100% coverage gate — exercises `playwright-core`
+ * (Anthropic SDK-shape mock-blocked by ESM) + the real Chromium process
+ * over a TCP socket; matches the parent claude-code-core.ts exclusion
+ * rationale.
+ */
+import { type BlockedRequestRecorder } from "../automation/cdp-network-interception.js";
+import type Database from "better-sqlite3";
+import type { HostProfile } from "../types.js";
+export type AcquirePlaywrightContextOptions = {
+    db: Database.Database;
+    host: HostProfile;
+    paDataDir: string;
+    workflowId: string;
+    variant: "anon";
+    /**
+     * Per-workflow positive selector. When `null` (the 2026-05-27
+     * open-navigation default for browser-task) the CDP layer
+     * enforces only the denylist. The legacy Instance A workflow
+     * path passes a real regex.
+     */
+    allowlistRegex: RegExp | null;
+    /**
+     * User-curated hostname denylist (compiled regexes). Threaded
+     * into the CDP route handler. Empty/undefined means "rely on
+     * IP CIDR + payment-path layers only".
+     */
+    hostnameDenylist?: ReadonlyArray<RegExp>;
+} | {
+    db: Database.Database;
+    host: HostProfile;
+    paDataDir: string;
+    workflowId: string;
+    variant: "auth";
+    /** B-2.5 per-site identifier — selects the profile dir under
+     *  `chromium-automation-auth/<siteKey>/` and threads through to
+     *  the launcher so persistent cookies survive across runs. */
+    siteKey: string;
+    /** Per-workflow positive selector. The runner enforces that this
+     *  is a subset of the site's `allowedHostPattern` before reaching
+     *  the launcher. */
+    allowlistRegex: RegExp;
+    /** User-curated hostname denylist applied alongside the positive
+     *  selector. See `variant: "anon"` for the full semantics. */
+    hostnameDenylist?: ReadonlyArray<RegExp>;
+} | {
+    db: Database.Database;
+    host: HostProfile;
+    paDataDir: string;
+    workflowId: string;
+    variant: "purchase";
+    /** B-4 per-site identifier — selects the profile dir under
+     *  `chromium-automation-purchase/<siteKey>/`. The cookies survive
+     *  across runs (so the cart state populated by user/B-3 work
+     *  persists), but the profile is strictly isolated from the
+     *  auth-variant profile of the same `siteKey`. */
+    siteKey: string;
+    /** Per-workflow positive selector. The workflow declares this in
+     *  its `allowlistRegex` (e.g. checkout-page subpath). */
+    allowlistRegex: RegExp;
+    /** User-curated hostname denylist applied alongside the positive
+     *  selector. See `variant: "anon"` for the full semantics. */
+    hostnameDenylist?: ReadonlyArray<RegExp>;
+};
+export interface ManagedPlaywrightHandle {
+    /** Playwright `BrowserContext`. Workflow `run()` consumes via
+     *  `playwrightContext.newPage()` / etc. Typed `unknown` so callers
+     *  that don't need the strong type avoid a transitive playwright-core
+     *  import. */
+    context: unknown;
+    /** Per-task blocked-request audit accumulator. Read at release-
+     *  time by the browser-task runner to persist the count onto the
+     *  parent `browser_task` row (BROWSER_TASK_REDESIGN_PLAN.md §14.2);
+     *  pre-Phase-6 the workflow-runner persisted the list into
+     *  `browser_automation_workflows.blocked_requests` (retained audit). */
+    blockedRequests: BlockedRequestRecorder;
+    /** Idempotent teardown — closes context (anon-only — for auth/purchase
+     *  the persistent default context is left in place so Chromium's own
+     *  shutdown sequence flushes profile state to disk), disconnects
+     *  Playwright, SIGTERMs Chromium, deletes anon profile dir. */
+    release(): Promise<void>;
+}
+export type AcquirePlaywrightContextResult = {
+    ok: true;
+    handle: ManagedPlaywrightHandle;
+} | {
+    ok: false;
+    reason: "missing_binary" | "missing_sandbox" | "spawn_failed" | "cdp_timeout" | "playwright_connect_failed";
+};
+export declare function acquirePlaywrightContext(opts: AcquirePlaywrightContextOptions): Promise<AcquirePlaywrightContextResult>;

package/dist/services/browser-history/managed-chromium/cdp-connect.js

@@ -0,0 +1,171 @@
+/**
+ * Playwright `connectOverCDP` shim for Instance A.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §5.3, §8.2.
+ *
+ * The daemon owns Chromium's process lifecycle (`instance-a-launcher`).
+ * Playwright drives the **already-running** browser via the DevTools
+ * Protocol — so we use `chromium.connectOverCDP(endpoint)` rather than
+ * Playwright's `chromium.launch()`, which would manage its own bundled
+ * Chromium and skip our sandbox wrapping.
+ *
+ * Lifecycle binding:
+ *   1. Launch Instance A → get `LaunchedInstanceA` handle.
+ *   2. Connect Playwright over CDP at the handle's endpoint.
+ *   3. Create a fresh `BrowserContext` for the workflow.
+ *   4. Install the CDP route interception layer (`cdp-network-interception`)
+ *      with the workflow's allowlist regex.
+ *   5. Return a `ManagedPlaywrightHandle` whose `release()` closes the
+ *      context, disconnects the Playwright browser, and tears down
+ *      Instance A.
+ *
+ * Excluded from the 100% coverage gate — exercises `playwright-core`
+ * (Anthropic SDK-shape mock-blocked by ESM) + the real Chromium process
+ * over a TCP socket; matches the parent claude-code-core.ts exclusion
+ * rationale.
+ */
+import { createLogger } from "../../../logging.js";
+import { applyCDPInterception, makeBlockedRequestRecorder, } from "../automation/cdp-network-interception.js";
+import { launchInstanceA } from "./instance-a-launcher.js";
+const logger = createLogger("instance-a-cdp-connect");
+export async function acquirePlaywrightContext(opts) {
+    const launchResult = await launchInstanceA(opts.variant === "anon"
+        ? {
+            db: opts.db,
+            host: opts.host,
+            paDataDir: opts.paDataDir,
+            workflowId: opts.workflowId,
+            variant: "anon",
+        }
+        : opts.variant === "auth"
+            ? {
+                db: opts.db,
+                host: opts.host,
+                paDataDir: opts.paDataDir,
+                workflowId: opts.workflowId,
+                variant: "auth",
+                siteKey: opts.siteKey,
+            }
+            : {
+                db: opts.db,
+                host: opts.host,
+                paDataDir: opts.paDataDir,
+                workflowId: opts.workflowId,
+                variant: "purchase",
+                siteKey: opts.siteKey,
+            });
+    if (!launchResult.ok) {
+        return { ok: false, reason: launchResult.reason };
+    }
+    const launched = launchResult.handle;
+    let chromiumApi;
+    try {
+        // Dynamic import keeps `playwright-core` off the daemon's eager
+        // module graph — only workflow runs pay the cost. Also lets the
+        // unit test layer stub the dynamic loader if it ever needs to.
+        const mod = (await import("playwright-core"));
+        chromiumApi = mod.chromium;
+    }
+    catch (err) {
+        logger.error({ err }, "playwright-core dynamic import failed");
+        await launched.release();
+        return { ok: false, reason: "playwright_connect_failed" };
+    }
+    let browser;
+    try {
+        browser = await chromiumApi.connectOverCDP(launched.cdpEndpoint);
+    }
+    catch (err) {
+        logger.warn({ err, endpoint: launched.cdpEndpoint, workflowId: opts.workflowId }, "playwright connectOverCDP failed");
+        await launched.release();
+        return { ok: false, reason: "playwright_connect_failed" };
+    }
+    // anon: `newContext()` builds a fresh incognito-like context. Storage
+    // state for the per-workflow profile dir is irrelevant — the dir is
+    // deleted on release.
+    //
+    // auth/purchase: MUST attach to the persistent default context. When
+    // Chromium spawns with `--user-data-dir=<per-site-dir>` the profile's
+    // cookies / localStorage are loaded into the *default* BrowserContext,
+    // not into a fresh one. `connectOverCDP` exposes that default via
+    // `browser.contexts()[0]`. Calling `newContext()` here would silently
+    // create an incognito context that does not see the cookies the user
+    // planted during sign-in — breaking every auth-variant workflow
+    // (getAmazonPurchaseHistory etc.) without surfacing an error.
+    // See MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §16.4: "fresh
+    // BrowserContext is created per workflow run so storage state from
+    // the profile dir (cookies, localStorage) loads in" — the
+    // implementation must use the persistent context to honour that
+    // guarantee.
+    let context;
+    try {
+        if (opts.variant === "anon") {
+            context = await browser.newContext();
+        }
+        else {
+            const existing = browser.contexts();
+            if (existing.length === 0) {
+                // A CDP-connected Chromium spawned with --user-data-dir always
+                // exposes one default context. Zero contexts means the spawn
+                // raced with a failure mode we did not anticipate; fail closed
+                // rather than silently re-creating an empty context.
+                logger.warn({ workflowId: opts.workflowId, variant: opts.variant }, "no default browser context after CDP connect; refusing to fall back to newContext()");
+                await browser.close().catch(() => { });
+                await launched.release();
+                return { ok: false, reason: "playwright_connect_failed" };
+            }
+            context = existing[0];
+        }
+    }
+    catch (err) {
+        logger.warn({ err, workflowId: opts.workflowId, variant: opts.variant }, "playwright context acquisition failed");
+        await browser.close().catch(() => { });
+        await launched.release();
+        return { ok: false, reason: "playwright_connect_failed" };
+    }
+    const recorder = makeBlockedRequestRecorder();
+    try {
+        await applyCDPInterception(context, {
+            workflowId: opts.workflowId,
+            allowlistRegex: opts.allowlistRegex,
+            recorder,
+            hostnameDenylist: opts.hostnameDenylist,
+        });
+    }
+    catch (err) {
+        logger.warn({ err, workflowId: opts.workflowId }, "CDP route interception install failed");
+        await context.close().catch(() => { });
+        await browser.close().catch(() => { });
+        await launched.release();
+        return { ok: false, reason: "playwright_connect_failed" };
+    }
+    let released = false;
+    const handle = {
+        context,
+        blockedRequests: recorder,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            if (opts.variant === "anon") {
+                // For anon: close the per-workflow incognito context so any
+                // pending request handlers detach cleanly. The dir gets nuked
+                // shortly after, so storage flush doesn't matter.
+                try {
+                    await context.close();
+                }
+                catch {
+                    // best-effort
+                }
+            }
+            // For auth/purchase: do NOT call context.close() — the persistent
+            // default context owns the profile dir; closing it before
+            // browser.close() can race with Chromium's cookie/localStorage
+            // flush. browser.close() shuts the whole instance down and
+            // chrome flushes the profile during normal exit.
+            await browser.close().catch(() => { });
+            await launched.release();
+        },
+    };
+    return { ok: true, handle };
+}