@_nazmiforreal/flutter-ota 0.1.25 → 0.1.27

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/BlacklistStore.kt

@@ -0,0 +1,154 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.Context
+import android.util.Log
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * 已知"装上就出事"的补丁本地黑名单。
+ *
+ * # 为什么需要
+ * 没有黑名单时，若服务端持续下发同一个有问题的补丁：
+ * 客户端下载 → 校验通过 → 装上 → 启动崩溃 → 自动回滚 → 下次又收到 → 死循环。
+ * 黑名单把"已经验证过的坏补丁"记下来，再次下发直接拒，连流量都不浪费。
+ *
+ * # 双键设计 (version, md5)
+ * - 只用 `version`：开发者修了 bug 后用同样 version 重发会被无脑拒绝
+ * - 只用 `md5`：可读性差，debug 时不知道是哪个补丁
+ * - 用 (version, md5) 同时作为复合键：不同 md5 视作"修了再试"，允许下载
+ *
+ * # 持久性
+ * **不**因 APK 版本升级清空。否则线上事故时若服务端配置忘下架，升 APK 后又
+ * 能下到坏补丁。除非用户主动调 [clear]，黑名单条目永久保留。
+ *
+ * # 容量
+ * FIFO 上限 [MAX_ENTRIES]=50，超出按时间淘汰最老条目。极端情况下避免无限增长。
+ */
+internal object BlacklistStore {
+
+    private const val TAG = "FlutterPatcher/Blacklist"
+
+    /** SharedPreferences key（沿用 PatcherConfig.PREFS_NAME 文件，与现有键无冲突）。*/
+    private const val KEY_BLACKLIST = "patch_blacklist"
+
+    /** 黑名单条目数上限，达到后 FIFO 淘汰最早入黑的条目。*/
+    const val MAX_ENTRIES = 50
+
+    // ---- 入黑原因常量（与 BootDiagnosticStore 命名风格保持一致）----
+
+    const val REASON_BOOT_CRASH = "BOOT_CRASH"
+    const val REASON_MD5_MISMATCH = "MD5_MISMATCH"
+    const val REASON_SIGNATURE_INVALID = "SIGNATURE_INVALID"
+    const val REASON_META_CORRUPTED = "META_CORRUPTED"
+    const val REASON_APPLY_FAILED = "APPLY_FAILED"
+
+    // ---- 字段 key ----
+
+    private const val FIELD_VERSION = "version"
+    private const val FIELD_MD5 = "md5"
+    private const val FIELD_REASON = "reason"
+    private const val FIELD_BLACKLISTED_AT = "blacklistedAt"
+
+    /**
+     * 把 (version, md5) 加入黑名单。重复 add 会更新 reason + 时间戳，不会出现重复条目。
+     * version 或 md5 为空字符串则忽略（防御性，不进黑名单）。
+     */
+    @Synchronized
+    fun add(context: Context, version: String, md5: String, reason: String) {
+        if (version.isEmpty() || md5.isEmpty()) {
+            Log.w(TAG, "skip blacklist entry: version='$version' md5='$md5'")
+            return
+        }
+        val arr = readArray(context)
+        // 找到旧条目并删除（按双键），再追加到末尾，达到"重复 add 时刷新位置 + 元数据"的语义
+        val md5Lower = md5.lowercase()
+        val filtered = JSONArray()
+        for (i in 0 until arr.length()) {
+            val obj = arr.optJSONObject(i) ?: continue
+            val v = obj.optString(FIELD_VERSION)
+            val m = obj.optString(FIELD_MD5)
+            if (v == version && m == md5Lower) continue
+            filtered.put(obj)
+        }
+        filtered.put(JSONObject().apply {
+            put(FIELD_VERSION, version)
+            put(FIELD_MD5, md5Lower)
+            put(FIELD_REASON, reason)
+            put(FIELD_BLACKLISTED_AT, System.currentTimeMillis())
+        })
+        // FIFO 淘汰：超过上限就丢最老的
+        val capped = if (filtered.length() > MAX_ENTRIES) {
+            val drop = filtered.length() - MAX_ENTRIES
+            val sliced = JSONArray()
+            for (i in drop until filtered.length()) sliced.put(filtered.opt(i))
+            sliced
+        } else {
+            filtered
+        }
+        PatcherConfig.prefs(context).edit()
+            .putString(KEY_BLACKLIST, capped.toString())
+            .commit()
+        Log.w(TAG, "blacklisted version=$version md5=$md5Lower reason=$reason (${capped.length()}/$MAX_ENTRIES)")
+    }
+
+    /** 命中 (version, md5) 双键则返回 true。md5 大小写不敏感比较。*/
+    fun contains(context: Context, version: String, md5: String): Boolean {
+        if (version.isEmpty() || md5.isEmpty()) return false
+        val arr = readArray(context)
+        val md5Lower = md5.lowercase()
+        for (i in 0 until arr.length()) {
+            val obj = arr.optJSONObject(i) ?: continue
+            if (obj.optString(FIELD_VERSION) == version &&
+                obj.optString(FIELD_MD5).equals(md5Lower, ignoreCase = true)
+            ) {
+                return true
+            }
+        }
+        return false
+    }
+
+    /**
+     * 仅以 version 维度命中黑名单。供"调用方未下发 md5"场景的下载前置检查。
+     * 同 version 任意 md5 条目都视为命中。
+     */
+    fun containsByVersion(context: Context, version: String): Boolean {
+        if (version.isEmpty()) return false
+        val arr = readArray(context)
+        for (i in 0 until arr.length()) {
+            val obj = arr.optJSONObject(i) ?: continue
+            if (obj.optString(FIELD_VERSION) == version) return true
+        }
+        return false
+    }
+
+    /** 全部黑名单条目（旧→新顺序）。供 Dart 业务侧查询展示用。*/
+    fun entries(context: Context): List<Map<String, Any?>> {
+        val arr = readArray(context)
+        return List(arr.length()) { i ->
+            val obj = arr.optJSONObject(i)
+            mapOf(
+                FIELD_VERSION to obj?.optString(FIELD_VERSION),
+                FIELD_MD5 to obj?.optString(FIELD_MD5),
+                FIELD_REASON to obj?.optString(FIELD_REASON),
+                FIELD_BLACKLISTED_AT to (obj?.optLong(FIELD_BLACKLISTED_AT) ?: 0L),
+            )
+        }
+    }
+
+    /** 清空整个黑名单。慎用：通常只在调试时调用。*/
+    fun clear(context: Context) {
+        PatcherConfig.prefs(context).edit().remove(KEY_BLACKLIST).commit()
+        Log.w(TAG, "blacklist cleared")
+    }
+
+    private fun readArray(context: Context): JSONArray {
+        val raw = PatcherConfig.prefs(context).getString(KEY_BLACKLIST, null) ?: return JSONArray()
+        return try {
+            JSONArray(raw)
+        } catch (e: Exception) {
+            Log.w(TAG, "blacklist json corrupt, resetting", e)
+            JSONArray()
+        }
+    }
+}

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/BootDiagnosticStore.kt

@@ -0,0 +1,150 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.Context
+import android.util.Log
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * 上次冷启动时补丁加载结果的持久化存储。
+ *
+ * 现状：补丁能否生效取决于 `CrashGuard` / `PatchManager.getValidPatchPath` /
+ * `LoaderHook.install` 三处决策，事件只写 logcat。线上业务只能事后通过
+ * [PatchManager.currentVersion] 间接推测"补丁是不是又没了"，监控/告警接不上。
+ *
+ * 本对象在每次冷启动时把"补丁的加载结果 + 上下文"一次性覆写到
+ * SharedPreferences，Dart 侧通过 `FlutterPatcher.lastBootDiagnostic` 查询。
+ *
+ * # 写入时机
+ * - [FlutterPatcherApplication.attachPatcher] 三个出口（patched / hookFailed / noPatch / unknown）
+ * - [PatchManager.getValidPatchPath] 通过传入的 onDrop 闭包写入（versionCode/md5/sig/meta）
+ * - [CrashGuard.shouldLoadPatch] 通过传入的 onDrop 闭包写入（circuit breaker）
+ *
+ * # 跨边界约定
+ * status 用大写 SCREAMING_SNAKE 字符串而非 int，保证 Kotlin / Dart 两侧可读性 +
+ * 未来扩展不破坏序列化兼容。Dart 侧用 [PatchBootStatus] 枚举映射。
+ */
+internal object BootDiagnosticStore {
+
+    private const val TAG = "FlutterPatcher/Diag"
+
+    /** SharedPreferences key（沿用 PatcherConfig.PREFS_NAME 文件，与现有键无冲突）。*/
+    private const val KEY_LAST_BOOT_DIAG = "last_boot_diagnostic"
+
+    // ---- status 常量（与 Dart 侧 PatchBootStatus 一一对应）----
+
+    /** 未安装补丁，使用 APK 内置 libapp.so。属于正常状态。*/
+    const val NO_PATCH = "NO_PATCH"
+
+    /** 补丁加载成功，本次启动按补丁运行。*/
+    const val PATCHED = "PATCHED"
+
+    /** 补丁被丢弃：targetVersionCode 与当前 APK versionCode 不匹配。*/
+    const val DROPPED_VERSION_CODE_MISMATCH = "DROPPED_VERSION_CODE_MISMATCH"
+
+    /** 补丁被丢弃：本地 .so 文件 md5 与 meta.effectiveMd5 不一致。*/
+    const val DROPPED_MD5_MISMATCH = "DROPPED_MD5_MISMATCH"
+
+    /** 补丁被丢弃：Ed25519 签名校验失败 / 严格模式下 API < 33。*/
+    const val DROPPED_SIGNATURE_INVALID = "DROPPED_SIGNATURE_INVALID"
+
+    /** 补丁被丢弃：meta.json 损坏或缺关键字段（effectiveMd5 等）。*/
+    const val DROPPED_META_CORRUPTED = "DROPPED_META_CORRUPTED"
+
+    /** 补丁被丢弃：连续启动失败累计 >= maxCrashCount，熔断器触发。*/
+    const val DROPPED_CIRCUIT_BREAKER = "DROPPED_CIRCUIT_BREAKER"
+
+    /** 补丁文件保留，但反射替换 FlutterLoader 失败，本次启动用了内置 .so。*/
+    const val HOOK_INSTALL_FAILED = "HOOK_INSTALL_FAILED"
+
+    /** attachPatcher 阶段抛出未分类异常。*/
+    const val UNKNOWN = "UNKNOWN"
+
+    // ---- 字段 key（写入 / 读取共用）----
+
+    private const val FIELD_STATUS = "status"
+    private const val FIELD_PATCH_VERSION = "patchVersion"
+    private const val FIELD_PATCH_TARGET_VC = "patchTargetVersionCode"
+    private const val FIELD_APP_VC = "appVersionCode"
+    private const val FIELD_CRASH_COUNT = "crashCount"
+    private const val FIELD_ATTEMPTED_LOADER_FIELDS = "attemptedLoaderFields"
+    private const val FIELD_MESSAGE = "message"
+    private const val FIELD_RECORDED_AT = "recordedAt"
+
+    /**
+     * 覆写一条诊断记录。
+     *
+     * 使用 commit 同步写入：本方法常在 attachBaseContext 阶段调用，若进程随后
+     * 因补丁问题崩溃，commit 能保证下次启动 Dart 侧仍能查询到本次的诊断结果。
+     */
+    fun record(
+        context: Context,
+        status: String,
+        patchVersion: String? = null,
+        patchTargetVersionCode: Long? = null,
+        appVersionCode: Long? = null,
+        crashCount: Int? = null,
+        attemptedLoaderFields: List<String>? = null,
+        message: String? = null,
+    ) {
+        val json = JSONObject().apply {
+            put(FIELD_STATUS, status)
+            putOpt(FIELD_PATCH_VERSION, patchVersion)
+            putOpt(FIELD_PATCH_TARGET_VC, patchTargetVersionCode)
+            putOpt(FIELD_APP_VC, appVersionCode)
+            putOpt(FIELD_CRASH_COUNT, crashCount)
+            if (attemptedLoaderFields != null) {
+                put(FIELD_ATTEMPTED_LOADER_FIELDS, JSONArray(attemptedLoaderFields))
+            }
+            putOpt(FIELD_MESSAGE, message)
+            put(FIELD_RECORDED_AT, System.currentTimeMillis())
+        }
+        PatcherConfig.prefs(context).edit()
+            .putString(KEY_LAST_BOOT_DIAG, json.toString())
+            .commit()
+        Log.d(TAG, "record status=$status patch=$patchVersion msg=$message")
+    }
+
+    /**
+     * 读取最近一次 record。
+     *
+     * @return 诊断 Map，可直接交给 MethodChannel 发到 Dart 侧；
+     *         null 表示从未 record 过（首次安装或 pm clear 后第一次启动且尚未到首帧）。
+     */
+    fun read(context: Context): Map<String, Any?>? {
+        val raw = PatcherConfig.prefs(context).getString(KEY_LAST_BOOT_DIAG, null) ?: return null
+        return try {
+            val json = JSONObject(raw)
+            val map = mutableMapOf<String, Any?>()
+            map[FIELD_STATUS] = json.optString(FIELD_STATUS, UNKNOWN)
+            map[FIELD_PATCH_VERSION] = json.optStringOrNull(FIELD_PATCH_VERSION)
+            map[FIELD_PATCH_TARGET_VC] = json.optLongOrNull(FIELD_PATCH_TARGET_VC)
+            map[FIELD_APP_VC] = json.optLongOrNull(FIELD_APP_VC)
+            map[FIELD_CRASH_COUNT] = json.optIntOrNull(FIELD_CRASH_COUNT)
+            map[FIELD_ATTEMPTED_LOADER_FIELDS] = json.optStringListOrNull(FIELD_ATTEMPTED_LOADER_FIELDS)
+            map[FIELD_MESSAGE] = json.optStringOrNull(FIELD_MESSAGE)
+            map[FIELD_RECORDED_AT] = json.optLong(FIELD_RECORDED_AT, 0L)
+            map
+        } catch (e: Exception) {
+            Log.w(TAG, "read failed, raw=$raw", e)
+            null
+        }
+    }
+
+    // ---- 内部工具：JSONObject 缺字段时返回 null 而非 "" / 0 ----
+
+    private fun JSONObject.optStringOrNull(key: String): String? =
+        if (isNull(key) || !has(key)) null else optString(key, "").ifEmpty { null }
+
+    private fun JSONObject.optLongOrNull(key: String): Long? =
+        if (isNull(key) || !has(key)) null else optLong(key)
+
+    private fun JSONObject.optIntOrNull(key: String): Int? =
+        if (isNull(key) || !has(key)) null else optInt(key)
+
+    private fun JSONObject.optStringListOrNull(key: String): List<String>? {
+        if (isNull(key) || !has(key)) return null
+        val arr = optJSONArray(key) ?: return null
+        return List(arr.length()) { arr.optString(it) }
+    }
+}

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/CrashGuard.kt

@@ -0,0 +1,271 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.app.ActivityManager
+import android.app.ApplicationExitInfo
+import android.content.Context
+import android.os.Build
+import android.os.Process
+import android.util.Log
+import java.io.File
+
+/**
+ * 熔断器：防止补丁导致启动崩溃时无限重启。
+ *
+ * 状态机（解耦版）：
+ * 1. Application.attachBaseContext → [markBooting] 写 patch_loading=true（commit 同步）+ pid
+ * 2. Dart 首帧 → [markBootSuccess] 立即清 patch_loading=false + crash_count=0；
+ *    **保留** last_booting_pid 给下次冷启动的 ExitInfo 查询
+ * 3. Dart 首帧 + verifyAfter 秒 → 卸载 Dart 错误钩子（仅 Dart 层动作，不触原生）
+ *
+ * 下次冷启动 [shouldLoadPatch] 综合判定：
+ *
+ * - **API 30+ 且有 pid 记录**：通过 [ActivityManager.getHistoricalProcessExitReasons]
+ *   拿到精确死因。覆盖首帧前后所有崩溃。只有 [ApplicationExitInfo.REASON_CRASH]
+ *   / [ApplicationExitInfo.REASON_CRASH_NATIVE] / [ApplicationExitInfo.REASON_ANR]
+ *   / [ApplicationExitInfo.REASON_INITIALIZATION_FAILURE] 计入 crash_count；
+ *   用户从最近任务划掉、系统 OOM 等不计入。
+ * - **API < 30 或 ExitInfo 无记录**：退回到 patch_loading 兜底——
+ *   patch_loading=true（首帧前死了）→ 视为崩溃；
+ *   patch_loading=false（首帧后死的）→ 不计崩溃。
+ *
+ * API < 30 因此存在已知盲区：补丁加载首帧后才发生的 native crash / ANR 不会被
+ * 检测（Dart 层异常仍由 verifyAfter 窗口内的 Dart 错误钩子捕获）。覆盖率约
+ * 5–10% 的存量长尾设备，业务侧若无法接受可显式调高 `maxCrashCount`。
+ *
+ * 当 crash_count 累计 >= [PatcherConfig.maxCrashCount] 次，自动删除补丁并拒绝加载。
+ */
+internal class CrashGuard(private val context: Context) {
+
+    companion object {
+        private const val TAG = "FlutterPatcher/Guard"
+
+        /**
+         * Pure decision: should a real crash reason be charged against the patch?
+         *
+         * Only crashes within [PatcherConfig.BOOT_CRASH_WINDOW_MS] of boot start
+         * count as patch-boot failures. A crash long after a healthy boot is a
+         * runtime failure and must NOT trip the breaker (that was the bug causing
+         * a working OTA to silently revert hours later).
+         *
+         * When [bootStartedAt] or [crashTimestamp] is unknown (<= 0) we cannot
+         * bound it, so we conservatively charge the patch (preserves the old
+         * fail-fast behavior for that edge).
+         */
+        @JvmStatic
+        fun isWithinBootWindow(
+            bootStartedAt: Long,
+            crashTimestamp: Long,
+            windowMs: Long = PatcherConfig.BOOT_CRASH_WINDOW_MS,
+        ): Boolean {
+            if (bootStartedAt <= 0L || crashTimestamp <= 0L) return true
+            val elapsed = crashTimestamp - bootStartedAt
+            // Negative elapsed (clock skew / stale record) → treat as in-window.
+            if (elapsed < 0L) return true
+            return elapsed <= windowMs
+        }
+    }
+
+    private val sp = PatcherConfig.prefs(context)
+
+    /**
+     * 启动开始时综合判断是否加载补丁。
+     *
+     * @param onTrip 当熔断器**本次**触发并丢弃补丁时调用，参数为触发时的真实
+     *   crash_count（删除前）。供 [BootDiagnosticStore] / [BlacklistStore] 上报使用。
+     */
+    fun shouldLoadPatch(onTrip: ((crashCount: Int) -> Unit)? = null): Boolean {
+        val threshold = PatcherConfig.maxCrashCount(context)
+        val patchLoading = sp.getBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+        val lastPid = sp.getInt(PatcherConfig.KEY_LAST_BOOTING_PID, -1)
+        val bootStartedAt = sp.getLong(PatcherConfig.KEY_BOOT_STARTED_AT, 0L)
+
+        val verdict = classifyPreviousSession(patchLoading, lastPid, bootStartedAt)
+        if (verdict.isCrash) {
+            val count = recordCrashAndMaybeTrip(verdict.reasonName, onTrip)
+            if (count >= threshold) return false
+        } else if (patchLoading || lastPid > 0) {
+            // 非崩溃但状态未清：清掉以免下次冷启动重复处理同一会话
+            sp.edit()
+                .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+                .remove(PatcherConfig.KEY_LAST_BOOTING_PID)
+                .remove(PatcherConfig.KEY_BOOT_STARTED_AT)
+                .commit()
+            Log.i(TAG, "previous session ended without crash (${verdict.reasonName})")
+        }
+
+        return sp.getInt(PatcherConfig.KEY_CRASH_COUNT, 0) < threshold
+    }
+
+    /**
+     * 由 Dart 侧通过 MethodChannel 调用：上报一次"补丁加载阶段 Dart 层未捕获异常"。
+     *
+     * 这种崩溃不算系统层 [ApplicationExitInfo.REASON_CRASH] —— PlatformDispatcher
+     * 把异常吞了，进程没死，下次冷启动 ExitInfo 看到的是 USER_REQUESTED 之类的非
+     * 崩溃原因。所以需要 Dart 主动汇报，语义等同于一次真崩溃：crash_count += 1，
+     * 达到阈值则熔断 + 删补丁 + 黑名单。
+     *
+     * @param message 异常字符串（透传给日志 / 诊断展示，不做任何业务逻辑判断）
+     * @param onTrip  与 [shouldLoadPatch] 同款：触发熔断时调用，上报黑名单 / 诊断
+     */
+    fun reportDartBootError(message: String?, onTrip: ((crashCount: Int) -> Unit)? = null) {
+        recordCrashAndMaybeTrip(message ?: "no msg", onTrip)
+    }
+
+    /**
+     * 增计 crash_count、清 patch_loading、必要时触发熔断 + 删补丁。供
+     * [shouldLoadPatch] 与 [reportDartBootError] 共用，统一日志格式。
+     *
+     * @param reason  错误原因（ExitInfo reason name / Dart 异常 toString），仅用于日志
+     * @return 累加后的 crash_count（删补丁前的真实值）
+     */
+    private fun recordCrashAndMaybeTrip(
+        reason: String,
+        onTrip: ((crashCount: Int) -> Unit)?,
+    ): Int {
+        val threshold = PatcherConfig.maxCrashCount(context)
+        val count = sp.getInt(PatcherConfig.KEY_CRASH_COUNT, 0) + 1
+        sp.edit()
+            .putInt(PatcherConfig.KEY_CRASH_COUNT, count)
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+            .commit()
+        Log.w(TAG, "patch boot failure recorded ($reason), crash_count=$count")
+        if (count >= threshold) {
+            Log.w(TAG, "circuit tripped! $count consecutive failures, dropping patch")
+            onTrip?.invoke(count)
+            deletePatchFiles()
+        }
+        return count
+    }
+
+    /** 在 Application.attachBaseContext 内调用。commit 同步写入，确保进程崩溃前状态已持久化。 */
+    fun markBooting() {
+        sp.edit()
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, true)
+            .putInt(PatcherConfig.KEY_LAST_BOOTING_PID, Process.myPid())
+            .putLong(PatcherConfig.KEY_BOOT_STARTED_AT, System.currentTimeMillis())
+            .commit()
+    }
+
+    /**
+     * Dart 首帧渲染完成：补丁可信，立即清 patch_loading + crash_count。
+     *
+     * 注意：故意 **不清** [PatcherConfig.KEY_LAST_BOOTING_PID] / [PatcherConfig.KEY_BOOT_STARTED_AT]。
+     * 下次冷启动 [shouldLoadPatch] 仍可用这个 pid 查 [ApplicationExitInfo]，从而捕捉首帧
+     * 后短时间内（[PatcherConfig.BOOT_CRASH_WINDOW_MS] 以内）才发生的 native crash / ANR —— 那一刻
+     * patch_loading 已清，不能再作为崩溃信号。pid + 时间戳在 [shouldLoadPatch]
+     * 处理完一次会话后清除。
+     */
+    fun markBootSuccess() {
+        sp.edit()
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+            .putInt(PatcherConfig.KEY_CRASH_COUNT, 0)
+            .commit()
+    }
+
+    /** 清零所有熔断状态（配合补丁安装/回滚调用）。 */
+    fun reset() {
+        sp.edit()
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+            .putInt(PatcherConfig.KEY_CRASH_COUNT, 0)
+            .remove(PatcherConfig.KEY_LAST_BOOTING_PID)
+            .remove(PatcherConfig.KEY_BOOT_STARTED_AT)
+            .apply()
+    }
+
+    /**
+     * 综合 [patchLoading] 与 [lastPid] 判定上次会话是否崩溃。
+     *
+     * - API 30+ 且有 pid 记录 → 优先用 [ApplicationExitInfo] 精确分类。**但只把发生在
+     *   启动窗口内（距 [bootStartedAt] 不超过 [PatcherConfig.BOOT_CRASH_WINDOW_MS]）的
+     *   崩溃计入补丁失败**：首帧后长时间运行才发生的 crash/ANR 属于正常运行期故障，
+     *   与补丁无关，不应触发熔断回滚。用户主动关闭 / 系统 OOM 等也不计崩溃。
+     * - API < 30 或 ExitInfo 拿不到记录 → 退回到 [patchLoading] 兜底信号。
+     *   patchLoading=true（首帧前死了）→ 崩溃；patchLoading=false（首帧后死的，
+     *   或本就没启动过）→ 非崩溃。
+     */
+    private fun classifyPreviousSession(
+        patchLoading: Boolean,
+        lastPid: Int,
+        bootStartedAt: Long,
+    ): ExitVerdict {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R && lastPid > 0) {
+            val record = queryExitInfo(lastPid)
+            if (record != null) {
+                val isCrashReason = when (record.reason) {
+                    ApplicationExitInfo.REASON_CRASH,
+                    ApplicationExitInfo.REASON_CRASH_NATIVE,
+                    ApplicationExitInfo.REASON_ANR,
+                    ApplicationExitInfo.REASON_INITIALIZATION_FAILURE -> true
+                    else -> false
+                }
+                val reasonName = reasonNameApi30(record.reason)
+                if (!isCrashReason) {
+                    return ExitVerdict(false, reasonName)
+                }
+                // A real crash reason — but only charge it against the patch if it
+                // happened close to boot. A crash hours into a healthy session is a
+                // runtime bug, not a bad patch; counting it would revert a working OTA.
+                if (!isWithinBootWindow(bootStartedAt, record.timestamp)) {
+                    Log.i(
+                        TAG,
+                        "crash ($reasonName) at ts=${record.timestamp} is outside the " +
+                            "${PatcherConfig.BOOT_CRASH_WINDOW_MS}ms boot window " +
+                            "(bootStartedAt=$bootStartedAt); treating as runtime " +
+                            "failure, not charging the patch"
+                    )
+                    return ExitVerdict(false, "${reasonName}_LATE")
+                }
+                return ExitVerdict(true, reasonName)
+            }
+            // ExitInfo 队列已被新进程挤出（罕见）：退回到 patchLoading 兜底
+        }
+
+        return if (patchLoading) {
+            ExitVerdict(true, "NO_FIRST_FRAME")
+        } else {
+            ExitVerdict(false, "NO_RECORD")
+        }
+    }
+
+    private fun queryExitInfo(pid: Int): ApplicationExitInfo? {
+        val am = context.getSystemService(Context.ACTIVITY_SERVICE) as? ActivityManager
+        return try {
+            am?.getHistoricalProcessExitReasons(context.packageName, pid, 1)?.firstOrNull()
+        } catch (e: Throwable) {
+            Log.w(TAG, "getHistoricalProcessExitReasons failed", e)
+            null
+        }
+    }
+
+    private fun deletePatchFiles() {
+        val dir = File(context.filesDir, PatcherConfig.PATCH_DIR)
+        if (dir.exists()) dir.deleteRecursively()
+        sp.edit()
+            .putInt(PatcherConfig.KEY_CRASH_COUNT, 0)
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+            .remove(PatcherConfig.KEY_LAST_BOOTING_PID)
+            .remove(PatcherConfig.KEY_BOOT_STARTED_AT)
+            .commit()
+    }
+
+    private data class ExitVerdict(val isCrash: Boolean, val reasonName: String)
+}
+
+/** 把 [ApplicationExitInfo] reason 整数翻成可读名，仅在 API 30+ 调用。 */
+private fun reasonNameApi30(reason: Int): String = when (reason) {
+    ApplicationExitInfo.REASON_UNKNOWN -> "UNKNOWN"
+    ApplicationExitInfo.REASON_EXIT_SELF -> "EXIT_SELF"
+    ApplicationExitInfo.REASON_SIGNALED -> "SIGNALED"
+    ApplicationExitInfo.REASON_LOW_MEMORY -> "LOW_MEMORY"
+    ApplicationExitInfo.REASON_CRASH -> "CRASH"
+    ApplicationExitInfo.REASON_CRASH_NATIVE -> "CRASH_NATIVE"
+    ApplicationExitInfo.REASON_ANR -> "ANR"
+    ApplicationExitInfo.REASON_INITIALIZATION_FAILURE -> "INITIALIZATION_FAILURE"
+    ApplicationExitInfo.REASON_PERMISSION_CHANGE -> "PERMISSION_CHANGE"
+    ApplicationExitInfo.REASON_EXCESSIVE_RESOURCE_USAGE -> "EXCESSIVE_RESOURCE_USAGE"
+    ApplicationExitInfo.REASON_USER_REQUESTED -> "USER_REQUESTED"
+    ApplicationExitInfo.REASON_USER_STOPPED -> "USER_STOPPED"
+    ApplicationExitInfo.REASON_DEPENDENCY_DIED -> "DEPENDENCY_DIED"
+    ApplicationExitInfo.REASON_OTHER -> "OTHER"
+    else -> "REASON_$reason"
+}