FireCrasher: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository. This is the canonical instructions file; CLAUDE.md points here. Module-specific notes live in firecrasher/AGENTS.md and app/AGENTS.md.

What this is

FireCrasher is an Android library that catches uncaught exceptions and runs a staged recovery sequence to keep the app alive instead of letting it die. It is published to JitPack as com.github.osama-raddad:FireCrasher. Current version is 3.0.0.

The recovery escalation ladder has three levels (RecoveryLevel):

• RESTART_ACTIVITY — restart the crashed activity (recreate() on the first attempt, then relaunch-and-finish). Used while retryCount <= 1.
• GO_BACK — the activity keeps crashing, so pop the back stack (go back) if there is another activity behind it.
• RELAUNCH_APP — nothing to go back to, so relaunch the whole app from its launcher activity.

The core trick (FireLooper) is to replace the main-thread message loop with a reflection-driven loop wrapped in a try/catch, so an uncaught exception on the main thread does not tear down the process — the loop reposts itself and recovery runs.

Module layout

This is a two-module Gradle project (settings.gradle):

• firecrasher/ — the published library. This is where real work happens.
• app/ — a demo application (com.osama.firecrasherdemo) that installs FireCrasher and deliberately crashes to exercise recovery. Not published.

Library source (firecrasher/src/main/java/com/osama/firecrasher/)

File	Role
FireCrasher.kt	Public API entry point: the FireCrasher object (install), the Application.installFireCrasher extension, and the internal recovery policy (evaluate, recover, dispatchCrash, retryCount, recovery-state persistence).
FireCrasherConfig.kt	The @FireCrasherDsl marker and the install DSL builder: onCrash { } (CrashScope receiver, default { recover() }) and onPreviousProcessExit { }.
CrashScope.kt	Receiver of the onCrash handler: throwable, activity, level, retryCount, and recover(level = evaluated) { }.
RecoveryLevel.kt	The three-level recovery enum (RESTART_ACTIVITY, GO_BACK, RELAUNCH_APP). Declaration order is persisted by the codec — append only.
ExitInfo.kt	Public Context extensions historicalExitReasons(maxCount) / lastAbnormalExit() (API 30+, degrade to empty/null below).
CrashHandler.kt	Internal Thread.UncaughtExceptionHandler + ActivityLifecycleCallbacks. Tracks the current activity and the live activity count (backStackCount). Delivers crashes to dispatchCrash on the main thread.
FireLooper.kt	Reflection-based replacement main loop that survives exceptions. isSafe guards against double-install.
RecoveryState.kt	RecoveryState data class + RecoveryStateCodec — encodes recovery progress into a ≤128-byte blob stored via ActivityManager.setProcessStateSummary so recovery escalation survives process death (API 30+).