@mentra/bluetooth-sdk 3.3.0-dev.419 → 3.3.0-dev.421

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

@@ -43,6 +43,7 @@ import com.mentra.bluetoothsdk.DeviceStore
 import com.mentra.bluetoothsdk.ObservableStore
 import com.mentra.bluetoothsdk.incomingGlassesMessageAckId
 import com.mentra.bluetoothsdk.wifiResponseEnvelopeIsValid
+import com.mentra.bluetoothsdk.debug.BleEvidenceLog
 import com.mentra.bluetoothsdk.debug.BleTraceLogger
 import com.mentra.bluetoothsdk.utils.BlePhotoUploadService
 import com.mentra.bluetoothsdk.utils.ConnTypes
@@ -597,6 +598,12 @@ class MentraLive : SGCManager() {
     private val gattLifecycleHandler = Handler(Looper.getMainLooper())
     // Owned exclusively by the main looper, including callback validation and mutation.
     private var gattEpoch = 0L
+    // Provenance of the current accepted connection and wire epoch. Copied into each accepted
+    // notification before decoding; never re-read to label an already received message.
+    private var evidenceOrigin: BleEvidenceLog.Origin? = null
+    // Evidence boundary of the current bleSessionGeneration (seq of its ble_generation record).
+    @Volatile private var evidenceWriteGeneration = 0L
+    @Volatile private var evidenceWriteGenerationValue = -1L
     private var connectionRequestEpoch = 0L
     @Volatile private var gattTeardownToken: Long? = null
     @Volatile private var gattTeardownTimeoutRunnable: Runnable? = null
@@ -650,7 +657,9 @@ class MentraLive : SGCManager() {
             val commandType: String,
             val requestId: String?,
             val appId: String?,
-            val messageId: Long?
+            val messageId: Long?,
+            // Wi-Fi scan request id; every native write of that command is recorded against it.
+            val scanId: String? = null
     )
 
     private data class BleWriteTrace(
@@ -666,7 +675,11 @@ class MentraLive : SGCManager() {
             val packedBytes: Int,
             val wakeup: Boolean,
             val chunked: Boolean,
-            val queuedAtMs: Long
+            val queuedAtMs: Long,
+            val scanId: String? = null,
+            // Provenance captured when the write is queued; later outcomes never re-read state.
+            val evidenceConnection: Long = 0L,
+            val evidenceWriteGeneration: Long? = null
     )
 
     private data class QueuedBleWrite(
@@ -1024,6 +1037,7 @@ class MentraLive : SGCManager() {
         this.type = DeviceTypes.LIVE
         this.hasMic = true
         this.context = Bridge.getContext()
+        recordWriteGeneration(bleSessionGeneration.get())
 
         // Initialize bluetooth adapter
         val bluetoothManager =
@@ -1179,6 +1193,9 @@ class MentraLive : SGCManager() {
         if (state == ConnTypes.DISCONNECTED) {
             DeviceStore.apply("glasses", "hotspotOtaVersion", 0)
         }
+        if (state == ConnTypes.DISCONNECTED) {
+            closeEvidenceConnection("disconnected")
+        }
         val isEqual = state == connectionState
         if (isEqual) {
             if (state == ConnTypes.DISCONNECTED) {
@@ -1692,6 +1709,7 @@ class MentraLive : SGCManager() {
         }
         val token = gattTeardownBarrier.beginTeardown()
         gattTeardownToken = token
+        closeEvidenceConnection("teardown")
         // Teardown owns session invalidation, including the timeout/replacement paths that do
         // not receive the normal remote-disconnect cleanup callback.
         cancelMtuWatchdog()
@@ -1765,6 +1783,34 @@ class MentraLive : SGCManager() {
         mtuSetupGate.cancel()
     }
 
+    private fun closeEvidenceConnection(reason: String) {
+        evidenceOrigin?.let { BleEvidenceLog.connectionClosed(it.connection, reason) }
+        evidenceOrigin = null
+    }
+
+    /** RX/TX carry every JSON/K900 message; audio and file characteristics are never evidence. */
+    private fun isCommandCharacteristic(characteristic: BluetoothGattCharacteristic): Boolean =
+            characteristic.uuid == RX_CHAR_UUID || characteristic.uuid == TX_CHAR_UUID
+
+    private fun recordScanSend(trace: BleWriteTrace?, outcome: String) {
+        val scanId = trace?.scanId ?: return
+        BleEvidenceLog.scanSend(
+                scanId,
+                outcome,
+                trace.chunkIndex ?: 0,
+                trace.totalChunks ?: 1,
+                trace.evidenceConnection,
+                trace.evidenceWriteGeneration
+        )
+    }
+
+    /** Records the send-queue generation boundary that queued writes will reference. */
+    private fun recordWriteGeneration(generation: Long) {
+        evidenceWriteGeneration =
+                BleEvidenceLog.bleGeneration(evidenceOrigin?.connection ?: 0L, generation)
+        evidenceWriteGenerationValue = generation
+    }
+
     /**
      * Reject callbacks delivered by a GATT object from an earlier connection attempt. Without
      * this identity check, a late disconnect can tear down the active connection and clear its
@@ -2276,6 +2322,15 @@ class MentraLive : SGCManager() {
                 // This lets connectGatt return and install the identity before validation.
                 gattLifecycleHandler.post { work() }
             }, { gatt -> epoch == gattEpoch && isCurrentGattCallback(gatt) }) {
+                override fun onStaleNotification(
+                        gatt: BluetoothGatt,
+                        characteristic: BluetoothGattCharacteristic
+                ) {
+                    if (isCommandCharacteristic(characteristic)) {
+                        BleEvidenceLog.receiveRejected("stale_gatt", null)
+                    }
+                }
+
                 override fun handleConnectionStateChange(
                         gatt: BluetoothGatt,
                         status: Int,
@@ -2313,6 +2368,8 @@ class MentraLive : SGCManager() {
                             isConnecting = false
                             isConnected = true
                             connectedDevice = gatt.device
+                            closeEvidenceConnection("replaced")
+                            evidenceOrigin = BleEvidenceLog.connectionAccepted(gatt.device.address)
                             classicAudioConnectionTracker.setTarget(gatt.device.address)
                             refreshClassicAudioConnectionState(gatt.device)
                             emitConnectedPendingDeviceForPairingScan()
@@ -2384,6 +2441,7 @@ class MentraLive : SGCManager() {
                             )
                             isConnected = false
                             isConnecting = false
+                            closeEvidenceConnection("remote_disconnect")
 
                             connectedDevice = null
                             glassesReady = false // Reset ready state on disconnect
@@ -2700,6 +2758,10 @@ class MentraLive : SGCManager() {
                             else null
                     inFlightBleWriteTrace = null
                     inFlightBleWriteStartedAtMs = 0L
+                    recordScanSend(
+                            trace,
+                            if (status == BluetoothGatt.GATT_SUCCESS) "write_ok" else "write_failed"
+                    )
 
                     if (status == BluetoothGatt.GATT_SUCCESS) {
                         // Bridge.log("LIVE: Characteristic write successful");
@@ -2759,8 +2821,13 @@ class MentraLive : SGCManager() {
                         data: ByteArray
                 ) {
                     if (!isActiveGattCallback(gatt)) {
+                        if (isCommandCharacteristic(characteristic)) {
+                            BleEvidenceLog.receiveRejected("teardown", null)
+                        }
                         return
                     }
+                    // Immutable origin of this notification, captured before any decoding.
+                    val origin = evidenceOrigin
 
                     // Get thread ID for tracking thread issues
                     val threadId = Thread.currentThread().id
@@ -2807,7 +2874,7 @@ class MentraLive : SGCManager() {
                     }
 
                     // Process command/JSON data on RX/TX characteristics
-                    processReceivedData(data, data.size)
+                    processReceivedData(data, data.size, origin)
                 }
 
                 override fun handleDescriptorWrite(
@@ -3223,6 +3290,7 @@ class MentraLive : SGCManager() {
         var queuedWrite = sendQueue.poll()
         val currentGeneration = bleSessionGeneration.get()
         while (queuedWrite != null && queuedWrite.sessionGeneration != currentGeneration) {
+            recordScanSend(queuedWrite.trace, "stale_dropped")
             Bridge.log(
                     "LIVE: Dropping stale queued write from BLE session " +
                             queuedWrite.sessionGeneration +
@@ -3258,10 +3326,15 @@ class MentraLive : SGCManager() {
 
     /** Send data through BLE */
     private fun sendDataInternal(write: QueuedBleWrite?) {
-        if (!isConnected || write == null) {
+        if (write == null) {
+            return
+        }
+        if (!isConnected) {
+            recordScanSend(write.trace, "gatt_refused")
             return
         }
         if (write.sessionGeneration != bleSessionGeneration.get()) {
+            recordScanSend(write.trace, "stale_dropped")
             Bridge.log("LIVE: Dropping stale BLE write before GATT transmission")
             return
         }
@@ -3269,6 +3342,7 @@ class MentraLive : SGCManager() {
         val gatt = bluetoothGatt
         val characteristic = txCharacteristic
         if (gatt == null || characteristic == null) {
+            recordScanSend(write.trace, "gatt_refused")
             return
         }
 
@@ -3278,6 +3352,7 @@ class MentraLive : SGCManager() {
             inFlightBleWriteTrace = write.trace
             inFlightBleWriteStartedAtMs = writeStartedAtMs
             val writeAccepted = gatt.writeCharacteristic(characteristic)
+            recordScanSend(write.trace, if (writeAccepted) "gatt_accepted" else "gatt_refused")
             logBleWriteTrace(
                     "write_call",
                     write.trace,
@@ -3294,6 +3369,7 @@ class MentraLive : SGCManager() {
                 inFlightBleWriteStartedAtMs = 0L
             }
         } catch (e: Exception) {
+            recordScanSend(write.trace, "gatt_refused")
             Log.e(TAG, "Error sending data via BLE", e)
             logBleWriteTrace(
                     "write_exception",
@@ -3320,9 +3396,16 @@ class MentraLive : SGCManager() {
                             queuedAtMs =
                                     if (trace.queuedAtMs > 0L)
                                             trace.queuedAtMs
-                                    else System.currentTimeMillis()
+                                    else System.currentTimeMillis(),
+                            evidenceConnection = evidenceOrigin?.connection ?: 0L,
+                            // A write carrying an older generation is already stale: no boundary.
+                            evidenceWriteGeneration =
+                                    if (sessionGeneration == evidenceWriteGenerationValue)
+                                            evidenceWriteGeneration
+                                    else null
                     )
             sendQueue.add(QueuedBleWrite(data, queuedTrace, sessionGeneration))
+            recordScanSend(queuedTrace, "queued")
             logBleChunkTrace(
                     "queued",
                     queuedTrace,
@@ -3543,6 +3626,7 @@ class MentraLive : SGCManager() {
      */
     private fun resetPendingAckState() {
         val nextGeneration = bleSessionGeneration.incrementAndGet()
+        recordWriteGeneration(nextGeneration)
         val pendingCount = pendingMessages.size
         pendingMessages.clear()
         if (pendingCount > 0) {
@@ -3871,7 +3955,7 @@ class MentraLive : SGCManager() {
     }
 
     /** Process data received from the glasses */
-    private fun processReceivedData(data: ByteArray?, size: Int) {
+    private fun processReceivedData(data: ByteArray?, size: Int, origin: BleEvidenceLog.Origin?) {
         // Bridge.log("LIVE: Processing received data: " + bytesToHex(data));
 
         // Check if we have enough data
@@ -3938,7 +4022,7 @@ class MentraLive : SGCManager() {
             }
 
             if (cmdType == K900ProtocolUtils.CMD_TYPE_BINARY_MSG) {
-                processBinaryWireFrame(data)
+                processBinaryWireFrame(data, origin)
                 return
             }
 
@@ -3956,7 +4040,7 @@ class MentraLive : SGCManager() {
                     Log.w(TAG, "Thread-$threadId: Rejected unsupported compact wire form")
                     return
                 }
-                processJsonMessage(expanded)
+                processJsonMessage(expanded, origin)
             } else {
                 Log.w(TAG, "Thread-" + threadId + ": Failed to parse K900 protocol data")
             }
@@ -3981,7 +4065,7 @@ class MentraLive : SGCManager() {
                     val jsonStr = String(data, 0, size, StandardCharsets.UTF_8)
                     if (jsonStr.startsWith("{") && jsonStr.endsWith("}")) {
                         val json = JSONObject(jsonStr)
-                        processJsonMessage(json)
+                        processJsonMessage(json, origin)
                     } else {
                         Log.w(TAG, "Received data that starts with '{' but is not valid JSON")
                     }
@@ -4004,7 +4088,7 @@ class MentraLive : SGCManager() {
     }
 
     /** Process a JSON message */
-    private fun processJsonMessage(json: JSONObject) {
+    private fun processJsonMessage(json: JSONObject, origin: BleEvidenceLog.Origin?) {
         // Demoted from INFO (Bridge.log) to DEBUG: per-type handlers below already log
         // the messages that matter, and full payloads can leak PII (wifi SSID, bt_mac,
         // OTA URLs) into the persisted file logger when they arrive every ~50ms during OTA.
@@ -4016,7 +4100,7 @@ class MentraLive : SGCManager() {
         GlassesLinkDiagnostics.recordInbound()
 
         if (MessageChunker.isChunkedMessage(json)) {
-            processChunkedJsonMessage(json)
+            processChunkedJsonMessage(json, origin)
             return
         }
 
@@ -4035,7 +4119,7 @@ class MentraLive : SGCManager() {
 
         // Check if this is a K900 command format (has "C" field instead of "type")
         if (json.has("C")) {
-            processK900JsonMessage(json)
+            processK900JsonMessage(json, origin)
             return
         }
 
@@ -4131,7 +4215,15 @@ class MentraLive : SGCManager() {
                 // that reads "charging" for most of a discharging pack's range. Charging
                 // state comes exclusively from the PMU charg bit in the sr_hrt heartbeat.
                 val percent = json.optInt("percent", batteryLevel)
-                updateBatteryStatus(percent, isCharging)
+                // A missing or invalid field keeps the previous fallback display value, but only a
+                // measured percentage carries provenance.
+                updateBatteryStatus(
+                        percent,
+                        isCharging,
+                        measuredPercent(json, "percent")?.let {
+                            BatteryProvenance("battery_status", origin, null)
+                        }
+                )
             }
             "stream_controller_probe" -> {
                 val values = mapOf("protocolVersion" to json.opt("protocolVersion"),
@@ -4306,6 +4398,8 @@ class MentraLive : SGCManager() {
             "wifi_scan_result" -> {
                 // Process WiFi scan results
                 val networks: MutableList<Map<String, Any>> = ArrayList()
+                // Evidence only: false when the network list is missing or not fully parsed.
+                var networksParsed = false
 
                 if (json.has("networks_neo")) {
                     try {
@@ -4323,6 +4417,7 @@ class MentraLive : SGCManager() {
                             }
                             networks.add(networkMap)
                         }
+                        networksParsed = true
 
                         Bridge.log(
                                 "Received enhanced WiFi scan results: " +
@@ -4337,7 +4432,9 @@ class MentraLive : SGCManager() {
                 val scanComplete =
                         json.optBoolean("scan_complete", json.optBoolean("scanComplete", false))
                 val scanId = json.optString("scanId", "").ifEmpty { null }
-                Bridge.updateWifiScanResults(networks, scanComplete, scanId)
+                val eventId =
+                        BleEvidenceLog.scanChunk(origin, scanId, networks, scanComplete, networksParsed)
+                Bridge.updateWifiScanResults(networks, scanComplete, scanId, eventId)
             }
             "token_status" -> {
                 // Process coreToken acknowledgment
@@ -5211,7 +5308,7 @@ class MentraLive : SGCManager() {
         return value
     }
 
-    private fun processChunkedJsonMessage(json: JSONObject) {
+    private fun processChunkedJsonMessage(json: JSONObject, origin: BleEvidenceLog.Origin?) {
         try {
             val chunkInfo = MessageChunker.getChunkInfo(json)
             if (chunkInfo == null) {
@@ -5229,19 +5326,24 @@ class MentraLive : SGCManager() {
                 return
             }
 
+            val mixedBefore = incomingChunkReassembler.mixedOriginDrops
             val reassembled =
                     incomingChunkReassembler.addChunk(
                             chunkInfo.chunkId,
                             chunkInfo.chunkIndex,
                             chunkInfo.totalChunks,
-                            chunkInfo.data
+                            chunkInfo.data,
+                            origin
                     )
+            if (incomingChunkReassembler.mixedOriginDrops != mixedBefore) {
+                BleEvidenceLog.receiveRejected("mixed_origin", origin)
+            }
             if (reassembled == null) {
                 return
             }
 
             val reassembledJson = JSONObject(reassembled)
-            processJsonMessage(reassembledJson)
+            processJsonMessage(reassembledJson, origin)
         } catch (e: Exception) {
             Log.e(TAG, "Error processing chunked JSON message", e)
         }
@@ -5449,7 +5551,7 @@ class MentraLive : SGCManager() {
         }
     }
 
-    private fun processK900JsonMessage(json: JSONObject) {
+    private fun processK900JsonMessage(json: JSONObject, origin: BleEvidenceLog.Origin?) {
         val command = json.optString("C", "")
         // Bridge.log("LIVE: Processing K900 command: " + command);
 
@@ -5493,7 +5595,17 @@ class MentraLive : SGCManager() {
                         }
                         val charg = bodyObj.optInt("charg", -1)
                         if (batteryPercentage != -1 && charg != -1)
-                                updateBatteryStatus(batteryPercentage, charg == 1)
+                                updateBatteryStatus(
+                                        batteryPercentage,
+                                        charg == 1,
+                                        measuredPercent(bodyObj, "pt")?.let {
+                                            BatteryProvenance(
+                                                    "k900_sr_hrt",
+                                                    origin,
+                                                    pmuChargingBit(bodyObj)
+                                            )
+                                        }
+                                )
                     }
                 } catch (e: Exception) {
                     Log.e(TAG, "Error parsing sr_hrt response", e)
@@ -5524,7 +5636,13 @@ class MentraLive : SGCManager() {
                         // charging from voltage (>4.0V) reads "not charging" for most of a
                         // genuinely-charging pack's range. Charging state comes exclusively
                         // from the PMU charg bit in the sr_hrt heartbeat.
-                        updateBatteryStatus(batteryPercentage, isCharging)
+                        updateBatteryStatus(
+                                batteryPercentage,
+                                isCharging,
+                                measuredPercent(bodyObj, "pt")?.let {
+                                    BatteryProvenance("k900_sr_batv", origin, null)
+                                }
+                        )
                     }
                 } catch (e: Exception) {
                     Log.e(TAG, "Error parsing sr_batv response", e)
@@ -5761,7 +5879,7 @@ class MentraLive : SGCManager() {
                         Log.d(TAG, "🔓 Unwrapping and processing through standard message handler")
 
                         // Process through the standard message handler
-                        processJsonMessage(innerJson)
+                        processJsonMessage(innerJson, origin)
                         return // Exit after processing
                     }
                 } catch (e: JSONException) {
@@ -5875,7 +5993,44 @@ class MentraLive : SGCManager() {
      * Update battery status and notify listeners Matches iOS MentraLive.swift updateBatteryStatus
      * pattern
      */
-    private fun updateBatteryStatus(level: Int, isCharging: Boolean) {
+    /**
+     * [source] names the decoded message. [pmuCharging] is set only when the PMU charg bit of
+     * this very message supplied [isCharging]; percent-only sources re-pass the inherited value.
+     */
+    /**
+     * Provenance of a battery update decoded from one notification. [pmuCharging] is set only
+     * when the PMU charg bit of that message supplied the charging state.
+     */
+    private data class BatteryProvenance(
+            val source: String,
+            val origin: BleEvidenceLog.Origin?,
+            val pmuCharging: Boolean?
+    )
+
+    /**
+     * The sr_hrt PMU charging bit, only when `charg` is a number exactly equal to 0 or 1. The
+     * original value is compared without truncation, so 0.5 or 1.5 is not a bit.
+     */
+    private fun pmuChargingBit(body: JSONObject): Boolean? =
+            when ((body.opt("charg") as? Number)?.toDouble()) {
+                1.0 -> true
+                0.0 -> false
+                else -> null
+            }
+
+    /** The field's value when it is an actual integer percentage, else null (missing/invalid). */
+    private fun measuredPercent(obj: JSONObject, key: String): Int? {
+        val value = obj.opt(key) as? Number ?: return null
+        val asDouble = value.toDouble()
+        if (asDouble != Math.floor(asDouble) || asDouble < 0 || asDouble > 100) return null
+        return asDouble.toInt()
+    }
+
+    /**
+     * [provenance] is null for fallback or cached values: they are still displayed as before but
+     * carry no event id, so they can never count as a fresh measurement.
+     */
+    private fun updateBatteryStatus(level: Int, isCharging: Boolean, provenance: BatteryProvenance?) {
         // Keep the field in sync: percent-only messages (battery_status/sr_batv) re-pass
         // it as the last-known charging state, so a stale field would clobber the value
         // the sr_hrt PMU charg bit established.
@@ -5886,7 +6041,11 @@ class MentraLive : SGCManager() {
         DeviceStore.apply("glasses", "charging", isCharging)
 
         if (level >= 0) {
-            Bridge.sendBatteryStatus(level, isCharging)
+            val eventId =
+                    provenance?.let {
+                        BleEvidenceLog.battery(it.origin, level, it.source, it.pmuCharging)
+                    }
+            Bridge.sendBatteryStatus(level, isCharging, eventId)
         }
     }
 
@@ -6063,7 +6222,17 @@ class MentraLive : SGCManager() {
             if (!scanId.isNullOrEmpty()) {
                 json.put("scanId", scanId)
             }
-            sendJson(json, true)
+            val queued = sendJson(json, true, true)
+            if (!queued && !scanId.isNullOrEmpty()) {
+                BleEvidenceLog.scanSend(
+                        scanId,
+                        "not_queued",
+                        0,
+                        0,
+                        evidenceOrigin?.connection ?: 0L,
+                        evidenceWriteGeneration
+                )
+            }
             Bridge.log("LIVE: Sending WiFi scan request to glasses")
         } catch (e: JSONException) {
             Log.e(TAG, "Error creating WiFi scan request", e)
@@ -9009,6 +9178,9 @@ class MentraLive : SGCManager() {
      * the per-session handshake attempt cap) instead of trusting stale v2-active state.
      */
     private fun resetWireNegotiationState() {
+        evidenceOrigin?.let {
+            evidenceOrigin = it.copy(wire = BleEvidenceLog.wireReset(it.connection))
+        }
         incomingChunkReassembler.clear()
         peerWireProtocolVersion = 0
         useBinaryWireProtocol = false
@@ -9244,7 +9416,7 @@ class MentraLive : SGCManager() {
         activateBinaryWireV2Session("LIVE: Peer confirmed BLE wire protocol v2")
     }
 
-    private fun processBinaryWireFrame(data: ByteArray) {
+    private fun processBinaryWireFrame(data: ByteArray, origin: BleEvidenceLog.Origin?) {
         val info = K900ProtocolUtils.extractBinaryFragmentInfo(data) ?: run {
             Log.w(TAG, "Failed to parse binary wire frame")
             return
@@ -9261,14 +9433,19 @@ class MentraLive : SGCManager() {
             )
         }
 
+        val mixedBefore = incomingChunkReassembler.mixedOriginDrops
         val reassembled =
                 incomingChunkReassembler.addBinaryFragment(
                         info.msgId,
                         info.fragIdx,
                         info.fragCount,
-                        info.payload
+                        info.payload,
+                        origin
                 )
-                ?: return
+        if (incomingChunkReassembler.mixedOriginDrops != mixedBefore) {
+            BleEvidenceLog.receiveRejected("mixed_origin", origin)
+        }
+        if (reassembled == null) return
 
         try {
             val jsonStr = String(reassembled, StandardCharsets.UTF_8)
@@ -9284,7 +9461,7 @@ class MentraLive : SGCManager() {
                     BleWireProtocol.PROTOCOL_V2,
                     "glasses_to_phone"
             )
-            processJsonMessage(json)
+            processJsonMessage(json, origin)
         } catch (e: JSONException) {
             Log.e(TAG, "Failed to parse reassembled binary wire JSON", e)
         }
@@ -9493,7 +9670,11 @@ class MentraLive : SGCManager() {
                 }
             } else {
                 // Normal single message transmission
-                transportLog("LIVE: Sending data to glasses: " + wireData, bridgeLogging)
+                transportLog(
+                        "LIVE: Sending data to glasses: " +
+                                loggableOutgoingPayload(wireData, commandTraceInfo.commandType),
+                        bridgeLogging
+                )
 
                 // Pack the data using the centralized utility with the negotiated endianness
                 val packedData =
@@ -9625,11 +9806,15 @@ class MentraLive : SGCManager() {
     private fun parseOutgoingBleCommandTraceInfo(payload: String): OutgoingBleCommandTraceInfo {
         return try {
             val obj = JSONObject(payload)
+            val commandType = obj.optString("type", "unknown")
             OutgoingBleCommandTraceInfo(
-                    commandType = obj.optString("type", "unknown"),
+                    commandType = commandType,
                     requestId = optNonBlankString(obj, "requestId"),
                     appId = optNonBlankString(obj, "appId"),
-                    messageId = if (obj.has("mId")) obj.optLong("mId") else null
+                    messageId = if (obj.has("mId")) obj.optLong("mId") else null,
+                    scanId =
+                            if (commandType == "request_wifi_scan") optNonBlankString(obj, "scanId")
+                            else null
             )
         } catch (_: Exception) {
             OutgoingBleCommandTraceInfo(
@@ -9664,7 +9849,8 @@ class MentraLive : SGCManager() {
                 packedBytes = packedBytes,
                 wakeup = wakeup,
                 chunked = chunked,
-                queuedAtMs = System.currentTimeMillis()
+                queuedAtMs = System.currentTimeMillis(),
+                scanId = commandInfo.scanId
         )
     }
 
@@ -9795,6 +9981,18 @@ class MentraLive : SGCManager() {
         }
     }
 
+    /**
+     * Wi-Fi credentials are sent unchanged but never logged; the BLE trace records the command
+     * with the password redacted.
+     */
+    private fun loggableOutgoingPayload(payload: String, commandType: String): String =
+            try {
+                if (JSONObject(payload).has("password")) "<$commandType with credentials omitted>"
+                else payload
+            } catch (_: JSONException) {
+                payload
+            }
+
     private fun summarizeOutgoingMessage(payload: String?): String {
         if (payload == null || payload.isEmpty()) {
             return "type=unknown, requestId=none, appId=none, mode=none, transferMethod=none, bleImgId=none, exposureTimeNs=none, iso=none, mId=none"

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

@@ -18,6 +18,17 @@ internal abstract class SerializedGattCallback(
         enqueue { if (isCurrent(gatt)) work() }
     }
 
+    private fun dispatchNotification(
+        gatt: BluetoothGatt,
+        characteristic: BluetoothGattCharacteristic,
+        work: () -> Unit,
+    ) {
+        enqueue { if (isCurrent(gatt)) work() else onStaleNotification(gatt, characteristic) }
+    }
+
+    /** A notification from a GATT that is no longer current was dropped on the owner queue. */
+    protected open fun onStaleNotification(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic) {}
+
     final override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) =
         dispatch(gatt) { handleConnectionStateChange(gatt, status, newState) }
 
@@ -46,14 +57,14 @@ internal abstract class SerializedGattCallback(
         gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic,
     ) {
         val value = characteristic.value?.copyOf() ?: return
-        dispatch(gatt) { handleCharacteristicChanged(gatt, characteristic, value) }
+        dispatchNotification(gatt, characteristic) { handleCharacteristicChanged(gatt, characteristic, value) }
     }
 
     final override fun onCharacteristicChanged(
         gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray,
     ) {
         val snapshot = value.copyOf()
-        dispatch(gatt) { handleCharacteristicChanged(gatt, characteristic, snapshot) }
+        dispatchNotification(gatt, characteristic) { handleCharacteristicChanged(gatt, characteristic, snapshot) }
     }
 
     final override fun onDescriptorWrite(