camofox-browser 2.1.1 → 2.4.1

package/dist/src/server.js

@@ -6,22 +6,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const express_1 = __importDefault(require("express"));
 const core_1 = __importDefault(require("./routes/core"));
 const openclaw_1 = __importDefault(require("./routes/openclaw"));
+const docs_1 = __importDefault(require("./routes/docs"));
 const errors_1 = require("./middleware/errors");
 const logging_1 = require("./middleware/logging");
+const lifecycle_activity_1 = require("./middleware/lifecycle-activity");
 const config_1 = require("./utils/config");
 const browser_1 = require("./services/browser");
 const context_pool_1 = require("./services/context-pool");
+const lifecycle_controller_1 = require("./services/lifecycle-controller");
 const session_1 = require("./services/session");
 const download_1 = require("./services/download");
 const health_1 = require("./services/health");
 const youtube_1 = require("./services/youtube");
 const vnc_1 = require("./services/vnc");
 const CONFIG = (0, config_1.loadConfig)();
+(0, config_1.assertServerExposureSafety)(CONFIG);
 const app = (0, express_1.default)();
 app.use(express_1.default.json({ limit: '100kb' }));
 app.use(logging_1.loggingMiddleware);
+app.use((0, lifecycle_activity_1.createLifecycleActivityMiddleware)(lifecycle_controller_1.lifecycleController));
 app.use(core_1.default);
 app.use(openclaw_1.default);
+app.use(docs_1.default);
 // Fallback error middleware (routes largely handle their own errors to preserve legacy behavior)
 app.use((err, _req, res, _next) => {
     const anyErr = err;
@@ -44,6 +50,17 @@ void (0, youtube_1.detectYtDlp)((message) => {
     (0, logging_1.log)('info', 'yt-dlp detection', { message: String(message) });
 });
 let shuttingDown = false;
+async function cleanupDaemonPidFileFromEnv() {
+    const pidFile = process.env.CAMOFOX_SERVER_PID_FILE;
+    if (!pidFile)
+        return;
+    try {
+        await require('node:fs/promises').rm(pidFile, { force: true });
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+}
 async function gracefulShutdown(signal) {
     if (shuttingDown)
         return;
@@ -70,12 +87,13 @@ async function gracefulShutdown(signal) {
         healthProbeInterval = null;
     }
     await (0, browser_1.closeBrowser)().catch(() => { });
+    await cleanupDaemonPidFileFromEnv();
     process.exit(0);
 }
 process.on('SIGTERM', () => void gracefulShutdown('SIGTERM'));
 process.on('SIGINT', () => void gracefulShutdown('SIGINT'));
-server = app.listen(PORT, () => {
-    (0, logging_1.log)('info', 'server started', { port: PORT, pid: process.pid, nodeVersion: process.version });
+server = app.listen(PORT, CONFIG.host, () => {
+    (0, logging_1.log)('info', 'server started', { port: PORT, host: CONFIG.host, pid: process.pid, nodeVersion: process.version });
     (0, logging_1.log)('info', 'using persistent profiles', { profilesDir: CONFIG.profilesDir });
     (0, health_1.resetHealth)();
     healthProbeInterval = setInterval(() => {
@@ -91,9 +109,42 @@ server = app.listen(PORT, () => {
         });
     }, CONFIG.healthProbeIntervalMs);
     healthProbeInterval.unref();
+    // Lifecycle idle cleanup check
+    setInterval(async () => {
+        const now = Date.now();
+        const sessionSnapshot = (0, session_1.getLifecycleSessionSnapshot)();
+        const contextSnapshot = context_pool_1.contextPool.getLifecycleSnapshot();
+        lifecycle_controller_1.lifecycleController.syncLiveState({
+            liveSessions: sessionSnapshot.liveSessions,
+            liveTabs: sessionSnapshot.liveTabs,
+            launchingContexts: contextSnapshot.launchingContexts,
+            stagedCreates: sessionSnapshot.stagedCreates,
+        });
+        // Stage 2: check for idle exit after successful cleanup
+        if (lifecycle_controller_1.lifecycleController.shouldExit(now)) {
+            (0, logging_1.log)('info', 'idle exit started');
+            await gracefulShutdown('IDLE_TIMEOUT');
+            return;
+        }
+        if (lifecycle_controller_1.lifecycleController.shouldRunCleanup(now)) {
+            lifecycle_controller_1.lifecycleController.markCleanupStarted(now);
+            // Snapshot sessions and contexts atomically BEFORE async cleanup work
+            const sessionsToCheck = (0, session_1.getSessionsSnapshot)();
+            const contextsToCheck = context_pool_1.contextPool.getPoolEntries();
+            try {
+                const result = await (0, session_1.runLifecycleIdleCleanup)(sessionsToCheck, contextsToCheck, now);
+                lifecycle_controller_1.lifecycleController.markCleanupFinished('success', Date.now());
+                (0, logging_1.log)('info', 'idle cleanup completed', result);
+            }
+            catch (error) {
+                lifecycle_controller_1.lifecycleController.markCleanupFinished('failed', Date.now());
+                (0, logging_1.log)('error', 'idle cleanup failed', { error: (0, errors_1.safeError)(error) });
+            }
+        }
+    }, 250);
     if (!CONFIG.apiKey) {
-        console.warn('[camofox] ⚠️  CAMOFOX_API_KEY not set — all endpoints are open without authentication.');
-        console.warn('[camofox] Set CAMOFOX_API_KEY for production/network-exposed deployments.');
+        console.warn('[camofox] ⚠️  CAMOFOX_API_KEY not set — protected endpoints are only intended for loopback-only deployments.');
+        console.warn('[camofox] Set CAMOFOX_API_KEY before binding CAMOFOX_HOST beyond localhost.');
     }
 });
 server.on('error', (err) => {

package/dist/src/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"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"}

package/dist/src/services/context-pool.d.ts

@@ -1,11 +1,17 @@
 import { type BrowserContext, type BrowserContextOptions } from 'playwright-core';
+import type { ResolvedProxyConfig } from '../types';
 export interface PoolEntry {
     context: BrowserContext;
     userId: string;
+    profileKey: string;
     profileDir: string;
     lastAccess: number;
+    createdAt: number;
     launching?: Promise<BrowserContext>;
+    staged?: boolean;
+    stagedGeneration?: string;
     virtualDisplay?: any;
+    proxyConfig?: ResolvedProxyConfig | null;
     seedOptions?: Pick<BrowserContextOptions, 'locale' | 'timezoneId' | 'geolocation' | 'viewport'>;
 }
 export declare class ContextPool {
@@ -14,16 +20,26 @@ export declare class ContextPool {
     private onEvictCallbacks;
     onEvict(callback: (userId: string) => void): void;
     private notifyEviction;
-    getEntry(userId: string): PoolEntry | undefined;
+    getEntry(profileKey: string): PoolEntry | undefined;
     getDisplayForUser(userId: string): string | null;
     size(): number;
     listActiveUserIds(): string[];
+    getLifecycleSnapshot(): {
+        liveContexts: number;
+        launchingContexts: number;
+        stagedContexts: number;
+    };
+    getPoolEntries(): Map<string, PoolEntry>;
     private cleanupVirtualDisplay;
     private launchPersistentContext;
     restartContext(userId: string, headless?: boolean | 'virtual'): Promise<PoolEntry>;
     private evictIfNeeded;
-    ensureContext(userId: string, options?: BrowserContextOptions): Promise<PoolEntry>;
-    closeContext(userId: string): Promise<void>;
+    ensureContext(profileKey: string, userId: string, options?: BrowserContextOptions, resolvedProxy?: ResolvedProxyConfig | null, staged?: boolean, stagedGeneration?: string): Promise<PoolEntry>;
+    closeContext(profileKey: string): Promise<void>;
+    closeContextIfMatches(profileKey: string, expectedCreatedAt: number, expectedLastAccess?: number): Promise<void>;
+    closeStagedContext(profileKey: string, generation?: string): Promise<void>;
+    closeContextByUserId(userId: string): Promise<void>;
+    closeStagedContextByUserId(userId: string, generation?: string): Promise<void>;
     closeAll(): Promise<void>;
 }
 export declare const contextPool: ContextPool;

package/dist/src/services/context-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-pool.d.ts","sourceRoot":"","sources":["../../../src/services/context-pool.ts"],"names":[],"mappings":"AAQA,OAAO,EAAW,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAW3F,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACpC,cAAc,CAAC,EAAE,GAAG,CAAC;IACrB,WAAW,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,UAAU,CAAC,CAAC;CAChG;AA0GD,qBAAa,WAAW;IACvB,OAAO,CAAC,IAAI,CAAqC;IACjD,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,gBAAgB,CAAuC;IAE/D,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAIjD,OAAO,CAAC,cAAc;IAWtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI/C,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAiBhD,IAAI,IAAI,MAAM;IAId,iBAAiB,IAAI,MAAM,EAAE;IAI7B,OAAO,CAAC,qBAAqB;YAWf,uBAAuB;IAgH/B,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;YAc1E,aAAa;IAerB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC;IAuElF,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB3C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAM/B;AAED,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE/D"}
+{"version":3,"file":"context-pool.d.ts","sourceRoot":"","sources":["../../../src/services/context-pool.ts"],"names":[],"mappings":"AAYA,OAAO,EAAW,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAK3F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAQpD,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,GAAG,CAAC;IACrB,WAAW,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzC,WAAW,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,UAAU,CAAC,CAAC;CAChG;AA0HD,qBAAa,WAAW;IACvB,OAAO,CAAC,IAAI,CAAqC;IACjD,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,gBAAgB,CAAuC;IAE/D,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAIjD,OAAO,CAAC,cAAc;IAWtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAInD,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAoBhD,IAAI,IAAI,MAAM;IAId,iBAAiB,IAAI,MAAM,EAAE;IAU7B,oBAAoB,IAAI;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE;IAcnG,cAAc,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC;IAIxC,OAAO,CAAC,qBAAqB;YAWf,uBAAuB;IAuL/B,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;YAqB1E,aAAa;IAerB,aAAa,CAClB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,qBAAqB,EAC/B,aAAa,CAAC,EAAE,mBAAmB,GAAG,IAAI,EAC1C,MAAM,UAAQ,EACd,gBAAgB,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,SAAS,CAAC;IAiFf,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB/C,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhH,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1E,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnD,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9E,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAW/B;AAED,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE/D"}

package/dist/src/services/context-pool.js

@@ -11,11 +11,16 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_child_process_1 = require("node:child_process");
 const camoufox_js_1 = require("camoufox-js");
 const fingerprints_js_1 = require("camoufox-js/dist/fingerprints.js");
+// camoufox-js does not export version info from its public API.
+// This deep import is the only way to detect the installed engine version.
+// If it breaks on upgrade, getInstalledCamoufoxVersion() catches and returns 'unknown'.
+const pkgman_js_1 = require("camoufox-js/dist/pkgman.js");
 const playwright_core_1 = require("playwright-core");
 const config_1 = require("../utils/config");
+const sidecar_version_1 = require("../utils/sidecar-version");
 const logging_1 = require("../middleware/logging");
 const CONFIG = (0, config_1.loadConfig)();
-const MAX_CONTEXTS = Math.max(1, Number.parseInt(process.env.CAMOFOX_MAX_SESSIONS || '', 10) || 50);
+const MAX_CONTEXTS = CONFIG.maxSessions;
 function getHostOS() {
     const platform = node_os_1.default.platform();
     if (platform === 'darwin')
@@ -24,16 +29,32 @@ function getHostOS() {
         return 'windows';
     return 'linux';
 }
-function buildProxyConfig() {
-    const { host, port, username, password } = CONFIG.proxy;
-    if (!host || !port)
-        return null;
+function buildProxyConfig(proxy) {
+    if (!proxy) {
+        // Fallback to configured server proxy
+        const { host, port, username, password } = CONFIG.proxy;
+        if (!host || !port)
+            return null;
+        return {
+            server: `http://${host}:${port}`,
+            username: username || undefined,
+            password: password || undefined,
+        };
+    }
     return {
-        server: `http://${host}:${port}`,
-        username: username || undefined,
-        password: password || undefined,
+        server: proxy.server,
+        username: proxy.username,
+        password: proxy.password,
     };
 }
+function getInstalledCamoufoxVersion() {
+    try {
+        return (0, pkgman_js_1.installedVerStr)();
+    }
+    catch {
+        return 'unknown';
+    }
+}
 function profileDirForUserId(userId) {
     // Avoid path traversal from untrusted route params.
     const safe = encodeURIComponent(String(userId));
@@ -131,30 +152,57 @@ class ContextPool {
             }
         }
     }
-    getEntry(userId) {
-        return this.pool.get(userId);
+    getEntry(profileKey) {
+        return this.pool.get(profileKey);
     }
     getDisplayForUser(userId) {
-        const entry = this.pool.get(String(userId));
-        if (!entry)
-            return null;
-        if (entry.virtualDisplay) {
-            try {
-                const display = entry.virtualDisplay.get();
-                return typeof display === 'string' ? display : null;
-            }
-            catch {
-                return null;
+        // Find any entry for this userId (there may be multiple with different profile keys)
+        for (const entry of this.pool.values()) {
+            if (entry.userId !== String(userId))
+                continue;
+            if (entry.virtualDisplay) {
+                try {
+                    const display = entry.virtualDisplay.get();
+                    return typeof display === 'string' ? display : null;
+                }
+                catch {
+                    return null;
+                }
             }
+            const processDisplay = process.env.DISPLAY;
+            return typeof processDisplay === 'string' && processDisplay ? processDisplay : null;
         }
-        const processDisplay = process.env.DISPLAY;
-        return typeof processDisplay === 'string' && processDisplay ? processDisplay : null;
+        return null;
     }
     size() {
         return this.pool.size;
     }
     listActiveUserIds() {
-        return Array.from(this.pool.keys());
+        const userIds = new Set();
+        for (const entry of this.pool.values()) {
+            if (!entry.staged) {
+                userIds.add(entry.userId);
+            }
+        }
+        return Array.from(userIds);
+    }
+    getLifecycleSnapshot() {
+        let launchingContexts = 0;
+        let stagedContexts = 0;
+        for (const entry of this.pool.values()) {
+            if (entry.launching)
+                launchingContexts++;
+            if (entry.staged)
+                stagedContexts++;
+        }
+        return {
+            liveContexts: this.pool.size,
+            launchingContexts,
+            stagedContexts,
+        };
+    }
+    getPoolEntries() {
+        return new Map(this.pool);
     }
     cleanupVirtualDisplay(entry) {
         if (!entry.virtualDisplay)
@@ -169,12 +217,44 @@ class ContextPool {
             entry.virtualDisplay = undefined;
         }
     }
-    async launchPersistentContext(userId, contextOptions) {
+    async launchPersistentContext(userId, contextOptions, resolvedProxy) {
         const hostOS = getHostOS();
-        const proxy = buildProxyConfig();
+        const proxy = buildProxyConfig(resolvedProxy);
         const headless = this.headlessOverrides.get(userId) ?? CONFIG.headless;
         const profileDir = profileDirForUserId(userId);
         node_fs_1.default.mkdirSync(profileDir, { recursive: true });
+        const compatPath = node_path_1.default.join(profileDir, 'compatibility.json');
+        try {
+            const currentVersion = getInstalledCamoufoxVersion();
+            if (currentVersion === 'unknown') {
+                throw new Error(`Cannot verify profile compatibility for user "${userId}": installed Camoufox version could not be determined. ` +
+                    `Resolve the camoufox-js installation or delete the profile directory to reset: ${profileDir}`);
+            }
+            const compat = (0, sidecar_version_1.readVersionedSidecar)(compatPath, {
+                currentVersion: 1,
+                migrations: {},
+                label: 'profile compatibility',
+            });
+            if (compat) {
+                if (compat.camoufoxVersion === 'unknown') {
+                    throw new Error(`Profile for user "${userId}" has unknown version provenance and cannot be verified. Delete the profile directory to reset: ${profileDir}`);
+                }
+                if (compat.camoufoxVersion !== currentVersion) {
+                    throw new Error(`Profile for user "${userId}" was created with Camoufox ${compat.camoufoxVersion}, but the current version is ${currentVersion}. Delete the profile directory to reset: ${profileDir}`);
+                }
+            }
+            else {
+                (0, sidecar_version_1.writeVersionedSidecar)(compatPath, 1, {
+                    camoufoxVersion: currentVersion,
+                    createdAt: new Date().toISOString(),
+                });
+            }
+        }
+        catch (err) {
+            throw err instanceof Error
+                ? err
+                : new Error(`Profile compatibility check failed for user "${userId}": ${String(err)}. Delete the profile directory to reset: ${profileDir}`);
+        }
         let effectiveHeadless = headless === true;
         let virtualDisplay = undefined;
         if (headless === 'virtual' || (headless === false && hostOS === 'linux' && !hasUsableLinuxDisplay())) {
@@ -219,26 +299,46 @@ class ContextPool {
         try {
             const fpPath = node_path_1.default.join(profileDir, 'fingerprint.json');
             let fingerprint;
-            if (node_fs_1.default.existsSync(fpPath)) {
-                try {
-                    const parsed = JSON.parse(node_fs_1.default.readFileSync(fpPath, 'utf-8'));
-                    if (parsed && typeof parsed === 'object') {
-                        fingerprint = parsed;
-                        (0, logging_1.log)('info', 'loaded persisted fingerprint', { userId, fpPath });
-                    }
-                    else {
-                        (0, logging_1.log)('warn', 'persisted fingerprint is invalid, regenerating', { userId, fpPath });
-                    }
+            const configuredOs = CONFIG.fingerprintDefaults.os;
+            const fingerprintOperatingSystems = Array.isArray(configuredOs)
+                ? configuredOs
+                : configuredOs
+                    ? [configuredOs]
+                    : [hostOS];
+            const configuredScreen = CONFIG.fingerprintDefaults.screen;
+            const fingerprintScreen = configuredScreen
+                ? {
+                    minWidth: configuredScreen.width,
+                    maxWidth: configuredScreen.width,
+                    minHeight: configuredScreen.height,
+                    maxHeight: configuredScreen.height,
                 }
-                catch {
-                    (0, logging_1.log)('warn', 'failed to read persisted fingerprint, regenerating', { userId, fpPath });
+                : undefined;
+            try {
+                const persistedFingerprint = (0, sidecar_version_1.readVersionedSidecar)(fpPath, {
+                    currentVersion: 1,
+                    migrations: {
+                        0: (raw) => raw,
+                    },
+                    label: 'fingerprint sidecar',
+                });
+                fingerprint = persistedFingerprint ?? undefined;
+                if (fingerprint) {
+                    (0, logging_1.log)('info', 'loaded persisted fingerprint', { userId, fpPath });
                 }
             }
+            catch (err) {
+                throw err instanceof Error
+                    ? err
+                    : new Error(`Fingerprint sidecar failed for user "${userId}": ${String(err)}. Delete ${fpPath} to reset.`);
+            }
             if (!fingerprint) {
-                fingerprint = (0, fingerprints_js_1.generateFingerprint)(undefined, { operatingSystems: [hostOS] });
+                fingerprint = (0, fingerprints_js_1.generateFingerprint)(undefined, {
+                    operatingSystems: fingerprintOperatingSystems,
+                    ...(fingerprintScreen ? { screen: fingerprintScreen } : {}),
+                });
                 try {
-                    node_fs_1.default.mkdirSync(node_path_1.default.dirname(fpPath), { recursive: true });
-                    node_fs_1.default.writeFileSync(fpPath, JSON.stringify(fingerprint, null, 2), 'utf-8');
+                    (0, sidecar_version_1.writeVersionedSidecar)(fpPath, 1, fingerprint);
                     (0, logging_1.log)('info', 'generated new fingerprint and persisted it', { userId, fpPath });
                 }
                 catch {
@@ -248,8 +348,11 @@ class ContextPool {
             const opts = await (0, camoufox_js_1.launchOptions)({
                 headless: effectiveHeadless,
                 ...(virtualDisplay ? { virtual_display: virtualDisplay.get() } : {}),
-                os: hostOS,
-                humanize: true,
+                os: configuredOs ?? hostOS,
+                humanize: CONFIG.fingerprintDefaults.humanize ?? true,
+                ...(CONFIG.fingerprintDefaults.allowWebgl !== undefined
+                    ? { allow_webgl: CONFIG.fingerprintDefaults.allowWebgl }
+                    : {}),
                 enable_cache: true,
                 proxy: proxy ?? undefined,
                 geoip: !!proxy,
@@ -282,18 +385,25 @@ class ContextPool {
         if (headless !== undefined) {
             this.headlessOverrides.set(normalized, headless);
         }
-        const existing = this.pool.get(normalized);
-        if (existing) {
-            await this.closeContext(normalized);
+        // Close all contexts for this userId (there may be multiple with different profiles)
+        const entriesToClose = [];
+        for (const [profileKey, entry] of this.pool.entries()) {
+            if (entry.userId === normalized) {
+                entriesToClose.push(profileKey);
+            }
         }
-        return this.ensureContext(normalized);
+        for (const profileKey of entriesToClose) {
+            await this.closeContext(profileKey);
+        }
+        // Return a new entry with default key (for backward compatibility)
+        return this.ensureContext(normalized, normalized);
     }
     async evictIfNeeded() {
         if (this.pool.size <= MAX_CONTEXTS)
             return;
         let lru = null;
         for (const entry of this.pool.values()) {
-            if (entry.launching)
+            if (entry.launching || entry.staged)
                 continue;
             if (!lru || entry.lastAccess < lru.lastAccess)
                 lru = entry;
@@ -302,13 +412,17 @@ class ContextPool {
             return;
         (0, logging_1.log)('info', 'evicting persistent context (LRU)', { userId: lru.userId, profileDir: lru.profileDir });
         this.notifyEviction(lru.userId);
-        await this.closeContext(lru.userId);
+        await this.closeContext(lru.profileKey);
     }
-    async ensureContext(userId, options) {
+    async ensureContext(profileKey, userId, options, resolvedProxy, staged = false, stagedGeneration) {
         const normalized = String(userId);
-        let entry = this.pool.get(normalized);
+        let entry = this.pool.get(profileKey);
         const seed = pickSeedOptions(options);
         if (entry) {
+            if (staged) {
+                entry.staged = true;
+                entry.stagedGeneration = stagedGeneration;
+            }
             entry.lastAccess = Date.now();
             if (entry.launching) {
                 entry.context = await entry.launching;
@@ -322,7 +436,7 @@ class ContextPool {
                 void entry.context.pages();
             }
             catch {
-                this.pool.delete(normalized);
+                this.pool.delete(profileKey);
                 entry = undefined;
             }
         }
@@ -330,6 +444,7 @@ class ContextPool {
             if (seedDiffers(entry.seedOptions, seed)) {
                 (0, logging_1.log)('warn', 'persistent context already exists; ignoring new context overrides', {
                     userId: normalized,
+                    profileKey,
                     profileDir: entry.profileDir,
                 });
             }
@@ -340,11 +455,16 @@ class ContextPool {
         const newEntry = {
             context: null,
             userId: normalized,
+            profileKey,
             profileDir,
             lastAccess: Date.now(),
+            createdAt: Date.now(),
+            staged,
+            stagedGeneration,
+            proxyConfig: resolvedProxy || null,
             seedOptions: seed,
         };
-        newEntry.launching = this.launchPersistentContext(normalized, options)
+        newEntry.launching = this.launchPersistentContext(normalized, options, resolvedProxy)
             .then(({ context, virtualDisplay }) => {
             newEntry.context = context;
             newEntry.virtualDisplay = virtualDisplay;
@@ -352,27 +472,27 @@ class ContextPool {
             newEntry.lastAccess = Date.now();
             context.on('close', () => {
                 this.cleanupVirtualDisplay(newEntry);
-                (0, logging_1.log)('info', 'persistent context closed', { userId: normalized, profileDir });
-                this.pool.delete(normalized);
+                (0, logging_1.log)('info', 'persistent context closed', { userId: normalized, profileKey, profileDir });
+                this.pool.delete(profileKey);
             });
             return context;
         })
             .catch((err) => {
             this.cleanupVirtualDisplay(newEntry);
-            this.pool.delete(normalized);
+            this.pool.delete(profileKey);
             const message = err instanceof Error ? err.message : String(err);
-            (0, logging_1.log)('error', 'persistent context launch failed', { userId: normalized, profileDir, error: message });
+            (0, logging_1.log)('error', 'persistent context launch failed', { userId: normalized, profileKey, profileDir, error: message });
             throw err;
         });
-        this.pool.set(normalized, newEntry);
+        this.pool.set(profileKey, newEntry);
         await newEntry.launching;
         await this.evictIfNeeded();
         return newEntry;
     }
-    async closeContext(userId) {
-        const normalized = String(userId);
+    async closeContext(profileKey) {
+        const normalized = String(profileKey);
         const entry = this.pool.get(normalized);
-        if (!entry)
+        if (!entry || entry.staged)
             return;
         try {
             if (entry.launching) {
@@ -383,14 +503,77 @@ class ContextPool {
         }
         finally {
             this.cleanupVirtualDisplay(entry);
-            this.pool.delete(normalized);
-            (0, logging_1.log)('info', 'persistent context removed from pool', { userId: normalized, profileDir: entry.profileDir });
+            // Only delete if this entry is still in the pool (avoid deleting a newer entry with same key)
+            const currentEntry = this.pool.get(normalized);
+            if (currentEntry === entry) {
+                this.pool.delete(normalized);
+                (0, logging_1.log)('info', 'persistent context removed from pool', { userId: entry.userId, profileKey: normalized, profileDir: entry.profileDir });
+            }
+            else {
+                (0, logging_1.log)('info', 'persistent context closed but newer entry exists', { userId: entry.userId, profileKey: normalized, profileDir: entry.profileDir });
+            }
+        }
+    }
+    async closeContextIfMatches(profileKey, expectedCreatedAt, expectedLastAccess) {
+        const normalized = String(profileKey);
+        const entry = this.pool.get(normalized);
+        if (!entry)
+            return;
+        if (entry.createdAt !== expectedCreatedAt)
+            return;
+        // If lastAccess was provided and has changed, the context was reused - don't close
+        if (expectedLastAccess !== undefined && entry.lastAccess !== expectedLastAccess)
+            return;
+        await this.closeContext(normalized);
+    }
+    async closeStagedContext(profileKey, generation) {
+        const normalized = String(profileKey);
+        const entry = this.pool.get(normalized);
+        if (!entry?.staged)
+            return;
+        if (generation && entry.stagedGeneration !== generation)
+            return;
+        entry.staged = false;
+        entry.stagedGeneration = undefined;
+        await this.closeContext(normalized);
+    }
+    async closeContextByUserId(userId) {
+        const normalized = String(userId);
+        // Close all contexts for this userId
+        const entriesToClose = [];
+        for (const [profileKey, entry] of this.pool.entries()) {
+            if (entry.userId === normalized && !entry.staged) {
+                entriesToClose.push(profileKey);
+            }
+        }
+        for (const profileKey of entriesToClose) {
+            await this.closeContext(profileKey);
+        }
+    }
+    async closeStagedContextByUserId(userId, generation) {
+        const normalized = String(userId);
+        // Close all staged contexts for this userId
+        const entriesToClose = [];
+        for (const [profileKey, entry] of this.pool.entries()) {
+            if (entry.userId === normalized && entry.staged) {
+                if (!generation || entry.stagedGeneration === generation) {
+                    entriesToClose.push(profileKey);
+                }
+            }
+        }
+        for (const profileKey of entriesToClose) {
+            await this.closeStagedContext(profileKey, generation);
         }
     }
     async closeAll() {
-        const userIds = Array.from(this.pool.keys());
-        for (const userId of userIds) {
-            await this.closeContext(userId);
+        const profileKeys = Array.from(this.pool.keys());
+        for (const profileKey of profileKeys) {
+            const entry = this.pool.get(profileKey);
+            if (entry?.staged) {
+                entry.staged = false;
+                entry.stagedGeneration = undefined;
+            }
+            await this.closeContext(profileKey);
         }
     }
 }