@react-native-harness/jest 1.4.0-rc.1 → 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';
@@ -18,9 +19,9 @@ import {
   type HarnessPlatformInitOptions,
   type HarnessPlatformRunner,
 } from '@react-native-harness/platforms';
+import { createHarnessCache } from '@react-native-harness/cache';
 import {
   getMetroInstance,
-  isMetroCacheReusable,
   waitForMetroBackedAppReady,
   type MetroInstance,
   type MetroWebSocketEndpoint,
@@ -36,12 +37,17 @@ import {
 } from '@react-native-harness/plugins';
 import {
   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';
@@ -51,6 +57,12 @@ 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,
@@ -62,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 {
@@ -121,12 +134,35 @@ export const waitForBridgeDisconnectOrTimeout = async ({
   });
 };
 
+// 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;
   readonly startTime: number;
   readonly testFiles: string[];
   readonly watchMode: boolean;
   readonly coverageEnabled: boolean;
+  readonly completed?: boolean;
   readonly summary?: HarnessRunSummary;
   readonly status?: HarnessRunStatus;
   readonly error?: unknown;
@@ -137,10 +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'];
@@ -148,45 +186,47 @@ 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();
   }
 };
 
@@ -214,15 +254,17 @@ export const waitForStartupCrash = async ({
   signal: AbortSignal;
 }) => {
   if (!detectNativeCrashes) {
-    return await waitForAbort(signal);
+    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, waitForAbort(signal)]);
+    return await Promise.race([watch.promise, abortWait.promise]);
   } finally {
     watch.cancel();
+    abortWait.cancel();
   }
 };
 
@@ -264,17 +306,7 @@ 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 = () => { 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) => {
@@ -358,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
@@ -393,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 };
 };
 
 // ---------------------------------------------------------------------------
@@ -406,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);
 
@@ -429,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);
@@ -452,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();
@@ -488,49 +573,83 @@ export const createHarnessSession = async (
       rootDir: path.join(projectRoot, '.harness', 'crash-reports'),
     });
 
-    const bridge = await createHarnessBridge({
-      noServer: true,
-      timeout: runtimeConfig.bridgeTimeout,
-      context,
-    });
+    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,
-                crashArtifactWriter,
-              } 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;
     }
@@ -552,7 +671,9 @@ export const createHarnessSession = async (
     const restartAppSession = async (): Promise<AppSession> => {
       await crashMonitor.stop();
       await disposeCurrentAppSession();
-      const session = await platformInstance.createAppSession(appLaunchOptions);
+      const session = await diagnostics.measure('app.session.create', () =>
+        platformInstance.createAppSession(appLaunchOptions)
+      );
       currentAppSession = session;
       crashMonitor.setAppSession(session);
       await crashMonitor.start();
@@ -625,6 +746,8 @@ export const createHarnessSession = async (
       metroInstance.events.addListener(clientLogListener);
     }
 
+    const disposeBridgeDiagnostics = observeBridgeEvents(bridge, diagnostics);
+
     sessionLogger.debug('registered runtime, bridge, and Metro listeners');
 
     // --- Dispose ---
@@ -633,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 {
@@ -665,6 +789,8 @@ export const createHarnessSession = async (
       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) {
@@ -685,9 +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(),
-          disposeCurrentAppSession(),
           bridge.dispose(),
           platformInstance.dispose(),
           metroInstance.dispose(),
@@ -697,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') => {
@@ -715,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);
 
@@ -734,6 +877,10 @@ export const createHarnessSession = async (
     }
 
     logTestEnvironmentReady(platform);
+    diagnostics.record({
+      label: 'session.setup',
+      duration: Date.now() - setupStartedAt,
+    });
     sessionLogger.debug('session ready');
 
     // --- Public API ---
@@ -741,31 +888,35 @@ export const createHarnessSession = async (
     const ensureAppReady = async (testFilePath: string): Promise<void> => {
       await hooks.drain();
       sessionLogger.debug('ensuring app is ready for %s', testFilePath);
+      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?: string): Promise<void> => {
-      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?: string): Promise<void> => {
       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) {
@@ -777,9 +928,84 @@ export const createHarnessSession = async (
         crashMonitor.reset();
         await crashMonitor.start();
       }
+    };
 
+    const restartApp = async (testFilePath?: string): Promise<void> => {
       await hooks.drain();
-      sessionLogger.debug('restart completed');
+      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',
+        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: string): Promise<void> => {
+      const requestedKind = resolveResetStrategyKind(
+        runtimeConfig.resetEnvironmentBetweenTestFiles,
+      );
+      if (requestedKind === null) {
+        return;
+      }
+
+      await hooks.drain();
+      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 (
@@ -835,6 +1061,7 @@ export const createHarnessSession = async (
     return {
       config: runtimeConfig,
       context,
+      diagnostics,
       onTestRunnerEvent: (listener) => {
         testRunnerEventListeners.add(listener);
         return () => {
@@ -844,25 +1071,36 @@ export const createHarnessSession = async (
       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;
   }