@react-native-harness/jest 1.5.0 → 1.7.0

package/dist/cli-args.d.ts

@@ -1,6 +1,5 @@
-export type HarnessCliArgs = {
-    harnessRunner?: string;
-    metroPort?: number;
-};
+import { harnessCliOptions } from '@react-native-harness/config';
+import { type InferredOptionTypes } from 'yargs';
+export type HarnessCliArgs = InferredOptionTypes<typeof harnessCliOptions>;
 export declare const getAdditionalCliArgs: () => HarnessCliArgs;
 //# sourceMappingURL=cli-args.d.ts.map

package/dist/cli-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,oBAAoB,QAAO,cAoBvC,CAAC"}
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAGxD,MAAM,MAAM,cAAc,GAAG,mBAAmB,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE3E,eAAO,MAAM,oBAAoB,QAAO,cAcvC,CAAC"}

package/dist/cli-args.js

@@ -1,19 +1,14 @@
+import { harnessCliOptions } from '@react-native-harness/config';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 export const getAdditionalCliArgs = () => {
     const argv = yargs(hideBin(process.argv))
-        .option('harnessRunner', {
-        type: 'string',
-        description: 'Specify which Harness runner to use',
-    })
-        .option('metroPort', {
-        type: 'number',
-        description: 'Override the Metro bundler port',
-    })
+        .options(harnessCliOptions)
         .strict(false)
         .help(false)
         .version(false)
         .exitProcess(false)
+        .fail(false)
         .parseSync();
     return {
         harnessRunner: argv.harnessRunner,

package/dist/diagnostics/index.d.ts

@@ -1,3 +1,6 @@
 export { observeMetroEvents, observeBridgeEvents } from './derivers.js';
-export { writeTraceFile, printSummary } from './report.js';
+export { writeTraceFile, appendToTraceFile, printSummary, createDiagnosticsAppender, summarizeRunKpis, writeSummaryFile, appendStepSummary, } from './report.js';
+export type { DiagnosticsAppender, RunKpis } from './report.js';
+export { startSessionTelemetry } from './telemetry.js';
+export type { SessionTelemetry } from './telemetry.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/diagnostics/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/diagnostics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/diagnostics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,yBAAyB,EACzB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/diagnostics/index.js

@@ -1,2 +1,3 @@
 export { observeMetroEvents, observeBridgeEvents } from './derivers.js';
-export { writeTraceFile, printSummary } from './report.js';
+export { writeTraceFile, appendToTraceFile, printSummary, createDiagnosticsAppender, summarizeRunKpis, writeSummaryFile, appendStepSummary, } from './report.js';
+export { startSessionTelemetry } from './telemetry.js';

package/dist/diagnostics/report.d.ts

@@ -1,7 +1,87 @@
-import type { DiagnosticEntry } from '@react-native-harness/tools';
+import type { DiagnosticEntry, Diagnostics } from '@react-native-harness/tools';
+type TraceEvent = {
+    name: string;
+    ph: 'X' | 'i' | 'C';
+    ts: number;
+    dur?: number;
+    s?: 'g';
+    pid: number;
+    tid: number;
+    args?: Record<string, unknown>;
+};
+export declare const toTraceEvent: (entry: DiagnosticEntry) => TraceEvent;
 export declare const writeTraceFile: (entries: DiagnosticEntry[], options: {
     projectRoot: string;
     runId: string;
 }) => Promise<string>;
+export type DiagnosticsAppender = {
+    readonly filePath: string;
+    /** Synchronously writes everything not yet on disk. For `exit` handlers. */
+    flush(): void;
+    /** Waits for in-flight writes, then writes the rest and detaches. */
+    dispose(): Promise<void>;
+};
+/**
+ * Persists diagnostics entries as they are recorded, one JSON object per line
+ * in `.harness/diagnostics/<id>.jsonl`. The final trace is only written when a
+ * run finishes, so a job that is cancelled or killed mid-run (the case where
+ * the data matters most) would otherwise leave nothing behind.
+ *
+ * Entries are batched (every `flushIntervalMs` or `maxBufferedEntries`) and
+ * appended asynchronously, one write at a time, so recording an entry never
+ * blocks on disk, which matters most when the machine is overloaded. Only the
+ * `exit` handler writes synchronously: a process that is going away cannot
+ * wait for the event loop. The session already owns SIGINT/SIGTERM and leaves
+ * through `process.exit`, which emits `exit`; installing signal handlers here
+ * would depend on listener order and fight other handlers about who re-raises.
+ *
+ * Entries recorded before the appender was created are replayed, so the log
+ * starts at the beginning of the session.
+ */
+export declare const createDiagnosticsAppender: (diagnostics: Diagnostics, options: {
+    projectRoot: string;
+    id: string;
+    flushIntervalMs?: number;
+    maxBufferedEntries?: number;
+}) => DiagnosticsAppender;
+export type RunKpis = {
+    bootWaitMs: number | null;
+    timeToReadyMs: number | null;
+    peakHostCompressedMb: number | null;
+    peakLoad1: number | null;
+    minHostFreeMb: number | null;
+    /** Memory swapped out during the run, in MB. */
+    swapoutsDelta: number | null;
+    maxEventLoopLagMs: number | null;
+    testFileCount: number;
+    result: 'passed' | 'failed' | null;
+};
+/**
+ * Reduces a run's entries to the handful of numbers worth comparing between
+ * runs. Anything that cannot be derived from the entries is null, never a
+ * guess, so a missing probe shows up as "n/a" rather than as a misleading 0.
+ */
+export declare const summarizeRunKpis: (entries: DiagnosticEntry[]) => RunKpis;
+export declare const writeSummaryFile: (kpis: RunKpis, options: {
+    projectRoot: string;
+    runId: string;
+    sessionId?: string;
+}) => Promise<string>;
+/** The KPIs as label/value pairs, in display order. */
+export declare const formatRunKpis: (kpis: RunKpis) => Array<[string, string]>;
+/**
+ * Appends the KPIs as a markdown table to the GitHub Actions job summary when
+ * running there. Best effort: a failure here must never fail the run.
+ */
+export declare const appendStepSummary: (kpis: RunKpis, env?: NodeJS.ProcessEnv) => Promise<void>;
+/**
+ * Adds entries recorded after a run's trace was written (session teardown) to
+ * that trace, or writes a new trace if there is none yet.
+ */
+export declare const appendToTraceFile: (entries: DiagnosticEntry[], options: {
+    projectRoot: string;
+    runId: string;
+}) => Promise<string>;
 export declare const printSummary: (entries: DiagnosticEntry[], log: (line: string) => void) => void;
+export {};
 //# sourceMappingURL=report.d.ts.map

package/dist/diagnostics/report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/diagnostics/report.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAyCnE,eAAO,MAAM,cAAc,GACzB,SAAS,eAAe,EAAE,EAC1B,SAAS;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,KAC9C,OAAO,CAAC,MAAM,CAUhB,CAAC;AAkBF,eAAO,MAAM,YAAY,GACvB,SAAS,eAAe,EAAE,EAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,KAC1B,IA8CF,CAAC"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/diagnostics/report.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAKhF,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,GAAG,CAAC;IACR,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAKF,eAAO,MAAM,YAAY,GAAI,OAAO,eAAe,KAAG,UAmCrD,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,SAAS,eAAe,EAAE,EAC1B,SAAS;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,KAC9C,OAAO,CAAC,MAAM,CAUhB,CAAC;AAKF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,KAAK,IAAI,IAAI,CAAC;IACd,qEAAqE;IACrE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,GACpC,aAAa,WAAW,EACxB,SAAS;IACP,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,KACA,mBAyFF,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gDAAgD;IAChD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;CACpC,CAAC;AAQF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,eAAe,EAAE,KAAG,OA2C7D,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,MAAM,OAAO,EACb,SAAS;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KAClE,OAAO,CAAC,MAAM,CAahB,CAAC;AAQF,uDAAuD;AACvD,eAAO,MAAM,aAAa,GAAI,MAAM,OAAO,KAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAUnE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,OAAO,EACb,MAAK,MAAM,CAAC,UAAwB,KACnC,OAAO,CAAC,IAAI,CAsBd,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,SAAS,eAAe,EAAE,EAC1B,SAAS;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,KAC9C,OAAO,CAAC,MAAM,CAwBhB,CAAC;AAkBF,eAAO,MAAM,YAAY,GACvB,SAAS,eAAe,EAAE,EAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,KAC1B,IAsDF,CAAC"}

package/dist/diagnostics/report.js

@@ -1,9 +1,23 @@
+import fsSync from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { getHarnessRootPath } from '@react-native-harness/tools';
+import { getHarnessRootPath, logger, unrefTimer } from '@react-native-harness/tools';
+const reportLogger = logger.child('diagnostics');
 const TRACE_PID = 1;
 const TRACE_TID = 1;
-const toTraceEvent = (entry) => {
+export const toTraceEvent = (entry) => {
+    if (entry.kind === 'gauge') {
+        // Counter events become graphed tracks in Perfetto / chrome://tracing,
+        // one per distinct name, so each gauge label is its own series.
+        return {
+            name: entry.label,
+            ph: 'C',
+            ts: entry.startTime * 1000,
+            pid: TRACE_PID,
+            tid: TRACE_TID,
+            args: { [entry.label]: entry.value ?? 0 },
+        };
+    }
     if (entry.kind === 'mark') {
         return {
             name: entry.label,
@@ -26,13 +40,213 @@ const toTraceEvent = (entry) => {
     };
 };
 export const writeTraceFile = async (entries, options) => {
-    const dir = path.join(getHarnessRootPath(options.projectRoot), 'diagnostics');
+    const dir = getDiagnosticsDir(options.projectRoot);
     await fs.mkdir(dir, { recursive: true });
     const filePath = path.join(dir, `${options.runId}.json`);
     const trace = { traceEvents: entries.map(toTraceEvent) };
     await fs.writeFile(filePath, JSON.stringify(trace), 'utf-8');
     return filePath;
 };
+const getDiagnosticsDir = (projectRoot) => path.join(getHarnessRootPath(projectRoot), 'diagnostics');
+/**
+ * Persists diagnostics entries as they are recorded, one JSON object per line
+ * in `.harness/diagnostics/<id>.jsonl`. The final trace is only written when a
+ * run finishes, so a job that is cancelled or killed mid-run (the case where
+ * the data matters most) would otherwise leave nothing behind.
+ *
+ * Entries are batched (every `flushIntervalMs` or `maxBufferedEntries`) and
+ * appended asynchronously, one write at a time, so recording an entry never
+ * blocks on disk, which matters most when the machine is overloaded. Only the
+ * `exit` handler writes synchronously: a process that is going away cannot
+ * wait for the event loop. The session already owns SIGINT/SIGTERM and leaves
+ * through `process.exit`, which emits `exit`; installing signal handlers here
+ * would depend on listener order and fight other handlers about who re-raises.
+ *
+ * Entries recorded before the appender was created are replayed, so the log
+ * starts at the beginning of the session.
+ */
+export const createDiagnosticsAppender = (diagnostics, options) => {
+    const filePath = path.join(getDiagnosticsDir(options.projectRoot), `${options.id}.jsonl`);
+    if (!diagnostics.enabled) {
+        return {
+            filePath,
+            flush: () => undefined,
+            dispose: async () => undefined,
+        };
+    }
+    const maxBufferedEntries = options.maxBufferedEntries ?? 100;
+    let buffer = [];
+    // Chunks handed to the async writer and not yet confirmed on disk, kept so
+    // the `exit` handler can write them if the process leaves first. In the
+    // rare race where one was also completed by the writer, a chunk ends up in
+    // the file twice; losing it would be worse for a log whose purpose is
+    // surviving abrupt termination.
+    let pending = [];
+    let writeChain = Promise.resolve();
+    let directoryReady = false;
+    const render = (lines) => `${lines.join('\n')}\n`;
+    const flushAsync = () => {
+        if (buffer.length === 0) {
+            return;
+        }
+        const lines = buffer;
+        buffer = [];
+        pending.push(lines);
+        writeChain = writeChain.then(async () => {
+            try {
+                if (!directoryReady) {
+                    await fs.mkdir(path.dirname(filePath), { recursive: true });
+                    directoryReady = true;
+                }
+                await fs.appendFile(filePath, render(lines), 'utf-8');
+            }
+            catch (error) {
+                reportLogger.debug('failed to append diagnostics: %s', error);
+            }
+            finally {
+                pending = pending.filter((chunk) => chunk !== lines);
+            }
+        });
+    };
+    const flushSync = () => {
+        const lines = [...pending.flat(), ...buffer];
+        pending = [];
+        buffer = [];
+        if (lines.length === 0) {
+            return;
+        }
+        try {
+            fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
+            fsSync.appendFileSync(filePath, render(lines), 'utf-8');
+        }
+        catch (error) {
+            reportLogger.debug('failed to append diagnostics: %s', error);
+        }
+    };
+    const unsubscribe = diagnostics.subscribe((entry) => {
+        buffer.push(JSON.stringify(entry));
+        if (buffer.length >= maxBufferedEntries) {
+            flushAsync();
+        }
+    }, { replay: true });
+    const timer = setInterval(flushAsync, options.flushIntervalMs ?? 2000);
+    unrefTimer(timer);
+    process.on('exit', flushSync);
+    const dispose = async () => {
+        unsubscribe();
+        clearInterval(timer);
+        process.off('exit', flushSync);
+        flushAsync();
+        await writeChain;
+    };
+    return { filePath, flush: flushSync, dispose };
+};
+const maxOf = (values) => values.length > 0 ? Math.max(...values) : null;
+const minOf = (values) => values.length > 0 ? Math.min(...values) : null;
+/**
+ * Reduces a run's entries to the handful of numbers worth comparing between
+ * runs. Anything that cannot be derived from the entries is null, never a
+ * guess, so a missing probe shows up as "n/a" rather than as a misleading 0.
+ */
+export const summarizeRunKpis = (entries) => {
+    const gaugeValues = (label) => entries
+        .filter((entry) => entry.kind === 'gauge' && entry.label === label)
+        .map((entry) => entry.value)
+        .filter((value) => typeof value === 'number');
+    const spans = (label) => entries.filter((entry) => entry.kind === 'span' && entry.label === label);
+    const bootSpans = entries.filter((entry) => entry.kind === 'span' && entry.label.endsWith('.waitForBoot'));
+    const sessionStart = spans('session.config.load')[0]?.startTime;
+    const firstReady = spans('app.ready.total').find((entry) => entry.status === 'ok');
+    const swapouts = gaugeValues('host.mem.swapouts');
+    const runStatus = spans('run.total')[0]?.attrs?.status;
+    return {
+        bootWaitMs: bootSpans.length > 0
+            ? bootSpans.reduce((total, entry) => total + entry.duration, 0)
+            : null,
+        timeToReadyMs: sessionStart !== undefined && firstReady
+            ? firstReady.startTime + firstReady.duration - sessionStart
+            : null,
+        peakHostCompressedMb: maxOf(gaugeValues('host.mem.compressed')),
+        peakLoad1: maxOf(gaugeValues('host.load1')),
+        minHostFreeMb: minOf(gaugeValues('host.mem.free')),
+        swapoutsDelta: swapouts.length >= 2
+            ? swapouts[swapouts.length - 1] - swapouts[0]
+            : null,
+        maxEventLoopLagMs: maxOf(gaugeValues('node.event_loop.max_ms')),
+        testFileCount: spans('run.file').length,
+        result: runStatus === 'passed' || runStatus === 'failed' ? runStatus : null,
+    };
+};
+export const writeSummaryFile = async (kpis, options) => {
+    const dir = getDiagnosticsDir(options.projectRoot);
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, `${options.runId}.summary.json`);
+    const summary = {
+        runId: options.runId,
+        ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+        ...kpis,
+    };
+    await fs.writeFile(filePath, JSON.stringify(summary, null, 2), 'utf-8');
+    return filePath;
+};
+const formatNumber = (value, unit, digits = 0) => value === null ? 'n/a' : `${value.toFixed(digits)}${unit}`;
+const formatKpiDuration = (ms) => ms === null ? 'n/a' : formatDuration(ms);
+/** The KPIs as label/value pairs, in display order. */
+export const formatRunKpis = (kpis) => [
+    ['Result', kpis.result ?? 'n/a'],
+    ['Test files', String(kpis.testFileCount)],
+    ['Boot wait', formatKpiDuration(kpis.bootWaitMs)],
+    ['Time to ready', formatKpiDuration(kpis.timeToReadyMs)],
+    ['Peak host load (1m)', formatNumber(kpis.peakLoad1, '', 1)],
+    ['Peak compressed memory', formatNumber(kpis.peakHostCompressedMb, ' MB')],
+    ['Min free memory', formatNumber(kpis.minHostFreeMb, ' MB')],
+    ['Swapped out during run', formatNumber(kpis.swapoutsDelta, ' MB')],
+    ['Max event loop lag', formatNumber(kpis.maxEventLoopLagMs, ' ms')],
+];
+/**
+ * Appends the KPIs as a markdown table to the GitHub Actions job summary when
+ * running there. Best effort: a failure here must never fail the run.
+ */
+export const appendStepSummary = async (kpis, env = process.env) => {
+    const summaryPath = env.GITHUB_STEP_SUMMARY;
+    if (!summaryPath) {
+        return;
+    }
+    const rows = formatRunKpis(kpis).map(([label, value]) => `| ${label} | ${value} |`);
+    const markdown = [
+        '### Harness run KPIs',
+        '',
+        '| KPI | Value |',
+        '| --- | --- |',
+        ...rows,
+        '',
+        '',
+    ].join('\n');
+    try {
+        await fs.appendFile(summaryPath, markdown, 'utf-8');
+    }
+    catch (error) {
+        reportLogger.debug('failed to write GitHub step summary: %s', error);
+    }
+};
+/**
+ * Adds entries recorded after a run's trace was written (session teardown) to
+ * that trace, or writes a new trace if there is none yet.
+ */
+export const appendToTraceFile = async (entries, options) => {
+    const filePath = path.join(getDiagnosticsDir(options.projectRoot), `${options.runId}.json`);
+    let existing = [];
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, 'utf-8'));
+        existing = parsed.traceEvents ?? [];
+    }
+    catch {
+        // No trace yet (or an unreadable one): start a fresh file.
+    }
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify({ traceEvents: [...existing, ...entries.map(toTraceEvent)] }), 'utf-8');
+    return filePath;
+};
 const formatDuration = (ms) => {
     if (ms >= 1000) {
         return `${(ms / 1000).toFixed(1)}s`;
@@ -46,6 +260,10 @@ export const printSummary = (entries, log) => {
     }
     const statsByLabel = new Map();
     for (const entry of entries) {
+        // Gauges are samples, not timings; they are summarised as KPIs below.
+        if (entry.kind === 'gauge') {
+            continue;
+        }
         const existing = statsByLabel.get(entry.label);
         if (existing) {
             existing.count += 1;
@@ -81,4 +299,8 @@ export const printSummary = (entries, log) => {
             log(`    ${stats.label}: count=${stats.count} total=${formatDuration(stats.totalMs)} max=${formatDuration(stats.maxMs)}`);
         }
     }
+    log('  KPIs');
+    for (const [label, value] of formatRunKpis(summarizeRunKpis(entries))) {
+        log(`    ${label}: ${value}`);
+    }
 };

package/dist/diagnostics/telemetry.d.ts

@@ -0,0 +1,42 @@
+import { createLifecycleEmitter, type Diagnostics, type DiagnosticAttrs, type LifecyclePhase, type HostPressure } from '@react-native-harness/tools';
+import { type Config as HarnessConfig } from '@react-native-harness/config';
+import type { HarnessPlatformRunner } from '@react-native-harness/platforms';
+export type SessionTelemetry = {
+    /** Identifies the session; names the incremental `.jsonl` log. */
+    readonly sessionId: string;
+    /** Session code emits phases here; probes listen. */
+    readonly lifecycle: ReturnType<typeof createLifecycleEmitter>;
+    /** Emits a lifecycle phase. */
+    phase(phase: LifecyclePhase, attrs?: DiagnosticAttrs): void;
+    /** Makes the platform runner available to the platform collector probe. */
+    attachPlatform(platform: HarnessPlatformRunner): void;
+    /** Records the run that is current, so teardown data can join its trace. */
+    trackRun(runId: string): void;
+    /**
+     * Host pressure observed by the host-resources probe so far: peak load,
+     * mean idle CPU, lowest free memory and memory swapped out since the first
+     * sample. Null
+     * when no host sample was taken (diagnostics or the host probe are off).
+     */
+    hostPressure(): HostPressure | null;
+    /** Resolves once lifecycle driven collection started so far has finished. */
+    settled(): Promise<void>;
+    /**
+     * Stops probes and the incremental log. Entries recorded since the last
+     * run's report was written (the end-of-run snapshot, teardown spans) are
+     * added to that run's trace. Safe to call more than once.
+     */
+    dispose(): Promise<void>;
+};
+/**
+ * The single composition point for run telemetry: it wires the incremental
+ * log and the probes to the one diagnostics sink. Session code only emits
+ * lifecycle phases; it never calls a probe. Everything is a no-op, with no
+ * timers, listeners or spawned processes, when diagnostics are disabled.
+ */
+export declare const startSessionTelemetry: ({ diagnostics, config, projectRoot, }: {
+    diagnostics: Diagnostics;
+    config: Pick<HarnessConfig, "diagnostics">;
+    projectRoot: string;
+}) => SessionTelemetry;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/diagnostics/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/diagnostics/telemetry.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,sBAAsB,EAGtB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAEL,KAAK,MAAM,IAAI,aAAa,EAC7B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAK7E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;IAC9D,+BAA+B;IAC/B,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAC5D,2EAA2E;IAC3E,cAAc,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACtD,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;;OAKG;IACH,YAAY,IAAI,YAAY,GAAG,IAAI,CAAC;IACpC,6EAA6E;IAC7E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,uCAInC;IACD,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IAC3C,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,gBAyHH,CAAC"}

package/dist/diagnostics/telemetry.js

@@ -0,0 +1,120 @@
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
+import { logger, createDefaultProbes, createLifecycleEmitter, DEFAULT_SAMPLE_INTERVAL_MS, startTelemetryProbes, } from '@react-native-harness/tools';
+import { resolveDiagnosticsOptions, } from '@react-native-harness/config';
+import { appendToTraceFile, createDiagnosticsAppender } from './report.js';
+const telemetryLogger = logger.child('diagnostics');
+/**
+ * The single composition point for run telemetry: it wires the incremental
+ * log and the probes to the one diagnostics sink. Session code only emits
+ * lifecycle phases; it never calls a probe. Everything is a no-op, with no
+ * timers, listeners or spawned processes, when diagnostics are disabled.
+ */
+export const startSessionTelemetry = ({ diagnostics, config, projectRoot, }) => {
+    const sessionId = randomUUID();
+    const lifecycle = createLifecycleEmitter();
+    const abortController = new AbortController();
+    const options = resolveDiagnosticsOptions(config);
+    let platform;
+    let lastRunId;
+    const appender = createDiagnosticsAppender(diagnostics, {
+        projectRoot,
+        id: sessionId,
+    });
+    const run = startTelemetryProbes(createDefaultProbes({
+        host: options.probes.host,
+        node: options.probes.node,
+        snapshots: options.probes.snapshots,
+        platform: options.probes.platform
+            ? { getCollector: () => platform?.createTelemetryCollector?.() }
+            : undefined,
+    }), {
+        diagnostics,
+        signal: abortController.signal,
+        lifecycle,
+        sampleIntervalMs: options.sampleIntervalMs ?? DEFAULT_SAMPLE_INTERVAL_MS,
+    });
+    // Running aggregates rather than stored samples: a watch-mode session can
+    // live for hours, and only the extremes are needed.
+    let peakLoad1 = null;
+    let idlePctSum = 0;
+    let idlePctSamples = 0;
+    let minHostFreeMb = null;
+    let firstSwapoutsMb = null;
+    let lastSwapoutsMb = null;
+    const unsubscribePressure = diagnostics.subscribe(({ kind, label, value }) => {
+        if (kind !== 'gauge' || typeof value !== 'number') {
+            return;
+        }
+        if (label === 'host.load1') {
+            peakLoad1 = Math.max(peakLoad1 ?? value, value);
+        }
+        else if (label === 'host.cpu.idle_pct') {
+            idlePctSum += value;
+            idlePctSamples += 1;
+        }
+        else if (label === 'host.mem.free') {
+            minHostFreeMb = Math.min(minHostFreeMb ?? value, value);
+        }
+        else if (label === 'host.mem.swapouts') {
+            firstSwapoutsMb ??= value;
+            lastSwapoutsMb = value;
+        }
+    }, { replay: true });
+    const hostPressure = () => peakLoad1 === null && minHostFreeMb === null && lastSwapoutsMb === null
+        ? null
+        : {
+            peakLoad1,
+            meanIdlePct: idlePctSamples > 0 ? idlePctSum / idlePctSamples : null,
+            minHostFreeMb,
+            swapoutsDeltaMb: firstSwapoutsMb !== null && lastSwapoutsMb !== null
+                ? lastSwapoutsMb - firstSwapoutsMb
+                : null,
+            cpuCount: os.availableParallelism(),
+        };
+    const phase = (name, attrs) => {
+        if (!diagnostics.enabled) {
+            return;
+        }
+        lifecycle.emit({ type: 'phase', phase: name, attrs });
+    };
+    let disposed = null;
+    return {
+        sessionId,
+        lifecycle,
+        phase,
+        attachPlatform: (runner) => {
+            platform = runner;
+        },
+        trackRun: (runId) => {
+            lastRunId = runId;
+        },
+        hostPressure,
+        settled: run.settled,
+        dispose: () => {
+            disposed ??= (async () => {
+                unsubscribePressure();
+                try {
+                    abortController.abort();
+                    await run.dispose();
+                    if (diagnostics.enabled && lastRunId) {
+                        const leftover = diagnostics.flush();
+                        if (leftover.length > 0) {
+                            await appendToTraceFile(leftover, {
+                                projectRoot,
+                                runId: lastRunId,
+                            });
+                        }
+                    }
+                }
+                catch (error) {
+                    telemetryLogger.debug('failed to finalize diagnostics trace: %s', error);
+                }
+                finally {
+                    await appender.dispose();
+                }
+            })();
+            return disposed;
+        },
+    };
+};

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import { HarnessError } from '@react-native-harness/tools';
+import { HarnessError, type HostPressure } from '@react-native-harness/tools';
 import type { AppCrashDetails } from '@react-native-harness/platforms';
 export { StartupStallError, type StartupStallCode, type StartupStallDetails, } from '@react-native-harness/bundler-metro';
 export declare class NoRunnerSpecifiedError extends HarnessError {
@@ -13,7 +13,9 @@ export declare class InitializationTimeoutError extends HarnessError {
 }
 export declare class PlatformReadyTimeoutError extends HarnessError {
     readonly timeout: number;
-    constructor(timeout: number);
+    readonly hostPressure: HostPressure | null;
+    constructor(timeout: number, hostPressure?: HostPressure | null);
+    get hostStarved(): boolean;
 }
 export declare class MetroPortRangeExhaustedError extends HarnessError {
     readonly initialPort: number;
@@ -40,5 +42,9 @@ export declare class RuntimeDisconnectError extends HarnessError {
     constructor(testFilePath: string, details: RuntimeDisconnectDetails);
     get phase(): NativeCrashPhase;
 }
+export declare class HostSurfaceReplacedError extends HarnessError {
+    readonly testFilePath: string;
+    constructor(testFilePath: string, cause: Error);
+}
 export type HarnessRuntimeFailure = NativeCrashError | RuntimeDisconnectError;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,YAAY,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EACL,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,qCAAqC,CAAC;AAE7C,qBAAa,sBAAuB,SAAQ,YAAY;;CAKvD;AAED,qBAAa,mBAAoB,SAAQ,YAAY;aACvB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAI/C;AAED,qBAAa,0BAA2B,SAAQ,YAAY;;CAK3D;AAED,qBAAa,yBAA0B,SAAQ,YAAY;aAC7B,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAM5C;AAED,qBAAa,4BAA6B,SAAQ,YAAY;aAE1C,WAAW,EAAE,MAAM;aACnB,QAAQ,EAAE,MAAM;gBADhB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM;CAQnC;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,eAAe,GAAG;IACjD,KAAK,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG;IACvD,KAAK,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAmEF,qBAAa,gBAAiB,SAAQ,YAAY;aAE9B,YAAY,EAAE,MAAM;aACpB,OAAO,EAAE,kBAAkB;aAC3B,aAAa,CAAC,EAAE,MAAM;gBAFtB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,kBAAkB,EAC3B,aAAa,CAAC,EAAE,MAAM,YAAA;IAOxC,IAAI,KAAK,qBAER;CACF;AA0BD,qBAAa,sBAAuB,SAAQ,YAAY;aAEpC,YAAY,EAAE,MAAM;aACpB,OAAO,EAAE,wBAAwB;gBADjC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,wBAAwB;IAOnD,IAAI,KAAK,qBAER;CACF;AAED,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,sBAAsB,CAAC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,YAAY,EAEZ,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EACL,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,qCAAqC,CAAC;AAE7C,qBAAa,sBAAuB,SAAQ,YAAY;;CAKvD;AAED,qBAAa,mBAAoB,SAAQ,YAAY;aACvB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAI/C;AAED,qBAAa,0BAA2B,SAAQ,YAAY;;CAK3D;AAkBD,qBAAa,yBAA0B,SAAQ,YAAY;aAEvC,OAAO,EAAE,MAAM;aACf,YAAY,EAAE,YAAY,GAAG,IAAI;gBADjC,OAAO,EAAE,MAAM,EACf,YAAY,GAAE,YAAY,GAAG,IAAW;IAM1D,IAAI,WAAW,IAAI,OAAO,CAEzB;CACF;AAED,qBAAa,4BAA6B,SAAQ,YAAY;aAE1C,WAAW,EAAE,MAAM;aACnB,QAAQ,EAAE,MAAM;gBADhB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM;CAQnC;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,eAAe,GAAG;IACjD,KAAK,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG;IACvD,KAAK,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAmEF,qBAAa,gBAAiB,SAAQ,YAAY;aAE9B,YAAY,EAAE,MAAM;aACpB,OAAO,EAAE,kBAAkB;aAC3B,aAAa,CAAC,EAAE,MAAM;gBAFtB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,kBAAkB,EAC3B,aAAa,CAAC,EAAE,MAAM,YAAA;IAOxC,IAAI,KAAK,qBAER;CACF;AA0BD,qBAAa,sBAAuB,SAAQ,YAAY;aAEpC,YAAY,EAAE,MAAM;aACpB,OAAO,EAAE,wBAAwB;gBADjC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,wBAAwB;IAOnD,IAAI,KAAK,qBAER;CACF;AAID,qBAAa,wBAAyB,SAAQ,YAAY;aAC5B,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAK/D;AAED,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,sBAAsB,CAAC"}