fix(bindings): promote MeshForegroundService to foreground in onCreate + add Stop action (#278)

* fix(bindings): promote MeshForegroundService to foreground in onCreate

Android gives an app 5 seconds after startForegroundService() to reach
startForeground(). MeshForegroundService currently calls startForeground()
from onStartCommand, which on cold start and on resume can be delayed past
that window by JS-thread initialisation and main-thread work. When that
happens the OS terminates the process with a fatal RemoteServiceException.

Move the startForeground() call into onCreate so the deadline is
unreachable regardless of what runs on the main thread after service
creation. The subsequent startForeground() calls in onStartCommand are
idempotent on the same service instance and are safe re-promotes.

Also add a "Stop" notification action so the user can shut mesh down from
the notification shade. It routes back through the service's own
ACTION_STOP handler via PendingIntent.getForegroundService on Android O+
(getService on older releases), so no separate BroadcastReceiver is
required and the delivery is legal under the background service-start
restrictions that apply when the user taps the action while the app is in
the background.

Observed impact: this fix has been shipping in-app via a patch-package
override since v67 of the MINE app; the underlying crash was the top
ANR-adjacent fatal on Redmi Note 8 Pro (Android 11), fingerprinted by
Sentry as REACT-NATIVE-5Z.

Retires the MINE-side patch tracked by Linear OFF-1801.

* fix(bindings): make the mesh notification Stop action stop the mesh

The Stop action added alongside the onCreate promotion routes
straight back into the service's own ACTION_STOP handler, which
drops the keep-alive and nothing else.

But this service is *only* a keep-alive — the module owns the
protocol and the transports, exactly as the class comment has
said all along. So tapping Stop cleared the notification and the
foreground protection while BLE, WiFi Direct, Nostr and the
process scheduler kept right on running, with nothing told to
JS. The user sees "mesh off" while the radios keep draining the
battery until the OS gets around to reaping the process.

Give the notification its own action that hands off to a host
callback instead. The module runs the same teardown as its
JS-facing stop() and emits mesh_stopped_by_user so app state
can't silently diverge, and the service stays up until that
teardown comes back around through ACTION_STOP — clearing the
notification while the mesh is still running is exactly the lie
we're fixing here. With no host registered we still drop the
keep-alive, because a dead button is its own kind of bug.

While at it, the try/catch only wrapped the onCreate promotion;
the other two call sites were bare. That matters, because a
connectedDevice promotion throws once the Nearby-Devices
permissions are revoked — so the guarded failure came straight
back uncaught a few milliseconds later. All three share a helper
now. It is not immunity: if the instance came from
startForegroundService() and promotion genuinely fails, the
system still raises its own timeout kill, and the helper says so.
And stop() is a no-op when nothing is running, since creating an
instance purely to tear it down now means a notification flash on
a path the app already runs twice.

The new event tag is emitted by the bridge, not by the core enum,
so it joins the bridge-only allowlist in the types.ts drift
guard. That guard is doing exactly what it was built for — it
caught the omission before I did.

The tests pin the part that is invisible in the source: the
service is in the foreground by the end of onCreate, with no
start command delivered. Move that promotion back into
onStartCommand and the code still reads fine while the
five-second deadline is quietly reachable again.

* fix(bindings): serialize mesh teardown and always run its tail

The notification Stop action added earlier in this branch runs the
same teardown as the JS-facing stop(), except it does it on its own
thread. Nothing was stopping the two from overlapping, and a user
tapping Stop while the app foregrounds and calls stop() is not an
exotic scenario.

Two threads interleaving through stopTransportsAndProtocol
double-stop every transport mid-pass. Worse, if both throw — and BLE
teardown throwing on real devices is the entire reason #279 and #280
exist — neither pass ever reaches the remaining transports, the
keep-alive service, or the protocol core. The user-stop path then
clears the notification and tells JS the mesh is down while five
transports are still burning battery.

That is precisely the lie this branch was written to prevent.

The JS path had the same hole without needing a race at all: one
throwing transport skipped the foreground-service stop and
protocol.stop() outright, so the notification kept advertising an
active mesh over a half-dead stack.

So serialize the shared teardown, and move the keep-alive and core
shutdown into a finally. The second entrant through the lock re-runs
the stops after a completed pass, which is their idempotent no-op
path. The exception still propagates, so stop() rejects exactly as
it did before.

While at it, drop the now-redundant keep-alive stop from the
user-stop path — the shared function guarantees it now.

* test(bindings): stop leaking the start-request flag between tests

The service tracks start intent in a companion field, and onDestroy
is what clears it. A test that calls start() without ever creating
an instance therefore leaves that flag set for whatever runs next —
there is no service instance for the fixture to destroy.

Nothing is red today, because the one test that cares re-establishes
its own precondition. That is luck, not design, and it lasts exactly
until someone adds a test between those two.

So just call stop() in the fixture. It no-ops once both flags are
already down, which costs nothing on every other test.

---------

Co-authored-by: bahdotsh <appu.yess@gmail.com>

Author: taayyohh

bindings/react-native/android/build.gradle

@@ -86,6 +86,12 @@ dependencies {
 
     testImplementation 'junit:junit:4.13.2'
     testImplementation 'org.robolectric:robolectric:4.16'
+    // NotificationCompat reaches the production classpath transitively through
+    // react-android, which is compileOnly in the standalone/CI harness — so the
+    // JVM tests have to bring it themselves. Test-only: consumers keep getting
+    // it from the host app. Hold at 1.13.x, the last line that builds against
+    // compileSdk 34.
+    testImplementation 'androidx.core:core:1.13.1'
     // Real org.json for JVM unit tests (the android.jar org.json is a stub
     // that throws) — needed by RelayControlOpTranslatorTest.
     testImplementation 'org.json:json:20260719'

bindings/react-native/android/src/main/java/com/offlineprotocol/MeshForegroundService.kt

@@ -3,6 +3,7 @@ package com.offlineprotocol
 import android.app.Notification
 import android.app.NotificationChannel
 import android.app.NotificationManager
+import android.app.PendingIntent
 import android.app.Service
 import android.content.Context
 import android.content.Intent
@@ -24,7 +25,8 @@ import androidx.core.app.NotificationCompat
  * The service itself does NOT own the protocol or transport instances.
  * It exists solely to prevent the OS from killing the process while mesh
  * networking is active. Protocol and transport lifecycle remains in
- * OfflineProtocolModule.
+ * OfflineProtocolModule — including the notification's Stop action, which
+ * hands off to [onStopRequestedByUser] instead of tearing down here.
  */
 class MeshForegroundService : Service() {
 
@@ -37,10 +39,28 @@ class MeshForegroundService : Service() {
         private const val ACTION_START = "com.offlineprotocol.action.START_MESH"
         private const val ACTION_STOP = "com.offlineprotocol.action.STOP_MESH"
 
+        /**
+         * Delivered by the notification's Stop action. Deliberately distinct
+         * from [ACTION_STOP]: that one is the host telling the service that
+         * mesh is *already* going down, while this one is the user asking for
+         * a teardown the host has not started yet and must run itself.
+         */
+        private const val ACTION_STOP_FROM_NOTIFICATION =
+            "com.offlineprotocol.action.STOP_MESH_FROM_NOTIFICATION"
+
         @Volatile
         var isRunning: Boolean = false
             private set
 
+        /**
+         * Set by [start], cleared by [stop] and [onDestroy]. Tracks intent
+         * rather than state: the service is created asynchronously, so a
+         * `stop()` racing a just-issued `start()` sees [isRunning] still false
+         * while a service is on its way up.
+         */
+        @Volatile
+        private var startRequested: Boolean = false
+
         /**
          * Callback invoked when the service is restarted after a process kill
          * (START_STICKY re-delivery). The host module should set this so it can
@@ -49,7 +69,24 @@ class MeshForegroundService : Service() {
         @Volatile
         var onServiceRestarted: (() -> Unit)? = null
 
+        /**
+         * Callback invoked when the user taps "Stop" on the service
+         * notification. The host module must set this and run the same
+         * teardown as its JS-facing `stop()`: this service is only a
+         * keep-alive, so dropping it alone would leave BLE/WiFi-Direct/Nostr
+         * and the process scheduler running with no foreground protection and
+         * no JS-visible state change — the user sees "mesh off" while the
+         * radios keep draining until the OS reaps the process.
+         *
+         * Held in a companion field, so a host that captures itself here must
+         * null it out on teardown or it pins that host for the process
+         * lifetime.
+         */
+        @Volatile
+        var onStopRequestedByUser: (() -> Unit)? = null
+
         fun start(context: Context) {
+            startRequested = true
             val intent = Intent(context, MeshForegroundService::class.java).apply {
                 action = ACTION_START
             }
@@ -61,6 +98,18 @@ class MeshForegroundService : Service() {
         }
 
         fun stop(context: Context) {
+            // Skip when there is nothing to stop. Callers invoke this from
+            // both stop() and invalidate(), so a stop-after-stop would
+            // otherwise create an instance purely to tear it down — and since
+            // onCreate now promotes to the foreground, that means a visible
+            // notification flash during app teardown.
+            //
+            // Both flags are needed: startRequested covers a stop racing a
+            // service that is still coming up (isRunning not yet set), and
+            // isRunning covers an instance we never requested — a START_STICKY
+            // restart after process death, which resets the statics.
+            if (!startRequested && !isRunning) return
+            startRequested = false
             val intent = Intent(context, MeshForegroundService::class.java).apply {
                 action = ACTION_STOP
             }
@@ -79,28 +128,39 @@ class MeshForegroundService : Service() {
     override fun onCreate() {
         super.onCreate()
         createNotificationChannel()
+        // Enter the foreground here rather than waiting for onStartCommand.
+        // Android gives an app 5 seconds after startForegroundService() to
+        // call startForeground(); if onStartCommand is delayed past that
+        // window (JS-thread initialization on cold start, main-thread work
+        // during app resume on mid-range devices), the OS terminates the
+        // process with a fatal RemoteServiceException. Promoting in
+        // onCreate — which runs before any onStartCommand dispatch — makes
+        // the deadline unreachable. Subsequent startForeground() calls in
+        // onStartCommand are idempotent on the same service instance and
+        // remain safe re-promotes.
+        promoteToForeground()
     }
 
     override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
         when (intent?.action) {
             ACTION_STOP -> {
                 Log.i(TAG, "Stopping mesh foreground service")
-                isRunning = false
-                stopForeground(STOP_FOREGROUND_REMOVE)
-                stopSelf()
+                stopForegroundAndSelf()
                 return START_NOT_STICKY
             }
+            ACTION_STOP_FROM_NOTIFICATION -> {
+                Log.i(TAG, "User requested mesh stop from the notification")
+                return handleUserStopRequest()
+            }
             ACTION_START -> {
                 Log.i(TAG, "Starting mesh foreground service")
-                startForeground(NOTIFICATION_ID, buildNotification())
-                isRunning = true
+                promoteToForeground()
             }
             null -> {
                 // Service restarted by the system after process kill (START_STICKY).
                 // Re-enter foreground immediately to prevent ANR, then notify host.
                 Log.i(TAG, "Service restarted after process kill")
-                startForeground(NOTIFICATION_ID, buildNotification())
-                isRunning = true
+                promoteToForeground()
                 onServiceRestarted?.invoke()
             }
         }
@@ -109,10 +169,69 @@ class MeshForegroundService : Service() {
 
     override fun onDestroy() {
         isRunning = false
+        startRequested = false
         Log.i(TAG, "Mesh foreground service destroyed")
         super.onDestroy()
     }
 
+    /**
+     * Enter (or re-enter) the foreground with the mesh notification.
+     *
+     * Shared by all three promotion sites so none of them can throw where the
+     * caller does not expect it. A `connectedDevice`-typed promotion is not
+     * failure-free on targetSdk 34: it raises SecurityException once the
+     * Nearby-Devices runtime permissions are revoked, and a START_STICKY
+     * restart while the app is backgrounded raises
+     * ForegroundServiceStartNotAllowedException on Android 12+. Neither is
+     * worth taking the process down for by itself, and the ACTION_START path
+     * re-promotes afterwards.
+     *
+     * The residual is worth stating plainly: when the instance was created by
+     * startForegroundService() and promotion genuinely fails, swallowing here
+     * only defers the kill — the system still raises its own 5-second-timeout
+     * RemoteServiceException. This buys survival for transient OEM failures,
+     * not immunity.
+     */
+    private fun promoteToForeground() {
+        try {
+            startForeground(NOTIFICATION_ID, buildNotification())
+            isRunning = true
+        } catch (e: Exception) {
+            Log.w(TAG, "startForeground failed: ${e.message}", e)
+        }
+    }
+
+    /**
+     * Hand a user-initiated stop to the host, which owns protocol and
+     * transport lifecycle. Its teardown ends in [stop], so this service comes
+     * down through the ACTION_STOP branch once the mesh is actually off —
+     * keeping the notification truthful rather than clearing it while the
+     * radios still run.
+     */
+    private fun handleUserStopRequest(): Int {
+        val callback = onStopRequestedByUser
+        if (callback != null) {
+            try {
+                callback.invoke()
+                return START_NOT_STICKY
+            } catch (e: Exception) {
+                Log.w(TAG, "Host stop callback failed; stopping the service directly: ${e.message}", e)
+            }
+        } else {
+            Log.w(TAG, "No host stop callback registered; stopping the service only — transports may still be running")
+        }
+        // Fallback: nothing to defer to, so at least honour the button by
+        // dropping the keep-alive.
+        stopForegroundAndSelf()
+        return START_NOT_STICKY
+    }
+
+    private fun stopForegroundAndSelf() {
+        isRunning = false
+        stopForeground(STOP_FOREGROUND_REMOVE)
+        stopSelf()
+    }
+
     private fun createNotificationChannel() {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
             val channel = NotificationChannel(
@@ -129,13 +248,38 @@ class MeshForegroundService : Service() {
     }
 
     private fun buildNotification(): Notification {
+        // Route the notification's stop action back through this service's
+        // own ACTION_STOP_FROM_NOTIFICATION handler. Using
+        // PendingIntent.getForegroundService on O+ keeps the delivery legal
+        // under the background service-start restrictions that apply when the
+        // user taps the action from the notification shade while the app
+        // itself is in the background; pre-O falls back to getService which
+        // has no such restriction.
+        //
+        // Note the coupling with the onCreate promotion: if this fires against
+        // a dead service instance (a stale notification during a sticky-restart
+        // gap), startForegroundService() re-creates the service, and that
+        // promotion is the only thing satisfying the 5-second startForeground
+        // obligation before the stop is handled. Do not remove one without
+        // the other.
+        val stopIntent = Intent(this, MeshForegroundService::class.java).apply {
+            action = ACTION_STOP_FROM_NOTIFICATION
+        }
+        val pendingIntentFlags = PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        val stopPendingIntent = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            PendingIntent.getForegroundService(this, 0, stopIntent, pendingIntentFlags)
+        } else {
+            PendingIntent.getService(this, 0, stopIntent, pendingIntentFlags)
+        }
+
         return NotificationCompat.Builder(this, CHANNEL_ID)
             .setContentTitle("Mesh Active")
             .setContentText("Offline mesh networking is running")
             .setSmallIcon(android.R.drawable.stat_sys_data_bluetooth)
             .setOngoing(true)
             .setPriority(NotificationCompat.PRIORITY_LOW)
             .setCategory(NotificationCompat.CATEGORY_SERVICE)
+            .addAction(android.R.drawable.ic_media_pause, "Stop", stopPendingIntent)
             .build()
     }
 }