pulse-updates 1.0.11 → 1.0.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pulse Updates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,12 @@
-# Pulse Updates
+<p align="center"><img src="logo.png" width="88" alt="Pulse Updates" /></p>
+<h1 align="center">Pulse Updates — React Native SDK</h1>
+<p align="center">
+  <b>Lightweight over-the-air (OTA) updates for React Native.</b><br/>
+  Ship JavaScript &amp; assets instantly — a simpler, self-hostable alternative to expo-updates,
+  with full New Architecture (Fabric/Bridgeless) support and Ed25519 signature verification.
+</p>
 
-Lightweight OTA (Over-The-Air) updates for React Native apps. A simpler alternative to expo-updates with full support for React Native's New Architecture (Fabric/Bridgeless).
+---
 
 ## Features
 
@@ -45,8 +51,17 @@ Add these keys to your `Info.plist`:
 <string>$(MARKETING_VERSION)</string>
 <key>PulseUpdatesCheckOnLaunch</key>
 <string>ALWAYS</string>
+<!-- Code signing (REQUIRED in release builds) -->
+<key>PulseUpdatesRequireSignature</key>
+<true/>
+<key>PulseUpdatesSigningKeyId</key>
+<string>your-key-id</string>
+<key>PulseUpdatesSigningPublicKey</key>
+<string>base64-ed25519-public-key</string>
 ```
 
+> **Security:** In release builds `PulseUpdatesRequireSignature` defaults to `true`. When it is on, both `PulseUpdatesSigningKeyId` and `PulseUpdatesSigningPublicKey` are **required** — if the public key is missing or a manifest's Ed25519 signature does not verify, the update is rejected (fail-closed) and the embedded bundle is used. See [SECURITY.md](./SECURITY.md).
+
 ### Android Setup
 
 Add to your `android/app/build.gradle`:
@@ -64,8 +79,14 @@ Add metadata to `AndroidManifest.xml` inside `<application>`:
 <meta-data android:name="PulseUpdatesURL" android:value="https://your-update-server.com" />
 <meta-data android:name="PulseUpdatesRuntimeVersion" android:value="@string/app_version" />
 <meta-data android:name="PulseUpdatesCheckOnLaunch" android:value="ALWAYS" />
+<!-- Code signing (REQUIRED in release builds) -->
+<meta-data android:name="PulseUpdatesRequireSignature" android:value="true" />
+<meta-data android:name="PulseUpdatesSigningKeyId" android:value="your-key-id" />
+<meta-data android:name="PulseUpdatesSigningPublicKey" android:value="base64-ed25519-public-key" />
 ```
 
+> **Security:** In release builds `PulseUpdatesRequireSignature` defaults to `true`. When it is on, both `PulseUpdatesSigningKeyId` and `PulseUpdatesSigningPublicKey` are **required** — if the public key is missing or a manifest's Ed25519 signature does not verify, the update is rejected (fail-closed) and the embedded bundle is used. See [SECURITY.md](./SECURITY.md).
+
 #### New Architecture (Bridgeless) Setup
 
 For React Native 0.76+ with New Architecture enabled, update your `MainApplication.kt`:
@@ -119,6 +140,9 @@ class MainApplication : Application(), ReactApplication {
 | `PulseUpdatesCheckOnLaunch` | string | `ALWAYS` | When to check: `ALWAYS`, `WIFI_ONLY`, `NEVER` |
 | `PulseUpdatesChannel` | string | `production` | Update channel |
 | `PulseUpdatesLaunchWaitMs` | number | `0` | Wait time for update check on launch |
+| `PulseUpdatesRequireSignature` | boolean | `true` in release, `false` in debug | Reject manifests without a valid Ed25519 signature (fail-closed). When `true`, the signing keys below are **required** |
+| `PulseUpdatesSigningKeyId` | string | required in release | Key id that must match the manifest's `signature.keyId` |
+| `PulseUpdatesSigningPublicKey` | string | required in release | Base64 Ed25519 public key used to verify the manifest signature |
 
 ## JavaScript API
 
@@ -263,13 +287,38 @@ npx pulse-updates publish \
 | Option | Description |
 |--------|-------------|
 | `--platform` | Target platform: `ios` or `android` (required) |
-| `--build` | Build number for this update (required) |
+| `--build` | Build number for this update (optional metadata) |
+| `--dry-run` | Build + validate locally without creating a release on the server |
 | `--channel` | Update channel (default: `production`) |
 | `--api-key` | Server API key (or set in `pulse.config.json`) |
 | `--api-url` | Server URL (auto-detected from native config) |
 | `--runtime-version` | Runtime version (auto-detected from native config) |
 | `--message` | Release notes |
 | `--skip-bundle` | Skip bundle creation (use existing) |
+| `--strict` | Abort the publish if new native modules are detected (default: warn only) |
+
+### Generating Signing Keys
+
+Manifest signing uses Ed25519. Generate a matched keypair and paste each half into the right place:
+
+```bash
+npx pulse-updates keygen [--key-id <id>]
+```
+
+It prints the **private** seed for the server (`Pulse:SigningKey` / `SIGNING_KEY`) and the **public**
+key for the app (`PulseUpdatesSigningPublicKey` in Info.plist / AndroidManifest). The server's
+per-app Setup panel and `GET /api/signing` expose the public key too.
+
+### Registering Native Capabilities
+
+For capability-based crash-prediction, record what native modules the shipped binary actually provides:
+
+```bash
+npx pulse-updates register-capabilities --platform <ios|android> [--api-key <key>]
+```
+
+Run it at build time (after a native build) so the server can warn when a future JS-only update
+references native modules the installed binary doesn't have.
 
 ### Configuration File
 
@@ -287,11 +336,11 @@ Create `pulse.config.json` in your project root:
 
 Pulse Updates requires a compatible server. The server must implement:
 
-- `POST /api/releases` - Create new release
-- `POST /api/assets/check` - Check which assets exist
-- `POST /api/assets/upload` - Upload assets
-- `POST /api/releases/:id/finalize` - Finalize release
-- `GET /api/manifest/:appId` - Get latest manifest
+- `POST /api/releases` — create a release (CLI, `X-API-Key`)
+- `POST /api/releases/:id/assets/check` — check which assets already exist (dedup)
+- `POST /api/releases/:id/assets` — upload an asset
+- `POST /api/releases/:id/finalize` — finalize the release
+- `GET /pulse/manifest/:appSlug` — public signed manifest the on-device SDK fetches
 
 ## Embedded Manifest
 

package/android/src/main/java/app/pulse/updates/PulseController.kt

@@ -99,6 +99,32 @@ class PulseController private constructor() {
     private var embeddedManifest: EmbeddedManifest? = null
     private val executor = Executors.newSingleThreadExecutor()
 
+    // Stable, anonymous per-install device id (persisted in the pulse dir). Lazily generated.
+    // Used to (a) bucket staged rollouts server-side via the Pulse-Device-Id header and
+    // (b) attribute device telemetry events. Failures to read/persist are logged, never silent.
+    private var _deviceId: String? = null
+    val deviceId: String
+        get() {
+            _deviceId?.let { return it }
+            val dir = directory
+            val resolved = if (dir != null) {
+                val f = File(dir, "device_id")
+                var existing: String? = null
+                if (f.exists()) {
+                    try { existing = f.readText().trim().ifEmpty { null } }
+                    catch (e: Exception) { pulseLogWarn(TAG, "deviceId: read failed (${e.message}); regenerating") }
+                }
+                existing ?: java.util.UUID.randomUUID().toString().also { id ->
+                    try { f.writeText(id) }
+                    catch (e: Exception) { pulseLogWarn(TAG, "deviceId: persist failed (${e.message}); a new id will be used next launch") }
+                }
+            } else {
+                java.util.UUID.randomUUID().toString()
+            }
+            _deviceId = resolved
+            return resolved
+        }
+
     // Cached manifest from last check (to avoid duplicate requests in fetch)
     // Only valid for the immediate check->fetch sequence, cleared on use or new check
     private var lastCheckManifest: ManifestModel? = null
@@ -168,7 +194,8 @@ class PulseController private constructor() {
                 launchWaitMs = metadata.getInt("PulseUpdatesLaunchWaitMs", 0),
                 channel = metadata.getString("PulseUpdatesChannel"),
                 signingKeyId = metadata.getString("PulseUpdatesSigningKeyId"),
-                signingPublicKey = metadata.getString("PulseUpdatesSigningPublicKey")
+                signingPublicKey = metadata.getString("PulseUpdatesSigningPublicKey"),
+                requireSignature = metadata.getBoolean("PulseUpdatesRequireSignature", true)
             )
         } catch (e: Exception) {
             pulseLogWarn(TAG, "Failed to load native config: ${e.message}")
@@ -220,6 +247,20 @@ class PulseController private constructor() {
 
         // Synchronously select the best update for launch
         selectBestUpdateSync()
+
+        // Arm crash-rollback on the cold-start path too (parity with start() and iOS). The documented
+        // getBundleFile integration goes through here, and initializeWithoutStarting() sets
+        // isStarted=true, so a later start() early-returns and would never install recovery — it must
+        // be done here or a bad OTA could never auto-roll-back on the documented Android path.
+        if (errorRecovery == null) {
+            errorRecovery = PulseErrorRecovery().also {
+                it.initialize(errorRecoveryDelegate)
+                it.startMonitoring()
+            }
+        }
+        // Mark the launched OTA update as "launch in progress" so the health/recovery bookkeeping
+        // (consecutive failures, success/failure counts) is correct on this path.
+        launchedUpdate?.takeIf { !isEmbeddedLaunch }?.let { database?.recordLaunchStart(it.updateId) }
     }
 
     // Synchronously select the best update (used for initial launch before JS starts)
@@ -520,6 +561,21 @@ class PulseController private constructor() {
         return null
     }
 
+    // True when the host app is built debuggable. This is the runtime equivalent of iOS #if DEBUG:
+    // this module is an android-library, so its own BuildConfig.DEBUG reflects the library build
+    // type, not the host app. FLAG_DEBUGGABLE on the host context is authoritative.
+    private fun isHostDebuggable(): Boolean {
+        val ctx = context ?: return false
+        return (ctx.applicationInfo.flags and android.content.pm.ApplicationInfo.FLAG_DEBUGGABLE) != 0
+    }
+
+    // Refuse remote updates when a release build requires signing but no public key is configured.
+    // Debug builds are allowed to run unsigned remote updates for local iteration.
+    private fun shouldRefuseRemoteUpdates(cfg: PulseUpdatesConfig): Boolean {
+        if (isHostDebuggable()) return false
+        return cfg.requireSignature && cfg.signingPublicKey.isNullOrEmpty()
+    }
+
     fun checkForUpdate(callback: (Result<CheckResult>) -> Unit) {
         val cfg = config
         if (cfg == null) {
@@ -532,6 +588,15 @@ class PulseController private constructor() {
             return
         }
 
+        // Fail-closed: in non-debug builds, refuse remote updates when signing is not
+        // configured. Falls back to the embedded bundle (no remote install).
+        if (shouldRefuseRemoteUpdates(cfg)) {
+            pulseLogError(TAG, "checkForUpdate: signing required but not configured in a release build; " +
+                "refusing remote updates and using embedded bundle")
+            callback(Result.failure(PulseUpdatesException("Signing required but not configured")))
+            return
+        }
+
         executor.execute {
             // Clear any previous cached manifest before new check
             lastCheckManifest = null
@@ -552,6 +617,7 @@ class PulseController private constructor() {
                             }
 
                             lastCheckManifest = checkResult.manifest
+                            reportEvent("check", checkResult.manifest.updateId)
                             pulseLog(TAG, "checkForUpdate: cached manifest for fetch (ota=$otaCommitTime > embedded=$embeddedCommitTime)")
                         }
                     },
@@ -577,6 +643,15 @@ class PulseController private constructor() {
             return
         }
 
+        // Fail-closed: never download/install a remote update in a release build that
+        // lacks signing configuration (covers the cachedManifest fast-path that skips check).
+        if (shouldRefuseRemoteUpdates(cfg)) {
+            pulseLogError(TAG, "fetchUpdate: signing required but not configured in a release build; " +
+                "refusing remote updates and using embedded bundle")
+            callback(Result.failure(PulseUpdatesException("Signing required but not configured")))
+            return
+        }
+
         // Use cached manifest from recent check if available
         var manifestToUse = cachedManifest
         if (manifestToUse == null && lastCheckManifest != null) {
@@ -588,7 +663,12 @@ class PulseController private constructor() {
         lastCheckManifest = null
 
         executor.execute {
-            PulseRemoteLoader.fetchUpdate(cfg, database, dir, manifestToUse, callback)
+            PulseRemoteLoader.fetchUpdate(cfg, database, dir, manifestToUse) { result ->
+                // A freshly downloaded update marks this device as "served" on the server, which is
+                // what gates its launch outcomes into the crash-rate auto-rollback.
+                result.onSuccess { fr -> if (fr.isNew) reportEvent("download", fr.manifest?.updateId) }
+                callback(result)
+            }
         }
     }
 
@@ -607,6 +687,7 @@ class PulseController private constructor() {
             } catch (e: Exception) {
                 pulseLogWarn(TAG, "Failed to record successful launch: ${e.message}")
             }
+            if (!isEmbeddedLaunch) reportEvent("launch_success", update.updateId)
         }
 
         // Run reaper after successful launch
@@ -620,7 +701,52 @@ class PulseController private constructor() {
             } catch (e: Exception) {
                 pulseLogWarn(TAG, "Failed to record launch failure: ${e.message}")
             }
+            if (!isEmbeddedLaunch) reportEvent("launch_failure", update.updateId)
+        }
+    }
+
+    /**
+     * Fire-and-forget device telemetry to the server's /pulse/events endpoint, on a daemon thread so
+     * it never blocks update work. Best-effort: a failure is logged, never silently swallowed, and
+     * never affects the app. The server marks a device "served" on the "download" event — only served
+     * devices count toward crash-rate auto-rollback — and uses launch_success/launch_failure to drive
+     * that rate. appSlug + base are derived from the manifest URL (.../pulse/manifest/{appSlug}).
+     */
+    private fun reportEvent(type: String, updateId: String?) {
+        if (updateId.isNullOrEmpty()) return
+        val cfg = config ?: return
+        val marker = "/pulse/manifest/"
+        val idx = cfg.updateUrl.indexOf(marker)
+        if (idx < 0) {
+            pulseLogWarn(TAG, "reportEvent($type): updateUrl '${cfg.updateUrl}' has no $marker — cannot derive events endpoint, skipping")
+            return
         }
+        val base = cfg.updateUrl.substring(0, idx)
+        val appSlug = cfg.updateUrl.substring(idx + marker.length).substringBefore('/').substringBefore('?')
+        val eventsUrl = "$base/pulse/events"
+        val device = deviceId
+        Thread({
+            try {
+                val conn = URL(eventsUrl).openConnection() as java.net.HttpURLConnection
+                conn.requestMethod = "POST"
+                conn.setRequestProperty("Content-Type", "application/json")
+                conn.connectTimeout = 5000
+                conn.readTimeout = 5000
+                conn.doOutput = true
+                val body = JSONObject()
+                    .put("appSlug", appSlug)
+                    .put("updateId", updateId)
+                    .put("deviceId", device)
+                    .put("type", type)
+                    .toString()
+                conn.outputStream.use { it.write(body.toByteArray(Charsets.UTF_8)) }
+                val code = conn.responseCode
+                if (code !in 200..299) pulseLogWarn(TAG, "reportEvent($type) -> HTTP $code")
+                conn.disconnect()
+            } catch (e: Exception) {
+                pulseLogWarn(TAG, "reportEvent($type) failed: ${e.message}")
+            }
+        }, "pulse-telemetry").apply { isDaemon = true }.start()
     }
 
     // MARK: - Private Methods
@@ -831,6 +957,13 @@ class PulseController private constructor() {
             launchedUpdate?.updateId?.let { updateId ->
                 try {
                     database?.recordFailedLaunch(updateId)
+                    // Exclude this update from future launch selection: launchableUpdates() only
+                    // returns status IN ('ready','embedded'), so flipping a crashing OTA update to
+                    // FAILED makes the launcher (and selectBestUpdateSync) skip it and fall back to
+                    // the previous good/embedded update. Never demote the embedded update itself.
+                    if (launchedUpdate?.isEmbedded != true) {
+                        database?.setStatus(updateId, PulseUpdateStatus.FAILED)
+                    }
                 } catch (e: Exception) {
                     pulseLogWarn(TAG, "Failed to record failed launch: ${e.message}")
                 }
@@ -871,7 +1004,10 @@ data class PulseUpdatesConfig(
     val launchWaitMs: Int = 0,
     val channel: String? = null,
     val signingKeyId: String? = null,
-    val signingPublicKey: String? = null
+    val signingPublicKey: String? = null,
+    // Fail-closed by default: require a valid Ed25519 signature on remote manifests.
+    // Only meaningful for non-debug builds; debug builds always allow unsigned updates.
+    val requireSignature: Boolean = true
 ) {
     val scopeKey: String
         get() = try {
@@ -1107,6 +1243,9 @@ object PulseRemoteLoader {
             connection.setRequestProperty("Pulse-Protocol-Version", "2")
             connection.setRequestProperty("X-Pulse-Platform", "android")
             connection.setRequestProperty("X-Pulse-Runtime-Version", config.runtimeVersion)
+            // Stable device id so the server can bucket this device into staged rollouts (without it,
+            // a device is held back from any partial rollout until it reaches 100%).
+            connection.setRequestProperty("Pulse-Device-Id", PulseController.getInstance().deviceId)
 
             pulseLog(TAG, "checkForUpdate: url=${config.updateUrl}")
             pulseLog(TAG, "checkForUpdate: runtimeVersion=${config.runtimeVersion}")
@@ -1158,8 +1297,15 @@ object PulseRemoteLoader {
                 return
             }
 
-            // Verify signature if required
-            if (config.signingPublicKey != null) {
+            // Verify signature. When requireSignature is set we MUST have a configured key and
+            // a valid signature (verifyManifestSignature returns false on a missing signature),
+            // so an unsigned/misconfigured release fails closed instead of installing.
+            if (config.requireSignature) {
+                if (config.signingPublicKey.isNullOrEmpty()) {
+                    pulseLogError(TAG, "checkForUpdate: requireSignature is set but no signingPublicKey configured; refusing update")
+                    callback(Result.failure(PulseUpdatesException("Signature required but no public key configured")))
+                    return
+                }
                 pulseLog(TAG, "checkForUpdate: verifying signature...")
                 if (!verifyManifestSignature(manifest, response, config)) {
                     pulseLogWarn(TAG, "checkForUpdate: signature verification failed")
@@ -1167,6 +1313,17 @@ object PulseRemoteLoader {
                     return
                 }
                 pulseLog(TAG, "checkForUpdate: signature valid")
+            } else if (config.signingPublicKey != null && manifest.signature != null) {
+                // Optional mode (e.g. DEBUG): verify only WHEN a signature is present.
+                // verifyManifestSignature returns false on a null signature, so verifying
+                // unconditionally here would wrongly reject legitimately-unsigned DEBUG updates.
+                pulseLog(TAG, "checkForUpdate: verifying signature (optional)...")
+                if (!verifyManifestSignature(manifest, response, config)) {
+                    pulseLogWarn(TAG, "checkForUpdate: signature verification failed")
+                    callback(Result.failure(PulseUpdatesException("Signature verification failed")))
+                    return
+                }
+                pulseLog(TAG, "checkForUpdate: signature valid")
             }
 
             // Check if same update
@@ -1289,19 +1446,26 @@ object PulseRemoteLoader {
 
         // Download bundle (store in assets directory, same as other assets)
         val bundleDest = File(directory, "assets/sha256/$bundleHash")
-        if (!bundleDest.exists()) {
+        // Never trust a pre-existing content-addressed file blindly: re-hash it, and if it does not
+        // match (corruption / partial prior write) delete it and re-download. Only skip the download
+        // when the existing file verifies against the manifest hash.
+        var needBundleDownload = true
+        if (bundleDest.exists()) {
+            val existingHash = try { sha256Hex(bundleDest) } catch (e: Exception) { null }
+            if (existingHash == bundleHash) {
+                needBundleDownload = false
+            } else {
+                pulseLogWarn(TAG, "Pre-existing bundle failed re-hash (got=${existingHash?.take(16)} want=${bundleHash.take(16)}), re-downloading")
+                bundleDest.delete()
+            }
+        }
+        if (needBundleDownload) {
             try {
-                downloadFile(manifest.bundle.url, bundleDest, stagingDir)
-
-                // Verify hash
-                val actualHash = sha256Hex(bundleDest)
-                if (actualHash != bundleHash) {
-                    bundleDest.delete()
-                    database?.setStatus(updateId, PulseUpdateStatus.FAILED)
-                    callback(Result.failure(PulseUpdatesException("Bundle hash mismatch")))
-                    return
-                }
+                // downloadFile now verifies the SHA-256 on the staging temp BEFORE the atomic move,
+                // so a hash mismatch never produces a file at bundleDest.
+                downloadFile(manifest.bundle.url, bundleDest, stagingDir, bundleHash)
             } catch (e: Exception) {
+                bundleDest.delete()
                 database?.setStatus(updateId, PulseUpdateStatus.FAILED)
                 stagingDir.deleteRecursively()
                 callback(Result.failure(e))
@@ -1335,29 +1499,40 @@ object PulseRemoteLoader {
             val assetHash = asset.hash.lowercase()
             val assetDest = File(directory, "assets/sha256/$assetHash")
 
-            // Skip download if already cached
+            // Skip download only if a pre-existing cached file actually re-hashes correctly;
+            // otherwise treat it as missing and (re)download. Never reuse a file without re-hash.
             if (assetDest.exists()) {
-                // Asset already in cache, just link it
+                val existingHash = try { sha256Hex(assetDest) } catch (e: Exception) { null }
+                if (existingHash != assetHash) {
+                    pulseLogWarn(TAG, "Pre-existing asset failed re-hash for ${asset.key}, re-downloading")
+                    assetDest.delete()
+                    try {
+                        downloadFile(asset.url, assetDest, stagingDir, assetHash)
+                    } catch (e: Exception) {
+                        assetDest.delete()
+                        database?.setStatus(updateId, PulseUpdateStatus.FAILED)
+                        stagingDir.deleteRecursively()
+                        callback(Result.failure(PulseUpdatesException("Asset download failed for ${asset.key}: ${e.message}")))
+                        return
+                    }
+                }
             }
-            // Skip download if exists in embedded assets
+            // Use embedded fallback at runtime - nothing to download, just link below
             else if (embeddedHashes.contains(assetHash)) {
                 pulseLog(TAG, "Asset ${assetHash.take(16)}... exists in embedded, skipping download")
-                // Don't download - will use embedded fallback at runtime
             }
-            // Download if not exists anywhere
+            // Not present anywhere: download, verifying hash on the staging temp before the move.
+            // ALL-OR-NOTHING: any failure aborts the whole update instead of leaving it READY with a
+            // missing/corrupt asset (matches iOS downloadAssets which fails the batch on first error).
             else {
                 try {
-                    downloadFile(asset.url, assetDest, stagingDir)
-
-                    val actualHash = sha256Hex(assetDest)
-                    if (actualHash != assetHash) {
-                        assetDest.delete()
-                        pulseLogWarn(TAG, "Asset hash mismatch for ${asset.key}")
-                        continue
-                    }
+                    downloadFile(asset.url, assetDest, stagingDir, assetHash)
                 } catch (e: Exception) {
-                    pulseLogWarn(TAG, "Failed to download asset: ${e.message}")
-                    continue
+                    assetDest.delete()
+                    database?.setStatus(updateId, PulseUpdateStatus.FAILED)
+                    stagingDir.deleteRecursively()
+                    callback(Result.failure(PulseUpdatesException("Asset download failed for ${asset.key}: ${e.message}")))
+                    return
                 }
             }
 
@@ -1389,17 +1564,39 @@ object PulseRemoteLoader {
         callback(Result.success(Unit))
     }
 
-    private fun downloadFile(url: String, destination: File, stagingDir: File) {
+    private fun downloadFile(url: String, destination: File, stagingDir: File, expectedHash: String? = null) {
         destination.parentFile?.mkdirs()
         val tempFile = File(stagingDir, "temp_${System.currentTimeMillis()}")
 
-        URL(url).openStream().use { input ->
-            tempFile.outputStream().use { output ->
-                input.copyTo(output)
+        try {
+            URL(url).openStream().use { input ->
+                tempFile.outputStream().use { output ->
+                    input.copyTo(output)
+                }
+            }
+
+            // Verify SHA-256 on the STAGING TEMP before it ever lands at the content-addressed
+            // destination. A mismatch must never produce a file at `destination`.
+            if (expectedHash != null) {
+                val actualHash = sha256Hex(tempFile)
+                if (actualHash != expectedHash) {
+                    throw PulseUpdatesException("Hash mismatch: expected ${expectedHash.take(16)}, got ${actualHash.take(16)}")
+                }
+            }
+
+            // Atomic move into place. rename can fail across boundaries or if the target exists;
+            // delete any stale target first and treat a failed rename as a hard error so callers
+            // can abort the all-or-nothing apply.
+            destination.delete()
+            if (!tempFile.renameTo(destination)) {
+                throw PulseUpdatesException("Failed to move verified file into place: ${destination.name}")
+            }
+        } finally {
+            // Never leave a partial/temp file behind, regardless of success or failure.
+            if (tempFile.exists()) {
+                tempFile.delete()
             }
         }
-
-        tempFile.renameTo(destination)
     }
 
     private fun sha256Hex(file: File): String {

package/android/src/main/java/app/pulse/updates/database/PulseDatabase.kt

@@ -238,6 +238,13 @@ class PulseDatabase(context: Context, directory: File) : SQLiteOpenHelper(
 
     fun recordSuccessfulLaunch(updateId: String) {
         val now = System.currentTimeMillis()
+        // Upsert: on Android recordLaunchStart() is never called in the launch path, so the health
+        // row may not exist yet. A bare UPDATE would be a silent no-op and successful_launch_count
+        // would stay 0, which the error-recovery pipeline reads to decide whether to roll back.
+        writableDatabase.execSQL(
+            "INSERT OR IGNORE INTO health (update_id) VALUES (?)",
+            arrayOf(updateId)
+        )
         writableDatabase.execSQL("""
             UPDATE health SET
                 app_ready_at = ?,
@@ -249,6 +256,13 @@ class PulseDatabase(context: Context, directory: File) : SQLiteOpenHelper(
     }
 
     fun recordFailedLaunch(updateId: String) {
+        // Upsert (see recordSuccessfulLaunch): the health row may not exist because recordLaunchStart
+        // is not wired into the Android launch path. Without the INSERT this UPDATE is a silent
+        // no-op and failed_launch_count never increments, defeating crash-rollback bookkeeping.
+        writableDatabase.execSQL(
+            "INSERT OR IGNORE INTO health (update_id) VALUES (?)",
+            arrayOf(updateId)
+        )
         writableDatabase.execSQL("""
             UPDATE health SET
                 failed_launch_count = failed_launch_count + 1,

package/android/src/main/java/app/pulse/updates/errorrecovery/PulseErrorRecovery.kt

@@ -29,6 +29,11 @@ class PulseErrorRecovery {
     private var delegate: PulseErrorRecoveryDelegate? = null
     private var shouldHandleException = false
 
+    // Previous JVM uncaught-exception handler, so we can chain/restore it (Android analog of
+    // iOS RCTGet/SetFatalHandler). Captured when we install ours in startMonitoring().
+    private var previousUncaughtHandler: Thread.UncaughtExceptionHandler? = null
+    private var pulseUncaughtHandler: Thread.UncaughtExceptionHandler? = null
+
     fun initialize(delegate: PulseErrorRecoveryDelegate) {
         this.delegate = delegate
         if (!::handler.isInitialized) {
@@ -40,6 +45,43 @@ class PulseErrorRecovery {
     fun startMonitoring() {
         registerContentAppearedListener()
         shouldHandleException = true
+        installUncaughtExceptionHandler()
+    }
+
+    /**
+     * Install a JVM-level uncaught exception handler that routes crashes into the error recovery
+     * pipeline before delegating to the previously installed handler. This is the Android analog of
+     * iOS setRCTErrorHandlers(): without it, PulseErrorRecoveryHandler has no entry point and bad
+     * updates can brick the app.
+     */
+    private fun installUncaughtExceptionHandler() {
+        if (pulseUncaughtHandler != null) return
+
+        previousUncaughtHandler = Thread.getDefaultUncaughtExceptionHandler()
+        val handler = Thread.UncaughtExceptionHandler { thread, throwable ->
+            try {
+                if (shouldHandleException) {
+                    handleException(throwable as? Exception ?: RuntimeException(throwable))
+                }
+            } catch (e: Exception) {
+                pulseLogError(TAG, "ErrorRecovery: failed to handle uncaught exception: ${e.message}")
+            } finally {
+                previousUncaughtHandler?.uncaughtException(thread, throwable)
+            }
+        }
+        pulseUncaughtHandler = handler
+        Thread.setDefaultUncaughtExceptionHandler(handler)
+    }
+
+    private fun uninstallUncaughtExceptionHandler() {
+        // Only restore if our handler is still the active one (avoid clobbering a handler
+        // installed after us).
+        if (pulseUncaughtHandler != null &&
+            Thread.getDefaultUncaughtExceptionHandler() === pulseUncaughtHandler) {
+            Thread.setDefaultUncaughtExceptionHandler(previousUncaughtHandler)
+        }
+        pulseUncaughtHandler = null
+        previousUncaughtHandler = null
     }
 
     /**
@@ -65,6 +107,7 @@ class PulseErrorRecovery {
         // wait 10s before unsetting error handlers
         handler.postDelayed({
             shouldHandleException = false
+            uninstallUncaughtExceptionHandler()
             handler.postDelayed({ handlerThread.quitSafely() }, 10000)
         }, 10000)
     }

package/android/src/main/java/app/pulse/updates/launcher/PulseAppLauncher.kt

@@ -519,15 +519,22 @@ class PulseDefaultSelectionPolicy : PulseSelectionPolicy {
      * Priority: 1) Ready updates (newest by commitTime), 2) Embedded updates (fallback)
      */
     override fun selectUpdateToLaunch(updates: List<PulseUpdate>): PulseUpdate? {
-        // First, try to find the newest ready (downloaded) update
-        val readyUpdates = updates.filter { it.status == PulseUpdateStatus.READY }
+        // Exclude updates that failed to launch and were never confirmed good
+        // (failedLaunchCount > 0 && successfulLaunchCount == 0) so a bad update can't be
+        // re-selected on every launch — a crash loop that can effectively brick the app.
+        // Mirrors iOS PulseDefaultSelectionPolicy.selectUpdateToLaunch.
+        val healthy = updates.filter { !(it.failedLaunchCount > 0 && it.successfulLaunchCount == 0) }
+
+        // First, try to find the newest ready (downloaded) healthy update
+        val readyUpdates = healthy.filter { it.status == PulseUpdateStatus.READY }
         val newestReady = readyUpdates.maxByOrNull { it.commitTime.time }
         if (newestReady != null) {
             return newestReady
         }
 
-        // Fall back to embedded update
-        return updates.find { it.status == PulseUpdateStatus.EMBEDDED }
+        // Fall back to embedded update (embedded is always launchable).
+        return healthy.find { it.status == PulseUpdateStatus.EMBEDDED }
+            ?: updates.find { it.status == PulseUpdateStatus.EMBEDDED }
     }
 
     override fun selectUpdatesToDelete(launchedUpdate: PulseUpdateInfo, allUpdates: List<PulseUpdateInfo>): List<PulseUpdateInfo> {