@scalebun/react-native 1.0.3 → 1.1.0

package/android/src/main/java/com/scalebun/core/crash/CrashStorage.kt

@@ -13,14 +13,128 @@ internal object CrashStorage {
 
     private const val FILE_NAME = "scalebun_native_crash.json"
 
+    /**
+     * The session that is live RIGHT NOW, written once per session and read by the crash handler.
+     *
+     * WHY A SEPARATE FILE, AND WHY WRITTEN AHEAD OF TIME.
+     *
+     * A crash record survives the process; the JS session id did not, because it only ever existed
+     * in JS memory. So on the next launch there was nothing to attribute the crash to except
+     * whichever session had just been created — the crash from session A landed on session B.
+     *
+     * The fix is not to hand the id to the crash handler (a fatal handler cannot call into JS, and
+     * must not allocate or block), but to make sure it is ALREADY ON DISK before any crash can
+     * happen. This file is that guarantee: written once when a session starts, read synchronously
+     * inside `uncaughtException`.
+     *
+     * Kept separate from the crash record so a stale id can never resurrect a cleared crash, and so
+     * clearing a drained crash does not disturb the live session's identity.
+     */
+    private const val SESSION_FILE_NAME = "scalebun_active_session.txt"
+
+    /**
+     * Record the session that is now live. Called once per session from JS, never per event.
+     *
+     * Synchronous by design: it must be durable before the next line of app code runs, because the
+     * next line of app code is exactly what might crash. One small write per session is affordable;
+     * the same write per event would not be.
+     */
+    fun setActiveSessionId(context: Context, sessionId: String?) {
+        try {
+            val file = File(context.filesDir, SESSION_FILE_NAME)
+            if (sessionId.isNullOrEmpty()) file.delete() else file.writeText(sessionId)
+        } catch (_: Exception) {
+            // A missing session id degrades attribution; it must never break the app.
+        }
+    }
+
+    /**
+     * The live session id, or null.
+     *
+     * Called from the uncaught-exception handler, so it does exactly one thing: read a small file.
+     * No allocation beyond the string, no locks, no JS, no network.
+     */
+    fun activeSessionId(context: Context): String? {
+        return try {
+            val file = File(context.filesDir, SESSION_FILE_NAME)
+            if (!file.exists()) null else file.readText().trim().ifEmpty { null }
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    /**
+     * How many undelivered crashes we keep.
+     *
+     * One process produces one fatal crash, so this is not about a burst — it is about a device
+     * that crashes, restarts offline, and crashes again before the first crash could be uploaded.
+     * With a single fixed filename the second crash silently overwrote the first.
+     *
+     * Three is deliberately small: crashes are only pending while delivery is failing, and an
+     * unbounded spool on a device that crashes in a loop is its own bug. When full, the OLDEST is
+     * dropped — a fresh crash is better evidence than a stale one, and the alternative (dropping the
+     * new one) would hide an ongoing crash loop behind the first crash of the day.
+     */
+    private const val MAX_PENDING = 3
+    private const val PREFIX = "scalebun_native_crash"
+
+    /** Every pending crash file, oldest first. */
+    private fun pendingFiles(context: Context): List<File> =
+        (context.filesDir.listFiles { f -> f.name.startsWith(PREFIX) && f.name.endsWith(".json") }
+            ?: emptyArray())
+            .sortedBy { it.lastModified() }
+
+    /**
+     * Persist a crash. Each gets its own file and its own STABLE id.
+     *
+     * The id is generated HERE, once, when the crash is first written — never at upload time. It is
+     * what makes retry safe: the backend dedupes on it, so the same crash delivered any number of
+     * times produces one record. An id minted per attempt would defeat that completely.
+     */
     fun write(context: Context, crashData: JSONObject) {
         try {
-            File(context.filesDir, FILE_NAME).writeText(crashData.toString())
+            val crashId = crashData.optString("crashId", "").ifEmpty {
+                // Time + identity hash: unique in practice, and derivable without allocation-heavy
+                // APIs so the same scheme can be mirrored on the signal path.
+                "crash-${System.currentTimeMillis()}-${android.os.Process.myPid()}"
+            }
+            crashData.put("crashId", crashId)
+
+            val existing = pendingFiles(context)
+            if (existing.size >= MAX_PENDING) {
+                existing.take(existing.size - MAX_PENDING + 1).forEach { runCatching { it.delete() } }
+            }
+            File(context.filesDir, "$PREFIX-$crashId.json").writeText(crashData.toString())
         } catch (_: Exception) {
             // Must not throw — called from uncaught exception handler
         }
     }
 
+    /**
+     * Every pending crash, WITHOUT deleting anything.
+     *
+     * Read used to clear as a side effect, so a failed upload lost the crash permanently: the only
+     * durable copy was destroyed before anyone knew the network had worked. Deletion is now a
+     * separate, explicit act performed after the backend accepts — see [clearCrash].
+     */
+    fun readAll(context: Context): List<JSONObject> =
+        pendingFiles(context).mapNotNull { f ->
+            runCatching { JSONObject(f.readText()) }.getOrNull()
+        }
+
+    /** Drop one delivered crash by its stable id. Safe to call for an id that is already gone. */
+    fun clearCrash(context: Context, crashId: String) {
+        try {
+            File(context.filesDir, "$PREFIX-$crashId.json").delete()
+            // Legacy single-file record predating per-crash ids.
+            if (crashId.isEmpty()) File(context.filesDir, FILE_NAME).delete()
+        } catch (_: Exception) {}
+    }
+
+    /**
+     * The LEGACY single-file record, kept only so a crash written by a previous SDK version is not
+     * stranded on disk after an app update. Read non-destructively like everything else now.
+     */
     fun read(context: Context): JSONObject? {
         return try {
             val file = File(context.filesDir, FILE_NAME)

package/android/src/main/java/com/scalebun/core/crash/NativeCrashHandler.kt

@@ -49,6 +49,20 @@ class NativeCrashHandler private constructor(
                 put("timestamp", System.currentTimeMillis().toDouble())
                 put("platform", "android")
                 if (causeInfo != null) put("cause", causeInfo)
+
+                /**
+                 * The session this crash actually belongs to.
+                 *
+                 * Read from disk, where it was written when the session started — NOT asked for
+                 * now. A fatal handler cannot call into JS, and the JS thread may already be gone.
+                 * Without this the crash arrives on the next launch with no identity, and gets
+                 * attributed to whichever session exists by then: the crash from session A lands
+                 * on session B, marking a healthy session crashed and a crashed one clean.
+                 *
+                 * Omitted rather than written empty when unknown (a crash before any session
+                 * started), so the reader can tell "no session" from "session ''".
+                 */
+                CrashStorage.activeSessionId(context)?.let { put("sessionId", it) }
             }
 
             CrashStorage.write(context, data)

package/android/src/main/java/com/scalebun/replaysdk/ReplaySdkModule.kt

@@ -913,25 +913,41 @@ class ReplaySdkModule(reactContext: ReactApplicationContext) : ReplaySdkSpec(rea
     @ReactMethod
     override fun stopVoiceRecording(promise: Promise) {
         try {
-            val transcript = voiceTranscriber?.stop()
+            // Order matters twice here:
+            //  1. The recorder stops FIRST — it owns the mic while running, and on
+            //     most devices a concurrent capture silences the recognition engine
+            //     (the transcript arrives empty). Releasing the mic before asking
+            //     the engine to finalize gives its last buffer a chance to flush.
+            //  2. The transcript is read via the ASYNC stop: stopListening() →
+            //     onResults is not synchronous, and the old sync read raced it —
+            //     returning partials or nothing even when the engine had a result.
             val clip = voiceRecorder?.stop()
+            val transcriber = voiceTranscriber
             voiceRecorder = null
             voiceTranscriber = null
             if (clip == null) {
+                transcriber?.stop()
                 promise.resolve(null)
                 return
             }
             // Bytes are read into base64 by the recorder; drop the temp file now.
             java.io.File(clip.filePath).delete()
-            val result = Arguments.createMap().apply {
-                putString("base64", clip.base64)
-                putString("mime", "audio/mp4")
-                putInt("durationMs", clip.durationMs)
-                putInt("byteSize", clip.byteSize)
-                putString("transcript", transcript?.text ?: "")
-                putBoolean("transcriptAvailable", transcript?.available ?: false)
+            val resolveWith = { transcript: com.scalebun.replaysdk.voice.VoiceTranscriber.TranscriptResult? ->
+                val result = Arguments.createMap().apply {
+                    putString("base64", clip.base64)
+                    putString("mime", "audio/mp4")
+                    putInt("durationMs", clip.durationMs)
+                    putInt("byteSize", clip.byteSize)
+                    putString("transcript", transcript?.text ?: "")
+                    putBoolean("transcriptAvailable", transcript?.available ?: false)
+                }
+                promise.resolve(result)
+            }
+            if (transcriber == null) {
+                resolveWith(null)
+            } else {
+                transcriber.stop { transcript -> resolveWith(transcript) }
             }
-            promise.resolve(result)
         } catch (e: Exception) {
             voiceRecorder = null
             voiceTranscriber = null

package/android/src/main/java/com/scalebun/replaysdk/voice/VoiceTranscriber.kt

@@ -31,6 +31,11 @@ class VoiceTranscriber(private val context: Context) {
     @Volatile private var transcript: String = ""
     @Volatile private var available: Boolean = false
 
+    companion object {
+        /** How long stop() waits for the engine's final onResults before giving up. */
+        private const val FINAL_RESULT_GRACE_MS = 700L
+    }
+
     /** Start a live on-device recognition session. Best-effort — never throws. */
     fun start() {
         main.post {
@@ -63,7 +68,13 @@ class VoiceTranscriber(private val context: Context) {
         }
     }
 
-    /** Stop the session and return the accumulated transcript (may be empty). */
+    /**
+     * Stop the session and return the accumulated transcript (may be empty).
+     *
+     * Kept for binary compatibility; prefer [stop] with a callback — this sync
+     * form returns BEFORE the recognizer's final onResults can arrive, so it only
+     * ever sees partials.
+     */
     fun stop(): TranscriptResult {
         main.post {
             try {
@@ -76,12 +87,53 @@ class VoiceTranscriber(private val context: Context) {
         return TranscriptResult(transcript.trim(), available)
     }
 
+    /**
+     * Stop the session and deliver the transcript AFTER the engine has had a
+     * chance to emit its final result. stopListening() → onResults is
+     * asynchronous; the sync stop() raced it and returned partials-only (or
+     * nothing). We wait up to [FINAL_RESULT_GRACE_MS], completing early when
+     * onResults lands.
+     */
+    fun stop(onDone: (TranscriptResult) -> Unit) {
+        main.post {
+            val rec = recognizer
+            recognizer = null
+            if (rec == null || !available) {
+                onDone(TranscriptResult(transcript.trim(), available))
+                return@post
+            }
+            var completed = false
+            val finish = {
+                if (!completed) {
+                    completed = true
+                    try {
+                        rec.destroy()
+                    } catch (_: Exception) {
+                    }
+                    onDone(TranscriptResult(transcript.trim(), available))
+                }
+            }
+            pendingFinish = finish
+            try {
+                rec.stopListening()
+            } catch (_: Exception) {
+                finish()
+                return@post
+            }
+            main.postDelayed({ finish() }, FINAL_RESULT_GRACE_MS)
+        }
+    }
+
+    @Volatile private var pendingFinish: (() -> Unit)? = null
+
     private val listener = object : RecognitionListener {
         override fun onResults(results: Bundle?) {
             results
                 ?.getStringArrayList(SpeechRecognizer.RESULTS_RECOGNITION)
                 ?.firstOrNull()
                 ?.let { if (it.isNotBlank()) transcript = it }
+            // Final result is in — no reason to sit out the rest of the grace window.
+            main.post { pendingFinish?.invoke() }
         }
 
         override fun onPartialResults(partial: Bundle?) {
@@ -91,7 +143,21 @@ class VoiceTranscriber(private val context: Context) {
                 ?.let { if (it.isNotBlank()) transcript = it }
         }
 
-        override fun onError(error: Int) {}
+        override fun onError(error: Int) {
+            // The errors this swallowed are exactly the ones that explain an empty
+            // transcript in the field: ERROR_AUDIO(3)/ERROR_RECOGNIZER_BUSY(8) mean
+            // the mic was contended (a concurrent MediaRecorder usually wins and the
+            // engine hears silence); ERROR_NO_MATCH(7) means it heard but understood
+            // nothing. Keep them visible.
+            android.util.Log.i("ScaleBunVoice", "SpeechRecognizer error=$error (transcript so far: ${transcript.length} chars)")
+            if (error == SpeechRecognizer.ERROR_AUDIO ||
+                error == SpeechRecognizer.ERROR_RECOGNIZER_BUSY ||
+                error == SpeechRecognizer.ERROR_INSUFFICIENT_PERMISSIONS
+            ) {
+                available = false
+            }
+            main.post { pendingFinish?.invoke() }
+        }
         override fun onReadyForSpeech(params: Bundle?) {}
         override fun onBeginningOfSpeech() {}
         override fun onRmsChanged(rmsdB: Float) {}

package/android/src/main/java/com/scalebun/rn/crash/ScaleBunCrashModule.kt

@@ -48,16 +48,62 @@ class ScaleBunCrashModule(reactContext: ReactApplicationContext) :
         }
     }
 
+    /**
+     * Record which session is live, so a crash can name it.
+     *
+     * Called once when a session starts — never per event. The write is small and synchronous
+     * because it has to be durable before the next line of app code runs, and the next line of app
+     * code is exactly what might crash.
+     */
+    @ReactMethod
+    override fun setActiveSessionId(sessionId: String?, promise: Promise) {
+        try {
+            CrashStorage.setActiveSessionId(reactApplicationContext.applicationContext, sessionId)
+            promise.resolve(true)
+        } catch (e: Exception) {
+            // Attribution is best-effort; never fail the caller over it.
+            promise.resolve(false)
+        }
+    }
+
+    /**
+     * Delete one crash AFTER the backend has accepted it.
+     *
+     * Separating deletion from the read is the whole of at-least-once: the durable copy outlives
+     * every failed attempt and disappears only once the crash is known to be recorded.
+     */
+    @ReactMethod
+    override fun clearPendingCrash(crashId: String?, promise: Promise) {
+        try {
+            CrashStorage.clearCrash(reactApplicationContext.applicationContext, crashId ?: "")
+            promise.resolve(true)
+        } catch (e: Exception) {
+            // Failing to delete is harmless — the crash is already recorded, and the backend dedupes
+            // on crashId, so a redelivery produces no second row.
+            promise.resolve(false)
+        }
+    }
+
     @ReactMethod
     override fun drainPendingCrash(promise: Promise) {
         try {
             val context = reactApplicationContext.applicationContext
-            val crash = CrashStorage.read(context)
+            /**
+             * NON-DESTRUCTIVE.
+             *
+             * This used to clear the record the moment it was read, so a failed upload destroyed the
+             * only durable copy and the crash was gone forever — the app had proof of a crash,
+             * deleted it, and then failed to deliver it. Deletion is now `clearPendingCrash`, called
+             * by JS only after the backend has accepted.
+             *
+             * Oldest first: if several are pending, the earliest crash is the one that has been
+             * waiting longest and is most at risk of being aged out.
+             */
+            val crash = CrashStorage.readAll(context).firstOrNull() ?: CrashStorage.read(context)
             if (crash == null) {
                 promise.resolve(null)
                 return
             }
-            CrashStorage.clear(context)
 
             val result = Arguments.createMap()
             result.putString("name", crash.optString("name", "crash.native"))
@@ -67,6 +113,24 @@ class ScaleBunCrashModule(reactContext: ReactApplicationContext) :
             result.putDouble("timestamp", crash.optDouble("timestamp"))
             result.putString("platform", "android")
 
+            /**
+             * The session the crash belonged to — the whole point of the fix, and this mapper
+             * ENUMERATES its fields, so a value not named here is silently dropped no matter how
+             * carefully it was written on the crash path.
+             *
+             * Absent on records written before this shipped, and on a crash that happened before
+             * any session started. Left unset in both cases rather than defaulted, so the JS side
+             * can tell "unknown" from a real id and fall back deliberately.
+             */
+            val sid = crash.optString("sessionId", "")
+            if (sid.isNotEmpty()) result.putString("sessionId", sid)
+
+            // The STABLE id. It is what the backend dedupes on, and what JS hands back to
+            // clearPendingCrash once delivery succeeds — so it has to survive this enumerating
+            // mapper as well.
+            val cid = crash.optString("crashId", "")
+            if (cid.isNotEmpty()) result.putString("crashId", cid)
+
             val stackJson = crash.optJSONArray("stackTrace")
             if (stackJson != null) {
                 val frames = Arguments.createArray()

package/android/src/main/java/com/scalebun/rn/ota/SlotManager.kt

@@ -30,6 +30,15 @@ class SlotManager(private val filesDir: File) {
         private const val BUNDLE_FILENAME = "bundle.jsbundle"
         private const val META_FILENAME = "meta.json"
         private const val BOOT_MARKER_FILENAME = "boot_marker"
+
+        /**
+         * Launches a freshly-applied bundle gets to call markHealthy() before the
+         * guard treats it as crash-looping. 2 = one retry: a single unlucky boot
+         * (OOM kill, user swipe-away during startup) does not cost the update,
+         * but a bundle that genuinely cannot start is gone by the second launch.
+         */
+        private const val MAX_BOOT_ATTEMPTS = 2
+        private const val REVERT_RECORD_FILENAME = "last_revert.json"
     }
 
     private val otaRoot: File get() = File(filesDir, OTA_DIR)
@@ -37,6 +46,7 @@ class SlotManager(private val filesDir: File) {
     private val nextSlot: File get() = File(otaRoot, "next")
     private val previousSlot: File get() = File(otaRoot, "previous")
     private val bootMarker: File get() = File(otaRoot, BOOT_MARKER_FILENAME)
+    private val revertRecord: File get() = File(otaRoot, REVERT_RECORD_FILENAME)
 
     /**
      * Returns the absolute path to the active JS bundle, or null if no OTA
@@ -157,9 +167,26 @@ class SlotManager(private val filesDir: File) {
 
     /**
      * Revert to previous slot (boot-guard triggered or manual rollback).
+     *
+     * `reason` is persisted so JS can report WHY the device is no longer on the
+     * bundle it installed. Without it an auto-revert was invisible to the
+     * dashboard: `bootGuardReverted` was read by the orchestrator and written by
+     * nobody, so every crash-guard rollback recorded zero rollbacks.
      */
-    fun revert(): Boolean {
+    @JvmOverloads
+    fun revert(reason: String? = null): Boolean {
         try {
+            if (reason != null) {
+                runCatching {
+                    otaRoot.mkdirs()
+                    revertRecord.writeText(
+                        JSONObject()
+                            .put("reason", reason)
+                            .put("at", System.currentTimeMillis())
+                            .toString(),
+                    )
+                }
+            }
             if (!previousSlot.exists()) {
                 Log.w(TAG, "No previous/ to revert to — clearing current/")
                 currentSlot.deleteRecursively()
@@ -228,12 +255,39 @@ class SlotManager(private val filesDir: File) {
                     "Boot guard cannot verify this bundle — marker or meta has no sha256. " +
                         "Leaving it in place; restage with a current SDK to re-enable the check.",
                 )
-            } else if (currentId != markerId) {
+                return
+            }
+            if (currentId != markerId) {
                 Log.w(TAG, "Boot marker sha256 mismatch — auto-reverting")
                 revert()
+                return
             }
-            // If they match: this is the first launch of a new bundle.
-            // The marker stays until markHealthy() is called.
+
+            // ── Crash-loop revert ────────────────────────────────────────────
+            // Matching hashes mean the bundle is INTACT, which says nothing
+            // about whether it RUNS. A bundle that throws at JS init installs
+            // cleanly, matches every boot, and never reaches markHealthy() — so
+            // a hash-only guard let it crash-loop forever, bricking the app
+            // until reinstall. That is the exact failure an OTA boot guard
+            // exists to prevent.
+            //
+            // The marker is therefore also a boot-attempt counter: every launch
+            // that starts with the marker still present increments it. Reaching
+            // the limit means the bundle has been given MAX_BOOT_ATTEMPTS
+            // chances to call markHealthy() and never did → revert.
+            val attempts = markerJson.optInt("bootAttempts", 0) + 1
+            if (attempts >= MAX_BOOT_ATTEMPTS) {
+                Log.w(
+                    TAG,
+                    "Bundle failed to become healthy in $attempts launch(es) — auto-reverting",
+                )
+                revert(reason = "boot_crash_guard")
+                return
+            }
+            markerJson.put("bootAttempts", attempts)
+            bootMarker.writeText(markerJson.toString())
+            FileOutputStream(bootMarker, true).use { it.fd.sync() }
+            Log.i(TAG, "Boot guard: attempt $attempts/$MAX_BOOT_ATTEMPTS for this bundle")
         } catch (e: Exception) {
             Log.e(TAG, "checkBootGuard() failed — reverting to be safe", e)
             revert()
@@ -249,6 +303,18 @@ class SlotManager(private val filesDir: File) {
         state.put("next", readMeta(nextSlot))
         state.put("previous", readMeta(previousSlot))
         state.put("bootMarkerPresent", bootMarker.exists())
+        // Consume-on-read: the orchestrator turns this into an AUTO_ROLLBACK
+        // event exactly once, then the record is gone. Leaving it in place would
+        // re-report the same rollback on every subsequent launch.
+        if (revertRecord.exists()) {
+            runCatching {
+                val rec = JSONObject(revertRecord.readText())
+                state.put("bootGuardReverted", true)
+                state.put("bootGuardRevertReason", rec.optString("reason", "boot_crash_guard"))
+                state.put("bootGuardRevertedAt", rec.optLong("at", 0L))
+            }
+            revertRecord.delete()
+        }
         return state
     }
 

package/ios/Crash/ScaleBunCrashBridge.mm

@@ -25,6 +25,12 @@ RCT_EXTERN_METHOD(drainPendingCrash:(RCTPromiseResolveBlock)resolve
 RCT_EXTERN_METHOD(crashNow:(RCTPromiseResolveBlock)resolve
                   reject:(RCTPromiseRejectBlock)reject)
 
+// Selector must match the Swift @objc(setActiveSessionId:resolve:reject:) exactly — a mismatch here
+// fails at call time, not build time, and the symptom is a crash with no session rather than an error.
+RCT_EXTERN_METHOD(setActiveSessionId:(NSString *)sessionId
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
 @end
 
 #ifdef RCT_NEW_ARCH_ENABLED

package/ios/Crash/ScaleBunCrashHandler.swift

@@ -39,6 +39,15 @@ import Foundation
                 "timestamp": Date().timeIntervalSince1970 * 1000,
                 "platform": "ios",
             ]
+            /**
+             * The session this crash belongs to, read from state written when the session began —
+             * never asked for now. The JS thread may already be gone, and a fatal handler must not
+             * call into it. Absent when no session had started yet, which the reader treats as
+             * unknown rather than guessing.
+             */
+            if let sid = ScaleBunCrashStorage.activeSessionId() {
+                data["sessionId"] = sid
+            }
             if let userInfo = exception.userInfo, !userInfo.isEmpty {
                 // Flatten userInfo to string-keyed strings to stay JSON-safe
                 var info: [String: String] = [:]
@@ -57,7 +66,11 @@ import Foundation
         // Signal handlers — installs C-level handlers via ScaleBunCrashSignalBridge.
         // Handlers write a minimal record (signal number + timestamp) using only
         // async-signal-safe syscalls, then restore the default handler and re-raise.
-        ScaleBunCrashSignalBridgeInstall(ScaleBunCrashStorage.crashFilePathCString)
+        ScaleBunCrashSignalBridgeInstall(
+            ScaleBunCrashStorage.crashFilePathCString,
+            ScaleBunCrashStorage.sessionMarkerPathCString,
+            ScaleBunCrashStorage.sessionTmpPathCString
+        )
     }
 
     /** For testing only — resets the installed flag. */

package/ios/Crash/ScaleBunCrashModule.swift

@@ -50,6 +50,20 @@ class ScaleBunCrashModule: NSObject, RCTBridgeModule {
         }
     }
 
+    /**
+     * Record which session is live, so a crash can name it.
+     *
+     * Once per session, never per event. It must be durable before the next line of app code runs,
+     * because the next line of app code is what might crash.
+     */
+    @objc(setActiveSessionId:resolve:reject:)
+    func setActiveSessionId(_ sessionId: NSString?,
+                            resolve: @escaping RCTPromiseResolveBlock,
+                            reject: @escaping RCTPromiseRejectBlock) {
+        ScaleBunCrashStorage.setActiveSessionId(sessionId as String?)
+        resolve(true)
+    }
+
     @objc(drainPendingCrash:reject:)
     func drainPendingCrash(_ resolve: @escaping RCTPromiseResolveBlock,
                            reject: @escaping RCTPromiseRejectBlock) {

package/ios/Crash/ScaleBunCrashSignalBridge.h

@@ -15,4 +15,35 @@
  * @param crashFilePath  Null-terminated C string. Must remain valid for the
  *                       lifetime of the process (use a static buffer).
  */
-void ScaleBunCrashSignalBridgeInstall(const char *crashFilePath);
+/**
+ * @param crashFilePath      Where the crash record is written.
+ * @param sessionMarkerPath  Where the active session id is published (read by the handler).
+ * @param sessionTmpPath     Staging path for the atomic rename. MUST be on the same filesystem as
+ *                           sessionMarkerPath — rename is only atomic within one filesystem, and a
+ *                           cross-device rename fails outright, which would leave the marker stale.
+ *
+ * All three must remain valid for the process lifetime (use static buffers).
+ */
+void ScaleBunCrashSignalBridgeInstall(const char *crashFilePath,
+                                      const char *sessionMarkerPath,
+                                      const char *sessionTmpPath);
+
+/**
+ * Publish the active session id so a signal crash can name the session it happened in.
+ *
+ * Call from NORMAL CODE only (once per session) — never from a signal handler. It writes a temp file
+ * and `rename(2)`s it over the marker; POSIX requires that rename be atomic, so a handler reading
+ * the marker sees either the previous complete id or the new complete id, never a mix.
+ *
+ * This replaced a shared static buffer published under a `volatile sig_atomic_t` length. That design
+ * could tear: overwriting an id IN PLACE with one of the SAME length left the length valid while the
+ * bytes were half-replaced, so the handler could read "sess-BBBAAAA…". Nothing about the atomicity
+ * of the length fixed that, because the length never changed.
+ *
+ * Pass NULL to clear.
+ *
+ * @param sessionId  Null-terminated C string. Copied, so the caller's storage need not outlive the
+ *                   call. Characters outside [A-Za-z0-9_.:-] are dropped so the bytes are safe to
+ *                   emit inside a JSON string without escaping.
+ */
+void ScaleBunCrashSignalBridgeSetSessionId(const char *sessionId);