@scalebun-release/react-native 2.5.0

package/ios/Crash/ScaleBunCrashBridge.mm

@@ -0,0 +1,74 @@
+#import <React/RCTBridgeModule.h>
+
+/**
+ * ObjC++ bridge exposing the ScaleBunCrash Swift module to React Native.
+ *
+ * Old Architecture: RCT_EXTERN_MODULE + RCT_EXTERN_METHOD register the Swift
+ * class and its promise methods (selectors use `reject:` to match codegen).
+ *
+ * New Architecture: the `#ifdef RCT_NEW_ARCH_ENABLED` block vends ScaleBunCrash as a
+ * real TurboModule via the codegen-generated JSI class. This file is `.mm`
+ * (ObjC++) so it can return the C++ TurboModule type.
+ *
+ * ⚠️ UNVERIFIED ON DEVICE — written without an Xcode toolchain. See
+ * docs/ios-turbomodule-verification.md for the exact items to confirm/fix on a
+ * Mac (generated header name, JSI class name, import paths).
+ */
+@interface RCT_EXTERN_MODULE(ScaleBunCrash, NSObject)
+
+RCT_EXTERN_METHOD(install:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(drainPendingCrash:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+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)
+
+
+// Blocking synchronous: a fatal JS crash unwinds the process before an async
+// promise resolves, so the write must finish before this returns. Mirrors the
+// OTA/Storage sync methods. Selector matches @objc(persistJsCrash:) in Swift.
+RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(persistJsCrash:(NSString *)recordJson)
+@end
+
+#ifdef RCT_NEW_ARCH_ENABLED
+
+#import <ReactCommon/RCTTurboModule.h>
+// Codegen output from src/specs/NativeScaleBunCrash.ts (pod: ScaleBunSpec).
+#import <ScaleBunSpec/ScaleBunSpec.h>
+// The generated Swift header declares a UNUserNotificationCenterDelegate; under
+// static-library linkage its `@import UserNotifications;` is dropped (clang
+// modules off for this TU), so import the framework explicitly first.
+#import <UserNotifications/UserNotifications.h>
+// Swift -> ObjC generated header. The angle-bracket module path resolves under
+// use_frameworks!; for static-library linkage the same-target header is found by
+// its plain name. Guard so both linkage modes compile.
+#if __has_include(<scalebun_react_native/scalebun_react_native-Swift.h>)
+#import <scalebun_react_native/scalebun_react_native-Swift.h>
+#else
+#import "scalebun_react_native-Swift.h"
+#endif
+
+// Add TurboModule conformance + the JSI factory to the Swift `ScaleBunCrash` class
+// via a category. `ScaleBunCrash` is the ObjC name from `@objc(ScaleBunCrash)` in Swift.
+@interface ScaleBunCrash (TurboModule) <RCTTurboModule>
+@end
+
+@implementation ScaleBunCrash (TurboModule)
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+    return std::make_shared<facebook::react::NativeScaleBunCrashSpecJSI>(params);
+}
+
+@end
+
+#endif

package/ios/Crash/ScaleBunCrashHandler.swift

@@ -0,0 +1,84 @@
+import Foundation
+
+/**
+ * Installs native crash handlers for iOS.
+ *
+ * WHAT IS COVERED:
+ *   - ObjC/Swift exceptions via NSSetUncaughtExceptionHandler — full stack available
+ *   - Fatal signals (SIGABRT, SIGBUS, SIGSEGV, SIGILL, SIGFPE) via ScaleBunCrashSignalBridge
+ *     — minimal record only (signal number + timestamp); no stack in signal path
+ *
+ * WHAT IS NOT COVERED:
+ *   - C++ exceptions
+ *   - Symbolication of signal crash stacks
+ *
+ * PRODUCTION RECOMMENDATION:
+ *   For reliable signal handling and on-device symbolication, integrate PLCrashReporter
+ *   (https://github.com/microsoft/plcrashreporter) via CocoaPods or Swift Package Manager.
+ *   PLCrashReporter uses Mach exception ports, which are safer than signal handlers and
+ *   provide full thread states + symbolicated stacks.
+ *   This implementation is intentionally minimal to avoid async-signal-safety violations.
+ */
+@objc class ScaleBunCrashHandler: NSObject {
+
+    private static var installed = false
+
+    @objc static func install() {
+        guard !installed else { return }
+        installed = true
+
+        // ObjC exception handler — safe, provides full stack via callStackSymbols.
+        // Chained, not replaced: a host's existing reporter (Crashlytics is
+        // configured before this runs) keeps receiving every exception after we
+        // record it. See ScaleBunExceptionChain.
+        ScaleBunExceptionChain.install { exception in
+            let stack = exception.callStackSymbols
+            var data: [String: Any] = [
+                "name": "crash.native",
+                "exceptionType": exception.name.rawValue,
+                "message": exception.reason ?? "",
+                "stackTrace": stack,
+                "threadName": Thread.current.name ?? "unknown",
+                "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] = [:]
+                for (k, v) in userInfo {
+                    info["\(k)"] = "\(v)"
+                }
+                data["userInfo"] = info
+            }
+
+            if let jsonData = try? JSONSerialization.data(withJSONObject: data),
+               let jsonString = String(data: jsonData, encoding: .utf8) {
+                ScaleBunCrashStorage.write(jsonString)
+            }
+        }
+
+        // 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,
+            ScaleBunCrashStorage.sessionMarkerPathCString,
+            ScaleBunCrashStorage.sessionTmpPathCString
+        )
+    }
+
+    /** For testing only — resets the installed flag. */
+    @objc static func resetForTest() {
+        installed = false
+        ScaleBunExceptionChain.uninstallForTest()
+    }
+}

package/ios/Crash/ScaleBunCrashModule.swift

@@ -0,0 +1,98 @@
+import Foundation
+import React
+
+/**
+ * React Native bridge for native crash capture (iOS).
+ *
+ * Backward-compatible across architectures. The Swift class holds the methods;
+ * registration + (on the New Architecture) the TurboModule provider live in the
+ * ObjC++ bridge `ScaleBunCrashBridge.mm`. All capture logic stays in
+ * `ScaleBunCrashHandler` / `ScaleBunCrashStorage` — this is thin glue only.
+ *
+ * Selectors are pinned with explicit `@objc(name:reject:)` so they match the
+ * React Native Codegen-generated `NativeScaleBunCrashSpec` protocol (which uses
+ * `reject:`, not `rejecter:`) on the New Architecture, and the
+ * `RCT_EXTERN_METHOD` declarations in the bridge on the Old Architecture.
+ *
+ * Methods:
+ *   install()            — installs NSSetUncaughtExceptionHandler + signal handlers
+ *   drainPendingCrash()  — returns crash from previous run (or null), then clears it
+ *   crashNow()           — DEV/TEST: raises an uncaught NSException so the
+ *                          installed handler captures + persists it, then dies
+ */
+@objc(ScaleBunCrash)
+class ScaleBunCrashModule: NSObject, RCTBridgeModule {
+
+    static func moduleName() -> String! { "ScaleBunCrash" }
+
+    @objc static func requiresMainQueueSetup() -> Bool { false }
+
+    @objc(install:reject:)
+    func install(_ resolve: @escaping RCTPromiseResolveBlock,
+                 reject: @escaping RCTPromiseRejectBlock) {
+        ScaleBunCrashHandler.install()
+        resolve(true)
+    }
+
+    @objc(crashNow:reject:)
+    func crashNow(_ resolve: @escaping RCTPromiseResolveBlock,
+                  reject: @escaping RCTPromiseRejectBlock) {
+        // Resolve first — JS won't be reachable once the process dies.
+        resolve(true)
+        // Raise an uncaught exception; NSSetUncaughtExceptionHandler persists it
+        // and the process terminates (real native crash).
+        DispatchQueue.main.async {
+            NSException(
+                name: NSExceptionName("ScaleBunTestNativeCrash"),
+                reason: "ScaleBun test native crash (iOS)",
+                userInfo: nil
+            ).raise()
+        }
+    }
+
+    /**
+     * 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) {
+        guard let crash = ScaleBunCrashStorage.read() else {
+            resolve(nil)
+            return
+        }
+        ScaleBunCrashStorage.clear()
+
+        // Ensure required fields are present; fill defaults if partial (e.g. signal crashes)
+        var result = crash
+        if result["name"] == nil { result["name"] = "crash.native" }
+        if result["platform"] == nil { result["platform"] = "ios" }
+
+        resolve(result)
+    }
+
+    /**
+     * Persist a FATAL JS crash to the same store native crashes use.
+     *
+     * Blocking synchronous: the write must land on disk before the fatal JS
+     * handler returns and the process dies. drainPendingCrash reads it back on
+     * the next launch like any native crash. Returns a boolean to JS.
+     */
+    @objc(persistJsCrash:)
+    func persistJsCrash(_ recordJson: NSString) -> NSNumber {
+        let s = recordJson as String
+        if s.isEmpty { return NSNumber(value: false) }
+        ScaleBunCrashStorage.write(s)
+        return NSNumber(value: true)
+    }
+}

package/ios/Crash/ScaleBunCrashSignalBridge.h

@@ -0,0 +1,49 @@
+#pragma once
+#include <stdint.h>
+
+/**
+ * Installs async-signal-safe C-level signal handlers for fatal signals.
+ *
+ * Signals handled: SIGABRT, SIGBUS, SIGSEGV, SIGILL, SIGFPE.
+ * Each handler writes a minimal JSON record to crashFilePath using only
+ * async-signal-safe syscalls (open, write, close), then restores the
+ * previous handler and re-raises the signal.
+ *
+ * No stack walking is performed in the signal handler — this would require
+ * PLCrashReporter or equivalent to be safe.
+ *
+ * @param crashFilePath  Null-terminated C string. Must remain valid for the
+ *                       lifetime of the process (use a static buffer).
+ */
+/**
+ * @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);

package/ios/Crash/ScaleBunCrashSignalBridge.m

@@ -0,0 +1,296 @@
+/**
+ * ScaleBunCrashSignalBridge — C-level fatal signal handlers.
+ *
+ * SAFETY CONTRACT:
+ * All code in signal handlers below uses ONLY async-signal-safe operations:
+ *   open(2), write(2), close(2), signal(3), raise(3).
+ * No malloc, no ObjC runtime, no Swift runtime, no stdio.
+ *
+ * LIMITATION:
+ * Stack traces are NOT captured in signal handlers. For symbolicated stacks,
+ * integrate PLCrashReporter (https://github.com/microsoft/plcrashreporter).
+ */
+
+#include "ScaleBunCrashSignalBridge.h"
+#include <signal.h>
+#include <fcntl.h>
+#include <unistd.h>
+#include <string.h>
+#include <time.h>
+#include <stdlib.h>
+
+// ─── Statics (set once at install time, read-only after) ────────────────────
+
+static const char *scalebun_crash_path = NULL;
+
+/**
+ * The active session id, published as a FILE and read back through the filesystem.
+ *
+ * ── WHY NOT A SHARED BUFFER ────────────────────────────────────────────────────────────────────
+ *
+ * The previous version of this file kept the id in a static char array and published its length
+ * last through a `volatile sig_atomic_t`, arguing that a handler therefore saw either the old id or
+ * the new one. THAT ARGUMENT WAS WRONG, and the counter-example is short:
+ *
+ *   published:  "sess-AAAAAAAAAAAAAAAA"   len = 21
+ *   setter begins overwriting IN PLACE with "sess-BBBBBBBBBBBBBBBB" (same length)
+ *   signal arrives after 3 bytes           buffer = "sess-BBBAAAAAAAAAAAAA"
+ *   len is UNCHANGED and still valid  →    handler emits the torn id
+ *
+ * Publishing the length last only orders the length against the bytes. It does nothing when the new
+ * id is the same length as the old one — which is the normal case, since every session id here is
+ * `sess-` plus a UUID. Modelled over every interrupt point, 15 of 22 tore.
+ *
+ * `volatile sig_atomic_t` guarantees atomic access to THAT SCALAR. It says nothing about the
+ * ordinary `char[]` beside it. C11 7.14.1.1p5 is stricter still: inside a handler, the only objects
+ * a program may access are lock-free atomics and objects of type `volatile sig_atomic_t`. Reading a
+ * concurrently-modified ordinary array is undefined behaviour regardless of how it is ordered.
+ *
+ * A double buffer does not fix this either: with two slots, the third publication overwrites the
+ * slot a handler may still be reading. More slots widen the window without closing it, because
+ * nothing tells the publisher when a handler has finished.
+ *
+ * ── WHY A FILE IS ACTUALLY SAFE ────────────────────────────────────────────────────────────────
+ *
+ * The publisher writes a temp file and `rename(2)`s it over the marker. POSIX requires rename to be
+ * ATOMIC: a concurrent `open(2)` resolves to either the old inode or the new one, and each contains
+ * one complete id. There is no state shared between publisher and handler at all — no buffer, no
+ * length, no flag — so there is nothing to tear.
+ *
+ * That property is also what makes it correct ACROSS THREADS. A buffer scheme only reasons about a
+ * signal interrupting the publishing thread; this one holds even when the signal is delivered to a
+ * different thread while another is mid-publication, because the two never touch the same memory.
+ *
+ * The handler pays one extra open/read/close. It already performs open/write/close for the crash
+ * record itself, so this adds no new class of operation — see the safety table in the header.
+ */
+#define SCALEBUN_SESSION_MAX 128
+
+/* Set once at install, read-only afterwards — never mutated while a handler could run. */
+static const char *scalebun_session_marker_path = NULL;
+static const char *scalebun_session_tmp_path = NULL;
+
+static struct sigaction scalebun_prev_sigabrt;
+static struct sigaction scalebun_prev_sigbus;
+static struct sigaction scalebun_prev_sigsegv;
+static struct sigaction scalebun_prev_sigill;
+static struct sigaction scalebun_prev_sigfpe;
+
+// ─── Async-signal-safe integer serializer ───────────────────────────────────
+
+/* Writes decimal representation of n into buf, returns bytes written. */
+static int scalebun_itoa(char *buf, long long n) {
+    if (n == 0) { buf[0] = '0'; return 1; }
+    int i = 0;
+    long long tmp = n;
+    while (tmp > 0) { buf[i++] = '0' + (tmp % 10); tmp /= 10; }
+    // reverse
+    for (int j = 0, k = i - 1; j < k; j++, k--) {
+        char t = buf[j]; buf[j] = buf[k]; buf[k] = t;
+    }
+    return i;
+}
+
+// ─── Write minimal crash record ─────────────────────────────────────────────
+
+static void scalebun_write_signal_crash(int sig) {
+    if (!scalebun_crash_path) return;
+
+    int fd = open(scalebun_crash_path, O_WRONLY | O_CREAT | O_TRUNC, 0600);
+    if (fd < 0) return;
+
+    // Build: {"name":"crash.native","signal":<sig>,"platform":"ios","timestamp":<ms>}
+    // All strings are compile-time constants — no heap allocation.
+    char sigbuf[8];
+    int siglen = scalebun_itoa(sigbuf, (long long)sig);
+
+    // Timestamp in milliseconds using clock_gettime (async-signal-safe on Darwin)
+    struct timespec ts;
+    clock_gettime(CLOCK_REALTIME, &ts);
+    long long ms = (long long)ts.tv_sec * 1000LL + ts.tv_nsec / 1000000LL;
+    char tsbuf[24];
+    int tslen = scalebun_itoa(tsbuf, ms);
+
+    /*
+     * Literal lengths computed at COMPILE time, not by strlen.
+     *
+     * strlen is not on the POSIX async-signal-safe list. Calling it only on string literals is
+     * defensible in practice — it is a pure read of immutable memory — but "defensible in practice"
+     * is exactly the kind of reasoning that produced the torn buffer this file used to have. sizeof
+     * on a char array removes the call and the argument along with it.
+     */
+    static const char prefix[] = "{\"name\":\"crash.native\",\"signal\":";
+    static const char mid[]    = ",\"platform\":\"ios\",\"timestamp\":";
+    static const char sidkey[] = ",\"sessionId\":\"";
+    static const char cidkey[] = ",\"crashId\":\"sig-";
+    static const char quote[]  = "\"";
+    static const char suffix[] = "}";
+
+    write(fd, prefix, sizeof(prefix) - 1);
+    write(fd, sigbuf, (size_t)siglen);
+    write(fd, mid,    sizeof(mid) - 1);
+    write(fd, tsbuf,  (size_t)tslen);
+
+    /*
+     * Session id — read from the marker file into a STACK buffer.
+     *
+     * open/read/close are async-signal-safe, the buffer is automatic storage (no allocation), and
+     * no mutable global is touched. Because the publisher installs the marker with rename(2), this
+     * open resolves to a single complete id: either the previous one or the new one, never a mix.
+     *
+     * The publisher guarantees the bytes are already JSON-safe, so nothing is escaped here —
+     * escaping arbitrary input inside a signal handler would be solving a problem we can avoid
+     * having.
+     */
+    if (scalebun_session_marker_path) {
+        char sidbuf[SCALEBUN_SESSION_MAX];
+        int sfd = open(scalebun_session_marker_path, O_RDONLY);
+        if (sfd >= 0) {
+            ssize_t n = read(sfd, sidbuf, sizeof(sidbuf));
+            close(sfd);
+            if (n > 0) {
+                write(fd, sidkey, sizeof(sidkey) - 1);
+                write(fd, sidbuf, (size_t)n);
+                write(fd, quote, sizeof(quote) - 1);
+            }
+        }
+    }
+
+    /*
+     * A STABLE crash id, so a signal crash gets the same at-least-once retry protection as every
+     * other crash. Derived from the timestamp already computed above — no allocation, no RNG, and
+     * identical on every read of this file, which is what the backend dedupes on.
+     */
+    write(fd, cidkey, sizeof(cidkey) - 1);
+    write(fd, tsbuf, (size_t)tslen);
+    write(fd, quote, sizeof(quote) - 1);
+
+    write(fd, suffix, sizeof(suffix) - 1);
+    close(fd);
+}
+
+// ─── Individual signal handlers ─────────────────────────────────────────────
+
+static void scalebun_handle_sigabrt(int sig) {
+    scalebun_write_signal_crash(sig);
+    sigaction(SIGABRT, &scalebun_prev_sigabrt, NULL);
+    raise(sig);
+}
+
+static void scalebun_handle_sigbus(int sig) {
+    scalebun_write_signal_crash(sig);
+    sigaction(SIGBUS, &scalebun_prev_sigbus, NULL);
+    raise(sig);
+}
+
+static void scalebun_handle_sigsegv(int sig) {
+    scalebun_write_signal_crash(sig);
+    sigaction(SIGSEGV, &scalebun_prev_sigsegv, NULL);
+    raise(sig);
+}
+
+static void scalebun_handle_sigill(int sig) {
+    scalebun_write_signal_crash(sig);
+    sigaction(SIGILL, &scalebun_prev_sigill, NULL);
+    raise(sig);
+}
+
+static void scalebun_handle_sigfpe(int sig) {
+    scalebun_write_signal_crash(sig);
+    sigaction(SIGFPE, &scalebun_prev_sigfpe, NULL);
+    raise(sig);
+}
+
+// ─── Install ─────────────────────────────────────────────────────────────────
+
+/**
+ * Publish the active session id for the signal handler to read.
+ *
+ * Called from normal code (the main thread, once per session) — NOT from a signal handler. All the
+ * unsafe work happens here, where it is safe, so the handler is left with a read and a write.
+ *
+ * SANITISED HERE, ON PURPOSE. Anything that is not `[A-Za-z0-9_.:-]` is dropped, which makes the
+ * stored bytes valid inside a JSON string with no escaping. That is what lets the handler emit them
+ * directly: escaping in a signal handler would mean branching over arbitrary input to solve a
+ * problem we can simply not have. Session ids are `sess-<uuid>`, so nothing legitimate is lost.
+ *
+ * Over-long ids are TRUNCATED rather than rejected — a truncated id is still a strong hint for a
+ * human, and refusing to publish would silently return to the un-attributed behaviour.
+ */
+void ScaleBunCrashSignalBridgeSetSessionId(const char *sessionId) {
+    if (!scalebun_session_marker_path || !scalebun_session_tmp_path) return;
+
+    if (sessionId == NULL) {
+        unlink(scalebun_session_marker_path);
+        return;
+    }
+
+    /*
+     * Sanitise into a local buffer. Restricted to [A-Za-z0-9_.:-] so the stored bytes are valid
+     * inside a JSON string with no escaping — which is what lets the handler emit them directly.
+     * Session ids are `sess-<uuid>`, so nothing legitimate is lost. Over-long ids are truncated
+     * rather than rejected: a truncated id still identifies the session to a human, whereas
+     * refusing to publish would silently return to unattributed crashes.
+     */
+    char clean[SCALEBUN_SESSION_MAX];
+    int out = 0;
+    for (int i = 0; sessionId[i] != '\0' && out < SCALEBUN_SESSION_MAX; i++) {
+        char c = sessionId[i];
+        int ok = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
+                 (c >= '0' && c <= '9') || c == '-' || c == '_' || c == '.' || c == ':';
+        if (ok) clean[out++] = c;
+    }
+    if (out == 0) {
+        unlink(scalebun_session_marker_path);
+        return;
+    }
+
+    /*
+     * WRITE THEN RENAME — this is the whole safety argument.
+     *
+     * The temp file is written and closed completely before it is visible under the marker name.
+     * `rename(2)` is required by POSIX to be atomic, so a handler's `open` of the marker resolves
+     * to exactly one inode: the previous complete id, or the new complete id. A partially written
+     * file is never reachable under that name.
+     *
+     * Runs on a normal thread, so none of this needs to be async-signal-safe — only the READ side
+     * does. That asymmetry is the point: all the delicate work happens where delicacy is allowed.
+     */
+    int fd = open(scalebun_session_tmp_path, O_WRONLY | O_CREAT | O_TRUNC, 0600);
+    if (fd < 0) return;
+    ssize_t written = write(fd, clean, (size_t)out);
+    close(fd);
+    if (written != (ssize_t)out) {
+        // A short or failed write must not be promoted to the marker — the old id is better than a
+        // truncated new one, and leaving the marker untouched keeps it.
+        unlink(scalebun_session_tmp_path);
+        return;
+    }
+    rename(scalebun_session_tmp_path, scalebun_session_marker_path);
+}
+
+void ScaleBunCrashSignalBridgeInstall(const char *crashFilePath,
+                                      const char *sessionMarkerPath,
+                                      const char *sessionTmpPath) {
+    scalebun_crash_path = crashFilePath;
+    // Captured once and read-only afterwards, so the handler never dereferences changing state.
+    scalebun_session_marker_path = sessionMarkerPath;
+    scalebun_session_tmp_path = sessionTmpPath;
+
+    struct sigaction sa;
+    memset(&sa, 0, sizeof(sa));
+    sigemptyset(&sa.sa_mask);
+    sa.sa_flags = SA_RESETHAND; // restore default after first signal
+
+#define INSTALL(signo, handler, prev) \
+    sa.sa_handler = (handler); \
+    sigaction((signo), &sa, &(prev));
+
+    INSTALL(SIGABRT, scalebun_handle_sigabrt, scalebun_prev_sigabrt)
+    INSTALL(SIGBUS,  scalebun_handle_sigbus,  scalebun_prev_sigbus)
+    INSTALL(SIGSEGV, scalebun_handle_sigsegv, scalebun_prev_sigsegv)
+    INSTALL(SIGILL,  scalebun_handle_sigill,  scalebun_prev_sigill)
+    INSTALL(SIGFPE,  scalebun_handle_sigfpe,  scalebun_prev_sigfpe)
+
+#undef INSTALL
+}