@mentra/bluetooth-sdk 3.2.1-beta.506 → 3.2.1-beta.512

package/android/src/main/java/com/mentra/bluetoothsdk/BluetoothSdkModule.kt

@@ -550,6 +550,8 @@ class BluetoothSdkModule : Module() {
 
         SdkAsyncFunction("forget") { -> sdk?.forget() }
 
+        SdkCoroutineFunction("unpair") { -> deviceManager?.unpair() }
+
         AsyncFunction("connectDefaultController") { deviceManager?.connectDefaultController() }
 
         AsyncFunction("disconnectController") { deviceManager?.disconnectController() }

package/android/src/main/java/com/mentra/bluetoothsdk/DeviceManager.kt

@@ -35,7 +35,10 @@ import com.mentra.bluetoothsdk.utils.MicTypes
 import com.mentra.bluetoothsdk.utils.PhoneAudioMonitor
 import com.mentra.lc3Lib.Lc3Cpp
 import com.mentra.bluetoothsdk.stt.SherpaOnnxTranscriber
+import kotlin.coroutines.resume
+import kotlinx.coroutines.suspendCancellableCoroutine
 import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.withContext
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import java.text.SimpleDateFormat
@@ -1537,6 +1540,7 @@ class DeviceManager internal constructor(initializeHardware: Boolean) {
         // re-apply display height/depth after reconnection
         mainHandler.postDelayed(
             {
+                val device = sgc ?: return@postDelayed
                 val h =
                     (DeviceStore.store.get("bluetooth", "dashboard_height") as? Number)
                         ?.toInt()
@@ -1545,8 +1549,8 @@ class DeviceManager internal constructor(initializeHardware: Boolean) {
                     (DeviceStore.store.get("bluetooth", "dashboard_depth") as? Number)
                         ?.toInt()
                         ?: dashboardDepth // canonical default (2), not 1
-                val d = rawDepth.coerceIn(1, 4)
-                sgc?.setDashboardPosition(h, d)
+                val d = if (device.type == DeviceTypes.NIMO) rawDepth.coerceIn(0, 10) else rawDepth.coerceIn(1, 4)
+                device.setDashboardPosition(h, d)
             },
             2000
         )
@@ -2501,6 +2505,37 @@ class DeviceManager internal constructor(initializeHardware: Boolean) {
         controller = null
     }
 
+    private var unpairInProgress = false
+
+    /** Explicit user Unpair, separate from passive pairing cleanup and logout. */
+    suspend fun unpair() = withContext(Dispatchers.Main) {
+        check(!unpairInProgress) { "Unpair already in progress" }
+        unpairInProgress = true
+        try {
+            val target = sgc
+            val nimo = target as? Nimo
+            val savedNimoAddress = when {
+                defaultWearable == DeviceTypes.NIMO -> deviceAddress
+                pendingWearable == DeviceTypes.NIMO -> pendingDeviceAddress
+                else -> null
+            }
+            if (nimo != null) {
+                suspendCancellableCoroutine<Boolean> { continuation ->
+                    nimo.resetForUnpair { if (continuation.isActive) continuation.resume(it) }
+                }
+                check(sgc === target) { "Glasses changed during Unpair" }
+                // Drop the encrypted link before removing the phone's bond.
+                nimo.disconnect()
+                nimo.removeBluetoothBond()
+            } else if (target == null && savedNimoAddress != null) {
+                Nimo.removeBluetoothBond(savedNimoAddress)
+            }
+            forget()
+        } finally {
+            unpairInProgress = false
+        }
+    }
+
     fun forget() {
         synchronized(recoveryLock) {
             recoverG2Connection = false

package/android/src/main/java/com/mentra/bluetoothsdk/GeneratedReleaseMetadata.kt

@@ -3,9 +3,9 @@ package com.mentra.bluetoothsdk
 /** Generated by release CI. Do not edit in a release checkout. */
 internal object GeneratedReleaseMetadata {
     const val FAMILY_BASE_VERSION: String = "3.2.1"
-    const val RELEASE_IDENTITY: String = "3.2.1-beta.506"
-    const val RELEASE_SET_ID: String = "mentra-3.2.1-beta.506"
-    const val SOURCE_COMMIT: String = "cb87ecd9de2a0d253e54728493f1e8002c128207"
-    const val OTA_MANIFEST_URL: String = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.2.1/mentra-live-ota-3.2.1-beta.506.json"
-    const val OTA_MANIFEST_SHA256: String = "af76d286c921c9c8f22b938a92b0b13aa983f1983c377006df51a1ad7646eed7"
+    const val RELEASE_IDENTITY: String = "3.2.1-beta.512"
+    const val RELEASE_SET_ID: String = "mentra-3.2.1-beta.512"
+    const val SOURCE_COMMIT: String = "e09a07ee7b71972e75a5051003ec561c12e6cb9b"
+    const val OTA_MANIFEST_URL: String = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.2.1/mentra-live-ota-3.2.1-beta.512.json"
+    const val OTA_MANIFEST_SHA256: String = "bd24cbd8279319912d643699eeb435df3ca88582194953583491a3625799ec01"
 }

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/Nimo.kt

@@ -69,6 +69,7 @@ internal object NimoProtocol {
     const val CMD_INSTRUCTION_REPORT = 0x06
     const val CMD_CONTROL_INSTRUCTION = 0x07
     const val CMD_CONTROL_FACTORY = 0x08
+    const val FACTORY_RECOVER = 0x03
     const val CMD_CONTROL_NOTIFICATION = 0x09
 
     // get parameter keys
@@ -89,6 +90,9 @@ internal object NimoProtocol {
     const val SET_DISPLAY_OFF = 0x0F
     const val SET_PHONE_TYPE = 0x14
     const val SET_HEIGHT_LEVEL = 0x17
+    // Dynamic-v1 firmware: 1-based UI locale; 1 selects English.
+    const val SET_SYSTEM_LANGUAGE = 0x24
+    const val LANGUAGE_ENGLISH = 0x01
 
     // control instruction keys
     const val CTRL_ENTER_APP = 0x01
@@ -889,6 +893,17 @@ class Nimo : SGCManager() {
         private const val KEY_LAST_ADDRESS = "nimo_lastDeviceAddress"
         private const val KEY_LAST_NAME = "nimo_lastDeviceName"
 
+        internal fun removeBluetoothBond(address: String?) {
+            if (address.isNullOrBlank()) return
+            try {
+                val device = BluetoothAdapter.getDefaultAdapter()?.getRemoteDevice(address) ?: return
+                val removed = device.javaClass.getMethod("removeBond").invoke(device) as? Boolean
+                Bridge.log("NIMO: Bluetooth unbond requested=$removed")
+            } catch (error: Exception) {
+                Bridge.log("NIMO: Bluetooth unbond failed: ${error.message}")
+            }
+        }
+
         private const val TWS_TIMEOUT_MS = 10_000L
         private const val ACK_TIMEOUT_MS = 5_000L
         // Generous: the glasses' classic bond can take 30-45s PER attempt and may need
@@ -1097,6 +1112,31 @@ class Nimo : SGCManager() {
         DeviceStore.apply("glasses", "connectionState", ConnTypes.DISCONNECTED)
     }
 
+    /** Explicit Unpair only. Ordinary forget/cleanup must never reset the glasses. */
+    internal fun resetForUnpair(onResult: (Boolean) -> Unit) {
+        check(Looper.myLooper() == mainHandler.looper)
+        if (gatt == null || txChar == null || handshakeState != HandshakeState.READY) {
+            Bridge.log("NIMO: unpair while offline; remote reset unavailable")
+            onResult(false)
+            return
+        }
+        isDisconnecting = true
+        stopTimers()
+        reconnectionManager.stop()
+        canvasEncoder.invalidate()
+        canvas.disconnected()
+        Bridge.log("NIMO: sending factory reset for explicit Unpair")
+        sendAwaitingAck(NimoProtocol.CMD_CONTROL_FACTORY, NimoProtocol.FACTORY_RECOVER, byteArrayOf()) {
+            Bridge.log("NIMO: factory reset acknowledged=$it")
+            onResult(it)
+        }
+    }
+
+    internal fun removeBluetoothBond() {
+        val address = gatt?.device?.address ?: lastDeviceAddress ?: return
+        removeBluetoothBond(address)
+    }
+
     override fun forget() {
         if (Looper.myLooper() != mainHandler.looper) {
             runBlocking { withContext(Dispatchers.Main) { forget() } }
@@ -1980,7 +2020,10 @@ class Nimo : SGCManager() {
         }
         val timeout = Runnable {
             // Do not retry a timed-out key on the same transport: a late response is uncorrelated.
-            if (pendingAcks.remove(ackKey) != null) abortTransport("Handshake ACK timeout cmd=$cmd key=$key")
+            pendingAcks.remove(ackKey)?.let { expired ->
+                abortTransport("ACK timeout cmd=$cmd key=$key")
+                expired.onResult(false)
+            }
         }
         pendingAcks[ackKey] = PendingAck(onResult, timeout)
         mainHandler.postDelayed(timeout, timeoutMs)
@@ -2080,6 +2123,9 @@ class Nimo : SGCManager() {
                         needsAck = false
                 )
         )
+        // Optional setting: older firmware may reject it without preventing connection.
+        sendFrame(NimoFrameCodec.encodeFrame(NimoProtocol.CMD_SET_PARAMETER,
+            NimoProtocol.SET_SYSTEM_LANGUAGE, byteArrayOf(NimoProtocol.LANGUAGE_ENGLISH.toByte())))
         getBatteryStatus()
         requestVersionInfo()
 
@@ -2099,7 +2145,10 @@ class Nimo : SGCManager() {
             )
         }
         diagnostics?.connected((negotiatedMtu - 3).coerceIn(20, 512))
-        canvas.readiness(twsConnected && peerCompanionReady == true)
+        // Launch checks peer readiness in firmware; do not wait up to a minute for
+        // the first unsolicited heartbeat just because peer status is still unknown.
+        canvas.activate()
+        canvas.readiness(twsConnected && peerCompanionReady != false)
     }
 
     private fun handshakeFailed() {
@@ -2175,6 +2224,7 @@ class Nimo : SGCManager() {
         if (diagnostics?.onPacket(packet) == true) return
         if (packet.size >= 10 && packet[8].toInt() == 7 && (packet[9].toInt() and 255) in listOf(1, 3, 4)) {
             val response = NimoCanvasCodec.response(packet) ?: return
+            if (response.first == 1) Bridge.log("NIMO: canvas Launch response status=${response.second.firstOrNull()?.toInt()}")
             canvas.response(response.first, response.second)
             return
         }
@@ -2206,13 +2256,13 @@ class Nimo : SGCManager() {
                             if (appId != NimoCanvasCodec.APP_ID) {
                                 diagnostics?.cancelHeldCapture("Native app takeover preempted held capture", resumeCanvas = false)
                             }
-                            if (canvas.nativeApp(appId, true)) canvasEncoder.invalidate()
+                            canvas.nativeApp(appId, true)
                         }
                         NimoProtocol.STATE_EXIT -> {
                             if (appId == NimoCanvasCodec.APP_ID) {
                                 diagnostics?.cancelHeldCapture("Canvas exit preempted held capture", resumeCanvas = false)
                             }
-                            if (canvas.nativeApp(appId, false)) canvasEncoder.invalidate()
+                            canvas.nativeApp(appId, false)
                         }
                     }
                 }
@@ -2244,7 +2294,7 @@ class Nimo : SGCManager() {
                     // Both predicates were sampled by this device report. TWS-only
                     // reports and cached state cannot release a status-7 wait.
                     if (handshakeState == HandshakeState.READY) {
-                        canvas.confirmedReadiness(twsConnected && peerCompanionReady == true)
+                        canvas.confirmedReadiness(twsConnected && peerCompanionReady != false)
                     }
                 }
             }
@@ -2270,7 +2320,7 @@ class Nimo : SGCManager() {
         if (!connected && handshakeState == HandshakeState.READY) {
             Bridge.log("NIMO: TWS service dropped mid-session (arm removed/off?)")
         }
-        if (handshakeState == HandshakeState.READY) canvas.readiness(connected && peerCompanionReady == true)
+        if (handshakeState == HandshakeState.READY) canvas.readiness(connected && peerCompanionReady != false)
     }
 
     private fun handleInputEvent(code: Int) {
@@ -2306,6 +2356,9 @@ class Nimo : SGCManager() {
             // 5 not supported, 6 bad parameter, 7 device busy.
             Bridge.log("NIMO: response cmd=$cmd key=$key error status=$statusCode")
         }
+        if (cmd == NimoProtocol.CMD_SET_PARAMETER && key == NimoProtocol.SET_SYSTEM_LANGUAGE) {
+            Bridge.log("NIMO: English menu setting acknowledged=${statusCode == 0} status=$statusCode")
+        }
         resolvePendingAck(cmd, key, statusCode == 0)
 
         if (cmd != NimoProtocol.CMD_GET_PARAMETER || statusCode != 0) return

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/NimoCanvasCoordinator.kt

@@ -132,6 +132,7 @@ internal class NimoCanvasCoordinator(
     private var holding = false
     private var heldScope: String? = null
     private var cancelDeadline: (() -> Unit)? = null
+    private var cancelRetry: (() -> Unit)? = null
 
     fun offer(bytes: ByteArray, scope: String, force: Boolean = false) {
         if (holding && scope != heldScope) {
@@ -140,8 +141,15 @@ internal class NimoCanvasCoordinator(
         }
         run(session.offer(bytes, scope, force))
     }
-    fun readiness(ready: Boolean) = run(session.readiness(ready))
-    fun confirmedReadiness(ready: Boolean) = run(session.confirmedReadiness(ready))
+    fun activate() = run(session.activate())
+    fun readiness(ready: Boolean) {
+        if (!ready) { cancelRetry?.invoke(); cancelRetry = null }
+        run(session.readiness(ready))
+    }
+    fun confirmedReadiness(ready: Boolean) {
+        if (!ready) { cancelRetry?.invoke(); cancelRetry = null }
+        run(session.confirmedReadiness(ready))
+    }
     fun hold(onReady: () -> Unit) {
         session.hold(true)
         holding = true
@@ -155,19 +163,14 @@ internal class NimoCanvasCoordinator(
         heldScope = null
         run(session.hold(false, resume))
     }
-    fun exit() = run(session.exit())
-    /** Whether this report also invalidates an unfinished host encode. Exit's report does not
-     * invalidate a NEW scene submitted while the explicit Exit waits for its business ACK. */
-    fun nativeApp(appId: Int, entered: Boolean): Boolean {
-        val takeover = (appId == NimoCanvasCodec.APP_ID && !entered) ||
-            (appId != NimoCanvasCodec.APP_ID && entered)
-        val expectedExitReport = appId == NimoCanvasCodec.APP_ID && !entered && flight?.action?.key == 3
-        val invalidateEncoding = takeover && !expectedExitReport
-        run(session.nativeApp(appId, entered))
-        return invalidateEncoding
+    fun exit() {
+        cancelRetry?.invoke(); cancelRetry = null
+        run(session.exit())
     }
+    fun nativeApp(appId: Int, entered: Boolean) = run(session.nativeApp(appId, entered))
 
     fun disconnected() {
+        cancelRetry?.invoke(); cancelRetry = null
         cancelDeadline?.invoke(); cancelDeadline = null
         flight = null
         holdReady = null
@@ -199,6 +202,7 @@ internal class NimoCanvasCoordinator(
     private fun run(actions: List<NimoCanvasSession.Action>) {
         for (action in actions) when (action) {
             is NimoCanvasSession.Action.Send -> {
+                cancelRetry?.invoke(); cancelRetry = null
                 cancelDeadline?.invoke()
                 val current = Flight(action)
                 flight = current
@@ -219,7 +223,16 @@ internal class NimoCanvasCoordinator(
                 }
             }
             is NimoCanvasSession.Action.Reconnect -> { disconnected(); reconnect(action.reason) }
-            is NimoCanvasSession.Action.Rejected -> rejected(action.status)
+            is NimoCanvasSession.Action.Rejected -> {
+                rejected(action.status)
+                if (action.status == 7) {
+                    cancelRetry?.invoke()
+                    cancelRetry = scheduler.post(1_000) {
+                        cancelRetry = null
+                        run(session.retryNotReady())
+                    }
+                }
+            }
         }
     }
 }

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/NimoCanvasSession.kt

@@ -9,6 +9,7 @@ internal class NimoCanvasSession {
   }
   private data class Flight(val key: Int, val frame: ByteArray, val ticket: Long)
   private var ready = false
+  private var transportReady = false
   private var active = false
   private var held = false
   private var locked = false
@@ -16,6 +17,7 @@ internal class NimoCanvasSession {
   private var waitingReadiness = false
   private var observedNotReady = false
   private var readinessRetries = 0
+  private var probeRetries = 0
   private var exitRequested = false
   private var desired: ByteArray? = null
   private var accepted: ByteArray? = null
@@ -35,6 +37,23 @@ internal class NimoCanvasSession {
     return pump()
   }
 
+  /** Enter a blank canvas on a fresh connection unless a newer host scene is retained. */
+  fun activate(): List<Action> {
+    if (desired == null) desired = byteArrayOf(0, 0, 1)
+    exitRequested = false
+    return pump()
+  }
+
+  /** Launch itself checks peer readiness in firmware. Retry only explicit NOT_READY,
+   * with a small budget; never retry an ambiguous/missing business ACK on this link. */
+  fun retryNotReady(): List<Action> {
+    if (!transportReady || !waitingReadiness || desired == null || probeRetries >= 3) return emptyList()
+    probeRetries++
+    waitingReadiness = false
+    ready = true
+    return pump()
+  }
+
   /** Debug capture seam; production behavior is unchanged unless explicitly held. */
   fun hold(value: Boolean, resume: Boolean = true): List<Action> {
     held = value
@@ -50,7 +69,8 @@ internal class NimoCanvasSession {
   fun confirmedReadiness(value: Boolean): List<Action> = updateReadiness(value, confirmed = true)
 
   private fun updateReadiness(value: Boolean, confirmed: Boolean): List<Action> {
-    if (!value) readinessRetries = 0
+    transportReady = value
+    if (!value) { readinessRetries = 0; probeRetries = 0 }
     if (!value && flight != null) return resetLink("Readiness lost during canvas command")
     if (waitingReadiness) {
       if (!value) observedNotReady = true
@@ -67,9 +87,9 @@ internal class NimoCanvasSession {
 
   /** A new transport generation has no accepted frame. Retain only the latest desired scene. */
   fun disconnected() {
-    ready = false; active = false; held = false; locked = false; launchBlocked = false
+    ready = false; transportReady = false; active = false; held = false; locked = false; launchBlocked = false
     waitingReadiness = false; observedNotReady = false
-    readinessRetries = 0
+    readinessRetries = 0; probeRetries = 0
     accepted = null; rejected = null; flight = null; ticket++; forceRevision++
   }
 
@@ -78,21 +98,13 @@ internal class NimoCanvasSession {
     return pump()
   }
 
-  /** A local gesture/native app takeover suppresses replay until the host submits another scene. */
+  /** Firmware can restore its stock UI after reconnect. Keep host ownership and
+   * replay the newest scene, serializing behind any outstanding command ACK. */
   fun nativeApp(appId: Int, entered: Boolean): List<Action> {
     if ((appId == NimoCanvasCodec.APP_ID && !entered) || (appId != NimoCanvasCodec.APP_ID && entered)) {
-      // The expected FD Exit report preserves newer host content. A different
-      // native app entering is a real takeover, even while our Exit waits for ACK.
-      if (flight?.key == 3) {
-        active = false; accepted = null
-        if (appId != NimoCanvasCodec.APP_ID && entered) {
-          desired = null; rejected = null; scope = null
-        }
-        return emptyList()
-      }
-      val ambiguous = flight != null
-      desired = null; accepted = null; rejected = null; active = false; exitRequested = false; scope = null
-      if (ambiguous) return resetLink("Native app transition interrupted canvas command")
+      active = false
+      accepted = null
+      return pump()
     }
     return emptyList()
   }
@@ -130,8 +142,8 @@ internal class NimoCanvasSession {
       return listOf(Action.Rejected(status)) + pump()
     }
     when (key) {
-      1 -> active = true
-      4 -> { accepted = current.frame; rejected = null; readinessRetries = 0 }
+      1 -> { active = true; accepted = null }
+      4 -> { accepted = current.frame; rejected = null; readinessRetries = 0; probeRetries = 0 }
       3 -> { active = false; accepted = null; exitRequested = false }
     }
     return pump()
@@ -143,7 +155,7 @@ internal class NimoCanvasSession {
   }
 
   private fun resetLink(reason: String): List<Action> {
-    ready = false; active = false; accepted = null; flight = null; ticket++; forceRevision++
+    ready = false; transportReady = false; active = false; accepted = null; flight = null; ticket++; forceRevision++
     return listOf(Action.Reconnect(reason))
   }
 

package/android/src/test/java/com/mentra/bluetoothsdk/DeviceManagerSceneHandoffTest.kt

@@ -24,6 +24,20 @@ import java.util.concurrent.TimeUnit
 class DeviceManagerSceneHandoffTest {
     @Before fun setup() { Bridge.initialize(ApplicationProvider.getApplicationContext()) }
 
+    @Test @LooperMode(LooperMode.Mode.PAUSED)
+    fun delayedReconnectReplayPreservesNimoDepthEndpoints() {
+        for (depth in listOf(0, 10)) {
+            withReadyRecordingDevice { manager, device, _ ->
+                DeviceStore.set("bluetooth", "dashboard_height", 7)
+                DeviceStore.set("bluetooth", "dashboard_depth", depth)
+                manager.handleDeviceReady()
+                assertTrue(device.positions.isEmpty())
+                Shadows.shadowOf(Looper.getMainLooper()).idleFor(2, TimeUnit.SECONDS)
+                assertEquals(listOf(7 to depth), device.positions)
+            }
+        }
+    }
+
     @Test @LooperMode(LooperMode.Mode.PAUSED)
     fun reconnectRestoresUnchangedAudioRequests() {
         for (request in listOf("should_send_lc3", "should_send_pcm", "should_send_transcript", "local_stt_fallback_active")) {
@@ -592,6 +606,7 @@ class DeviceManagerSceneHandoffTest {
         val micChanges = mutableListOf<Boolean>()
         val calls = CopyOnWriteArrayList<String>()
         val brightnessCalls = mutableListOf<String>()
+        val positions = mutableListOf<Pair<Int, Int>>()
         val textSent = CountDownLatch(1)
         var lastTextNanos = 0L
         var lastClearNanos = 0L
@@ -622,7 +637,7 @@ class DeviceManagerSceneHandoffTest {
         override fun sendDoubleTextWall(top: String, bottom: String) {}
         override fun displayBitmap(base64ImageData: String, x: Int?, y: Int?, width: Int?, height: Int?) = true
         override fun showDashboard() {}
-        override fun setDashboardPosition(height: Int, depth: Int) {}
+        override fun setDashboardPosition(height: Int, depth: Int) { positions += height to depth }
         override fun setHeadUpAngle(angle: Int) {}
         override fun getBatteryStatus() {}
         override fun setSilentMode(enabled: Boolean) {}

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/NimoCanvasCoordinatorTest.kt

@@ -51,6 +51,46 @@ class NimoCanvasCoordinatorTest {
         fun finishUpdate(frame: ByteArray) { repeat(NimoCanvasCodec.frames(4, frame, 20).size) { written() }; ack(4) }
     }
 
+    @Test fun notReadyRetriesLaunchPromptlyButStopsAfterThreeProbes() {
+        val f = Fixture(); f.canvas.activate(); f.canvas.readiness(true)
+        repeat(4) { attempt ->
+            f.written(); f.ack(1, 7)
+            val before = f.writes.size
+            f.clock.advance(999)
+            assertEquals(before, f.writes.size)
+            f.clock.advance(1)
+            assertEquals(before + if (attempt < 3) 1 else 0, f.writes.size)
+        }
+        f.clock.advance(60_000)
+        assertEquals(4, f.writes.size)
+        assertTrue(f.failures.isEmpty())
+    }
+
+    @Test fun pendingReadinessRetryIsCancelledOnDisconnectExitAndKnownReadinessLoss() {
+        for (stop in listOf("disconnect", "exit", "notReady")) {
+            val f = Fixture(); f.canvas.activate(); f.canvas.readiness(true)
+            f.written(); f.ack(1, 7)
+            when (stop) {
+                "disconnect" -> f.canvas.disconnected()
+                "exit" -> f.canvas.exit()
+                else -> f.canvas.readiness(false)
+            }
+            f.clock.advance(2_000)
+            assertEquals(1, f.writes.size)
+            assertTrue(f.failures.isEmpty())
+        }
+    }
+
+    @Test fun readinessHeartbeatCancelsPendingProbeAndDoesNotDuplicateLaunch() {
+        val f = Fixture(); f.canvas.activate(); f.canvas.readiness(true)
+        f.written(); f.ack(1, 7)
+        f.canvas.confirmedReadiness(true)
+        f.clock.advance(1_000)
+        assertEquals(2, f.writes.size)
+        f.written(); f.ack(1); f.finishUpdate(byteArrayOf(0, 0, 1))
+        assertTrue(f.failures.isEmpty())
+    }
+
     @Test fun bothNotificationDescriptorsGateCharacteristicWrites() {
         val f = Fixture()
         val rx = Any(); val mic = Any()
@@ -184,7 +224,7 @@ class NimoCanvasCoordinatorTest {
         val f = Fixture(); f.launch(); f.finishUpdate(byteArrayOf(0, 0, 1))
         f.canvas.exit()
         f.canvas.offer(byteArrayOf(1, 0, 1), "two:1")
-        assertFalse(f.canvas.nativeApp(0xFD, false))
+        f.canvas.nativeApp(0xFD, false)
         f.written()
         val before = f.writes.size
         f.ack(3)
@@ -192,15 +232,15 @@ class NimoCanvasCoordinatorTest {
         assertArrayEquals(NimoCanvasCodec.frames(1, writeCapacity = 20).single(), f.writes.last())
     }
 
-    @Test fun actualNativeTakeoverDuringExitInvalidatesEncodingAndDoesNotRelaunch() {
+    @Test fun nativeTakeoverDuringExitRetainsNewerSceneUntilExitAck() {
         val f = Fixture(); f.launch(); f.finishUpdate(byteArrayOf(0, 0, 1))
         f.canvas.exit()
         f.canvas.offer(byteArrayOf(1, 0, 1), "two:1")
-        assertTrue(f.canvas.nativeApp(0, true))
+        f.canvas.nativeApp(0, true)
         f.written()
         val before = f.writes.size
         f.ack(3)
-        assertEquals(before, f.writes.size)
+        assertEquals(before + 1, f.writes.size)
         assertTrue(f.failures.isEmpty())
     }
 

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/NimoCanvasSessionTest.kt

@@ -210,31 +210,100 @@ class NimoCanvasSessionTest {
     assertArrayEquals(frameB, send(success(session, 1)).frame)
   }
 
-  @Test fun actualNativeTakeoverDuringExitDiscardsNewerScene() {
+  @Test fun nativeReportDuringExitPreservesNewerHostScene() {
     val session = NimoCanvasSession()
     launched(session); success(session, 4)
     assertEquals(3, send(session.exit()).key)
     session.offer(frameB, "two:1")
     assertTrue(session.nativeApp(0, true).isEmpty())
-    assertTrue(success(session, 3).isEmpty())
+    assertEquals(1, send(success(session, 3)).key)
+    assertArrayEquals(frameB, send(success(session, 1)).frame)
+  }
+
+  @Test fun nativeTakeoverRestoresLatestSceneWithoutAnotherHostOffer() {
+    for (app in listOf(0, 0xFD)) {
+      val session = NimoCanvasSession()
+      launched(session); success(session, 4)
+      assertEquals(1, send(session.nativeApp(app, app != 0xFD)).key)
+      assertArrayEquals(frameA, send(success(session, 1)).frame)
+    }
+  }
+
+  @Test fun nativeTakeoverWaitsForCurrentAckInsteadOfOverlappingCommands() {
+    val session = NimoCanvasSession(); launched(session)
+    assertTrue(session.nativeApp(0, true).isEmpty())
+    session.offer(frameB, "one:1")
+    assertEquals(1, send(success(session, 4)).key)
+    assertTrue(session.nativeApp(0, true).isEmpty()) // Startup report during Launch.
+    assertArrayEquals(frameB, send(success(session, 1)).frame)
+  }
+
+  @Test fun takeoverDuringUpdateReplaysIdenticalFrameAfterRelaunch() {
+    val session = NimoCanvasSession(); launched(session)
+    assertTrue(session.nativeApp(0, true).isEmpty())
+    // The old Update ACK must not deduplicate the same scene on a new canvas.
+    assertEquals(1, send(success(session, 4)).key)
+    assertArrayEquals(frameA, send(success(session, 1)).frame)
+    assertTrue(success(session, 4).isEmpty())
+    assertTrue(session.offer(frameA, "one:1").isEmpty())
+  }
+
+  @Test fun startupStockUiDoesNotDiscardRetainedSceneBeforeReadiness() {
+    val session = NimoCanvasSession(); launched(session); success(session, 4)
     session.disconnected()
-    assertTrue(session.readiness(true).isEmpty())
+    assertTrue(session.nativeApp(0, true).isEmpty())
+    session.activate()
+    assertEquals(1, send(session.readiness(true)).key)
+    assertArrayEquals(frameA, send(success(session, 1)).frame)
   }
 
-  @Test fun nativeTakeoverSuppressesReplayUntilNewHostFrame() {
-    val session = NimoCanvasSession()
-    launched(session); success(session, 4)
+  @Test fun explicitExitStillReturnsControlToStockUiUntilNextConnection() {
+    val session = NimoCanvasSession(); launched(session); success(session, 4)
+    assertEquals(3, send(session.exit()).key)
     assertTrue(session.nativeApp(0, true).isEmpty())
-    assertTrue(session.readiness(true).isEmpty())
-    assertEquals(1, send(session.offer(frameA, "one:1")).key)
+    assertTrue(success(session, 3).isEmpty())
+    assertTrue(session.nativeApp(0, true).isEmpty())
+    session.disconnected(); session.activate()
+    assertEquals(1, send(session.readiness(true)).key)
+    assertArrayEquals(byteArrayOf(0, 0, 1), send(success(session, 1)).frame)
   }
 
-  @Test fun nativeTakeoverOrReadinessLossDuringCommandResets() {
-    for (takeover in listOf(true, false)) {
-      val session = NimoCanvasSession(); launched(session)
-      val actions = if (takeover) session.nativeApp(0, true) else session.readiness(false)
-      assertTrue(actions.single() is NimoCanvasSession.Action.Reconnect)
+  @Test fun activationLaunchesBlankCanvasWithoutAnyMiniapp() {
+    val session = NimoCanvasSession()
+    assertTrue(session.activate().isEmpty())
+    assertEquals(1, send(session.readiness(true)).key)
+    assertArrayEquals(byteArrayOf(0, 0, 1), send(success(session, 1)).frame)
+  }
+
+  @Test fun successfulUpdateRestoresProbeBudgetForNextRecovery() {
+    val session = NimoCanvasSession(); session.activate(); session.readiness(true)
+    repeat(2) { episode ->
+      if (episode > 0) assertEquals(1, send(session.nativeApp(0, true)).key)
+      repeat(3) {
+        session.response(1, byteArrayOf(7))
+        assertEquals(1, send(session.retryNotReady()).key)
+      }
+      assertEquals(4, send(success(session, 1)).key)
+      assertTrue(success(session, 4).isEmpty())
+    }
+  }
+
+  @Test fun notReadyProbesAreBoundedAndFreshHeartbeatStillRecovers() {
+    val session = NimoCanvasSession(); session.activate(); session.readiness(true)
+    repeat(3) {
+      session.response(1, byteArrayOf(7))
+      assertEquals(1, send(session.retryNotReady()).key)
     }
+    session.response(1, byteArrayOf(7))
+    repeat(5) { assertTrue(session.retryNotReady().isEmpty()) }
+    assertEquals(1, send(session.confirmedReadiness(true)).key)
+    assertEquals(4, send(success(session, 1)).key)
+  }
+
+  @Test fun lostReadinessDuringCommandStillResets() {
+    val session = NimoCanvasSession(); launched(session)
+    assertTrue(session.readiness(false).single() is NimoCanvasSession.Action.Reconnect)
+    assertTrue(session.retryNotReady().isEmpty())
   }
 
   @Test fun offersCopyMutableInputAndRejectOversizedFrame() {