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

package/dist/browser-process/browser.js

@@ -3,12 +3,13 @@ import fs from 'fs/promises';
 import os from 'os';
 import path from 'path';
 import { log } from '@crawlee/core';
-import { getChromeBinaryVersion, getChromeExecutablePath, getAntiDetectBrowserPath } from './get-chrome-executable.js';
+import { isAntiDetectBrowserSync } from './anti-detect-browser.js';
+import { writeTempFingerprintConfig } from './anti-detect-config.js';
+import { getChromeExecutablePath, getAntiDetectBrowserPath } from './get-chrome-executable.js';
 import { BrowserProcess } from './process.js';
+import { seedWidevineCdm } from './widevine-cdm.js';
 import { populateChromeProfile } from '../browser-profiles/chrome/populate-profile.js';
 import { createChromeProfile } from '../browser-profiles/index.js';
-import { isAntiDetectBrowserSync } from './anti-detect-browser.js';
-import { writeTempFingerprintConfig } from './anti-detect-config.js';
 const EXTENSION_PATH = path.resolve(import.meta.dirname, '../fingerprinting/all-fingerprint-defender');
 const EXTENSION_PATH2 = path.resolve(import.meta.dirname, '../fingerprinting/anti-webgpu');
 // --lang is intentionally NOT hardcoded below. It is appended per-session from the
@@ -18,25 +19,35 @@ const EXTENSION_PATH2 = path.resolve(import.meta.dirname, '../fingerprinting/ant
 // Flag policy (see ChromeDriver default-switch audit in git history for full evidence):
 //
 //   Dropped as actively harmful:
-//     --enable-features=NetworkService,NetworkServiceInProcess  — desktop default is DISABLED
+//     --enable-features=NetworkService,NetworkServiceInProcess  - desktop default is DISABLED
 //         since M89; forcing it creates a runtime state no real user has.
-//     --disable-ipc-flooding-protection  — JS-probeable via 201+ history.pushState()/10s.
+//     --disable-ipc-flooding-protection  - JS-probeable via 201+ history.pushState()/10s.
 //
 //   Dropped because they have a concrete page-JS detection probe:
-//     --disable-popup-blocking  — window.open() null-vs-non-null from a timer.
-//     --disable-renderer-backgrounding  — document.visibilityState / rAF throttling.
-//     --disable-backgrounding-occluded-windows  — same surface; internally named
-//         kDisableBackgroundingOccludedWindowsForTesting.
-//     --disable-component-extensions-with-background-pages  — speechSynthesis.getVoices()
+//     --disable-popup-blocking  - window.open() null-vs-non-null from a timer.
+//     --disable-component-extensions-with-background-pages  - speechSynthesis.getVoices()
 //         leaks the missing TTS component extension.
 //
+//   Conditionally added based on which binary we launch:
+//     --disable-renderer-backgrounding + --disable-backgrounding-occluded-windows
+//         auto-enabled when launching the anti-detect binary; the binary's
+//         direct source-tree edit to document.visibilityState / document.hidden
+//         hides the rAF / setTimeout throttling tell, so these flags are safe.
+//         On vanilla Chrome they remain opt-in via CHROMIUM_KEEP_BACKGROUNDING=1.
+//         macOS's own compositor-pause-on-occlusion path is in
+//         WebContentsViewCocoa and has no command-line switch - the anti-detect
+//         binary drops the kOccluded transition directly in
+//         content/app_shim_remote_cocoa/web_contents_view_cocoa.mm.
+//
 //   Dropped because they are provably dead or placebo:
-//     --disable-translate  — string absent from Chromium switches files; noop since ~2018.
-//     --disable-infobars  — infobar_manager.cc:22-31 gate requires --headless OR a
+//     --disable-translate  - string absent from Chromium switches files; noop since ~2018.
+//     --disable-infobars  - infobar_manager.cc:22-31 gate requires --headless OR a
 //         Chrome-for-Testing build; never active in our setup.
-//     --disable-blink-features=AutomationControlled  — only blocks the disabled-by-default
+//     --disable-blink-features=AutomationControlled  - only blocks the disabled-by-default
 //         RuntimeEnabledFeatures path; the actual webdriver-setter is
-//         probe::ApplyAutomationOverride via CDP, which Cromite patch 0001 already no-ops.
+//         probe::ApplyAutomationOverride via CDP, which the anti-detect binary's
+//         direct edit to inspector_emulation_agent.cc / navigator.cc already no-ops
+//         (Navigator::webdriver() hardcoded to false).
 //
 //   Dropped because they are network-signature flags absent from modern stealth tooling
 //   (nodriver / Patchright) with no page-JS benefit on our setup:
@@ -48,6 +59,21 @@ const EXTENSION_PATH2 = path.resolve(import.meta.dirname, '../fingerprinting/ant
  *   (a) no known page-JS observable probe, AND
  *   (b) an operational or consistency justification (avoid startup dialogs, reduce
  *       automation-irrelevant background work, match realistic fresh-profile defaults).
+ *
+ * Two operationally-detectable flags moved to opt-in env vars:
+ *   - --disable-renderer-backgrounding / --disable-backgrounding-occluded-windows
+ *     (rAF throttle probe): opt in via CHROMIUM_KEEP_BACKGROUNDING=1 for local
+ *     headfull dev where window focus loss would otherwise stall the crawl. The
+ *     document.hidden() C++ override (cromite patch D26) handles the JS-property
+ *     side of the visibility spoof regardless.
+ *   - --use-angle=swiftshader (WebGL perf probe + tell on macOS): opt in via
+ *     CHROMIUM_USE_SWIFTSHADER=1 for canvas/WebGL pixel parity between local-mac
+ *     (Metal-capable) and Apify-linux. Off by default lets ANGLE Metal/D3D/GL
+ *     run natively. The anti-detect binary's direct source-tree edit to
+ *     WebGLRenderingContextBase::getParameter (in
+ *     third_party/blink/renderer/modules/webgl/webgl_rendering_context_base.cc)
+ *     still spoofs UNMASKED_VENDOR_WEBGL / UNMASKED_RENDERER_WEBGL regardless
+ *     of which backend ANGLE picks.
  */
 const UNIVERSAL_STEALTH_ARGS = [
     // CDP transport: Chrome 111+ requires an origin allow-list for WebSocket connections
@@ -61,28 +87,118 @@ const UNIVERSAL_STEALTH_ARGS = [
     '--disable-session-crashed-bubble',
     // Suppress the EU search-engine choice modal, which would block a fresh profile.
     '--disable-search-engine-choice-screen',
-    // Predictable startup URL — blank page instead of NTP fetch.
+    // Predictable startup URL - blank page instead of NTP fetch.
     '--homepage=about:blank',
     // Operational: do not show the "Page Unresponsive" dialog mid-crawl. No JS probe.
     '--disable-hang-monitor',
     // Operational: suppress the "Confirm form resubmission" dialog on POST reload. No JS probe.
     '--disable-prompt-on-repost',
 ];
+/**
+ * Optional flags gated on env vars. Adding either of these to the launch argv
+ * narrows operational pain (headfull focus-loss stalls; canvas parity drift)
+ * but adds a fingerprint surface that real Chrome users do not have.
+ *
+ * Default-off so production crawls ship the cleanest argv we can manage. Local
+ * dev opts in via env. The anti-detect binary path also auto-enables the
+ * backgrounding flags - see `getAntiDetectBackgroundingArgs`.
+ */
+function getOptionalStealthArgs() {
+    const out = [];
+    if (process.env.CHROMIUM_KEEP_BACKGROUNDING === '1'
+        || process.env.CHROMIUM_KEEP_BACKGROUNDING === 'true') {
+        // Keep the renderer running at full speed when the OS window loses focus
+        // or is occluded. Without these, headfull dev stalls when the user
+        // alt-tabs away - Chrome drops renderer priority and clamps setTimeout
+        // to ≥1s. (render_process_host_impl.cc; web_contents_impl.cc.)
+        //
+        // Trade-off: rAF/setTimeout drift while document.hidden===true is JS-probeable.
+        out.push('--disable-renderer-backgrounding');
+        out.push('--disable-backgrounding-occluded-windows');
+    }
+    if (process.env.CHROMIUM_USE_SWIFTSHADER === '1'
+        || process.env.CHROMIUM_USE_SWIFTSHADER === 'true') {
+        // Force ANGLE → SwiftShader so canvas/WebGL pixel output is identical
+        // between local-mac (Metal-capable) and Apify-linux (no GPU). Cromite's
+        // seeded pixel noise is a delta on top of a baseline; the baseline must
+        // match to make the final hash reproducible across hosts.
+        //
+        // Trade-off: WebGL perf benchmarks (timing a heavy scene) can detect
+        // SwiftShader on macOS hardware. Mainstream anti-bot vendors hash
+        // statically, but the flag is also visible in /proc/<pid>/cmdline on
+        // Linux when --no-sandbox is active.
+        out.push('--use-angle=swiftshader');
+    }
+    return out;
+}
+/**
+ * Backgrounding/occlusion suppression. Auto-enabled when launching the
+ * cromite anti-detect binary because cromite patch D26 pins
+ * `document.visibilityState` / `document.hidden` to "visible" at the
+ * Blink layer, so the rAF/setTimeout drift these flags would expose on
+ * vanilla Chrome is invisible to page JS under the patched binary.
+ *
+ * On macOS the equivalent of `CalculateNativeWinOcclusion` (the AURA
+ * Linux/Windows path) is `WebContentsViewCocoa.updateWebContentsVisibility`
+ * which has NO command-line kill switch - the kOccluded transition is
+ * hardcoded in content/app_shim_remote_cocoa/web_contents_view_cocoa.mm.
+ * That path is patched out in the cromite binary directly (see the
+ * "Anti-Detect: drop the kOccluded branch" patch), so no darwin-only
+ * launch flag is needed (or available) for the same effect.
+ *
+ * What these flags still do on macOS:
+ *   --disable-renderer-backgrounding stops the renderer-process priority
+ *     drop when our window is not the key window (CDP-driven sessions
+ *     often never become key).
+ *   --disable-backgrounding-occluded-windows stops the priority drop
+ *     specifically on occlusion (separate from the visibility transition
+ *     fixed by the cromite Cocoa patch).
+ */
+function getAntiDetectBackgroundingArgs(_platform) {
+    return [
+        '--disable-renderer-backgrounding',
+        '--disable-backgrounding-occluded-windows',
+    ];
+}
 /**
  * Linux-specific flags. Necessary for server-side operation; no page-JS probe on any:
  *   --no-sandbox: running as root or in a rootless container where seccomp-bpf is
  *       unavailable. Not observable from page JS (/proc/self/status is not reachable
- *       from the renderer).
- *   --disable-dev-shm-usage: Docker's default /dev/shm is 64 MB — renderers crash when
+ *       from the renderer). Can be opted out with $CHROMIUM_KEEP_SANDBOX=1 when the
+ *       container is rootless AND the host kernel allows user namespaces - e.g.
+ *       modern Apify runners that drop privileges to UID 1000. The kernel-level
+ *       sandbox is a small extra defense and removing the --no-sandbox flag
+ *       reduces /proc/<pid>/cmdline noise.
+ *   --disable-dev-shm-usage: Docker's default /dev/shm is 64 MB - renderers crash when
  *       it fills. Backing switches to /tmp. Not observable from page JS.
  *   --password-store=basic: avoid blocking on gnome-keyring/kwallet prompts. Not
  *       observable from page JS.
  */
-const LINUX_STEALTH_ARGS = [
-    '--no-sandbox',
+const LINUX_STEALTH_ARGS_BASE = [
     '--disable-dev-shm-usage',
     '--password-store=basic',
 ];
+/**
+ * Build the Linux flag list at runtime so the $CHROMIUM_KEEP_SANDBOX opt-out is
+ * picked up per-launch (process env can change between calls in long-running
+ * processes, e.g. when an Apify actor sets the var at startup).
+ *
+ * `--disable-setuid-sandbox` ships alongside `--no-sandbox`: even with
+ * `--no-sandbox`, Chrome may try to call the setuid sandbox helper
+ * (chrome_sandbox / chrome-sandbox) at startup; on restricted containers
+ * (Apify LIMITED_PERMISSIONS, Docker rootless) the helper isn't installed
+ * or can't bind, and Chrome hangs waiting on it instead of crashing -
+ * presents to the caller as a silent CDP-connect timeout. When
+ * CHROMIUM_KEEP_SANDBOX=1, both flags drop so the user-namespace sandbox
+ * can engage normally.
+ */
+function getLinuxStealthArgs() {
+    const keepSandbox = process.env.CHROMIUM_KEEP_SANDBOX === '1'
+        || process.env.CHROMIUM_KEEP_SANDBOX === 'true';
+    return keepSandbox
+        ? LINUX_STEALTH_ARGS_BASE
+        : ['--no-sandbox', '--disable-setuid-sandbox', ...LINUX_STEALTH_ARGS_BASE];
+}
 /**
  * macOS-specific flags. `--use-mock-keychain` substitutes the real Keychain with an
  * in-memory mock to avoid blocking-permission dialogs. Not observable from page JS.
@@ -94,28 +210,63 @@ const DARWIN_STEALTH_ARGS = [
  * Build the stealth argv list. Exported for unit tests so we can assert exact flag
  * sets without booting a browser.
  *
- * The `usingAntiDetectBrowser` flag is retained as a hook for future native-stealth-only
- * divergence, but is not currently needed — every flag in this set is either covered
- * identically by Cromite's C++ patches (no conflict) or orthogonal to them.
+ * When `usingAntiDetectBrowser` is true, the renderer-backgrounding and
+ * (on macOS) native-window-occlusion features are disabled regardless of
+ * env vars, because cromite patch D26 hides the only page-JS tell those
+ * flags would otherwise expose (document.hidden / rAF throttling). This
+ * fixes the "page goes blank until I refocus the window" symptom on
+ * headful macOS launches driven by CDP.
  */
 export function buildStealthArgs(env = {}) {
     const platform = env.platform ?? process.platform;
-    const args = [...UNIVERSAL_STEALTH_ARGS];
+    const args = [...UNIVERSAL_STEALTH_ARGS, ...getOptionalStealthArgs()];
+    if (env.usingAntiDetectBrowser) {
+        for (const flag of getAntiDetectBackgroundingArgs(platform)) {
+            if (!args.includes(flag))
+                args.push(flag);
+        }
+    }
     if (platform === 'linux')
-        args.push(...LINUX_STEALTH_ARGS);
+        args.push(...getLinuxStealthArgs());
     if (platform === 'darwin')
         args.push(...DARWIN_STEALTH_ARGS);
     return args;
 }
+/**
+ * Process-layer launch options: everything in BaseLaunchBrowserOptions
+ * (the single shared declaration in launch-options.ts) plus the spawn-time
+ * fields only this layer knows about.
+ */
+/**
+ * Resolve the platform-overrides config for an anti-detect browser launch, or
+ * THROW. The anti-detect binary exists to spoof; launching it without a config
+ * silently ships the host identity (navigator.platform / userAgent / WebGL all
+ * real) - the "30% of sessions are detectable and nobody notices" failure mode.
+ *
+ * Resolution order: the per-session config (stamped by browser-plugin.ts) first,
+ * then the static browser/config/default_fingerprint.json. If both are absent
+ * (per-session missing AND the default loader fails or yields nothing), this
+ * throws so the launch aborts instead of leaking. `loadStaticDefault` is injected
+ * so the dynamic-import path can be scripted in tests.
+ */
+export async function resolveAntiDetectFingerprintConfig(perSessionConfig, loadStaticDefault) {
+    const resolved = perSessionConfig ?? await loadStaticDefault().catch(() => null);
+    if (resolved == null) {
+        throw new Error('[AntiDetect] No fingerprint config resolved for the anti-detect browser '
+            + '(per-session config absent and browser/config/default_fingerprint.json unavailable). '
+            + 'Refusing to launch unspoofed - the session would leak the host platform, user agent, and WebGL identity.');
+    }
+    return resolved;
+}
 export const launchBrowserWithNewProfile = async (executablePath, options = {}) => {
     const { anonymizedProxyUrl, debuggingPort, windowWidth = 1920, windowHeight = 1080, ignoreHttpsErrors, headless, useExperimentalFingerprints = false, maximizeWindow = true, enableStealthMode = true, populateProfile: shouldPopulateProfile = true, userDataDir: providedUserDataDir, keepUserDataDir, dnsOverHttpsServer, secureDnsMode, webrtcIpHandlingPolicy, useNativeStealth = false, } = options;
     // Detect if we're running with the anti-detect browser binary
     const usingAntiDetectBrowser = useNativeStealth && isAntiDetectBrowserSync(executablePath);
     if (useNativeStealth && !usingAntiDetectBrowser) {
-        log.debug('[AntiDetect] useNativeStealth requested but anti-detect browser not detected — using standard Chrome');
+        log.debug('[AntiDetect] useNativeStealth requested but anti-detect browser not detected - using standard Chrome');
     }
     else if (usingAntiDetectBrowser) {
-        log.debug('[AntiDetect] Anti-detect browser detected — native C++ stealth active');
+        log.debug('[AntiDetect] Anti-detect browser detected - native C++ stealth active');
     }
     // Track temp config file for cleanup
     let fingerprintConfigPath = null;
@@ -127,8 +278,12 @@ export const launchBrowserWithNewProfile = async (executablePath, options = {})
         if (providedUserDataDir) {
             await fs.mkdir(userDataDir, { recursive: true });
         }
-        await createChromeProfile(userDataDir);
-        // Populate profile with realistic user data for 2024-2025 anti-bot evasion
+        // Populate profile with realistic user data for 2024-2025 anti-bot evasion.
+        // populateChromeProfile is the sole Preferences writer here: it builds the
+        // merged Preferences object in memory and writes it once (no separate
+        // createChromeProfile write to immediately overwrite). createChromeProfile
+        // is only used when population is disabled, or as a fallback if population
+        // fails partway so the launch still has a valid base profile.
         if (shouldPopulateProfile) {
             try {
                 await populateChromeProfile(userDataDir, {
@@ -140,6 +295,22 @@ export const launchBrowserWithNewProfile = async (executablePath, options = {})
             }
             catch (popError) {
                 log.debug(`Could not populate profile: ${popError}`);
+                await createChromeProfile(userDataDir).catch(() => { });
+            }
+        }
+        else {
+            await createChromeProfile(userDataDir);
+        }
+        // Seed the Widevine CDM from the per-host cache before Chromium starts, so
+        // startup registration picks it up and `requestMediaKeySystemAccess` resolves
+        // on the first navigation, exactly as it does in a real Chrome. On Linux this
+        // is the ONLY thing that works: the CDM is bound at startup there, so a copy
+        // fetched later in the session cannot be used until the next launch (see
+        // widevine-cdm.ts). A cold cache is a no-op; ensureWidevineCdm fills it.
+        if (usingAntiDetectBrowser) {
+            const seeded = await seedWidevineCdm(userDataDir);
+            if (seeded) {
+                log.debug(`[AntiDetect] Widevine CDM ${seeded.version} seeded into the profile before launch`);
             }
         }
         const browserArgs = [
@@ -154,7 +325,7 @@ export const launchBrowserWithNewProfile = async (executablePath, options = {})
             '--no-default-browser-check',
         ];
         // Add stealth arguments for anti-bot evasion. buildStealthArgs produces a
-        // platform-scoped set aligned with nodriver — see the rationale block above
+        // platform-scoped set aligned with nodriver - see the rationale block above
         // the UNIVERSAL_STEALTH_ARGS constant for per-flag evidence.
         if (enableStealthMode) {
             browserArgs.push(...buildStealthArgs({ usingAntiDetectBrowser }));
@@ -165,6 +336,38 @@ export const launchBrowserWithNewProfile = async (executablePath, options = {})
         if (webrtcIpHandlingPolicy) {
             browserArgs.push(`--force-webrtc-ip-handling-policy=${webrtcIpHandlingPolicy}`);
         }
+        if (options.fingerprintOptions?.forceEmulateWebgl === true) {
+            // Two switch names, because two binaries are in play and each reads
+            // only its own. Verified with `strings` on the shipped artifacts:
+            //
+            //   dist/linux-x64/chrome              (151)  force-gpu-emulation   x2
+            //   dist/linux-x64.cromite-147.bak/…   (147)  force-webgl-emulation x2
+            //
+            // and neither name appears in the other binary. The 147 artifact is
+            // the one currently published to the KV store, so pushing only the
+            // 151 name means `forceEmulateWebgl: true` is silently dropped for
+            // every consumer on the released browser - exactly the way stock
+            // Chrome drops an unknown switch. Pushing only the 147 name has the
+            // mirror-image problem once #148 flips.
+            //
+            // Same dual-pass shape as --blink-settings-file /
+            // --blink-platform-overrides-file above. Delete the 147 line at the
+            // #148 flip, not before.
+            //
+            // The canonical declaration is switches::kForceGpuEmulation in
+            // chrome/common/chrome_switches.{h,cc}, propagated to
+            // renderer/GPU children via the kCommonSwitchNames list in
+            // chrome/browser/chrome_content_browser_client.cc. The renderer
+            // WebGL factory hook in third_party/blink/renderer/modules/webgl/
+            // webgl_rendering_context_base.cc reads the switch and, when
+            // FingerprintConfig::IsLoaded() also holds, returns the in-process
+            // EmulatedWebGraphicsContext3DProvider directly (skipping the GPU
+            // command-buffer round-trip entirely). On stock Chrome the switch
+            // is unknown and silently dropped.
+            browserArgs.push('--force-gpu-emulation');
+            browserArgs.push('--force-webgl-emulation');
+            log.debug('[AntiDetect] forceEmulateWebgl=true → pushed --force-gpu-emulation + --force-webgl-emulation');
+        }
         // Set window size - either specific dimensions or maximize
         // Don't maximize if specific dimensions are provided to avoid conflicts
         if (windowWidth && windowHeight) {
@@ -184,41 +387,87 @@ export const launchBrowserWithNewProfile = async (executablePath, options = {})
             browserArgs.push(`--disable-extensions-except=${extList}`, // optional, keeps Chrome from loading the rest
             `--load-extension=${extList}`);
         }
-        // Anti-detect browser: write --fingerprint-config JSON and pass it to the browser.
-        // The C++ FingerprintConfig singleton reads this file at startup (lazy, first access).
+        // Anti-detect browser: write platform-overrides JSON and pass its path to the
+        // browser via the config switch (see the two-name note below - the shipped
+        // 147 binary calls it --blink-platform-overrides-file, the vanilla-151 one
+        // --blink-settings-file). The C++ singleton reads this file at startup
+        // (lazy, first access); the browser process re-emits the content inline as
+        // the matching -data switch so sandboxed children (renderer/GPU/utility)
+        // can parse it without file IO.
         if (usingAntiDetectBrowser) {
             try {
                 // Prefer a pre-generated per-session config (passed by browser-plugin.ts) so that
                 // each browser instance gets unique C++-level hardware fingerprints (GPU, screen,
                 // CPU). Fall back to the static default_fingerprint.json if none was provided.
-                const configToWrite = options.fingerprintConfig ?? await (async () => {
+                // Throws if neither source yields a config - see resolveAntiDetectFingerprintConfig.
+                const configToWrite = await resolveAntiDetectFingerprintConfig(options.fingerprintConfig, async () => {
                     const { default: def } = await import(
-                    /* @vite-ignore */ new URL('../../browser/config/default_fingerprint.json', import.meta.url).href).catch(() => ({ default: null }));
+                    /* @vite-ignore */ new URL('../../browser/config/default_fingerprint.json', import.meta.url).href);
                     return def;
-                })();
-                if (configToWrite) {
+                });
+                {
                     fingerprintConfigPath = await writeTempFingerprintConfig(configToWrite);
-                    browserArgs.push(`--fingerprint-config=${fingerprintConfigPath}`);
-                    // --fingerprint-accept-language is our custom C++ hook in
-                    // net/url_request/url_request_http_job.cc. Only the anti-detect binary
-                    // understands this flag. The hook splits on commas and feeds each entry
-                    // verbatim into `navigator.languages`, so we MUST strip q-values here;
-                    // otherwise the JS array leaks `"ko;q=0.9"`-style entries and becomes a
-                    // detectable anomaly (real Chrome's navigator.languages never carries
-                    // q-values — those are HTTP Accept-Language semantics only).
-                    const fpLangs = configToWrite.navigator?.languages;
-                    if (fpLangs) {
-                        const cleanLangs = fpLangs.split(',')
-                            .map((l) => l.split(';')[0].trim())
-                            .filter(Boolean)
-                            .join(',');
-                        browserArgs.push(`--fingerprint-accept-language=${cleanLangs}`);
+                    // Opaque switch name (renamed from --fingerprint-config). Mimics
+                    // existing Blink runtime-flag shape so /proc/<pid>/cmdline does
+                    // not advertise an anti-detect-specific flag.
+                    // #145 lockstep: the vanilla-151 binary renamed this switch to
+                    // --blink-settings-file (switches::kBlinkSettingsFile). It knows
+                    // no other name, and because it hard-fails when neither
+                    // --blink-settings-file nor --blink-settings-data is present
+                    // (#78), sending only the old name does not degrade gracefully -
+                    // the browser SIGTRAPs before the CDP endpoint is ready and the
+                    // crawler cannot launch it at all. The SHIPPED Cromite/147
+                    // artifact has the mirror-image problem: it only knows the old
+                    // name and hard-fails the same way if it is not passed.
+                    //
+                    // TEMPORARY COMPATIBILITY SHIM, not design. Both names are
+                    // pushed, pointing at the SAME file, so one crawler build drives
+                    // both binaries. Each binary reads the name it knows and ignores
+                    // the other: base::CommandLine::AppendSwitchesAndArguments
+                    // (base/command_line.cc) stores every `--k=v` token in a plain
+                    // map with no allowlist, so an unrecognised switch is inert -
+                    // nothing in the tree validates the switch set, and the only
+                    // switch-name-driven warning path (kBadFlags in
+                    // chrome/browser/ui/startup/bad_flags_prompt.cc) is a fixed list
+                    // that contains neither name. Verified against the artifacts
+                    // themselves: `strings` on the 147 build exports only
+                    // "blink-platform-overrides-file", on the 151 build only
+                    // "blink-settings-file".
+                    //
+                    // DELETE the legacy line below - and this comment - once the
+                    // shipped artifact is the vanilla line, i.e. after the browser
+                    // submodule pointer is flipped to the 151 build (#148). At that
+                    // point no binary we ship or download reads the old name, and
+                    // keeping it only adds a needless token to /proc/<pid>/cmdline.
+                    browserArgs.push(`--blink-settings-file=${fingerprintConfigPath}`);
+                    // LEGACY (Cromite/147 only) - remove with #148.
+                    browserArgs.push(`--blink-platform-overrides-file=${fingerprintConfigPath}`);
+                    // Anti-Detect 2026-05-18: also pass the spoofed User-Agent via
+                    // Chromium's standard `--user-agent` switch so the HTTP wire
+                    // layer sees the same UA as JS-visible `navigator.userAgent`.
+                    // The previous mechanism - reading FingerprintConfig directly
+                    // from `net/url_request/url_request_http_job.cc` - was a
+                    // net/→blink/ layering violation that broke component builds
+                    // (FAST_BUILD=1). `--user-agent` is honored by
+                    // embedder_support::GetUserAgent() which HttpUserAgentSettings
+                    // caches per-NetworkContext, so every outgoing HTTP request
+                    // carries the spoofed UA without any cross-layer dep.
+                    // Accept-Language is already covered by the `--lang=` switch
+                    // pushed below (line ~520) plus the `setenv("LANG"/"LC_ALL")`
+                    // pin in chrome_main_delegate.cc::BasicStartupComplete.
+                    const spoofedUA = configToWrite?.navigator?.userAgent;
+                    if (spoofedUA) {
+                        browserArgs.push(`--user-agent=${spoofedUA}`);
                     }
-                    log.debug(`[AntiDetect] Wrote fingerprint config: ${fingerprintConfigPath}${options.fingerprintConfig ? ' (per-session)' : ' (static default)'}`);
+                    log.debug(`[Blink] Wrote platform-overrides config: ${fingerprintConfigPath}${options.fingerprintConfig ? ' (per-session)' : ' (static default)'}`);
                 }
             }
             catch (configErr) {
-                log.debug(`[AntiDetect] Could not write fingerprint config: ${configErr}`);
+                // Never swallow a config failure for the anti-detect binary: a
+                // browser launched without the platform-overrides config runs
+                // unspoofed and silently leaks the host identity. Surface it so
+                // the launch aborts rather than shipping a detectable session.
+                throw new Error(`[AntiDetect] Failed to prepare the fingerprint config for the anti-detect browser - refusing to launch unspoofed: ${configErr instanceof Error ? configErr.message : String(configErr)}`);
             }
         }
         // --lang is understood by every Chrome binary (stock + anti-detect) and configures
@@ -235,14 +484,24 @@ export const launchBrowserWithNewProfile = async (executablePath, options = {})
             browserArgs.push(`--lang=${langArg || options.resolvedLocale.locale}`);
         }
         else {
-            // No locale resolved — preserve historical default so we don't change behavior
+            // No locale resolved - preserve historical default so we don't change behavior
             // for callers that never touched fingerprintOptions.
             browserArgs.push('--lang=en-US,en');
         }
         if (anonymizedProxyUrl) {
             browserArgs.push(`--proxy-server=${anonymizedProxyUrl}`);
         }
-        if (ignoreHttpsErrors) {
+        // Anti-Detect 2026-05-18: `--ignore-certificate-errors` is JS-detectable.
+        // A page can issue a `fetch()` to a sub-resource hosted under a
+        // self-signed certificate; real Chrome blocks the load (cert error),
+        // we silently succeed. That single asymmetry is enough to flag us.
+        //
+        // When running the native anti-detect binary we therefore force real
+        // certificate validation, regardless of the caller's `ignoreHttpsErrors`
+        // setting - the stealth invariant (mimic real Chrome wire behaviour)
+        // overrides the convenience flag. Stock-Chromium / non-stealth callers
+        // keep the historical default.
+        if (ignoreHttpsErrors && !usingAntiDetectBrowser) {
             browserArgs.push('--ignore-certificate-errors');
             // disabled because of cloudflare blocking
             // browserArgs.push('--disable-web-security');
@@ -251,31 +510,117 @@ export const launchBrowserWithNewProfile = async (executablePath, options = {})
             browserArgs.push('--headless=new');
         }
         log.debug(`Launching browser with user data dir: ${userDataDir}`);
-        const chromeVersion = getChromeBinaryVersion(executablePath);
-        if (chromeVersion) {
-            log.debug(`Using Chrome binary version: ${chromeVersion}`);
-        }
         log.debug('browserArgs', browserArgs);
         log.debug(`Stealth mode: ${enableStealthMode}, Profile populated: ${shouldPopulateProfile}, cleanup profile: ${shouldCleanupUserDataDir}`);
-        // Chrome bundles its own ICU so LANG/LC_ALL don't drive Intl — but a handful of
+        // Chrome bundles its own ICU so LANG/LC_ALL don't drive Intl - but a handful of
         // system APIs (file dialogs, native notifications, extension readers) consult them.
         // Setting these matches what a real user's shell would do and costs nothing.
+        //
+        // We also override TZ and LANGUAGE: a hardcoded host TZ (e.g. Europe/Berlin from
+        // an Apify Dockerfile) would otherwise leak through to anything that reads
+        // /etc/localtime or honors $TZ for fallback paths. Chrome's main Intl/Date path
+        // is covered by Emulation.setTimezoneOverride (called from fingerprint-injector)
+        // but workers and out-of-process subsystems can still consult $TZ.
         const spawnEnv = { ...process.env };
         if (options.resolvedLocale?.posix) {
             spawnEnv.LANG = options.resolvedLocale.posix;
             spawnEnv.LC_ALL = options.resolvedLocale.posix;
         }
+        if (options.resolvedLocale?.languages) {
+            // GTK/glib and some apps read $LANGUAGE for fallback chains; align with the
+            // primary language (strip q-values).
+            const primaryLang = options.resolvedLocale.languages
+                .split(',')[0]
+                ?.split(';')[0]
+                ?.trim();
+            if (primaryLang)
+                spawnEnv.LANGUAGE = primaryLang;
+        }
+        if (options.resolvedLocale?.timezone) {
+            spawnEnv.TZ = options.resolvedLocale.timezone;
+        }
+        // Pipe stderr instead of swallowing it so a Chromium crash on Linux
+        // (missing shared lib, sandbox failure, GLIBC mismatch, …) surfaces
+        // in the logs instead of presenting as a generic "Failed to connect to
+        // browser on port: 9200" 30s timeout. Last ~50 lines are buffered and
+        // dumped at WARN level if the process exits before the CDP listener
+        // comes up.
         const browserProcess = spawn(executablePath, browserArgs, {
-            stdio: 'ignore',
+            stdio: ['ignore', 'ignore', 'pipe'],
             env: spawnEnv,
+            // Put the browser in its own process group (pgid === pid) so the
+            // whole Chromium process tree - parent + renderer/GPU/utility
+            // helpers - can be reaped at once via `process.kill(-pid, sig)`.
+            // Without this, signals hit only the parent and helpers orphan to
+            // launchd/init, leaking RAM and exhausting macOS IOSurface clients.
+            // Ctrl+C is still handled explicitly by signal-cleanup.ts, so losing
+            // the TTY's automatic SIGINT forwarding to the group is fine.
+            detached: true,
         });
         const proc = new BrowserProcess(browserProcess, userDataDir, shouldCleanupUserDataDir);
-        // Clean up temp fingerprint config file when the browser process exits
+        const stderrBuffer = [];
+        const STDERR_BUFFER_LIMIT = 50;
+        let stderrLeftover = '';
+        // Chromium writes a large volume of benign stderr on headless container
+        // launches (GPU-less init, ALSA "no sound card", dbus, WebRTC P2P
+        // resolve failures, the DevTools banner, zygote teardown races, …).
+        // None of it is actionable at runtime, so EVERY stderr line is logged at
+        // DEBUG only - it surfaces solely when the Apify log level is DEBUG.
+        // Real failures are not lost: the `exit` handler below dumps the buffered
+        // stderr tail at WARNING whenever Chromium exits with a non-zero code,
+        // which is the signature of an actual crash.
+        browserProcess.stderr?.on('data', (chunk) => {
+            stderrLeftover += chunk.toString('utf8');
+            const lines = stderrLeftover.split('\n');
+            stderrLeftover = lines.pop() ?? '';
+            for (const line of lines) {
+                if (!line)
+                    continue;
+                stderrBuffer.push(line);
+                if (stderrBuffer.length > STDERR_BUFFER_LIMIT)
+                    stderrBuffer.shift();
+                log.debug(`[Chromium stderr] ${line}`);
+                // Puppeteer-style readiness: Chromium prints the browser-level CDP
+                // WebSocket endpoint here once its remote-debugging server is
+                // accepting connections. Parsing it is the exact moment the browser
+                // is connectable - no TCP-port poll or fixed pre-connect delay
+                // needed.
+                const wsMatch = line.match(/DevTools listening on (ws:\S+)/);
+                if (wsMatch) {
+                    proc.resolveWsEndpoint(wsMatch[1]);
+                }
+            }
+        });
+        // Surface the buffered stderr if Chrome exits before something else
+        // gets a chance to inspect it (typical crash-on-startup signature), and
+        // fail the readiness promise fast with that same tail so a dead binary
+        // never presents as a generic connect timeout.
+        browserProcess.once('exit', (code, signal) => {
+            if (stderrLeftover) {
+                stderrBuffer.push(stderrLeftover);
+                stderrLeftover = '';
+            }
+            const tail = stderrBuffer.slice(-20).join('\n');
+            if (code !== 0 && code !== null) {
+                log.warning(`Chromium exited with code=${code} signal=${signal}. `
+                    + `Last stderr lines:\n${tail || '(empty - Chrome wrote nothing to stderr)'}`);
+            }
+            // No-op once the ws line was already seen (settled-once guard).
+            proc.rejectWsEndpoint(new Error(`Chromium exited (code=${code} signal=${signal}) before the CDP WebSocket endpoint was ready. `
+                + `Last stderr lines:\n${tail || '(empty - Chrome wrote nothing to stderr)'}`));
+        });
+        // A spawn-level failure (missing binary, EACCES, …) fires `error` and may
+        // never fire `exit`, so reject readiness here too. Also settled-once.
+        browserProcess.once('error', (err) => {
+            const tail = stderrBuffer.slice(-20).join('\n');
+            proc.rejectWsEndpoint(new Error(`Browser process failed to start before the CDP WebSocket endpoint was ready: ${err.message}${tail ? `\nLast stderr lines:\n${tail}` : ''}`));
+        });
+        // Track the temp fingerprint config file on the BrowserProcess so it is
+        // removed both on normal exit (via cleanup()) and on a SIGINT/SIGTERM
+        // signal (via the signal-cleanup registry), not just the exit event -
+        // which never fires when the process is interrupted before teardown.
         if (fingerprintConfigPath) {
-            const configPath = fingerprintConfigPath;
-            browserProcess.once('exit', () => {
-                fs.unlink(configPath).catch(() => { });
-            });
+            proc.trackFingerprintConfigPath(fingerprintConfigPath);
         }
         return proc;
     }
@@ -284,7 +629,18 @@ export const launchBrowserWithNewProfile = async (executablePath, options = {})
         throw new Error(`Error launching the browser: ${error}`);
     }
 };
-export const createTempUserDataDir = async () => {
+// Cache the resolved writable base directory for the process lifetime. The
+// mkdir + write-test probe below only depends on the filesystem layout and the
+// process's cwd/home, none of which change underneath us mid-process, so the
+// probe is run once and its result reused. Only a SUCCESSFUL probe is cached -
+// a transient failure (e.g. a full disk during the first launch) must be
+// retried on the next launch rather than pinned for the whole process. Each
+// launch still gets its own fresh user-data-dir via fs.mkdtemp under the base.
+let cachedBaseTempDir = null;
+const resolveWritableBaseTempDir = async () => {
+    if (cachedBaseTempDir) {
+        return cachedBaseTempDir;
+    }
     // Try to create temp directory in order of preference:
     // 1. Project's temp directory (if we're in a project)
     // 2. User's home directory temp folder
@@ -297,7 +653,6 @@ export const createTempUserDataDir = async () => {
         // System temp directory (fallback)
         path.join(os.tmpdir(), 'cdp-crawler-browsers'),
     ];
-    let baseTempDir = null;
     for (const candidate of tempDirCandidates) {
         try {
             await fs.mkdir(candidate, { recursive: true });
@@ -305,17 +660,18 @@ export const createTempUserDataDir = async () => {
             const testFile = path.join(candidate, '.write-test');
             await fs.writeFile(testFile, 'test');
             await fs.unlink(testFile);
-            baseTempDir = candidate;
-            break;
+            cachedBaseTempDir = candidate;
+            return candidate;
         }
         catch (error) {
             log.debug(`Cannot use temp directory ${candidate}: ${error}`);
             continue;
         }
     }
-    if (!baseTempDir) {
-        throw new Error('Could not find a writable directory for browser profiles');
-    }
+    throw new Error('Could not find a writable directory for browser profiles');
+};
+export const createTempUserDataDir = async () => {
+    const baseTempDir = await resolveWritableBaseTempDir();
     const tempDirPrefix = path.join(baseTempDir, 'browser_');
     const userDataDir = await fs.mkdtemp(tempDirPrefix);
     log.debug(`Created browser profile directory: ${userDataDir}`);
@@ -326,7 +682,7 @@ export const launchChromeBrowserWithNewProfile = async (options = {}) => {
     // CDPBrowserPlugin._launch() (resolveAntiDetectBrowserPath throws there if the
     // binary is missing). Direct callers of this function without native stealth
     // still fall through to the system Chrome lookup.
-    let executablePath = options.executablePath;
+    let { executablePath } = options;
     if (!executablePath) {
         const wantsNativeStealth = options.useNativeStealth || options.fingerprintOptions?.useNativeStealth;
         if (wantsNativeStealth) {