@onekeyfe/react-native-background-thread 3.0.31 → 3.0.32

package/android/src/main/cpp/cpp-adapter.cpp

@@ -586,6 +586,28 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeSetupErrorHandler(
     }
 }
 
+// ── nativeInvalidateSharedRpc ───────────────────────────────────────────
+// Synchronously quiesce the SharedRPC listener for a given runtimeId before
+// the underlying JS runtime is torn down. Called from
+// BackgroundThreadManager.restart() ahead of process restart / soft reload
+// so any cross-runtime executor lambda still in flight short-circuits
+// instead of dispatching onto a dying runtime (parity with iOS).
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_backgroundthread_BackgroundThreadManager_nativeInvalidateSharedRpc(
+    JNIEnv *env, jobject thiz, jstring runtimeId) {
+
+    const char *idChars = env->GetStringUTFChars(runtimeId, nullptr);
+    if (!idChars) {
+        return JNI_FALSE;
+    }
+    std::string id(idChars);
+    env->ReleaseStringUTFChars(runtimeId, idChars);
+
+    bool found = SharedRPC::invalidate(id);
+    LOGI("nativeInvalidateSharedRpc: id=%s found=%d", id.c_str(), found ? 1 : 0);
+    return found ? JNI_TRUE : JNI_FALSE;
+}
+
 // ── nativeDestroy ───────────────────────────────────────────────────────
 // Clean up native resources.
 // Called from BackgroundThreadManager.destroy().

package/android/src/main/java/com/backgroundthread/BackgroundThreadManager.kt

@@ -5,6 +5,8 @@ import android.content.Intent
 import android.net.Uri
 import android.os.Handler
 import android.os.Looper
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactHost
 import com.facebook.react.ReactPackage
 import com.facebook.proguard.annotations.DoNotStrip
 import com.facebook.react.ReactInstanceEventListener
@@ -21,6 +23,7 @@ import com.facebook.react.runtime.hermes.HermesInstance
 import com.facebook.react.shell.MainReactPackage
 import java.io.File
 import java.lang.ref.WeakReference
+import java.util.concurrent.TimeUnit
 
 /**
  * Singleton manager for the background React Native runtime.
@@ -47,6 +50,14 @@ class BackgroundThreadManager private constructor() {
     @Volatile
     private var mainRuntimePtr: Long = 0
     private var mainReactContext: ReactApplicationContext? = null
+
+    // Captured lazily on the first installSharedBridgeInMainRuntime() call.
+    // Used by restart(mode='ui') to soft-reload the main runtime via
+    // ReactHost.reload(reason) so the bg runtime stays hot. Null when the
+    // host app is not on bridgeless / NewArch — restart() falls back to a
+    // full process restart in that case.
+    @Volatile
+    private var mainReactHost: ReactHost? = null
     private var isStarted = false
 
     companion object {
@@ -74,6 +85,14 @@ class BackgroundThreadManager private constructor() {
     private external fun nativeDestroy()
     private external fun nativeExecuteWork(runtimePtr: Long, workId: Long)
 
+    /**
+     * Synchronously mark the SharedRPC listener for `runtimeId` as dead
+     * before the underlying JS runtime is torn down. See
+     * SharedRPC::invalidate (cpp/SharedRPC.cpp) for the cross-runtime
+     * correctness rationale.
+     */
+    private external fun nativeInvalidateSharedRpc(runtimeId: String): Boolean
+
     // ── SharedBridge ────────────────────────────────────────────────────────
 
     /**
@@ -86,6 +105,23 @@ class BackgroundThreadManager private constructor() {
 
     fun installSharedBridgeInMainRuntime(context: ReactApplicationContext) {
         mainReactContext = context
+        // Capture the host the first time we see it; reload() needs it. We
+        // resolve via ReactApplication.reactHost — non-null only on bridgeless
+        // / NewArch builds. Bound here (not in restart()) because installShared
+        // Bridge is invoked from JS bootstrap, which is also when ReactContext
+        // is guaranteed live. Restart('ui') falls back to process restart if
+        // this stays null.
+        if (mainReactHost == null) {
+            try {
+                val app = context.applicationContext as? ReactApplication
+                mainReactHost = app?.reactHost
+                if (mainReactHost == null) {
+                    BTLogger.warn("ReactHost unavailable (non-bridgeless host?); restart('ui') will fall back to process restart")
+                }
+            } catch (t: Throwable) {
+                BTLogger.error("Failed to resolve ReactHost: ${t.message}")
+            }
+        }
         context.runOnJSQueueThread {
             try {
                 val ptr = context.javaScriptContextHolder?.get() ?: 0L
@@ -754,6 +790,180 @@ class BackgroundThreadManager private constructor() {
         }
     }
 
+    // ── Restart ─────────────────────────────────────────────────────────────
+    //
+    // Replaces direct use of `react-native-restart` from JS. The native module
+    // is the only piece that has visibility into BOTH the main and background
+    // ReactHost lifecycles, so it can sequence:
+    //   1. SharedRPC quiesce (mark listener alive=false, leak callback, drop
+    //      executor) — synchronous, holds SharedRPC mutex internally
+    //   2. JS runtime teardown — see per-mode behaviour below
+    //
+    // mode='ui':
+    //   Soft-reload the main runtime via ReactHost.reload(reason). bg runtime
+    //   keeps running. After reload, JS bootstrap re-invokes installShared
+    //   Bridge() (the TurboModule entry point), which re-installs the "main"
+    //   SharedRPC listener and refreshes mainRuntimePtr. Requires bridgeless /
+    //   NewArch — if ReactHost was never captured (old arch host), falls back
+    //   to a process restart so callers get consistent reload semantics.
+    //
+    // mode='all':
+    //   Process-level restart (Runtime.exit + makeRestartActivityTask). OTA
+    //   install/switch and resetData want a clean slate on disk; a process
+    //   relaunch trivially guarantees both runtimes bootstrap from fresh
+    //   bundle content without us having to sequence "tear down bg → reload
+    //   main → wait for new main → restart bg". iOS goes through soft reload
+    //   for mode='all' because abrupt termination is App Store-unfriendly and
+    //   iOS has no clean self-relaunch; Android does, so we keep using it.
+
+    fun restart(context: ReactApplicationContext, mode: String, reason: String, promise: com.facebook.react.bridge.Promise) {
+        val isUi = mode == "ui"
+        val isAll = mode == "all"
+        if (!isUi && !isAll) {
+            promise.reject(
+                "BG_RESTART_ERROR",
+                "BackgroundThread.restart: unsupported mode '$mode', expected 'ui' or 'all'"
+            )
+            return
+        }
+
+        BTLogger.info("restart: mode=$mode reason=$reason")
+
+        try {
+            nativeInvalidateSharedRpc("main")
+            if (isAll) {
+                nativeInvalidateSharedRpc("background")
+            }
+        } catch (t: Throwable) {
+            // Invalidate is best-effort; not fatal if the JNI call somehow
+            // throws (e.g. so library not loaded yet). Continue to restart.
+            BTLogger.error("restart: SharedRPC invalidate failed: ${t.message}")
+        }
+
+        val host = mainReactHost
+        if (isUi && host != null) {
+            BTLogger.info("restart(ui): soft reload via ReactHost.reload")
+            // Post to the UI thread to keep the call off the JS thread that
+            // is about to be torn down; ReactHost.reload is itself thread-
+            // safe but the work it kicks off (JNI teardown of the old
+            // ReactInstance) is cleaner when not initiated from inside the
+            // outgoing runtime's callback frame.
+            //
+            // Promise resolution is sequenced after reload() returns. The
+            // actual *delivery* of that resolve to JS is best-effort: the
+            // CallInvoker that would route it back is tied to the outgoing
+            // ReactInstance which reload() is about to invalidate, and the
+            // typical caller is `await restart(...)` whose continuation
+            // never runs because the reload supersedes it. The position
+            // matters only for the synchronous-throw case — if reload()
+            // throws inline, the catch block reaches the fallback / reject
+            // path instead of misreporting success.
+            //
+            // ReactHost.reload(reason) returns a TaskInterface<Void> that
+            // completes when the new ReactInstance is up; an async fault
+            // means reload failed AFTER we already invalidated the
+            // SharedRPC main listener — main runtime is torn down without
+            // rebuild, SharedRPC is permanently dead for "main". Watch the
+            // task on a daemon thread and fall back to a process restart
+            // on fault / cancellation / timeout so we converge on a known
+            // good state instead of leaving the app wedged. TaskInterface
+            // only exposes waitForCompletion + isFaulted/isCancelled/
+            // getError (no continueWith/onError callback in RN 0.83's
+            // public surface), so polling on a worker thread is what we
+            // have. Timeout is generous (15s) — observed worst case
+            // reload on a low-end Android is ~3s.
+            Handler(Looper.getMainLooper()).post {
+                val task = try {
+                    host.reload("BackgroundThread.restart(ui): $reason").also {
+                        promise.resolve(null)
+                    }
+                } catch (t: Throwable) {
+                    BTLogger.error("restart(ui): ReactHost.reload threw synchronously: ${t.message}")
+                    if (!triggerProcessRestart(context)) {
+                        promise.reject(
+                            "BG_RESTART_ERROR",
+                            "restart(ui): reload failed and process restart fallback also failed: ${t.message}",
+                            t,
+                        )
+                    }
+                    // if triggerProcessRestart returned true, Runtime.exit(0)
+                    // ran and this reject is unreachable
+                    null
+                }
+                if (task != null) {
+                    Thread {
+                        try {
+                            val completed = task.waitForCompletion(15, TimeUnit.SECONDS)
+                            if (!completed || task.isFaulted() || task.isCancelled()) {
+                                val err = task.getError()
+                                BTLogger.error(
+                                    "restart(ui): reload task did not complete cleanly " +
+                                            "(completed=$completed, faulted=${task.isFaulted()}, " +
+                                            "cancelled=${task.isCancelled()}): ${err?.message} — " +
+                                            "falling back to process restart"
+                                )
+                                Handler(Looper.getMainLooper()).post {
+                                    triggerProcessRestart(context)
+                                }
+                            } else {
+                                BTLogger.info("restart(ui): reload task completed successfully")
+                            }
+                        } catch (t: Throwable) {
+                            BTLogger.error(
+                                "restart(ui): reload-task watch thread errored: ${t.message} — " +
+                                        "falling back to process restart"
+                            )
+                            Handler(Looper.getMainLooper()).post {
+                                triggerProcessRestart(context)
+                            }
+                        }
+                    }.apply {
+                        isDaemon = true
+                        name = "OneKey-BgThread-ReloadWatch"
+                        start()
+                    }
+                }
+            }
+            return
+        }
+
+        if (isUi) {
+            BTLogger.warn("restart(ui): ReactHost unavailable, falling back to process restart")
+        }
+        if (!triggerProcessRestart(context)) {
+            promise.reject(
+                "BG_RESTART_ERROR",
+                "Failed to trigger process restart (intent resolution or startActivity failed)"
+            )
+        }
+        // if triggerProcessRestart returned true, Runtime.exit(0) ran and
+        // any further code here is unreachable
+    }
+
+    /**
+     * Returns true if Runtime.exit(0) was reached (in which case the process
+     * is now terminating and any code after the call site is unreachable).
+     * Returns false if intent resolution failed or startActivity threw
+     * before exit() — caller is responsible for propagating that failure
+     * to the JS Promise so callers don't observe a false success.
+     */
+    private fun triggerProcessRestart(context: ReactApplicationContext): Boolean {
+        try {
+            val intent = context.packageManager.getLaunchIntentForPackage(context.packageName)
+            if (intent == null) {
+                BTLogger.error("triggerProcessRestart: launch intent not found for ${context.packageName}")
+                return false
+            }
+            val mainIntent = Intent.makeRestartActivityTask(intent.component)
+            context.startActivity(mainIntent)
+            Runtime.getRuntime().exit(0)
+            return true // unreachable; exit() does not return
+        } catch (t: Throwable) {
+            BTLogger.error("triggerProcessRestart: ${t.message}")
+            return false
+        }
+    }
+
     // ── Lifecycle ───────────────────────────────────────────────────────────
 
     val isBackgroundStarted: Boolean get() = isStarted
@@ -763,6 +973,7 @@ class BackgroundThreadManager private constructor() {
         bgRuntimePtr = 0
         mainRuntimePtr = 0
         mainReactContext = null
+        mainReactHost = null
         bgReactHost?.destroy("BackgroundThreadManager destroyed", null)
         bgReactHost = null
         isStarted = false

package/android/src/main/java/com/backgroundthread/BackgroundThreadModule.kt

@@ -38,4 +38,8 @@ class BackgroundThreadModule(reactContext: ReactApplicationContext) :
                 }
             }
     }
+
+    override fun restart(mode: String, reason: String, promise: Promise) {
+        BackgroundThreadManager.getInstance().restart(reactApplicationContext, mode, reason, promise)
+    }
 }

package/cpp/SharedRPC.cpp

@@ -1,5 +1,7 @@
 #include "SharedRPC.h"
 
+#include <algorithm>
+
 #ifdef __ANDROID__
 #include <android/log.h>
 #define RPC_LOG(...) __android_log_print(ANDROID_LOG_INFO, "SharedRPC", __VA_ARGS__)
@@ -23,24 +25,68 @@ void SharedRPC::install(jsi::Runtime &rt, RPCRuntimeExecutor executor,
   auto obj = jsi::Object::createFromHostObject(rt, rpc);
   rt.global().setProperty(rt, "sharedRPC", std::move(obj));
 
+  auto alive = std::make_shared<std::atomic<bool>>(true);
+
+  std::lock_guard<std::mutex> lock(mutex_);
+  // Defensive dedup: under the normal restart flow, invalidate() has already
+  // run for this runtimeId and erased the entry, so this loop matches
+  // nothing. The branch survives as a fallback for any path that re-installs
+  // without first calling invalidate (e.g. legacy host integrations, partial
+  // teardown). Same correctness invariants as invalidate(): flip alive=false
+  // so any executor lambda already in flight short-circuits, and leak the
+  // jsi::Function callback because destroying it on a wrong/dying thread
+  // crashes (null deref in Pointer::~Pointer).
+  for (auto &listener : listeners_) {
+    if (listener.runtimeId == runtimeId) {
+      if (listener.alive) {
+        listener.alive->store(false);
+      }
+      if (listener.callback) {
+        new std::shared_ptr<jsi::Function>(std::move(listener.callback));
+      }
+    }
+  }
+  listeners_.erase(
+      std::remove_if(listeners_.begin(), listeners_.end(),
+                     [&runtimeId](const RuntimeListener &l) {
+                       return l.runtimeId == runtimeId;
+                     }),
+      listeners_.end());
+  listeners_.push_back(
+      {runtimeId, &rt, std::move(executor), nullptr, std::move(alive)});
+}
+
+bool SharedRPC::invalidate(const std::string &runtimeId) {
   std::lock_guard<std::mutex> lock(mutex_);
-  // Remove any existing listener with the same runtimeId (reload scenario).
-  // IMPORTANT: The old listener's callback is a jsi::Function tied to the old
-  // runtime. On reload, that runtime is already destroyed, so calling
-  // ~jsi::Function() would crash (null deref in Pointer::~Pointer).
-  // We intentionally leak the callback to avoid this.
+  bool found = false;
   for (auto &listener : listeners_) {
-    if (listener.runtimeId == runtimeId && listener.callback) {
+    if (listener.runtimeId != runtimeId) continue;
+    if (listener.alive) {
+      listener.alive->store(false);
+    }
+    if (listener.callback) {
+      // Same rationale as install(): destroying a jsi::Function tied to a
+      // torn-down runtime crashes. Leak it; the runtime is going away anyway.
       new std::shared_ptr<jsi::Function>(std::move(listener.callback));
     }
+    // Drop the executor closure so nothing tries to dispatch via the dying
+    // RCTInstance/CallInvoker after this point.
+    listener.executor = nullptr;
+    found = true;
   }
+  // Erase the dead entries. Already-dispatched executor lambdas hold their
+  // own shared_ptr<alive> snapshot, so erasing here does not affect them —
+  // it only prevents NEW notifyOtherRuntime() snapshots from picking up the
+  // dead listener. Without the erase, a mode='all' restart whose post-reload
+  // re-install never fires would leave a permanently-dead entry in the
+  // vector. The next install() for the same runtimeId pushes a fresh entry.
   listeners_.erase(
       std::remove_if(listeners_.begin(), listeners_.end(),
                      [&runtimeId](const RuntimeListener &l) {
                        return l.runtimeId == runtimeId;
                      }),
       listeners_.end());
-  listeners_.push_back({runtimeId, &rt, std::move(executor), nullptr});
+  return found;
 }
 
 void SharedRPC::reset() {
@@ -48,7 +94,12 @@ void SharedRPC::reset() {
   slots_.clear();
   // Intentionally leak jsi::Function callbacks to avoid destroying them on the
   // wrong thread (same rationale as the leak in install() for reload scenarios).
+  // Also flip alive=false so any executor lambda still in flight short-circuits
+  // before touching a torn-down runtime.
   for (auto &listener : listeners_) {
+    if (listener.alive) {
+      listener.alive->store(false);
+    }
     if (listener.callback) {
       new std::shared_ptr<jsi::Function>(std::move(listener.callback));
     }
@@ -59,25 +110,49 @@ void SharedRPC::reset() {
 void SharedRPC::notifyOtherRuntime(jsi::Runtime &callerRt, const std::string &callId) {
   // Collect executors and callbacks under lock, then invoke outside lock
   // to avoid deadlock (executor may schedule work that also acquires mutex_).
-  std::vector<std::pair<RPCRuntimeExecutor, std::shared_ptr<jsi::Function>>> toNotify;
+  //
+  // Each snapshot carries the listener's shared `alive` flag. The flag is
+  // checked twice — once here (so an already-invalidated listener is never
+  // even scheduled) and once again inside the dispatched lambda (so a
+  // listener invalidated AFTER snapshot but BEFORE the lambda runs is also
+  // short-circuited before touching the dying runtime).
+  struct Snapshot {
+    RPCRuntimeExecutor executor;
+    std::shared_ptr<jsi::Function> callback;
+    std::shared_ptr<std::atomic<bool>> alive;
+  };
+  std::vector<Snapshot> toNotify;
   {
     std::lock_guard<std::mutex> lock(mutex_);
     RPC_LOG("notifyOtherRuntime: callId=%s, listeners=%zu, callerRt=%p",
             callId.c_str(), listeners_.size(), &callerRt);
     for (auto &listener : listeners_) {
-      RPC_LOG("  listener: id=%s, rt=%p, hasCallback=%d",
-              listener.runtimeId.c_str(), listener.runtime, listener.callback != nullptr);
+      RPC_LOG("  listener: id=%s, rt=%p, hasCallback=%d, alive=%d",
+              listener.runtimeId.c_str(), listener.runtime,
+              listener.callback != nullptr,
+              listener.alive ? listener.alive->load() : 0);
       if (listener.runtime == &callerRt) continue;
       if (!listener.callback) continue;
-      toNotify.emplace_back(listener.executor, listener.callback);
+      if (!listener.executor) continue;
+      if (!listener.alive || !listener.alive->load()) continue;
+      toNotify.push_back({listener.executor, listener.callback, listener.alive});
     }
     RPC_LOG("  toNotify count: %zu", toNotify.size());
   }
 
-  for (auto &[executor, cb] : toNotify) {
+  for (auto &snap : toNotify) {
     auto id = callId;
     RPC_LOG("  invoking executor for callId=%s", id.c_str());
-    executor([cb, id](jsi::Runtime &rt) {
+    auto cb = snap.callback;
+    auto alive = snap.alive;
+    snap.executor([cb, alive, id](jsi::Runtime &rt) {
+      // Listener was invalidated between snapshot and dispatch — bail
+      // before calling into a runtime that may already be torn down.
+      if (!alive || !alive->load()) {
+        RPC_LOG("  executor work skipped (listener invalidated) for callId=%s",
+                id.c_str());
+        return;
+      }
       RPC_LOG("  executor work running for callId=%s", id.c_str());
       try {
         cb->call(rt, jsi::String::createFromUtf8(rt, id));

package/cpp/SharedRPC.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <jsi/jsi.h>
+#include <atomic>
 #include <functional>
 #include <memory>
 #include <mutex>
@@ -22,6 +23,11 @@ struct RuntimeListener {
   jsi::Runtime *runtime;
   RPCRuntimeExecutor executor;
   std::shared_ptr<jsi::Function> callback; // JS onWrite callback
+  // Liveness flag, shared with any executor lambda already in flight.
+  // Flipped to false by invalidate() (or by a follow-up install() that
+  // replaces this listener) so notifyOtherRuntime and any already-enqueued
+  // lambda can short-circuit before touching a torn-down runtime.
+  std::shared_ptr<std::atomic<bool>> alive;
 };
 
 class SharedRPC : public jsi::HostObject {
@@ -37,6 +43,14 @@ public:
   static void install(jsi::Runtime &rt, RPCRuntimeExecutor executor,
                       const std::string &runtimeId);
 
+  /// Synchronously quiesce the listener for runtimeId before the underlying
+  /// JS runtime is torn down. Marks alive=false (so any executor lambda
+  /// already in flight short-circuits), leaks the jsi::Function callback
+  /// (destroying it on a wrong/dying thread crashes), and clears the
+  /// executor closure (drops the lambda's captured RCTInstance/CallInvoker).
+  /// Safe to call from any thread. Returns true if a listener was found.
+  static bool invalidate(const std::string &runtimeId);
+
   static void reset();
 
 private:

package/ios/BackgroundRunnerReactNativeDelegate.mm

@@ -368,10 +368,18 @@ static NSURL *resolveBundleSourceURL(NSString *jsBundleSourceNS)
     // Install SharedStore into background runtime
     SharedStore::install(runtime);
 
-    // Install SharedRPC with executor for cross-runtime notifications
-    RCTInstance *bgInstance = _rctInstance;
-    RPCRuntimeExecutor bgExecutor = [bgInstance](std::function<void(jsi::Runtime &)> work) {
-        [bgInstance callFunctionOnBufferedRuntimeExecutor:[work](jsi::Runtime &rt) {
+    // Install SharedRPC with executor for cross-runtime notifications.
+    // Capture the bg RCTInstance __weak so executor lambdas still in flight
+    // when the bg host is torn down (BackgroundThread.restart mode=all,
+    // OTA bundle install) no-op cleanly instead of dispatching onto a
+    // freed instance and crashing.
+    __weak RCTInstance *weakBgInstance = _rctInstance;
+    RPCRuntimeExecutor bgExecutor = [weakBgInstance](std::function<void(jsi::Runtime &)> work) {
+        RCTInstance *strongBgInstance = weakBgInstance;
+        if (!strongBgInstance) {
+            return;
+        }
+        [strongBgInstance callFunctionOnBufferedRuntimeExecutor:[work](jsi::Runtime &rt) {
             work(rt);
         }];
     };

package/ios/BackgroundThread.h

@@ -9,5 +9,9 @@
                            path:(NSString *)path
                         resolve:(RCTPromiseResolveBlock)resolve
                          reject:(RCTPromiseRejectBlock)reject;
+- (void)restart:(NSString *)mode
+         reason:(NSString *)reason
+        resolve:(RCTPromiseResolveBlock)resolve
+         reject:(RCTPromiseRejectBlock)reject;
 
 @end

package/ios/BackgroundThread.mm

@@ -45,6 +45,22 @@
     }];
 }
 
+- (void)restart:(NSString *)mode
+         reason:(NSString *)reason
+        resolve:(RCTPromiseResolveBlock)resolve
+         reject:(RCTPromiseRejectBlock)reject {
+    BackgroundThreadManager *manager = [BackgroundThreadManager sharedInstance];
+    [manager restartWithMode:mode
+                      reason:reason
+                  completion:^(NSError * _Nullable error) {
+        if (error) {
+            reject(@"BG_RESTART_ERROR", error.localizedDescription, error);
+        } else {
+            resolve(nil);
+        }
+    }];
+}
+
 + (NSString *)moduleName
 {
   return @"BackgroundThread";

package/ios/BackgroundThreadManager.h

@@ -12,7 +12,14 @@ NS_ASSUME_NONNULL_BEGIN
 + (instancetype)sharedInstance;
 
 /// Install SharedBridge HostObject into the main (UI) runtime.
-/// Call this from your AppDelegate's ReactNativeDelegate hostDidStart: callback.
+///
+/// MUST be invoked from the host app's RCTReactNativeFactoryDelegate
+/// hostDidStart: callback on EVERY main RCTHost lifecycle start — including
+/// after a `BackgroundThread.restart` (both modes) reloads the main bridge.
+/// The module cannot self-invoke this because it does not own the RCTHost
+/// reference; restartWithMode: emits a loud error log if it detects this
+/// contract was violated post-reload.
+///
 /// @param host The RCTHost for the main runtime
 + (void)installSharedBridgeInMainRuntime:(RCTHost *)host;
 
@@ -23,8 +30,14 @@ NS_ASSUME_NONNULL_BEGIN
 /// @param entryURL The custom entry URL for the background runner
 - (void)startBackgroundRunnerWithEntryURL:(NSString *)entryURL;
 
-/// Check if background runner is started
-@property (nonatomic, readonly) BOOL isStarted;
+/// Check if background runner is started.
+///
+/// Atomic to match the implementation's redeclaration (the post-reload
+/// health-check reads this on the main thread while the start path writes
+/// it from whichever thread the caller is on). Keeping the header
+/// `nonatomic` while the impl was `atomic` tripped Clang's
+/// -Wproperty-attribute-mismatch and breaks CI builds under -Werror.
+@property (atomic, readonly) BOOL isStarted;
 
 /// Register a HBC segment in the background runtime (Phase 2.5 spike)
 /// @param segmentId The segment ID to register
@@ -34,6 +47,67 @@ NS_ASSUME_NONNULL_BEGIN
                                path:(NSString *)path
                          completion:(void (^)(NSError * _Nullable error))completion;
 
+/// Restart the JS runtime(s). Replaces direct use of `react-native-restart`.
+/// Coordinates SharedRPC quiesce + RCTReloadCommand so cross-runtime traffic
+/// in flight during reload is silently dropped instead of crashing on a
+/// torn-down RCTInstance / dangling jsi::Function callback.
+///
+/// ## Post-reload contract (host responsibility)
+///
+/// After `RCTTriggerReloadCommandListeners` rebuilds the main RCTHost, the
+/// host app's `RCTReactNativeFactoryDelegate.hostDidStart:` is responsible
+/// for re-arming BOTH halves of the integration on the new host:
+///   1. `+[BackgroundThreadManager installSharedBridgeInMainRuntime:newHost]`
+///      — re-arms the "main" SharedRPC listener; without this main→bg RPC
+///      silently breaks even though both runtimes are alive.
+///   2. (mode='all' only) `[BackgroundThreadManager.sharedInstance
+///      startBackgroundRunner]` — recreates the bg RCTHost since the
+///      previous one was released and `isStarted` was reset to NO.
+///
+/// The module defends against host integration omissions with a two-stage
+/// post-reload health-check (`dispatch_after` on the main queue scheduled
+/// before the reload is triggered — does NOT depend on
+/// `RCTJavaScriptDidLoadNotification`, which is unreliable in bridgeless /
+/// NewArch). Stage 1 fires ~3s after `restartWithMode:` returns; stage 2
+/// (if needed) ~3s later. The check decides:
+///   - Both halves healthy at stage 1 → log success, done.
+///   - Anything missing at stage 1 → reschedule stage 2 unconditionally.
+///     Earlier designs short-circuited the "main ready, bg not ready"
+///     case at stage 1 as a stable signal, but hosts that gate
+///     startBackgroundRunner on async work (feature flag, login, network)
+///     can be mainReady=YES while the real start call is still inflight;
+///     short-circuiting would race them and the host's late start would
+///     be silently dropped (now warn-logged on the early-return path).
+///   - Stage 2 → final verdict; whatever's missing is logged and self-
+///     healed where possible.
+///
+/// For mode='all' self-respawn, the module replays the host's last entry
+/// URL — cached in `startBackgroundRunnerWithEntryURL:` — instead of the
+/// default `background.bundle`. This is critical on OTA-equipped hosts:
+/// without the cache, self-respawn would load the bundled bg bundle from
+/// the IPA while main runs the OTA-updated main bundle, and the next
+/// cross-runtime RPC would moduleId-mismatch and crash. The cache makes
+/// self-respawn a true safety net for the broken-AppDelegate-wiring case.
+/// The bundled default name `"background.bundle"` is intentionally treated
+/// as "no real cache" by the self-respawn fallback so the OTA-mismatch
+/// warning still fires for hosts that initially bootstrapped with the
+/// default URL and never swapped to an OTA-resolved path.
+///
+/// Concurrent restart() calls are made safe via a monotonic generation
+/// counter: each invocation captures its own generation and each health-
+/// check stage bails if a newer restart() has superseded it.
+///
+/// @param mode `@"ui"` to reload only the main runtime (bg stays hot);
+///             `@"all"` to reload both. Any other value invokes completion
+///             with NSError domain `BackgroundThread` code 10.
+/// @param reason Free-form attribution string forwarded to
+///               RCTTriggerReloadCommandListeners and host logs.
+/// @param completion Invoked once the reload has been triggered. nil error
+///                   on success.
+- (void)restartWithMode:(NSString *)mode
+                 reason:(NSString *)reason
+             completion:(void (^)(NSError * _Nullable error))completion;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/BackgroundThreadManager.mm

@@ -17,6 +17,7 @@
 
 #include "SharedStore.h"
 #include "SharedRPC.h"
+#import <React/RCTReloadCommand.h>
 #import <ReactCommon/RCTHost.h>
 #import <objc/runtime.h>
 
@@ -24,9 +25,50 @@
 @property (nonatomic, strong) BackgroundReactNativeDelegate *reactNativeFactoryDelegate;
 @property (nonatomic, strong) RCTReactNativeFactory *reactNativeFactory;
 @property (nonatomic, assign) BOOL hasListeners;
-@property (nonatomic, assign, readwrite) BOOL isStarted;
+// Atomic because the post-reload health-check reads it on the main thread
+// while startBackgroundRunnerWithEntryURL: writes it from whichever thread
+// the caller is on (the module's public surface does not constrain caller
+// thread). Atomic gives us the memory-barrier needed for cross-thread
+// reads to see the latest store. The set+dispatch pattern in start... is
+// still TOCTOU-racy for concurrent first-time starts, but that hazard
+// pre-exists this PR and is out of scope here.
+@property (atomic, assign, readwrite) BOOL isStarted;
+// Flipped to YES inside the installSharedBridgeInMainRuntime: lambda and to
+// NO at the start of restartWithMode:. Read by the post-reload health-check
+// to detect when the host app's hostDidStart: failed to re-invoke the
+// install on the new RCTHost — which would silently break main→bg RPC.
+@property (atomic, assign) BOOL mainSharedBridgeInstalled;
+// Monotonic counter bumped on every restartWithMode: call. The post-reload
+// health-check captures its own generation and bails if a newer restart()
+// supersedes it, preventing the second restart's flag reset from making
+// the first restart's check misreport. Touched only on the main thread
+// (the dispatch_block_t `work` runs there), so non-atomic is correct.
+@property (nonatomic, assign) NSUInteger restartGeneration;
+// Cached from the most recent startBackgroundRunnerWithEntryURL: call. Used
+// by the mode='all' self-respawn fallback to preserve the host's last
+// chosen entry URL (typically an OTA-resolved bundle path) across restart;
+// `reactNativeFactoryDelegate` is released for mode='all', so without this
+// cache we'd fall back to the bundled "background.bundle" — which on OTA
+// devices is a moduleId-mismatch crash waiting to happen. Atomic for the
+// same reason as isStarted: written from the caller's thread (public API
+// doesn't pin start... to main) and read on main by the health-check.
+@property (atomic, copy) NSString *lastEntryURL;
+
+// Forward declaration so restartWithMode: can call it; definition lives
+// after restartWithMode: for readability (the call site is the natural
+// place to start reading the restart flow).
+- (void)scheduleHealthCheckForRestart:(NSString *)mode
+                                isAll:(BOOL)isAll
+                           generation:(NSUInteger)myGen
+                              retried:(BOOL)retried;
 @end
 
+// First-stage delay for the post-reload health-check. Picked so the host's
+// hostDidStart: chain has time to run on a typical device. On slower
+// devices the chain can exceed this; that's why the check is structured as
+// two stages — see scheduleHealthCheckForRestart:isAll:generation:retried:.
+static const NSTimeInterval kRestartHealthCheckDelaySeconds = 3.0;
+
 @implementation BackgroundThreadManager
 
 static BackgroundThreadManager *_sharedInstance = nil;
@@ -71,14 +113,28 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
     [instance callFunctionOnBufferedRuntimeExecutor:^(facebook::jsi::Runtime &runtime) {
         SharedStore::install(runtime);
 
-        // Install SharedRPC with executor for cross-runtime notifications
-        id capturedInstance = instance;
-        RPCRuntimeExecutor mainExecutor = [capturedInstance](std::function<void(jsi::Runtime &)> work) {
-            [capturedInstance callFunctionOnBufferedRuntimeExecutor:[work](jsi::Runtime &rt) {
+        // Install SharedRPC with executor for cross-runtime notifications.
+        // Capture the RCTInstance __weak: when the main host is torn down on
+        // reload (RNRestart / RCTReloadCommand / BackgroundThread.restart) the
+        // instance is dealloc'd, and any executor lambda still in flight will
+        // see a nil strong reference and bail out — instead of dispatching
+        // callFunctionOnBufferedRuntimeExecutor on a freed instance and
+        // crashing (EXC_BAD_ACCESS / use-after-free).
+        __weak id weakInstance = instance;
+        RPCRuntimeExecutor mainExecutor = [weakInstance](std::function<void(jsi::Runtime &)> work) {
+            id strongInstance = weakInstance;
+            if (!strongInstance) {
+                return;
+            }
+            [strongInstance callFunctionOnBufferedRuntimeExecutor:[work](jsi::Runtime &rt) {
                 work(rt);
             }];
         };
         SharedRPC::install(runtime, std::move(mainExecutor), "main");
+        // Set the integration-health flag from inside the JS-thread lambda so
+        // it only flips true AFTER the listener is actually live; the post-
+        // reload observer reads this to detect host hostDidStart: omissions.
+        [BackgroundThreadManager sharedInstance].mainSharedBridgeInstalled = YES;
         [BTLogger info:@"SharedStore and SharedRPC installed in main runtime"];
     }];
 }
@@ -96,9 +152,27 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
 
 - (void)startBackgroundRunnerWithEntryURL:(NSString *)entryURL {
     if (self.isStarted) {
+        // Surface the URL mismatch when a second start... call would
+        // otherwise silently drop the host's intent — most common in the
+        // self-respawn-vs-host-start race after restart('all'): self-
+        // respawn boots with cached URL, then the host's async
+        // hostDidStart chain (gated on feature flag / login / network)
+        // finally calls start with a different URL and gets short-
+        // circuited. The log lets that race be diagnosed from production
+        // traces instead of "why is bg on the old URL".
+        if (entryURL.length > 0 && ![entryURL isEqualToString:self.lastEntryURL]) {
+            [BTLogger warn:[NSString stringWithFormat:
+                @"startBackgroundRunnerWithEntryURL: ignored (already started); requested=%@ active=%@",
+                entryURL, self.lastEntryURL ?: @"<nil>"]];
+        }
         return;
     }
     self.isStarted = YES;
+    // Cache the URL before we even start so the mode='all' self-respawn
+    // path can preserve it across a restart that releases the delegate.
+    // Updated unconditionally — first-time and re-start with a new URL
+    // both reflect into lastEntryURL.
+    self.lastEntryURL = entryURL;
     [BTLogger info:[NSString stringWithFormat:@"Starting background runner with entryURL: %@", entryURL]];
 
     dispatch_async(dispatch_get_main_queue(), ^{
@@ -156,4 +230,210 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
     }
 }
 
+#pragma mark - Restart
+
+- (void)restartWithMode:(NSString *)mode
+                 reason:(NSString *)reason
+             completion:(void (^)(NSError * _Nullable error))completion
+{
+    BOOL isUI = [mode isEqualToString:@"ui"];
+    BOOL isAll = [mode isEqualToString:@"all"];
+
+    if (!isUI && !isAll) {
+        NSError *error = [NSError errorWithDomain:@"BackgroundThread"
+                                             code:10
+                                         userInfo:@{NSLocalizedDescriptionKey:
+                                                        [NSString stringWithFormat:@"BackgroundThread.restart: unsupported mode '%@', expected 'ui' or 'all'", mode]}];
+        if (completion) completion(error);
+        return;
+    }
+
+    NSString *attributedReason = reason.length > 0
+        ? [NSString stringWithFormat:@"BackgroundThread.restart(%@): %@", mode, reason]
+        : [NSString stringWithFormat:@"BackgroundThread.restart(%@)", mode];
+
+    [BTLogger info:[NSString stringWithFormat:@"restart: mode=%@ reason=%@", mode, reason ?: @"<none>"]];
+
+    // Bridge teardown must happen on the main thread; everything before
+    // RCTTriggerReloadCommandListeners runs synchronously on that thread so
+    // the quiesce is provably done before any reload-driven instance dealloc.
+    dispatch_block_t work = ^{
+        // (1) Quiesce SharedRPC listener(s). Synchronous, holds the SharedRPC
+        // mutex internally — any concurrent notifyOtherRuntime that gets past
+        // the lock will see alive=false.
+        SharedRPC::invalidate("main");
+        if (isAll) {
+            SharedRPC::invalidate("background");
+        }
+
+        // (2) For mode=all, drop our strong refs to the bg host so ARC can
+        // dealloc it. We also reset isStarted so the post-reload hostDidStart
+        // callback (which is invoked from AppDelegate after the main reload
+        // completes) re-enters startBackgroundRunner instead of short-circuiting.
+        if (isAll) {
+            [BTLogger info:@"restart(all): releasing bg factory + resetting isStarted"];
+            self.reactNativeFactory = nil;
+            self.reactNativeFactoryDelegate = nil;
+            self.isStarted = NO;
+        }
+
+        // (3) Schedule a defensive post-reload health-check BEFORE triggering
+        // the reload. The check uses pure dispatch_after on our own state
+        // (mainSharedBridgeInstalled, isStarted) instead of an
+        // RCTJavaScriptDidLoadNotification observer — that notification's
+        // post timing is unreliable in bridgeless / NewArch, and an
+        // observer-based design introduces observer-leak + cross-generation
+        // misreporting hazards that dispatch_after + restartGeneration
+        // sidesteps entirely. See scheduleHealthCheckForRestart:... for the
+        // two-stage retry that tolerates slow devices.
+        self.mainSharedBridgeInstalled = NO;
+        NSUInteger myGen = ++self.restartGeneration;
+        [self scheduleHealthCheckForRestart:mode isAll:isAll generation:myGen retried:NO];
+
+        // (4) Trigger the main bridge reload. Equivalent to what
+        // react-native-restart did, but now sequenced AFTER quiesce so the
+        // SharedRPC race window is closed.
+        RCTTriggerReloadCommandListeners(attributedReason);
+
+        // (5) For mode=all, the new main host's hostDidStart will call
+        // BackgroundThreadBridge.startBackgroundRunner again (isStarted==NO
+        // now), recreating the bg host and re-installing the "background"
+        // listener via BackgroundRunnerReactNativeDelegate.hostDidStart.
+        // If the host fails to do so, the health-check above self-heals
+        // (with the default-entry-URL caveat noted there).
+        // For mode=ui, the bg host stays as-is; only the "main" listener
+        // gets re-installed in installSharedBridgeInMainRuntime.
+
+        if (completion) completion(nil);
+    };
+
+    if ([NSThread isMainThread]) {
+        work();
+    } else {
+        dispatch_async(dispatch_get_main_queue(), work);
+    }
+}
+
+#pragma mark - Restart Health Check
+
+// Two-stage post-reload health-check.
+//
+// Stage 1 fires at +kRestartHealthCheckDelaySeconds (~3s) from restart()
+// dispatch. Reads `mainSharedBridgeInstalled` and (for mode='all')
+// `isStarted` — both signals the module owns. Decides:
+//   - Both healthy → log success, done.
+//   - Anything missing → reschedule stage 2 (+~3s more, total ~6s) and
+//     defer the final verdict. This is intentional: even the "main ready,
+//     bg not ready" case is rescheduled rather than self-respawned at
+//     stage 1, because hosts that gate startBackgroundRunner on async
+//     work (feature-flag fetch, login, network callback) can be
+//     mainReady=YES while their async start is still in flight — see the
+//     in-line comment in the stage-1 branch below.
+//
+// Stage 2 fires at total ~6s. Whatever state we see is the final verdict;
+// any remaining gap is logged as an integration failure (with self-heal
+// where possible). 6s comfortably covers a low-end iPhone OTA reload chain
+// (observed worst case ~2.5s); past that, integration is more likely
+// broken than slow.
+//
+// Generation check at the top of each stage block bails out if a newer
+// restart() has bumped restartGeneration in the meantime — its own check
+// will run, and reading flags now would mix cycles.
+- (void)scheduleHealthCheckForRestart:(NSString *)mode
+                                isAll:(BOOL)isAll
+                           generation:(NSUInteger)myGen
+                              retried:(BOOL)retried
+{
+    __weak BackgroundThreadManager *weakSelf = self;
+    dispatch_after(dispatch_time(DISPATCH_TIME_NOW,
+                                 (int64_t)(kRestartHealthCheckDelaySeconds * NSEC_PER_SEC)),
+                   dispatch_get_main_queue(), ^{
+        BackgroundThreadManager *strongSelf = weakSelf;
+        if (!strongSelf) return;
+        if (strongSelf.restartGeneration != myGen) {
+            [BTLogger info:[NSString stringWithFormat:
+                @"restart(%@) health-check stage%@ superseded by newer restart (gen %lu → %lu)",
+                mode, retried ? @"2" : @"1",
+                (unsigned long)myGen, (unsigned long)strongSelf.restartGeneration]];
+            return;
+        }
+
+        BOOL mainReady = strongSelf.mainSharedBridgeInstalled;
+        BOOL bgReady = !isAll || strongSelf.isStarted;
+        NSString *stage = retried ? @"2" : @"1";
+
+        if (mainReady && bgReady) {
+            [BTLogger info:[NSString stringWithFormat:
+                @"restart(%@): post-reload health-check stage%@ OK (mainReady=YES, bgReady=YES)",
+                mode, stage]];
+            return;
+        }
+
+        // Stage 1: anything missing → reschedule stage 2.
+        //
+        // Earlier rounds short-circuited the "mainReady=YES, bgReady=NO"
+        // case as a stable signal that the host wasn't going to call
+        // startBackgroundRunner. That assumption holds only for hosts
+        // whose hostDidStart: synchronously calls both install AND start.
+        // Hosts that gate startBackgroundRunner on async work (feature
+        // flag fetch, login state, network callback) can have
+        // mainReady=YES while their async start call is still in flight;
+        // self-respawning at stage 1 would race them and the host's
+        // later (real) start would be silently dropped by the early
+        // return in startBackgroundRunnerWithEntryURL: (now logged as a
+        // warn, see #2). Stage 2 (+~3s) is sized to give that async path
+        // time to land; if it still hasn't by then, the host is broken
+        // and self-respawn is correct.
+        if (!retried) {
+            [BTLogger info:[NSString stringWithFormat:
+                @"restart(%@): stage1 incomplete (mainReady=%@, bgReady=%@) — rescheduling stage2 to cover slow hostDidStart chains and async host start calls",
+                mode, mainReady ? @"YES" : @"NO", bgReady ? @"YES" : @"NO"]];
+            [strongSelf scheduleHealthCheckForRestart:mode isAll:isAll generation:myGen retried:YES];
+            return;
+        }
+
+        // Stage 2 final verdict.
+
+        if (isAll && !strongSelf.isStarted) {
+            NSString *cachedURL = strongSelf.lastEntryURL;
+            // Treat the bundled default name as "no real cache" so the
+            // OTA warn still fires for hosts that initially bootstrapped
+            // with the default URL and haven't yet swapped to an OTA-
+            // resolved path. Such hosts have OTA risk but no signal in
+            // lastEntryURL that distinguishes them.
+            BOOL hasCustomCachedURL = cachedURL.length > 0
+                && ![cachedURL isEqualToString:@"background.bundle"];
+            if (hasCustomCachedURL) {
+                // Preferred path: replay the host's last entry URL. On OTA
+                // devices this is the OTA-resolved bundle, which keeps the
+                // bg moduleId table aligned with the new main bundle and
+                // avoids the silent → crash regression of falling back to
+                // the bundled `background.bundle`.
+                [BTLogger info:[NSString stringWithFormat:
+                    @"restart(%@): bg not respawned by host AppDelegate; self-respawning with cached entryURL=%@",
+                    mode, cachedURL]];
+                [strongSelf startBackgroundRunnerWithEntryURL:cachedURL];
+            } else {
+                // Cache is empty or holds the bundled default. Fall back
+                // and warn — on an OTA-equipped host this is the path
+                // that historically produces a moduleId-mismatch crash on
+                // the next cross-runtime RPC.
+                [BTLogger warn:[NSString stringWithFormat:
+                    @"restart(%@): bg not respawned and no custom cached entryURL (cache=%@); falling back to default. If host uses OTA bundles, wire AppDelegate.hostDidStart: to call startBackgroundRunner explicitly to avoid moduleId-mismatch.",
+                    mode, cachedURL ?: @"<nil>"]];
+                [strongSelf startBackgroundRunner];
+            }
+        }
+
+        if (!strongSelf.mainSharedBridgeInstalled) {
+            [BTLogger error:[NSString stringWithFormat:
+                @"restart(%@): SharedBridge not re-installed in main runtime within ~%.1fs after reload (stage%@). "
+                @"Host AppDelegate's hostDidStart: must invoke "
+                @"+[BackgroundThreadManager installSharedBridgeInMainRuntime:newHost] "
+                @"on the new RCTHost or main→bg RPC will silently fail.",
+                mode, kRestartHealthCheckDelaySeconds * 2, stage]];
+        }
+    });
+}
+
 @end

package/lib/module/NativeBackgroundThread.js

@@ -1,5 +1,31 @@
 "use strict";
 
 import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * Allowed values for `restart()`'s `mode` argument.
+ *
+ * Defined as a string literal union (not a TypeScript `enum`) on purpose:
+ *
+ * 1. **Zero runtime cost.** A regular `enum` compiles to a JS object that
+ *    ships with the bundle. A literal union erases to nothing.
+ * 2. **Codegen-friendly.** React Native's TurboModule codegen reads this
+ *    spec to generate native types; its supported set is primitives,
+ *    Object/Array, Promise, and string-literal unions. Plain TS `enum`
+ *    is not in that set — behaviour varies by RN version and best
+ *    avoided in spec files.
+ * 3. **Callsite type-safety without a runtime import.** Consumers can
+ *    `import type { RestartMode } from '@onekeyfe/react-native-background-thread'`
+ *    and pass a plain string; TypeScript narrows it without a runtime
+ *    dependency on this module's value space.
+ *
+ * Migration note: the JSDoc on `restart()` historically said callers
+ * should use the `EAppRestartMode` enum from `@onekeyhq/shared`. If that
+ * is a regular TS string enum, its values aren't assignable to this union
+ * directly — either cast at the call site (`mode as RestartMode`) or
+ * migrate `EAppRestartMode` to a string-literal union / `as const` object
+ * so the two stay aligned.
+ */
+
 export default TurboModuleRegistry.getEnforcing('BackgroundThread');
 //# sourceMappingURL=NativeBackgroundThread.js.map

package/lib/typescript/src/NativeBackgroundThread.d.ts

@@ -1,8 +1,84 @@
 import type { TurboModule } from 'react-native';
+/**
+ * Allowed values for `restart()`'s `mode` argument.
+ *
+ * Defined as a string literal union (not a TypeScript `enum`) on purpose:
+ *
+ * 1. **Zero runtime cost.** A regular `enum` compiles to a JS object that
+ *    ships with the bundle. A literal union erases to nothing.
+ * 2. **Codegen-friendly.** React Native's TurboModule codegen reads this
+ *    spec to generate native types; its supported set is primitives,
+ *    Object/Array, Promise, and string-literal unions. Plain TS `enum`
+ *    is not in that set — behaviour varies by RN version and best
+ *    avoided in spec files.
+ * 3. **Callsite type-safety without a runtime import.** Consumers can
+ *    `import type { RestartMode } from '@onekeyfe/react-native-background-thread'`
+ *    and pass a plain string; TypeScript narrows it without a runtime
+ *    dependency on this module's value space.
+ *
+ * Migration note: the JSDoc on `restart()` historically said callers
+ * should use the `EAppRestartMode` enum from `@onekeyhq/shared`. If that
+ * is a regular TS string enum, its values aren't assignable to this union
+ * directly — either cast at the call site (`mode as RestartMode`) or
+ * migrate `EAppRestartMode` to a string-literal union / `as const` object
+ * so the two stay aligned.
+ */
+export type RestartMode = 'ui' | 'all';
 export interface Spec extends TurboModule {
     startBackgroundRunnerWithEntryURL(entryURL: string): void;
     installSharedBridge(): void;
     loadSegmentInBackground(segmentId: number, path: string): Promise<void>;
+    /**
+     * Reload one or both JS runtimes. Replaces `react-native-restart`.
+     *
+     * `mode` (see {@link RestartMode}):
+     * - `'ui'`: restart only the main JS runtime (the one driving the UI).
+     *   The background runtime stays hot, preserving its state and avoiding
+     *   the SharedRPC reload race that crashed iOS on language switch.
+     * - `'all'`: restart both main and background JS runtimes. Required when
+     *   the JS bundle on disk has changed (OTA install/switch) so the two
+     *   runtimes cannot keep running mismatched moduleId tables.
+     *
+     * Any other value rejects the promise — callers should pass a
+     * `RestartMode` literal. The native validation still runs at runtime
+     * (it's the source of truth for what the platforms accept), so a string
+     * cast that smuggles in an unknown value will be rejected there.
+     *
+     * `reason` is forwarded to RCTTriggerReloadCommandListeners and to host
+     * logs / Sentry breadcrumbs so production restarts are attributable.
+     *
+     * ## Platform behaviour for `mode='all'`
+     *
+     * iOS and Android tear down the JS runtimes the same way, but the OS
+     * process around them differs — code that runs natively (timers,
+     * singletons, in-memory caches, scheduled jobs, foreground services)
+     * cannot assume cross-platform survival semantics:
+     *
+     * - **iOS**: process survives. The main RCTHost is rebuilt in-place via
+     *   `RCTTriggerReloadCommandListeners`; the bg RCTHost is released and
+     *   re-spawned by the host AppDelegate's `hostDidStart:`, with the
+     *   module's two-stage `dispatch_after` health-check as a fallback if
+     *   the host integration fails to re-arm (intentionally not driven by
+     *   `RCTJavaScriptDidLoadNotification`, whose timing is unreliable in
+     *   bridgeless / NewArch). Any process-level state (NSUserDefaults cache,
+     *   live URLSession tasks, GCD timers attached to the app process)
+     *   survives. iOS goes through soft reload here because abrupt
+     *   termination is App Store-unfriendly and iOS lacks a clean self-
+     *   relaunch path.
+     * - **Android**: process is killed. `BackgroundThreadManager` invokes
+     *   `Runtime.exit(0)` after queuing `makeRestartActivityTask`, so the
+     *   JVM is replaced wholesale. Any process-level state is lost; Activity
+     *   stack is rebuilt from the launch intent. The choice is intentional
+     *   — `mode='all'` is meant for OTA install/switch where a fresh re-
+     *   read of both bundles from disk is desirable, and Android has a
+     *   clean self-relaunch path that iOS doesn't.
+     *
+     * Callers that depend on process-level state (anything held in native
+     * singletons, background services, JNI handles) must not rely on it
+     * surviving `mode='all'` cross-platform. For UI-only resets that should
+     * preserve process state on both platforms, use `mode='ui'`.
+     */
+    restart(mode: RestartMode, reason: string): Promise<void>;
 }
 declare const _default: Spec;
 export default _default;

package/lib/typescript/src/index.d.ts

@@ -1,4 +1,5 @@
 export declare const BackgroundThread: import("./NativeBackgroundThread").Spec;
+export type { RestartMode } from './NativeBackgroundThread';
 export { getSharedStore } from './SharedStore';
 export type { ISharedStore } from './SharedStore';
 export { getSharedRPC } from './SharedRPC';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-background-thread",
-  "version": "3.0.31",
+  "version": "3.0.32",
   "description": "react-native-background-thread",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -84,7 +84,7 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "@onekeyfe/react-native-bundle-update": ">=3.0.31",
+    "@onekeyfe/react-native-bundle-update": "*",
     "react": "*",
     "react-native": "*"
   },

package/src/NativeBackgroundThread.ts

@@ -1,13 +1,88 @@
 import { TurboModuleRegistry } from 'react-native';
 
 import type { TurboModule } from 'react-native';
+
+/**
+ * Allowed values for `restart()`'s `mode` argument.
+ *
+ * Defined as a string literal union (not a TypeScript `enum`) on purpose:
+ *
+ * 1. **Zero runtime cost.** A regular `enum` compiles to a JS object that
+ *    ships with the bundle. A literal union erases to nothing.
+ * 2. **Codegen-friendly.** React Native's TurboModule codegen reads this
+ *    spec to generate native types; its supported set is primitives,
+ *    Object/Array, Promise, and string-literal unions. Plain TS `enum`
+ *    is not in that set — behaviour varies by RN version and best
+ *    avoided in spec files.
+ * 3. **Callsite type-safety without a runtime import.** Consumers can
+ *    `import type { RestartMode } from '@onekeyfe/react-native-background-thread'`
+ *    and pass a plain string; TypeScript narrows it without a runtime
+ *    dependency on this module's value space.
+ *
+ * Migration note: the JSDoc on `restart()` historically said callers
+ * should use the `EAppRestartMode` enum from `@onekeyhq/shared`. If that
+ * is a regular TS string enum, its values aren't assignable to this union
+ * directly — either cast at the call site (`mode as RestartMode`) or
+ * migrate `EAppRestartMode` to a string-literal union / `as const` object
+ * so the two stay aligned.
+ */
+export type RestartMode = 'ui' | 'all';
+
 export interface Spec extends TurboModule {
   startBackgroundRunnerWithEntryURL(entryURL: string): void;
   installSharedBridge(): void;
-  loadSegmentInBackground(
-    segmentId: number,
-    path: string,
-  ): Promise<void>;
+  loadSegmentInBackground(segmentId: number, path: string): Promise<void>;
+  /**
+   * Reload one or both JS runtimes. Replaces `react-native-restart`.
+   *
+   * `mode` (see {@link RestartMode}):
+   * - `'ui'`: restart only the main JS runtime (the one driving the UI).
+   *   The background runtime stays hot, preserving its state and avoiding
+   *   the SharedRPC reload race that crashed iOS on language switch.
+   * - `'all'`: restart both main and background JS runtimes. Required when
+   *   the JS bundle on disk has changed (OTA install/switch) so the two
+   *   runtimes cannot keep running mismatched moduleId tables.
+   *
+   * Any other value rejects the promise — callers should pass a
+   * `RestartMode` literal. The native validation still runs at runtime
+   * (it's the source of truth for what the platforms accept), so a string
+   * cast that smuggles in an unknown value will be rejected there.
+   *
+   * `reason` is forwarded to RCTTriggerReloadCommandListeners and to host
+   * logs / Sentry breadcrumbs so production restarts are attributable.
+   *
+   * ## Platform behaviour for `mode='all'`
+   *
+   * iOS and Android tear down the JS runtimes the same way, but the OS
+   * process around them differs — code that runs natively (timers,
+   * singletons, in-memory caches, scheduled jobs, foreground services)
+   * cannot assume cross-platform survival semantics:
+   *
+   * - **iOS**: process survives. The main RCTHost is rebuilt in-place via
+   *   `RCTTriggerReloadCommandListeners`; the bg RCTHost is released and
+   *   re-spawned by the host AppDelegate's `hostDidStart:`, with the
+   *   module's two-stage `dispatch_after` health-check as a fallback if
+   *   the host integration fails to re-arm (intentionally not driven by
+   *   `RCTJavaScriptDidLoadNotification`, whose timing is unreliable in
+   *   bridgeless / NewArch). Any process-level state (NSUserDefaults cache,
+   *   live URLSession tasks, GCD timers attached to the app process)
+   *   survives. iOS goes through soft reload here because abrupt
+   *   termination is App Store-unfriendly and iOS lacks a clean self-
+   *   relaunch path.
+   * - **Android**: process is killed. `BackgroundThreadManager` invokes
+   *   `Runtime.exit(0)` after queuing `makeRestartActivityTask`, so the
+   *   JVM is replaced wholesale. Any process-level state is lost; Activity
+   *   stack is rebuilt from the launch intent. The choice is intentional
+   *   — `mode='all'` is meant for OTA install/switch where a fresh re-
+   *   read of both bundles from disk is desirable, and Android has a
+   *   clean self-relaunch path that iOS doesn't.
+   *
+   * Callers that depend on process-level state (anything held in native
+   * singletons, background services, JNI handles) must not rely on it
+   * surviving `mode='all'` cross-platform. For UI-only resets that should
+   * preserve process state on both platforms, use `mode='ui'`.
+   */
+  restart(mode: RestartMode, reason: string): Promise<void>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('BackgroundThread');

package/src/SharedRPC.ts

@@ -7,7 +7,6 @@ export interface ISharedRPC {
 }
 
 declare global {
-  // eslint-disable-next-line no-var
   var sharedRPC: ISharedRPC | undefined;
 }
 

package/src/SharedStore.ts

@@ -9,7 +9,6 @@ export interface ISharedStore {
 }
 
 declare global {
-  // eslint-disable-next-line no-var
   var sharedStore: ISharedStore | undefined;
 }
 

package/src/index.tsx

@@ -1,6 +1,7 @@
 import NativeBackgroundThread from './NativeBackgroundThread';
 
 export const BackgroundThread = NativeBackgroundThread;
+export type { RestartMode } from './NativeBackgroundThread';
 export { getSharedStore } from './SharedStore';
 export type { ISharedStore } from './SharedStore';
 export { getSharedRPC } from './SharedRPC';