@react-native-harness/jest 1.3.0 → 1.4.0

package/src/harness-session.ts

@@ -1,5 +1,6 @@
 import {
   createHarnessBridge,
+  AppBridgeDisconnectedError,
   type HarnessBridge,
   type AppConnection,
 } from '@react-native-harness/bridge/server';
@@ -7,18 +8,20 @@ import {
   HARNESS_BRIDGE_PATH,
   type HarnessContext,
   type BridgeEvents,
+  type TestRunnerEvents,
   type TestExecutionOptions,
   type TestSuiteResult,
 } from '@react-native-harness/bridge';
 import {
   type AppLaunchOptions,
+  type AppSession,
   type HarnessPlatform,
   type HarnessPlatformInitOptions,
   type HarnessPlatformRunner,
 } from '@react-native-harness/platforms';
+import { createHarnessCache } from '@react-native-harness/cache';
 import {
   getMetroInstance,
-  isMetroCacheReusable,
   waitForMetroBackedAppReady,
   type MetroInstance,
   type MetroWebSocketEndpoint,
@@ -33,21 +36,33 @@ import {
   type HarnessRunSummary,
 } from '@react-native-harness/plugins';
 import {
-  logger,
   createCrashArtifactWriter,
+  createDiagnostics,
+  logger,
   getTimeoutSignal,
-  raceAbortSignals,
+  ensureSignalsDeliverable,
+  waitForAbort,
+  type Diagnostics,
 } from '@react-native-harness/tools';
 import {
   getConfig,
+  isDiagnosticsEnabled,
+  resolveMetroCacheEnabled,
   type Config as HarnessConfig,
   ConfigSchema,
 } from '@react-native-harness/config';
 import type { Config as JestConfig } from 'jest-runner';
 import { preRunMessage } from 'jest-util';
+import path from 'node:path';
 import { PlatformReadyTimeoutError } from './errors.js';
 import { NoRunnerSpecifiedError, RunnerNotFoundError } from './errors.js';
 import { createCrashMonitor, type CrashMonitor } from './crash-monitor.js';
+import {
+  createProcessResetStrategy,
+  createRuntimeResetStrategy,
+  resolveResetStrategyKind,
+  withEscalation,
+} from './environment-reset.js';
 import { createHookQueue, type HookQueue } from './hook-queue.js';
 import {
   createClientLogCollector,
@@ -59,6 +74,7 @@ import {
   type ResourceLockManager,
   type ResourceLease,
 } from './resource-lock.js';
+import { observeBridgeEvents, observeMetroEvents } from './diagnostics/index.js';
 import { resolveHarnessMetroPort } from './metro-port.js';
 import { getAdditionalCliArgs } from './cli-args.js';
 import {
@@ -75,6 +91,70 @@ import {
 const sessionLogger = logger.child('runtime');
 const defaultResourceLockManager = createResourceLockManager();
 const ignorePromiseRejection = () => undefined;
+const isBridgeDisconnectError = (error: unknown) =>
+  error instanceof Error && error.message === 'App bridge disconnected';
+const TEST_RUN_BRIDGE_STABILITY_WAIT_MS = 500;
+
+type DisconnectObservableBridge = {
+  readonly connection: AppConnection | null;
+  on: (event: 'disconnected', listener: () => void) => void;
+  off: (event: 'disconnected', listener: () => void) => void;
+};
+
+export const waitForBridgeDisconnectOrTimeout = async ({
+  bridge,
+  connection,
+  timeoutMs,
+}: {
+  bridge: DisconnectObservableBridge;
+  connection: AppConnection;
+  timeoutMs: number;
+}): Promise<boolean> => {
+  if (bridge.connection !== connection) {
+    return true;
+  }
+
+  return await new Promise<boolean>((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,
+}: {
+  bridge: Pick<HarnessBridge, 'on' | 'off'>;
+  signal: AbortSignal;
+}): Promise<void> =>
+  new Promise<void>((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 type HarnessRunState = {
   readonly runId: string;
@@ -82,6 +162,7 @@ export type HarnessRunState = {
   readonly testFiles: string[];
   readonly watchMode: boolean;
   readonly coverageEnabled: boolean;
+  readonly completed?: boolean;
   readonly summary?: HarnessRunSummary;
   readonly status?: HarnessRunStatus;
   readonly error?: unknown;
@@ -92,9 +173,12 @@ export type HarnessRunTestsOptions = Exclude<TestExecutionOptions, 'platform'>;
 export type HarnessSession = {
   readonly config: HarnessConfig;
   readonly context: HarnessContext;
+  readonly diagnostics: Diagnostics;
+  onTestRunnerEvent: (listener: (event: TestRunnerEvents) => void) => () => void;
   runTestFile: (path: string, options: HarnessRunTestsOptions) => Promise<TestSuiteResult>;
   ensureAppReady: (testFilePath: string) => Promise<void>;
   restartApp: (testFilePath?: string) => Promise<void>;
+  resetEnvironment: (testFilePath: string) => Promise<void>;
   resetCrashState: () => void;
   flushClientLogs: () => ClientLogBuffer;
   callHook: HarnessPluginManager<HarnessConfig, HarnessPlatform>['callHook'];
@@ -102,58 +186,86 @@ export type HarnessSession = {
   dispose: (reason?: 'normal' | 'abort' | 'error') => Promise<void>;
 };
 
+export const getSignalExitCodeForRunState = (
+  state: HarnessRunState | null
+): number => {
+  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: AbortSignal): Promise<never> => {
-  if (signal.aborted) {
-    return Promise.reject(signal.reason ?? createAbortError());
-  }
-  return new Promise((_, reject) => {
-    signal.addEventListener(
-      'abort',
-      () => reject(signal.reason ?? createAbortError()),
-      { once: true },
-    );
-  });
-};
-
-const withPlatformReadyTimeout = async <T>(options: {
+// 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 <T>(options: {
   timeout: number;
   signal: AbortSignal;
   work: (signal: AbortSignal) => Promise<T>;
 }): Promise<T> => {
   const timeoutSignal = getTimeoutSignal(options.timeout);
-  const combinedSignal = raceAbortSignals([options.signal, timeoutSignal]);
+  const abortWait = waitForAbort(timeoutSignal);
   try {
-    return await options.work(combinedSignal);
-  } catch (error) {
-    if (
-      error instanceof DOMException &&
-      error.name === 'AbortError' &&
-      timeoutSignal.aborted &&
-      !options.signal.aborted
-    ) {
-      throw new PlatformReadyTimeoutError(options.timeout);
-    }
-    throw error;
+    return await Promise.race([
+      options.work(options.signal),
+      abortWait.promise.catch(() => {
+        throw new PlatformReadyTimeoutError(options.timeout);
+      }),
+    ]);
+  } finally {
+    abortWait.cancel();
   }
 };
 
 type AppReadyOptions = {
   metroInstance: MetroInstance;
   bridge: HarnessBridge;
-  platformInstance: HarnessPlatformRunner;
   platformId: string;
   bundleStartTimeout: number;
   readyTimeout: number;
   maxAppRestarts: number;
   crashMonitor: CrashMonitor;
-  appLaunchOptions?: AppLaunchOptions;
+  detectNativeCrashes: boolean;
+  restartAppSession: () => Promise<AppSession>;
+};
+
+export const waitForStartupCrash = async ({
+  crashMonitor,
+  detectNativeCrashes,
+  testFilePath,
+  signal,
+}: {
+  crashMonitor: CrashMonitor;
+  detectNativeCrashes: boolean;
+  testFilePath: string;
+  signal: AbortSignal;
+}) => {
+  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 Promise.race([watch.promise, abortWait.promise]);
+  } finally {
+    watch.cancel();
+    abortWait.cancel();
+  }
 };
 
 const waitForAppReady = async (
@@ -163,13 +275,13 @@ const waitForAppReady = async (
   const {
     metroInstance,
     bridge,
-    platformInstance,
     platformId,
     bundleStartTimeout,
     readyTimeout,
     maxAppRestarts,
     crashMonitor,
-    appLaunchOptions,
+    detectNativeCrashes,
+    restartAppSession,
   } = base;
 
   const logWait = (message: string, ...args: unknown[]) =>
@@ -184,7 +296,7 @@ const waitForAppReady = async (
     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) => {
@@ -194,28 +306,17 @@ const waitForAppReady = async (
       // 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<void>((resolve, reject) => {
-        const onConnected = (_conn: AppConnection) => { 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);
@@ -289,13 +390,37 @@ const applyEnvVars = (
   }
 };
 
+/**
+ * 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: {
+  config: Pick<HarnessConfig, 'cache' | 'unstable__enableMetroCache'>;
+  projectRoot: string;
+  platform: HarnessPlatform;
+}): void => {
+  if (!resolveMetroCacheEnabled(options.config)) {
+    return;
+  }
+
+  if (
+    createHarnessCache({ projectRoot: options.projectRoot }).isWarm('metro')
+  ) {
+    logMetroCacheReused(options.platform);
+  }
+};
+
 const loadConfig = async (globalConfig: JestConfig.GlobalConfig): Promise<{
   harnessConfig: HarnessConfig;
   platform: HarnessPlatform;
   projectRoot: string;
+  configProjectRoot: string;
 }> => {
   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
@@ -324,7 +449,7 @@ const loadConfig = async (globalConfig: JestConfig.GlobalConfig): Promise<{
   const platform = harnessConfig.runners.find((r) => r.name === selectedRunnerName);
   if (!platform) throw new RunnerNotFoundError(selectedRunnerName);
 
-  return { harnessConfig, platform, projectRoot };
+  return { harnessConfig, platform, projectRoot, configProjectRoot };
 };
 
 // ---------------------------------------------------------------------------
@@ -337,20 +462,32 @@ export const createHarnessSession = async (
 ): Promise<HarnessSession> => {
   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);
 
@@ -360,20 +497,25 @@ export const createHarnessSession = async (
 
   logTestRunHeader(platform);
 
-  const resourceLease = await lockManager.acquire(resourceLockKey, {
-    signal: setupController.signal,
-    onWait: () => {
-      didWaitForResourceLock = true;
-      logRunnerWaitingInQueue(platform);
-      sessionLogger.debug('waiting in queue for runner=%s key=%s', platform.name, resourceLockKey);
-    },
-    onStillWaiting: (elapsedMs) => {
-      if (elapsedMs - lastStillWaitingLogAt < 5000) return;
-      lastStillWaitingLogAt = elapsedMs;
-      logRunnerStillWaitingInQueue(platform);
-      sessionLogger.debug('still waiting in queue for runner=%s key=%s elapsedMs=%d', platform.name, resourceLockKey, elapsedMs);
-    },
-  });
+  const resourceLease = await diagnostics.measure(
+    'session.lock.wait',
+    () =>
+      lockManager.acquire(resourceLockKey, {
+        signal: sessionController.signal,
+        onWait: () => {
+          didWaitForResourceLock = true;
+          logRunnerWaitingInQueue(platform);
+          sessionLogger.debug('waiting in queue for runner=%s key=%s', platform.name, resourceLockKey);
+        },
+        onStillWaiting: (elapsedMs) => {
+          if (elapsedMs - lastStillWaitingLogAt < 5000) return;
+          lastStillWaitingLogAt = elapsedMs;
+          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);
@@ -383,28 +525,40 @@ export const createHarnessSession = async (
   let metroPortLease: ResourceLease | null = null;
 
   try {
-    const resolution = await resolveHarnessMetroPort({
-      config: harnessConfig,
-      platform,
-      resourceLockManager: lockManager,
-      signal: setupController.signal,
+    const portResolveSpan = diagnostics.start('session.port.resolve');
+    let resolution: Awaited<ReturnType<typeof resolveHarnessMetroPort>>;
+    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);
-    }
+    maybeLogMetroCacheReused({
+      config: runtimeConfig,
+      projectRoot: configProjectRoot,
+      platform,
+    });
 
-    const pluginAbortController = new AbortController();
     const pluginManager = createHarnessPluginManager<HarnessConfig, HarnessPlatform>({
       plugins: (runtimeConfig.plugins ?? []) as Array<HarnessPlugin<object, HarnessConfig, HarnessPlatform>>,
       projectRoot,
       config: runtimeConfig,
       runner: platform,
-      abortSignal: pluginAbortController.signal,
+      abortSignal: sessionController.signal,
     });
 
     const hooks = createHookQueue();
@@ -413,74 +567,131 @@ export const createHarnessSession = async (
     const clientLogCollector = createClientLogCollector();
 
     const context: HarnessContext = { platform };
-
-    const bridge = await createHarnessBridge({
-      noServer: true,
-      timeout: runtimeConfig.bridgeTimeout,
-      context,
+    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: MetroInstance;
     let platformInstance: HarnessPlatformRunner;
+    // Noop until the Metro instance resolves and the deriver is attached.
+    let disposeMetroDiagnostics: () => void = () => undefined;
 
     try {
       [metroInstance, platformInstance] = await Promise.all([
-        getMetroInstance(
-          {
-            projectRoot,
-            harnessConfig: runtimeConfig,
-            websocketEndpoints: {
-              [HARNESS_BRIDGE_PATH]: bridge.ws as unknown as MetroWebSocketEndpoint,
+        diagnostics.measure('metro.init', () =>
+          getMetroInstance(
+            {
+              projectRoot,
+              harnessConfig: runtimeConfig,
+              websocketEndpoints: {
+                [HARNESS_BRIDGE_PATH]: bridge.ws as unknown as MetroWebSocketEndpoint,
+              },
+              watchMode: globalConfig.watch || globalConfig.watchAll,
             },
-          },
-          setupController.signal,
-        ).then((instance) => {
-          sessionLogger.debug('Metro initialized');
-          return instance;
-        }),
-        withPlatformReadyTimeout({
-          timeout: runtimeConfig.platformReadyTimeout,
-          signal: setupController.signal,
-          work: async (signal) => {
-            return await import(platform.runner).then((module) =>
-              module.default(platform.config, runtimeConfig, {
-                signal,
-              } satisfies HarnessPlatformInitOptions),
-            ).then((instance) => {
-              sessionLogger.debug('platform runner initialized');
-              return instance;
-            });
-          },
-        }),
+            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;
+          })
+        ),
+        diagnostics.measure(
+          'platform.init',
+          () =>
+            withPlatformReadyTimeout({
+              timeout: runtimeConfig.platformReadyTimeout,
+              signal: sessionController.signal,
+              work: async (signal) => {
+                return await import(platform.runner).then((module) =>
+                  module.default(platform.config, runtimeConfig, {
+                    signal,
+                    crashArtifactWriter,
+                    diagnostics,
+                  } satisfies HarnessPlatformInitOptions),
+                ).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 as { appLaunchOptions?: AppLaunchOptions }).appLaunchOptions;
 
-    const crashMonitor = createCrashMonitor({ appMonitor, platformRunner: platformInstance });
+    let currentAppSession: AppSession | null = null;
+    const crashMonitor = createCrashMonitor();
+
+    const disposeCurrentAppSession = async () => {
+      const session = currentAppSession;
+      currentAppSession = null;
+      crashMonitor.setAppSession(null);
+      if (session) {
+        await session.dispose();
+      }
+    };
+
+    const restartAppSession = async (): Promise<AppSession> => {
+      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: AppReadyOptions = {
       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 ---
@@ -497,6 +708,19 @@ export const createHarnessSession = async (
     const flushClientLogs = (): ClientLogBuffer => clientLogCollector.flush();
 
     const clientLogListener = clientLogCollector.handleEvent;
+    const testRunnerEventListeners = new Set<(event: TestRunnerEvents) => void>();
+    const onTestRunnerEvent = (event: BridgeEvents) => {
+      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: AppConnection) => {
       const runId = getCurrentRunId();
@@ -508,16 +732,22 @@ export const createHarnessSession = async (
       const runId = getCurrentRunId();
       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 ---
@@ -526,6 +756,7 @@ export const createHarnessSession = async (
 
     const disposeOnce = async (reason: 'normal' | 'abort' | 'error') => {
       sessionLogger.debug('disposing session (reason=%s)', reason);
+      const disposeSpan = diagnostics.start('dispose.total', { reason });
       let hookError: unknown;
 
       try {
@@ -557,11 +788,15 @@ export const createHarnessSession = async (
       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,
@@ -576,8 +811,13 @@ export const createHarnessSession = async (
 
       let cleanupError: unknown;
       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(),
@@ -587,13 +827,20 @@ export const createHarnessSession = async (
         cleanupError = error;
       } finally {
         await resourceLease.release();
-        pluginAbortController.abort();
+        sessionController.abort();
       }
 
       sessionLogger.debug('session resources disposed');
 
-      if (hookError) throw hookError;
-      if (cleanupError) throw cleanupError;
+      if (hookError) {
+        disposeSpan.fail(hookError);
+        throw hookError;
+      }
+      if (cleanupError) {
+        disposeSpan.fail(cleanupError);
+        throw cleanupError;
+      }
+      disposeSpan.end();
     };
 
     const dispose = (reason: 'normal' | 'abort' | 'error' = 'normal') => {
@@ -605,7 +852,13 @@ export const createHarnessSession = async (
     // 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);
 
@@ -614,8 +867,6 @@ export const createHarnessSession = async (
     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();
     } catch (error) {
@@ -626,6 +877,10 @@ export const createHarnessSession = async (
     }
 
     logTestEnvironmentReady(platform);
+    diagnostics.record({
+      label: 'session.setup',
+      duration: Date.now() - setupStartedAt,
+    });
     sessionLogger.debug('session ready');
 
     // --- Public API ---
@@ -633,43 +888,124 @@ export const createHarnessSession = async (
     const ensureAppReady = async (testFilePath: string): Promise<void> => {
       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 });
+    };
+
+    // 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?: string): Promise<void> => {
+      await crashMonitor.stop();
+      await disposeCurrentAppSession();
+
+      if (testFilePath) {
+        await ensureAppReady(testFilePath);
+      } else {
+        const session = await platformInstance.createAppSession(appLaunchOptions);
+        currentAppSession = session;
+        crashMonitor.setAppSession(session);
+        crashMonitor.reset();
+        await crashMonitor.start();
+      }
     };
 
     const restartApp = async (testFilePath?: string): Promise<void> => {
       await hooks.drain();
-      await crashMonitor.stop();
+      const reason: 'stop-and-ensure-ready' | 'direct-restart' = testFilePath
+        ? 'stop-and-ensure-ready'
+        : 'direct-restart';
       sessionLogger.debug(
         'restarting app (testFile=%s mode=%s)',
         testFilePath ?? 'n/a',
-        testFilePath ? 'stop-and-ensure-ready' : 'direct-restart',
+        reason,
       );
+      const restartSpan = diagnostics.start('app.restart', { reason });
 
-      if (testFilePath) {
-        await platformInstance.stopApp();
-      } else {
-        await platformInstance.restartApp(appLaunchOptions);
+      try {
+        await performRestart(testFilePath);
+        await hooks.drain();
+        sessionLogger.debug('restart completed');
+        restartSpan.end();
+      } catch (error) {
+        restartSpan.fail(error);
+        throw error;
       }
+    };
 
-      crashMonitor.reset();
-      await crashMonitor.start();
+    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,
+    });
 
-      if (testFilePath) {
-        await ensureAppReady(testFilePath);
+    const resetEnvironment = async (testFilePath: string): Promise<void> => {
+      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 (
@@ -681,7 +1017,7 @@ export const createHarnessSession = async (
       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;
@@ -692,12 +1028,31 @@ export const createHarnessSession = async (
       // 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();
       }
@@ -706,28 +1061,46 @@ export const createHarnessSession = async (
     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;
   }