doc-detective 4.28.0 → 4.29.0

package/dist/core/tests.js

@@ -13,7 +13,7 @@ import { requiredBrowserAssets, ensureBrowserInstalled, } from "../runtime/brows
 // Single source of truth for browser/driver-requiring step keys.
 import { BROWSER_STEP_KEYS as driverActions, startSurfaceDescriptors, stepOpensBrowserSurface, } from "../runtime/browserStepKeys.js";
 import os from "node:os";
-import { log, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, isRetryableSessionError, } from "./utils.js";
+import { log, logLevelEnabled, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, isRetryableSessionError, } from "./utils.js";
 import axios from "axios";
 import { instantiateCursor } from "./tests/moveTo.js";
 import { goTo } from "./tests/goTo.js";
@@ -34,10 +34,12 @@ import { httpRequest } from "./tests/httpRequest.js";
 import { clickElement } from "./tests/click.js";
 import { runCode } from "./tests/runCode.js";
 import { closeSurface } from "./tests/closeSurface.js";
-import { createAppSessionState, appSurfacePreflight, isAppDriverRequired, stepTargetsAppSurface, teardownAppSession, } from "./tests/appSurface.js";
+import { createAppSessionState, appSurfacePreflight, isAppDriverRequired, stepTargetsAppSurface, teardownAppSession, APP_DRIVER_PLATFORMS, probeIosToolchain, } from "./tests/appSurface.js";
 import { startSurfaceStep } from "./tests/startSurface.js";
 import { isMobileTargetPlatform } from "./tests/mobilePlatform.js";
-import { mobileBrowserGate, buildMobileBrowserCapabilities, } from "./tests/mobileBrowser.js";
+import { mobileBrowserGate, buildMobileBrowserCapabilities, CHROMEDRIVER_AUTODOWNLOAD_ARGS, } from "./tests/mobileBrowser.js";
+import { planWarmTasks, executeWarmTasks, raceBootInitiation, wrapInitiationEffects, RUNTIME_INSTALL_RESOURCE, } from "./warmPhase.js";
+import { locateManagedWda } from "../runtime/wdaProducts.js";
 import { getCacheDir } from "../runtime/cacheDir.js";
 import { detectAndroidSdk } from "../runtime/androidSdk.js";
 import { hostAbi, listInstalledSystemImages, installAndroid, } from "../runtime/androidInstaller.js";
@@ -59,9 +61,7 @@ import http from "node:http";
 import https from "node:https";
 import { fileURLToPath } from "node:url";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export { runSpecs, runViaApi, getRunner, ensureChromeAvailable, ensureContextBrowserInstalled, combinationKey, warmUpDecision, selectWarmUpTargets, getDriverCapabilities, withChromedriverPort, getDefaultBrowser, buildFallbackCandidates, driverSkipDiagnostic, resolveBrowserFallbackPolicy, shouldRepairBeforeFallback, isSupportedContext, contextRequirementsSkipMessage, resolveAutoScreenshot, resolveAutoRecord, buildAutoRecordStep, specIsRouted, killTree, jobDisplayResources, };
-// exports.appiumStart = appiumStart;
-// exports.appiumIsReady = appiumIsReady;
+export { runSpecs, runViaApi, getRunner, ensureChromeAvailable, ensureContextBrowserInstalled, combinationKey, warmUpDecision, selectWarmUpTargets, getDriverCapabilities, withChromedriverPort, getDefaultBrowser, buildFallbackCandidates, driverSkipDiagnostic, resolveBrowserFallbackPolicy, shouldRepairBeforeFallback, isSupportedContext, contextRequirementsSkipMessage, resolveAutoScreenshot, resolveAutoRecord, buildAutoRecordStep, specIsRouted, killTree, jobDisplayResources, buildWarmPlanDeps, warmBrowserInstall, prefetchMobileChromedriver, appiumIsReady, };
 // exports.driverStart = driverStart;
 // Browser names getDriverCapabilities knows how to build caps for. `safari` is
 // rewritten to `webkit` during context resolution, so both appear here.
@@ -157,6 +157,28 @@ function combinationKey(context) {
 function warmUpDecision(prev) {
     return prev === "failed" ? "skip" : "attempt";
 }
+/**
+ * Bind the real selection predicates for the warm-phase planner
+ * (planWarmTasks in warmPhase.ts). The planner takes these as an injected
+ * bag because most of them live in this module — importing them from
+ * warmPhase.ts would create a tests.ts ⇄ warmPhase.ts cycle — and because
+ * the bag keeps the planner hermetically unit-testable. Exported so planner
+ * tests exercise production selection logic, not stand-ins.
+ */
+function buildWarmPlanDeps() {
+    return {
+        isBrowserRequired,
+        isAppDriverRequired,
+        isMobileTargetPlatform,
+        getDefaultBrowser,
+        requiredBrowserAssets,
+        collectDeviceDescriptors,
+        normalizeDeviceDescriptor,
+        mobileBrowserGate,
+        contextRequirementsSkipMessage,
+        appDriverPlatforms: APP_DRIVER_PLATFORMS,
+    };
+}
 // Get Appium driver capabilities and apply options.
 function getDriverCapabilities({ runnerDetails, name, options }) {
     let capabilities = {};
@@ -1129,6 +1151,11 @@ async function runSpecs({ resolvedTests }) {
             },
         },
         specs: [],
+        // Inline warm phase results (docs/design/warm-phase.md). Present on the
+        // skeleton so a run that plans nothing (or whose planning fails —
+        // best-effort) still reports the structural empty block; the phase
+        // overwrites it with real task results below.
+        warm: { durationMs: 0, tasks: [] },
     };
     // Resolve concurrency up front (defensive re-resolve: API callers can hand
     // runSpecs a config that never went through core setConfig, leaving
@@ -1392,6 +1419,11 @@ async function runSpecs({ resolvedTests }) {
         // that removes the port race and fails fast on the first server that can't
         // come up, tearing down any already started so they don't leak.
         try {
+            // Spawn servers one at a time (serial spawn keeps the findFreePort race
+            // protection + avoids a CPU spike), but collect their readiness polls and
+            // await them together so the waits OVERLAP — total ≈ max(readiness)
+            // instead of the sum of serial waits.
+            const readinessWaits = [];
             for (let i = 0; i < serverCount; i++) {
                 let display;
                 if (useXvfbDisplays) {
@@ -1399,7 +1431,20 @@ async function runSpecs({ resolvedTests }) {
                     xvfbProcesses.push(await startXvfb(display));
                     log(config, "debug", `Started Xvfb on ${display} for recording.`);
                 }
-                appiumServers.push(await startAppiumServer(appiumEntry, config, display));
+                const server = await spawnAppiumServer(appiumEntry, config, display);
+                appiumServers.push(server);
+                const wait = appiumIsReady(server.port);
+                // Attach a no-op catch so that once Promise.all rejects on the FIRST
+                // failing server, the other still-pending readiness rejections don't
+                // surface as unhandled promise rejections. Promise.all still sees the
+                // original `wait`, so it fails fast on the first error; the catch
+                // block below tears down every spawned server (ready or not).
+                wait.catch(() => { });
+                readinessWaits.push(wait);
+            }
+            await Promise.all(readinessWaits);
+            for (const server of appiumServers) {
+                log(config, "debug", `Appium is ready on port ${server.port}.`);
             }
         }
         catch (error) {
@@ -1439,6 +1484,15 @@ async function runSpecs({ resolvedTests }) {
     // Swept in the `finally` below — only simulators Doc Detective booted are
     // shut down (launch-ownership).
     const simulatorRegistry = createSimulatorRegistry();
+    // One resource registry per run, shared by the warm phase, every phase's
+    // flat pool, AND the routed sequencer — so warm's cache-mutating tasks,
+    // flat-pool recordings, and routed-spec recordings all contend on the same
+    // named mutexes. Warm is awaited before Phase 2 dispatch and
+    // runResourceAware releases every tag in a `finally`, so the pools always
+    // start with an empty registry. Only consulted where items carry tags
+    // (warm tasks always do; jobs only at limit>1 — at limit===1 the pools
+    // stay on the byte-identical runConcurrent path).
+    const resourceRegistry = createResourceRegistry();
     // Kill every still-registered background process (and its child tree) and
     // remove any deferred temp scripts. Awaits the kills so the process tree is
     // actually gone before the run returns. Idempotent: closeSurface already
@@ -1495,25 +1549,56 @@ async function runSpecs({ resolvedTests }) {
     // warmUpContexts (e.g. getAvailableApps failing during the re-detect) would
     // leak the started servers, leaving orphaned processes bound to their ports.
     try {
-        // For concurrent runs, resolve missing browser dependencies and warm up
-        // each unique driver combination serially *before* the pool. Two contexts
-        // can't then race on an on-demand install (which mutates the shared app
-        // cache), and a combination that can't start a driver is recorded once here
-        // so every parallel context sharing it skips instantly instead of re-paying
-        // driverStart's backoff. This pre-populates installAttempts /
-        // warmUpResults / runnerDetails.availableApps, so runContext's own gates
-        // below collapse to fast cache hits. Sequential runs (limit 1) keep #338's
-        // natural first-context-warms-up behavior in runContext — no pre-pass, no
-        // extra driver start, byte-identical to before.
-        if (limit > 1 && appiumPool) {
-            await warmUpContexts({
-                jobs: sizingJobs,
-                config,
+        // Inline warm phase (docs/design/warm-phase.md): always-on, best-effort
+        // provisioning between resolution and execution. The planner derives
+        // every task the run's contexts would JIT-provision anyway (browser and
+        // app-driver installs, device boots, the WDA availability check, the
+        // mobile chromedriver prefetch, the folded-in session probe) and the
+        // executor overlaps them under the run's resource registry — so boot ∥
+        // npm install ∥ browser download overlap each other even for a serial
+        // test run. A failed task is a warning; the per-context paths retry or
+        // skip with exactly the semantics they have today. The historical
+        // `limit > 1 && appiumPool` gate now guards only the session-probe TASK
+        // (inside planWarmTasks), preserving #338's natural
+        // first-context-warms-up behavior for serial runs, whose memo state is
+        // byte-identical by the warmBrowserInstall mirror contract. Device
+        // boots resolve at initiation; only the chromedriver prefetch awaits
+        // readiness (and only runs with android mobile-web contexts pay it —
+        // they'd pay the same boot + session at their first mobile context).
+        // The never-gates contract covers the whole phase, planning included: a
+        // throw from the planner or its bound predicates must degrade to a
+        // warning + the skeleton's empty warm block, never abort the run
+        // (executeWarmTasks already isolates per-task failures internally).
+        try {
+            const warmTasks = planWarmTasks({
+                sizingJobs,
                 runnerDetails,
-                appiumPool,
-                installAttempts,
-                warmUpResults,
+                limit,
+                hasAppiumPool: !!appiumPool,
+                deps: buildWarmPlanDeps(),
             });
+            if (warmTasks.length > 0) {
+                log(config, "debug", `Warm phase: ${warmTasks.length} task(s).`);
+                report.warm = await executeWarmTasks({
+                    tasks: warmTasks,
+                    registry: resourceRegistry,
+                    runTask: buildWarmTaskRunner({
+                        config,
+                        runnerDetails,
+                        sizingJobs,
+                        appiumPool,
+                        installAttempts,
+                        warmUpResults,
+                        deviceRegistry,
+                        simulatorRegistry,
+                        resourceRegistry,
+                    }),
+                    log: (level, message) => log(config, level, message),
+                });
+            }
+        }
+        catch (error) {
+            log(config, "warning", `Warm phase skipped (planning failed; the run proceeds with on-demand provisioning): ${error?.message ?? error}`);
         }
         // Phase 2: run context jobs through the worker pool, gated into three
         // sequential phases. Config-level `beforeAny` specs all finish before any
@@ -1598,12 +1683,6 @@ async function runSpecs({ resolvedTests }) {
                 : "main";
             routedByPhase[phase].push(entry);
         }
-        // One resource registry per run, shared by every phase's flat pool AND the
-        // routed sequencer, so a flat-pool recording and a routed-spec recording
-        // never hold the shared "display" at the same time. Only consulted at
-        // limit>1 (where jobs were tagged); at limit===1 the pools stay on the
-        // byte-identical runConcurrent path.
-        const resourceRegistry = createResourceRegistry();
         for (const phase of PHASES) {
             if (limit > 1) {
                 await runResourceAware(jobsByPhase[phase], limit, resourceRegistry, runJob);
@@ -2103,27 +2182,20 @@ async function warmUpContexts({ jobs, config, runnerDetails, appiumPool, install
             context.platform === platform &&
             Array.isArray(context?.steps) &&
             requiredBrowserAssets(context.browser?.name).length > 0) {
-            const firstAttempt = !installAttempts.has((context.browser?.name ?? "<none>").toLowerCase());
-            const outcome = await ensureContextBrowserInstalled({
+            // Extracted install + first-attempt re-detect (shared with the warm
+            // phase's browser-install task) — the memo state it leaves is exactly
+            // what this loop produced inline before.
+            await warmBrowserInstall({
                 browserName: context.browser?.name,
                 config,
+                runnerDetails,
                 installAttempts,
-                deps: {
-                    ensureBrowser: (asset, options) => ensureBrowserInstalled(asset, options),
-                    log,
-                },
-                // Repair a present-but-broken driver, not just install-if-missing.
-                repair: true,
             });
-            if (firstAttempt && (outcome === "installed" || outcome === "failed")) {
-                clearAppCache(config);
-                runnerDetails.availableApps = await getAvailableApps({ config });
-                supported = isSupportedContext({
-                    context,
-                    apps: runnerDetails.availableApps,
-                    platform,
-                });
-            }
+            supported = isSupportedContext({
+                context,
+                apps: runnerDetails.availableApps,
+                platform,
+            });
         }
         // Unsupported combinations are left unmarked; runContext skips each with the
         // appropriate per-context reason (install-but-undetected vs unsupported).
@@ -2177,6 +2249,404 @@ async function warmUpContexts({ jobs, config, runnerDetails, appiumPool, install
         }
     }
 }
+/**
+ * On-demand browser install + first-attempt re-detect — the install half of
+ * warmUpContexts, extracted so the warm phase's browser-install task and the
+ * session-probe loop share ONE implementation of the mirror contract: the
+ * `installAttempts` / `runnerDetails.availableApps` state left behind is
+ * exactly what the first same-browser consuming context would have produced
+ * serially (no more, no less), so every later gate collapses to a cache hit.
+ * Deps are injected for hermetic tests; production callers use the defaults.
+ */
+async function warmBrowserInstall({ browserName, config, runnerDetails, installAttempts, deps = {}, }) {
+    // Already-detected engines need no install — and, mirroring the serial
+    // path (which only reaches the install when the support gate failed),
+    // no memo entry either.
+    const appName = normalizeBrowserName(browserName);
+    if (runnerDetails.availableApps?.find((app) => app.name === appName)) {
+        return {
+            outcome: "skipped",
+            note: `'${browserName}' is already available`,
+        };
+    }
+    const firstAttempt = !installAttempts.has((browserName ?? "<none>").toLowerCase());
+    const outcome = await ensureContextBrowserInstalled({
+        browserName,
+        config,
+        installAttempts,
+        deps: {
+            ensureBrowser: deps.ensureBrowser ??
+                ((asset, options) => ensureBrowserInstalled(asset, options)),
+            log,
+        },
+        // Repair a present-but-broken driver, not just install-if-missing.
+        repair: true,
+    });
+    // Re-detect only after a FIRST install attempt (installed or failed):
+    // the app cache is stale either way, and later gates must read the
+    // refreshed list or they'd misread the memo as installed-but-undetected.
+    if (firstAttempt && (outcome === "installed" || outcome === "failed")) {
+        (deps.clearAppCache ?? clearAppCache)(config);
+        runnerDetails.availableApps = await (deps.getAvailableApps ??
+            getAvailableApps)({ config });
+    }
+    if (outcome === "installed")
+        return { outcome: "warmed" };
+    if (outcome === "failed") {
+        return { outcome: "failed", note: `couldn't install '${browserName}'` };
+    }
+    return {
+        outcome: "skipped",
+        note: `'${browserName}' has no installable assets`,
+    };
+}
+/**
+ * Light per-run Android environment probe for warm tasks: SDK + emulator
+ * binary + acceleration (or a running emulator). Null means "not ready" —
+ * the warm task reports skipped and the consuming context performs the full
+ * androidContextPreflight (including the loud lazy toolchain install, which
+ * warm deliberately never triggers — that decision and its warning belong on
+ * the context report).
+ */
+/* c8 ignore start — real SDK/emulator probes; exercised on the CI emulator
+   legs and dev boxes. Unit coverage targets the pure planner/executor. */
+async function resolveAndroidWarmEnv(config) {
+    try {
+        const abi = hostAbi();
+        const sdk = detectAndroidSdk({ cacheDir: config?.cacheDir });
+        if (!sdk?.emulator)
+            return null;
+        const deviceDeps = buildAcquireDeviceDeps(sdk, abi, (m) => log(config, "debug", m));
+        const running = await deviceDeps.listRunning();
+        const capable = running.length > 0 || (await checkEmulatorAcceleration(sdk.emulator));
+        if (!capable)
+            return null;
+        return { sdkRoot: sdk.sdkRoot, deviceDeps };
+    }
+    catch {
+        return null;
+    }
+}
+/* c8 ignore stop */
+/**
+ * Async twin of probeIosToolchain for the warm executor: the sync probe's
+ * spawnSync (up to 120s on a cold CoreSimulator service) would block the
+ * event loop and stall every "concurrent" warm task. Pre-run both probe
+ * commands with async spawns (in parallel), then hand the collected results
+ * to the real probe via its injected runner — the decision logic and every
+ * skip message stay in ONE place.
+ */
+/* c8 ignore start — real xcode-select/xcrun spawns; the decision logic is
+   probeIosToolchain's and is unit-tested there. */
+async function probeIosToolchainWarm() {
+    if (process.platform !== "darwin")
+        return probeIosToolchain();
+    const runAsync = (command, args, timeout) => new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        try {
+            const child = spawn(command, args, { windowsHide: true, timeout });
+            child.stdout?.on("data", (d) => (stdout += String(d)));
+            child.stderr?.on("data", (d) => (stderr += String(d)));
+            child.on("error", () => resolve({ status: null, stdout, stderr }));
+            child.on("close", (status) => resolve({ status, stdout, stderr }));
+        }
+        catch {
+            resolve({ status: null, stdout, stderr });
+        }
+    });
+    const [xcodeSelect, simctl] = await Promise.all([
+        runAsync("xcode-select", ["-p"], 15000),
+        // Same generous ceiling as the sync probe's xcrun spawn: the first cold
+        // simctl call launches CoreSimulatorService.
+        runAsync("xcrun", ["simctl", "list", "devices", "available"], 120000),
+    ]);
+    return probeIosToolchain({
+        run: (command) => (command === "xcrun" ? simctl : xcodeSelect),
+    });
+}
+/* c8 ignore stop */
+/**
+ * Bind the effectful per-kind warm task bodies to the run's state. Every
+ * body upholds the warm contract: best-effort (a throw is caught by the
+ * executor and recorded as failed), and memo effects identical to what the
+ * first consuming context would have produced serially. Device boots resolve
+ * at boot initiation (raceBootInitiation); the chromedriver prefetch is the
+ * one task that awaits device readiness (it needs a live session).
+ */
+/* c8 ignore start — thin dispatch over injected/imported effects; the pure
+   pieces (planner, executor, raceBootInitiation, warmBrowserInstall) carry
+   the unit coverage, and the wiring is exercised end-to-end by the fixture
+   matrix + core-core.test.js. */
+function buildWarmTaskRunner({ config, runnerDetails, sizingJobs, appiumPool, installAttempts, warmUpResults, deviceRegistry, simulatorRegistry, resourceRegistry, }) {
+    // One Android env probe per run, shared by device boots and the
+    // chromedriver prefetch.
+    let androidEnv;
+    const getAndroidEnv = () => (androidEnv ??= resolveAndroidWarmEnv(config));
+    // One iOS toolchain probe per run, async so the (potentially slow) xcrun
+    // spawn never blocks the executor's event loop; device boots and the
+    // driver install share the single result.
+    let iosToolchain;
+    const getIosToolchain = () => (iosToolchain ??= probeIosToolchainWarm());
+    // Manual leases on the run's resource registry, for work that must
+    // serialize on a named mutex but can't express its hold window as a task
+    // tag (runResourceAware releases tags at task RESOLUTION, and warm tasks
+    // deliberately resolve before their background work finishes). The
+    // returned release is idempotent.
+    const acquireLease = async (names) => {
+        while (!resourceRegistry.tryAcquire(names)) {
+            await resourceRegistry.waitForFree();
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            resourceRegistry.release(names);
+        };
+    };
+    const withRuntimeInstallLock = async (fn) => {
+        const release = await acquireLease([RUNTIME_INSTALL_RESOURCE]);
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    };
+    // One android app preflight (driver install + Appium co-homing) per run,
+    // always performed under the install lease.
+    let androidPreflight;
+    const getAndroidPreflight = () => (androidPreflight ??= withRuntimeInstallLock(() => appSurfacePreflight({ config, platform: "android" })));
+    return async (task) => {
+        switch (task.kind) {
+            case "browser-install":
+                return warmBrowserInstall({
+                    browserName: task.payload.browserName,
+                    config,
+                    runnerDetails,
+                    installAttempts,
+                });
+            case "driver-install": {
+                // Mirror the per-context preflights' host-capability gates BEFORE
+                // installing: they probe the environment first and skip without
+                // installing on hosts that can never run the platform, and warm
+                // must not install what those gates would refuse.
+                if (task.payload.platform === "android") {
+                    const env = await getAndroidEnv();
+                    if (!env) {
+                        return {
+                            outcome: "skipped",
+                            note: "Android toolchain not ready; the driver install stays with the consuming context",
+                        };
+                    }
+                }
+                if (task.payload.platform === "ios") {
+                    const toolchain = await getIosToolchain();
+                    if (!toolchain.ok) {
+                        return { outcome: "skipped", note: toolchain.reason };
+                    }
+                }
+                // Same lazy-loaded install path appSurfacePreflight uses; it skips
+                // packages already resolvable, so the later per-context preflight
+                // finds the driver present and pays only Appium co-homing.
+                const { ensureRuntimeInstalled } = await import("../runtime/loader.js");
+                await ensureRuntimeInstalled([task.payload.driverPackage], {
+                    ctx: { cacheDir: config?.cacheDir },
+                    deps: { logger: (m) => log(config, "debug", m) },
+                });
+                return { outcome: "warmed" };
+            }
+            case "device-boot": {
+                const desc = task.payload.desc;
+                const onError = (error) => log(config, "warning", `Warm boot of '${task.name}' failed (a consuming context will retry): ${error?.message ?? String(error)}`);
+                if (task.payload.platform === "android") {
+                    const env = await getAndroidEnv();
+                    if (!env) {
+                        return {
+                            outcome: "skipped",
+                            note: "Android toolchain not ready; device setup stays with the consuming context",
+                        };
+                    }
+                    // Hold the run's "android-emulator" mutex from before initiation
+                    // until the boot settles — in the BACKGROUND, past this task's
+                    // resolution — so warm's boot and any Phase-2 job's boot (which
+                    // tag the same name) can never run two emulators at once: on a
+                    // small CI runner concurrent boots starve each other and the
+                    // sessions that follow. Released via the acquire promise's settle
+                    // chain (both branches handled — no unhandled rejection), not a
+                    // finally, precisely because the task resolves first.
+                    const releaseEmulatorLease = await acquireLease([
+                        "android-emulator",
+                    ]);
+                    return raceBootInitiation({
+                        onError,
+                        startAcquire: (signalInitiated) => {
+                            const acquiring = acquireDevice({
+                                desc,
+                                registry: deviceRegistry,
+                                sdkRoot: env.sdkRoot,
+                                deps: wrapInitiationEffects(env.deviceDeps, ["createAvd", "boot"], signalInitiated),
+                            });
+                            acquiring.then(() => releaseEmulatorLease(), () => releaseEmulatorLease());
+                            return acquiring;
+                        },
+                    });
+                }
+                const toolchain = await getIosToolchain();
+                if (!toolchain.ok) {
+                    return { outcome: "skipped", note: toolchain.reason };
+                }
+                const simDeps = buildAcquireSimulatorDeps((m) => log(config, "debug", m));
+                return raceBootInitiation({
+                    onError,
+                    startAcquire: (signalInitiated) => acquireSimulator({
+                        desc,
+                        registry: simulatorRegistry,
+                        deps: wrapInitiationEffects(simDeps, ["create", "boot"], signalInitiated),
+                    }),
+                });
+            }
+            case "wda-check": {
+                const hit = locateManagedWda({ ctx: { cacheDir: config?.cacheDir } });
+                if (hit) {
+                    return {
+                        outcome: "warmed",
+                        note: `prebuilt WebDriverAgent available (${hit.key})`,
+                    };
+                }
+                return {
+                    outcome: "skipped",
+                    note: "no prebuilt WebDriverAgent for the current toolchain — `doc-detective install ios` prebuilds it",
+                };
+            }
+            case "session-probe": {
+                if (!appiumPool) {
+                    return { outcome: "skipped", note: "no browser Appium pool" };
+                }
+                await warmUpContexts({
+                    jobs: sizingJobs,
+                    config,
+                    runnerDetails,
+                    appiumPool,
+                    installAttempts,
+                    warmUpResults,
+                });
+                const ok = [...warmUpResults.values()].filter((v) => v === "ok").length;
+                const failed = warmUpResults.size - ok;
+                // Failed combinations are a warm-level note, not a task failure:
+                // they already have per-context recorded-skip semantics downstream.
+                return {
+                    outcome: "warmed",
+                    note: `${ok} combination${ok === 1 ? "" : "s"} ok${failed ? `, ${failed} failed` : ""}`,
+                };
+            }
+            case "chromedriver-prefetch":
+                return prefetchMobileChromedriver({
+                    config,
+                    desc: task.payload.desc,
+                    deviceRegistry,
+                    getAndroidEnv,
+                    deps: {
+                        // The cache-mutating half (driver install + Appium co-homing)
+                        // runs once per run under the manual runtime-install lease, so
+                        // the prefetch task itself only holds its device tag while it
+                        // awaits readiness and runs the throwaway session.
+                        appSurfacePreflight: () => getAndroidPreflight(),
+                        acquireEmulatorLease: () => acquireLease(["android-emulator"]),
+                    },
+                });
+        }
+    };
+}
+/* c8 ignore stop */
+/**
+ * Pre-pay the on-device chromedriver download for android mobile-web: the
+ * UiAutomator2 server only fetches a chromedriver matching the device's
+ * Chrome at SESSION creation, so this task awaits the device (the one warm
+ * task that blocks on readiness), opens a disposable mobile-web session on a
+ * dedicated short-lived Appium server with the scoped autodownload feature —
+ * the exact shape runContext's mobile-web branch uses — and tears both down.
+ * The downloaded chromedriver lands in the shared cache, so the first real
+ * session skips the download. Because the warm phase is awaited before
+ * Phase 2 dispatch, this throwaway session can never overlap the first real
+ * session on the same device. A throw is the executor's problem (recorded
+ * as failed, run proceeds). Effects are injected for hermetic tests.
+ */
+async function prefetchMobileChromedriver({ config, desc, deviceRegistry, getAndroidEnv, deps = {}, }) {
+    const preflight = deps.appSurfacePreflight ?? appSurfacePreflight;
+    const acquire = deps.acquireDevice ?? acquireDevice;
+    const startServer = deps.startAppiumServer ?? startAppiumServer;
+    const startDriver = deps.driverStart ?? driverStart;
+    const kill = deps.killTree ?? killTree;
+    const env = await getAndroidEnv();
+    if (!env) {
+        return {
+            outcome: "skipped",
+            note: "Android toolchain not ready; the first mobile-web session downloads chromedriver as needed",
+        };
+    }
+    // Driver install + Appium co-homing, idempotent: usually a no-op after
+    // the driver-install task (the shared runtime-install exclusivity tag
+    // keeps the two from ever mutating the cache concurrently), and android
+    // has no platform probes, so this is exactly the install half.
+    const pre = await preflight({ config, platform: "android" });
+    if (!pre.ok)
+        return { outcome: "skipped", note: pre.reason };
+    // Await the device. If the device-boot task already initiated this boot,
+    // this acquire converges on the same registry entry and awaits its
+    // in-flight `ready`; otherwise it performs the full acquire itself —
+    // under the shared emulator lease, so a boot this task performs never
+    // overlaps another emulator boot in the run.
+    const releaseLease = deps.acquireEmulatorLease
+        ? await deps.acquireEmulatorLease()
+        : undefined;
+    let acquired;
+    try {
+        acquired = await acquire({
+            desc,
+            registry: deviceRegistry,
+            sdkRoot: env.sdkRoot,
+            deps: env.deviceDeps,
+        });
+    }
+    finally {
+        releaseLease?.();
+    }
+    if ("skip" in acquired)
+        return { outcome: "skipped", note: acquired.skip };
+    let server;
+    let driver;
+    try {
+        server = await startServer(pre.appiumEntry, config, undefined, {
+            APPIUM_HOME: pre.appiumHome,
+            ANDROID_HOME: env.sdkRoot,
+            ANDROID_SDK_ROOT: env.sdkRoot,
+        }, CHROMEDRIVER_AUTODOWNLOAD_ARGS);
+        driver = await startDriver(buildMobileBrowserCapabilities({
+            platform: "android",
+            udid: acquired.entry.udid,
+            cacheDir: getCacheDir({ cacheDir: config?.cacheDir }),
+        }), server.port, 2, { cacheDir: config?.cacheDir });
+        return {
+            outcome: "warmed",
+            note: `chromedriver ready for device '${acquired.entry.name}'`,
+        };
+    }
+    finally {
+        if (driver) {
+            try {
+                await driver.deleteSession();
+            }
+            catch {
+                // best-effort teardown of the throwaway session
+            }
+        }
+        if (server) {
+            await kill(server.process?.pid);
+        }
+    }
+}
 /**
  * Pure predicate: does this spec carry TEST-level routing? True iff ANY of its
  * tests has a non-empty `onPass`/`onFail`/`onWarning`/`onSkip` array. This is
@@ -2814,7 +3284,8 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
         contextReport.resultDescription = errorMessage;
         return contextReport;
     }
-    clog("debug", `CONTEXT:\n${JSON.stringify(context, null, 2)}`);
+    if (logLevelEnabled(config, "debug"))
+        clog("debug", `CONTEXT:\n${JSON.stringify(context, null, 2)}`);
     let driver;
     let appiumPort;
     // Multi-surface Phase 4 (ADR 01019): the context's browser-session registry.
@@ -2854,9 +3325,7 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             // Chromedriver autodownload is an Appium insecure feature; opt in
             // scoped to the uiautomator2 driver on this run-owned server so it can
             // fetch the chromedriver matching the device's Chrome.
-            const extraArgs = mobileTarget === "android"
-                ? ["--allow-insecure", "uiautomator2:chromedriver_autodownload"]
-                : [];
+            const extraArgs = mobileTarget === "android" ? CHROMEDRIVER_AUTODOWNLOAD_ARGS : [];
             // Server start + device boot are environment work: any failure there
             // (port pressure, an emulator that can't finish booting on this host,
             // simctl trouble) is a gating SKIP with the reason named — never a
@@ -3278,7 +3747,8 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 stepExecutionFailed = true;
                 break;
             }
-            clog("debug", `STEP:\n${JSON.stringify(step, null, 2)}`);
+            if (logLevelEnabled(config, "debug"))
+                clog("debug", `STEP:\n${JSON.stringify(step, null, 2)}`);
             if (step.unsafe && runnerDetails.allowUnsafeSteps === false) {
                 clog("warning", `Skipping unsafe step: ${step.description} in test ${test.testId} context ${context.contextId}`);
                 // Mark as skipped
@@ -3380,7 +3850,8 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                     processRegistry: processRegistry,
                     appSession: appSession,
                 });
-                clog("debug", `RESULT: ${r.status}\n${JSON.stringify(r, null, 2)}`);
+                if (logLevelEnabled(config, "debug"))
+                    clog("debug", `RESULT: ${r.status}\n${JSON.stringify(r, null, 2)}`);
                 r.result = r.status;
                 r.resultDescription = r.description;
                 delete r.status;
@@ -3968,7 +4439,12 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
 // Start one Appium server on a free port and resolve once it answers /status.
 // Each concurrent runner gets its own server (own port) so parallel contexts
 // never create sessions on the same Appium instance.
-async function startAppiumServer(appiumEntry, config, display, extraEnv, 
+// Spawn an Appium server process WITHOUT waiting for readiness. Split out from
+// startAppiumServer so the browser-pool startup (below) can spawn servers
+// SERIALLY — preserving the findFreePort close-to-rebind race protection and
+// avoiding a startup CPU spike — while OVERLAPPING their readiness polls. A
+// single-server caller uses startAppiumServer, which spawns then awaits.
+async function spawnAppiumServer(appiumEntry, config, display, extraEnv, 
 // Extra CLI args for the server, e.g. the scoped `--allow-insecure`
 // chromedriver-autodownload opt-in for android mobile-web sessions.
 extraArgs) {
@@ -3996,8 +4472,15 @@ extraArgs) {
     });
     proc.stdout.on("data", () => { });
     proc.stderr.on("data", () => { });
+    return { port, process: proc, display };
+}
+async function startAppiumServer(appiumEntry, config, display, extraEnv, 
+// Extra CLI args for the server, e.g. the scoped `--allow-insecure`
+// chromedriver-autodownload opt-in for android mobile-web sessions.
+extraArgs) {
+    const server = await spawnAppiumServer(appiumEntry, config, display, extraEnv, extraArgs);
     try {
-        await appiumIsReady(port);
+        await appiumIsReady(server.port);
     }
     catch (error) {
         // appiumIsReady threw or timed out — the spawned child is still alive and
@@ -4005,29 +4488,48 @@ extraArgs) {
         // propagating so subsequent runs don't trip on the stale state. Awaited
         // so the process is confirmed gone before this function returns control
         // to the caller.
-        await killTree(proc?.pid);
+        await killTree(server.process?.pid);
         throw error;
     }
-    log(config, "debug", `Appium is ready on port ${port}.`);
-    return { port, process: proc, display };
+    log(config, "debug", `Appium is ready on port ${server.port}.`);
+    return server;
 }
-// Delay execution until Appium server is available.
-async function appiumIsReady(port, timeoutMs = 120000) {
-    let isReady = false;
+// Per-probe HTTP timeout for the Appium `/status` check. Bounds a single
+// hung request so the overall readiness timeout can still fire; a healthy
+// server answers in milliseconds.
+const STATUS_PROBE_TIMEOUT_MS = 10000;
+// Delay execution until Appium server is available. Probe `/status`
+// IMMEDIATELY, then poll on a short 250ms interval until ready or the overall
+// timeout — a server that is already up returns in ~one round-trip instead of
+// paying a fixed leading 1s sleep (the old loop slept before its first probe).
+// `probe`/`sleep` are injectable for hermetic unit tests; the overall timeout
+// cap (default 120s) is unchanged.
+async function appiumIsReady(port, timeoutMs = 120000, deps = {}) {
+    const probe = deps.probe ??
+        (async (p) => {
+            try {
+                // Bound each probe: without a per-request timeout a hung /status
+                // response would block this await indefinitely, and the overall
+                // `timeoutMs` guard (checked only between probes) could never fire.
+                const resp = await axios.get(`http://127.0.0.1:${p}/status`, {
+                    timeout: STATUS_PROBE_TIMEOUT_MS,
+                });
+                return resp.status === 200;
+            }
+            catch {
+                return false;
+            }
+        });
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const start = Date.now();
-    while (!isReady) {
+    while (true) {
+        if (await probe(port))
+            return true;
         if (Date.now() - start > timeoutMs) {
             throw new Error(`Appium server on port ${port} failed to start within ${timeoutMs / 1000} seconds`);
         }
-        await new Promise((resolve) => setTimeout(resolve, 1000));
-        try {
-            let resp = await axios.get(`http://127.0.0.1:${port}/status`);
-            if (resp.status === 200)
-                isReady = true;
-        }
-        catch { }
+        await sleep(250);
     }
-    return isReady;
 }
 // Start the Appium driver specified in `capabilities`.
 async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {