unified-ble-manager 4.0.6 → 4.0.8

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 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
+
+- `cancelPairing()` reports what the cancellation **achieved**, not what it requested, and can no longer contradict the pairing it cancelled. Every backend answered `'cancelled'` unconditionally the moment the cancel was dispatched, so a cancellation that lost the race told the caller no bond exists while one did — and a caller who believes that never looks again. It now reads the in-flight pairing's own result rather than forming a second opinion, which is what makes the two calls incapable of disagreeing: there is one source of truth and the cancellation reads it. `SecurityCancelPairingResult` gains the words to say so — `'paired'` when the bond completed before the cancellation arrived, and `'rejected'` (carrying the peer's reason) when the peer refused, because claiming credit for stopping something that stopped itself is the same substitution with the arrow reversed. A pairing that *fails* is not given an invented outcome: `cancelPairing()` rejects with the error the pairing rejected with. `'paired'` deliberately matches `SecurityPairResult`'s `'paired'` — a bond exists as a result of this operation — and is not `'already-paired'`, which in that type means the peer was bonded *before* the call; one word, one meaning, in both types. Applies to BlueZ, Android, WinRT **and** the deterministic `/testing` backend, since a mock that answers differently from every real radio lets a consumer's suite pass against a contract no device honours. WinRT additionally short-circuited *upstream* of the shared mapper — when its dispatcher reported the operation already terminal, which is exactly the lost race, it answered `'not-pairing'`, contradicting its own `pair()` and making that word mean both "there was nothing to stop" and "it was already over" (#159).
+
+### Additions
+
+- **`PairOptions.secureConnections` can now actually select the LE pairing generation on BlueZ — behind a host-supplied privileged operation.** Some peripherals accept only LE Legacy and terminate the link on a Secure Connections pairing request; 4.0.6 gave the contract a way to say so but no backend that could honour it. `org.bluez.Adapter1` (BlueZ 5.85) exposes no Secure Connections property and `Device1.Pair` takes no parameters — the setting lives behind the kernel management socket's Set Secure Connections command, which requires **`CAP_NET_ADMIN`**.
+
+  This package never acquires that privilege: it opens no management socket, shells out to nothing, and does not assume it is root. A library that silently escalates hands an application capabilities its author did not choose and cannot audit. The **host** supplies the operation via `BluezBackendProviderOptions.pairingGeneration`, which makes the escalation visible in the application that opted into it. Omit it and `'require'`/`'disallow'` keep failing closed exactly as in 4.0.6 — the default posture is unchanged.
+
+  Three properties of the kernel setting a host must accept, documented in `docs/BONDING.md` rather than discovered: it is **adapter-wide**, not per-pairing, so every pairing on that controller uses the selected generation while it is held; it **outlives the process**, because the kernel keeps it until something sets it back; and a **failed restore never changes the pairing's outcome** — a bond that was created is reported as created, with the restore failure reported separately, because leaving a controller in LE Legacy and telling a caller they are not bonded are both serious and are different facts. Concurrent *directed* pairings on one adapter are serialised so they cannot corrupt each other's restore value; an undirected (`'prefer'`) pairing does not take that lock and uses whichever generation is held, which `docs/BONDING.md` states beside the option.
+
+  `security:pairing-generation` joins the capability catalog and is reported by the instantiated backend at runtime: `unsupported` with the platform reason when no operation was supplied, `limited` when one was — so two BlueZ backends on one machine legitimately answer differently. Evidence is deterministic tests only; this is **not** physical-radio proof, and the label says so (#144).
+
+### Fixes
+
+- A Tauri connect that succeeds physically but is then denied admission no longer strands the peer. Both compensation branches — the caller vanished, and the caller's lease went stale — removed the peer reservation *before* attempting the disconnect and then discarded its result with `.ok()`. If that disconnect failed or hung while the peripheral stayed connected, the result was a connected peer with no owner and no handle: nothing could reach it, nothing could retry it, and the caller was told only that admission was denied. Compensation now follows the rule the explicit disconnect already follows — a bounded wait, a fresh state reading, and a D-Bus error naming a vanished device object read as evidence of release rather than as a failed question — and surrenders the reservation only when the platform proves the link is down. Genuine indeterminacy keeps it so a retry can reclaim the peer, and the admission error carries what compensation could not undo, which is the difference between "try again" and "a peer is stranded" (#146).
+
+### Known limitations
+
+- `pair()`'s abort path still reports `'cancelled'` without knowing whether the daemon bonded anyway. Learning the truth means waiting for the radio, and waiting risks a hang that a wedged daemon would inflict on the caller — which the suite explicitly forbids. Resolving it needs a vocabulary that can express "cancellation requested, bond state not yet known"; `state()` and `watch()` remain authoritative meanwhile (#157).
+
 ## [4.0.6] - 2026-08-26
 
 The first release cut against a live peripheral on Android as well as Linux. Most of it is defects that only real hardware surfaced, several of them boundaries that discarded evidence and so presented a specific fault as silence. Does not retag `v4.0.5`.
@@ -38,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.6`. 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.6` 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`, and `4.0.5` are immutable. `4.0.6` 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,58 @@ 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
+exact current `main` commit before publication; do not create it from a side
+branch or an older commit. Do not retag any immutable version.
+
+```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.7"
+git diff --exit-code
+git diff --cached --exit-code
+
+git tag -a v4.0.7 -m "v4.0.7"
+git push origin v4.0.7
+```
+
+Do not push another commit to `main` between the final verification and the tag
+push.
+
+Before tagging, confirm the release-notes extraction finds the entry — the
+workflow's awk matches `^## \[4.0.7\]`, and a heading left as `[Unreleased]`
+publishes a stub instead of the changelog:
+
+```sh
+awk -v ver=4.0.7 '$0 ~ ("^## \\[" ver "\\]") {p=1;next} p && $0 ~ /^## \[/ {exit} p {print}' CHANGELOG.md
+```
+
 ## Releasing 4.0.6
 
 The source version is prepared on `main` before the tag. The release workflow verifies that every initial release tag points at the exact current `main` commit before publication; do not create that tag from a side branch or an older commit. Do not retag immutable `v4.0.0`, `v4.0.1`, `v4.0.2`, or `v4.0.3`.

package/SBOM.cdx.json

@@ -6,15 +6,15 @@
   "metadata": {
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/unified-ble-manager@4.0.6",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.8",
       "name": "unified-ble-manager",
-      "version": "4.0.6",
+      "version": "4.0.8",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.6"
+      "purl": "pkg:npm/unified-ble-manager@4.0.8"
     },
     "properties": [
       {
@@ -560,7 +560,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.6",
+      "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.6"
+    "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();
   }