@mentra/bluetooth-sdk 3.2.1-beta.319 → 3.2.1-beta.354

package/android/src/testDebug/java/com/mentra/bluetoothsdk/sgcs/NimoDiagnosticsTest.kt

@@ -0,0 +1,287 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import androidx.test.core.app.ApplicationProvider
+import java.io.File
+import java.util.concurrent.TimeUnit
+import org.json.JSONObject
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.LooperMode
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@LooperMode(LooperMode.Mode.PAUSED)
+class NimoDiagnosticsTest {
+  private data class Write(val packet: ByteArray, val completed: () -> Unit)
+  private val writes = mutableListOf<Write>()
+  private var heldReady: (() -> Unit)? = null
+  private val holdReleases = mutableListOf<Boolean>()
+  private lateinit var diagnostics: NimoDiagnostics
+  private lateinit var root: File
+  private lateinit var previousDirectories: Set<String>
+
+  @Before fun setup() {
+    val context = ApplicationProvider.getApplicationContext<Context>()
+    root = File(context.filesDir, "nimo-framebuffer")
+    previousDirectories = root.listFiles()?.map { it.name }?.toSet() ?: emptySet()
+    diagnostics = NimoDiagnostics(
+      context,
+      Handler(Looper.getMainLooper()),
+      { frame, complete -> writes.add(Write(frame.copyOf(), complete)); true },
+      { ready -> heldReady = ready },
+      { resume -> holdReleases += resume },
+    )
+    diagnostics.connected(512)
+  }
+
+  @After fun dispose() { diagnostics.close() }
+
+  @Test fun probePreservesNotReadyAndAcceptsResponsesBeforeWriteCallbacks() {
+    start("probe")
+    driveToPageGate()
+    assertTrue(diagnostics.onPacket(fbpReply(writes[3].packet, ByteArray(240))))
+    val result = receipt()
+    assertTrue(result.getBoolean("probe_ok"))
+    assertFalse(result.getBoolean("ok"))
+    assertTrue(result.isNull("error"))
+    assertEquals(0, result.getJSONObject("readiness").getInt("ready"))
+    assertEquals(1, result.getJSONObject("readiness").getInt("tws"))
+    assertEquals(NimoFramebufferProtocol.EXPECTED_VERSION, result.getString("runtime_version"))
+    assertEquals(8, result.getInt("wire_events"))
+    assertEquals(8, File(captureDirectory(), "wire.jsonl").readLines().size)
+    writes.toList().forEach { it.completed() }
+    idle(4_000)
+    assertEquals(4, writes.size)
+    assertTrue(receipt().getBoolean("probe_ok"))
+    assertTrue(writes.all { it.packet[8] == 2.toByte() && (it.packet[9].toInt() and 255) in listOf(0x0B, 0x19, 0x15) })
+  }
+
+  @Test fun duplicateTriggerDoesNotStartAnotherRead() {
+    start("capture")
+    start("probe")
+    assertEquals(1, writes.size)
+    assertEquals(1, newDirectories().size)
+  }
+
+  @Test fun disconnectCancelsPendingTimeoutAndIgnoresLateWriteCompletion() {
+    start("capture")
+    writes.single().completed()
+    diagnostics.disconnected()
+    val error = receipt().getString("error")
+    assertTrue(error.contains("disconnected"))
+    diagnostics.connected(512)
+    writes.single().completed()
+    idle(4_000)
+    assertEquals(error, receipt().getString("error"))
+    assertEquals(1, writes.size)
+    assertFalse(diagnostics.onPacket(versionReply()))
+    assertFalse(receipt().getBoolean("ok"))
+  }
+
+  @Test fun timeoutStartsAtWriteCompletionAndDoesNotRetry() {
+    start("probe")
+    idle(5_000)
+    assertFalse(File(captureDirectory(), "session.json").exists())
+    writes.single().completed()
+    idle(2_900)
+    assertFalse(File(captureDirectory(), "session.json").exists())
+    idle(200)
+    assertTrue(receipt().getString("error").contains("response timeout"))
+    assertEquals(1, writes.size)
+  }
+
+  @Test fun captureRejectsCrcBeforeRequestingBulkPages() {
+    start("capture")
+    driveToPageGate()
+    val corrupted = fbpReply(writes[3].packet, ByteArray(240)).also { it[4] = (it[4].toInt() xor 1).toByte() }
+    assertTrue(diagnostics.onPacket(corrupted))
+    assertFalse(receipt().getBoolean("ok"))
+    assertFalse(receipt().getBoolean("probe_ok"))
+    assertTrue(receipt().getString("error").contains("CRC mismatch"))
+    assertEquals(4, writes.size)
+    assertEquals(0, receipt().getJSONArray("banks").length())
+  }
+
+  @Test fun totalDeadlineBoundsAWriteThatNeverCompletes() {
+    start("capture")
+    idle(600_001)
+    assertTrue(receipt().getString("error").contains("10-minute budget"))
+    writes.single().completed()
+    idle(4_000)
+    assertEquals(1, writes.size)
+  }
+
+  @Test fun heldSampleBudgetIncludesCanvasDrainAndStaleReadyCannotStartCapture() {
+    start("held-sample")
+    assertTrue(writes.isEmpty())
+    assertNotNull(heldReady)
+
+    idle(15_001)
+
+    assertEquals(listOf(true), holdReleases)
+    assertTrue(receipt().getString("error").contains("15-second budget"))
+    heldReady?.invoke()
+    assertTrue(writes.isEmpty())
+    assertEquals(listOf(true), holdReleases)
+  }
+
+  @Test fun disconnectBeforeHeldCaptureIsReadyReleasesWithoutResumingCanvas() {
+    start("held-capture")
+
+    diagnostics.disconnected()
+
+    assertEquals(listOf(false), holdReleases)
+    assertTrue(receipt().getString("error").contains("disconnected"))
+    heldReady?.invoke()
+    assertTrue(writes.isEmpty())
+    assertEquals(listOf(false), holdReleases)
+  }
+
+  @Test fun duplicateHeldCaptureDoesNotReplaceHoldOrDeadline() {
+    start("held-sample")
+    val firstReady = heldReady
+
+    start("held-capture")
+
+    assertSame(firstReady, heldReady)
+    assertEquals(1, newDirectories().size)
+    idle(15_001)
+    assertEquals(listOf(true), holdReleases)
+  }
+
+  @Test fun insufficientCapacityFailsWithoutSendingDiagnosticCommands() {
+    diagnostics.connected(20)
+    start("capture")
+    assertEquals(0, writes.size)
+    assertTrue(receipt().getString("error").contains("Write capacity"))
+  }
+
+  @Test fun samplePinsPreparedBankAndNeverClaimsStaticPairVerification() {
+    assertSample(1)
+  }
+
+  @Test fun sampleAlsoPinsPreparedBankZero() {
+    assertSample(0)
+  }
+
+  @Test fun heldSampleStartsOnlyAfterDrainAndReleasesOnSuccess() {
+    assertSample(1, "held-sample")
+    assertEquals(listOf(true), holdReleases)
+  }
+
+  private fun assertSample(bank: Int, mode: String = "sample") {
+    val state = byteArrayOf((1 - bank).toByte(), bank.toByte(), 0, 0)
+    start(mode)
+    if (mode == "held-sample") {
+      assertTrue(writes.isEmpty())
+      requireNotNull(heldReady).invoke()
+    }
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240), state))
+    // The gate always probes bank0/page0; the sample follows its prepared selector.
+    repeat(315) { page ->
+      val request = writes.last().packet
+      assertEquals(bank, request[21].toInt())
+      assertEquals(page, (request[22].toInt() and 255) or ((request[23].toInt() and 255) shl 8))
+      diagnostics.onPacket(fbpReply(request, ByteArray(240) { page.toByte() }, state))
+    }
+    val result = receipt()
+    assertTrue(result.getBoolean("sample_ok"))
+    assertFalse(result.getBoolean("ok"))
+    assertFalse(result.getBoolean("atomic"))
+    assertFalse(result.getBoolean("optical"))
+    assertEquals("non_atomic_single_pass", result.getString("evidence_kind"))
+    assertEquals(0, result.getInt("static_pairs_verified"))
+    assertEquals(1, result.getJSONArray("banks").length())
+    assertEquals(319, writes.size)
+    assertEquals(638, result.getInt("wire_events"))
+    assertFalse(result.getBoolean("pixel_stability_verified"))
+    assertEquals(mode, result.getString("mode"))
+    assertEquals(75_600, File(captureDirectory(), "bank$bank-pass1.bin").length().toInt())
+  }
+
+  @Test fun sampleRejectsSelectorChangeBetweenGateAndFirstPageWithoutRetrying() {
+    start("sample")
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240)))
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240), byteArrayOf(1, 0, 0, 0)))
+    val result = receipt()
+    assertFalse(result.getBoolean("sample_ok"))
+    assertFalse(result.getBoolean("ok"))
+    assertTrue(result.getString("error").contains("Sample metadata differs from page gate"))
+    assertEquals(5, writes.size)
+    assertEquals(0, result.getJSONArray("banks").length())
+  }
+
+  @Test fun sampleTimeoutCannotProduceSuccessOrStartASecondPass() {
+    start("sample")
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240)))
+    writes.last().completed()
+    idle(3_001)
+    assertFalse(receipt().getBoolean("sample_ok"))
+    assertFalse(receipt().getBoolean("ok"))
+    assertEquals(5, writes.size)
+  }
+
+  @Test fun fullCaptureStillRequiresFourCompleteReadsAndTwoStaticPairs() {
+    start("capture")
+    driveToPageGate()
+    diagnostics.onPacket(fbpReply(writes.last().packet, ByteArray(240)))
+    repeat(4) { pass ->
+      repeat(315) { page ->
+        val request = writes.last().packet
+        assertEquals(pass / 2, request[21].toInt())
+        diagnostics.onPacket(fbpReply(request, ByteArray(240) { page.toByte() }))
+      }
+      if (pass < 3) assertFalse(File(captureDirectory(), "session.json").exists())
+    }
+    assertTrue(receipt().getBoolean("ok"))
+    assertEquals(2, receipt().getInt("static_pairs_verified"))
+    assertEquals(4, receipt().getJSONArray("banks").length())
+    assertEquals(1264, writes.size)
+  }
+
+  private fun driveToPageGate() {
+    assertEquals(1, writes.size)
+    assertFalse(diagnostics.onPacket(versionReply()))
+    assertEquals(2, writes.size)
+    assertFalse(diagnostics.onPacket(frame(0x19, byteArrayOf(0, 0, 1, 0))))
+    assertEquals(3, writes.size)
+    assertTrue(diagnostics.onPacket(fbpReply(writes[2].packet, "537cf1p1".toByteArray())))
+    assertEquals(4, writes.size)
+  }
+
+  // Exercise the production coordinator without pretending Robolectric proves Android's
+  // signature-permission enforcement for the ADB receiver. That boundary needs a device test.
+  private fun start(mode: String) {
+    NimoDiagnostics::class.java.getDeclaredMethod("start", String::class.java).apply { isAccessible = true }
+      .invoke(diagnostics, mode)
+  }
+  private fun idle(milliseconds: Long) = Shadows.shadowOf(Looper.getMainLooper()).idleFor(milliseconds, TimeUnit.MILLISECONDS)
+  private fun newDirectories() = root.listFiles()?.filter { it.name !in previousDirectories } ?: emptyList()
+  private fun captureDirectory() = newDirectories().single()
+  private fun receipt() = JSONObject(File(captureDirectory(), "session.json").readText())
+  private fun versionReply() = frame(0x0B, byteArrayOf(0) + NimoFramebufferProtocol.EXPECTED_VERSION.toByteArray())
+
+  private fun fbpReply(request: ByteArray, data: ByteArray, state: ByteArray = byteArrayOf(0, 1, 0, 0)): ByteArray {
+    val payload = byteArrayOf(0) + "FBP1".toByteArray() + request.copyOfRange(16, 24) + state + state +
+      byteArrayOf(data.size.toByte(), (data.size shr 8).toByte()) + data
+    return frame(0x15, payload)
+  }
+  private fun frame(key: Int, payload: ByteArray): ByteArray {
+    val body = byteArrayOf(2, key.toByte(), payload.size.toByte(), (payload.size shr 8).toByte()) + payload
+    val crc = NimoCanvasCodec.crc16(body)
+    return byteArrayOf(0xBF.toByte(), 0, body.size.toByte(), (body.size shr 8).toByte(),
+      crc.toByte(), (crc shr 8).toByte(), 0, 0) + body
+  }
+}

package/android/src/testDebug/java/com/mentra/bluetoothsdk/sgcs/NimoFramebufferProtocolTest.kt

@@ -0,0 +1,127 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class NimoFramebufferProtocolTest {
+  @Test fun hexPreservesEveryByteAndEmptyEvidence() {
+    val bytes = ByteArray(256) { it.toByte() }
+    assertEquals(bytes.joinToString("") { "%02x".format(it.toInt() and 255) }, NimoFramebufferProtocol.hex(bytes))
+    assertEquals("", NimoFramebufferProtocol.hex(byteArrayOf()))
+  }
+  private val pingRequest = NimoFramebufferProtocol.Request(0x01020304L, 0, 0, 0)
+  // Fixed vectors produced independently by the existing Python FBP1 codec.
+  private val ping = hex("bf0023008234000002151f0000464250310403020100000000000100000001000008003533376366317031")
+  private val page = hex("bf000b0175e500000215070100464250310403020101013a010001000000010000f000") +
+    ByteArray(240) { it.toByte() }
+
+  @Test fun requestAndReplyMatchIndependentGoldenVectors() {
+    assertArrayEquals(hex("bf001000227a000002150c00464250310403020100000000"),
+      NimoFramebufferProtocol.requestFrame(pingRequest))
+    val reply = NimoFramebufferProtocol.reply(ping, pingRequest)
+    assertArrayEquals("537cf1p1".toByteArray(), reply.data)
+    assertEquals(NimoFramebufferProtocol.State(0, 1, 0, 0), reply.before)
+    val expectedPage = NimoFramebufferProtocol.Request(0x01020304L, 1, 1, 314)
+    assertArrayEquals(ByteArray(240) { it.toByte() }, NimoFramebufferProtocol.reply(page, expectedPage).data)
+  }
+
+  @Test fun rejectsCrcLengthsDirectionIndexAndCommand() {
+    for (offset in listOf(0, 1, 2, 4, 6, 8, 9, 10)) {
+      val invalid = ping.copyOf().also { it[offset] = (it[offset].toInt() xor 1).toByte() }
+      rejects { NimoFramebufferProtocol.reply(invalid, pingRequest) }
+    }
+    rejects { NimoFramebufferProtocol.reply(ping + 0, pingRequest) }
+    rejects { NimoFramebufferProtocol.reply(ping.copyOf(ping.size - 1), pingRequest) }
+  }
+
+  @Test fun rejectsWrongTagMagicNonceOperationBankAndPage() {
+    for (offset in listOf(13, 17, 21, 22, 23, 33, 35)) {
+      val invalid = changeAndRecrc(ping, offset, ping[offset].toInt() xor 1)
+      rejects { NimoFramebufferProtocol.reply(invalid, pingRequest) }
+    }
+    rejects { NimoFramebufferProtocol.reply(ping, pingRequest.copy(nonce = 9)) }
+    rejects { NimoFramebufferProtocol.reply(ping, pingRequest.copy(op = 1)) }
+  }
+
+  @Test fun rejectsStatusErrorsEvenWithValidCorrelation() {
+    for (status in listOf(1, 6, 7, 255)) {
+      val payload = ping.copyOfRange(12, 35).also { it[0] = status.toByte(); it[21] = 0; it[22] = 0 }
+      rejects { NimoFramebufferProtocol.reply(frame(0x15, payload), pingRequest) }
+    }
+    rejects { NimoFramebufferProtocol.reply(changeAndRecrc(ping, 12, 6), pingRequest) }
+  }
+
+  @Test fun rejectsMetadataChangedWithinAndAcrossPagesAndOutOfOrder() {
+    val request = NimoFramebufferProtocol.Request(0x01020304L, 1, 1, 0)
+    val first = NimoFramebufferProtocol.reply(pageAt(0), request)
+    val read = NimoFramebufferProtocol.BankRead(request.nonce, request.bank)
+    read.add(first)
+    rejects { read.add(first) }
+    rejects { NimoFramebufferProtocol.BankRead(request.nonce, request.bank).add(first.copy(page = 1)) }
+    rejects { NimoFramebufferProtocol.reply(changeAndRecrc(pageAt(0), 29, 1), request) }
+    val changed = first.copy(page = 1, before = first.before.copy(dirty = 1), after = first.after.copy(dirty = 1))
+    val changedRead = NimoFramebufferProtocol.BankRead(request.nonce, request.bank)
+    changedRead.add(first)
+    rejects { changedRead.add(changed) }
+  }
+
+  @Test fun bankRequiresEveryPageAndIndependentEqualSecondPass() {
+    val first = completeBank(10)
+    val second = completeBank(11)
+    NimoFramebufferProtocol.verifyPair(first, second)
+    assertEquals(75600, first.bytes().size)
+    rejects { NimoFramebufferProtocol.verifyPair(first, first) }
+    rejects { NimoFramebufferProtocol.verifyPair(first, completeBank(12, changedLastPixel = true)) }
+    rejects { NimoFramebufferProtocol.BankRead(20, 1).bytes() }
+  }
+
+  @Test fun requestLimitsPreventArbitraryCommandsOrAddresses() {
+    for (request in listOf(pingRequest.copy(nonce = -1), pingRequest.copy(nonce = 0x100000000L),
+      pingRequest.copy(op = 2), pingRequest.copy(bank = 2), pingRequest.copy(page = 1),
+      pingRequest.copy(op = 1, page = 315))) {
+      rejects { NimoFramebufferProtocol.requestFrame(request) }
+    }
+    rejects { NimoFramebufferProtocol.queryFrame(0x0A) }
+  }
+
+  @Test fun basicResponsesRequireExactVersionAndReadinessShape() {
+    val version = byteArrayOf(0) + NimoFramebufferProtocol.EXPECTED_VERSION.toByteArray()
+    assertEquals(NimoFramebufferProtocol.EXPECTED_VERSION,
+      NimoFramebufferProtocol.version(frame(0x0B, version)))
+    rejects { NimoFramebufferProtocol.version(frame(0x0B, version + 0)) }
+    rejects { NimoFramebufferProtocol.version(frame(0x0B, version.copyOf().also { it[0] = 7 })) }
+    assertEquals(listOf(0, 0, 1, 0), NimoFramebufferProtocol.readiness(frame(0x19, byteArrayOf(0, 0, 1, 0))))
+    rejects { NimoFramebufferProtocol.readiness(frame(0x19, byteArrayOf(0, 1, 1))) }
+  }
+
+  private fun completeBank(nonce: Long, changedLastPixel: Boolean = false): NimoFramebufferProtocol.BankRead {
+    val read = NimoFramebufferProtocol.BankRead(nonce, 1)
+    repeat(315) { index ->
+      val original = NimoFramebufferProtocol.reply(pageAt(index),
+        NimoFramebufferProtocol.Request(0x01020304L, 1, 1, index))
+      val data = original.data.copyOf()
+      if (changedLastPixel && index == 314) data[239] = 0
+      read.add(original.copy(nonce = nonce, data = data))
+    }
+    return read
+  }
+
+  private fun pageAt(index: Int): ByteArray {
+    val result = page.copyOf()
+    result[23] = index.toByte(); result[24] = (index shr 8).toByte()
+    return recrc(result)
+  }
+  private fun changeAndRecrc(value: ByteArray, index: Int, byte: Int) =
+    recrc(value.copyOf().also { it[index] = byte.toByte() })
+  private fun recrc(value: ByteArray): ByteArray {
+    val crc = NimoCanvasCodec.crc16(value.copyOfRange(8, value.size))
+    value[4] = crc.toByte(); value[5] = (crc shr 8).toByte()
+    return value
+  }
+  private fun frame(key: Int, payload: ByteArray): ByteArray {
+    val body = byteArrayOf(2, key.toByte(), payload.size.toByte(), (payload.size shr 8).toByte()) + payload
+    return recrc(byteArrayOf(0xBF.toByte(), 0, body.size.toByte(), (body.size shr 8).toByte(), 0, 0, 0, 0) + body)
+  }
+  private fun rejects(block: () -> Unit) { assertThrows(IllegalArgumentException::class.java, block) }
+  private fun hex(value: String) = value.chunked(2).map { it.toInt(16).toByte() }.toByteArray()
+}

package/android/src/testDebug/java/com/mentra/bluetoothsdk/sgcs/NimoLifecycleTest.kt

@@ -0,0 +1,194 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.ContextWrapper
+import android.content.SharedPreferences
+import android.os.Handler
+import android.os.Looper
+import androidx.test.core.app.ApplicationProvider
+import com.mentra.bluetoothsdk.Bridge
+import com.mentra.bluetoothsdk.DeviceManager
+import com.mentra.bluetoothsdk.DeviceStore
+import com.mentra.bluetoothsdk.utils.ConnTypes
+import java.io.File
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicReference
+import org.json.JSONObject
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.LooperMode
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@LooperMode(LooperMode.Mode.PAUSED)
+class NimoLifecycleTest {
+  private class TrackingContext(base: Context) : ContextWrapper(base) {
+    val unregisterLoopers = mutableListOf<Looper?>()
+    val preferenceLoopers = mutableListOf<Looper?>()
+    override fun getApplicationContext(): Context = this
+    override fun getSharedPreferences(name: String, mode: Int): SharedPreferences {
+      if (name == "NimoPrefs") preferenceLoopers.add(Looper.myLooper())
+      return super.getSharedPreferences(name, mode)
+    }
+    override fun unregisterReceiver(receiver: BroadcastReceiver) {
+      unregisterLoopers.add(Looper.myLooper())
+      super.unregisterReceiver(receiver)
+    }
+  }
+
+  private lateinit var context: TrackingContext
+  private lateinit var nimo: Nimo
+  private lateinit var encoderThread: Thread
+  private lateinit var manager: DeviceManager
+  private var previousManager: DeviceManager? = null
+  private lateinit var diagnostics: NimoDiagnostics
+  private lateinit var captureDirectory: File
+  private lateinit var writeCompleted: () -> Unit
+  private var writes = 0
+  private val storeLoopers = mutableListOf<Looper?>()
+  private var listener: String? = null
+
+  @Before fun setup() {
+    context = TrackingContext(ApplicationProvider.getApplicationContext())
+    Bridge.initialize(context)
+    manager = DeviceManager(initializeHardware = false)
+    DeviceManager::class.java.getDeclaredField("_instance").apply { isAccessible = true }.let {
+      previousManager = it.get(null) as DeviceManager?
+      it.set(null, manager)
+    }
+    val threadsBefore = Thread.getAllStackTraces().keys
+    nimo = Nimo()
+    encoderThread = Thread.getAllStackTraces().keys.single {
+      it.name == "NimoCanvasEncoder" && it !in threadsBefore
+    }
+    context.getSharedPreferences("NimoPrefs", Context.MODE_PRIVATE).edit()
+      .putString("nimo_lastDeviceAddress", "00:11:22:33:44:55")
+      .putString("nimo_lastDeviceName", "Nimo-test")
+      .commit()
+    DeviceStore.set("glasses", "connected", true)
+    DeviceStore.set("glasses", "fullyBooted", true)
+    DeviceStore.set("glasses", "connectionState", ConnTypes.CONNECTED)
+    listener = DeviceStore.store.addListener { category, _ ->
+      if (category == "glasses") storeLoopers.add(Looper.myLooper())
+    }
+    diagnostics = NimoDiagnostics(context, Handler(Looper.getMainLooper()), send = { _, completed ->
+      writes += 1
+      writeCompleted = completed
+      true
+    })
+    diagnostics.connected(512)
+    // Install the real debug collaborator without requiring a Bluetooth radio handshake.
+    Nimo::class.java.getDeclaredField("diagnostics").apply { isAccessible = true }
+      .set(nimo, diagnostics)
+    val root = File(context.filesDir, "nimo-framebuffer")
+    val previous = root.listFiles()?.map { it.name }?.toSet() ?: emptySet()
+    // Receiver permission enforcement is a device test; this starts its real capture path.
+    NimoDiagnostics::class.java.getDeclaredMethod("start", String::class.java)
+      .apply { isAccessible = true }.invoke(diagnostics, "capture")
+    captureDirectory = root.listFiles()!!.single { it.name !in previous }
+    assertEquals(1, writes)
+  }
+
+  @After fun dispose() {
+    nimo.cleanup()
+    Shadows.shadowOf(Looper.getMainLooper()).idle()
+    encoderThread.join(1_000)
+    listener?.let { DeviceStore.store.removeListener(it) }
+    manager.cleanup()
+    DeviceManager::class.java.getDeclaredField("_instance").apply { isAccessible = true }
+      .set(null, previousManager)
+  }
+
+  @Test fun offMainDisconnectCompletesOnMainAndInterruptsActiveCapture() {
+    runOffMain { nimo.disconnect() }
+    assertDisconnectedOnMain()
+    assertRememberedDevice()
+  }
+
+  @Test fun offMainForgetClearsRememberedDeviceAfterMainThreadTeardown() {
+    runOffMain { nimo.forget() }
+    assertDisconnectedOnMain()
+    val prefs = context.getSharedPreferences("NimoPrefs", Context.MODE_PRIVATE)
+    assertFalse(prefs.contains("nimo_lastDeviceAddress"))
+    assertFalse(prefs.contains("nimo_lastDeviceName"))
+    assertTrue(context.preferenceLoopers.all { it === Looper.getMainLooper() })
+  }
+
+  @Test fun offMainCleanupClosesDiagnosticsAfterMainThreadTeardown() {
+    runOffMain { nimo.cleanup() }
+    assertDisconnectedOnMain()
+    assertRememberedDevice()
+    encoderThread.join(1_000)
+    assertFalse("Cleanup left its encoder thread alive", encoderThread.isAlive)
+    // A closed diagnostic cannot register another receiver or start a new capture.
+    diagnostics.connected(512)
+    NimoDiagnostics::class.java.getDeclaredMethod("start", String::class.java)
+      .apply { isAccessible = true }.invoke(diagnostics, "capture")
+    assertEquals(1, writes)
+  }
+
+  private fun runOffMain(operation: () -> Unit) {
+    val failure = AtomicReference<Throwable?>()
+    val caller = Thread({
+      try {
+        operation()
+        // The manager may replace this instance immediately after return. An asynchronous
+        // post is insufficient: the old connection must already be completely torn down.
+        assertEquals(false, DeviceStore.get("glasses", "connected"))
+        assertEquals(false, DeviceStore.get("glasses", "fullyBooted"))
+        assertTrue(File(captureDirectory, "session.json").exists())
+      } catch (error: Throwable) { failure.set(error) }
+    }, "Expo-AsyncFunctionQueue-test")
+    caller.start()
+    // The Main looper is paused, so no teardown may have run on the Expo worker.
+    assertEquals(true, DeviceStore.get("glasses", "connected"))
+    assertEquals(true, DeviceStore.get("glasses", "fullyBooted"))
+    assertRememberedDevice()
+    assertTrue(context.unregisterLoopers.isEmpty())
+    assertTrue(storeLoopers.isEmpty())
+    assertTrue("Encoder stopped before Main processed teardown", encoderThread.isAlive)
+    assertFalse(File(captureDirectory, "session.json").exists())
+    val deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5)
+    while (caller.isAlive && System.nanoTime() < deadline) {
+      Shadows.shadowOf(Looper.getMainLooper()).idle()
+      caller.join(10)
+    }
+    if (caller.isAlive) {
+      caller.interrupt()
+      caller.join(1_000)
+      fail("Lifecycle did not return after Main processed teardown")
+    }
+    failure.get()?.let { throw AssertionError("Off-main lifecycle entrypoint failed", it) }
+  }
+
+  private fun assertDisconnectedOnMain() {
+    assertEquals(false, DeviceStore.get("glasses", "connected"))
+    assertEquals(false, DeviceStore.get("glasses", "fullyBooted"))
+    assertEquals(ConnTypes.DISCONNECTED, DeviceStore.get("glasses", "connectionState"))
+    assertEquals(listOf(Looper.getMainLooper()), context.unregisterLoopers)
+    assertTrue(storeLoopers.isNotEmpty())
+    assertTrue(storeLoopers.all { it === Looper.getMainLooper() })
+    val receiptFile = File(captureDirectory, "session.json")
+    val beforeLateCallback = receiptFile.readText()
+    val receipt = JSONObject(beforeLateCallback)
+    assertFalse(receipt.getBoolean("ok"))
+    assertTrue(receipt.getString("error").contains("disconnected"))
+    writeCompleted()
+    Shadows.shadowOf(Looper.getMainLooper()).idle()
+    assertEquals(beforeLateCallback, receiptFile.readText())
+    assertEquals(1, writes)
+  }
+
+  private fun assertRememberedDevice() {
+    val prefs = context.getSharedPreferences("NimoPrefs", Context.MODE_PRIVATE)
+    assertEquals("00:11:22:33:44:55", prefs.getString("nimo_lastDeviceAddress", null))
+    assertEquals("Nimo-test", prefs.getString("nimo_lastDeviceName", null))
+  }
+}