jumpy-lion 0.1.6-beta.7 → 1.0.0-beta.0

package/dist/browser-process/launch-options.d.ts

@@ -0,0 +1,301 @@
+import type { FingerprintConfigJson } from './anti-detect-config.js';
+import type { ResolvedLocale } from '../fingerprinting/locale-resolver.js';
+/**
+ * Fingerprint-GENERATION inputs - mirrors the subset of Crawlee's
+ * `browserPoolOptions.fingerprintOptions.fingerprintGeneratorOptions`
+ * (from `fingerprint-generator`) that cdp-crawler forwards. This selects
+ * *which* fingerprint identity to synthesize; it is a wholly separate concept
+ * from `FingerprintOptions` below (which spoof surfaces to enforce and how).
+ * See issue #80 - the two must not be conflated.
+ */
+export interface FingerprintGeneratorOptions {
+    /** Operating systems to generate fingerprints for (e.g., ["windows"], ["macos"], ["linux"]) */
+    operatingSystems?: string[];
+    /** Devices to generate fingerprints for (e.g., ["desktop"], ["mobile"]) */
+    devices?: string[];
+    /** Browsers to generate fingerprints for (e.g., ["chrome"], ["firefox"]) */
+    browsers?: string[];
+    /** Locales to generate fingerprints for (e.g., ["en-US"], ["it-IT"]) */
+    locales?: string[];
+}
+/**
+ * Humanization options for simulating realistic user behavior.
+ * All options are disabled by default for performance.
+ */
+export interface HumanizationOptions {
+    /** Enable mouse movement humanization. Default: false */
+    mouse?: boolean;
+    /** Enable keyboard humanization. Default: false */
+    keyboard?: boolean;
+    /** Enable scroll humanization. Default: false */
+    scroll?: boolean;
+}
+/**
+ * Fingerprint-spoofing options shared by the JS override pipeline
+ * (CdpFingerprintInjector) and the native-stealth (C++) launch path.
+ */
+export interface FingerprintOptions {
+    /**
+     * Legacy nested location for the top-level `useNativeStealth` flag.
+     * Normalized to `launchOptions.useNativeStealth` by resolveUseNativeStealth()
+     * in session-profile.ts before launch; prefer the top-level field.
+     */
+    useNativeStealth?: boolean;
+    enableAdvancedStealth?: boolean;
+    bypassRuntimeEnable?: boolean;
+    spoofWebGL?: boolean;
+    spoofAudioContext?: boolean;
+    spoofClientRects?: boolean;
+    maskAutomationFlags?: boolean;
+    useFingerprintDefaults?: boolean;
+    platform?: 'Win32' | 'MacIntel' | 'Linux x86_64';
+    spoofFonts?: boolean;
+    spoofPerformance?: boolean;
+    spoofLocale?: boolean;
+    detectTimezone?: boolean;
+    useExperimentalFingerprints?: boolean;
+    /**
+     * BCP-47 locale tag (e.g. 'ko-KR', 'de-DE'). One flag that coherently drives
+     * navigator.language(s), Accept-Language header, Intl defaults, currency
+     * symbol, date/number formatting, and timezone (derived from region).
+     * When unset, falls back to proxy-country lookup → fingerprint language → 'en-US'.
+     */
+    locale?: string;
+    /** Explicit IANA timezone (e.g. 'Asia/Seoul'). Overrides locale-derived timezone. */
+    timezone?: string;
+    /** Explicit Accept-Language header (e.g. 'ko-KR,ko;q=0.9'). Overrides locale-derived list. */
+    languages?: string;
+    bypassCDPDetection?: boolean;
+    spoofStorage?: boolean;
+    spoofTiming?: boolean;
+    enableDataDomeBypass?: boolean;
+    /** WebRTC policy inside page scripts. Default: 'spoof'. */
+    webRtcPolicy?: 'spoof' | 'disable';
+    /** Humanization options (all disabled by default) */
+    humanization?: HumanizationOptions;
+    /** Enable debug logging in browser console. Default: true for debugging */
+    debug?: boolean;
+    /**
+     * Use real Chrome device profiles (Camoufox-inspired) instead of the
+     * Apify fingerprint-generator statistical model. Profiles are sampled from
+     * a bundled database of real devices where every property - navigator,
+     * screen, GPU, UA-CH - was measured on the same physical hardware,
+     * guaranteeing cross-property consistency. If the `camoufox` Python package
+     * is installed and `preferCamoufox` is true, Firefox device-level data is
+     * extracted and mapped to Chrome values.
+     * Default: false
+     */
+    useNonApifyFingerprints?: boolean;
+    /**
+     * Explicit fingerprint seed key for tests / A-B harvest comparisons.
+     * Production derives the seed from the proxy URL's `session-X` token;
+     * this field lets harvest runs on different hosts (Mac vs Linux Docker)
+     * hit the SAME bundled profile without needing a fake proxy.
+     */
+    seedKey?: string;
+    /**
+     * Force WebGL to render through the in-process emulated WebGraphics
+     * Context3DProvider instead of relying on a real GPU. Default: false.
+     *
+     * Why this matters on Apify-linux Docker containers:
+     *   The Docker image has no GPU. The Chromium GPU process therefore
+     *   crashes during init (vkCreateInstance: no drivers, no compositor
+     *   adapter, "Exiting GPU process due to errors during initialization"),
+     *   which transitively kills WebGL context creation in the renderer:
+     *
+     *     [...]ERROR:gpu/command_buffer/.../gles2_cmd_decoder_passthrough.cc:1073]
+     *       Automatic fallback to software WebGL has been deprecated.
+     *       Please use the --enable-unsafe-swiftshader flag to opt in to
+     *       lower security guarantees for trusted content.
+     *
+     *   Chrome ≥126 removed the implicit fall-back-to-SwiftShader behaviour
+     *   that used to mask a missing GPU. Without an explicit switch,
+     *   `canvas.getContext('webgl')` returns null on a GPU-less container.
+     *   Real Chrome on a real desktop ALWAYS exposes WebGL, so a missing
+     *   WebGL context is itself a strong bot tell.
+     *
+     * What setting this to true does:
+     *   Pushes the anti-detect binary's bespoke `--force-webgl-emulation`
+     *   Chromium command-line switch. The switch is declared in
+     *   chrome/common/chrome_switches.{h,cc} and propagated to renderer/
+     *   GPU child processes via the kCommonSwitchNames list in
+     *   chrome/browser/chrome_content_browser_client.cc. The renderer-side
+     *   factory hook at third_party/blink/renderer/modules/webgl/
+     *   webgl_rendering_context_base.cc::CreateContextProviderInternal
+     *   reads the switch + FingerprintConfig::IsLoaded() and, when both
+     *   are true, instantiates the in-process
+     *   EmulatedWebGraphicsContext3DProvider instead of asking the GPU
+     *   process for a command buffer. The provider returns a non-null
+     *   WebGLRenderingContext whose getParameter values come from
+     *   FingerprintConfig (vendor/renderer/max texture size) and a
+     *   bundled Mac M1 baseline (other queryable params), and whose
+     *   readPixels output is a deterministic xoshiro256** noise pattern
+     *   seeded from FingerprintConfig.seed (plus a recorded baseline
+     *   pixel buffer for known fingerprint probe shaders).
+     *
+     *   The C++ provider ALSO acts as a fallback (without this switch)
+     *   when the upstream real-GL / SwiftShader path returns null - set
+     *   this flag to TRUE only when you want to skip real-GL entirely on
+     *   hosts where it might otherwise succeed but degrade unpredictably
+     *   (e.g. Apify Linux containers).
+     */
+    forceEmulateWebgl?: boolean;
+}
+/**
+ * Advanced options for the JS fingerprint-override pipeline (issue #80).
+ *
+ * These configure the JS injector's per-surface override modules. They belong
+ * under `stealth.overrides` when the `js` engine is selected - see
+ * {@link StealthOptions}. They are meaningless on the native engine (the C++
+ * binary owns every surface), which is why the discriminated union makes them
+ * settable ONLY under `engine: 'js'`.
+ *
+ * Keys are the community-canonical fingerprint-surface names (canvas/webgl/audio/
+ * clientRects/fonts/webrtc/… - the vocabulary used by fingerprintjs, CreepJS,
+ * puppeteer-extra) rather than ad-hoc `spoofX`/`maskX`/`bypassX` verbs. Each maps
+ * 1:1 onto an entry in the internal override registry. All spoof surfaces default
+ * to ON (opt-out); `webrtc` defaults to `'spoof'`; `dataDomeBypass` defaults OFF.
+ *
+ * Identity/locale/routing knobs (`platform`, `locale`, `useNonApifyFingerprints`,
+ * …) are intentionally NOT part of this group. The legacy per-surface toggles on
+ * `fingerprintOptions` (`spoofWebGL`, `maskAutomationFlags`, …) remain honoured as
+ * a deprecated alias.
+ */
+export interface JsOverrideOptions {
+    /** Master gate for the advanced spoof set. Default: true. */
+    advancedStealth?: boolean;
+    /** WebGL `getParameter` / debug-renderer spoofing. Default: true. */
+    webgl?: boolean;
+    /** AudioContext fingerprint noise. Default: true. */
+    audio?: boolean;
+    /** `getBoundingClientRect` sub-pixel jitter. Default: true. */
+    clientRects?: boolean;
+    /** Font-enumeration spoofing. Default: true. */
+    fonts?: boolean;
+    /** `performance.now` shaping. Default: true. */
+    performance?: boolean;
+    /** `Intl` / locale formatting consistency. Default: true. */
+    locale?: boolean;
+    /** Storage-quota consistency. Default: true. */
+    storage?: boolean;
+    /** `Date.now` alignment. Default: true. */
+    timing?: boolean;
+    /** CDP-detection bypass (iframe/eval/sourceURL hiding). Default: true. */
+    cdpDetection?: boolean;
+    /** navigator.webdriver removal + automation-artifact masking. Default: true. */
+    automation?: boolean;
+    /** WebRTC handling. Default: `'spoof'`. */
+    webrtc?: 'spoof' | 'disable';
+    /** DataDome-specific bypass (JS challenges, proof-of-work). Default: false. */
+    dataDomeBypass?: boolean;
+    /** Human-like input behavior (mouse/keyboard/scroll). All off by default. */
+    humanization?: HumanizationOptions;
+    /**
+     * Use the generated fingerprint's values instead of hardcoded defaults for
+     * navigator/WebGL/UA-CH. Default: true for synthetic profiles.
+     */
+    useFingerprintDefaults?: boolean;
+    /** Verbose in-page debug logging. Default: false. */
+    debug?: boolean;
+}
+/**
+ * The fingerprint-enforcement engine - a mutually-exclusive choice (issue #80).
+ *
+ * Native stealth (the C++ anti-detect binary) and the JS override pipeline are
+ * two engines that cannot both run: under native stealth the JS bundle is
+ * skipped entirely, so JS spoof toggles are silently inert. Modelling the choice
+ * as a discriminated union makes that exclusivity explicit - `overrides` is only
+ * settable under `engine: 'js'`, so it is a *type error* to configure JS spoof
+ * toggles while the native engine is selected.
+ *
+ * Canonical selector for `launchOptions.stealth`. The legacy `useNativeStealth`
+ * boolean (+ its nested/root mirrors) and the JS toggles on `fingerprintOptions`
+ * are still honoured as deprecated aliases; `stealth` wins when set.
+ */
+export type StealthOptions = {
+    /** C++ anti-detect binary owns every fingerprint surface; no JS overrides apply. */
+    engine: 'native';
+} | {
+    /** JS fingerprint-override injection pipeline (stock Chrome). */
+    engine: 'js';
+    /** Advanced spoof/humanization toggles - only meaningful on this engine. */
+    overrides?: JsOverrideOptions;
+};
+/**
+ * Launch options shared by the plugin layer (CDPBrowserPlugin) and the
+ * process layer (browser-process/browser.ts). Each layer extends this with
+ * its own fields - the plugin adds Crawlee-facing fields (browserType,
+ * proxyUrl, sessionBundle, …); the process layer adds spawn-time fields
+ * (anonymizedProxyUrl, debuggingPort, …).
+ */
+export interface BaseLaunchBrowserOptions {
+    /**
+     * The fingerprint-enforcement engine and its config (issue #80). Selecting
+     * `{ engine: 'js', overrides: { … } }` is the canonical, discoverable home
+     * for the JS spoof/humanization toggles; `{ engine: 'native' }` selects the
+     * C++ binary and makes those toggles a type error. Wins over the deprecated
+     * `useNativeStealth` boolean and the JS toggles on `fingerprintOptions`.
+     */
+    stealth?: StealthOptions;
+    ignoreHttpsErrors?: boolean;
+    headless?: boolean;
+    executablePath?: string;
+    useExperimentalFingerprints?: boolean;
+    /**
+     * Use the C++ anti-detect browser patches (Cromite-based custom binary)
+     * instead of the JS fingerprint override pipeline. When true, the plugin
+     * auto-resolves the binary installed by postinstall.js unless an explicit
+     * `executablePath` (or ANTI_DETECT_CHROME_PATH) pins one, and the entire
+     * JS injection bundle is skipped - C++ patches handle all fingerprinting.
+     * If the binary is not an anti-detect build, the process layer falls back
+     * to plain stealth args for system Chrome.
+     * Default: false
+     */
+    useNativeStealth?: boolean;
+    /** Whether to start the browser maximized and fullscreen. Default: true */
+    maximizeWindow?: boolean;
+    /** Window width in pixels. Default: 1920 */
+    windowWidth?: number;
+    /** Window height in pixels. Default: 1080 */
+    windowHeight?: number;
+    /**
+     * Reuse a specific Chrome user data directory across runs.
+     * When provided, this directory is preserved by default.
+     */
+    userDataDir?: string;
+    /**
+     * Force keeping or cleaning the profile directory on close.
+     * Defaults to true for temporary profiles and false for custom userDataDir.
+     */
+    keepUserDataDir?: boolean;
+    /**
+     * DNS-over-HTTPS endpoint template, for example:
+     * https://cloudflare-dns.com/dns-query
+     */
+    dnsOverHttpsServer?: string;
+    /** Chromium secure DNS mode. Default: 'secure' when dnsOverHttpsServer is set. */
+    secureDnsMode?: 'off' | 'automatic' | 'secure';
+    /**
+     * WebRTC IP handling policy. Recommended stealth value:
+     * disable_non_proxied_udp
+     */
+    webrtcIpHandlingPolicy?: 'default' | 'default_public_interface_only' | 'default_public_and_private_interfaces' | 'disable_non_proxied_udp';
+    fingerprintOptions?: FingerprintOptions;
+    /**
+     * Pre-generated platform-overrides JSON to pass via --blink-platform-overrides-file
+     * to the anti-detect browser. When provided, this overrides the static
+     * default_fingerprint.json so that each browser instance gets unique C++-level
+     * platform values (GPU, screen, CPU count, device memory) derived from the real
+     * device profile.
+     */
+    fingerprintConfig?: FingerprintConfigJson;
+    /**
+     * Pre-resolved locale triple from `resolveLocale()`. Populated in browser-plugin
+     * before launch so the native-stealth launch args (`--lang`,
+     * `--fingerprint-accept-language`, LANG/LC_ALL env vars) and the CDP-path
+     * injector read the same values and stay coherent. Consumers should prefer
+     * this over re-deriving from fingerprintOptions.
+     */
+    resolvedLocale?: ResolvedLocale;
+}
+//# sourceMappingURL=launch-options.d.ts.map

package/dist/browser-process/launch-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-options.d.ts","sourceRoot":"","sources":["../../src/browser-process/launch-options.ts"],"names":[],"mappings":"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"}

package/dist/browser-process/launch-options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=launch-options.js.map

package/dist/browser-process/launch-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-options.js","sourceRoot":"","sources":["../../src/browser-process/launch-options.ts"],"names":[],"mappings":""}

package/dist/browser-process/port-allocator.d.ts

@@ -0,0 +1,64 @@
+/**
+ * PortAllocator - owns the Chrome debugging-port pool.
+ *
+ * Interface is two methods: `acquire()` / `release(port)`. The implementation
+ * owns the range, acquisition serialization, the wraparound scan, the
+ * probe-busy quarantine, and the stale-port sweep. The OS socket probe sits
+ * behind the narrow `PortProbe` seam: real socket adapter in production,
+ * scripted adapter in tests.
+ */
+export interface PortProbe {
+    /** True when the port can be bound on 127.0.0.1 right now. */
+    isFree(port: number): Promise<boolean>;
+}
+/**
+ * Production adapter: try to bind a throwaway server on 127.0.0.1.
+ * Resolves false on bind error or after a 2 s safety timeout.
+ */
+export declare const socketPortProbe: PortProbe;
+export interface PortAllocatorOptions {
+    min?: number;
+    max?: number;
+    probe?: PortProbe;
+    /** How long a probe-busy port stays quarantined before it may be retried. */
+    quarantineMs?: number;
+    /**
+     * Grace period after `acquire()` during which the stale sweep will NOT
+     * reclaim a reserved port, even though the probe reports it free. Covers the
+     * window between handing a port out and Chrome actually binding it.
+     */
+    launchGraceMs?: number;
+    /** Injectable clock (tests drive it); defaults to `Date.now`. */
+    now?: () => number;
+}
+export declare class PortAllocator {
+    private readonly min;
+    private readonly max;
+    private readonly probe;
+    private readonly quarantineMs;
+    private readonly launchGraceMs;
+    private readonly now;
+    private readonly usedPorts;
+    private lastAssignedPort;
+    /** Serializes acquire() calls - concurrent launches never race the scan. */
+    private acquireChain;
+    constructor(options?: PortAllocatorOptions);
+    acquire(): Promise<number>;
+    release(port: number): void;
+    private _acquireSerialized;
+    /**
+     * Drop tracked ports whose owner has since exited (probe binds OK).
+     * A crash path that never called release() would otherwise leak the slot
+     * forever.
+     *
+     * Reserved ports are protected for `launchGraceMs` after acquisition: a
+     * port is handed out BEFORE Chrome starts, so between `acquire()` and the
+     * browser binding its debug socket the probe legitimately reports the port
+     * free. Sweeping there un-tracked a port whose browser was still launching
+     * and handed the same port to a second browser - one of the two then failed
+     * to bind. Quarantine entries carry no such window (they were never ours),
+     * so they stay immediately reclaimable.
+     */
+    private _sweepStalePorts;
+}
+//# sourceMappingURL=port-allocator.d.ts.map

package/dist/browser-process/port-allocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-allocator.d.ts","sourceRoot":"","sources":["../../src/browser-process/port-allocator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,WAAW,SAAS;IACtB,8DAA8D;IAC9D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SA+B7B,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAcD,qBAAa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,gBAAgB,CAAS;IACjC,4EAA4E;IAC5E,OAAO,CAAC,YAAY,CAAuC;gBAE/C,OAAO,GAAE,oBAAyB;IAUxC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAShC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;YAWb,kBAAkB;IAgDhC;;;;;;;;;;;;OAYG;YACW,gBAAgB;CAcjC"}

package/dist/browser-process/port-allocator.js

@@ -0,0 +1,198 @@
+/**
+ * PortAllocator - owns the Chrome debugging-port pool.
+ *
+ * Interface is two methods: `acquire()` / `release(port)`. The implementation
+ * owns the range, acquisition serialization, the wraparound scan, the
+ * probe-busy quarantine, and the stale-port sweep. The OS socket probe sits
+ * behind the narrow `PortProbe` seam: real socket adapter in production,
+ * scripted adapter in tests.
+ */
+import net from 'node:net';
+import { log } from 'crawlee';
+/**
+ * Production adapter: try to bind a throwaway server on 127.0.0.1.
+ * Resolves false on bind error or after a 2 s safety timeout.
+ */
+export const socketPortProbe = {
+    async isFree(port) {
+        return new Promise((resolve) => {
+            const server = net.createServer();
+            let resolved = false;
+            const finish = (result) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                try {
+                    server.close();
+                }
+                catch {
+                    // Ignore errors during cleanup
+                }
+                resolve(result);
+            };
+            server.once('error', () => finish(false));
+            server.once('listening', () => finish(true));
+            // Safety timeout to prevent hanging
+            const timer = setTimeout(() => finish(false), 2000);
+            timer.unref?.();
+            try {
+                server.listen(port, '127.0.0.1');
+            }
+            catch {
+                finish(false);
+            }
+        });
+    },
+};
+export class PortAllocator {
+    constructor(options = {}) {
+        Object.defineProperty(this, "min", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "max", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "probe", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "quarantineMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "launchGraceMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "now", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "usedPorts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "lastAssignedPort", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Serializes acquire() calls - concurrent launches never race the scan. */
+        Object.defineProperty(this, "acquireChain", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Promise.resolve()
+        });
+        this.min = options.min ?? 9200;
+        this.max = options.max ?? 9600;
+        this.probe = options.probe ?? socketPortProbe;
+        this.quarantineMs = options.quarantineMs ?? 5000;
+        this.launchGraceMs = options.launchGraceMs ?? 15000;
+        this.now = options.now ?? Date.now;
+        this.lastAssignedPort = this.min - 1;
+    }
+    async acquire() {
+        // Chain onto the previous acquire so the scan below never interleaves
+        // with another caller's - the replacement for the old static spin-lock.
+        const result = this.acquireChain.then(async () => this._acquireSerialized());
+        // Keep the chain alive even when an acquire rejects (pool exhausted).
+        this.acquireChain = result.catch(() => { });
+        return result;
+    }
+    release(port) {
+        // Idempotent: the browser close/error/disconnect handlers can all fire
+        // for one instance.
+        if (this.usedPorts.has(port)) {
+            this.usedPorts.delete(port);
+            log.debug(`Released port ${port} back to pool. Used ports: ${this.usedPorts.size}/${this.max - this.min + 1}`);
+        }
+        else {
+            log.debug(`Attempted to release port ${port} that was not in use`);
+        }
+    }
+    async _acquireSerialized() {
+        const maxAttempts = this.max - this.min + 1;
+        for (let attempts = 0; attempts < maxAttempts; attempts++) {
+            // Increment the last assigned port, wrapping around if necessary
+            this.lastAssignedPort++;
+            if (this.lastAssignedPort > this.max) {
+                this.lastAssignedPort = this.min;
+                log.debug('Port range wrapped around, starting from beginning');
+            }
+            const candidatePort = this.lastAssignedPort;
+            // Skip if port is already tracked as in use
+            if (this.usedPorts.has(candidatePort)) {
+                continue;
+            }
+            if (await this.probe.isFree(candidatePort)) {
+                this.usedPorts.set(candidatePort, { at: this.now(), quarantined: false });
+                log.debug(`Reserved port ${candidatePort} for browser instance (attempt ${attempts + 1})`);
+                return candidatePort;
+            }
+            // Probe says busy (something outside the pool holds it) -
+            // quarantine so the scan doesn't retry it immediately.
+            this.usedPorts.set(candidatePort, { at: this.now(), quarantined: true });
+            const timer = setTimeout(() => {
+                this.usedPorts.delete(candidatePort);
+            }, this.quarantineMs);
+            timer.unref?.();
+        }
+        // Every port is tracked or probe-busy: sweep stale entries and rescan.
+        log.warning(`All ports in range ${this.min}-${this.max} are in use. Attempting cleanup.`);
+        await this._sweepStalePorts();
+        for (let port = this.min; port <= this.max; port++) {
+            if (!this.usedPorts.has(port) && await this.probe.isFree(port)) {
+                this.usedPorts.set(port, { at: this.now(), quarantined: false });
+                log.debug(`Reserved port ${port} after cleanup`);
+                return port;
+            }
+        }
+        throw new Error(`No available ports found in the configured range ${this.min}-${this.max} after maximum attempts and cleanup`);
+    }
+    /**
+     * Drop tracked ports whose owner has since exited (probe binds OK).
+     * A crash path that never called release() would otherwise leak the slot
+     * forever.
+     *
+     * Reserved ports are protected for `launchGraceMs` after acquisition: a
+     * port is handed out BEFORE Chrome starts, so between `acquire()` and the
+     * browser binding its debug socket the probe legitimately reports the port
+     * free. Sweeping there un-tracked a port whose browser was still launching
+     * and handed the same port to a second browser - one of the two then failed
+     * to bind. Quarantine entries carry no such window (they were never ours),
+     * so they stay immediately reclaimable.
+     */
+    async _sweepStalePorts() {
+        log.debug('Cleaning up stale ports');
+        const now = this.now();
+        for (const [port, lease] of Array.from(this.usedPorts)) {
+            if (!lease.quarantined && now - lease.at < this.launchGraceMs) {
+                log.debug(`Skipping port ${port} - still inside the ${this.launchGraceMs}ms launch grace window`);
+                continue;
+            }
+            if (await this.probe.isFree(port)) {
+                this.usedPorts.delete(port);
+                log.debug(`Cleaned up stale port ${port}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=port-allocator.js.map

package/dist/browser-process/port-allocator.js.map

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