Rebuild native crash detection as app lifecycle monitors

[V3RON]

Problem Statement

Harness needs reliable native crash detection across Android, iOS Simulator, and physical iOS devices. The current crash detector should be re-implemented from scratch because the new design needs to be explicit about platform capabilities, easier to test, and less coupled to app launch internals.

From a Harness user's perspective, native crashes should fail the relevant startup or test execution phase quickly, include useful evidence, and avoid false positives when Harness itself intentionally stops or restarts the app. The system should work well on Android and iOS Simulator, while being honest about the more limited realtime guarantees available on physical iOS devices.

The implementation should preserve Harness' existing platform ownership model: Jest orchestrates runs and lifecycle timing, platform packages own platform tool details, and shared packages define only stable contracts.

Solution

Introduce a shared AppLifecycleMonitor contract implemented by each platform. The Jest package will drive this contract linearly during session setup, app launch, restart, stop, startup readiness, test execution, and teardown. Every platform returns a monitor implementation; disabled or unsupported monitoring is represented by a noop monitor rather than optional metadata or conditional checks in Jest.

Platform packages will own evidence collection:

• Android will monitor adb logcat, process state through pidof, and best-effort tombstone/ANR artifacts.
• iOS Simulator will monitor simctl spawn ... log stream, simulator/app state, and host crash reports.
• Physical iOS devices will monitor devicectl JSON process state and crash log artifacts, with heavier fallbacks where needed.

The monitor will distinguish low-latency suspicion from confirmed crash reports. A suspected crash can be raised from logs or process transitions, then confirmed through corroborating evidence such as process exit, crash report files, tombstones, ANR traces, or device crash logs. Crash evidence should be persisted through the existing crash artifact writer so test failures can point to local reports.

User Stories

1. As a Harness user, I want Android Java crashes to fail the active test quickly, so that failures are reported as native crashes instead of bridge timeouts.
2. As a Harness user, I want Android native crashes to include logcat evidence, so that I can diagnose failures without rerunning manually.
3. As a Harness user, I want Android ANRs to be detected when platform evidence is available, so that hangs are not reported only as generic timeouts.
4. As a Harness user, I want iOS Simulator crashes to be detected from simulator logs and crash reports, so that simulator runs fail with actionable native diagnostics.
5. As a Harness user, I want physical iOS device crashes to be detected from official device artifacts, so that device runs can report native failures without relying on unsupported log streams.
6. As a Harness user, I want crash detection to avoid false positives during controlled restarts, so that Harness does not treat its own stopApp calls as crashes.
7. As a Harness user, I want startup crashes to fail during app readiness, so that Harness does not wait for the bridge until timeout when the app has already crashed.
8. As a Harness user, I want execution crashes to fail the currently running test file, so that the failure is attributed to the correct phase.
9. As a Harness user, I want fast provisional detection and later confirmed reports, so that I get low latency without losing diagnostic depth.
10. As a Harness user, I want crash artifacts to be saved locally, so that I can inspect tombstones, ANR traces, logcat windows, or iOS crash reports after the run.
11. As a Harness user, I want monitoring to be togglable, so that I can disable native crash detection without changing the rest of the run flow.
12. As a Harness user, I want disabled monitoring to behave predictably, so that the same Jest orchestration path is used whether monitoring is real or noop.
13. As a Harness maintainer, I want Jest orchestration to stay platform-neutral, so that it does not depend on adb, simctl, or devicectl command details.
14. As a Harness maintainer, I want platform packages to own their evidence collectors, so that platform-specific behavior can evolve independently.
15. As a Harness maintainer, I want a shared monitor interface, so that tests can use fake monitors to verify lifecycle ordering.
16. As a Harness maintainer, I want lifecycle events around launch, stop, and restart, so that monitors can suppress controlled process exits and correlate real launch windows.
17. As a Harness maintainer, I want monitor implementations to use instance keys rather than bare PIDs, so that fast app restarts and PID reuse do not merge unrelated evidence.
18. As a Harness maintainer, I want Android detection to combine logcat and process polling, so that neither noisy logs nor ambiguous process disappearance become the only signal.
19. As a Harness maintainer, I want iOS Simulator detection to combine unified logs and crash report watchers, so that realtime suspicion and file-based confirmation reinforce each other.
20. As a Harness maintainer, I want physical iOS detection to be conservative, so that weak process-loss evidence does not become an unreliable crash failure.
21. As a Harness maintainer, I want warning states for degraded capabilities, so that missing tombstone access or delayed iOS crash logs do not look like monitor bugs.
22. As a Harness maintainer, I want the artifact writer to stay storage-only, so that detection logic remains separate from persistence.
23. As a Harness maintainer, I want monitor tests to use command output fixtures, so that platform parsing can be hardened without requiring live devices in unit tests.
24. As a Harness maintainer, I want end-to-end validation on emulator, simulator, and physical-device paths, so that the implementation reflects real platform behavior.
25. As a plugin author, I want future structured crash events to contain phase and artifact metadata, so that reporting integrations can display useful failure information.
26. As a CI user, I want Android and iOS Simulator crash detection to work in CI-friendly environments, so that native failures are caught automatically.
27. As a CI user with physical iOS devices, I want degraded but official crash retrieval paths, so that device-lab runs can collect evidence when fast crash logs are delayed.
28. As a developer debugging a flaky run, I want duplicate crash signals to be debounced, so that one crash does not produce multiple conflicting failures.
29. As a developer debugging app launch, I want launch IDs or launch windows to appear in monitor correlation, so that startup failures are tied to the correct attempt.
30. As a developer maintaining platform launch code, I want launch mechanics to remain unchanged from the monitor's perspective, so that crash detection does not tightly couple to start command construction.

Implementation Decisions

• Add a shared AppLifecycleMonitor contract with lifecycle notifications, crash watches, reset, start, stop, dispose, and liveness methods.
• Add a noop monitor that implements the full contract and observes nothing.
• Keep monitor creation on the platform runner through createAppMonitor.
• Do not add optional monitorTarget metadata. Platform implementations capture their target identifiers when constructing monitors.
• Preserve detectNativeCrashes as the user-facing toggle by returning either a real monitor or the noop monitor.
• Let Jest drive monitor lifecycle linearly: create, start, notify launch/stop/restart, race watches, reset, stop, dispose.
• Keep platform command details out of Jest.
• Keep adb, simctl, and devicectl usage inside the respective platform packages.
• Use lifecycle events to suppress crashes during controlled stops and restarts.
• Use launch IDs or launch windows to correlate startup and execution crashes.
• Normalize platform evidence into shared crash concepts: suspected crash, confirmed crash, report ready, warning, and monitor error.
• Use confidence levels internally so weak evidence, such as process disappearance alone, can be treated differently from crash reports or fatal log signatures.
• Use instance keys instead of bare PIDs.
• Debounce duplicate signals within a short correlation window.
• Persist crash evidence through the existing artifact writer, but keep the writer out of detection decisions.
• Android monitor implementation should include a logcat session, process poller, and artifact fetcher.
• Android logcat should stream crash, main, and system buffers with threadtime; the events buffer may be added for ANR correlation.
• Android process polling should use pidof and treat process disappearance as neutral unless correlated with crash evidence or exit-reason support.
• Android artifact fetch should opportunistically retrieve tombstones and ANR traces when accessible, treating access failures as warnings.
• iOS Simulator monitor implementation should include a unified log stream, process-state checks, and a host crash report watcher.
• iOS Simulator log streaming should prefer JSON style and fall back to compact style when needed.
• iOS Simulator crash report matching should filter stale reports and confirm the current simulator or launch window.
• Physical iOS monitor implementation should use devicectl JSON-output commands and avoid stdout scraping.
• Physical iOS process checks should match running processes through installed app metadata.
• Physical iOS confirmation should primarily come from matching device crash logs rather than process disappearance alone.
• Physical iOS sysdiagnose collection should be an escalation fallback, not the normal fast path.
• App-assisted Android ApplicationExitInfo and physical iOS heartbeat support are valid future enhancements but are not required for the baseline.
• Monitor warnings should distinguish degraded platform capability from app crash failures.
• The ADR attached in the issue comments is the detailed implementation reference for command shapes and detection flow.

Testing Decisions

• Test external behavior and lifecycle ordering rather than private implementation details.
• Jest orchestration tests should use fake monitors and assert that lifecycle events are emitted around startup, restart, stop, execution, and teardown.
• Jest orchestration tests should verify that disabled monitoring still follows the same code path through a noop monitor.
• Shared monitor tests should cover suspicion windows, confirmation windows, duplicate suppression, controlled-stop suppression, launch correlation, and report assembly.
• Android monitor tests should use logcat fixtures for Java exceptions, native crashes, ANRs, unrelated logs, and noisy device output.
• Android process tests should cover PID disappearance, PID replacement, controlled force-stop, device disconnect, and inaccessible artifact directories.
• iOS Simulator tests should use unified log fixtures and .ips or .crash fixtures for current, stale, and mismatched simulator reports.
• iOS Simulator tests should cover JSON log parsing and compact log fallback.
• Physical iOS tests should use devicectl JSON fixtures for device discovery, app lookup, process listing, crash log listing, and crash log copying.
• Physical iOS tests should cover process disappearance without crash logs, delayed crash log arrival, stale crash logs, and device unplug during artifact retrieval.
• Artifact persistence tests should remain focused on file/text persistence and deduplication.
• End-to-end validation should cover Android Java crash, Android native crash, Android ANR, iOS Simulator fatal error, iOS Simulator abort, physical iOS crash log retrieval, and controlled restart false-positive suppression.

Out of Scope

• Reusing or refactoring the existing crash monitor internals.
• Building a generic cross-platform process-death detector that treats all platforms the same.
• Adding mandatory app instrumentation for the baseline implementation.
• Guaranteeing Android-style realtime crash detection on physical iOS devices.
• Uploading crash artifacts to external services.
• Implementing full symbolication as a required synchronous step.
• Adding retention-policy UI or configuration for crash artifacts.
• Implementing app-assisted Android exit-reason bridge in the baseline unless it naturally falls out as a small optional extension.
• Implementing app-assisted physical iOS heartbeat in the baseline unless it is explicitly prioritized later.

Further Notes

The key architectural rule is: platform adapters may know platform tools; the shared monitor and Jest orchestration may only know lifecycle events, monitor capabilities, normalized evidence, and crash artifacts.

The implementation should be honest about asymmetry:

• Android has the strongest near-realtime path through logcat plus PID correlation.
• iOS Simulator has a strong path through simulator unified logs plus host crash reports.
• Physical iOS devices should use official devicectl JSON and crash artifact retrieval, with conservative realtime assumptions.

The attached ADR contains the detailed interface sketch, dependency chain, shell commands, platform detection logic, artifact policy, migration plan, and open questions.

[V3RON]

ADR 0001: App Lifecycle Crash Monitor

Date: 2026-05-20

Status: Proposed

Context

React Native Harness needs to re-implement native crash detection from scratch. The replacement must be cross-platform, but it must not treat Android, iOS Simulator, and physical iOS devices as equivalent systems. The platform tooling provides different evidence, different latency, and different levels of confidence.

The current Harness launch architecture already has the right high-level shape:

• packages/jest orchestrates Metro, platform runner creation, app readiness, app restarts, test execution, crash races, and teardown.
• packages/platforms defines the shared HarnessPlatformRunner and monitor-facing types.
• packages/platform-android owns Android target resolution and app launch through adb.
• packages/platform-ios owns iOS Simulator launch through simctl and physical-device launch through devicectl.

The new crash monitor should preserve this ownership. The Jest layer may know that an app launch, restart, stop, or test execution phase is happening, but it must not know how adb, simctl, or devicectl work. Platform packages may know platform tools, but they should expose them through a small shared monitor contract.

We also agreed to avoid optional monitor metadata that forces orchestration code to branch. Instead, every platform runner should provide an AppLifecycleMonitor implementation. When monitoring is disabled or unsupported, the platform should return a noop monitor implementing the same interface.

Decision

Implement crash detection as a platform-specific set of AppLifecycleMonitor implementations behind one shared interface.

packages/jest will drive the monitor linearly:

1. Create the platform runner.
2. Create the app monitor.
3. Start the monitor before the run.
4. Notify the monitor around app launch, restart, and stop operations.
5. Race test execution and startup readiness against monitor.watch(...).
6. Stop or reset the monitor around controlled restarts.
7. Dispose the monitor during session teardown.

Platform packages will return concrete monitor implementations:

• Android: AndroidAppLifecycleMonitor
• iOS Simulator: IosSimulatorAppLifecycleMonitor
• iOS physical device: IosDeviceAppLifecycleMonitor
• Disabled or unsupported: NoopAppLifecycleMonitor

The shared monitor contract will be non-optional. The orchestration layer always talks to a monitor. Some monitors observe nothing.

Goals

• Detect native and runtime crashes with low latency when platform tooling supports it.
• Preserve high-confidence confirmation through process state and crash artifacts.
• Keep packages/jest platform-neutral.
• Keep platform command details inside platform packages.
• Keep monitor usage linear, with no optional monitorTarget checks.
• Improve testability by separating lifecycle orchestration, evidence collection, correlation, and artifact persistence.
• Preserve detectNativeCrashes as the user-facing toggle, but implement it by choosing a real or noop monitor.

Non-Goals

• Do not build a single generic "process died means crash" engine.
• Do not make physical iOS devices pretend to have Android-style realtime crash streams.
• Do not require app instrumentation for the baseline implementation.
• Do not couple Jest orchestration to adb, simctl, devicectl, or platform command arguments.
• Do not use the old crash monitor implementation as a design constraint.
• Do not upload raw crash artifacts to external services by default.

Architecture

flowchart TD
    A["packages/jest Harness session"] --> B["HarnessPlatformRunner"]
    A --> C["AppLifecycleMonitor interface"]

    B --> D["platform-android runner"]
    B --> E["platform-ios simulator runner"]
    B --> F["platform-ios device runner"]

    D --> G["AndroidAppLifecycleMonitor"]
    E --> H["IosSimulatorAppLifecycleMonitor"]
    F --> I["IosDeviceAppLifecycleMonitor"]

    G --> J["adb logcat"]
    G --> K["adb shell pidof"]
    G --> L["tombstone / ANR artifact fetch"]

    H --> M["simctl spawn log stream"]
    H --> N["simulator process state"]
    H --> O["host DiagnosticReports watcher"]

    I --> P["devicectl JSON commands"]
    I --> Q["device process state"]
    I --> R["systemCrashLogs artifact fetch"]
    I --> S["sysdiagnose fallback"]

    C --> T["shared correlator"]
    T --> U["crash events"]
    U --> V["CrashArtifactWriter"]

Loading

The shared interface is intentionally small. It models lifecycle notifications, crash watches, and resource management. It does not expose platform-specific command handles.

Shared Interfaces

The exact names may change during implementation, but the shape should remain stable.

export type AppLifecyclePhase = 'startup' | 'execution';

export type AppLifecycleEventBase = {
  launchId: string;
  at: number;
};

export type LaunchRequestedEvent = AppLifecycleEventBase & {
  type: 'launch_requested';
  reason: 'start' | 'restart' | 'ensure_ready';
};

export type LaunchCompletedEvent = AppLifecycleEventBase & {
  type: 'launch_completed';
  reason: 'start' | 'restart' | 'ensure_ready';
};

export type LaunchFailedEvent = AppLifecycleEventBase & {
  type: 'launch_failed';
  reason: 'start' | 'restart' | 'ensure_ready';
  error: unknown;
};

export type StopRequestedEvent = {
  type: 'stop_requested';
  at: number;
  reason: 'restart' | 'dispose' | 'coverage' | 'manual';
};

export type StopCompletedEvent = {
  type: 'stop_completed';
  at: number;
  reason: 'restart' | 'dispose' | 'coverage' | 'manual';
};

export type CrashWatch = {
  promise: Promise<never>;
  cancel: () => void;
};

export type AppLifecycleMonitor = {
  start: () => Promise<void>;
  stop: () => Promise<void>;
  dispose: () => Promise<void>;

  launchRequested: (event: LaunchRequestedEvent) => void;
  launchCompleted: (event: LaunchCompletedEvent) => void;
  launchFailed: (event: LaunchFailedEvent) => void;
  stopRequested: (event: StopRequestedEvent) => void;
  stopCompleted: (event: StopCompletedEvent) => void;

  watch: (testFilePath: string, phase: AppLifecyclePhase) => CrashWatch;
  reset: () => void;
  isAlive: () => boolean;
};

The noop implementation must implement the same contract:

export const createNoopAppLifecycleMonitor = (): AppLifecycleMonitor => ({
  start: async () => undefined,
  stop: async () => undefined,
  dispose: async () => undefined,

  launchRequested: () => undefined,
  launchCompleted: () => undefined,
  launchFailed: () => undefined,
  stopRequested: () => undefined,
  stopCompleted: () => undefined,

  watch: () => ({
    promise: new Promise<never>(() => undefined),
    cancel: () => undefined,
  }),

  reset: () => undefined,
  isAlive: () => true,
});

The platform runner interface should keep a single creation method:

export type CreateAppMonitorOptions = {
  crashArtifactWriter?: CrashArtifactWriter;
};

export type HarnessPlatformRunner = {
  startApp: (options?: AppLaunchOptions) => Promise<void>;
  restartApp: (options?: AppLaunchOptions) => Promise<void>;
  stopApp: () => Promise<void>;
  dispose: () => Promise<void>;
  isAppRunning: () => Promise<boolean>;
  createAppMonitor: (options?: CreateAppMonitorOptions) => AppLifecycleMonitor;
};

There should be no optional monitorTarget property. Target information is captured by the platform implementation when it constructs the monitor.

Platform Monitor Construction

Android platform instances already resolve:

• adbId
• bundleId
• activityName
• appUid

They should construct either:

createAndroidAppLifecycleMonitor({
  adbId,
  bundleId,
  appUid,
  isAppRunning: () => adb.isAppRunning(adbId, bundleId),
  crashArtifactWriter,
});

or a noop monitor when detectNativeCrashes === false.

iOS Simulator platform instances already resolve:

• udid
• bundleId

They should construct either:

createIosSimulatorAppLifecycleMonitor({
  udid,
  bundleId,
  isAppRunning: () => simctl.isAppRunning(udid, bundleId),
  crashArtifactWriter,
});

or a noop monitor when disabled.

iOS physical-device platform instances already resolve:

• CoreDevice deviceId
• hardware udid
• bundleId

They should construct either:

createIosDeviceAppLifecycleMonitor({
  deviceId,
  hardwareUdid: device.hardwareProperties.udid,
  bundleId,
  isAppRunning: () => devicectl.isAppRunning(deviceId, bundleId),
  crashArtifactWriter,
});

or a noop monitor when disabled.

Jest Dependency Chain

The Jest package should remain the lifecycle conductor.

Current dependency chain:

packages/jest
  imports platform runner dynamically
  creates platformInstance
  creates crashArtifactWriter
  creates appMonitor through platformInstance.createAppMonitor()
  starts appMonitor before run
  uses crashMonitor/watch while waiting for readiness and test execution
  stops/resets around restarts
  disposes monitor during session teardown

Target dependency chain:

packages/jest
  depends on:
    packages/platforms types
    platformInstance.createAppMonitor()
    AppLifecycleMonitor methods

packages/platforms
  depends on:
    shared type definitions only

packages/platform-android
  depends on:
    adb helpers
    Android logcat/process/artifact collectors
    shared AppLifecycleMonitor type

packages/platform-ios
  depends on:
    simctl helpers
    devicectl helpers
    iOS log/process/artifact collectors
    shared AppLifecycleMonitor type

packages/tools
  depends on:
    filesystem artifact persistence

packages/jest must not import adb, simctl, or devicectl.

Jest Orchestration Rules

The app lifecycle monitor should receive notifications around all controlled app lifecycle operations.

For direct launch:

const launchId = randomUUID();
monitor.launchRequested({
  type: 'launch_requested',
  launchId,
  at: Date.now(),
  reason: 'start',
});

try {
  await platformInstance.startApp(appLaunchOptions);
  monitor.launchCompleted({
    type: 'launch_completed',
    launchId,
    at: Date.now(),
    reason: 'start',
  });
} catch (error) {
  monitor.launchFailed({
    type: 'launch_failed',
    launchId,
    at: Date.now(),
    reason: 'start',
    error,
  });
  throw error;
}

For restart:

await monitor.stop();

monitor.stopRequested({
  type: 'stop_requested',
  at: Date.now(),
  reason: 'restart',
});

await platformInstance.stopApp();

monitor.stopCompleted({
  type: 'stop_completed',
  at: Date.now(),
  reason: 'restart',
});

monitor.reset();
await monitor.start();

const launchId = randomUUID();
monitor.launchRequested({
  type: 'launch_requested',
  launchId,
  at: Date.now(),
  reason: 'restart',
});

await platformInstance.startApp(appLaunchOptions);

monitor.launchCompleted({
  type: 'launch_completed',
  launchId,
  at: Date.now(),
  reason: 'restart',
});

When the existing platformInstance.restartApp(...) method is used directly, Jest should still emit one logical stop window and one logical launch window around the call:

const launchId = randomUUID();

monitor.stopRequested({ type: 'stop_requested', at: Date.now(), reason: 'restart' });
monitor.launchRequested({ type: 'launch_requested', launchId, at: Date.now(), reason: 'restart' });

try {
  await platformInstance.restartApp(appLaunchOptions);
  monitor.stopCompleted({ type: 'stop_completed', at: Date.now(), reason: 'restart' });
  monitor.launchCompleted({ type: 'launch_completed', launchId, at: Date.now(), reason: 'restart' });
} catch (error) {
  monitor.launchFailed({ type: 'launch_failed', launchId, at: Date.now(), reason: 'restart', error });
  throw error;
}

For test execution:

const crashWatch = monitor.watch(testPath, 'execution');
crashWatch.promise.catch(() => undefined);

try {
  return await Promise.race([
    conn.runTests(testPath, { ...options, runner: platform.runner }),
    crashWatch.promise,
  ]);
} finally {
  crashWatch.cancel();
}

For startup readiness:

const crashWatch = monitor.watch(testPath, 'startup');
crashWatch.promise.catch(() => undefined);

try {
  return await Promise.race([
    waitForBridgeReady(),
    crashWatch.promise,
  ]);
} finally {
  crashWatch.cancel();
}

Shared Detection Model

All real monitors should normalize evidence into the same conceptual model.

type CrashSignal = {
  id: string;
  platform: 'android' | 'ios-simulator' | 'ios-device';
  kind:
    | 'java-exception'
    | 'native-crash'
    | 'anr'
    | 'watchdog'
    | 'process-exit'
    | 'crash-report'
    | 'device-offline'
    | 'unknown';
  confidence: 'low' | 'medium' | 'high';
  occurredAt: number;
  launchId?: string;
  pid?: number;
  processName?: string;
  summary?: string;
  rawLines?: string[];
  artifactPath?: string;
};

The monitor should emit two internal stages:

• crashSuspected: first strong signal, optimized for low latency.
• crashConfirmed: corroborated by process exit, crash artifact, tombstone, ANR trace, or platform exit reason.

The public watch(...) promise should reject with the existing runtime failure shape used by Jest, for example NativeCrashError, once the monitor has enough evidence to report a crash. If a suspected crash is not corroborated, the monitor may keep it as degraded evidence or report a warning, but it should avoid failing tests on weak evidence alone.

Correlation Model

Use an instance key instead of bare PID.

Android instance key:

(adbId, bundleId, pid, firstSeenMonotonic)

iOS Simulator instance key:

(udid, bundleId, launchId or launchEpoch)

iOS device instance key:

(deviceId, bundleId, launchId or crashTimestampBucket)

Correlation rules:

1. Open a suspicion window when the first fatal signal arrives.
2. Collect related evidence for 1 to 3 seconds.
3. Confirm if process loss, restart, exit reason, crash file, tombstone, ANR trace, or device crash log appears.
4. Emit one consolidated crash failure.
5. Suppress duplicates until a new app instance starts or a cooldown expires.

Controlled stops must not be reported as crashes. Jest should call stopRequested before controlled stops, and monitors should suppress process-exit evidence during that window.

Android Commands

The Android launcher currently starts apps with:

adb -s <adbId> shell am start \
  -a android.intent.action.MAIN \
  -c android.intent.category.LAUNCHER \
  -n <bundleId>/<activityName>

Launch extras:

--es <key> <string-value>
--ez <key> true|false
--ei <key> <integer-value>

Controlled stop:

adb -s <adbId> shell am force-stop <bundleId>

Process check:

adb -s <adbId> shell pidof <bundleId>

Realtime crash stream:

adb -s <adbId> logcat -b crash -b main -b system -v threadtime

Optional event buffer:

adb -s <adbId> logcat -b crash -b main -b system -b events -v threadtime

Native tombstone retrieval when accessible:

adb -s <adbId> shell ls -t /data/tombstones
adb -s <adbId> pull /data/tombstones/<tombstone-file> <artifact-dir>

ANR retrieval when accessible:

adb -s <adbId> shell ls -t /data/anr
adb -s <adbId> pull /data/anr/<newest-anr-file> <artifact-dir>

Native symbolication when NDK symbols are configured:

$ANDROID_NDK_HOME/ndk-stack -sym <symbols-dir> -dump <tombstone-or-log-file>

Android Detection Logic

The Android monitor should start a long-lived logcat subprocess and a process poller.

Recommended collectors:

• LogcatSession
• AndroidProcessPoller
• AndroidArtifactFetcher
• optional ApplicationExitInfo app-side bridge later

High-confidence logcat signals:

• tag AndroidRuntime with message containing FATAL EXCEPTION
• debuggerd or tombstone banners
• native abort markers
• visible ActivityManager crash markers
• ANR markers such as am_anr when the events buffer is enabled

Process polling:

• Poll pidof <bundleId> at a modest interval, for example 250 to 500 ms during active test execution.
• Treat PID disappearance as neutral by itself.
• Treat PID disappearance inside a suspicion window as confirming evidence.
• Treat immediate PID replacement as a restart and use the instance key to avoid merging old and new evidence.
• Suppress PID disappearance during a controlled stop window opened by stopRequested.

Suggested Android flow:

onLogcatLine(line) {
  const record = parseThreadtime(line);
  ringBuffer.push(line);

  if (record.tag === 'AndroidRuntime' && record.message.includes('FATAL EXCEPTION')) {
    suspectCrash({ kind: 'java-exception', pid: record.pid, confidence: 'high' });
  }

  if (looksLikeDebuggerdBanner(line) || looksLikeNativeAbort(line)) {
    suspectCrash({ kind: 'native-crash', pid: record.pid, confidence: 'high' });
  }

  if (looksLikeAnrEvent(line)) {
    suspectCrash({ kind: 'anr', confidence: 'medium' });
  }
}

onPidPoll(nextPid) {
  if (controlledStopWindow.isOpen()) {
    updateCurrentPid(nextPid);
    return;
  }

  if (currentPid && !nextPid && suspicionWindow.hasRecentSignal()) {
    confirmCrash({ reason: 'process-exit-after-fatal-signal' });
    fetchFastArtifacts();
    return;
  }

  if (currentPid && !nextPid) {
    recordGoneUnknown();
    fetchExitReasonFallbackIfAvailable();
    return;
  }

  if (!currentPid && nextPid) {
    markAppStarted({ pid: nextPid });
  }
}

Android artifact policy:

• Always persist the relevant logcat ring buffer for confirmed crashes.
• Try tombstones for suspected native crashes.
• Try ANR traces for suspected ANRs.
• Treat artifact fetch failure as a warning, not as a monitor failure, because production devices often block /data/anr and /data/tombstones.

iOS Simulator Commands

Simulator discovery:

xcrun simctl list devices --json

Boot:

xcrun simctl boot <udid>
xcrun simctl bootstatus <udid> -b

Install:

xcrun simctl install <udid> <app-path>

Launch:

xcrun simctl launch <udid> <bundleId> [...arguments]

Launch environment:

SIMCTL_CHILD_<KEY>=<VALUE>

Terminate:

xcrun simctl terminate <udid> <bundleId>

Recommended realtime log stream:

xcrun simctl spawn <udid> log stream \
  --style json \
  --level debug \
  --predicate 'process == "<processName>" OR process == "<bundleId>" OR subsystem == "<bundleId>"'

Fallback stream if JSON style is unavailable:

xcrun simctl spawn <udid> log stream \
  --style compact \
  --level info \
  --predicate '<predicate>'

Simulator diagnostic fallback:

xcrun simctl diagnose --udid=<udid> --no-archive --output=<output-dir> -b

Host crash report location to watch:

~/Library/Logs/DiagnosticReports

iOS Simulator Detection Logic

The simulator monitor should use three signal sources:

• unified log stream through simctl spawn <udid> log stream
• app process state through existing simulator helpers
• host crash report file watcher

Recommended collectors:

• SimctlUnifiedLogStream
• IosSimulatorProcessPoller
• DiagnosticReportsWatcher
• optional SimctlDiagnoseCollector

Signals:

• fatal-looking unified log records
• abort/watchdog/native exception terms in logs
• app process disappearance after a fatal-looking record
• new .ips or .crash report in ~/Library/Logs/DiagnosticReports
• simulator diagnostic bundle containing a matching crash report

Crash report matching:

• Prefer filename prefix matching by process name when available.
• Parse .ips and .crash contents.
• Confirm reports that mention the simulator UDID or otherwise match the current launch time and process.
• Filter reports older than the current launch or current run timestamp.

Suggested iOS Simulator flow:

onSimLogRecord(record) {
  ringBuffer.push(record);

  if (looksFatal(record) || looksAbort(record) || looksWatchdog(record)) {
    suspectCrash({
      platform: 'ios-simulator',
      kind: classifyIosFatal(record),
      confidence: 'medium',
    });
  }
}

onCrashFileCreated(path) {
  const parsed = parseCrashReport(path);

  if (!matchesBundleOrProcess(parsed)) {
    return;
  }

  if (!matchesCurrentSimulator(parsed, udid)) {
    return;
  }

  confirmCrash({
    kind: 'crash-report',
    confidence: 'high',
    artifactPath: persist(path),
  });
}

onProcessPoll(isRunning) {
  if (controlledStopWindow.isOpen()) {
    return;
  }

  if (!isRunning && suspicionWindow.hasRecentSignal()) {
    confirmCrash({ reason: 'process-exit-after-fatal-signal' });
  }
}

The simulator path should usually be able to produce a low-latency crashSuspected event and a high-confidence crashConfirmed event.

iOS Physical Device Commands

Device discovery must use JSON file output:

xcrun devicectl list devices --json-output <temp-json-file>

Device details:

xcrun devicectl device info details \
  --device <deviceId> \
  --json-output <temp-json-file>

Installed app lookup:

xcrun devicectl device info apps \
  --device <deviceId> \
  --bundle-id <bundleId> \
  --json-output <temp-json-file>

Launch:

xcrun devicectl device process launch \
  --device <deviceId> \
  <bundleId> \
  --json-output <temp-json-file>

Launch with environment:

xcrun devicectl device process launch \
  --device <deviceId> \
  --environment-variables '{"KEY":"VALUE"}' \
  <bundleId> \
  --json-output <temp-json-file>

Launch with arguments:

xcrun devicectl device process launch \
  --device <deviceId> \
  <bundleId> \
  --json-output <temp-json-file> \
  -- <arg1> <arg2>

Process list:

xcrun devicectl device info processes \
  --device <deviceId> \
  --json-output <temp-json-file>

Terminate:

xcrun devicectl device process terminate \
  --device <deviceId> \
  --pid <pid> \
  --json-output <temp-json-file>

List crash logs:

xcrun devicectl device info files \
  --device <deviceId> \
  --domain-type systemCrashLogs \
  --recurse \
  --json-output <temp-json-file>

Copy crash log:

xcrun devicectl device copy from \
  --device <deviceId> \
  --source <remote-crash-log-path> \
  --destination <local-output-dir> \
  --domain-type systemCrashLogs \
  --json-output <temp-json-file>

Heavy fallback:

xcrun devicectl device sysdiagnose \
  --device <deviceId> \
  --json-output <temp-json-file>

The command shape should be validated against the locally installed Xcode's xcrun devicectl help. Scripts must consume --json-output files instead of scraping stdout.

iOS Physical Device Detection Logic

Physical iOS device support is intentionally conservative. The monitor should not assume a stable generic realtime crash stream equivalent to Android logcat.

Recommended collectors:

• DevicectlProcessPoller
• IosDeviceCrashLogCollector
• optional DevicectlLaunchResultTracker
• optional DarwinNotificationHeartbeat if an app-assisted heartbeat is added later
• optional DevicectlSysdiagnoseCollector

Signals:

• app process disappears after a launch and outside a controlled stop window
• a matching crash log appears in systemCrashLogs
• devicectl process launch JSON provides launch/process metadata
• optional heartbeat disappears in app-assisted mode
• sysdiagnose contains matching crash reports after escalation

Process matching:

• Get app info for bundleId.
• Use app url from devicectl device info apps.
• List running processes.
• Match processes whose executable starts with the app url.

Suggested physical iOS flow:

onLaunchCompleted(event) {
  currentLaunchId = event.launchId;
  launchCompletedAt = event.at;
  pollProcessSoon();
  scheduleCrashLogSweep({ afterMs: 1000 });
}

onProcessPoll(process) {
  if (controlledStopWindow.isOpen()) {
    return;
  }

  if (lastKnownRunning && !process) {
    suspectCrash({
      platform: 'ios-device',
      kind: 'process-exit',
      confidence: 'low',
    });

    collectCrashLogs({ minOccurredAt: launchCompletedAt });
  }
}

onCrashLogCollected(report) {
  if (!matchesBundleOrProcess(report)) {
    return;
  }

  if (report.occurredAt < launchCompletedAt - toleranceMs) {
    return;
  }

  confirmCrash({
    platform: 'ios-device',
    kind: 'crash-report',
    confidence: 'high',
    artifactPath: persist(report.path),
  });
}

Physical iOS confidence rules:

• Process disappearance alone is low confidence.
• Process disappearance plus matching crash log is high confidence.
• Matching crash log near the current launch window is high confidence even if process polling missed the transition.
• Missing crash logs should produce a degraded warning, not an immediate false crash, unless paired with stronger app-assisted evidence.

Artifact Persistence

CrashArtifactWriter is storage, not detection logic.

It persists file or text evidence into .harness/crash-reports and returns the persisted path:

crashArtifactWriter.persistArtifact({
  artifactKind: 'logcat',
  source: {
    kind: 'text',
    fileName: 'android-crash.log',
    text: logcatWindow,
  },
});

crashArtifactWriter.persistArtifact({
  artifactKind: 'ios-crash-report',
  source: {
    kind: 'file',
    path: reportPath,
  },
});

The monitor should use it for:

• Android logcat windows
• Android tombstones
• Android ANR traces
• iOS .ips or .crash reports
• iOS diagnostic excerpts
• optional symbolicated outputs

The monitor should be able to run without a writer, but reports will be less useful.

Error And Warning Semantics

Monitor infrastructure failures should be separated from app crashes.

Examples of warnings:

• adb logcat restarted after disconnect.
• tombstone directory inaccessible.
• ANR directory inaccessible.
• simctl log stream unavailable in JSON mode, falling back to compact mode.
• physical iOS crash logs not available yet.
• devicectl command shape unsupported by local Xcode.

Examples of monitor errors:

• cannot start required baseline collector
• malformed command output from required JSON interface
• repeated collector restart failure beyond configured backoff

App crash failures should include:

• platform
• target identifier
• phase: startup or execution
• test file path
• summary
• signal or exception type when known
• process name and PID when known
• artifact path when available
• short raw evidence window

Security And Retention

Crash artifacts and logs may contain sensitive data.

The implementation should:

• store artifacts under .harness/crash-reports
• avoid sending raw artifacts outside the local run by default
• deduplicate persisted artifacts
• redact obvious tokens before indexing or displaying summaries
• avoid logging full crash files at normal log levels
• make future retention controls possible

Testing Strategy

Testing should be split by responsibility.

Jest orchestration tests:

• use a fake AppLifecycleMonitor
• assert linear lifecycle ordering
• assert no optional monitor checks are needed
• assert startup readiness races against monitor.watch(..., 'startup')
• assert test execution races against monitor.watch(..., 'execution')
• assert controlled restarts call stop/reset/start in the right order
• assert monitor disposal happens during teardown

Shared monitor tests:

• suspicion window behavior
• duplicate suppression
• controlled stop suppression
• launch ID correlation
• report assembly
• artifact persistence integration through a fake writer

Android monitor tests:

• Java FATAL EXCEPTION logcat fixture
• native debuggerd/tombstone fixture
• ANR event fixture
• PID disappearance without crash signal
• PID disappearance inside suspicion window
• immediate PID replacement
• controlled force-stop
• inaccessible tombstone/ANR directories
• device disconnect and logcat restart

iOS Simulator monitor tests:

• JSON unified log fatal fixture
• compact unified log fallback fixture
• .ips crash report matching current simulator UDID
• stale crash report filtering
• process disappearance after fatal log
• controlled simctl terminate
• simctl diagnose fallback artifact discovery

iOS physical-device monitor tests:

• devicectl JSON command parsing
• app URL based process matching
• process disappearance without crash log
• matching systemCrashLogs report confirmation
• stale crash log filtering
• delayed crash log arrival
• device unplug during artifact copy
• sysdiagnose fallback trigger

End-to-end scenarios:

• Android Java exception
• Android native crash
• Android ANR
• Android user force-stop
• Android app restart
• iOS Simulator fatalError
• iOS Simulator abort()
• iOS Simulator fast relaunch
• physical iOS crash with fast crash log retrieval
• physical iOS crash with delayed crash log retrieval
• physical iOS unplug during retrieval

Migration Plan

1. Add the new shared AppLifecycleMonitor interface and noop implementation in packages/platforms.
2. Update packages/jest to use the lifecycle monitor directly and linearly.
3. Preserve the existing detectNativeCrashes toggle by returning noop monitors when disabled.
4. Implement Android monitor from scratch using logcat, PID polling, and artifact fetchers.
5. Implement iOS Simulator monitor from scratch using simctl log streaming and host crash report watching.
6. Implement iOS physical-device monitor from scratch using devicectl JSON commands, process polling, and crash log retrieval.
7. Add platform fixtures and unit tests for collectors and correlators.
8. Add Jest orchestration tests with a fake monitor.
9. Validate on real Android emulator/device, iOS Simulator, and at least one physical iOS device.
10. Remove old monitor implementation after replacement coverage is in place.

Consequences

Positive:

• Jest orchestration remains platform-neutral.
• The monitor becomes easier to test because lifecycle events can be faked.
• Platform packages retain ownership of platform command details.
• Disabled monitoring uses the same code path through a noop implementation.
• The design can report degraded capability honestly, especially on physical iOS.

Negative:

• More types and lifecycle events are required up front.
• Platform monitors need separate implementations and fixtures.
• Physical iOS detection will remain less immediate than Android and iOS Simulator.
• Some artifact collection paths are best-effort on production devices.

Open Questions

• Should app-assisted Android ApplicationExitInfo be added in the first implementation or as a later enhancement?
• Should app-assisted physical iOS heartbeat via Darwin notification be added in the first implementation or as a later enhancement?
• Should simctl log stream default to --style json immediately, with compact fallback, or keep compact first for compatibility?
• What retention policy should .harness/crash-reports use?
• Should symbolication be synchronous before reportReady or asynchronous after the test has already failed?
• Should monitor warnings be exposed to plugins as structured hook events?

[V3RON]

Open question decisions

Follow-up decisions from the design discussion:

• Treat the app as a black box from the native side. Harness can influence the JavaScript side, but the baseline crash monitor must not require native app changes such as Android ApplicationExitInfo bridges, native crash handlers, or iOS Darwin notification heartbeats.
• Wait for a short 1 to 3 second correlation window before failing a watch, so the monitor can gather related crash evidence and attach better diagnostics.
• For physical iOS devices, process disappearance outside a controlled stop window can eventually fail the active watch, but the monitor should first wait for a matching crash artifact for a bounded grace period. If the artifact takes too long, fail with degraded process-exit evidence and surface the artifact later if it appears.
• Keep .harness/crash-reports append-only for now. Do not clean or expire old crash artifacts in this implementation.
• Update plugin events as part of v1. Plugins should be able to observe possible crashes, confirmed crashes, report readiness, and monitor warnings through structured app-level hooks.

I also updated the local ADR with these decisions.

[V3RON]

Physical iOS artifact experiment update

Additional decisions from the follow-up discussion:

• Symbolication is out of scope for v1. The monitor should persist raw platform artifacts and summarize enough metadata to identify the crash.
• Replace app:possible-crash with a clearer event set: app:crash-suspected, app:crash-confirmed, app:crash-report-ready, and app:monitor-warning.
• Keep the native app black-box requirement. The playground crash hook is valid as a Harness test fixture, but the production monitor must not require app-under-test native changes.

I validated physical iPhone crash-artifact latency with the playground app's DEBUG crash support:

xcrun devicectl device process launch \
  --device <device> \
  --terminate-existing \
  --environment-variables '{"HARNESS_CRASH_MODE":"pre_rn"}' \
  --json-output <launch-json> \
  --log-output <launch-log> \
  --timeout 30 \
  com.harnessplayground

Then I polled systemCrashLogs with:

xcrun devicectl device info files \
  --device <device> \
  --domain-type systemCrashLogs \
  --recurse \
  --json-output <poll-json> \
  --log-output <poll-log> \
  --timeout 30

Observed on 2026-05-20 against a physical iPhone on iOS 26.5 with Xcode 17E202 / devicectl 518.27:

Run	Crash artifact	Time until listed	Copy duration
1	HarnessPlayground-2026-05-20-101009.ips	1623 ms	194 ms
2	HarnessPlayground-2026-05-20-101102.ips	1271 ms	151 ms
3	HarnessPlayground-2026-05-20-101105.ips	1382 ms	453 ms

All copied .ips files contained bundleID / CFBundleIdentifier for com.harnessplayground.

Implementation notes from the experiment:

• devicectl device process launch options must be placed before <bundleId>; values after <bundleId> are app arguments.
• devicectl device copy from for a single crash log should use a full local destination filename, not an existing directory.
• Physical iOS crash artifacts can be available quickly enough for startup crash reporting. Use a 3 second bounded artifact grace window for v1, then fail with degraded process-exit evidence if no matching artifact appears and surface late artifacts later.

The local ADR has been updated with these details.

[V3RON]

iOS Simulator artifact experiment update

I ran the same playground crash experiment on a booted iOS Simulator using the DEBUG crash hook:

SIMCTL_CHILD_HARNESS_CRASH_MODE=pre_rn \
  xcrun simctl launch <udid> com.harnessplayground

Measured signals:

• host PID returned by simctl launch;
• time until that PID disappeared from ps;
• time until HarnessPlayground-*.ips appeared in ~/Library/Logs/DiagnosticReports;
• whether simctl spawn <udid> log stream produced useful crash evidence.

Observed on 2026-05-20 with an iPhone 17 Pro simulator on iOS 26.4.1 / Xcode 17E202:

Run	Mode	PID gone	Crash artifact listed
1	pre_rn, first post-install run	not measured	10943 ms
2	pre_rn	938 ms	2276 ms
3	pre_rn	837 ms	2174 ms
4	delayed_pre_ready	1917 ms	3269 ms

All copied .ips files verified as com.harnessplayground.

simctl spawn <udid> log stream with process/fatal predicates did not produce useful app crash evidence in these runs, so simulator monitoring should treat unified logs as opportunistic context rather than the primary detector for now.

Important operational note: the macOS Problem Reporter dialog appeared saying the app crashed, with Ignore and Report actions. The monitor must not rely on that dialog or require human interaction. It also should not assume the dialog blocks artifact creation; valid .ips files appeared while the dialog was visible.

Design implication:

• For iOS Simulator, process disappearance is the best low-latency suspected-crash signal.
• Host DiagnosticReports is the best confirmation source.
• Use the same initial 3 second artifact grace window, but allow late reportReady because the first post-install run took about 11 seconds.
• Add crash-dialog suppression/dismissal as an implementation/CI hygiene consideration if it becomes disruptive.

[V3RON]

Simulator crash dialog follow-up

I reran the Simulator pre_rn crash while intentionally leaving the macOS Problem Reporter dialog untouched.

Result:

Mode	PID gone	Crash artifact listed	Verified
pre_rn	925 ms	1599 ms	yes, .ips contained com.harnessplayground

This suggests the crash dialog does not block .ips creation, at least on this machine/toolchain. The monitor should still ignore the dialog entirely and rely on PID/process disappearance plus ~/Library/Logs/DiagnosticReports.

[V3RON]

Android emulator crash experiment update

I ran the playground crash experiment on the booted Pixel_8_API_35 emulator.

Launch shape:

adb -s <serial> shell am start \
  -a android.intent.action.MAIN \
  -c android.intent.category.LAUNCHER \
  -n com.harnessplayground/.MainActivity \
  --es harness_crash_mode pre_rn

Measured signals:

• adb shell pidof com.harnessplayground;
• AndroidRuntime / FATAL EXCEPTION in logcat;
• am_crash / Force finishing activity in logcat;
• /data/anr and /data/tombstones accessibility.

Observed on 2026-05-20 with Pixel_8_API_35, Android 15 / API 35, emulator-5554:

Mode	First PID observed	Fatal log after ActivityTaskManager START	PID gone
pre_rn	261 ms	404 ms	531 ms
delayed_pre_ready	259 ms	1599 ms	1812 ms

Other findings:

• am_crash / Force finishing activity appeared for both crashes.
• No new tombstones were created, which is expected for Java/Kotlin exceptions.
• /data/anr and /data/tombstones were accessible on this emulator, but no new ANR/tombstone artifact was relevant to these crash cases.
• Dumped events buffers can contain stale am_crash records if the buffer is not fully cleared or if a monitor starts mid-run. The implementation should correlate by stream position and launch-time window, not just the first matching event line in a dump.

Design implication:

• For Android Java/Kotlin crashes, logcat is the best primary signal.
• PID disappearance is useful corroborating evidence and arrived shortly after the fatal log in these runs.
• Artifact fetch should remain opportunistic: persist the logcat evidence first, then fetch tombstones/ANR traces only when the crash kind calls for them and the paths are accessible.

[V3RON]

Diagnostic detail without symbolication

Clarifying the v1 scope: symbolication is out of scope, but raw stack data is still required.

The monitor should point Harness users toward the problem using the artifacts already available from platform tools:

• Android Java/Kotlin crashes: persist and summarize AndroidRuntime logcat frames, including exception class/message, process/PID, and app frames such as MainActivity.kt:31.
• Android native crashes: persist debuggerd/tombstone text when available, but do not run ndk-stack in v1.
• iOS Simulator / physical iOS crashes: persist .ips / .crash files and extract app name, bundle id, incident id, exception/termination fields, faulting thread, and top frames when present.

No dSYMs, atos, NDK symbols, or source maps are required for v1. Future enrichment can be optional; the first implementation should make crashes actionable using raw platform evidence.

[V3RON]

Physical Android crash experiment

Ran the same playground crash experiment on a connected physical Android device.

Device

• Xiaomi M2101K7BNY, Android 13 / API 33
• Serial: 5LHUBUQWTW6LYXBQ
• Fingerprint: Redmi/rosemary_eea/rosemary:13/TP1A.220624.014/V14.0.11.0.TKLEUXM:user/release-keys
• App: com.harnessplayground, debug APK

Command shape

adb -s 5LHUBUQWTW6LYXBQ shell am start \
  -a android.intent.action.MAIN \
  -c android.intent.category.LAUNCHER \
  -n com.harnessplayground/.MainActivity \
  --es harness_crash_mode pre_rn

Monitoring sources:

adb -s 5LHUBUQWTW6LYXBQ logcat -b crash -b main -b system -b events -v threadtime
adb -s 5LHUBUQWTW6LYXBQ shell pidof com.harnessplayground
adb -s 5LHUBUQWTW6LYXBQ shell ls -t /data/anr
adb -s 5LHUBUQWTW6LYXBQ shell ls -t /data/tombstones

Results

Mode	First PID	Fatal log	am_crash	PID gone	Artifact access
pre_rn	418 ms	829 ms	839 ms	1138 ms	/data/anr listable, /data/tombstones denied
delayed_pre_ready	387 ms	1950 ms	1955 ms	not gone during poll window	/data/anr listable, /data/tombstones denied

The logcat stack excerpts were actionable without symbolication:

• pre_rn: IllegalStateException: Intentional pre-RN startup crash, with app frames at MainActivity.kt:20 and MainActivity.kt:38.
• delayed_pre_ready: IllegalStateException: Intentional delayed startup crash, with an app frame at MainActivity.kt:31.

No ANR files or tombstones were created for these Java/Kotlin crashes, which is expected.

Design implication

For Android Java/Kotlin crashes, AndroidRuntime: FATAL EXCEPTION plus am_crash should be confirmation-grade evidence. PID disappearance is useful corroboration, but it cannot be required: on this physical device the delayed crash left the app PID visible during the polling window, most likely because the system crash dialog kept the crashed process around.

So v1 should persist the relevant logcat ring buffer and summarize exception class/message, process/PID, app stack frames, am_crash, and nearby ActivityManager lines. Tombstone/ANR access remains opportunistic and should produce warnings rather than blocking crash reporting.

[V3RON]

ADR 0001: App Lifecycle Crash Monitor

Date: 2026-05-20

Status: Proposed

Context

React Native Harness needs to re-implement native crash detection from scratch. The replacement must be cross-platform, but it must not treat Android, iOS Simulator, and physical iOS devices as equivalent systems. The platform tooling provides different evidence, different latency, and different levels of confidence.

The current Harness launch architecture already has the right high-level shape:

• packages/jest orchestrates Metro, platform runner creation, app readiness, app restarts, test execution, crash races, and teardown.
• packages/platforms defines the shared HarnessPlatformRunner and monitor-facing types.
• packages/platform-android owns Android target resolution and app launch through adb.
• packages/platform-ios owns iOS Simulator launch through simctl and physical-device launch through devicectl.

The new crash monitor should preserve this ownership. The Jest layer may know that an app launch, restart, stop, or test execution phase is happening, but it must not know how adb, simctl, or devicectl work. Platform packages may know platform tools, but they should expose them through a small shared monitor contract.

We also agreed to avoid optional monitor metadata that forces orchestration code to branch. Instead, every platform runner should provide an AppLifecycleMonitor implementation. When monitoring is disabled or unsupported, the platform should return a noop monitor implementing the same interface.

Decision

Implement crash detection as a platform-specific set of AppLifecycleMonitor implementations behind one shared interface.

packages/jest will drive the monitor linearly:

1. Create the platform runner.
2. Create the app monitor.
3. Start the monitor before the run.
4. Notify the monitor around app launch, restart, and stop operations.
5. Race test execution and startup readiness against monitor.watch(...).
6. Stop or reset the monitor around controlled restarts.
7. Dispose the monitor during session teardown.

Platform packages will return concrete monitor implementations:

• Android: AndroidAppLifecycleMonitor
• iOS Simulator: IosSimulatorAppLifecycleMonitor
• iOS physical device: IosDeviceAppLifecycleMonitor
• Disabled or unsupported: NoopAppLifecycleMonitor

The shared monitor contract will be non-optional. The orchestration layer always talks to a monitor. Some monitors observe nothing.

Goals

• Detect native and runtime crashes with low latency when platform tooling supports it.
• Preserve high-confidence confirmation through process state and crash artifacts.
• Keep packages/jest platform-neutral.
• Keep platform command details inside platform packages.
• Keep monitor usage linear, with no optional monitorTarget checks.
• Improve testability by separating lifecycle orchestration, evidence collection, correlation, and artifact persistence.
• Preserve detectNativeCrashes as the user-facing toggle, but implement it by choosing a real or noop monitor.

Non-Goals

• Do not build a single generic "process died means crash" engine.
• Do not make physical iOS devices pretend to have Android-style realtime crash streams.
• Do not require native app instrumentation for the baseline implementation.
• Do not couple Jest orchestration to adb, simctl, devicectl, or platform command arguments.
• Do not use the old crash monitor implementation as a design constraint.
• Do not upload raw crash artifacts to external services by default.
• Do not rely on native app changes such as Android ApplicationExitInfo bridges or iOS Darwin notification heartbeats in the baseline. The app should be treated as a black box from the native side.
• Do not perform symbolication in v1. Persist raw platform artifacts and summarize them enough to identify the crash.

Architecture

flowchart TD
    A["packages/jest Harness session"] --> B["HarnessPlatformRunner"]
    A --> C["AppLifecycleMonitor interface"]

    B --> D["platform-android runner"]
    B --> E["platform-ios simulator runner"]
    B --> F["platform-ios device runner"]

    D --> G["AndroidAppLifecycleMonitor"]
    E --> H["IosSimulatorAppLifecycleMonitor"]
    F --> I["IosDeviceAppLifecycleMonitor"]

    G --> J["adb logcat"]
    G --> K["adb shell pidof"]
    G --> L["tombstone / ANR artifact fetch"]

    H --> M["simctl spawn log stream"]
    H --> N["simulator process state"]
    H --> O["host DiagnosticReports watcher"]

    I --> P["devicectl JSON commands"]
    I --> Q["device process state"]
    I --> R["systemCrashLogs artifact fetch"]
    I --> S["sysdiagnose fallback"]

    C --> T["shared correlator"]
    T --> U["crash events"]
    U --> V["CrashArtifactWriter"]

Loading

The shared interface is intentionally small. It models lifecycle notifications, crash watches, and resource management. It does not expose platform-specific command handles.

Shared Interfaces

The exact names may change during implementation, but the shape should remain stable.

export type AppLifecyclePhase = 'startup' | 'execution';

export type AppLifecycleEventBase = {
  launchId: string;
  at: number;
};

export type LaunchRequestedEvent = AppLifecycleEventBase & {
  type: 'launch_requested';
  reason: 'start' | 'restart' | 'ensure_ready';
};

export type LaunchCompletedEvent = AppLifecycleEventBase & {
  type: 'launch_completed';
  reason: 'start' | 'restart' | 'ensure_ready';
};

export type LaunchFailedEvent = AppLifecycleEventBase & {
  type: 'launch_failed';
  reason: 'start' | 'restart' | 'ensure_ready';
  error: unknown;
};

export type StopRequestedEvent = {
  type: 'stop_requested';
  at: number;
  reason: 'restart' | 'dispose' | 'coverage' | 'manual';
};

export type StopCompletedEvent = {
  type: 'stop_completed';
  at: number;
  reason: 'restart' | 'dispose' | 'coverage' | 'manual';
};

export type CrashWatch = {
  promise: Promise<never>;
  cancel: () => void;
};

export type AppLifecycleMonitor = {
  start: () => Promise<void>;
  stop: () => Promise<void>;
  dispose: () => Promise<void>;

  launchRequested: (event: LaunchRequestedEvent) => void;
  launchCompleted: (event: LaunchCompletedEvent) => void;
  launchFailed: (event: LaunchFailedEvent) => void;
  stopRequested: (event: StopRequestedEvent) => void;
  stopCompleted: (event: StopCompletedEvent) => void;

  watch: (testFilePath: string, phase: AppLifecyclePhase) => CrashWatch;
  reset: () => void;
  isAlive: () => boolean;
};

The noop implementation must implement the same contract:

export const createNoopAppLifecycleMonitor = (): AppLifecycleMonitor => ({
  start: async () => undefined,
  stop: async () => undefined,
  dispose: async () => undefined,

  launchRequested: () => undefined,
  launchCompleted: () => undefined,
  launchFailed: () => undefined,
  stopRequested: () => undefined,
  stopCompleted: () => undefined,

  watch: () => ({
    promise: new Promise<never>(() => undefined),
    cancel: () => undefined,
  }),

  reset: () => undefined,
  isAlive: () => true,
});

The platform runner interface should keep a single creation method:

export type CreateAppMonitorOptions = {
  crashArtifactWriter?: CrashArtifactWriter;
};

export type HarnessPlatformRunner = {
  startApp: (options?: AppLaunchOptions) => Promise<void>;
  restartApp: (options?: AppLaunchOptions) => Promise<void>;
  stopApp: () => Promise<void>;
  dispose: () => Promise<void>;
  isAppRunning: () => Promise<boolean>;
  createAppMonitor: (options?: CreateAppMonitorOptions) => AppLifecycleMonitor;
};

There should be no optional monitorTarget property. Target information is captured by the platform implementation when it constructs the monitor.

Platform Monitor Construction

Android platform instances already resolve:

• adbId
• bundleId
• activityName
• appUid

They should construct either:

createAndroidAppLifecycleMonitor({
  adbId,
  bundleId,
  appUid,
  isAppRunning: () => adb.isAppRunning(adbId, bundleId),
  crashArtifactWriter,
});

or a noop monitor when detectNativeCrashes === false.

iOS Simulator platform instances already resolve:

• udid
• bundleId

They should construct either:

createIosSimulatorAppLifecycleMonitor({
  udid,
  bundleId,
  isAppRunning: () => simctl.isAppRunning(udid, bundleId),
  crashArtifactWriter,
});

or a noop monitor when disabled.

iOS physical-device platform instances already resolve:

• CoreDevice deviceId
• hardware udid
• bundleId

They should construct either:

createIosDeviceAppLifecycleMonitor({
  deviceId,
  hardwareUdid: device.hardwareProperties.udid,
  bundleId,
  isAppRunning: () => devicectl.isAppRunning(deviceId, bundleId),
  crashArtifactWriter,
});

or a noop monitor when disabled.

Jest Dependency Chain

The Jest package should remain the lifecycle conductor.

Current dependency chain:

packages/jest
  imports platform runner dynamically
  creates platformInstance
  creates crashArtifactWriter
  creates appMonitor through platformInstance.createAppMonitor()
  starts appMonitor before run
  uses crashMonitor/watch while waiting for readiness and test execution
  stops/resets around restarts
  disposes monitor during session teardown

Target dependency chain:

packages/jest
  depends on:
    packages/platforms types
    platformInstance.createAppMonitor()
    AppLifecycleMonitor methods

packages/platforms
  depends on:
    shared type definitions only

packages/platform-android
  depends on:
    adb helpers
    Android logcat/process/artifact collectors
    shared AppLifecycleMonitor type

packages/platform-ios
  depends on:
    simctl helpers
    devicectl helpers
    iOS log/process/artifact collectors
    shared AppLifecycleMonitor type

packages/tools
  depends on:
    filesystem artifact persistence

packages/jest must not import adb, simctl, or devicectl.

Jest Orchestration Rules

The app lifecycle monitor should receive notifications around all controlled app lifecycle operations.

For direct launch:

const launchId = randomUUID();
monitor.launchRequested({
  type: 'launch_requested',
  launchId,
  at: Date.now(),
  reason: 'start',
});

try {
  await platformInstance.startApp(appLaunchOptions);
  monitor.launchCompleted({
    type: 'launch_completed',
    launchId,
    at: Date.now(),
    reason: 'start',
  });
} catch (error) {
  monitor.launchFailed({
    type: 'launch_failed',
    launchId,
    at: Date.now(),
    reason: 'start',
    error,
  });
  throw error;
}

For restart:

await monitor.stop();

monitor.stopRequested({
  type: 'stop_requested',
  at: Date.now(),
  reason: 'restart',
});

await platformInstance.stopApp();

monitor.stopCompleted({
  type: 'stop_completed',
  at: Date.now(),
  reason: 'restart',
});

monitor.reset();
await monitor.start();

const launchId = randomUUID();
monitor.launchRequested({
  type: 'launch_requested',
  launchId,
  at: Date.now(),
  reason: 'restart',
});

await platformInstance.startApp(appLaunchOptions);

monitor.launchCompleted({
  type: 'launch_completed',
  launchId,
  at: Date.now(),
  reason: 'restart',
});

When the existing platformInstance.restartApp(...) method is used directly, Jest should still emit one logical stop window and one logical launch window around the call:

const launchId = randomUUID();

monitor.stopRequested({ type: 'stop_requested', at: Date.now(), reason: 'restart' });
monitor.launchRequested({ type: 'launch_requested', launchId, at: Date.now(), reason: 'restart' });

try {
  await platformInstance.restartApp(appLaunchOptions);
  monitor.stopCompleted({ type: 'stop_completed', at: Date.now(), reason: 'restart' });
  monitor.launchCompleted({ type: 'launch_completed', launchId, at: Date.now(), reason: 'restart' });
} catch (error) {
  monitor.launchFailed({ type: 'launch_failed', launchId, at: Date.now(), reason: 'restart', error });
  throw error;
}

For test execution:

const crashWatch = monitor.watch(testPath, 'execution');
crashWatch.promise.catch(() => undefined);

try {
  return await Promise.race([
    conn.runTests(testPath, { ...options, runner: platform.runner }),
    crashWatch.promise,
  ]);
} finally {
  crashWatch.cancel();
}

For startup readiness:

const crashWatch = monitor.watch(testPath, 'startup');
crashWatch.promise.catch(() => undefined);

try {
  return await Promise.race([
    waitForBridgeReady(),
    crashWatch.promise,
  ]);
} finally {
  crashWatch.cancel();
}

Shared Detection Model

All real monitors should normalize evidence into the same conceptual model.

type CrashSignal = {
  id: string;
  platform: 'android' | 'ios-simulator' | 'ios-device';
  kind:
    | 'java-exception'
    | 'native-crash'
    | 'anr'
    | 'watchdog'
    | 'process-exit'
    | 'crash-report'
    | 'device-offline'
    | 'unknown';
  confidence: 'low' | 'medium' | 'high';
  occurredAt: number;
  launchId?: string;
  pid?: number;
  processName?: string;
  summary?: string;
  rawLines?: string[];
  artifactPath?: string;
};

The monitor should emit two internal stages:

• crashSuspected: first strong signal, optimized for low latency.
• crashConfirmed: corroborated by process exit, crash artifact, tombstone, ANR trace, or platform exit reason.

The public watch(...) promise should reject with the existing runtime failure shape used by Jest, for example NativeCrashError, once the monitor has enough evidence to report a crash. Monitors should wait for a short 1 to 3 second correlation window before rejecting so related evidence can be gathered and attached to the failure. If a suspected crash is not corroborated, the monitor may keep it as degraded evidence or report a warning, but it should avoid failing tests on weak evidence alone except for the physical iOS policy described below.

Correlation Model

Use an instance key instead of bare PID.

Android instance key:

(adbId, bundleId, pid, firstSeenMonotonic)

iOS Simulator instance key:

(udid, bundleId, launchId or launchEpoch)

iOS device instance key:

(deviceId, bundleId, launchId or crashTimestampBucket)

Correlation rules:

1. Open a suspicion window when the first fatal signal arrives.
2. Collect related evidence for 1 to 3 seconds.
3. Confirm if process loss, restart, exit reason, crash file, tombstone, ANR trace, or device crash log appears.
4. Emit one consolidated crash failure.
5. Suppress duplicates until a new app instance starts or a cooldown expires.

Controlled stops must not be reported as crashes. Jest should call stopRequested before controlled stops, and monitors should suppress process-exit evidence during that window.

Android Commands

The Android launcher currently starts apps with:

adb -s <adbId> shell am start \
  -a android.intent.action.MAIN \
  -c android.intent.category.LAUNCHER \
  -n <bundleId>/<activityName>

Launch extras:

--es <key> <string-value>
--ez <key> true|false
--ei <key> <integer-value>

Controlled stop:

adb -s <adbId> shell am force-stop <bundleId>

Process check:

adb -s <adbId> shell pidof <bundleId>

Realtime crash stream:

adb -s <adbId> logcat -b crash -b main -b system -v threadtime

Optional event buffer:

adb -s <adbId> logcat -b crash -b main -b system -b events -v threadtime

Native tombstone retrieval when accessible:

adb -s <adbId> shell ls -t /data/tombstones
adb -s <adbId> pull /data/tombstones/<tombstone-file> <artifact-dir>

ANR retrieval when accessible:

adb -s <adbId> shell ls -t /data/anr
adb -s <adbId> pull /data/anr/<newest-anr-file> <artifact-dir>

Android Detection Logic

The Android monitor should start a long-lived logcat subprocess and a process poller.

Recommended collectors:

• LogcatSession
• AndroidProcessPoller
• AndroidArtifactFetcher
• optional ApplicationExitInfo app-side bridge later

High-confidence logcat signals:

• tag AndroidRuntime with message containing FATAL EXCEPTION
• debuggerd or tombstone banners
• native abort markers
• visible ActivityManager crash markers
• ANR markers such as am_anr when the events buffer is enabled

Process polling:

• Poll pidof <bundleId> at a modest interval, for example 250 to 500 ms during active test execution.
• Treat PID disappearance as neutral by itself.
• Treat PID disappearance inside a suspicion window as confirming evidence.
• Do not require PID disappearance to confirm a Java/Kotlin crash. On physical devices, the system crash dialog can keep the crashed app process visible after AndroidRuntime and am_crash have already identified the crash.
• Treat immediate PID replacement as a restart and use the instance key to avoid merging old and new evidence.
• Suppress PID disappearance during a controlled stop window opened by stopRequested.

Suggested Android flow:

onLogcatLine(line) {
  const record = parseThreadtime(line);
  ringBuffer.push(line);

  if (record.tag === 'AndroidRuntime' && record.message.includes('FATAL EXCEPTION')) {
    suspectCrash({ kind: 'java-exception', pid: record.pid, confidence: 'high' });
    openEvidenceWindow({ durationMs: 1000 });
  }

  if (looksLikeActivityManagerCrash(line)) {
    confirmCrash({
      reason: 'activity-manager-crash-record',
      kind: 'java-exception',
      confidence: 'high',
    });
    fetchFastArtifacts();
  }

  if (looksLikeDebuggerdBanner(line) || looksLikeNativeAbort(line)) {
    suspectCrash({ kind: 'native-crash', pid: record.pid, confidence: 'high' });
  }

  if (looksLikeAnrEvent(line)) {
    suspectCrash({ kind: 'anr', confidence: 'medium' });
  }
}

onPidPoll(nextPid) {
  if (controlledStopWindow.isOpen()) {
    updateCurrentPid(nextPid);
    return;
  }

  if (currentPid && !nextPid && suspicionWindow.hasRecentSignal()) {
    confirmCrash({ reason: 'process-exit-after-fatal-signal' });
    fetchFastArtifacts();
    return;
  }

  if (currentPid && !nextPid) {
    recordGoneUnknown();
    fetchExitReasonFallbackIfAvailable();
    return;
  }

  if (!currentPid && nextPid) {
    markAppStarted({ pid: nextPid });
  }
}

Android artifact policy:

• Always persist the relevant logcat ring buffer for confirmed crashes.
• For Java/Kotlin crashes, persist the AndroidRuntime stack excerpt and nearby am_crash / ActivityManager lines. This is v1's primary Android diagnostic artifact.
• Try tombstones for suspected native crashes.
• Try ANR traces for suspected ANRs.
• Treat artifact fetch failure as a warning, not as a monitor failure, because production devices often block /data/anr and /data/tombstones.

Android Emulator Crash Experiment

The playground app has DEBUG-only Android crash modes in apps/playground/android/app/src/main/java/com/harnessplayground/MainActivity.kt. Unlike iOS, the mode is supplied through an intent extra:

adb -s <serial> shell am start \
  -a android.intent.action.MAIN \
  -c android.intent.category.LAUNCHER \
  -n com.harnessplayground/.MainActivity \
  --es harness_crash_mode pre_rn

Relevant modes:

• pre_rn: throws IllegalStateException("Intentional pre-RN startup crash") before React Native startup.
• delayed_pre_ready: schedules IllegalStateException("Intentional delayed startup crash") after roughly 1 second.

Observed on 2026-05-20:

• Device: Pixel_8_API_35 emulator, Android 15 / API 35, emulator-5554.
• App: com.harnessplayground, debug APK.
• Log source: adb logcat -b crash -b main -b system -b events -v threadtime.
• Process source: adb shell pidof com.harnessplayground.

Results:

• pre_rn: process first observed after 261 ms; AndroidRuntime FATAL EXCEPTION logged 404 ms after ActivityTaskManager start; PID disappeared after 531 ms.
• delayed_pre_ready: process first observed after 259 ms; AndroidRuntime FATAL EXCEPTION logged 1599 ms after ActivityTaskManager start; PID disappeared after 1812 ms.
• am_crash / Force finishing activity appeared in logcat for both crashes.
• No new tombstone files were created, as expected for Java/Kotlin exceptions.
• /data/anr and /data/tombstones were accessible on this emulator, but no new ANR/tombstone artifact was relevant to these Java crash cases.

Experiment notes:

• For Java/Kotlin crashes, logcat is the best first signal. PID disappearance follows shortly, but it should be corroborating evidence rather than the primary detector.
• The events buffer can contain older am_crash records if the buffer is not fully cleared or if a monitor starts mid-run. Long-lived monitoring should prefer monotonic stream position and launch-time filtering over naive "first matching line in dump" parsing.
• For test scripts that clear buffers, clear the same buffers the monitor reads, for example adb logcat -b crash -b main -b system -b events -c, or use -T / launch-time filtering.
• Android may show an app crash dialog, but unlike Simulator the fatal log evidence arrives before any human action is needed. The monitor must ignore the dialog and rely on logcat/process evidence.

Physical Android Crash Experiment

The same playground Android crash modes were validated on a connected physical device.

Observed on 2026-05-20:

• Device: Xiaomi M2101K7BNY, Android 13 / API 33, serial 5LHUBUQWTW6LYXBQ.
• Build fingerprint: Redmi/rosemary_eea/rosemary:13/TP1A.220624.014/V14.0.11.0.TKLEUXM:user/release-keys.
• App: com.harnessplayground, debug APK.
• Log source: adb logcat -b crash -b main -b system -b events -v threadtime.
• Process source: adb shell pidof com.harnessplayground.
• Artifact probes: adb shell ls -t /data/anr and adb shell ls -t /data/tombstones.

Results:

• pre_rn: process first observed after 418 ms; AndroidRuntime FATAL EXCEPTION logged 829 ms after ActivityTaskManager start; am_crash logged after 839 ms; ActivityManager process death logged after 918 ms; PID disappeared after 1138 ms.
• delayed_pre_ready: process first observed after 387 ms; AndroidRuntime FATAL EXCEPTION logged 1950 ms after ActivityTaskManager start; am_crash logged after 1955 ms; PID was still visible after the polling window.
• pre_rn stack excerpt included IllegalStateException: Intentional pre-RN startup crash, MainActivity.kt:20, and MainActivity.kt:38.
• delayed_pre_ready stack excerpt included IllegalStateException: Intentional delayed startup crash and MainActivity.kt:31.
• /data/anr was listable on this device, but no new ANR artifact was produced for these Java crashes.
• /data/tombstones was not accessible: Permission denied.
• No new tombstones were produced, as expected for Java/Kotlin exceptions.

Experiment notes:

• Physical Android confirmed that logcat alone can provide actionable raw stack traces without symbolication.
• AndroidRuntime plus am_crash should be confirmation-grade evidence for Java/Kotlin crashes. Waiting for PID disappearance alone is too strict because the OS crash dialog can leave the process visible.
• PID disappearance remains useful corroboration, and it remains important for unknown exits, native crashes, and restarts.
• Production-like physical devices may block tombstones, so the monitor must not depend on /data/tombstones access for v1 Java crash reporting.
• The v1 Android report should include the exception class/message, process/PID, app stack frames, am_crash, and nearby ActivityManager lines from the ring buffer.

iOS Simulator Commands

Simulator discovery:

xcrun simctl list devices --json

Boot:

xcrun simctl boot <udid>
xcrun simctl bootstatus <udid> -b

Install:

xcrun simctl install <udid> <app-path>

Launch:

xcrun simctl launch <udid> <bundleId> [...arguments]

Launch environment:

SIMCTL_CHILD_<KEY>=<VALUE>

Terminate:

xcrun simctl terminate <udid> <bundleId>

Recommended realtime log stream:

xcrun simctl spawn <udid> log stream \
  --style json \
  --level debug \
  --predicate 'process == "<processName>" OR process == "<bundleId>" OR subsystem == "<bundleId>"'

Fallback stream if JSON style is unavailable:

xcrun simctl spawn <udid> log stream \
  --style compact \
  --level info \
  --predicate '<predicate>'

Simulator diagnostic fallback:

xcrun simctl diagnose --udid=<udid> --no-archive --output=<output-dir> -b

Host crash report location to watch:

~/Library/Logs/DiagnosticReports

iOS Simulator Detection Logic

The simulator monitor should use three signal sources:

• unified log stream through simctl spawn <udid> log stream
• app process state through existing simulator helpers
• host crash report file watcher

Recommended collectors:

• SimctlUnifiedLogStream
• IosSimulatorProcessPoller
• DiagnosticReportsWatcher
• optional SimctlDiagnoseCollector

Signals:

• fatal-looking unified log records
• abort/watchdog/native exception terms in logs
• app process disappearance after a fatal-looking record or immediately after a Harness-controlled launch
• new .ips or .crash report in ~/Library/Logs/DiagnosticReports
• simulator diagnostic bundle containing a matching crash report

Crash report matching:

• Prefer filename prefix matching by process name when available.
• Parse .ips and .crash contents.
• Confirm reports that mention the simulator UDID or otherwise match the current launch time and process.
• Filter reports older than the current launch or current run timestamp.

Suggested iOS Simulator flow:

onSimLogRecord(record) {
  ringBuffer.push(record);

  if (looksFatal(record) || looksAbort(record) || looksWatchdog(record)) {
    suspectCrash({
      platform: 'ios-simulator',
      kind: classifyIosFatal(record),
      confidence: 'medium',
    });
  }
}

onCrashFileCreated(path) {
  const parsed = parseCrashReport(path);

  if (!matchesBundleOrProcess(parsed)) {
    return;
  }

  if (!matchesCurrentSimulator(parsed, udid)) {
    return;
  }

  confirmCrash({
    kind: 'crash-report',
    confidence: 'high',
    artifactPath: persist(path),
  });
}

onProcessPoll(isRunning) {
  if (controlledStopWindow.isOpen()) {
    return;
  }

  if (!isRunning && suspicionWindow.hasRecentSignal()) {
    confirmCrash({ reason: 'process-exit-after-fatal-signal' });
  }

  if (!isRunning && currentLaunchIsRecent()) {
    suspectCrash({
      platform: 'ios-simulator',
      kind: 'process-exit',
      confidence: 'medium',
    });
    waitForCrashReport({ graceMs: 3000 });
  }
}

The simulator path should usually be able to produce a low-latency crashSuspected event from process disappearance and a high-confidence crashConfirmed event from the host crash report.

iOS Simulator Artifact Experiment

The same playground crash modes used for the physical iPhone experiment also work on Simulator through SIMCTL_CHILD_HARNESS_CRASH_MODE.

Experiment command shape:

SIMCTL_CHILD_HARNESS_CRASH_MODE=pre_rn \
  xcrun simctl launch <udid> com.harnessplayground

The experiment measured:

• host PID returned by simctl launch;
• time until that PID disappeared from ps;
• time until a matching HarnessPlayground-*.ips appeared in ~/Library/Logs/DiagnosticReports;
• whether simctl spawn <udid> log stream produced useful crash evidence.

Observed on 2026-05-20:

• Simulator: iPhone 17 Pro, iOS 26.4.1 runtime.
• Toolchain: Xcode 17E202.
• Crash modes: pre_rn and delayed_pre_ready.
• Initial post-install pre_rn run: crash report appeared after 10943 ms.
• Repeat pre_rn run 1: PID disappeared after 938 ms; crash report appeared after 2276 ms.
• Repeat pre_rn run 2: PID disappeared after 837 ms; crash report appeared after 2174 ms.
• delayed_pre_ready run: PID disappeared after 1917 ms; crash report appeared after 3269 ms.
• pre_rn run with the macOS Problem Reporter dialog intentionally left untouched: PID disappeared after 925 ms; crash report appeared after 1599 ms.
• All copied .ips files contained bundleID / CFBundleIdentifier for com.harnessplayground.
• simctl spawn <udid> log stream with process/fatal predicates did not produce useful app crash evidence in these runs.

The user also observed the macOS Problem Reporter dialog saying the app crashed, with Ignore and Report actions. The monitor must not rely on this dialog or require a human action. It also should not assume the dialog blocks artifact creation; in these runs, valid .ips files appeared while the dialog was visible and while it was intentionally left untouched.

Initial conclusion:

• For Simulator, process disappearance is the best low-latency suspected-crash signal.
• Host DiagnosticReports is the best confirmation source.
• Use the same 3 second artifact grace window as physical iOS, but allow late reportReady because the first post-install run took about 11 seconds.
• Treat unified log streaming as opportunistic context, not the primary simulator crash detector, until a stronger predicate/stream source is validated.
• The implementation should document or eventually automate crash-dialog suppression for local/CI runs if it becomes disruptive.

iOS Physical Device Commands

Device discovery must use JSON file output:

xcrun devicectl list devices --json-output <temp-json-file>

Device details:

xcrun devicectl device info details \
  --device <deviceId> \
  --json-output <temp-json-file>

Installed app lookup:

xcrun devicectl device info apps \
  --device <deviceId> \
  --json-output <temp-json-file>

Filter the JSON result by bundleIdentifier in Node. Do not rely on a --bundle-id flag being available across Xcode versions.

Launch:

xcrun devicectl device process launch \
  --device <deviceId> \
  --json-output <temp-json-file> \
  <bundleId>

Launch with environment:

xcrun devicectl device process launch \
  --device <deviceId> \
  --environment-variables '{"KEY":"VALUE"}' \
  --json-output <temp-json-file> \
  <bundleId>

Launch with arguments:

xcrun devicectl device process launch \
  --device <deviceId> \
  --json-output <temp-json-file> \
  <bundleId> \
  <arg1> <arg2>

For device process launch, keep all devicectl options before <bundleId>. Values after <bundleId> are treated as app command-line arguments.

Process list:

xcrun devicectl device info processes \
  --device <deviceId> \
  --json-output <temp-json-file>

Terminate:

xcrun devicectl device process terminate \
  --device <deviceId> \
  --pid <pid> \
  --json-output <temp-json-file>

List crash logs:

xcrun devicectl device info files \
  --device <deviceId> \
  --domain-type systemCrashLogs \
  --recurse \
  --json-output <temp-json-file>

Copy crash log:

xcrun devicectl device copy from \
  --device <deviceId> \
  --source <remote-crash-log-path> \
  --destination <local-output-file> \
  --domain-type systemCrashLogs \
  --json-output <temp-json-file>

For single-file crash logs, pass a full local destination filename. On the tested Xcode 17E202 / devicectl 518.27 toolchain, passing an existing directory as --destination failed with Cannot open destination file ... Is a directory.

Heavy fallback:

xcrun devicectl device sysdiagnose \
  --device <deviceId> \
  --json-output <temp-json-file>

The command shape should be validated against the locally installed Xcode's xcrun devicectl help. Scripts must consume --json-output files instead of scraping stdout.

iOS Physical Device Detection Logic

Physical iOS device support is intentionally conservative. The monitor should not assume a stable generic realtime crash stream equivalent to Android logcat.

Recommended collectors:

• DevicectlProcessPoller
• IosDeviceCrashLogCollector
• optional DevicectlLaunchResultTracker
• optional DarwinNotificationHeartbeat if an app-assisted heartbeat is added later
• optional DevicectlSysdiagnoseCollector

Signals:

• app process disappears after a launch and outside a controlled stop window
• a matching crash log appears in systemCrashLogs
• devicectl process launch JSON provides launch/process metadata
• optional heartbeat disappears in app-assisted mode
• sysdiagnose contains matching crash reports after escalation

Process matching:

• Get app info for bundleId.
• Use app url from devicectl device info apps.
• List running processes.
• Match processes whose executable starts with the app url.

Suggested physical iOS flow:

onLaunchCompleted(event) {
  currentLaunchId = event.launchId;
  launchCompletedAt = event.at;
  pollProcessSoon();
  scheduleCrashLogSweep({ afterMs: 1000 });
}

onProcessPoll(process) {
  if (controlledStopWindow.isOpen()) {
    return;
  }

  if (lastKnownRunning && !process) {
    suspectCrash({
      platform: 'ios-device',
      kind: 'process-exit',
      confidence: 'low',
    });

    collectCrashLogs({ minOccurredAt: launchCompletedAt });
  }
}

onCrashLogCollected(report) {
  if (!matchesBundleOrProcess(report)) {
    return;
  }

  if (report.occurredAt < launchCompletedAt - toleranceMs) {
    return;
  }

  confirmCrash({
    platform: 'ios-device',
    kind: 'crash-report',
    confidence: 'high',
    artifactPath: persist(report.path),
  });
}

Physical iOS confidence rules:

• Process disappearance alone is low confidence.
• Process disappearance plus matching crash log is high confidence.
• Matching crash log near the current launch window is high confidence even if process polling missed the transition.
• Missing crash logs should not cause an immediate failure. The monitor should wait for a crash artifact for a bounded grace period because physical-device crash log sync can lag behind process exit.
• If a physical iOS process disappears outside a controlled stop window and a matching crash artifact does not arrive before the bounded grace period expires, the monitor may fail the active watch with degraded process-exit evidence. If a matching artifact arrives later, it should be persisted and surfaced as a report update.
• Based on the initial physical iPhone experiment below, start with a 3 second artifact grace window for v1. This lines up with the shared 1 to 3 second correlation window and still leaves room for a degraded fallback if a device or Xcode version is slower.

Physical iPhone Artifact Experiment

The playground app has DEBUG-only crash modes in apps/playground/ios/HarnessPlayground/AppDelegate.swift. The mode is read from HARNESS_CRASH_MODE or --harness-crash-mode=<mode>.

Relevant modes:

• pre_rn: calls fatalError("Intentional pre-RN startup crash") before React Native startup.
• delayed_pre_ready: schedules fatalError("Intentional delayed startup crash") after roughly 1 second.

This gives Harness a useful physical-device experiment without requiring native changes in apps under test. The playground is only a test fixture; the production monitor still treats the app as a native black box.

Experiment command shape:

xcrun devicectl device process launch \
  --device <hardware-udid-or-device-id> \
  --terminate-existing \
  --environment-variables '{"HARNESS_CRASH_MODE":"pre_rn"}' \
  --json-output <launch-json> \
  --log-output <launch-log> \
  --timeout 30 \
  com.harnessplayground

Then poll:

xcrun devicectl device info files \
  --device <hardware-udid-or-device-id> \
  --domain-type systemCrashLogs \
  --recurse \
  --json-output <poll-json> \
  --log-output <poll-log> \
  --timeout 30

And copy:

xcrun devicectl device copy from \
  --device <hardware-udid-or-device-id> \
  --source HarnessPlayground-<timestamp>.ips \
  --destination <artifact-dir>/HarnessPlayground-<timestamp>.ips \
  --domain-type systemCrashLogs \
  --json-output <copy-json> \
  --log-output <copy-log> \
  --timeout 60

Observed on 2026-05-20:

• Device: physical iPhone, iOS 26.5, app com.harnessplayground.
• Toolchain: Xcode 17E202, devicectl JSON version 3 / tool version 518.27.
• Crash mode: HARNESS_CRASH_MODE=pre_rn.
• Run 1: crash log listed after 1623 ms; copy to explicit filename took 194 ms.
• Run 2: crash log listed after 1271 ms; copy took 151 ms.
• Run 3: crash log listed after 1382 ms; copy took 453 ms.
• All copied .ips files contained bundleID / CFBundleIdentifier for com.harnessplayground.

Initial conclusion:

• Physical iOS systemCrashLogs can be fast enough for startup crash reporting.
• The v1 monitor should poll crash logs soon after launch and process disappearance rather than assuming physical iOS artifacts are slow.
• A 3 second grace period is a reasonable initial default before failing with degraded process-exit evidence.
• Continue surfacing late artifacts if they arrive after the watch has already failed.

App Black-Box Policy

The monitor should treat the app's native layer as unavailable. Harness may influence the JavaScript side of the app through its existing runtime and launch options, but the crash detector must not require native code changes in the app under test.

Baseline implications:

• Do not require an Android native bridge for ApplicationExitInfo.
• Do not require an iOS native heartbeat or Darwin notification integration.
• Do not require native crash handlers inside the app.
• Prefer host-side platform tools and host-visible artifacts.
• Keep app-assisted hooks as future optional enhancements only if they can be introduced without changing the baseline contract.

Plugin Events

The new monitor should update the plugin event surface rather than keeping crash monitor state entirely internal.

Existing app-level hooks include:

• app:started
• app:exited
• app:possible-crash

The implementation should replace app:possible-crash with a clearer event set so plugins can observe monitor states without parsing thrown errors. The event payloads should include the run id, optional test file, lifecycle phase, platform, target identifier, launch id when available, confidence, source, summary, process metadata, and artifact metadata when available.

Recommended hook model:

• app:started: emitted when a new app instance is observed.
• app:exited: emitted when the app process exits or disappears, including whether the exit is controlled, unknown, or crash-related.
• app:crash-suspected: emitted for suspected crashes during the correlation window.
• app:crash-confirmed: emitted when the monitor has enough evidence to fail the active watch.
• app:crash-report-ready: emitted when a crash report, tombstone, ANR trace, or late physical-device crash artifact has been persisted.
• app:monitor-warning: emitted for degraded monitoring states such as inaccessible artifacts, delayed physical iOS crash logs, collector fallback, or command capability gaps.

app:possible-crash should be removed from the new event contract. New code should use app:crash-suspected.

Plugin events should be scheduled through the existing hook queue so crash reporting does not bypass normal plugin ordering and abort behavior.

Artifact Persistence

CrashArtifactWriter is storage, not detection logic.

It persists file or text evidence into .harness/crash-reports and returns the persisted path:

crashArtifactWriter.persistArtifact({
  artifactKind: 'logcat',
  source: {
    kind: 'text',
    fileName: 'android-crash.log',
    text: logcatWindow,
  },
});

crashArtifactWriter.persistArtifact({
  artifactKind: 'ios-crash-report',
  source: {
    kind: 'file',
    path: reportPath,
  },
});

The monitor should use it for:

• Android logcat windows
• Android tombstones
• Android ANR traces
• iOS .ips or .crash reports
• iOS diagnostic excerpts

The monitor should be able to run without a writer, but reports will be less useful.

Diagnostic Detail Without Symbolication

Symbolication is out of scope for v1, but raw stack data is still required. The goal is to point a Harness user toward the failing layer and the most likely source location, not to produce fully symbolicated production crash reports.

For Android Java/Kotlin crashes, logcat already contains the actionable stack trace:

• exception class and message, for example IllegalStateException: Intentional delayed startup crash;
• process name and PID;
• Java/Kotlin frames, including app frames such as MainActivity.kt:31;
• system corroboration such as am_crash and Force finishing activity.

For Android native crashes, persist the debuggerd/tombstone text when available. Do not run ndk-stack in v1. Even without symbolication, tombstones usually provide signal, fault address, loaded module names, ABI, thread list, and program-counter/module offsets.

For iOS Simulator and physical iOS device crashes, persist the raw .ips or .crash file and extract a small summary when possible:

• app name and bundle id;
• timestamp and incident id;
• exception type / termination reason when present;
• faulting thread id;
• top frames from the faulting thread;
• source file, line, or symbol fields when the report already includes them.

Do not require dSYMs, .dSYM lookup, atos, NDK symbols, or source maps in v1. Future work can add optional enrichment, but the first implementation should make crashes actionable using host-visible platform artifacts.

Error And Warning Semantics

Monitor infrastructure failures should be separated from app crashes.

Examples of warnings:

• adb logcat restarted after disconnect.
• tombstone directory inaccessible.
• ANR directory inaccessible.
• simctl log stream unavailable in JSON mode, falling back to compact mode.
• physical iOS crash logs not available yet.
• devicectl command shape unsupported by local Xcode.

Examples of monitor errors:

• cannot start required baseline collector
• malformed command output from required JSON interface
• repeated collector restart failure beyond configured backoff

App crash failures should include:

• platform
• target identifier
• phase: startup or execution
• test file path
• summary
• signal or exception type when known
• process name and PID when known
• artifact path when available
• short raw evidence window
• extracted raw stack excerpt when available, for example Android AndroidRuntime frames or the iOS faulting-thread frames

Security And Retention

Crash artifacts and logs may contain sensitive data.

The implementation should:

• store artifacts under .harness/crash-reports
• keep crash artifacts append-only for now
• avoid sending raw artifacts outside the local run by default
• deduplicate persisted artifacts
• redact obvious tokens before indexing or displaying summaries
• avoid logging full crash files at normal log levels
• make future retention controls possible, but do not clean or expire old crash artifacts in this implementation

Testing Strategy

Testing should be split by responsibility.

Jest orchestration tests:

• use a fake AppLifecycleMonitor
• assert linear lifecycle ordering
• assert no optional monitor checks are needed
• assert startup readiness races against monitor.watch(..., 'startup')
• assert test execution races against monitor.watch(..., 'execution')
• assert controlled restarts call stop/reset/start in the right order
• assert monitor disposal happens during teardown

Shared monitor tests:

• suspicion window behavior
• duplicate suppression
• controlled stop suppression
• launch ID correlation
• report assembly
• artifact persistence integration through a fake writer

Android monitor tests:

• Java FATAL EXCEPTION logcat fixture
• native debuggerd/tombstone fixture
• ANR event fixture
• PID disappearance without crash signal
• PID disappearance inside suspicion window
• immediate PID replacement
• controlled force-stop
• inaccessible tombstone/ANR directories
• device disconnect and logcat restart

iOS Simulator monitor tests:

• JSON unified log fatal fixture
• compact unified log fallback fixture
• .ips crash report matching current simulator UDID
• stale crash report filtering
• process disappearance after fatal log
• controlled simctl terminate
• simctl diagnose fallback artifact discovery

iOS physical-device monitor tests:

• devicectl JSON command parsing
• app URL based process matching
• process disappearance without crash log
• matching systemCrashLogs report confirmation
• stale crash log filtering
• delayed crash log arrival
• device unplug during artifact copy
• sysdiagnose fallback trigger

End-to-end scenarios:

• Android Java exception
• Android native crash
• Android ANR
• Android user force-stop
• Android app restart
• iOS Simulator fatalError
• iOS Simulator abort()
• iOS Simulator fast relaunch
• physical iOS crash with fast crash log retrieval
• physical iOS crash with delayed crash log retrieval
• physical iOS unplug during retrieval
• plugin hook emission for suspected crash, confirmed crash, late report readiness, and monitor warnings

Migration Plan

1. Add the new shared AppLifecycleMonitor interface and noop implementation in packages/platforms.
2. Update packages/jest to use the lifecycle monitor directly and linearly.
3. Preserve the existing detectNativeCrashes toggle by returning noop monitors when disabled.
4. Implement Android monitor from scratch using logcat, PID polling, and artifact fetchers.
5. Implement iOS Simulator monitor from scratch using simctl log streaming and host crash report watching.
6. Implement iOS physical-device monitor from scratch using devicectl JSON commands, process polling, and crash log retrieval.
7. Add platform fixtures and unit tests for collectors and correlators.
8. Add Jest orchestration tests with a fake monitor.
9. Validate on real Android emulator/device, iOS Simulator, and at least one physical iOS device.
10. Remove old monitor implementation after replacement coverage is in place.

Consequences

Positive:

• Jest orchestration remains platform-neutral.
• The monitor becomes easier to test because lifecycle events can be faked.
• Platform packages retain ownership of platform command details.
• Disabled monitoring uses the same code path through a noop implementation.
• The design can report degraded capability honestly, especially on physical iOS.

Negative:

• More types and lifecycle events are required up front.
• Platform monitors need separate implementations and fixtures.
• Physical iOS detection will remain less immediate than Android and iOS Simulator.
• Some artifact collection paths are best-effort on production devices.

Resolved Scope Decisions

• The app should be treated as a black box from the native side. Harness can influence the JavaScript side, but the baseline monitor must not require native app code changes.
• The monitor should wait 1 to 3 seconds to gather and correlate crash evidence before failing a watch.
• Physical iOS process disappearance can eventually fail a watch, but the monitor should first wait for a matching crash artifact for a bounded grace period. Based on the initial iPhone experiment, use 3 seconds as the v1 default. If the artifact takes too long, fail with degraded process-exit evidence and surface the artifact later if it appears.
• Crash artifacts should be append-only under .harness/crash-reports.
• Symbolication is out of scope for v1.
• Plugin events should replace app:possible-crash with structured suspected, confirmed, report-ready, and warning events.

Remaining Open Questions

• Should simctl log stream default to --style json immediately, with compact fallback, or keep compact first for compatibility?