@react-native-harness/jest 1.3.0 → 1.4.0

package/dist/harness-session.js

@@ -1,53 +1,116 @@
-import { createHarnessBridge, } from '@react-native-harness/bridge/server';
+import { createHarnessBridge, AppBridgeDisconnectedError, } from '@react-native-harness/bridge/server';
 import { HARNESS_BRIDGE_PATH, } from '@react-native-harness/bridge';
-import { getMetroInstance, isMetroCacheReusable, waitForMetroBackedAppReady, } from '@react-native-harness/bundler-metro';
+import { createHarnessCache } from '@react-native-harness/cache';
+import { getMetroInstance, waitForMetroBackedAppReady, } from '@react-native-harness/bundler-metro';
 import { createHarnessPluginManager, } from '@react-native-harness/plugins';
-import { logger, createCrashArtifactWriter, getTimeoutSignal, raceAbortSignals, } from '@react-native-harness/tools';
-import { getConfig, ConfigSchema, } from '@react-native-harness/config';
+import { createCrashArtifactWriter, createDiagnostics, logger, getTimeoutSignal, ensureSignalsDeliverable, waitForAbort, } from '@react-native-harness/tools';
+import { getConfig, isDiagnosticsEnabled, resolveMetroCacheEnabled, ConfigSchema, } from '@react-native-harness/config';
 import { preRunMessage } from 'jest-util';
+import path from 'node:path';
 import { PlatformReadyTimeoutError } from './errors.js';
 import { NoRunnerSpecifiedError, RunnerNotFoundError } from './errors.js';
 import { createCrashMonitor } from './crash-monitor.js';
+import { createProcessResetStrategy, createRuntimeResetStrategy, resolveResetStrategyKind, withEscalation, } from './environment-reset.js';
 import { createHookQueue } from './hook-queue.js';
 import { createClientLogCollector, } from './client-log-handler.js';
 import { createActionHooksPlugin } from './action-hooks.js';
 import { createResourceLockManager, } from './resource-lock.js';
+import { observeBridgeEvents, observeMetroEvents } from './diagnostics/index.js';
 import { resolveHarnessMetroPort } from './metro-port.js';
 import { getAdditionalCliArgs } from './cli-args.js';
 import { logMetroCacheReused, logMetroPortFallback, logNativeCoverageCollected, logRunnerStarting, logRunnerStillWaitingInQueue, logRunnerWaitingInQueue, logTestEnvironmentReady, logTestRunHeader, } from './logs.js';
 const sessionLogger = logger.child('runtime');
 const defaultResourceLockManager = createResourceLockManager();
 const ignorePromiseRejection = () => undefined;
+const isBridgeDisconnectError = (error) => error instanceof Error && error.message === 'App bridge disconnected';
+const TEST_RUN_BRIDGE_STABILITY_WAIT_MS = 500;
+export const waitForBridgeDisconnectOrTimeout = async ({ bridge, connection, timeoutMs, }) => {
+    if (bridge.connection !== connection) {
+        return true;
+    }
+    return await new Promise((resolve) => {
+        const onDisconnected = () => {
+            cleanup();
+            resolve(true);
+        };
+        const cleanup = () => {
+            clearTimeout(timer);
+            bridge.off('disconnected', onDisconnected);
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve(bridge.connection !== connection);
+        }, timeoutMs);
+        bridge.on('disconnected', onDisconnected);
+    });
+};
+// Resolves the NEXT time the bridge reports a 'connected' event, rejecting
+// if `signal` aborts first. Deliberately does not use bridge.nextConnection(),
+// which would resolve immediately for a stale, already-set connection.
+export const waitForNextConnected = ({ bridge, signal, }) => new Promise((resolve, reject) => {
+    const onConnected = () => { cleanup(); resolve(); };
+    const onAbort = () => { cleanup(); reject(signal.reason ?? new DOMException('Aborted', 'AbortError')); };
+    const cleanup = () => {
+        bridge.off('connected', onConnected);
+        signal.removeEventListener('abort', onAbort);
+    };
+    if (signal.aborted) {
+        onAbort();
+        return;
+    }
+    bridge.on('connected', onConnected);
+    signal.addEventListener('abort', onAbort, { once: true });
+});
+export const getSignalExitCodeForRunState = (state) => {
+    if (state?.completed &&
+        state.status === 'passed' &&
+        !state.error &&
+        (state.summary?.failed ?? 0) === 0) {
+        return 0;
+    }
+    return 1;
+};
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-const createAbortError = () => new DOMException('The operation was aborted', 'AbortError');
-const waitForAbort = (signal) => {
-    if (signal.aborted) {
-        return Promise.reject(signal.reason ?? createAbortError());
+// Bounds only the init *call* with a readiness timeout; `options.signal` (the
+// session-lifetime signal) is passed to `work` unmodified, so a slow init
+// call keeps observing real session teardown, not a synthetic timeout abort.
+// On timeout this throws PlatformReadyTimeoutError without cancelling `work`
+// itself — the caller is expected to abort the session signal as part of
+// tearing down, which then cancels the still-inflight call cooperatively.
+export const withPlatformReadyTimeout = async (options) => {
+    const timeoutSignal = getTimeoutSignal(options.timeout);
+    const abortWait = waitForAbort(timeoutSignal);
+    try {
+        return await Promise.race([
+            options.work(options.signal),
+            abortWait.promise.catch(() => {
+                throw new PlatformReadyTimeoutError(options.timeout);
+            }),
+        ]);
+    }
+    finally {
+        abortWait.cancel();
     }
-    return new Promise((_, reject) => {
-        signal.addEventListener('abort', () => reject(signal.reason ?? createAbortError()), { once: true });
-    });
 };
-const withPlatformReadyTimeout = async (options) => {
-    const timeoutSignal = getTimeoutSignal(options.timeout);
-    const combinedSignal = raceAbortSignals([options.signal, timeoutSignal]);
+export const waitForStartupCrash = async ({ crashMonitor, detectNativeCrashes, testFilePath, signal, }) => {
+    if (!detectNativeCrashes) {
+        return await waitForAbort(signal).promise;
+    }
+    const watch = crashMonitor.watch(testFilePath, 'startup');
+    watch.promise.catch(ignorePromiseRejection); // suppress unhandled-rejection when abort wins race
+    const abortWait = waitForAbort(signal);
     try {
-        return await options.work(combinedSignal);
+        return await Promise.race([watch.promise, abortWait.promise]);
     }
-    catch (error) {
-        if (error instanceof DOMException &&
-            error.name === 'AbortError' &&
-            timeoutSignal.aborted &&
-            !options.signal.aborted) {
-            throw new PlatformReadyTimeoutError(options.timeout);
-        }
-        throw error;
+    finally {
+        watch.cancel();
+        abortWait.cancel();
     }
 };
 const waitForAppReady = async (base, testFilePath) => {
-    const { metroInstance, bridge, platformInstance, platformId, bundleStartTimeout, readyTimeout, maxAppRestarts, crashMonitor, appLaunchOptions, } = base;
+    const { metroInstance, bridge, platformId, bundleStartTimeout, readyTimeout, maxAppRestarts, crashMonitor, detectNativeCrashes, restartAppSession, } = base;
     const logWait = (message, ...args) => sessionLogger.debug(`waitForAppReady: ${message}`, ...args);
     return await waitForMetroBackedAppReady({
         metro: metroInstance,
@@ -58,7 +121,7 @@ const waitForAppReady = async (base, testFilePath) => {
         signal: new AbortController().signal,
         startAttempt: async () => {
             logWait('launching app for %s', testFilePath);
-            await platformInstance.restartApp(appLaunchOptions);
+            await restartAppSession();
             logWait('launch request completed, waiting for bridge ready');
         },
         waitForReady: async (signal) => {
@@ -68,32 +131,17 @@ const waitForAppReady = async (base, testFilePath) => {
             // is already set. waitForReady is called before startAttempt, so a stale
             // connection from a previous run would resolve the promise before startAttempt
             // even restarts the app — leaving bridge.connection null after the restart.
-            await new Promise((resolve, reject) => {
-                const onConnected = (_conn) => { cleanup(); resolve(); };
-                const onAbort = () => { cleanup(); reject(signal.reason ?? new DOMException('Aborted', 'AbortError')); };
-                const cleanup = () => {
-                    bridge.off('connected', onConnected);
-                    signal.removeEventListener('abort', onAbort);
-                };
-                if (signal.aborted) {
-                    onAbort();
-                    return;
-                }
-                bridge.on('connected', onConnected);
-                signal.addEventListener('abort', onAbort, { once: true });
-            });
+            await waitForNextConnected({ bridge, signal });
             logWait('runtime ready received');
         },
         waitForCrash: async (signal) => {
-            const watch = crashMonitor.watch(testFilePath, 'startup');
-            watch.promise.catch(ignorePromiseRejection); // suppress unhandled-rejection when abort wins race
-            try {
-                logWait('waiting for crash or runtime ready');
-                return await Promise.race([watch.promise, waitForAbort(signal)]);
-            }
-            finally {
-                watch.cancel();
-            }
+            logWait('waiting for crash or runtime ready');
+            return await waitForStartupCrash({
+                crashMonitor,
+                detectNativeCrashes,
+                testFilePath,
+                signal,
+            });
         },
         onAttemptStart: () => {
             logWait('beginning launch attempt for %s', testFilePath);
@@ -150,9 +198,23 @@ const applyEnvVars = (harnessConfig, globalConfig) => {
         process.env.RN_HARNESS_VIEW_FLATTENING = 'false';
     }
 };
+/**
+ * Logs the "Reusing Metro cache" message when persistent Metro caching is
+ * enabled and the cache is warm. `projectRoot` must be the config-resolved
+ * project root so the warmth check looks at the same directory Metro caches
+ * into.
+ */
+export const maybeLogMetroCacheReused = (options) => {
+    if (!resolveMetroCacheEnabled(options.config)) {
+        return;
+    }
+    if (createHarnessCache({ projectRoot: options.projectRoot }).isWarm('metro')) {
+        logMetroCacheReused(options.platform);
+    }
+};
 const loadConfig = async (globalConfig) => {
     const projectRoot = globalConfig.rootDir;
-    const { config: rawConfig } = await getConfig(projectRoot);
+    const { config: rawConfig, projectRoot: configProjectRoot } = await getConfig(projectRoot);
     const cliArgs = getAdditionalCliArgs();
     let harnessConfig = cliArgs.metroPort != null
         ? ConfigSchema.parse({ ...rawConfig, metroPort: cliArgs.metroPort })
@@ -173,29 +235,40 @@ const loadConfig = async (globalConfig) => {
     const platform = harnessConfig.runners.find((r) => r.name === selectedRunnerName);
     if (!platform)
         throw new RunnerNotFoundError(selectedRunnerName);
-    return { harnessConfig, platform, projectRoot };
+    return { harnessConfig, platform, projectRoot, configProjectRoot };
 };
 // ---------------------------------------------------------------------------
 // Session creation
 // ---------------------------------------------------------------------------
 export const createHarnessSession = async (globalConfig, { lockManager = defaultResourceLockManager } = {}) => {
     preRunMessage.remove(process.stderr);
-    const { harnessConfig, platform, projectRoot } = await loadConfig(globalConfig);
+    const setupStartedAt = Date.now();
+    const { harnessConfig, platform, projectRoot, configProjectRoot } = await loadConfig(globalConfig);
     applyEnvVars(harnessConfig, globalConfig);
+    const diagnostics = createDiagnostics({
+        enabled: isDiagnosticsEnabled(harnessConfig),
+    });
+    diagnostics.record({
+        label: 'session.config.load',
+        duration: Date.now() - setupStartedAt,
+    });
     sessionLogger.debug('creating session for runner=%s platform=%s', platform.name, platform.platformId);
-    // Single AbortController for the entire setup phase. Registered signal
-    // handlers abort this so that slow inflight operations (Metro init, platform
-    // runner startup) are cancelled promptly on SIGTERM/SIGINT.
-    const setupController = new AbortController();
-    const onEarlySignal = () => setupController.abort();
+    // Single, session-lifetime AbortController: it aborts on early SIGTERM/SIGINT
+    // during setup (below) and, once the session is up, in dispose()'s finally
+    // (unchanged lifetime). It is the one signal the plugin manager and platform
+    // runner see for the entire session, so its abort reaches every long-lived
+    // child the runner threads it into.
+    ensureSignalsDeliverable();
+    const sessionController = new AbortController();
+    const onEarlySignal = () => sessionController.abort();
     process.once('SIGTERM', onEarlySignal);
     process.once('SIGINT', onEarlySignal);
     const resourceLockKey = await (platform.getResourceLockKey?.() ?? getDefaultResourceLockKey(platform));
     let didWaitForResourceLock = false;
     let lastStillWaitingLogAt = 0;
     logTestRunHeader(platform);
-    const resourceLease = await lockManager.acquire(resourceLockKey, {
-        signal: setupController.signal,
+    const resourceLease = await diagnostics.measure('session.lock.wait', () => lockManager.acquire(resourceLockKey, {
+        signal: sessionController.signal,
         onWait: () => {
             didWaitForResourceLock = true;
             logRunnerWaitingInQueue(platform);
@@ -208,7 +281,7 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
             logRunnerStillWaitingInQueue(platform);
             sessionLogger.debug('still waiting in queue for runner=%s key=%s elapsedMs=%d', platform.name, resourceLockKey, elapsedMs);
         },
-    });
+    }), { lockKey: resourceLockKey });
     if (didWaitForResourceLock)
         logRunnerStarting(platform);
     sessionLogger.debug('resource lock acquired for runner=%s key=%s', platform.name, resourceLockKey);
@@ -216,90 +289,147 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
     // port resolution but before the inner try/catch (e.g. bridge creation failure).
     let metroPortLease = null;
     try {
-        const resolution = await resolveHarnessMetroPort({
-            config: harnessConfig,
-            platform,
-            resourceLockManager: lockManager,
-            signal: setupController.signal,
+        const portResolveSpan = diagnostics.start('session.port.resolve');
+        let resolution;
+        try {
+            resolution = await resolveHarnessMetroPort({
+                config: harnessConfig,
+                platform,
+                resourceLockManager: lockManager,
+                signal: sessionController.signal,
+            });
+        }
+        catch (error) {
+            portResolveSpan.fail(error);
+            throw error;
+        }
+        portResolveSpan.end({
+            port: resolution.config.metroPort,
+            didFallback: resolution.didFallback,
         });
         metroPortLease = resolution.metroPortLease;
         const { config: runtimeConfig, initialMetroPort, didFallback } = resolution;
         if (didFallback)
             logMetroPortFallback(initialMetroPort, runtimeConfig.metroPort);
-        if (runtimeConfig.unstable__enableMetroCache && isMetroCacheReusable(projectRoot)) {
-            logMetroCacheReused(platform);
-        }
-        const pluginAbortController = new AbortController();
+        maybeLogMetroCacheReused({
+            config: runtimeConfig,
+            projectRoot: configProjectRoot,
+            platform,
+        });
         const pluginManager = createHarnessPluginManager({
             plugins: (runtimeConfig.plugins ?? []),
             projectRoot,
             config: runtimeConfig,
             runner: platform,
-            abortSignal: pluginAbortController.signal,
+            abortSignal: sessionController.signal,
         });
         const hooks = createHookQueue();
         let currentRun = null;
         const getCurrentRunId = () => currentRun?.runId;
         const clientLogCollector = createClientLogCollector();
         const context = { platform };
-        const bridge = await createHarnessBridge({
+        const crashArtifactWriter = createCrashArtifactWriter({
+            runnerName: platform.name,
+            platformId: platform.platformId,
+            rootDir: path.join(projectRoot, '.harness', 'crash-reports'),
+        });
+        const bridge = await diagnostics.measure('session.bridge.init', () => createHarnessBridge({
             noServer: true,
             timeout: runtimeConfig.bridgeTimeout,
             context,
-        });
+        }));
         sessionLogger.debug('bridge initialized on Metro websocket path %s', HARNESS_BRIDGE_PATH);
         let metroInstance;
         let platformInstance;
+        // Noop until the Metro instance resolves and the deriver is attached.
+        let disposeMetroDiagnostics = () => undefined;
         try {
             [metroInstance, platformInstance] = await Promise.all([
-                getMetroInstance({
+                diagnostics.measure('metro.init', () => getMetroInstance({
                     projectRoot,
                     harnessConfig: runtimeConfig,
                     websocketEndpoints: {
                         [HARNESS_BRIDGE_PATH]: bridge.ws,
                     },
-                }, setupController.signal).then((instance) => {
+                    watchMode: globalConfig.watch || globalConfig.watchAll,
+                }, sessionController.signal).then((instance) => {
                     sessionLogger.debug('Metro initialized');
+                    // Attach the Metro diagnostics deriver before the eager prewarm
+                    // fires so its bundle build/request events land in the trace.
+                    disposeMetroDiagnostics = observeMetroEvents(instance.events, diagnostics);
+                    if (runtimeConfig.eagerPrewarm !== false) {
+                        // Kick off the first bundle build while the platform is still booting.
+                        // prewarm() memoizes this first call, so its session-lifetime setup
+                        // signal is the one that matters — later callers' signals cannot
+                        // cancel it. Not awaited: metro.init must resolve immediately.
+                        const prewarmSpan = diagnostics.start('metro.prewarm');
+                        instance
+                            .prewarm({
+                            platform: platform.platformId,
+                            signal: sessionController.signal,
+                        })
+                            .then((completed) => prewarmSpan.end({ completed }))
+                            // Swallow AbortError on teardown so it never becomes an
+                            // unhandled rejection; non-abort failures resolve false.
+                            .catch((error) => prewarmSpan.fail(error));
+                    }
                     return instance;
-                }),
-                withPlatformReadyTimeout({
+                })),
+                diagnostics.measure('platform.init', () => withPlatformReadyTimeout({
                     timeout: runtimeConfig.platformReadyTimeout,
-                    signal: setupController.signal,
+                    signal: sessionController.signal,
                     work: async (signal) => {
                         return await import(platform.runner).then((module) => module.default(platform.config, runtimeConfig, {
                             signal,
+                            crashArtifactWriter,
+                            diagnostics,
                         })).then((instance) => {
                             sessionLogger.debug('platform runner initialized');
                             return instance;
                         });
                     },
-                }),
+                }), { runner: platform.runner, platformId: platform.platformId }),
             ]);
         }
         catch (error) {
-            // Only bridge needs cleanup here; leases are released by the outer catch.
+            // Only bridge and the Metro diagnostics listener need cleanup here;
+            // leases are released by the outer catch.
+            disposeMetroDiagnostics();
             await bridge.dispose();
             throw error;
         }
-        const crashArtifactWriter = createCrashArtifactWriter({
-            runnerName: platform.name,
-            platformId: platform.platformId,
-        });
-        const appMonitor = platformInstance.createAppMonitor({ crashArtifactWriter });
         const appLaunchOptions = platform.config.appLaunchOptions;
-        const crashMonitor = createCrashMonitor({ appMonitor, platformRunner: platformInstance });
+        let currentAppSession = null;
+        const crashMonitor = createCrashMonitor();
+        const disposeCurrentAppSession = async () => {
+            const session = currentAppSession;
+            currentAppSession = null;
+            crashMonitor.setAppSession(null);
+            if (session) {
+                await session.dispose();
+            }
+        };
+        const restartAppSession = async () => {
+            await crashMonitor.stop();
+            await disposeCurrentAppSession();
+            const session = await diagnostics.measure('app.session.create', () => platformInstance.createAppSession(appLaunchOptions));
+            currentAppSession = session;
+            crashMonitor.setAppSession(session);
+            await crashMonitor.start();
+            return session;
+        };
         // Pre-build the options that are constant across all app-ready calls;
         // only testFilePath varies per call.
         const appReadyBaseOptions = {
             metroInstance,
             bridge,
-            platformInstance,
             platformId: platform.platformId,
             bundleStartTimeout: runtimeConfig.bundleStartTimeout ?? 60000,
             readyTimeout: runtimeConfig.bridgeTimeout,
             maxAppRestarts: runtimeConfig.maxAppRestarts ?? 2,
             crashMonitor,
-            appLaunchOptions,
+            detectNativeCrashes: runtimeConfig.detectNativeCrashes !== false,
+            restartAppSession,
         };
         // --- Event listeners ---
         const bridgeEventListener = buildBridgeHookScheduler(hooks, pluginManager, getCurrentRunId);
@@ -311,6 +441,17 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
         };
         const flushClientLogs = () => clientLogCollector.flush();
         const clientLogListener = clientLogCollector.handleEvent;
+        const testRunnerEventListeners = new Set();
+        const onTestRunnerEvent = (event) => {
+            if (event.type === 'test-started' ||
+                event.type === 'test-finished' ||
+                event.type === 'suite-started' ||
+                event.type === 'suite-finished' ||
+                event.type === 'file-started' ||
+                event.type === 'file-finished') {
+                testRunnerEventListeners.forEach((listener) => listener(event));
+            }
+        };
         const onConnected = (conn) => {
             const runId = getCurrentRunId();
             if (!runId)
@@ -322,19 +463,25 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
             if (!runId)
                 return;
             hooks.schedule(() => pluginManager.callHook('runtime:disconnected', { runId, reason: 'bridge-disconnected' }));
+            if (runtimeConfig.detectNativeCrashes !== false) {
+                crashMonitor.handleBridgeDisconnect();
+            }
         };
         bridge.on('connected', onConnected);
         bridge.on('disconnected', onDisconnected);
         bridge.on('event', bridgeEventListener);
+        bridge.on('event', onTestRunnerEvent);
         metroInstance.events.addListener(onMetroEvent);
         if (runtimeConfig.forwardClientLogs) {
             metroInstance.events.addListener(clientLogListener);
         }
+        const disposeBridgeDiagnostics = observeBridgeEvents(bridge, diagnostics);
         sessionLogger.debug('registered runtime, bridge, and Metro listeners');
         // --- Dispose ---
         let disposePromise = null;
         const disposeOnce = async (reason) => {
             sessionLogger.debug('disposing session (reason=%s)', reason);
+            const disposeSpan = diagnostics.start('dispose.total', { reason });
             let hookError;
             try {
                 await hooks.drain();
@@ -365,10 +512,14 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
             bridge.off('connected', onConnected);
             bridge.off('disconnected', onDisconnected);
             bridge.off('event', bridgeEventListener);
+            bridge.off('event', onTestRunnerEvent);
+            disposeMetroDiagnostics();
+            disposeBridgeDiagnostics();
             const nativeCoverageConfig = runtimeConfig.coverage?.native?.ios;
             if (nativeCoverageConfig?.pods?.length && platformInstance.collectNativeCoverage) {
                 try {
-                    await platformInstance.stopApp();
+                    await crashMonitor.stop();
+                    await disposeCurrentAppSession();
                     const lcovPath = await platformInstance.collectNativeCoverage({
                         pods: nativeCoverageConfig.pods,
                         outputDir: projectRoot,
@@ -383,8 +534,13 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
             }
             let cleanupError;
             try {
+                // The app session (and its logcat/device log stream) must be fully
+                // torn down before the platform is disposed: platform disposal can
+                // shut down the device/emulator, and doing that concurrently with
+                // the app session's own cleanup races the device's log stream
+                // against the device disappearing out from under it.
+                await Promise.all([crashMonitor.dispose(), disposeCurrentAppSession()]);
                 await Promise.all([
-                    crashMonitor.dispose(),
                     bridge.dispose(),
                     platformInstance.dispose(),
                     metroInstance.dispose(),
@@ -396,13 +552,18 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
             }
             finally {
                 await resourceLease.release();
-                pluginAbortController.abort();
+                sessionController.abort();
             }
             sessionLogger.debug('session resources disposed');
-            if (hookError)
+            if (hookError) {
+                disposeSpan.fail(hookError);
                 throw hookError;
-            if (cleanupError)
+            }
+            if (cleanupError) {
+                disposeSpan.fail(cleanupError);
                 throw cleanupError;
+            }
+            disposeSpan.end();
         };
         const dispose = (reason = 'normal') => {
             disposePromise ??= disposeOnce(reason);
@@ -412,15 +573,16 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
         // that all infrastructure is up.
         process.off('SIGTERM', onEarlySignal);
         process.off('SIGINT', onEarlySignal);
-        const onSignal = () => void dispose('abort').then(() => process.exit(0));
+        const onSignal = () => {
+            const exitCode = getSignalExitCodeForRunState(currentRun);
+            void dispose('abort').then(() => process.exit(exitCode), () => process.exit(1));
+        };
         process.once('SIGTERM', onSignal);
         process.once('SIGINT', onSignal);
         // --- Startup hooks ---
         try {
             await pluginManager.callHook('harness:before-creation', { appLaunchOptions });
             await hooks.drain();
-            await appMonitor.start();
-            sessionLogger.debug('app monitor started');
             await pluginManager.callHook('harness:before-run', { appLaunchOptions });
             await hooks.drain();
         }
@@ -431,38 +593,112 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
             throw error;
         }
         logTestEnvironmentReady(platform);
+        diagnostics.record({
+            label: 'session.setup',
+            duration: Date.now() - setupStartedAt,
+        });
         sessionLogger.debug('session ready');
         // --- Public API ---
         const ensureAppReady = async (testFilePath) => {
             await hooks.drain();
             sessionLogger.debug('ensuring app is ready for %s', testFilePath);
-            if (crashMonitor.isAlive() && bridge.connection !== null && await platformInstance.isAppRunning()) {
-                sessionLogger.debug('reusing existing ready app for %s', testFilePath);
-                return;
+            const appReadySpan = diagnostics.start('app.ready.total');
+            if (crashMonitor.isAlive() && bridge.connection !== null && currentAppSession) {
+                const state = await currentAppSession.getState();
+                if (state.status === 'running') {
+                    sessionLogger.debug('reusing existing ready app for %s', testFilePath);
+                    appReadySpan.end({ file: testFilePath, reused: true });
+                    return;
+                }
             }
             crashMonitor.reset();
             sessionLogger.debug('app not ready, waiting for launch and runtime readiness');
-            await waitForAppReady(appReadyBaseOptions, testFilePath);
+            try {
+                await waitForAppReady(appReadyBaseOptions, testFilePath);
+            }
+            catch (error) {
+                appReadySpan.fail(error, { file: testFilePath, reused: false });
+                throw error;
+            }
             await hooks.drain();
             sessionLogger.debug('app is ready for %s', testFilePath);
+            appReadySpan.end({ file: testFilePath, reused: false });
         };
-        const restartApp = async (testFilePath) => {
-            await hooks.drain();
+        // Shared by restartApp (crash/timeout recovery) and the 'process' reset
+        // strategy: kill the current app session and either wait for a fresh one
+        // to become ready for testFilePath, or (no testFilePath) just launch one.
+        const performRestart = async (testFilePath) => {
             await crashMonitor.stop();
-            sessionLogger.debug('restarting app (testFile=%s mode=%s)', testFilePath ?? 'n/a', testFilePath ? 'stop-and-ensure-ready' : 'direct-restart');
+            await disposeCurrentAppSession();
             if (testFilePath) {
-                await platformInstance.stopApp();
+                await ensureAppReady(testFilePath);
             }
             else {
-                await platformInstance.restartApp(appLaunchOptions);
+                const session = await platformInstance.createAppSession(appLaunchOptions);
+                currentAppSession = session;
+                crashMonitor.setAppSession(session);
+                crashMonitor.reset();
+                await crashMonitor.start();
             }
-            crashMonitor.reset();
-            await crashMonitor.start();
-            if (testFilePath) {
-                await ensureAppReady(testFilePath);
+        };
+        const restartApp = async (testFilePath) => {
+            await hooks.drain();
+            const reason = testFilePath
+                ? 'stop-and-ensure-ready'
+                : 'direct-restart';
+            sessionLogger.debug('restarting app (testFile=%s mode=%s)', testFilePath ?? 'n/a', reason);
+            const restartSpan = diagnostics.start('app.restart', { reason });
+            try {
+                await performRestart(testFilePath);
+                await hooks.drain();
+                sessionLogger.debug('restart completed');
+                restartSpan.end();
+            }
+            catch (error) {
+                restartSpan.fail(error);
+                throw error;
+            }
+        };
+        const processResetStrategy = createProcessResetStrategy({
+            restart: performRestart,
+        });
+        const runtimeResetStrategy = createRuntimeResetStrategy({
+            getConnection: () => bridge.connection,
+            expectDisconnect: crashMonitor.expectDisconnect,
+            waitForReconnect: (signal) => waitForNextConnected({ bridge, signal }),
+            // Pending rpc.invoke calls reject with AppBridgeDisconnectedError when
+            // the app connection drops (see bridge server's disconnect()).
+            isDisconnectError: (error) => error instanceof AppBridgeDisconnectedError,
+            timeoutMs: runtimeConfig.bundleStartTimeout ?? 60000,
+        });
+        const resetEnvironment = async (testFilePath) => {
+            const requestedKind = resolveResetStrategyKind(runtimeConfig.resetEnvironmentBetweenTestFiles);
+            if (requestedKind === null) {
+                return;
             }
             await hooks.drain();
-            sessionLogger.debug('restart completed');
+            sessionLogger.debug('resetting environment (testFile=%s kind=%s)', testFilePath, requestedKind);
+            let escalated = false;
+            const strategy = requestedKind === 'runtime'
+                ? withEscalation(runtimeResetStrategy, processResetStrategy, {
+                    onEscalate: (error) => {
+                        escalated = true;
+                        sessionLogger.debug('runtime reset failed, escalating to process restart: %s', error);
+                    },
+                })
+                : processResetStrategy;
+            const resetSpan = diagnostics.start('app.reset', { requested: requestedKind });
+            const performed = () => (escalated ? 'process' : requestedKind);
+            try {
+                await strategy.reset({ testFilePath });
+                await hooks.drain();
+                sessionLogger.debug('environment reset completed');
+                resetSpan.end({ performed: performed(), escalated });
+            }
+            catch (error) {
+                resetSpan.fail(error, { performed: performed(), escalated });
+                throw error;
+            }
         };
         const runTestFile = async (testPath, options) => {
             await hooks.drain();
@@ -470,7 +706,7 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
             if (!conn)
                 throw new Error('No active app connection');
             sessionLogger.debug('running test file on client: %s', testPath);
-            if (!runtimeConfig.detectNativeCrashes) {
+            if (runtimeConfig.detectNativeCrashes === false) {
                 const result = await conn.runTests(testPath, { ...options, runner: platform.runner });
                 await hooks.drain();
                 return result;
@@ -480,13 +716,30 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
             // crash wins the race or cancel() is called after the test run wins.
             crashWatch.promise.catch(ignorePromiseRejection);
             try {
-                const result = await Promise.race([
-                    conn.runTests(testPath, { ...options, runner: platform.runner }),
-                    crashWatch.promise,
-                ]);
+                const testRunPromise = conn.runTests(testPath, {
+                    ...options,
+                    runner: platform.runner,
+                });
+                const result = await Promise.race([testRunPromise, crashWatch.promise]);
+                const bridgeDisconnected = await waitForBridgeDisconnectOrTimeout({
+                    bridge,
+                    connection: conn,
+                    timeoutMs: TEST_RUN_BRIDGE_STABILITY_WAIT_MS,
+                });
+                if (bridgeDisconnected) {
+                    return await crashWatch.promise;
+                }
                 await hooks.drain();
                 return result;
             }
+            catch (error) {
+                if (isBridgeDisconnectError(error)) {
+                    const result = await crashWatch.promise;
+                    await hooks.drain();
+                    return result;
+                }
+                throw error;
+            }
             finally {
                 crashWatch.cancel();
             }
@@ -494,29 +747,44 @@ export const createHarnessSession = async (globalConfig, { lockManager = default
         return {
             config: runtimeConfig,
             context,
+            diagnostics,
+            onTestRunnerEvent: (listener) => {
+                testRunnerEventListeners.add(listener);
+                return () => {
+                    testRunnerEventListeners.delete(listener);
+                };
+            },
             runTestFile,
             ensureAppReady,
             restartApp,
+            resetEnvironment,
             resetCrashState: () => crashMonitor.reset(),
             flushClientLogs,
             callHook: async (name, payload) => {
                 await hooks.drain();
-                await pluginManager.callHook(name, payload);
+                await diagnostics.measure('plugin.hook', () => pluginManager.callHook(name, payload), { hook: String(name) });
                 await hooks.drain();
             },
             setRunState: (state) => {
                 currentRun = state;
             },
-            dispose: (reason = 'normal') => {
-                process.off('SIGTERM', onSignal);
-                process.off('SIGINT', onSignal);
-                return dispose(reason);
+            dispose: async (reason = 'normal') => {
+                try {
+                    await dispose(reason);
+                }
+                finally {
+                    process.off('SIGTERM', onSignal);
+                    process.off('SIGINT', onSignal);
+                }
             },
         };
     }
     catch (error) {
         process.off('SIGTERM', onEarlySignal);
         process.off('SIGINT', onEarlySignal);
+        // Cancels any inflight init work still holding sessionController.signal
+        // (e.g. a platform init call abandoned after a readiness timeout race).
+        sessionController.abort();
         await Promise.allSettled([resourceLease.release(), metroPortLease?.release()]);
         throw error;
     }