doc-detective 4.38.0 → 4.41.4

package/dist/core/tests.js

@@ -8,15 +8,14 @@ import fs from "node:fs";
 // optional package on disk — webdriverio is an optionalDependency that npm may
 // skip on a CI runner, and a hard compile-time type reference would otherwise
 // turn that skipped install into an intermittent build failure.
-import { loadHeavyDep, resolveHeavyDepPath } from "../runtime/loader.js";
+import { loadHeavyDep, prefetchHeavyDep, resolveHeavyDepPath } from "../runtime/loader.js";
 import { resolveTheme } from "./annotations/model.js";
 import { annotate, pruneExpired, renderLayer } from "./tests/annotate.js";
 import { requiredBrowserAssets, ensureBrowserInstalled, } from "../runtime/browsers.js";
 // Single source of truth for browser/driver-requiring step keys.
 import { BROWSER_STEP_KEYS as driverActions, startSurfaceDescriptors, stepOpensBrowserSurface, stepTargetsProcessSurface, stepIsSurfacelessInteraction, testHasNonBrowserSurfaceSignal, } from "../runtime/browserStepKeys.js";
 import os from "node:os";
-import { log, logLevelEnabled, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, isRetryableSessionError, classifyContextRetry, realizeViewport, isViewportFloored, } from "./utils.js";
-import axios from "axios";
+import { log, logLevelEnabled, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, isRetryableSessionError, classifyContextRetry, guardBlankDocumentNavigation, applyBrowserSize, isViewportFloored, loadAxios, } from "./utils.js";
 import { instantiateCursor } from "./tests/moveTo.js";
 import { goTo } from "./tests/goTo.js";
 import { findElement } from "./tests/findElement.js";
@@ -37,26 +36,28 @@ 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, APP_DRIVER_PLATFORMS, probeIosToolchain, } from "./tests/appSurface.js";
+import { createAppSessionState, appSurfacePreflight, isAppDriverRequired, stepTargetsAppSurface, teardownAppSession, createAppServerPool, APP_DRIVER_PLATFORMS, probeIosToolchain, } from "./tests/appSurface.js";
 import { startSurfaceStep } from "./tests/startSurface.js";
 import { createActiveSurfaceTracker, } from "./tests/activeSurface.js";
 import { isMobileTargetPlatform } from "./tests/mobilePlatform.js";
+import { GECKODRIVER_EXECUTABLE_ARGS, applyDriverOptions, } from "./tests/geckoDriver.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";
-import { buildAcquireDeviceDeps, checkEmulatorAcceleration, hostHasKvm, planDeviceAcquisition, planAndroidToolchain, normalizeDeviceDescriptor, acquireDevice, createDeviceRegistry, teardownDeviceRegistry, } from "./tests/androidEmulator.js";
-import { buildAcquireSimulatorDeps, planSimulatorAcquisition, acquireSimulator, createSimulatorRegistry, teardownSimulatorRegistry, } from "./tests/iosSimulator.js";
+import { buildAcquireDeviceDeps, findUia2Helpers, checkEmulatorAcceleration, hostHasKvm, planDeviceAcquisition, planAndroidToolchain, normalizeDeviceDescriptor, acquireDevice, createDeviceRegistry, teardownDeviceRegistry, shutdownEmulator, } from "./tests/androidEmulator.js";
+import { buildAcquireSimulatorDeps, planSimulatorAcquisition, acquireSimulator, createSimulatorRegistry, teardownSimulatorRegistry, iosMajorOfRuntime, } from "./tests/iosSimulator.js";
 import { runBrowserScript } from "./tests/runBrowserScript.js";
 import { dragAndDropElement } from "./tests/dragAndDrop.js";
 import { createSessionRegistry, registerSession, activeDriver, sweepSessions, } from "./tests/browserSessions.js";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { setAppiumHome } from "./appium.js";
-import { contentHash } from "../common/src/detectTests.js";
+import { setAppiumHome, appiumHomeForDriverPath, useDriversArgs, browserPoolDriverPackages, } from "./appium.js";
+import { reuseAppiumEnabled, appiumServerKey, createServerCache, takeServer, handBackServer, probeStatus, listSessions, allowSessionDiscovery, APPIUM_WATCHDOG_IMPORT, } from "./appiumReuse.js";
+import { contentHash } from "../common/src/textUtils.js";
 import { resolveExpression } from "./expressions.js";
 import { evaluateCustomAssertions, evaluateGuard, guardReferencesSteps, customAssertionsReferenceSteps, resolveStepRouting, resolveTestRouting, computeRetryDelay, buildConditionContext, } from "./routing.js";
 import { getEnvironment, getAvailableApps, clearAppCache, resolveConcurrentRunners, } from "./config.js";
@@ -65,8 +66,26 @@ 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, resolveRetryPolicy, runContextWithRetries, shouldRepairBeforeFallback, isSupportedContext, contextRequirementsSkipMessage, resolveAutoScreenshot, resolveAutoRecord, buildAutoRecordStep, specIsRouted, killTree, jobDisplayResources, buildWarmPlanDeps, warmBrowserInstall, prefetchMobileChromedriver, appiumIsReady, };
-// exports.driverStart = driverStart;
+// Idle browser-pool Appium servers kept between runs in this process, only
+// when DOC_DETECTIVE_REUSE_APPIUM is set (ADR 01125). Empty otherwise.
+// killTree is a hoisted function declaration, called only when a server dies.
+// Background kill failures log at debug under the last reusing run's config.
+// Used only for that log line, so last-writer-wins across concurrent runs is fine.
+// Only logLevel is read (by log()).
+let lastReuseConfig;
+const appiumServerCache = createServerCache({
+    kill: (server) => killTree(server.process?.pid),
+    onKillError: (server, err) => log(lastReuseConfig ?? {}, "debug", `Failed to close idle Appium server on port ${server.port}: ${err?.message ?? err}`),
+    idleMs: 60000,
+    maxIdle: 4,
+});
+// The runner's appiumIsReady call sites poll at this interval. A refused
+// /status on loopback fails in about a millisecond, so a tighter poll costs
+// nothing and trims the lag between Appium coming up and the run noticing
+// (ADR 01124). appiumIsReady's own 250ms default stays for callers that don't
+// pass `pollMs`.
+const APPIUM_READY_POLL_MS = 50;
+export { runSpecs, runViaApi, getRunner, ensureChromeAvailable, ensureContextBrowserInstalled, combinationKey, warmUpDecision, selectWarmUpTargets, getDriverCapabilities, withDriverPort, getDefaultBrowser, buildFallbackCandidates, driverSkipDiagnostic, resolveBrowserFallbackPolicy, resolveRetryPolicy, runContextWithRetries, shouldRepairBeforeFallback, isSupportedContext, contextRequirementsSkipMessage, resolveAutoScreenshot, resolveAutoRecord, buildAutoRecordStep, specIsRouted, killTree, appiumServerCache, jobDisplayResources, buildWarmPlanDeps, warmBrowserInstall, prefetchMobileChromedriver, appiumIsReady, APPIUM_READY_POLL_MS, driverStart, };
 // Browser names getDriverCapabilities knows how to build caps for. `safari` is
 // rewritten to `webkit` during context resolution, so both appear here.
 const KNOWN_BROWSERS = ["firefox", "chrome", "safari", "webkit"];
@@ -212,6 +231,18 @@ function getDriverCapabilities({ runnerDetails, name, options }) {
                 "appium:newCommandTimeout": 600, // 10 minutes
                 browserName: "MozillaFirefox",
                 "wdio:enforceWebDriverClassic": true, // Disable BiDi, use classic mode
+                // Pin the geckodriver Doc Detective manages. appium-geckodriver
+                // resolves its binary from this capability or `which geckodriver` and
+                // nothing else, so without it the managed install in the browsers cache
+                // (version-suffixed, off PATH) can never be used — Firefox then only
+                // works where some other geckodriver happens to be on PATH, which is
+                // why containers fail and GitHub-hosted runners don't. The pool's
+                // servers always carry GECKODRIVER_EXECUTABLE_ARGS, which is what makes
+                // this insecure-gated capability legal to send. Omitted when no path
+                // was resolved, leaving the PATH lookup as the Layer 4 fallback.
+                ...(firefox.driver
+                    ? { "appium:geckodriverExecutable": firefox.driver }
+                    : {}),
                 "moz:firefoxOptions": {
                     // Reference: https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/firefoxOptions
                     args,
@@ -309,17 +340,26 @@ function getDriverCapabilities({ runnerDetails, name, options }) {
 // the other's connection is REFUSED, surfacing later as a mid-session
 // `ECONNREFUSED 127.0.0.1:9515` when a command proxies to the wrong/dead
 // chromedriver (ADR 01039). Assigning a unique free port per session removes the
-// collision. Gecko/Safari are unaffected — geckodriver auto-selects a free
-// `systemPort` from a range, and Safari has no such port — so this only touches
-// Chromium caps, leaving every other engine's caps byte-identical. An explicit
-// `appium:chromedriverPort` (a caller opting into a fixed port) is preserved.
-function withChromedriverPort(capabilities, port) {
-    if (!capabilities ||
-        capabilities["appium:automationName"] !== "Chromium" ||
-        capabilities["appium:chromedriverPort"] !== undefined) {
-        return capabilities;
-    }
-    return { ...capabilities, "appium:chromedriverPort": port };
+// collision. Gecko races the same way, just less often: appium-geckodriver
+// picks the lowest free port in 5200..5300 for `systemPort` but only reserves
+// it once geckodriver binds, so two concurrent Appium servers can both pick
+// 5200 and one proxies into the other's geckodriver session ("Got unexpected
+// session id"; ADR 01105). Safari has no such port, so its caps (and every
+// other engine's) stay byte-identical. An explicit port capability (a caller
+// opting into a fixed port) is preserved.
+const DRIVER_PORT_CAPABILITY = {
+    Chromium: "appium:chromedriverPort",
+    Gecko: "appium:systemPort",
+};
+// The port capability these caps still need, or undefined when the engine has
+// none or the caller already pinned one.
+function driverPortCapability(capabilities) {
+    const key = DRIVER_PORT_CAPABILITY[capabilities?.["appium:automationName"]];
+    return key && capabilities[key] === undefined ? key : undefined;
+}
+function withDriverPort(capabilities, port) {
+    const key = driverPortCapability(capabilities);
+    return key ? { ...capabilities, [key]: port } : capabilities;
 }
 function isDriverRequired({ test }) {
     let driverRequired = false;
@@ -495,6 +535,23 @@ function isBrowserRequired({ test }) {
             // (the goTo-opener sibling); app/process descriptors don't.
             stepOpensBrowserSurface(step)));
 }
+// Whether any context in `specs` could read the available-apps list: it names a
+// browser, targets a mobile platform, or has a step that drives a browser or
+// opens/closes a surface. A deliberate superset of every availableApps reader in
+// this file, so a run where it's false never consults the list and can skip
+// detection (ADR 01133). Falls back to the test's steps only when a context has
+// no steps array; an explicit `steps: []` is a context with nothing to run.
+export function runNeedsAvailableApps(specs) {
+    const list = (v) => (Array.isArray(v) ? v : []);
+    const stepNeedsApps = (step) => Boolean(step) &&
+        typeof step === "object" &&
+        (step.startSurface !== undefined ||
+            step.closeSurface !== undefined ||
+            driverActions.some((key) => step[key] !== undefined));
+    return list(specs).some((spec) => list(spec?.tests).some((test) => list(test?.contexts).some((context) => Boolean(context?.browser) ||
+        isMobileTargetPlatform(context?.platform) ||
+        list(Array.isArray(context?.steps) ? context.steps : test?.steps).some(stepNeedsApps))));
+}
 // Size the browser Appium server pool: the number of concurrent runner jobs
 // that will actually create a BROWSER session. App-only jobs are excluded —
 // they provision their own per-context Appium server (homed where the native
@@ -508,6 +565,12 @@ export function browserJobCount(jobs) {
     return jobs.filter((job) => isBrowserRequired({ test: job?.context }))
         .length;
 }
+// Whether a job's context has a screenshot step: gates the sharp prefetch
+// during Appium's boot (ADR 01135).
+export function jobTakesScreenshot(job) {
+    const steps = job?.context?.steps;
+    return Array.isArray(steps) && steps.some((s) => s?.screenshot !== undefined);
+}
 // Evaluate a context's `requires` capability gate. Returns null when the gate
 // is absent or fully met; otherwise a skip message naming every unmet
 // requirement, so the context lands as SKIPPED (the same non-failing outcome
@@ -685,7 +748,7 @@ async function androidContextPreflight({ config, context, clog, }) {
                 };
             }
         }
-        const deviceDeps = buildAcquireDeviceDeps(sdk, abi, (m) => clog("debug", m));
+        const deviceDeps = buildAcquireDeviceDeps(sdk, abi, (m) => clog("debug", m), uia2HelpersResolver(config));
         // Device plan: every device the test needs must resolve (reuse an existing
         // AVD/emulator, or create one from an installed image + Java). A gap SKIPs.
         const running = await deviceDeps.listRunning();
@@ -913,29 +976,6 @@ function driverSkipDiagnostic({ requestedName, platform, platformMatches, attemp
     msg += ` A present-but-broken driver (for example a partially downloaded ${driverHint}) can cause this; reinstall the driver or its browser.`;
     return msg;
 }
-// Realize a context's target viewport and return the size the page actually
-// rendered. Prefers viewport emulation (exact size, no window floor) and falls
-// back to window resizing, warning if the browser/OS floored the request. The
-// `// Confirm viewport size` intent is now realized by realizeViewport's
-// read-back.
-async function setViewportSize(context, driver, config = {}) {
-    // Guard on POSITIVE dimensions (not truthiness): the schema doesn't floor
-    // these, so a 0/negative/NaN value must not enter the resize path — matching
-    // the startSurface browser descriptor's guard.
-    const vw = Number(context.browser?.viewport?.width);
-    const vh = Number(context.browser?.viewport?.height);
-    if (vw > 0 || vh > 0) {
-        const requested = {
-            ...(vw > 0 ? { width: vw } : {}),
-            ...(vh > 0 ? { height: vh } : {}),
-        };
-        // Attribute the warning so a multi-context run can tell which context's
-        // viewport was floored.
-        const label = `viewport for ${context.browser?.name ?? "browser"} on ${context.platform ?? "host"}`;
-        return realizeViewport(driver, requested, config, label);
-    }
-    return undefined;
-}
 async function allowUnsafeSteps({ config }) {
     // If allowUnsafeSteps is set to true, return true
     if (config.allowUnsafeSteps === true)
@@ -958,6 +998,7 @@ async function allowUnsafeSteps({ config }) {
 }
 // Run specifications via API.
 async function runViaApi({ resolvedTests, apiKey, config = {} }) {
+    const axios = await loadAxios();
     // Apply specFilter / testFilter before sending. Without this the API run
     // path silently ignores --test / --spec, since the orchestration server
     // sees the full unfiltered payload.
@@ -1126,10 +1167,16 @@ async function runSpecs({ resolvedTests }) {
             specs: [],
         };
     }
-    // Get runner details
+    // Get runner details. Browser detection is skipped when no context can use
+    // its result (ADR 01133); APPIUM_HOME is still set, as detection would have.
+    const needsApps = runNeedsAvailableApps(specs);
+    if (!needsApps) {
+        log(config, "debug", "No context in this run uses a browser; skipping browser detection.");
+        setAppiumHome({ cacheDir: config?.cacheDir });
+    }
     const runnerDetails = {
         environment: getEnvironment(),
-        availableApps: await getAvailableApps({ config }),
+        availableApps: needsApps ? await getAvailableApps({ config }) : [],
         allowUnsafeSteps: await allowUnsafeSteps({ config }),
     };
     // Set initial shorthand values
@@ -1310,6 +1357,9 @@ async function runSpecs({ resolvedTests }) {
                 description: test.description,
                 contentPath: test.contentPath,
                 detectSteps: test.detectSteps,
+                // Resolved by position via applyBadgeAnchoredTests (ADR 01141), not by name.
+                badge: test.badge,
+                location: test.location,
                 contexts: new Array(test.contexts.length),
             };
             specReport.tests.push(testReport);
@@ -1436,15 +1486,16 @@ async function runSpecs({ resolvedTests }) {
     const xvfbProcesses = [];
     const useXvfbDisplays = concurrency.xvfbContexts.length > 0;
     let portToDisplay;
+    // Set only when this run takes and hands back idle servers (ADR 01125).
+    // Xvfb runs never reuse: their displays die with the run.
+    let reuseKey;
     if (browserPoolJobCount > 0) {
         setAppiumHome({ cacheDir: config?.cacheDir });
-        // Resolve appium's actual JS entrypoint via `require.resolve` (shim
-        // node_modules first, runtime cache second) and invoke it with
-        // `node <entry>`. This sidesteps every shell-injection trap at once: no
-        // `.cmd` shim, so no Windows-requires-shell:true; no `npx`, so no PATH
-        // lookup; no user-controlled paths in a shell-interpreted string. Works
-        // for both `--omit=optional` users (appium in cache only) and default
-        // installs (appium in shim).
+        // Resolve appium's actual JS entrypoint via `require.resolve` (always
+        // from the runtime cache, the shared APPIUM_HOME — ADR 01111) and invoke
+        // it with `node <entry>`. This sidesteps every shell-injection trap at
+        // once: no `.cmd` shim, so no Windows-requires-shell:true; no `npx`, so no
+        // PATH lookup; no user-controlled paths in a shell-interpreted string.
         const appiumEntry = resolveHeavyDepPath("appium", {
             cacheDir: config?.cacheDir,
         });
@@ -1465,16 +1516,54 @@ async function runSpecs({ resolvedTests }) {
             // await them together so the waits OVERLAP — total ≈ max(readiness)
             // instead of the sum of serial waits.
             const readinessWaits = [];
+            // Load only the desktop browser drivers (ADR 01117): the shared home
+            // also holds the mobile drivers, which roughly doubled startup.
+            const poolDriverPackages = browserPoolDriverPackages(process.platform);
+            const useDrivers = useDriversArgs(process.env.APPIUM_HOME, poolDriverPackages);
+            // Every desktop pool server allows the geckodriver-path insecure
+            // feature, not just the ones a Firefox context lands on: these servers
+            // are shared across contexts and cross-browser fallback can route a
+            // chrome-authored context to Firefox mid-run, so gating the flag on the
+            // run's authored browsers would leave the capability illegal exactly
+            // when the fallback needs it. See GECKODRIVER_EXECUTABLE_ARGS.
+            let serverArgs = [...GECKODRIVER_EXECUTABLE_ARGS, ...useDrivers];
+            if (reuseAppiumEnabled() && !useXvfbDisplays) {
+                // Hand-back must be able to list leftover sessions.
+                serverArgs = allowSessionDiscovery(serverArgs);
+                lastReuseConfig = config;
+                reuseKey = appiumServerKey({
+                    entry: appiumEntry,
+                    args: serverArgs,
+                    env: process.env,
+                    appiumHome: process.env.APPIUM_HOME,
+                    packages: ["appium", ...poolDriverPackages],
+                });
+            }
             for (let i = 0; i < serverCount; i++) {
+                const reused = reuseKey
+                    ? await takeServer(appiumServerCache, reuseKey, { isReady: probeStatus })
+                    : undefined;
+                if (reused) {
+                    log(config, "debug", `Reusing idle Appium server on port ${reused.port}.`);
+                    // A spawn would prefetch webdriverio (ADR 01135); a reused server
+                    // skips the spawn, so start the import here instead.
+                    prefetchHeavyDep("webdriverio", { cacheDir: config?.cacheDir });
+                    appiumServers.push(reused);
+                    continue;
+                }
                 let display;
                 if (useXvfbDisplays) {
                     display = xvfbDisplay(i);
                     xvfbProcesses.push(await startXvfb(display));
                     log(config, "debug", `Started Xvfb on ${display} for recording.`);
                 }
-                const server = await spawnAppiumServer(appiumEntry, config, display);
+                // A reusable server exits once this process dies (ADR 01125).
+                const server = await spawnAppiumServer(appiumEntry, config, display, undefined, serverArgs, reuseKey ? ["--import", APPIUM_WATCHDOG_IMPORT] : undefined);
+                appiumServerCache.resetPort(server.port);
                 appiumServers.push(server);
-                const wait = appiumIsReady(server.port);
+                const wait = appiumIsReady(server.port, undefined, {
+                    pollMs: APPIUM_READY_POLL_MS,
+                });
                 // 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
@@ -1483,6 +1572,8 @@ async function runSpecs({ resolvedTests }) {
                 wait.catch(() => { });
                 readinessWaits.push(wait);
             }
+            if (sizingJobs.some(jobTakesScreenshot))
+                prefetchHeavyDep("sharp", { cacheDir: config?.cacheDir });
             await Promise.all(readinessWaits);
             for (const server of appiumServers) {
                 log(config, "debug", `Appium is ready on port ${server.port}.`);
@@ -1525,6 +1616,10 @@ async function runSpecs({ resolvedTests }) {
     // Swept in the `finally` below — only simulators Doc Detective booted are
     // shut down (launch-ownership).
     const simulatorRegistry = createSimulatorRegistry();
+    // Run-level pool of iOS app Appium servers (ADR 01115): sequential iOS
+    // contexts reuse one server instead of starting and killing their own.
+    // Drained in the `finally` below.
+    const appServerPool = createAppServerPool();
     // 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
@@ -1572,7 +1667,7 @@ async function runSpecs({ resolvedTests }) {
         signalHandled = true;
         (async () => {
             await killAllRegistered();
-            await Promise.all(appiumServers.map((server) => killTree(server.process?.pid)));
+            await Promise.all([...appiumServers, ...appServerPool.drain()].map((server) => killTree(server.process?.pid)));
             for (const xvfb of xvfbProcesses) {
                 try {
                     xvfb.kill();
@@ -1665,6 +1760,7 @@ async function runSpecs({ resolvedTests }) {
                     processRegistry,
                     deviceRegistry,
                     simulatorRegistry,
+                    appServerPool,
                     logPrefix: limit > 1 ? `[${job.test.testId}/${job.context.contextId}]` : "",
                 });
             }
@@ -1746,6 +1842,7 @@ async function runSpecs({ resolvedTests }) {
                     processRegistry,
                     deviceRegistry,
                     simulatorRegistry,
+                    appServerPool,
                     platform,
                     markAutoRecord,
                     limit,
@@ -1806,10 +1903,35 @@ async function runSpecs({ resolvedTests }) {
         // (shells out to `taskkill /T /F` on Windows); firing it without
         // awaiting let the run finish before the browser was really dead,
         // orphaning it.
-        await Promise.all(appiumServers.map((server) => {
+        // With reuse on (ADR 01125), a server with no sessions left goes back to
+        // the cache instead; one that still has a session is killed the same way.
+        await Promise.all(appiumServers.map(async (server) => {
+            if (reuseKey) {
+                const outcome = await handBackServer(appiumServerCache, reuseKey, server, {
+                    listSessions,
+                });
+                log(config, "debug", outcome === "parked"
+                    ? `Keeping idle Appium server on port ${server.port} for reuse.`
+                    : `Closed Appium server on port ${server.port}`);
+                return;
+            }
             log(config, "debug", `Closing Appium server on port ${server.port}`);
             return killTree(server.process?.pid);
         }));
+        // Close the pooled iOS app servers (ADR 01115) through the same teardown a
+        // per-context server gets, so the Windows orphan sweep still applies.
+        for (const server of appServerPool.drain()) {
+            log(config, "debug", `Closing app Appium server on port ${server.port}`);
+            // A fresh state with no `release` sends teardown down the kill path.
+            const owner = createAppSessionState();
+            owner.server = { port: server.port, process: server.process };
+            try {
+                await teardownAppSession(owner, (pid) => killTree(pid));
+            }
+            catch (error) {
+                log(config, "debug", `Couldn't close app Appium server: ${error?.message ?? error}`);
+            }
+        }
         // Tear down any Xvfb virtual displays started for recording.
         for (const xvfb of xvfbProcesses) {
             try {
@@ -1827,7 +1949,9 @@ async function runSpecs({ resolvedTests }) {
         if (deviceRegistry.size > 0) {
             await teardownDeviceRegistry(deviceRegistry, async (entry) => {
                 log(config, "debug", `Shutting down emulator "${entry.name}" (${entry.udid}).`);
-                await killTree(entry.process?.pid);
+                // Graceful, not a tree-kill: a hard kill can leave the AVD's disk
+                // images (and the clean boot snapshot inside them) inconsistent.
+                await shutdownEmulator(entry);
             });
         }
         // Sweep the iOS simulator registry (native app phase A4): shut down only the
@@ -1908,7 +2032,7 @@ async function runSpecs({ resolvedTests }) {
  * NEVER touches the summary — Phase-3 in runSpecs remains the sole tally site;
  * here we only push reports.
  */
-async function runRoutedSpec({ spec, specReport, specGuardSkip, config, runnerDetails, appiumPool, portToDisplay, metaValues, installAttempts, warmUpResults, processRegistry, deviceRegistry, simulatorRegistry, platform, markAutoRecord, limit, resourceRegistry, exclusivityCtx, }) {
+async function runRoutedSpec({ spec, specReport, specGuardSkip, config, runnerDetails, appiumPool, portToDisplay, metaValues, installAttempts, warmUpResults, processRegistry, deviceRegistry, simulatorRegistry, appServerPool, platform, markAutoRecord, limit, resourceRegistry, exclusivityCtx, }) {
     // Set once a `stop:spec` (or deferred `stop:run`) decision halts the spec; the
     // remaining tests are recorded SKIPPED with the stop reason and not executed.
     let stopRest = false;
@@ -1969,6 +2093,8 @@ async function runRoutedSpec({ spec, specReport, specGuardSkip, config, runnerDe
             description: test.description,
             contentPath: test.contentPath,
             detectSteps: test.detectSteps,
+            badge: test.badge,
+            location: test.location,
             contexts: new Array(test.contexts.length),
         };
         // Stamp the visit number when a backward goToTest re-ran this test (additive
@@ -2072,6 +2198,7 @@ async function runRoutedSpec({ spec, specReport, specGuardSkip, config, runnerDe
                     processRegistry,
                     deviceRegistry,
                     simulatorRegistry,
+                    appServerPool,
                     logPrefix: limit > 1 ? `[${job.test.testId}/${job.context.contextId}]` : "",
                 });
             }
@@ -2363,6 +2490,20 @@ async function warmBrowserInstall({ browserName, config, runnerDetails, installA
         note: `'${browserName}' has no installable assets`,
     };
 }
+// Resolves the UiAutomator2 driver's helper APKs (and its version) from
+// wherever the driver is installed, for baking into clean snapshots (ADR
+// 01108). Lazy: the warm-phase boot can start before the driver install ends.
+function uia2HelpersResolver(config) {
+    return () => {
+        const entry = resolveHeavyDepPath("appium-uiautomator2-driver", {
+            cacheDir: config?.cacheDir,
+        });
+        const home = entry ? appiumHomeForDriverPath(entry) : null;
+        return home
+            ? findUia2Helpers(path.join(home, "node_modules", "appium-uiautomator2-driver"))
+            : null;
+    };
+}
 /**
  * Light per-run Android environment probe for warm tasks: SDK + emulator
  * binary + acceleration (or a running emulator). Null means "not ready" —
@@ -2379,7 +2520,7 @@ async function resolveAndroidWarmEnv(config) {
         const sdk = detectAndroidSdk({ cacheDir: config?.cacheDir });
         if (!sdk?.emulator)
             return null;
-        const deviceDeps = buildAcquireDeviceDeps(sdk, abi, (m) => log(config, "debug", m));
+        const deviceDeps = buildAcquireDeviceDeps(sdk, abi, (m) => log(config, "debug", m), uia2HelpersResolver(config));
         const running = await deviceDeps.listRunning();
         const capable = running.length > 0 || (await checkEmulatorAcceleration(sdk.emulator));
         if (!capable)
@@ -2685,7 +2826,13 @@ async function prefetchMobileChromedriver({ config, desc, deviceRegistry, getAnd
             APPIUM_HOME: pre.appiumHome,
             ANDROID_HOME: env.sdkRoot,
             ANDROID_SDK_ROOT: env.sdkRoot,
-        }, CHROMEDRIVER_AUTODOWNLOAD_ARGS);
+        }, [
+            ...CHROMEDRIVER_AUTODOWNLOAD_ARGS,
+            // Load only UiAutomator2 (ADR 01117).
+            ...useDriversArgs(pre.appiumHome, [
+                APP_DRIVER_PLATFORMS.android.driverPackage,
+            ]),
+        ]);
         driver = await startDriver(buildMobileBrowserCapabilities({
             platform: "android",
             udid: acquired.entry.udid,
@@ -3016,7 +3163,7 @@ async function captureAutoScreenshot({ config, driver, spec, test, context, step
  * report or summary counters — the caller owns aggregation, which keeps this
  * function safe to run concurrently with sibling contexts.
  */
-async function runContext({ config, spec, test, context, runnerDetails, appiumPool, portToDisplay, metaValues, installAttempts, warmUpResults, processRegistry, deviceRegistry, simulatorRegistry, logPrefix = "", }) {
+async function runContext({ config, spec, test, context, runnerDetails, appiumPool, portToDisplay, metaValues, installAttempts, warmUpResults, processRegistry, deviceRegistry, simulatorRegistry, appServerPool, logPrefix = "", }) {
     const platform = runnerDetails.environment.platform;
     // `let`, not `const`: an on-demand browser install below re-detects available
     // apps and reassigns this snapshot.
@@ -3145,6 +3292,7 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             appSession.appiumHome = pre.appiumHome;
             appSession.iosSimulatorRegistry = simulatorRegistry;
             appSession.iosSimulatorDeps = pre.simulatorDeps;
+            appSession.appServerPool = appServerPool;
             gateBrowserName = pre.mobileWebBrowserName;
             /* c8 ignore stop */
         }
@@ -3372,15 +3520,33 @@ 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" ? CHROMEDRIVER_AUTODOWNLOAD_ARGS : [];
+            const extraArgs = [
+                ...(mobileTarget === "android" ? CHROMEDRIVER_AUTODOWNLOAD_ARGS : []),
+                // Load only the device's driver (ADR 01117).
+                ...useDriversArgs(appSession.appiumHome, [
+                    (mobileTarget === "android"
+                        ? APP_DRIVER_PLATFORMS.android
+                        : APP_DRIVER_PLATFORMS.ios).driverPackage,
+                ]),
+            ];
             // 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
             // FAIL — matching the mobile rule that every environment gap SKIPs.
             let acquired;
             try {
-                const server = await startAppiumServer(appSession.appiumEntry, config, undefined, env, extraArgs);
-                appSession.server = { port: server.port, process: server.process };
+                const start = async () => startAppiumServer(appSession.appiumEntry, config, undefined, env, extraArgs);
+                // iOS shares the run's pooled server for this launch environment
+                // (ADR 01115); `release` hands it back at context teardown.
+                const pool = appSession.appServerPool;
+                const server = pool
+                    ? await pool.acquire(JSON.stringify({ appiumEntry: appSession.appiumEntry, env, extraArgs }), start)
+                    : await start();
+                appSession.server = {
+                    port: server.port,
+                    process: server.process,
+                    release: server.release,
+                };
                 const desc = normalizeDeviceDescriptor({
                     contextDevice: context.device,
                     platform: mobileTarget,
@@ -3427,13 +3593,19 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 // The resolved cache root (not the raw config field, which is
                 // usually unset) — the chromedriver autodownload dir lives here.
                 cacheDir: getCacheDir({ cacheDir: config?.cacheDir }),
+                // iOS: the simulator's version picks the WDA launch mode (ADR 01110).
+                iosMajor: iosMajorOfRuntime(acquired.entry.runtime),
             });
             try {
                 driver = await driverStart(capabilities, appSession.server.port, 2, {
                     cacheDir: config?.cacheDir,
+                    log: (m) => clog("warning", m),
                 });
             }
             catch (error) {
+                // A client-side timeout can abort while the server is still creating
+                // the session, so keep a pooled server out of reuse (ADR 01115).
+                appSession.sessionLeftOpen = true;
                 // A capable host that can't open the device browser is an
                 // environment gap (the absent-browser precedent): SKIP with the
                 // likely cause named, never FAIL.
@@ -3500,18 +3672,18 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                         runnerDetails,
                         name: browserName,
                         options: {
-                            width: overrides?.size?.width ||
-                                context.browser?.window?.width ||
-                                1200,
-                            height: overrides?.size?.height ||
-                                context.browser?.window?.height ||
-                                800,
                             headless,
                             ...recordOptions,
                         },
                     });
-                    if (overrides?.driverOptions)
-                        Object.assign(caps, overrides.driverOptions);
+                    // Merge the authored escape hatch, minus the capabilities that are
+                    // only legal because we opted the server in to an insecure feature.
+                    // A plain Object.assign here would let a spec-authored
+                    // `appium:geckodriverExecutable` overwrite the managed path and have
+                    // Appium spawn any local binary. See PROTECTED_CAPABILITIES.
+                    if (overrides?.driverOptions) {
+                        applyDriverOptions(caps, overrides.driverOptions, (message) => log(config, "warning", message));
+                    }
                     return caps;
                 };
                 const startFailure = () => {
@@ -3652,6 +3824,18 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                         const res = await startDriverForBrowser(engine, overrides);
                         if (!res.ok)
                             throw new Error(res.error);
+                        // A later session takes the context's size unless its
+                        // startSurface descriptor sets `size`. A sizing failure leaves
+                        // the session usable at its default size, so warn, don't fail.
+                        try {
+                            await applyBrowserSize(res.driver, Number(overrides?.size?.width) > 0 ||
+                                Number(overrides?.size?.height) > 0
+                                ? { window: overrides.size }
+                                : context.browser, config, `browser session for ${engine}`);
+                        }
+                        catch (error) {
+                            log(config, "warning", `Couldn't size the new ${engine} session: ${error?.message ?? error}`);
+                        }
                         return res.driver;
                     },
                     isNameTaken: (name) => !!processRegistry?.has(name),
@@ -3663,31 +3847,18 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                     driver,
                 });
             }
-            // Positive-dimension guard (not truthiness): a 0/negative/NaN viewport
-            // must fall through to the window-size branch rather than entering the
-            // (no-op) viewport path.
-            const viewportW = Number(context.browser?.viewport?.width);
-            const viewportH = Number(context.browser?.viewport?.height);
-            if (viewportW > 0 || viewportH > 0) {
-                // Set driver viewport size
-                const realized = await setViewportSize(context, driver, config);
-                // Stamp the context REPORT (not the context object — the report is a
-                // curated copy) when the browser floored the request. A context-level
-                // viewport has no step output to carry the realized size, so this is
-                // the only signal the post-run `useMobilePlatforms` hint can read.
-                if (isViewportFloored({
-                    ...(viewportW > 0 ? { width: viewportW } : {}),
-                    ...(viewportH > 0 ? { height: viewportH } : {}),
-                }, realized)) {
-                    contextReport.viewportFloored = true;
-                }
-            }
-            else if (context.browser?.window?.width ||
-                context.browser?.window?.height) {
-                // Get driver window size
-                const windowSize = await driver.getWindowSize();
-                // Resize window if necessary
-                await driver.setWindowSize(context.browser?.window?.width || windowSize.width, context.browser?.window?.height || windowSize.height);
+            // Size the session: the authored viewport, else the authored window,
+            // else the default viewport (ADR 01144). The label attributes a floor
+            // warning to this context in a multi-context run.
+            const sizing = await applyBrowserSize(driver, context.browser, config, `viewport for ${context.browser?.name ?? "browser"} on ${context.platform ?? "host"}`);
+            // Stamp the context REPORT (not the context object — the report is a
+            // curated copy) when the browser floored an authored viewport. A
+            // context-level viewport has no step output to carry the realized size,
+            // so this is the only signal the post-run `useMobilePlatforms` hint can
+            // read.
+            if (sizing.target.kind === "viewport" &&
+                isViewportFloored(sizing.target, sizing.realized)) {
+                contextReport.viewportFloored = true;
             }
         }
         // Effective autoScreenshot for this context (test > spec > config).
@@ -4129,7 +4300,9 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             // retry warning the wrapper already logs. The alive-but-unusable cases do,
             // because "the session responded and we retried anyway" is otherwise
             // surprising in a log.
-            const retryReason = await classifyContextRetry(probeDrivers);
+            const retryReason = await classifyContextRetry(probeDrivers, {
+                navigated: contextReport.steps.some((s) => s.goTo !== undefined && s.result !== "SKIPPED"),
+            });
             if (retryReason) {
                 sessionDiedMidRun = true;
                 if (retryReason === "page-broken") {
@@ -4190,8 +4363,11 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
         // start, so the sweep covers it; sessions a closeSurface step already
         // ended are gone from the registry). In a finally so an unexpected throw
         // can't leak sessions while sibling contexts keep running.
+        // A session left open (a failed delete) must keep a pooled iOS app server
+        // from being reused: the mobile-web session runs on it (ADR 01115).
+        let sessionsClosed = true;
         if (browserSessions) {
-            await sweepSessions(browserSessions);
+            sessionsClosed = await sweepSessions(browserSessions);
         }
         else if (driver) {
             // Registry creation is unconditional after a driver starts, so this
@@ -4200,9 +4376,12 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 await driver.deleteSession();
             }
             catch (error) {
+                sessionsClosed = false;
                 clog("error", `Failed to delete driver session: ${error.message}`);
             }
         }
+        if (appSession && !sessionsClosed)
+            appSession.sessionLeftOpen = true;
         // Tear down app surfaces: close every remaining app session (the driver
         // terminates apps it launched) and stop the app Appium server. Tree-kill
         // in callback form so the server process is actually gone before the
@@ -4613,10 +4792,32 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
                                 /* best-effort */
                             }
                         }
-                        const server = await startAppiumServer(appiumEntry, config, undefined, env);
-                        return { port: server.port, process: server.process };
+                        // Load only this platform's app driver (ADR 01117).
+                        const driverPackage = context?.platform
+                            ? APP_DRIVER_PLATFORMS[context.platform]?.driverPackage
+                            : undefined;
+                        const extraArgs = driverPackage
+                            ? useDriversArgs(appiumHome, [driverPackage])
+                            : [];
+                        const start = async () => {
+                            const server = await startAppiumServer(appiumEntry, config, undefined, env, extraArgs);
+                            return { port: server.port, process: server.process };
+                        };
+                        // iOS contexts share the run's pooled server for this exact launch
+                        // environment and argument list (ADR 01115); teardown releases it
+                        // via `release`. Deliberately a different key from the mobile-web
+                        // site: app servers also carry the ffmpeg PATH, so the two never
+                        // share a server.
+                        const pool = appSession?.appServerPool;
+                        if (pool) {
+                            return pool.acquire(JSON.stringify({ appiumEntry, env, extraArgs }), start);
+                        }
+                        return start();
                     },
-                    startDriver: (capabilities, port) => driverStart(capabilities, port, 2, { cacheDir: config?.cacheDir }),
+                    startDriver: (capabilities, port) => driverStart(capabilities, port, 2, {
+                        cacheDir: config?.cacheDir,
+                        log: (m) => log(config, "warning", m),
+                    }),
                     // Mobile device acquisition (boot/create-and-boot, or reuse), bound
                     // to the run-level registry stashed on the app session. Android uses
                     // the emulator layer; iOS uses the simctl simulator layer. Both
@@ -4783,7 +4984,9 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
 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) {
+extraArgs, 
+// Node args placed before the entry, e.g. the reuse watchdog (ADR 01125).
+nodeArgs) {
     const port = await findFreePort();
     log(config, "debug", `Starting Appium on port ${port}`);
     // When a virtual display is supplied (Linux Xvfb recording), launch the
@@ -4798,7 +5001,15 @@ extraArgs) {
             ...(extraEnv ?? {}),
         }
         : process.env;
-    const proc = spawn(process.execPath, [appiumEntry, "-a", "127.0.0.1", "-p", String(port), ...(extraArgs ?? [])], {
+    const proc = spawn(process.execPath, [
+        ...(nodeArgs ?? []),
+        appiumEntry,
+        "-a",
+        "127.0.0.1",
+        "-p",
+        String(port),
+        ...(extraArgs ?? []),
+    ], {
         windowsHide: true,
         cwd: path.join(__dirname, "../.."),
         env,
@@ -4808,6 +5019,8 @@ extraArgs) {
     });
     proc.stdout.on("data", () => { });
     proc.stderr.on("data", () => { });
+    // Overlap webdriverio's ~350 ms import with Appium's boot (ADR 01135).
+    prefetchHeavyDep("webdriverio", { cacheDir: config?.cacheDir });
     return { port, process: proc, display };
 }
 async function startAppiumServer(appiumEntry, config, display, extraEnv, 
@@ -4816,7 +5029,9 @@ async function startAppiumServer(appiumEntry, config, display, extraEnv,
 extraArgs) {
     const server = await spawnAppiumServer(appiumEntry, config, display, extraEnv, extraArgs);
     try {
-        await appiumIsReady(server.port);
+        await appiumIsReady(server.port, undefined, {
+            pollMs: APPIUM_READY_POLL_MS,
+        });
     }
     catch (error) {
         // appiumIsReady threw or timed out — the spawned child is still alive and
@@ -4841,13 +5056,14 @@ const STATUS_PROBE_TIMEOUT_MS = 10000;
 // `probe`/`sleep` are injectable for hermetic unit tests; the overall timeout
 // cap (default 120s) is unchanged.
 async function appiumIsReady(port, timeoutMs = 120000, deps = {}) {
+    const pollMs = deps.pollMs ?? 250;
     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`, {
+                const resp = await (await loadAxios()).get(`http://127.0.0.1:${p}/status`, {
                     timeout: STATUS_PROBE_TIMEOUT_MS,
                 });
                 return resp.status === 200;
@@ -4864,7 +5080,7 @@ async function appiumIsReady(port, timeoutMs = 120000, deps = {}) {
         if (Date.now() - start > timeoutMs) {
             throw new Error(`Appium server on port ${port} failed to start within ${timeoutMs / 1000} seconds`);
         }
-        await sleep(250);
+        await sleep(pollMs);
     }
 }
 // Start the Appium driver specified in `capabilities`.
@@ -4888,19 +5104,23 @@ async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
     let lastError;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         try {
-            // Chromium sessions get a unique free chromedriver port so concurrent
-            // browser contexts never collide on chromedriver's fixed default (9515);
-            // see withChromedriverPort (ADR 01039). A FRESH port is allocated per
+            // Chromium and Gecko sessions get a unique free driver port so
+            // concurrent browser contexts never collide on chromedriver's fixed
+            // default (9515) or geckodriver's lowest-free-in-range pick; see
+            // withDriverPort (ADR 01039, 01105). A FRESH port is allocated per
             // attempt so a retryable ECONNREFUSED — the very rebind-race the Appium
             // path already retries — moves to a new free port instead of re-racing
-            // the same one. Only Chromium caps need a port; every other engine skips
-            // the allocation and keeps a byte-identical wdio.remote payload.
-            const needsChromedriverPort = capabilities?.["appium:automationName"] === "Chromium" &&
-                capabilities?.["appium:chromedriverPort"] === undefined;
-            const attemptCaps = needsChromedriverPort
-                ? withChromedriverPort(capabilities, await findFreePort())
+            // the same one. Engines without a driver port skip the allocation and
+            // keep a byte-identical wdio.remote payload.
+            const attemptCaps = driverPortCapability(capabilities)
+                ? withDriverPort(capabilities, await findFreePort())
                 : capabilities;
-            const driver = await wdio.remote({
+            // Every attempt is reported to the reuse cache: a failed or abandoned
+            // start may still register a session on this server, so it must not be
+            // handed to a later run (ADR 01125).
+            const settle = appiumServerCache.sessionStarting(port);
+            // Start from a resolved promise so a synchronous throw still settles.
+            const driver = await Promise.resolve().then(() => (ctx.remote ?? wdio.remote)({
                 protocol: "http",
                 hostname: "127.0.0.1",
                 port,
@@ -4909,6 +5129,15 @@ async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
                 capabilities: attemptCaps,
                 connectionRetryTimeout: startupCeiling,
                 waitforTimeout: 120000, // 2 minutes
+                // webdriverio 10's `$` throws when a selector matches several
+                // elements. Keep the documented first-match behavior (ADR 01143).
+                strictSelectors: false,
+            })).then((d) => {
+                settle(true);
+                return d;
+            }, (e) => {
+                settle(false);
+                throw e;
             });
             // Per-context mutable state. `recordings` lives here (not on config)
             // so concurrent contexts can't clobber each other's recordings. It is a
@@ -4923,6 +5152,8 @@ async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
             if (!isRetryableSessionError(String(err && err.message), startupCeiling))
                 throw err;
             if (attempt < maxAttempts) {
+                const reason = String(err?.message ?? err).split("\n")[0];
+                ctx.log?.(`Session start attempt ${attempt} of ${maxAttempts} failed (${reason}); retrying.`);
                 await new Promise((r) => setTimeout(r, 500 * attempt));
             }
         }
@@ -5085,7 +5316,15 @@ async function getRunner(options = {}) {
     if (!appiumEntry) {
         throw new Error("appium is not installed. Run `doc-detective install runtime appium` to install it.");
     }
-    const appium = spawn(process.execPath, [appiumEntry, "-a", "127.0.0.1", "-p", String(appiumPort)], {
+    const appium = spawn(process.execPath, [
+        appiumEntry,
+        "-a",
+        "127.0.0.1",
+        "-p",
+        String(appiumPort),
+        // Load only the desktop browser drivers (ADR 01117).
+        ...useDriversArgs(process.env.APPIUM_HOME, browserPoolDriverPackages(process.platform)),
+    ], {
         windowsHide: true,
         cwd: path.join(__dirname, "../.."),
     });
@@ -5095,11 +5334,14 @@ async function getRunner(options = {}) {
     appium.on("error", (err) => {
         log(config, "warning", `Appium process error: ${err?.stack ?? err?.message ?? String(err)}`);
     });
+    prefetchHeavyDep("webdriverio", { cacheDir: config?.cacheDir }); // ADR 01135
     // Wait for Appium to be ready. Same kill-on-throw guard as in
     // runSpecs above — without it, a startup timeout would leave an
     // orphan Appium child holding the ephemeral port.
     try {
-        await appiumIsReady(appiumPort);
+        await appiumIsReady(appiumPort, undefined, {
+            pollMs: APPIUM_READY_POLL_MS,
+        });
     }
     catch (error) {
         try {
@@ -5140,6 +5382,15 @@ async function getRunner(options = {}) {
             throw new Error(`Failed to start Chrome runner: ${error.message}`);
         }
     }
+    // A fresh Chromium session starts parked on its initial blank document
+    // (`data:,`) and sometimes stays there even though `url()` resolved, so the
+    // navigation silently didn't take (ADR 01084, ADR 01088). Steps run through
+    // `runStep` are covered by goTo's guard, but the documented way to drive this
+    // runner is `await runner.url(...)` straight through WebdriverIO, which was
+    // not: the caller got a blank page, and the failure surfaced later as an empty
+    // title or a missing element with nothing pointing at the navigation. Guard
+    // the session's own `url` command so every caller gets the same verification.
+    guardBlankDocumentNavigation(runner, config);
     // Set window size
     try {
         await runner.setWindowSize(width, height);