@mentra/bluetooth-sdk 3.2.1-dev.314 → 3.3.0-beta.942

package/README.md

@@ -217,9 +217,9 @@ reordering rows just because RSSI metadata arrives later.
 
 ## Mentra SDK Usage Analytics
 
-The SDK sends three usage events to Mentra's PostHog project by default so
-Mentra can understand SDK adoption, successful glasses connections, and
-enterprise device deployments:
+The SDK sends usage events to Mentra's PostHog project by default so Mentra
+can understand SDK adoption, glasses connections, enterprise device
+deployments, and how Mentra Live features are used:
 
 - `bluetooth_sdk_started`: sent once per app runtime after the native SDK starts.
 - `bluetooth_sdk_glasses_connected`: sent when SDK status transitions from not connected to connected.
@@ -229,6 +229,45 @@ The connected event waits for the glasses model when the model is not known at
 the moment the connection flag flips; if the connection ends first it is sent
 without a model and with `glasses_model_unresolved=true`.
 
+Each usage occurrence below is one event, sent when it happens:
+
+- `bluetooth_sdk_glasses_disconnected`: a connection reported as connected
+  ended. Carries `session_duration_ms`, `disconnect_reason` (`user_disconnect`,
+  `forget`, `cancel`, `bluetooth_off`, `link_lost`, or `unknown`), and the
+  battery levels seen during the connection. A connection already up when the
+  SDK started is not reported.
+- `bluetooth_sdk_photo_taken`: a `requestPhoto` call settled, or a photo taken
+  with the glasses button failed (successful button photos never reach the
+  phone). Carries `trigger` (`api` / `button`), `success`, `error_code`,
+  `latency_ms`, the requested size, mode, compression, gallery save and
+  transfer method, and `file_size_bytes` when the response carries it.
+- `bluetooth_sdk_video_recorded`: an app- or button-started recording stopped
+  or failed. Carries `trigger`, `success`, `error_code`, `duration_ms` (phone
+  clock, start to stop status), the requested resolution and frame rate,
+  gallery save, maximum duration, and `stopped_by_app`.
+- `bluetooth_sdk_stream_started` / `bluetooth_sdk_stream_ended`: a
+  `startStream` call settled, and that stream later ended. `protocol` comes
+  from the URL scheme only (`rtmp`, `srt`, `whip`, or `unknown`). The start
+  carries the requested video settings, `capture_audio`, `glasses_network`, and
+  `latency_ms`; the end carries `duration_ms`, `end_state`, `stopped_by_app`,
+  `reconnect_attempts`, `error_code`, and the last bitrate, frame rate, dropped
+  frames, and temperature when the stream reported statistics.
+- `bluetooth_sdk_mic_session`: the active microphone turned off or changed.
+  Carries `duration_ms`, `mic_source`, and `local_transcription`.
+- `bluetooth_sdk_wifi_setup` / `bluetooth_sdk_hotspot_started`:
+  `sendWifiCredentials` or `setHotspotState(true)` settled, with `success`,
+  `error_code`, and `latency_ms`.
+- `bluetooth_sdk_ota_finished`: a glasses software update completed or failed,
+  with the failed step and error, `total_steps`, `duration_ms`, and the
+  glasses versions it started from.
+- `bluetooth_sdk_request_failed`: a glasses command timed out
+  (`error_code=request_timeout`), named by `operation`. At most 100 per SDK
+  start.
+
+These usage events also carry the connected glasses' `glasses_model`,
+`glasses_device_id` and `glasses_build_number` when known. A recording or
+stream whose end never reaches the running app produces only its start.
+
 Analytics delivery never blocks Bluetooth SDK behavior: events are submitted
 asynchronously off the caller thread. An upload that fails (no network, non-2xx)
 is kept in a small on-device queue (at most 100 events, 7 days) and retried on
@@ -281,10 +320,30 @@ write token, not a private PostHog personal API key. Apps do not configure the
 analytics destination; these SDK usage events are always sent to Mentra's
 PostHog project unless analytics are disabled.
 
+### Update check
+
+Separately from analytics, the SDK checks for a newer SDK release every time it
+starts, whether or not analytics are disabled. The check is one HTTPS request
+(4-second timeout, no retry) to
+`https://core.mentraglass.com/api/client/bluetooth-sdk/update-check` carrying
+`install_id` (the same anonymous install id analytics uses), `app_identifier`,
+`app_version`, `app_build`, `app_build_type`, `app_install_source`,
+`app_environment`, `sdk_version`, `sdk_platform`, `sdk_surface`,
+`os_platform`, and `os_version`. Mentra records each check. The SDK compares
+itself with the latest release on its own channel (stable, beta, or dev).
+
+When a newer release exists, the SDK prints a banner with the update command to
+the developer console: Logcat (`MentraBluetoothSDK` tag) on Android, the Xcode
+console on iOS, and `console.warn` in React Native, which shows as a LogBox
+warning in debug builds. The banner repeats every 15 minutes while the SDK
+instance lives. Nothing is shown in app UI. A network that blocks
+`core.mentraglass.com` loses only the banner; SDK behavior is unchanged.
+
 Captured properties include `event_source`, `sdk_platform`, `sdk_surface`,
 `sdk_version`, `app_identifier` (the Android package or iOS bundle identifier),
 the platform-specific `app_package` or `app_bundle_identifier`, OS
-platform/version, and `event_kind`. Every event also carries host build facts:
+platform/version, `phone_manufacturer`, `phone_model`, `locale`, `timezone`,
+and `event_kind`. Every event also carries host build facts:
 `app_version`, `app_build`, `app_build_type` (`debug` / `release`),
 `app_install_source` (`play_store`, `app_store`, `testflight`, `adhoc_or_dev`,
 `simulator`, `sideload`, a named third-party store, `other_store`, or `unknown`
@@ -308,8 +367,11 @@ decode it from the glasses' BLE advertisement / manufacturer data.
 
 Apart from that glasses serial, the SDK does not upload BLE MAC addresses,
 CoreBluetooth identifiers, the host phone's Android device serial, Bluetooth
-device names, user ids, tokens, Wi-Fi credentials, microphone data, photos, or
-transcripts. PostHog receives a locally generated anonymous SDK install id as
+device names, user ids, tokens, Wi-Fi names or credentials, stream, webhook or
+upload URLs, microphone data, photos, videos, or transcripts, and it never reads
+device location. Error details have URLs removed before they are sent. PostHog
+derives an approximate location (country, region, city) from the IP address
+each event is sent from. PostHog receives a locally generated anonymous SDK install id as
 `distinct_id`, and events include `$process_person_profile: false`.
 
 ## React Hooks
@@ -446,9 +508,9 @@ console.log(ledAck.state)
 
 ## Dashboard Content
 
-`setDashboardContent(content)` keeps the standard `$TIME12$ $DATE$ $GBATT$
-$CONNECTION_STATUS$` status header and places non-empty content below it after a
-blank line. Pass the exact empty string to reset the dashboard to the status
+`setDashboardContent(content)` keeps the standard `$TIME12$ $DATE$ $GBATT$`
+status header and places non-empty content below it after a blank line. Pass the
+exact empty string to reset the dashboard to the status
 header only. The template is held in memory for the SDK process/session, and its
 status placeholders are refreshed each time the dashboard renders. Calling this
 method does not open the dashboard; it updates an active contextual dashboard
@@ -507,7 +569,7 @@ Disabling restores normal hotspot-only behavior: the server rebinds to an active
 Both the native SDK and ASG client need this command; older glasses firmware times out without claiming success. The client app must have local-network access and permit cleartext HTTP to the local device under its platform/MDM policy.
 
 WiFi, hotspot, and version-info commands resolve from the ASG response path, not local dispatch:
-`requestWifiScan()` resolves from the ASG `wifi_scan_result` completion response with the updated scan list, including `[]` when no networks are found. Intermediate `wifi_scan_result` events can arrive with `scanComplete: false` while the glasses stream discovered networks; the final event uses `scanComplete: true`. If older glasses stream non-empty scan results but never send the completion event, the request resolves with the accumulated scan list when the request times out. `sendWifiCredentials()` resolves when the requested SSID is connected, `forgetWifiNetwork()` returns a semantic `WifiForgetResult`, `getSavedWifiNetworks()` returns a semantic `SavedWifiNetworksResult`, `setHotspotState()` resolves when the requested hotspot state is reported, and `requestVersionInfo()` waits for all chunks declared by the correlated response's `chunkCount`, `chunkIndex`, and `final` metadata. Legacy single-message responses complete immediately; legacy chunked responses complete on `version_info_3` after `version_info_1`. Missing final chunks time out rather than returning partial data after a quiet period.
+`requestWifiScan()` resolves from the ASG `wifi_scan_result` completion response with the updated scan list, including `[]` when no networks are found. Intermediate `wifi_scan_result` events can arrive with `scanComplete: false` while the glasses stream discovered networks; the final event uses `scanComplete: true`. If older glasses stream non-empty scan results but never send the completion event, the request resolves with the accumulated scan list when the request times out. `sendWifiCredentials()` resolves when the requested SSID is connected, `forgetWifiNetwork()` returns a semantic `WifiForgetResult`, `getSavedWifiNetworks()` returns a semantic `SavedWifiNetworksResult`, `setHotspotState()` resolves when the requested hotspot state is reported, and `requestVersionInfo()` waits for all chunks declared by the correlated response's `chunkCount`, `chunkIndex`, and `final` metadata. Legacy single-message responses complete immediately. Factory ASG27 declares build 27 in `version_info_1` and completes on its final `version_info_2` carrying the OTA URL; other legacy chunked responses complete on `version_info_3` after `version_info_1`. Missing final chunks time out rather than returning partial data after a quiet period.
 
 Current Mentra Live builds advertise `wifiForgetResultVersion` and `savedWifiNetworksVersion` in `version_info_1`. Native queues calls while those capabilities are unknown, sharing one 15-second deadline for negotiation and response. A discovery timeout rejects and never guesses that the glasses are legacy. Only version 1 is supported: modern commands carry `protocolVersion: 1`, a nonempty request ID, and the glasses process session ID; legacy forget commands omit all three fields. Unknown or malformed versions fail closed. Correlated results must match the complete tuple and (for forget) exact SSID; unrelated `wifi_status` events never settle a modern request. Session changes and disconnects reject pending WiFi work instead of allowing stale responses to cross sessions.
 

package/android/build.gradle

@@ -186,6 +186,21 @@ apply from: expoModulesCorePlugin
 applyKotlinExpoModulesCorePlugin()
 useExpoPublishing()
 
+// Hosts that embed @mentra/crust compile with Kotlin 2.3 (its QuickJS library
+// requires it). Keep the public Maven artifact usable from Kotlin 2.1 builds:
+// 2.2 metadata (a 2.1 compiler reads one version ahead; 2.2 is also the lowest
+// language version that reads the 2.3 expo-modules-core classes compiled here),
+// 2.1 stdlib APIs, and a kotlin-stdlib 2.1.20 dependency in the POM.
+if (publicMavenSdk) {
+  kotlin {
+    coreLibrariesVersion = "2.1.20"
+    compilerOptions {
+      languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_2
+      apiVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1
+    }
+  }
+}
+
 // If you want to use the managed Android SDK versions from expo-modules-core, set this to true.
 // The Android SDK versions will be bumped from time to time in SDK releases and may introduce breaking changes in your module code.
 // Most of the time, you may like to manage the Android SDK versions yourself.

package/android/lc3Lib/build.gradle

@@ -129,7 +129,12 @@ android {
 
         externalNativeBuild {
             cmake {
-                arguments '-DCMAKE_OBJECT_PATH_MAX=600', '-DANDROID_STL=c++_static'
+                // Google Play rejects 64-bit libraries whose ELF LOAD segments
+                // are not 16 KB aligned. NDK r27 (the React Native default)
+                // only aligns them with this flag; React Native's Gradle plugin
+                // adds it to the app module, never to library modules.
+                arguments '-DCMAKE_OBJECT_PATH_MAX=600', '-DANDROID_STL=c++_static',
+                    '-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON'
             }
         }
     }

package/android/src/debug/java/com/mentra/bluetoothsdk/sgcs/NimoDiagnostics.kt

@@ -0,0 +1,368 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import android.util.Log
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.BufferedWriter
+import java.io.File
+import java.security.MessageDigest
+import java.security.SecureRandom
+import java.util.UUID
+
+/** ADB-only, debug-build framebuffer capture on the existing owning GATT connection.
+ *
+ * No display, lifecycle, firmware, memory-address, or arbitrary-command controls are exposed.
+ * Captures are private device files, not application events or cloud logs. Two matching reads
+ * are non-atomic panel-memory evidence, not proof of light emitted by the display.
+ */
+internal class NimoDiagnostics(
+  context: Context,
+  private val handler: Handler,
+  private val send: (ByteArray, () -> Unit) -> Boolean,
+  private val requestCanvasHold: ((() -> Unit) -> Unit) = { ready -> ready() },
+  private val releaseCanvasHold: (resume: Boolean) -> Unit = {},
+) {
+  private val context = context.applicationContext
+  private val random = SecureRandom()
+  private var generation = 0L
+  private var maxWriteBytes = 0
+  private var registered = false
+  private var closed = false
+  private var active: Capture? = null
+
+  private enum class Stage { VERSION, READINESS, PING, GATE, PAGE }
+  private class Step(val stage: Stage, val request: NimoFramebufferProtocol.Request? = null) {
+    var timeout: Runnable? = null
+  }
+  private class Capture(val mode: String, val directory: File, val generation: Long) {
+    val started = SystemClock.elapsedRealtime()
+    val startedWallTime = System.currentTimeMillis()
+    val wire: BufferedWriter = File(directory, "wire.jsonl").bufferedWriter()
+    val nonces = mutableSetOf<Long>()
+    val banks = mutableListOf<NimoFramebufferProtocol.BankRead>()
+    val bankReceipts = JSONArray()
+    var wireCount = 0
+    var version: String? = null
+    var readiness: List<Int>? = null
+    var pending: Step? = null
+    var deadline: Runnable? = null
+    var currentBank: NimoFramebufferProtocol.BankRead? = null
+    var probeOk = false
+    var verifiedBanks = 0
+    var sampleState: NimoFramebufferProtocol.State? = null
+    var readStarted: Long? = null
+    var readFinished: Long? = null
+    var holdRequested = false
+    var holdReleased = false
+  }
+
+  private val receiver = object : BroadcastReceiver() {
+    override fun onReceive(context: Context?, intent: Intent?) {
+      requireMain()
+      if (intent?.action != ACTION) return
+      val mode = intent.getStringExtra("mode") ?: "probe"
+      if (mode !in listOf("probe", "capture", "sample", "held-capture", "held-sample")) {
+        Log.w(TAG, "Rejected unsupported mode")
+        return
+      }
+      start(mode)
+    }
+  }
+
+  fun connected(maxWriteBytes: Int) {
+    requireMain()
+    if (closed) return
+    disconnected()
+    this.maxWriteBytes = maxWriteBytes
+    try {
+      val filter = IntentFilter(ACTION)
+      if (Build.VERSION.SDK_INT >= 33) {
+        context.registerReceiver(receiver, filter, "android.permission.DUMP", handler, Context.RECEIVER_EXPORTED)
+      } else {
+        @Suppress("DEPRECATION")
+        context.registerReceiver(receiver, filter, "android.permission.DUMP", handler)
+      }
+      registered = true
+      Log.i(TAG, "ADB diagnostic receiver ready; write capacity=$maxWriteBytes")
+    } catch (error: RuntimeException) {
+      Log.w(TAG, "Diagnostic receiver unavailable: ${error.javaClass.simpleName}")
+    }
+  }
+
+  fun disconnected() {
+    requireMain()
+    generation += 1
+    active?.let { finish(it, "GATT disconnected or connection generation changed", resumeHeldCanvas = false) }
+    maxWriteBytes = 0
+    if (registered) {
+      registered = false
+      try { context.unregisterReceiver(receiver) } catch (_: IllegalArgumentException) { }
+    }
+  }
+
+  fun close() {
+    requireMain()
+    disconnected()
+    closed = true
+  }
+
+  fun cancelHeldCapture(reason: String, resumeCanvas: Boolean = false) {
+    requireMain()
+    val capture = active ?: return
+    if (isHeld(capture.mode)) finish(capture, reason, resumeCanvas)
+  }
+
+  /** Called only for notifications from the owning NIMO response characteristic. */
+  fun onPacket(packet: ByteArray): Boolean {
+    requireMain()
+    val capture = active ?: return false
+    if (packet.size < 10 || packet[8].toInt() != 2) return false
+    val key = packet[9].toInt() and 255
+    if (key !in listOf(0x0B, 0x19, 0x15)) return false
+    try {
+      recordWire(capture, "rx", packet)
+      val step = capture.pending
+      when (key) {
+        0x0B -> {
+          val payload = NimoFramebufferProtocol.basicPayload(packet, key)
+          capture.version = if (payload.isNotEmpty()) payload.copyOfRange(1, payload.size).toString(Charsets.US_ASCII) else ""
+          NimoFramebufferProtocol.version(packet)
+          if (step?.stage == Stage.VERSION) {
+            completeStep(capture, step)
+            request(capture, Step(Stage.READINESS))
+          }
+        }
+        0x19 -> {
+          capture.readiness = NimoFramebufferProtocol.readiness(packet)
+          val state = capture.readiness!!
+          Log.i(TAG, "Readiness status=${state[0]} ready=${state[1]} tws=${state[2]} peerGatt=${state[3]}")
+          if (step?.stage == Stage.READINESS) {
+            completeStep(capture, step)
+            request(capture, Step(Stage.PING, NimoFramebufferProtocol.Request(nonce(capture), 0, 0, 0)))
+          }
+        }
+        0x15 -> {
+          require(step != null && step.request != null) { "Unexpected FBP1 response without a pending request" }
+          val reply = NimoFramebufferProtocol.reply(packet, step.request)
+          completeStep(capture, step)
+          when (step.stage) {
+            Stage.PING -> request(capture, Step(Stage.GATE, NimoFramebufferProtocol.Request(nonce(capture), 1, 0, 0)))
+            Stage.GATE -> {
+              // A complete 275-byte response must succeed before any bulk read is attempted.
+              capture.probeOk = true
+              if (isSample(capture.mode)) capture.sampleState = reply.after
+              Log.i(TAG, "FBP1 identity and full-page gate verified; mode=${capture.mode}")
+              if (capture.mode == "probe") finish(capture, null) else nextBank(capture)
+            }
+            Stage.PAGE -> acceptPage(capture, reply)
+            else -> throw IllegalArgumentException("FBP1 response arrived in an invalid phase")
+          }
+        }
+      }
+    } catch (error: Exception) {
+      finish(capture, "${error.javaClass.simpleName}: ${error.message?.take(160)}")
+    }
+    // Basic responses remain visible to the production handshake. Private FBP1 never enters
+    // the legacy assembler, whose response length convention is different.
+    return key == 0x15
+  }
+
+  private fun start(mode: String) {
+    if (closed || !registered) return
+    if (active != null) { Log.w(TAG, "Capture already running; ignored duplicate request"); return }
+    val capture = try {
+      val root = File(context.filesDir, "nimo-framebuffer")
+      require(root.isDirectory || root.mkdirs()) { "Cannot create private capture directory" }
+      val directory = File(root, "${System.currentTimeMillis()}-${UUID.randomUUID().toString().take(8)}")
+      require(directory.mkdir()) { "Cannot create unique capture directory" }
+      Capture(mode, directory, generation)
+    } catch (error: Exception) {
+      Log.e(TAG, "Cannot begin private capture: ${error.javaClass.simpleName}")
+      return
+    }
+    active = capture
+    Log.i(TAG, "Starting $mode; files=${capture.directory.absolutePath}")
+    if (maxWriteBytes < 24) { finish(capture, "Write capacity below 24-byte diagnostic request"); return }
+    val budgetMs = when (mode) {
+      "held-sample" -> 15_000L
+      "held-capture" -> 55_000L
+      else -> 600_000L
+    }
+    val budgetDescription = when (mode) {
+      "held-sample" -> "15-second budget"
+      "held-capture" -> "55-second budget"
+      else -> "10-minute budget"
+    }
+    val deadline = Runnable {
+      if (active === capture) finish(capture, "Capture exceeded $budgetDescription")
+    }
+    capture.deadline = deadline
+    handler.postDelayed(deadline, budgetMs)
+    if (isHeld(mode)) {
+      capture.holdRequested = true
+      requestCanvasHold {
+        requireMain()
+        if (active === capture && capture.generation == generation) request(capture, Step(Stage.VERSION))
+      }
+    } else {
+      request(capture, Step(Stage.VERSION))
+    }
+  }
+
+  private fun request(capture: Capture, step: Step) {
+    if (active !== capture || capture.generation != generation) return
+    require(capture.pending == null) { "Only one diagnostic request may be in flight" }
+    val frame = when (step.stage) {
+      Stage.VERSION -> NimoFramebufferProtocol.queryFrame(0x0B)
+      Stage.READINESS -> NimoFramebufferProtocol.queryFrame(0x19)
+      else -> NimoFramebufferProtocol.requestFrame(requireNotNull(step.request))
+    }
+    capture.pending = step
+    try {
+      recordWire(capture, "tx", frame)
+      val accepted = send(frame) {
+        requireMain()
+        // A response may beat Android's write callback. Never arm an old step's timeout.
+        if (active === capture && capture.generation == generation && capture.pending === step) {
+          val timeout = Runnable {
+            if (active === capture && capture.pending === step) finish(capture, "${step.stage} response timeout")
+          }
+          step.timeout = timeout
+          handler.postDelayed(timeout, 3_000L)
+        }
+      }
+      if (!accepted && active === capture) finish(capture, "Owning GATT queue rejected diagnostic request")
+    } catch (error: Exception) {
+      finish(capture, "Diagnostic send failed: ${error.javaClass.simpleName}")
+    }
+  }
+
+  private fun completeStep(capture: Capture, step: Step) {
+    step.timeout?.let(handler::removeCallbacks)
+    capture.pending = null
+  }
+
+  private fun nextBank(capture: Capture) {
+    if (isSample(capture.mode) && capture.banks.size == 1) { finish(capture, null); return }
+    if (capture.banks.size == 4) { finish(capture, null); return }
+    val bank = if (isSample(capture.mode)) requireNotNull(capture.sampleState).prepared else capture.banks.size / 2
+    val read = NimoFramebufferProtocol.BankRead(nonce(capture), bank)
+    capture.currentBank = read
+    capture.readStarted = SystemClock.elapsedRealtime() - capture.started
+    request(capture, Step(Stage.PAGE, NimoFramebufferProtocol.Request(read.nonce, 1, bank, 0)))
+  }
+
+  private fun acceptPage(capture: Capture, reply: NimoFramebufferProtocol.Reply) {
+    val read = requireNotNull(capture.currentBank)
+    if (isSample(capture.mode)) {
+      require(reply.before == capture.sampleState) { "Sample metadata differs from page gate" }
+    }
+    read.add(reply)
+    if (read.pageCount % 63 == 0) Log.i(TAG, "bank=${read.bank} pass=${capture.banks.size % 2 + 1} pages=${read.pageCount}/315")
+    if (read.pageCount < NimoFramebufferProtocol.PAGE_COUNT) {
+      request(capture, Step(Stage.PAGE, NimoFramebufferProtocol.Request(read.nonce, 1, read.bank, read.pageCount)))
+      return
+    }
+    val pass = capture.banks.size % 2 + 1
+    val filename = "bank${read.bank}-pass$pass.bin"
+    val bytes = read.bytes()
+    capture.readFinished = SystemClock.elapsedRealtime() - capture.started
+    File(capture.directory, filename).writeBytes(bytes)
+    capture.bankReceipts.put(JSONObject().put("bank", read.bank).put("pass", pass).put("nonce", read.nonce)
+      .put("file", filename).put("page_count", read.pageCount).put("sha256", sha256(bytes))
+      .put("metadata", metadata(requireNotNull(read.metadata))))
+    capture.banks.add(read)
+    capture.currentBank = null
+    if (pass == 2) {
+      NimoFramebufferProtocol.verifyPair(capture.banks[capture.banks.size - 2], read)
+      capture.verifiedBanks += 1
+      Log.i(TAG, "Static pair verified for bank=${read.bank}; non-atomic panel memory only")
+    }
+    nextBank(capture)
+  }
+
+  private fun finish(capture: Capture, error: String?, resumeHeldCanvas: Boolean = true) {
+    if (active !== capture) return
+    active = null
+    capture.deadline?.let(handler::removeCallbacks)
+    capture.pending?.timeout?.let(handler::removeCallbacks)
+    capture.pending = null
+    if (capture.holdRequested && !capture.holdReleased) {
+      capture.holdReleased = true
+      releaseCanvasHold(resumeHeldCanvas)
+    }
+    var failure = error
+    try { capture.wire.close() } catch (_: Exception) { failure = failure ?: "Wire evidence could not be flushed" }
+    val complete = failure == null && !isSample(capture.mode) && capture.mode != "probe" &&
+      capture.verifiedBanks == 2 && capture.banks.size == 4
+    val sampleComplete = failure == null && isSample(capture.mode) && capture.banks.size == 1
+    val receipt = JSONObject().put("mode", capture.mode).put("ok", complete)
+      .put("sample_ok", sampleComplete)
+      .put("probe_ok", capture.probeOk && failure == null).put("error", failure ?: JSONObject.NULL)
+      .put("started_at_unix_ms", capture.startedWallTime).put("elapsed_ms", SystemClock.elapsedRealtime() - capture.started)
+      .put("runtime_version", capture.version ?: JSONObject.NULL)
+      .put("declared_installed_artifact_sha256", NimoFramebufferProtocol.ARTIFACT_SHA256)
+      .put("artifact_provenance", "Previously installed local diagnostic artifact; runtime SHA-256 is not measured")
+      .put("runtime_digest_measured", false)
+      .put("evidence_kind", if (isSample(capture.mode)) "non_atomic_single_pass" else "non_atomic_static_scene")
+      .put("pixel_stability_verified", complete)
+      .put("atomic", false).put("optical", false).put("optical_output_verified", false)
+      .put("notification_source", JSONObject().put("service", "7033").put("characteristic", "2022")
+        .put("transport", "Mentra owning Android GATT"))
+      .put("write_capacity", maxWriteBytes).put("width", NimoFramebufferProtocol.WIDTH)
+      .put("height", NimoFramebufferProtocol.HEIGHT).put("format", "packed4_high_nibble_first")
+      .put("wire_file", "wire.jsonl").put("wire_events", capture.wireCount).put("banks", capture.bankReceipts)
+      .put("static_pairs_verified", capture.verifiedBanks)
+    if (isSample(capture.mode)) {
+      receipt.put("selection_policy", "prepared_at_page_gate")
+        .put("selected_bank", capture.sampleState?.prepared ?: JSONObject.NULL)
+        .put("selection_metadata", capture.sampleState?.let(::metadata) ?: JSONObject.NULL)
+        .put("read_started_elapsed_ms", capture.readStarted ?: JSONObject.NULL)
+        .put("read_finished_elapsed_ms", capture.readFinished ?: JSONObject.NULL)
+    }
+    capture.readiness?.let { state ->
+      receipt.put("readiness", JSONObject().put("status", state[0]).put("ready", state[1])
+        .put("tws", state[2]).put("peer_gatt", state[3]))
+    }
+    try {
+      File(capture.directory, "session.json").writeText(receipt.toString(2) + "\n")
+      Log.i(TAG, "Finished mode=${capture.mode} ok=$complete sample_ok=$sampleComplete probe_ok=${capture.probeOk && failure == null} error=${failure ?: "none"}; files=${capture.directory.absolutePath}")
+    } catch (_: Exception) {
+      Log.e(TAG, "Capture receipt could not be written; do not treat this capture as verified")
+    }
+  }
+
+  private fun nonce(capture: Capture): Long {
+    var value: Long
+    do { value = random.nextInt().toLong() and 0xFFFFFFFFL } while (!capture.nonces.add(value))
+    return value
+  }
+
+  private fun recordWire(capture: Capture, direction: String, packet: ByteArray) {
+    require(packet.size <= 512 && capture.wireCount < 2700) { "Diagnostic wire evidence exceeded its bound" }
+    capture.wire.write(JSONObject().put("direction", direction).put("elapsed_ms", SystemClock.elapsedRealtime() - capture.started)
+      .put("hex", NimoFramebufferProtocol.hex(packet)).toString())
+    capture.wire.newLine()
+    capture.wireCount += 1
+  }
+
+  private fun metadata(state: NimoFramebufferProtocol.State) = JSONObject().put("draw", state.draw)
+    .put("prepared", state.prepared).put("dirty", state.dirty).put("pending", state.pending)
+  private fun sha256(bytes: ByteArray) = NimoFramebufferProtocol.hex(MessageDigest.getInstance("SHA-256").digest(bytes))
+  private fun requireMain() { check(Looper.myLooper() == handler.looper) { "NIMO diagnostics must run on its owning handler" } }
+  private fun isHeld(mode: String) = mode == "held-capture" || mode == "held-sample"
+  private fun isSample(mode: String) = mode == "sample" || mode == "held-sample"
+
+  companion object {
+    private const val TAG = "NimoFramebuffer"
+    private const val ACTION = "com.mentra.NIMO_FRAMEBUFFER_CAPTURE"
+  }
+}