unified-ble-manager 4.0.7 → 4.0.8

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to `unified-ble-manager` are documented here.
 
+## [Unreleased]
+
+No changes yet.
+
+## [4.0.8] - 2026-08-29
+
+### Fixes
+
+- **Apple runtime shutdown no longer retains a closed JavaScript attachment through its invoker.** Closing the native protocol now moves the `CallInvoker` out of shared state before scheduling runtime-thread sink cleanup, breaking the state/invoker/callback ownership cycle. iOS, macOS, and tvOS keep the same public behavior while clean teardown no longer leaves JSI functions alive past their runtime.
+
+- **Public capability checks no longer hide implemented operations whose evidence is limited.** `manager.capabilities.supports(id)` and `require(id)` now agree with the core manager: both `supported` and invocable `limited` descriptors are usable, while `unavailable`, `unsupported`, and missing capabilities still fail closed. Callers that need full qualification can inspect `manager.capabilities.get(id).state` and its retained limitations. This fixes Android callers incorrectly discarding the bonded `when-available` reconnect path merely because its physical-radio evidence is still labelled `limited` (#174, PR #170).
+
+- **Expo Android connected-device monitoring now has an app-controlled notification and explicit lifecycle recovery.** While an active background lease is held, `manager.background.updateNotification({ title, body? })` updates the existing UBM notification in place without acquiring or starting another service. The configured channel, icon, connected-device service type, ongoing state, session-intent policy, and host-app tap are preserved. `restart: 'while-session-intent-exists'` now also manages boot and package-replaced recovery, but only starts the service when native UBM session intent exists; it never scans or reconnects. Once a recovered service is promoted, a package-scoped `FOREGROUND_READY` signal lets an app-owned headless runtime resume without racing Android's background-service restrictions; normal acquisition resolves its existing caller without launching a redundant headless runtime. Background and restart remain absent/`never` by default, and unsupported hosts reject the operation truthfully (#177, PR #170).
+
+- **React Native no longer closes a healthy notification subscription during a legitimate burst of native events.** Android and Apple still fail closed on an undrained native-to-JavaScript queue, but both bridges now retain up to 512 records / 1 MiB before declaring overflow. That bounded budget accommodates common catch-up transfers such as roughly 288 five-minute readings delivered in one 24-hour history response while preserving a visible `stream.overflow` terminal if JavaScript genuinely cannot keep up. The change applies only to the two React Native native-event ingress queues; other backends keep their existing buffering and capability truth (#175).
+
+- **React Native Android now exposes the system bonded peer directory.** `manager.peers.bonded()` reads the ABI-6 Android bond table, returns deterministic version-1 system-scoped references, and `manager.peers.resolve()` rechecks that a saved reference remains bonded before reconnecting. `manager.connect(peer, { intent: 'when-available' })` reaches Android's queued auto-connect path. Bonded metadata does not imply reachability; Android reports unknown reachability and preserves `permission.denied` instead of returning an empty list. Other backends keep their truthful unsupported boundaries, and Web origin-authorized devices remain distinct from bonded peers.
+
+- **React Native Android now honours `PairOptions.transport: 'le'` instead of discarding it.** The public security layer validated and forwarded the selector, but the React Native Android backend dropped it before the native command and always called parameterless `createBond()`. Explicit LE pairing now crosses native-protocol ABI 5 and invokes Android's transport-selecting bond operation with `BluetoothDevice.TRANSPORT_LE`; `'auto'` remains the platform default. Unsupported or rejected explicit selection fails closed rather than silently changing the request. Because Android API 36 cannot publicly query bond state by transport, only an LE-only device's existing bond satisfies an explicit-LE `already-paired` result; dual-mode, classic, and unknown devices retry the directed operation instead of risking a false success from a BR/EDR-only bond. Reflection-wrapped permission failures retain `permissionDenied`. BlueZ and WinRT already pair through BLE-only device objects, while Apple and Web keep generic pairing unsupported; those platform semantics are unchanged.
+
+- **Every GATT notification was dropped on both React Native backends, and characteristic and descriptor reads with them.** A notification's payload is carried as a binary reference, and the protocol requires that reference to name the operation the event belongs to — the codec compares the two for equality (`requireBinaryCorrelation`). Both bindings stamped the subscribe's correlation on the event while minting the payload under a correlation of their own (`"notification:<subscription>:<ordinal>"` on Android, `"apple-notification:..."` on Apple), a combination that can never validate. Every notification was therefore refused inside our own codec before reaching a caller, so a subscription delivered nothing at all while the radio received the peer perfectly well. The read paths decorated their correlation the same way (`"read:<epoch>:<nonce>"`, `"apple-read:<nonce>"`) and failed the same check on the result record. All four sites now mint the payload under the owning operation's nonce, as the write path always did.
+
+  Sharing one correlation across a subscription's notifications is safe: `OwnedBinaryPayloadStore` keys retained payloads by a freshly generated owner token and releases by that token, treating the correlation as metadata it cross-checks rather than as a unique key.
+
+  The deterministic layer could not catch this, which is why it shipped: the React Native test doubles minted their own notification correlations and omitted the operation correlation entirely, so they modelled a record the native codec refuses to deliver, and the suite stayed green against a shape no device could ever produce. `ReactNativeAndroidProtocolBoundary` now enforces the same rule the native codec enforces, the doubles emit the shape the bindings actually emit, and the codec's own tests pin both the notification event and the read result. Live-device evidence showed the platform receiving a peer's reply chunks while the application received none (#168).
+
 ## [4.0.7] - 2026-08-26
 
 ### Changed behaviour
@@ -62,7 +88,7 @@ The first release cut against a live peripheral on Android as well as Linux. Mos
 
 ## [4.0.5] - 2026-08-25
 
-First release cut against a live peripheral. Every fix below came from driving a real CGM from an Android phone and a Linux/BlueZ host, and several are defects no unit test had reason to catch. Does not retag `v4.0.4`.
+First release cut against a live peripheral. Every fix below came from driving a real BLE device from an Android phone and a Linux/BlueZ host, and several are defects no unit test had reason to catch. Does not retag `v4.0.4`.
 
 ### Fixes
 

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-The current package is `4.0.7`. The `4.0.0` release is a new package and a new contract. It is **not a source-compatible rename**. There is no `new BleManager()` facade, no Base64 characteristic values, and no public transaction IDs.
+This source targets `4.0.8`. The `4.0.0` release is a new package and a new contract. It is **not a source-compatible rename**. There is no `new BleManager()` facade, no Base64 characteristic values, and no public transaction IDs.
 
 This page is for a React Native app that already uses `react-native-ble-plx`. Web, Electron, Node, and Tauri are new hosts — use those pages after you understand the RN rewrite.
 

package/README.md

@@ -6,7 +6,20 @@
 
 It is an evolution of `react-native-ble-plx`, rewritten as a **cross-platform unified product**. One bytes-first BLE model and lifecycle semantics across hosts, with host-specific construction and ownership. The root package never picks a radio for you, and it will not quietly fall back to a simulator or a different backend.
 
-Install `unified-ble-manager` from npm (`4.0.7` on `latest`). The root import does not pick a radio. Package SemVer and backend support labels are independent: each radio backend stays Experimental until live-radio evidence says otherwise. See [`docs/PLATFORMS.md`](docs/PLATFORMS.md).
+Install `unified-ble-manager` from npm. The registry and provenance attached to
+the tag-driven release are the authority for the current `latest` version. The
+root import does not pick a radio. Package SemVer and backend support labels are
+independent: each radio backend keeps its evidence-derived label. See
+[`docs/PLATFORMS.md`](docs/PLATFORMS.md).
+
+This source tree is preparing `4.0.8`; that version is installable only after it
+appears in the npm registry.
+
+> **4.0 development note:** The 4.0 line is the real-application proving ground
+> for a simpler, stronger 4.1. Develop carefully against it: pin the version you
+> validate, read the changelog when upgrading, inspect capability limitations,
+> and report real-device behavior. Missing hardware evidence remains visible;
+> it does not make an implemented operation unusable.
 
 > Sponsored by [Imagi Explain](https://imagiexplain.com) — researched, narrated whiteboard explainers from a prompt, a PDF, or your notes.
 
@@ -85,6 +98,12 @@ const manager = await createReactNativeBleManager({
 
 On Android 12+ the app must request `BLUETOOTH_SCAN` and `BLUETOOTH_CONNECT` itself. The library does not call `PermissionsAndroid`.
 
+On Android, `manager.peers.bonded()` lists paired system peers and
+`manager.peers.resolve(reference)` rechecks a saved reference before
+`manager.connect(peer, { intent: 'when-available' })`; paired does not mean
+reachable. See [`docs/PEERS.md`](docs/PEERS.md) for the persistence and error
+semantics.
+
 ### Expo plugin
 
 Use an Expo development build, never Expo Go. Plugin options live in
@@ -209,7 +228,11 @@ Web Bluetooth replaces the scan with `ble.choose(...)` from a user gesture. Taur
 
 Controls report the truth of the instantiated host backend, including
 `supported`, `limited`, `unavailable`, or `unsupported`; host family alone is
-not evidence of support. Readiness is unsupported until the backend advertises
+not evidence of support. `manager.capabilities.supports(id)` answers whether
+the operation is implemented and invocable, so it returns `true` for both
+`supported` and `limited`. Use `manager.capabilities.get(id)` when application
+policy needs to distinguish full qualification from a named limitation.
+Readiness is unsupported until the backend advertises
 the readiness capability, and a readiness event does not prove a later payload
 was retained.
 

package/RELEASE.md

@@ -81,7 +81,7 @@ Active `4.0.0-rc.*` release-train candidates publish to npm `latest` so a bare `
 
 On release day, set `release_candidate` to the exact candidate required by the
 release plan. RC2, RC3, RC4, `4.0.0-rc.4.1`, and RC5 are already immutable
-once tagged. Stable `4.0.0`, `4.0.1`, `4.0.2`, `4.0.3`, `4.0.4`, `4.0.5`, and `4.0.6` are immutable. `4.0.7` is the current train head.
+once tagged. Stable `4.0.0` through `4.0.7` are immutable. `4.0.8` is the current train head.
 
 ```sh
 release_candidate=4.0.0-rc.N
@@ -133,6 +133,27 @@ The `v4.0.3` tag is immutable published history. Do not recreate or move it.
 git tag -a v4.0.3 -m "v4.0.3"
 ```
 
+## Releasing 4.0.8
+
+The `v4.0.8` tag must identify the exact current `main` commit after canonical
+CI passes. Do not tag this feature branch or `release/4.0.8` directly.
+
+```sh
+git fetch origin --tags
+git checkout main
+git pull --ff-only origin main
+
+test "$(git branch --show-current)" = "main"
+test "$(node -p "require('./package.json').version")" = "4.0.8"
+git diff --exit-code
+git diff --cached --exit-code
+
+git tag -a v4.0.8 -m "v4.0.8"
+git push origin v4.0.8
+```
+
+Before tagging, confirm release-note extraction finds `## [4.0.8]`.
+
 ## Releasing 4.0.7
 
 Same shape as 4.0.6. The release workflow verifies that the tag points at the

package/SBOM.cdx.json

@@ -6,15 +6,15 @@
   "metadata": {
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/unified-ble-manager@4.0.7",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.8",
       "name": "unified-ble-manager",
-      "version": "4.0.7",
+      "version": "4.0.8",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.7"
+      "purl": "pkg:npm/unified-ble-manager@4.0.8"
     },
     "properties": [
       {
@@ -560,7 +560,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.7",
+      "ref": "pkg:npm/unified-ble-manager@4.0.8",
       "dependsOn": [
         "pkg:npm/%40babel/runtime@7.29.7",
         "pkg:npm/%40tauri-apps/api@2.11.1",

package/THIRD_PARTY_LICENSES.json

@@ -4,7 +4,7 @@
   "schemaVersion": "1.0.0",
   "package": {
     "name": "unified-ble-manager",
-    "version": "4.0.7"
+    "version": "4.0.8"
   },
   "source": {
     "method": "pnpm-lock production graph with installed-manifest license audit",

package/android/src/main/java/com/sfourdrinier/unifiedblemanager/BlePlxForegroundService.java

@@ -3,6 +3,7 @@ package com.sfourdrinier.unifiedblemanager;
 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;
@@ -26,6 +27,8 @@ import java.util.Map;
 /** Explicit connected-device foreground lease. It performs no scan or reconnect work. */
 public final class BlePlxForegroundService extends Service {
   public static final String ACTION_START = "com.sfourdrinier.unifiedblemanager.background.START";
+  public static final String ACTION_FOREGROUND_READY =
+      "com.sfourdrinier.unifiedblemanager.background.FOREGROUND_READY";
   public static final String EXTRA_ACK = "backgroundStartAcknowledgement";
   public static final int ACK_STARTED = 1;
   public static final int ACK_FAILED = 2;
@@ -37,6 +40,8 @@ public final class BlePlxForegroundService extends Service {
   private static final String EXTRA_BODY = "body";
   private static final String EXTRA_ICON_NAME = "iconName";
   private static final String EXTRA_RESTART_STICKY = "restartSticky";
+  private static volatile BlePlxForegroundService activeService;
+  private volatile ForegroundServiceNotificationConfiguration activeConfiguration;
 
   public static Intent startIntent(
       Context context,
@@ -75,28 +80,15 @@ public final class BlePlxForegroundService extends Service {
         return START_NOT_STICKY;
       }
 
-      final String channelId = configuration.getChannelId();
-      final String channelName = configuration.getChannelName();
-      final String title = configuration.getTitle();
-      final String body = configuration.getBody();
+      activeService = this;
+      activeConfiguration = configuration;
       if (!getSharedPreferences("unified-ble-manager", MODE_PRIVATE)
           .edit()
           .putBoolean(SESSION_INTENT_PREFERENCE, configuration.restartWhileSessionIntentExists())
           .commit()) {
         throw new IllegalStateException("Android could not persist the foreground-service session intent.");
       }
-      ensureChannel(channelId, channelName);
-      final Notification.Builder builder =
-          Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
-              ? new Notification.Builder(this, channelId)
-              : new Notification.Builder(this);
-      builder
-          .setSmallIcon(iconResource(this, configuration.getIconName()))
-          .setContentTitle(title)
-          .setOngoing(true)
-          .setCategory(Notification.CATEGORY_SERVICE);
-      if (body != null) builder.setContentText(body);
-      final Notification notification = builder.build();
+      final Notification notification = buildNotification(configuration);
       if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
         startForeground(
             ForegroundServiceNotificationConfiguration.NOTIFICATION_ID,
@@ -106,6 +98,13 @@ public final class BlePlxForegroundService extends Service {
         startForeground(ForegroundServiceNotificationConfiguration.NOTIFICATION_ID, notification);
       }
       acknowledge(intent, ACK_STARTED, null);
+      // A normal acquisition already has a live JS caller waiting on EXTRA_ACK;
+      // starting a second headless runtime before that lease commits is both
+      // redundant and racy. Only recovery starts (boot, package replacement,
+      // or START_STICKY recreation) need the app-owned wake signal.
+      if (intent == null || !intent.hasExtra(EXTRA_ACK)) {
+        sendBroadcast(new Intent(ACTION_FOREGROUND_READY).setPackage(getPackageName()));
+      }
       return configuration.restartWhileSessionIntentExists() ? START_STICKY : START_NOT_STICKY;
     } catch (RuntimeException error) {
       acknowledge(intent, ACK_FAILED, error.getMessage());
@@ -117,16 +116,50 @@ public final class BlePlxForegroundService extends Service {
             new IllegalStateException("Android could not clear the foreground-service session intent."));
       }
       stopSelf();
+      activeService = null;
+      activeConfiguration = null;
       return START_NOT_STICKY;
     }
   }
 
   @Override
-  public void onDestroy() {
+  public synchronized void onDestroy() {
+    activeService = null;
+    activeConfiguration = null;
     stopForeground(STOP_FOREGROUND_REMOVE);
     super.onDestroy();
   }
 
+  public static void updateNotification(String title, String body) {
+    final BlePlxForegroundService service = activeService;
+    if (service == null || service.activeConfiguration == null) {
+      throw new com.sfourdrinier.unifiedblemanager.background.ForegroundServiceControlException(
+          "foregroundServiceNotRunning",
+          "The connected-device foreground service is not running; acquire a background lease first.");
+    }
+    synchronized (service) {
+      final ForegroundServiceNotificationConfiguration current = service.activeConfiguration;
+      if (current == null) {
+        throw new com.sfourdrinier.unifiedblemanager.background.ForegroundServiceControlException(
+            "foregroundServiceNotRunning", "The connected-device foreground service is not running; acquire a background lease first.");
+      }
+      service.activeConfiguration = ForegroundServiceNotificationConfiguration.fromValues(
+          current.getChannelId(),
+          current.getChannelName(),
+          title,
+          body,
+          current.getIconName(),
+          current.restartWhileSessionIntentExists());
+      final NotificationManager manager = service.getSystemService(NotificationManager.class);
+      if (manager == null) {
+        throw new com.sfourdrinier.unifiedblemanager.background.ForegroundServiceControlException(
+            "foregroundServiceNotRunning", "Android notification service is unavailable.");
+      }
+      manager.notify(ForegroundServiceNotificationConfiguration.NOTIFICATION_ID,
+          service.buildNotification(service.activeConfiguration));
+    }
+  }
+
   @Nullable
   @Override
   public IBinder onBind(Intent intent) {
@@ -141,6 +174,34 @@ public final class BlePlxForegroundService extends Service {
         new NotificationChannel(channelId, channelName, NotificationManager.IMPORTANCE_LOW));
   }
 
+  private Notification buildNotification(ForegroundServiceNotificationConfiguration configuration) {
+    ensureChannel(configuration.getChannelId(), configuration.getChannelName());
+    final Notification.Builder builder =
+        Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
+            ? new Notification.Builder(this, configuration.getChannelId())
+            : new Notification.Builder(this);
+    final Intent launchIntent = getPackageManager().getLaunchIntentForPackage(getPackageName());
+    if (launchIntent == null) {
+      throw new com.sfourdrinier.unifiedblemanager.background.ForegroundServiceControlException(
+          "foregroundServiceNotConfigured", "The host app has no launchable activity for the notification tap.");
+    }
+    final PendingIntent contentIntent = PendingIntent.getActivity(
+        this,
+        ForegroundServiceNotificationConfiguration.NOTIFICATION_ID,
+        launchIntent,
+        Build.VERSION.SDK_INT >= Build.VERSION_CODES.M
+            ? PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
+            : PendingIntent.FLAG_UPDATE_CURRENT);
+    builder
+        .setSmallIcon(iconResource(this, configuration.getIconName()))
+        .setContentTitle(configuration.getTitle())
+        .setContentIntent(contentIntent)
+        .setOngoing(true)
+        .setCategory(Notification.CATEGORY_SERVICE);
+    if (configuration.getBody() != null) builder.setContentText(configuration.getBody());
+    return builder.build();
+  }
+
   private static String required(Intent intent, String name) {
     final String value = intent.getStringExtra(name);
     if (value == null || value.isEmpty()) {

package/android/src/main/java/com/sfourdrinier/unifiedblemanager/background/AndroidConnectedDeviceForegroundServiceDriver.java

@@ -32,6 +32,11 @@ public final class AndroidConnectedDeviceForegroundServiceDriver
 
   @Override
   public void start(String reason) {
+    if (Looper.myLooper() == Looper.getMainLooper()) {
+      throw new ForegroundServiceControlException(
+          "foregroundServiceMainThreadUnavailable",
+          "Android foreground-service acquisition cannot wait for promotion on the main thread.");
+    }
     final ForegroundServiceNotificationConfiguration configuration = configuration();
     requireRuntimePermissions();
     final CountDownLatch acknowledgement = new CountDownLatch(1);
@@ -116,6 +121,19 @@ public final class AndroidConnectedDeviceForegroundServiceDriver
     }
   }
 
+  @Override
+  public void update(String title, String body) {
+    try {
+      BlePlxForegroundService.updateNotification(title, body);
+    } catch (RuntimeException error) {
+      if (error instanceof ForegroundServiceControlException) throw error;
+      throw new ForegroundServiceControlException(
+          "foregroundServiceNotificationUpdateFailed",
+          "Android could not update the connected-device foreground-service notification; retry while the lease is active.",
+          error);
+    }
+  }
+
   private ForegroundServiceNotificationConfiguration configuration() {
     try {
       final ApplicationInfo application = context.getPackageManager().getApplicationInfo(

package/android/src/main/java/com/sfourdrinier/unifiedblemanager/background/BlePlxForegroundServiceRecoveryReceiver.java

@@ -0,0 +1,50 @@
+package com.sfourdrinier.unifiedblemanager.background;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.os.Build;
+import android.util.Log;
+
+import com.sfourdrinier.unifiedblemanager.BlePlxForegroundService;
+
+/** Restores only the configured foreground service; it never scans or reconnects. */
+public final class BlePlxForegroundServiceRecoveryReceiver extends BroadcastReceiver {
+  private static final String TAG = "UnifiedBleRecovery";
+
+  @Override
+  public void onReceive(Context context, Intent intent) {
+    if (intent == null || (!Intent.ACTION_BOOT_COMPLETED.equals(intent.getAction())
+        && !Intent.ACTION_MY_PACKAGE_REPLACED.equals(intent.getAction()))) return;
+    if (!context.getSharedPreferences("unified-ble-manager", Context.MODE_PRIVATE)
+        .getBoolean(BlePlxForegroundService.SESSION_INTENT_PREFERENCE, false)) return;
+    try {
+      final ForegroundServiceNotificationConfiguration configuration = configuration(context);
+      if (!configuration.restartWhileSessionIntentExists()) return;
+      final Intent start = BlePlxForegroundService.startIntent(context, configuration);
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) context.startForegroundService(start);
+      else context.startService(start);
+    } catch (RuntimeException error) {
+      Log.e(TAG, "Connected-device foreground-service recovery failed", error);
+    }
+  }
+
+  private static ForegroundServiceNotificationConfiguration configuration(Context context) {
+    try {
+      final android.content.pm.ApplicationInfo application =
+          context.getPackageManager().getApplicationInfo(
+              context.getPackageName(), android.content.pm.PackageManager.GET_META_DATA);
+      final java.util.Map<String, String> metadata = new java.util.HashMap<>();
+      if (application.metaData != null) {
+        for (String key : application.metaData.keySet()) {
+          final Object value = application.metaData.get(key);
+          if (value instanceof String) metadata.put(key, (String) value);
+        }
+      }
+      return ForegroundServiceNotificationConfiguration.fromMetadata(metadata);
+    } catch (android.content.pm.PackageManager.NameNotFoundException error) {
+      throw new ForegroundServiceControlException(
+          "foregroundServiceNotConfigured", "Managed foreground-service metadata is unavailable", error);
+    }
+  }
+}

package/android/src/main/java/com/sfourdrinier/unifiedblemanager/background/ConnectedDeviceForegroundServiceDriver.java

@@ -3,4 +3,5 @@ package com.sfourdrinier.unifiedblemanager.background;
 public interface ConnectedDeviceForegroundServiceDriver {
   void start(String reason);
   void stop();
+  void update(String title, String body);
 }

package/android/src/main/java/com/sfourdrinier/unifiedblemanager/background/ConnectedDeviceForegroundServiceLeaseRegistry.java

@@ -44,6 +44,15 @@ public final class ConnectedDeviceForegroundServiceLeaseRegistry {
     leases.clear();
   }
 
+  public synchronized void update(String leaseId, String title, String body) {
+    if (!leases.contains(leaseId)) {
+      throw new ForegroundServiceControlException(
+          "invalidBackgroundLease",
+          "The connected-device background lease is stale or already released.");
+    }
+    driver.update(title, body);
+  }
+
   public synchronized int activeLeaseCount() {
     return leases.size();
   }

package/android/src/main/java/com/sfourdrinier/unifiedblemanager/protocol/UnifiedBleProtocolAndroidDispatcher.kt

@@ -7,9 +7,11 @@ import android.content.Context
 import android.os.Build
 import android.os.SystemClock
 import com.sfourdrinier.unifiedblemanager.protocol.generated.NATIVE_PROTOCOL_VERSION
+import com.sfourdrinier.unifiedblemanager.protocol.generated.ConnectionIntents
 import com.sfourdrinier.unifiedblemanager.protocol.generated.RecordKind
 import com.sfourdrinier.unifiedblemanager.radio.OwnedAndroidGattRadio
 import com.sfourdrinier.unifiedblemanager.radio.OwnedRadioTeardownFailure
+import com.sfourdrinier.unifiedblemanager.radio.BondedPeerSnapshot
 import com.sfourdrinier.unifiedblemanager.radio.nextUuidOccurrence
 import java.util.UUID
 import java.util.concurrent.ConcurrentHashMap
@@ -204,6 +206,7 @@ class UnifiedBleProtocolAndroidDispatcher(
           securityEventsEnabled.set(true)
           securityCancelPairing(command)
         }
+        "enumerateBondedPeers" -> enumerateBondedPeers(command)
         "subscribe" -> subscribe(command, true)
         "unsubscribe" -> subscribe(command, false)
         "cancel" -> cancel(command)
@@ -286,7 +289,11 @@ class UnifiedBleProtocolAndroidDispatcher(
     val prior = pendingConnects.putIfAbsent(peerId.uppercase(), command)
     require(prior == null) { "A protocol connect is already pending for this peer" }
     try {
-      radio.connect(peerId, false)
+      val autoConnect = when (connectionIntent(command.requiredString(20))) {
+        ConnectionIntents.DIRECT -> false
+        ConnectionIntents.WHEN_AVAILABLE -> true
+      }
+      radio.connect(peerId, autoConnect)
     } catch (error: Exception) {
       pendingConnects.remove(peerId.uppercase(), command)
       throw error
@@ -736,7 +743,8 @@ class UnifiedBleProtocolAndroidDispatcher(
 
   private fun securityPair(command: ProtocolWireRecord) {
     val peerId = command.requiredString(15)
-    val operationId = radio.pair(peerId) { outcome, state ->
+    val pairTransport = command.requiredString(19)
+    val operationId = radio.pair(peerId, pairTransport) { outcome, state ->
       if (!isPending(command)) return@pair
       if (outcome == "rejected") {
         emitFailure(command, "pairRejected", "Android rejected the system bond request")
@@ -764,7 +772,32 @@ class UnifiedBleProtocolAndroidDispatcher(
     emitSuccess(command, "accepted")
   }
 
+  private fun enumerateBondedPeers(command: ProtocolWireRecord) {
+    val snapshots = bondedPeerSnapshotRecords(radio.bondedPeerSnapshots())
+    emitSuccess(
+      command,
+      "bondedPeers",
+      mapOf(23 to ProtocolWireValue.RecordListValue(snapshots))
+    )
+  }
+
   private fun emitSuccess(command: ProtocolWireRecord, kind: String, additions: Map<Int, ProtocolWireValue> = emptyMap()) {
+    if (kind == "bondedPeers") {
+      // Bonded enumeration reads Android metadata synchronously and can block while
+      // JSI cancellation or attachment teardown runs concurrently. Claim first so
+      // only one terminal path owns this command's result.
+      if (!claimExactPendingCommand(pendingCommands, operationKey(command), command)) return
+      val records = additions[23]
+      require(records is ProtocolWireValue.RecordListValue) {
+        "Android bonded peer result is missing its peer snapshot list"
+      }
+      UnifiedBleProtocolJsiBinding.emitRecord(
+        nativeHandle,
+        ProtocolWireEncoder.encode(bondedPeerResultRecord(command.requiredRecord(2), records.value))
+      )
+      radioOperationIds.remove(operationKey(command))
+      return
+    }
     if (!isPending(command)) return
     val fields = mutableMapOf<Int, ProtocolWireValue>(
       1 to ProtocolWireValue.UnsignedIntegerValue(NATIVE_PROTOCOL_VERSION.toLong()),
@@ -779,13 +812,18 @@ class UnifiedBleProtocolAndroidDispatcher(
       }
     }
     fields.putAll(additions)
-    UnifiedBleProtocolJsiBinding.emitRecord(nativeHandle, ProtocolWireEncoder.encode(ProtocolWireRecord(RecordKind.RESULT, fields)))
-    pendingCommands.remove(operationKey(command), command)
+    val result = ProtocolWireRecord(RecordKind.RESULT, fields)
+    UnifiedBleProtocolJsiBinding.emitRecord(nativeHandle, ProtocolWireEncoder.encode(result))
+    claimExactPendingCommand(pendingCommands, operationKey(command), command)
     radioOperationIds.remove(operationKey(command))
   }
 
   private fun emitFailure(command: ProtocolWireRecord, code: String, message: String) {
-    if (!isPending(command)) return
+    val bondedPeerCommand = command.requiredString(3) == "enumerateBondedPeers"
+    if (bondedPeerCommand) {
+      // Keep failure/cancellation/teardown mutually exclusive with a late success.
+      if (!claimExactPendingCommand(pendingCommands, operationKey(command), command)) return
+    } else if (!isPending(command)) return
     val error = ProtocolWireRecord(
       RecordKind.ERROR,
       mapOf(
@@ -806,12 +844,15 @@ class UnifiedBleProtocolAndroidDispatcher(
       )
     )
     UnifiedBleProtocolJsiBinding.emitRecord(nativeHandle, ProtocolWireEncoder.encode(result))
-    pendingCommands.remove(operationKey(command), command)
+    if (!bondedPeerCommand) claimExactPendingCommand(pendingCommands, operationKey(command), command)
     radioOperationIds.remove(operationKey(command))
   }
 
   private fun emitCancelled(command: ProtocolWireRecord) {
-    if (!isPending(command)) return
+    val bondedPeerCommand = command.requiredString(3) == "enumerateBondedPeers"
+    if (bondedPeerCommand) {
+      if (!claimExactPendingCommand(pendingCommands, operationKey(command), command)) return
+    } else if (!isPending(command)) return
     val result = ProtocolWireRecord(
       RecordKind.RESULT,
       mapOf(
@@ -833,7 +874,7 @@ class UnifiedBleProtocolAndroidDispatcher(
       )
     )
     UnifiedBleProtocolJsiBinding.emitRecord(nativeHandle, ProtocolWireEncoder.encode(result))
-    pendingCommands.remove(operationKey(command), command)
+    if (!bondedPeerCommand) claimExactPendingCommand(pendingCommands, operationKey(command), command)
     radioOperationIds.remove(operationKey(command))
   }
 
@@ -849,7 +890,7 @@ class UnifiedBleProtocolAndroidDispatcher(
       )
     )
     UnifiedBleProtocolJsiBinding.emitRecord(nativeHandle, ProtocolWireEncoder.encode(result))
-    pendingCommands.remove(operationKey(command), command)
+    claimExactPendingCommand(pendingCommands, operationKey(command), command)
   }
 
   private fun emitConnectionLost(connection: ProtocolWireRecord, status: Int) {
@@ -1163,15 +1204,75 @@ internal fun dispatcherResultKindFor(commandKind: String): String = when (comman
   "unsubscribe" -> "unsubscribed"
   "securityState" -> "securityState"
   "securityPair" -> "securityPair"
+  "enumerateBondedPeers" -> "bondedPeers"
   "destroy" -> "destroyed"
   else -> "accepted"
 }
 
+internal fun bondedPeerResultRecord(
+  correlation: ProtocolWireRecord,
+  snapshots: List<ProtocolWireRecord>
+): ProtocolWireRecord = ProtocolWireRecord(
+  RecordKind.RESULT,
+  mapOf(
+    1 to ProtocolWireValue.UnsignedIntegerValue(NATIVE_PROTOCOL_VERSION.toLong()),
+    2 to ProtocolWireValue.StringValue("bondedPeers"),
+    3 to ProtocolWireValue.RecordValue(
+      ProtocolWireRecord(
+        RecordKind.TERMINAL,
+        mapOf(
+          1 to ProtocolWireValue.RecordValue(correlation),
+          2 to ProtocolWireValue.StringValue("succeeded")
+        )
+      )
+    ),
+    23 to ProtocolWireValue.RecordListValue(snapshots)
+  )
+)
+
+internal fun bondedPeerSnapshotRecords(
+  snapshots: Iterable<BondedPeerSnapshot>
+): List<ProtocolWireRecord> = snapshots.map { peer ->
+  ProtocolWireRecord(
+    RecordKind.BONDED_PEER_SNAPSHOT,
+    buildMap {
+      put(1, ProtocolWireValue.StringValue(peer.nativePeerId))
+      peer.displayName?.let { name -> put(2, ProtocolWireValue.StringValue(name)) }
+    }
+  )
+}
+
+/** Atomically claim one pending command by operation key and object identity. */
+internal fun claimExactPendingCommand(
+  pending: ConcurrentHashMap<String, ProtocolWireRecord>,
+  key: String,
+  command: ProtocolWireRecord
+): Boolean {
+  var removed = false
+  pending.computeIfPresent(key) { _, candidate ->
+    if (candidate === command) {
+      removed = true
+      null
+    } else {
+      candidate
+    }
+  }
+  return removed
+}
+
 private fun ProtocolWireRecord.requiredBoolean(fieldId: Int): Boolean {
   val value = fields[fieldId]
   return if (value is ProtocolWireValue.BooleanValue) value.value else throw IllegalArgumentException("Boolean field is missing")
 }
 
+private fun connectionIntent(value: String): ConnectionIntents {
+  return when (value) {
+    "direct" -> ConnectionIntents.DIRECT
+    "whenAvailable" -> ConnectionIntents.WHEN_AVAILABLE
+    else -> throw IllegalArgumentException("Connection intent is invalid")
+  }
+}
+
 private fun ProtocolWireRecord.requiredSignedInteger(fieldId: Int): Long {
   val value = fields[fieldId]
   return if (value is ProtocolWireValue.SignedIntegerValue) value.value else throw IllegalArgumentException("Signed field is missing")