@mentra/bluetooth-sdk 0.1.14 → 0.1.16

package/ios/Source/sgcs/G2.swift

@@ -1322,6 +1322,56 @@ private class G2ReceiveManager {
     }
 }
 
+// MARK: - Image ACK box
+
+/// Thread-safe holder for the single in-flight image-fragment ACK continuation.
+///
+/// Lives OUTSIDE `@MainActor` isolation so the CoreBluetooth notify callback (which runs on the BLE
+/// dispatch queue) can correlate and resume the awaiting continuation directly, without hopping to
+/// the main actor. That hop is exactly what caused intermittent "glasses stopped responding": the
+/// ACK would queue behind a packet burst / heartbeats / the text-queue tick on the main actor and
+/// miss the timeout window even though it had physically arrived.
+///
+/// All access is guarded by `lock`. Resuming a `CheckedContinuation` from any thread is safe, and
+/// `arm`/`resolve` clear the slot atomically so neither the duplicate L/R ACK nor the timeout can
+/// resume the same continuation twice.
+private final class ImgAckBox {
+    private let lock = NSLock()
+    private var session: Int?
+    private var fragment: Int32?
+    private var cont: CheckedContinuation<Bool, Never>?
+
+    /// Install the awaiting continuation for `(session, fragment)`.
+    func arm(session: Int, fragment: Int32, cont: CheckedContinuation<Bool, Never>) {
+        lock.lock()
+        self.session = session
+        self.fragment = fragment
+        self.cont = cont
+        lock.unlock()
+    }
+
+    /// Resume the continuation if it matches `(session, fragment)`. Returns true if it fired.
+    @discardableResult
+    func resolve(session: Int, fragment: Int32, success: Bool) -> Bool {
+        lock.lock()
+        guard self.session == session, self.fragment == fragment, let c = cont else {
+            lock.unlock()
+            return false
+        }
+        self.session = nil
+        self.fragment = nil
+        self.cont = nil
+        lock.unlock()
+        c.resume(returning: success)
+        return true
+    }
+
+    /// Time out the continuation for `(session, fragment)` (resumes false if still armed).
+    func timeout(session: Int, fragment: Int32) {
+        _ = resolve(session: session, fragment: fragment, success: false)
+    }
+}
+
 // MARK: - G2 Class (SGCManager implementation)
 
 /// Actor for reconnection logic (matches G1 pattern)
@@ -1405,6 +1455,17 @@ class G2: NSObject, SGCManager {
     private var pairingTimeoutTimer: DispatchWorkItem?
     private var useEvenDashboard = true
     private var dashboardShowing = 0
+    // The 08011A00 gesture_ctrl event is ambiguous: the firmware sends it BOTH when the dashboard
+    // opens (it shuts our page down to take the screen) and when it closes (returns to us). When
+    // showDashboard() runs we set this latch; the next 08011A00 is the OPEN confirm — consume it
+    // WITHOUT recovering (else we rebuild our page and snatch the screen back from the dashboard).
+    // The following 08011A00 is the real CLOSE → recover.
+    private var dashboardOpening = false
+    // Recovery throttle: the firmware spams systemExit + dashboard-close ~1×/sec on its own.
+    // Coalesce so recovery can't storm — one rebuild in flight, one per RECOVERY_DEBOUNCE_MS.
+    private var recoveryInFlight = false
+    private var lastRecoveryRebuildMs: Int64 = 0
+    private let RECOVERY_DEBOUNCE_MS: Int64 = 1500
 
     /// Device search
     var DEVICE_SEARCH_ID = "NOT_SET"
@@ -1459,18 +1520,36 @@ class G2: NSObject, SGCManager {
     private var foregroundObserver: NSObjectProtocol?
     private var startupPageCreated: Bool = false  // createStartUpPageContainer can only be called once
     private var pageCreated: Bool = false
+    // Live hardware truth: is the firmware mic actually streaming. DISTINCT from the
+    // glasses/micEnabled DeviceStore flag, which is *intent* (does the user want the mic on).
+    // Cleared on every page teardown (the firmware kills the mic with the page) WITHOUT touching
+    // intent, so recovery can re-arm iff intent still says the mic should be on.
+    private var evenHubMicActive: Bool = false
     private var currentTextContent: String = ""
     private var currentBitmapBase64: String = ""
     private var textContainerID: Int32 = 1
     private var imageSessionCounter: Int = 0
+    /// Lock-protected, non-isolated holder for the in-flight image ACK so the BLE-queue notify
+    /// callback can resolve it without bouncing through the main actor (see [ImgAckBox]).
+    private let imgAckBox = ImgAckBox()
+    /// Background loop that owns ALL display sends (text + images): each pass pushes dirty text
+    /// containers, then dirty image containers one at a time. Because it's the sole sender, exactly
+    /// one `sendImageData` is ever in flight by construction — no serializing lock needed; display
+    /// ops just mark containers dirty and signal `displayDirtySignal`.
+    private var displayReconcileTask: Task<Void, Never>?
+    /// ~100ms ticker that nudges the reconcile loop while idle, so text resends and image retries
+    /// still happen with no new mutations. Just yields into `displayDirtySignal`.
+    private var displayTickTask: Task<Void, Never>?
+    /// Wakes the reconcile loop the instant a container is marked dirty, instead of waiting out the
+    /// idle tick. `signalDisplayDirty()` (and the ticker) yield into this; the loop drains it.
+    private var displayDirtySignal: AsyncStream<Void>.Continuation?
+    private let IMG_ACK_TIMEOUT_NS: UInt64 = 2_000_000_000  // 1000ms timeout (matches Dart host)
+    private let IMG_MAX_ATTEMPTS = 3
     private var heartbeatTask: Task<Void, Never>?
     private var heartbeatCounter: Int = 0
-    private var evenHubQueueTask: Task<Void, Never>?
-    private var pendingTextMsg: Data?
-    private var lastEvenHubMsg: Data?
-    private var lastEvenHubResendsRemaining: Int = 0
+    /// How many redundant resends each text update gets (text has no ACK). The reconcile loop sets a
+    /// container's `pendingSends` to `1 + EVEN_HUB_RESEND_COUNT` on change.
     private let EVEN_HUB_RESEND_COUNT: Int = 1
-    private let evenHubQueueLock = NSLock()
     private var authStarted: Bool = false
 
     /// Dashboard menu: appId → packageName mapping for selection reverse lookup
@@ -1496,6 +1575,11 @@ class G2: NSObject, SGCManager {
             "img-\(id)"
         }
         var bmpData: Data
+        /// Set true when `bmpData` changes and the new pixels haven't been pushed to the glasses yet.
+        /// The reconcile loop (see `displayReconcileTask`) is the sole sender; it clears this once the
+        /// exact bytes it sent still match the container. Lets every display op be a pure state
+        /// mutation, so only one `sendImageData` is ever in flight (no DisplayMutex needed).
+        var dirty: Bool = false
 
         func matches(x: Int32, y: Int32, width: Int32, height: Int32) -> Bool {
             self.x == x && self.y == y && self.width == width && self.height == height
@@ -1513,6 +1597,10 @@ class G2: NSObject, SGCManager {
         let borderColor: Int32
         let borderRadius: Int32
         let paddingLength: Int32
+        /// Remaining sends the reconcile loop owes this container. Text has no ACK, so each content
+        /// change schedules `1 + EVEN_HUB_RESEND_COUNT` sends (the update + a redundant resend on a
+        /// later tick) as a delivery hedge; the loop sends once and decrements per tick until 0.
+        var pendingSends: Int = 0
         var name: String {
             "text-\(id)"
         }
@@ -1563,15 +1651,83 @@ class G2: NSObject, SGCManager {
 
     // MARK: - BLE Sending
 
+    // Per-side FIFO write queues, drained by a single paced async writer per side.
+    //
+    // We write `.withoutResponse` directly and pace with a small `Task.sleep` between packets —
+    // exactly like G1 (`G1.swift attemptSend`). We deliberately do NOT gate on
+    // `canSendWriteWithoutResponse` / wait for `peripheralIsReady(toSendWriteWithoutResponse:)`:
+    // iOS suppresses that "ready" callback for a backgrounded bluetooth-central app (G2 has no
+    // active AVAudioSession — glasses-mic audio arrives over BLE), so a gated drain DEADLOCKS in the
+    // background: the queue grows for the whole bg window and floods the glasses on resume — the
+    // captions "freeze in bg, then flood" bug. G1 never gates and never floods; this matches it.
+    // The pace replaces the gate's overflow protection (the original reason for gating). Any packet
+    // CoreBluetooth still drops self-heals: text is re-sent (TextContainer.pendingSends) and image
+    // fragments retry on their ACK (`awaitImageAck`).
+    private var leftWriteQueue: [Data] = []
+    private var rightWriteQueue: [Data] = []
+    private var leftDraining = false
+    private var rightDraining = false
+    // Pace between consecutive packets (~G1's chunk pacing). Off any external callback, so the drain
+    // keeps making progress in the background instead of waiting for a callback iOS won't deliver.
+    private let writePaceNanos: UInt64 = 6_000_000
+    // Diagnostic: warn if a side's queue ever backs up (it shouldn't now — the drainer is always
+    // making progress). Rate-limited. Prefixed "BGCAP:" so it's easy to grep/strip after validation.
+    private var bgcapDepthLogAt: Double = 0
+
     private func sendToGlasses(_ packets: [Data], left: Bool = false, right: Bool = true) {
-        // Bridge.log("G2: sendToGlasses() - sending \(packets.count) packets first byte: \(packets[0][0])")
-        for packet in packets {
-            if right, let char = rightWriteChar, let peripheral = rightPeripheral {
-                peripheral.writeValue(packet, for: char, type: .withoutResponse)
+        if right {
+            rightWriteQueue.append(contentsOf: packets)
+            startDrain(right: true)
+        }
+        if left {
+            leftWriteQueue.append(contentsOf: packets)
+            startDrain(right: false)
+        }
+    }
+
+    /// Ensure a single paced drainer is running for this side. Idempotent — a second call while one
+    /// is already draining is a no-op (the running loop will pick up the newly-enqueued packets).
+    private func startDrain(right: Bool) {
+        if right {
+            if rightDraining { return }
+            rightDraining = true
+        } else {
+            if leftDraining { return }
+            leftDraining = true
+        }
+        Task { @MainActor [weak self] in
+            await self?.drainLoop(right: right)
+        }
+    }
+
+    /// Drain one side's queue: write each packet directly (`.withoutResponse`), paced by a small
+    /// sleep. No `canSend` gate (see note above). Runs until the queue is empty, then clears the
+    /// per-side flag so the next enqueue restarts it.
+    private func drainLoop(right: Bool) async {
+        while true {
+            guard let peripheral = right ? rightPeripheral : leftPeripheral,
+                let char = right ? rightWriteChar : leftWriteChar
+            else {
+                // No connection for this side; drop pending packets so they can't replay later.
+                if right { rightWriteQueue.removeAll(); rightDraining = false }
+                else { leftWriteQueue.removeAll(); leftDraining = false }
+                return
+            }
+            let depth = (right ? rightWriteQueue : leftWriteQueue).count
+            if depth == 0 {
+                if right { rightDraining = false } else { leftDraining = false }
+                return
             }
-            if left, let char = leftWriteChar, let peripheral = leftPeripheral {
-                peripheral.writeValue(packet, for: char, type: .withoutResponse)
+            if depth > 20 {
+                let now = Date().timeIntervalSince1970
+                if now - bgcapDepthLogAt >= 1.0 {
+                    Bridge.log("BGCAP: g2 write queue depth=\(depth) side=\(right ? "R" : "L") (draining, not blocked)")
+                    bgcapDepthLogAt = now
+                }
             }
+            let packet = right ? rightWriteQueue.removeFirst() : leftWriteQueue.removeFirst()
+            peripheral.writeValue(packet, for: char, type: .withoutResponse)
+            try? await Task.sleep(nanoseconds: writePaceNanos)
         }
     }
 
@@ -1859,15 +2015,32 @@ class G2: NSObject, SGCManager {
             }
         }
 
-        // EvenHub text command queue: drain the most recent pending updateText every 100ms
-        evenHubQueueTask?.cancel()
-        evenHubQueueTask = Task { [weak self] in
+        // Display reconcile loop: push any dirty text containers (one send each, with a redundant
+        // resend), then any dirty image containers one at a time. Single sender, so a `sendImageData`
+        // never overlaps another and can't clobber imgAckBox — the invariant DisplayMutex used to
+        // enforce. The loop wakes on each stream element: mutations yield one immediately (instant
+        // reaction), and a ~100ms ticker yields one when idle so periodic work (text resends, image
+        // retries) still runs. The 1-deep buffer coalesces bursts into a single wake.
+        displayReconcileTask?.cancel()
+        displayTickTask?.cancel()
+        // Closure-based initializer (not makeStream, which is iOS 16+). 1-deep newest buffer so a
+        // burst of mutations coalesces into a single wake.
+        var signalContinuation: AsyncStream<Void>.Continuation!
+        let signalStream = AsyncStream<Void>(bufferingPolicy: .bufferingNewest(1)) { continuation in
+            signalContinuation = continuation
+        }
+        displayDirtySignal = signalContinuation
+        displayTickTask = Task { [weak self] in
             while !Task.isCancelled {
                 try? await Task.sleep(nanoseconds: 100_000_000)
                 guard !Task.isCancelled else { break }
-                await MainActor.run {
-                    self?.drainEvenHubQueue()
-                }
+                self?.displayDirtySignal?.yield()
+            }
+        }
+        displayReconcileTask = Task { [weak self] in
+            for await _ in signalStream {
+                if Task.isCancelled { break }
+                await self?.reconcileDisplay()
             }
         }
     }
@@ -1875,13 +2048,19 @@ class G2: NSObject, SGCManager {
     private func stopHeartbeats() {
         heartbeatTask?.cancel()
         heartbeatTask = nil
-        evenHubQueueTask?.cancel()
-        evenHubQueueTask = nil
-        evenHubQueueLock.lock()
-        pendingTextMsg = nil
-        lastEvenHubMsg = nil
-        lastEvenHubResendsRemaining = 0
-        evenHubQueueLock.unlock()
+        displayTickTask?.cancel()
+        displayTickTask = nil
+        displayReconcileTask?.cancel()
+        displayReconcileTask = nil
+        displayDirtySignal?.finish()
+        displayDirtySignal = nil
+    }
+
+    /// Wake the reconcile loop now (a container was just marked dirty / had sends scheduled). Cheap
+    /// and idempotent: coalesced by the stream's 1-deep buffer, so a burst of mutations yields at
+    /// most one extra wake.
+    private func signalDisplayDirty() {
+        displayDirtySignal?.yield()
     }
 
     private func sendEvenHubHeartbeat() {
@@ -1945,6 +2124,16 @@ class G2: NSObject, SGCManager {
         await sendTextWall(text)
     }
 
+    func sendPositionedText(
+        _ text: String, x: Int32, y: Int32, width: Int32, height: Int32,
+        borderWidth: Int32, borderRadius: Int32
+    ) async {
+        await sendTextAt(
+            text, x: x, y: y, width: width, height: height,
+            borderWidth: borderWidth, borderRadius: borderRadius
+        )
+    }
+
     func sendTextAt(
         _ text: String, x: Int32? = nil, y: Int32? = nil, width: Int32? = nil, height: Int32? = nil,
         borderWidth: Int32? = nil, borderColor: Int32? = nil, borderRadius: Int32? = nil,
@@ -1963,44 +2152,53 @@ class G2: NSObject, SGCManager {
         let ry = y ?? G2.defaultTextContainer.y
         let rw = width ?? G2.defaultTextContainer.width
         let rh = height ?? G2.defaultTextContainer.height
-        let borderWidth = G2.defaultTextContainer.borderWidth
-        let borderColor = G2.defaultTextContainer.borderColor
-        let borderRadius = G2.defaultTextContainer.borderRadius
-        let paddingLength = G2.defaultTextContainer.paddingLength
+        let borderWidth = borderWidth ?? G2.defaultTextContainer.borderWidth
+        let borderColor = borderColor ?? G2.defaultTextContainer.borderColor
+        let borderRadius = borderRadius ?? G2.defaultTextContainer.borderRadius
+        let paddingLength = paddingLength ?? G2.defaultTextContainer.paddingLength
         let content = text.isEmpty ? " " : text
 
-        // Reuse an existing container if the rect matches exactly; otherwise add a new one.
-        var container: TextContainer
+        // Pure state mutation: update the container's content and schedule its sends; the reconcile
+        // loop (`displayReconcileTask`) does the actual updateText writes. Reuse an existing container
+        // if the rect matches exactly; otherwise add a new one.
         if let i = textContainers.firstIndex(where: {
             $0.matches(
                 x: rx, y: ry, width: rw, height: rh, borderWidth: borderWidth,
                 borderColor: borderColor, borderRadius: borderRadius, paddingLength: paddingLength)
         }) {
             textContainers[i].content = content
-            container = textContainers[i]
-            Bridge.log(
-                "G2: sendText() - reusing container \(container.id) for rect \(rx),\(ry) \(rw)x\(rh)"
-            )
+            textContainers[i].pendingSends = 1 + EVEN_HUB_RESEND_COUNT
+            let container = textContainers[i]
+            // Wake the reconcile loop either way. When the page is live it sends the text;
+            // when the page is down the loop coalesces the burst into a single rebuild (see
+            // reconcileDisplay) instead of one shutdown/rebuild per caption. The container's
+            // content is overwritten in place (last-wins), so a backlog that piled up while
+            // iOS had us suspended collapses to one catch-up render — no flood on resume.
+            signalDisplayDirty()
             if !pageCreated {
-                await rebuildPage()
+                Bridge.log(
+                    "G2: sendText() - page down, buffering latest content for container \(container.id) (rebuild deferred to reconcile)"
+                )
                 return
             }
-            let msg = EvenHubProto.updateTextMessage(
-                containerID: container.id,
-                contentOffset: 0,
-                contentLength: Int32(container.content.utf8.count),
-                content: container.content
+            Bridge.log(
+                "G2: sendText() - reusing container \(container.id) for rect \(rx),\(ry) \(rw)x\(rh)"
             )
-            queueEvenHubCommand(msg)
             return
         }
 
-        container = addTextContainer(
+        let container = addTextContainer(
             x: rx, y: ry, width: rw, height: rh, content: content, borderWidth: borderWidth,
             borderColor: borderColor, borderRadius: borderRadius, paddingLength: paddingLength)
         Bridge.log(
             "G2: sendText() - added text container \(container.id) for rect \(rx),\(ry) \(rw)x\(rh), rebuilding page"
         )
+        // New container changes page structure: rebuild it (the rebuild embeds initial content), then
+        // schedule sends so the loop refreshes it.
+        if let j = textContainers.firstIndex(where: { $0.id == container.id }) {
+            textContainers[j].pendingSends = 1 + EVEN_HUB_RESEND_COUNT
+        }
+        signalDisplayDirty()
         await rebuildPage()
     }
 
@@ -2013,60 +2211,131 @@ class G2: NSObject, SGCManager {
 
     func clearDisplay() {
         Bridge.log("G2: clearDisplay()")
-        // Don't shutdown the EvenHub page — that kills audio streaming too.
-        // Instead, just clear the text content by sending a space.
-
-        // if !pageCreated {
-        //     Bridge.log("G2: clearDisplay() - page not created")
-        //     createPageWithContainers()
-        // }
-
-        // reset the content of all text containers to empty:
+        // Blank the text in place — do NOT shut down + rebuild the page. A teardown kills audio
+        // and triggers a firmware systemExit→recovery→rebuild; the cloud sends clearDisplay in
+        // bursts, so that turned into a rebuild storm. The reconcile loop pushes the blanked text.
         for i in textContainers.indices {
             textContainers[i].content = " "
+            textContainers[i].pendingSends = 1 + EVEN_HUB_RESEND_COUNT
         }
-        for i in imageContainers.indices {
+        for i in imageContainers.indices where !imageContainers[i].bmpData.isEmpty {
+            // The firmware still shows this container's image; emptying bmpData locally never
+            // reaches it (#3232 dropped the teardown that used to drop empty containers on
+            // rebuild). Empty + dirty tells the reconcile loop to push an all-black frame that
+            // overwrites the image on-glass — the page stays up, so no audio/mic churn.
             imageContainers[i].bmpData = Data()
+            imageContainers[i].dirty = true
         }
-        // shutdown the page and then recreate the containers without the content:
-        Task { await rebuildPage() }
+        signalDisplayDirty()
     }
 
-    /// Send BMP data to an image container via fragmented updateImageRawData
+    /// Send a bitmap to an image container as fragmented updateImageRawData packets.
+    ///
+    /// The glasses reply ONCE per fragment with an ImgResCmd ErrorCode (4=success, 5=failed).
+    /// Each fragment is sent with its own session id, then this awaits that fragment's ACK for up
+    /// to `IMG_ACK_TIMEOUT_NS` before sending the next. A `failed` ACK OR no ACK within the window
+    /// counts as a failure and the entire image is re-sent (fresh sessions) up to
+    /// `IMG_MAX_ATTEMPTS` times. On exhausting all attempts it logs a warning and returns
+    /// (best-effort — callers are unaffected).
     private func sendImageData(containerID: Int32, containerName: String, bmpData: Data) async {
         let fragmentSize = 4096
-        imageSessionCounter += 1
-        let sessionId = imageSessionCounter
         let totalSize = Int32(bmpData.count)
-        var fragmentIndex: Int32 = 0
-        var offset = 0
+        let fragmentCount = (bmpData.count + fragmentSize - 1) / fragmentSize
 
-        Bridge.log(
-            "G2: sendImageData(\(containerName)) - \(fragmentIndex) fragments, \(bmpData.count) bytes"
-        )
+        // skip if the image is empty:
+        if bmpData.count == 0 {
+            return
+        }
 
-        while offset < bmpData.count {
-            let end = min(offset + fragmentSize, bmpData.count)
-            let fragment = bmpData[offset..<end]
-
-            let msg = EvenHubProto.updateImageRawDataMessage(
-                containerID: containerID,
-                containerName: containerName,
-                mapSessionId: Int32(sessionId),
-                mapTotalSize: totalSize,
-                compressMode: 0,
-                mapFragmentIndex: fragmentIndex,
-                mapFragmentPacketSize: Int32(fragment.count),
-                mapRawData: Data(fragment)
-            )
-            sendEvenHubCommand(msg)
+        // Bridge.log(
+        //     "G2: sendImageData(\(containerName)) - \(fragmentCount) fragments, \(bmpData.count) bytes"
+        // )
 
-            fragmentIndex += 1
-            offset = end
-            try? await Task.sleep(nanoseconds: 200_000_000)  // 200ms between fragments
+        for attempt in 1...IMG_MAX_ATTEMPTS {
+            // One session id per WHOLE image transfer (per attempt). The glasses key their
+            // reassembly buffer on MapSessionId, so every fragment of this image must reuse the
+            // same session id with an incrementing MapFragmentIndex; the per-fragment ACK is
+            // correlated by the (session, fragmentIndex) pair. A retry uses a fresh session so a
+            // stale ACK from a prior attempt can't match.
+            imageSessionCounter = (imageSessionCounter + 1) % 256
+            let sessionId = imageSessionCounter
+
+            var fragmentIndex: Int32 = 0
+            var offset = 0
+            var transferOk = true
+            // if attempt > 1 {
+            //     Bridge.log("G2: sendImageData(\(containerName)) - attempt \(attempt) starting")
+            // }
+            while offset < bmpData.count {
+                let end = min(offset + fragmentSize, bmpData.count)
+                let fragment = bmpData[offset..<end]
+
+                let msg = EvenHubProto.updateImageRawDataMessage(
+                    containerID: containerID,
+                    containerName: containerName,
+                    mapSessionId: Int32(sessionId),
+                    mapTotalSize: totalSize,
+                    compressMode: 0,
+                    mapFragmentIndex: fragmentIndex,
+                    mapFragmentPacketSize: Int32(fragment.count),
+                    mapRawData: Data(fragment)
+                )
+                // Send the fragment directly: the reconcile loop already serializes whole image
+                // sends, and the per-fragment ACK gate below provides pacing — no transmit queue.
+                sendEvenHubCommand(msg)
+                // Bridge.log("G2: img_sen: session=\(sessionId) fragment=\(fragmentIndex)")
+
+                // Gate on THIS fragment's ACK before sending the next (the ACK provides pacing).
+                // Timeout/img_failed → abandon the attempt and retry the whole image.
+                let ok = await awaitImageAck(sessionId: sessionId, fragmentIndex: fragmentIndex)
+                if !ok {
+                    Bridge.log(
+                        "G2: img_sen: session=\(sessionId) fragment=\(fragmentIndex) failed"
+                    )
+                    transferOk = false
+                    break
+                }
+
+                fragmentIndex += 1
+                offset = end
+            }
+
+            if transferOk {
+                // Bridge.log("G2: img_sen: container=\(containerName) - success=true")
+                return
+            }
+        }
+
+        Bridge.log("G2: img_sen: container=\(containerName) - failed after \(IMG_MAX_ATTEMPTS) attempts")
+    }
+
+    /// Suspend until correlateImageAck() resolves the ACK for this `(sessionId, fragmentIndex)`, or
+    /// `IMG_ACK_TIMEOUT_NS` elapses (whichever comes first). Returns whether the fragment was acked
+    /// successfully; a timeout returns false. All fragments of one image share a session id, so the
+    /// fragment index distinguishes their ACKs. The continuation lives in [ImgAckBox], whose lock
+    /// makes the ACK-resolve and the timeout mutually exclusive — exactly one resumes it.
+    private func awaitImageAck(sessionId: Int, fragmentIndex: Int32) async -> Bool {
+        let timeoutNs = IMG_ACK_TIMEOUT_NS
+        let box = imgAckBox
+        return await withCheckedContinuation { (cont: CheckedContinuation<Bool, Never>) in
+            box.arm(session: sessionId, fragment: fragmentIndex, cont: cont)
+
+            // Detached (not @MainActor): the timeout must fire on its own schedule regardless of how
+            // busy the main actor is. The box's lock makes racing with resolve() safe.
+            Task.detached {
+                try? await Task.sleep(nanoseconds: timeoutNs)
+                box.timeout(session: sessionId, fragment: fragmentIndex)
+            }
         }
     }
 
+    /// Resume the pending image-ACK continuation for `(session, fragmentIndex)` (if it matches the
+    /// in-flight one). Idempotent via [ImgAckBox]: a duplicate L/R ACK or the timeout can't resume
+    /// the same continuation twice. Safe to call from any thread (the BLE callback queue).
+    private nonisolated func completeImageAck(session: Int, fragmentIndex: Int32, success: Bool) {
+        imgAckBox.resolve(session: session, fragment: fragmentIndex, success: success)
+    }
+
     /// Display a bitmap inside a positioned image container.
     ///
     /// The page keeps a live list of up to 4 image containers keyed by exact rect:
@@ -2080,6 +2349,9 @@ class G2: NSObject, SGCManager {
         base64ImageData: String, x: Int32? = nil, y: Int32? = nil, width: Int32? = nil,
         height: Int32? = nil
     ) async -> Bool {
+        // Pure state mutation: update the target container's bytes and mark it dirty. The reconcile
+        // loop (`displayReconcileTask`) is the sole sender, so two displayBitmap calls can never
+        // overlap a `sendImageData` and clobber the single-slot imgAckBox — no lock needed.
         let rx = x ?? G2.defaultImgContainer.x
         let ry = y ?? G2.defaultImgContainer.y
         let rw = width ?? G2.defaultImgContainer.width
@@ -2105,33 +2377,117 @@ class G2: NSObject, SGCManager {
         }
 
         // Reuse an existing container if the rect matches exactly; otherwise add a new one.
-        var container: ImgContainer
         if let i = imageContainers.firstIndex(where: {
             $0.matches(x: rx, y: ry, width: rw, height: rh)
         }) {
             imageContainers[i].bmpData = bmpData
-            container = imageContainers[i]
+            imageContainers[i].dirty = true
+            signalDisplayDirty()
+            let container = imageContainers[i]
             Bridge.log(
                 "G2: displayBitmap() - reusing container \(container.id) for rect \(rx),\(ry) \(rw)x\(rh)"
             )
+            // A brand-new page needs its structure built before the loop can push pixels; the dirty
+            // flag stays set so the reconcile loop sends the image once the page exists.
             if !pageCreated {
                 await rebuildPage()
-                return true
             }
-            await sendImageData(
-                containerID: container.id, containerName: container.name, bmpData: container.bmpData
-            )
-            return true
         } else {
-            container = addImageContainer(x: rx, y: ry, width: rw, height: rh, bmpData: bmpData)
+            let container = addImageContainer(x: rx, y: ry, width: rw, height: rh, bmpData: bmpData)
+            if let j = imageContainers.firstIndex(where: { $0.id == container.id }) {
+                imageContainers[j].dirty = true
+            }
+            signalDisplayDirty()
             Bridge.log(
                 "G2: displayBitmap() - added container \(container.id) for rect \(rx),\(ry) \(rw)x\(rh), rebuilding page"
             )
+            // New container changes page structure: rebuild it, then the loop sends the pixels.
             await rebuildPage()
         }
         return true
     }
 
+    /// Push pending display state to the glasses: dirty text containers first (one updateText each,
+    /// with a redundant resend per `pendingSends`), then dirty image containers one at a time. The
+    /// loop awaits this, and this awaits each `sendImageData` in turn, so image sends never overlap
+    /// and `imgAckBox` is never clobbered. A failed image send leaves the container dirty for the
+    /// next cycle; if its bytes changed mid-send, the flag stays set so the newer image is sent next.
+    private func reconcileDisplay() async {
+        // Page is dead but content is waiting (e.g. captions kept arriving while iOS had us
+        // suspended and the firmware tore the session down). Rebuild the page ONCE here — the
+        // reconcile loop is coalesced (1-deep signal buffer), so a burst of buffered sendText
+        // calls collapses into a single rebuild instead of one shutdown/rebuild per caption.
+        // rebuildState() recreates the page, re-pushes the current text/image, and re-arms the
+        // mic iff intent says so. Skip while the native dashboard owns the screen.
+        if !pageCreated {
+            let useNativeDashboard =
+                DeviceStore.shared.get("bluetooth", "use_native_dashboard") as? Bool ?? false
+            // Only resurrect a dead page for non-blank content — don't rebuild just to render a
+            // clearDisplay's blank, or a clear burst churns the page back up pointlessly.
+            let hasPendingText = textContainers.contains {
+                $0.pendingSends > 0 && $0.content.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false
+            }
+            let hasPendingImage = imageContainers.contains { $0.dirty && !$0.bmpData.isEmpty }
+            if (hasPendingText || hasPendingImage) && !(useNativeDashboard && dashboardShowing > 0) {
+                Bridge.log("G2: reconcileDisplay() - page down with pending content, rebuilding once")
+                await rebuildState()
+            }
+            return
+        }
+
+        // Text: synchronous, no ACK. Send one update per container with pending sends and decrement.
+        for i in textContainers.indices where textContainers[i].pendingSends > 0 {
+            let container = textContainers[i]
+            let msg = EvenHubProto.updateTextMessage(
+                containerID: container.id,
+                contentOffset: 0,
+                contentLength: Int32(container.content.utf8.count),
+                content: container.content
+            )
+            sendEvenHubCommand(msg)
+            textContainers[i].pendingSends -= 1
+        }
+
+        // Images: ACK-gated, exactly one in flight. Cap iterations defensively so a container that
+        // keeps being re-dirtied mid-send can't spin this pass forever (next tick picks it up).
+        var guardCount = 0
+        while pageCreated, guardCount < imageContainerIDPool.count,
+            let i = imageContainers.firstIndex(where: { $0.dirty })
+        {
+            guardCount += 1
+            let container = imageContainers[i]
+            let sentBytes = container.bmpData
+            // Empty + dirty means "just cleared": the firmware still shows the old image, so push an
+            // all-black frame sized to the container to overwrite it on-glass (the page stays up — no
+            // teardown, no mic churn). A container only reaches here when dirty, and clearDisplay is
+            // the sole source of an empty-but-dirty container, so this fires exactly on a clear.
+            if sentBytes.isEmpty {
+                if let blank = blankBmp(width: Int(container.width), height: Int(container.height)) {
+                    await sendImageData(
+                        containerID: container.id, containerName: container.name, bmpData: blank
+                    )
+                }
+                // Only settle the flag if it's still empty — a displayBitmap during the await would
+                // have set new bytes, so leave it dirty for the next pass to send the real image.
+                if let j = imageContainers.firstIndex(where: { $0.id == container.id }),
+                    imageContainers[j].bmpData.isEmpty
+                {
+                    imageContainers[j].dirty = false
+                }
+                continue
+            }
+            await sendImageData(
+                containerID: container.id, containerName: container.name, bmpData: sentBytes
+            )
+            // Re-find by id: the array may have shifted (eviction) during the await.
+            if let j = imageContainers.firstIndex(where: { $0.id == container.id }),
+                imageContainers[j].bmpData == sentBytes
+            {
+                imageContainers[j].dirty = false
+            }
+        }
+    }
+
     /// Add a new image container for `rect`, evicting the oldest when the list is full (max 4).
     /// Returns the newly tracked container (with an assigned ID from the pool).
     private func addImageContainer(x: Int32, y: Int32, width: Int32, height: Int32, bmpData: Data)
@@ -2176,44 +2532,69 @@ class G2: NSObject, SGCManager {
         let msg = EvenHubProto.shutdownMessage()
         sendEvenHubCommand(msg)
         pageCreated = false
-        await rebuildState()
+        try? await Task.sleep(nanoseconds: 300_000_000)// 300ms to settle
+        // we will automatically rebuild state when we detect the glasses shutdown:
+        // await rebuildState()
     }
 
-    // re-creates the containers and sends all images and text again to the glasses:
+    // re-creates the containers and re-sends all images to the glasses:
     private func rebuildState() async {
         Bridge.log("G2: rebuildState()")
-        // recreate the containers:
+        // recreate the containers (sets pageCreated = true; embeds text content directly):
         createPageWithContainers()
 
         try? await Task.sleep(nanoseconds: 300_000_000)  // 300ms to settle
-        // send any image containers we have
-        // go through each container and send the data:
-        for container in imageContainers {
+        // Mark every image container dirty and let the reconcile loop re-send them, one at a time.
+        // Doing the sends here directly is what used to race a concurrent displayBitmap and clobber
+        // imgAckBox; routing through the dirty flag keeps a single sender (see displayReconcileTask).
+        // Text needs no resend here: createPageWithContainers already embeds each container's content.
+        for i in imageContainers.indices where !imageContainers[i].bmpData.isEmpty {
             Bridge.log(
-                "G2: rebuildState() - sending image data to container \(container.id), \(container.bmpData.count) bytes"
-            )
-            await sendImageData(
-                containerID: container.id, containerName: container.name, bmpData: container.bmpData
+                "G2: rebuildState() - marking container \(imageContainers[i].id) dirty (\(imageContainers[i].bmpData.count) bytes)"
             )
-            try? await Task.sleep(nanoseconds: 300_000_000)  // 300ms between containers
+            imageContainers[i].dirty = true
         }
+        signalDisplayDirty()
 
-        // go through each text container and send the data:
-        // disabled because text containers are initialized with their content:
-        // for container in textContainers {
-        //     let msg = EvenHubProto.updateTextMessage(
-        //         containerID: container.id,
-        //         contentOffset: 0,
-        //         contentLength: Int32(container.content.utf8.count),
-        //         content: container.content
-        //     )
-        //     sendEvenHubCommand(msg)
-        // }
-        
         try? await Task.sleep(nanoseconds: 300_000_000)  // 300ms to settle
         restartMicIfAlreadyEnabled()
     }
 
+    /// Single coalesced recovery: rebuild the page + re-arm the mic from intent, but never
+    /// stack rebuilds. The firmware spams systemExit/dashboard-close ~1×/sec; without this
+    /// guard each one triggered a rebuild that was torn down again → rebuild→exit→rebuild
+    /// storm. At most one rebuild in flight, and at most one per RECOVERY_DEBOUNCE_MS.
+    private func recoverPageAndMic(reason: String) {
+        let now = Int64(Date().timeIntervalSince1970 * 1000)
+        // If the page is already alive and the mic matches intent, there's nothing to recover —
+        // this is a spurious/phantom firmware event (it spams close/exit even when our page is
+        // healthy). Rebuilding here is what created the churn, so skip it.
+        let micIntent = DeviceStore.shared.get("glasses", "micEnabled") as? Bool ?? false
+        if pageCreated && evenHubMicActive == micIntent {
+            // Bridge.log("G2: recover(\(reason)) skipped — page alive, mic matches intent")
+            return
+        }
+        if recoveryInFlight {
+            // Bridge.log("G2: recover(\(reason)) skipped — already in flight")
+            return
+        }
+        if now - lastRecoveryRebuildMs < RECOVERY_DEBOUNCE_MS {
+            // Bridge.log("G2: recover(\(reason)) skipped — debounced")
+            return
+        }
+        recoveryInFlight = true
+        lastRecoveryRebuildMs = now
+        Bridge.log("G2: recover(\(reason)) — rebuilding EvenHub page")
+        Task { [weak self] in
+            guard let self = self else { return }
+            await self.rebuildState()
+            // Reconcile against DeviceManager's authoritative current view so the glasses
+            // match the phone, not just the last-cached G2 containers.
+            DeviceManager.shared.sendCurrentState()
+            self.recoveryInFlight = false
+        }
+    }
+
     /// Upscale BMP pixel data by 2x (200x100 → 400x200) using nearest-neighbor
     private func upscaleBmp2x(_ bmpData: Data, srcWidth: Int, srcHeight: Int) -> Data? {
         // Parse the BMP to extract pixel data, then rebuild at 2x
@@ -2363,6 +2744,15 @@ class G2: NSObject, SGCManager {
         return bmp
     }
 
+    /// Build an all-black BMP sized to a container. Sent to overwrite (and thus visually clear) an
+    /// image container without tearing the page down — on the green monochrome display, pixel 0 is
+    /// unlit, so an all-zero frame reads as blank. Used by the reconcile loop to clear a bitmap.
+    private func blankBmp(width: Int, height: Int) -> Data? {
+        guard width > 0, height > 0 else { return nil }
+        let zeros = Data(count: width * height)  // all-zero 8-bit grayscale = black
+        return build4BitBmp(grayscalePixels: zeros, width: width, height: height)
+    }
+
     /// Build a 4-bit indexed BMP file from 8-bit grayscale pixel data.
     /// BMP rows are stored bottom-up. Each row is padded to a 4-byte boundary.
     private func build4BitBmp(grayscalePixels: Data, width: Int, height: Int) -> Data? {
@@ -2442,10 +2832,14 @@ class G2: NSObject, SGCManager {
     /// The glasses fall back to the dashboard automatically when no page is up.
     func showDashboard() {
         Bridge.log("G2: showDashboard()")
-        dashboardShowing += 2
+        // Dashboard is open: a 0/1 flag (the old +=2/-=1 depth dance drifted >0 and wedged the
+        // mic). dashboardOpening latches so the open-confirm 08011A00 doesn't trigger recovery.
+        dashboardShowing = 1
+        dashboardOpening = true
         let msg = EvenHubProto.shutdownMessage()
         sendEvenHubCommand(msg)
         pageCreated = false
+        evenHubMicActive = false  // dashboard takes EvenHub focus; firmware kills the mic
         currentBitmapBase64 = ""
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
             guard let self = self else { return }
@@ -2662,32 +3056,6 @@ class G2: NSObject, SGCManager {
         pageCreated = true
     }
 
-    private func queueEvenHubCommand(_ payload: Data) {
-        evenHubQueueLock.lock()
-        pendingTextMsg = payload
-        evenHubQueueLock.unlock()
-    }
-
-    private func drainEvenHubQueue() {
-        evenHubQueueLock.lock()
-        let msg = pendingTextMsg
-        pendingTextMsg = nil
-        let toSend: Data?
-        if let msg = msg {
-            lastEvenHubMsg = msg
-            lastEvenHubResendsRemaining = EVEN_HUB_RESEND_COUNT
-            toSend = msg
-        } else if lastEvenHubResendsRemaining > 0, let last = lastEvenHubMsg {
-            lastEvenHubResendsRemaining -= 1
-            toSend = last
-        } else {
-            toSend = nil
-        }
-        evenHubQueueLock.unlock()
-        guard let toSend = toSend else { return }
-        sendEvenHubCommand(toSend)
-    }
-
     private func restartMicIfAlreadyEnabled() {
         let currentEnabled = DeviceStore.shared.get("glasses", "micEnabled") as? Bool ?? false
         if currentEnabled {
@@ -2696,8 +3064,10 @@ class G2: NSObject, SGCManager {
     }
 
     func restartMic() {
-        // if already enabled, set to disabled, then send enabled after 500ms:
+        // Intent is "mic on". The mic only exists inside a live EvenHub page, so we
+        // toggle it off then back on (the firmware needs the off→on edge to re-arm).
         DeviceStore.shared.apply("glasses", "micEnabled", true)
+        evenHubMicActive = false
         let msg = EvenHubProto.audioControlMessage(enable: false)
         sendEvenHubCommand(msg)
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
@@ -2705,14 +3075,24 @@ class G2: NSObject, SGCManager {
             let useNativeDashboard =
                 DeviceStore.shared.get("bluetooth", "use_native_dashboard") as? Bool ?? false
             // Bridge.log("G2: setMicEnabled - useNativeDashboard=\(useNativeDashboard), dashboardShowing=\(dashboardShowing)")
+            // Dashboard owns the screen + session right now — don't arm the mic into a
+            // page the dashboard has taken over; recovery re-arms on dashboard close.
             if useNativeDashboard && dashboardShowing > 0 {
                 return
             }
-            if !pageCreated {
-                DeviceManager.shared.sendCurrentState()  // should re-create the page if needed
+            // Never send audioControl(enable:true) without a live page — no page means no
+            // mic. Rebuild first, which itself re-arms the mic at the end (intent is on),
+            // so we're done.
+            if !self.pageCreated {
+                Task { [weak self] in
+                    await self?.rebuildState()
+                    DeviceManager.shared.sendCurrentState()
+                }
+                return
             }
             let msg = EvenHubProto.audioControlMessage(enable: true)
             self.sendEvenHubCommand(msg)
+            self.evenHubMicActive = true
         }
     }
 
@@ -2720,8 +3100,12 @@ class G2: NSObject, SGCManager {
 
     func setMicEnabled(_ enabled: Bool) {
         Bridge.log("G2: setMicEnabled(\(enabled))")
+        if enabled && !pageCreated {
+            restartMic()
+            return
+        }
         let currentEnabled = DeviceStore.shared.get("glasses", "micEnabled") as? Bool ?? false
-        if currentEnabled && enabled {
+        if enabled && currentEnabled {
             restartMic()
             return
         }
@@ -2729,6 +3113,7 @@ class G2: NSObject, SGCManager {
         DeviceStore.shared.apply("glasses", "micEnabled", enabled)
         let msg = EvenHubProto.audioControlMessage(enable: enabled)
         sendEvenHubCommand(msg)
+        evenHubMicActive = enabled
     }
 
     func sortMicRanking(list: [String]) -> [String] {
@@ -2790,6 +3175,8 @@ class G2: NSObject, SGCManager {
             centralManager?.cancelPeripheralConnection(peripheral)
         }
 
+        leftWriteQueue.removeAll()
+        rightWriteQueue.removeAll()
         leftInitialized = false
         rightInitialized = false
         authStarted = false
@@ -2798,6 +3185,7 @@ class G2: NSObject, SGCManager {
         startupPageCreated = false
         pageCreated = false
         dashboardShowing = 0
+        dashboardOpening = false
         heartbeatCounter = 0
         DeviceStore.shared.apply("glasses", "connected", false)
         DeviceStore.shared.apply("glasses", "fullyBooted", false)
@@ -2963,6 +3351,7 @@ class G2: NSObject, SGCManager {
         // } else {
         //     stopCompass()
         // }
+        Task { await runAuthSequence() }
     }
 
     /// Start a navigation session so the glasses stream compass heading via
@@ -3155,6 +3544,7 @@ class G2: NSObject, SGCManager {
     func sendButtonPhotoSettings() {}
     func sendButtonVideoRecordingSettings() {}
     func sendButtonMaxRecordingTime() {}
+    func sendButtonCameraLedSetting() {}
 
     func sendCameraFovSetting() {}
 
@@ -3442,6 +3832,15 @@ class G2: NSObject, SGCManager {
         var reader = ProtobufReader(payload)
         let fields = reader.parseFields()
 
+
+        let payloadStr = "\(payload.map { String(format: "%02X", $0) }.joined())"
+        if payloadStr.contains("080C7A02100C") {
+            // heartbeat response
+            return
+        }
+
+        // Bridge.log("G2: hub_res: payload=\(payload.map { String(format: "%02X", $0) }.joined())")
+
         guard let cmdValue = fields[1] as? Int32 else {
             Bridge.log(
                 "G2: EvenHub response - no cmd field, \(payload.count) bytes: \(payload.map { String(format: "%02X", $0) }.joined())"
@@ -3449,7 +3848,6 @@ class G2: NSObject, SGCManager {
             return
         }
 
-        // Bridge.log("G2: EvenHub incoming cmd=\(cmdValue), fields=\(Array(fields.keys).sorted())")
 
         if cmdValue == EvenHubResponseCmd.osNotifyEventToApp.rawValue {
             // Touch/gesture event from glasses
@@ -3492,6 +3890,10 @@ class G2: NSObject, SGCManager {
             }
         } else {
 
+            // NOTE: the per-fragment image ACK is correlated inline on the BLE callback queue in
+            // correlateImageAck() (called from didUpdateValueFor before this is dispatched to the
+            // main actor) so it is never delayed behind a saturated main actor. Nothing to do here.
+
             // response codes:
             let timestamp = Int64(Date().timeIntervalSince1970 * 1000)
             if lastEvenHubResponseTimestamp != nil
@@ -3520,16 +3922,17 @@ class G2: NSObject, SGCManager {
                                 "G2: WARN: Glasses shutdown our EvenHub page — resetting page state"
                             )
                             pageCreated = false
+                            evenHubMicActive = false  // mic dies with the page
                         }
                     }
-                    if let errorCode = resFields[8] as? Int32 {
-                        // ImgResCmd has ErrorCode in field 8
-                        if errorCode == 4 {
-                            Bridge.log("G2: img_success")
-                        } else {
-                            Bridge.log("G2: EvenHub ImgRes errorCode=\(errorCode)")
-                        }
-                    }
+                    // if let errorCode = resFields[8] as? Int32 {
+                    //     // ImgResCmd has ErrorCode in field 8
+                    //     if errorCode == 4 {
+                    //         Bridge.log("G2: img_success")
+                    //     } else {
+                    //         Bridge.log("G2: EvenHub ImgRes errorCode=\(errorCode)")
+                    //     }
+                    // }
                 }
             }
 
@@ -3537,6 +3940,7 @@ class G2: NSObject, SGCManager {
             if cmdValue == 9 || cmdValue == 10 {
                 Bridge.log("G2: ERROR: Glasses shutdown our EvenHub page — resetting page state")
                 pageCreated = false
+                evenHubMicActive = false  // mic dies with the page
             }
         }
     }
@@ -3696,23 +4100,15 @@ class G2: NSObject, SGCManager {
             //     Bridge.log("G2: Click detected")
             // }
 
-            // System exit: glasses killed our EvenHub page (user opened menu or another app)
-            // Reset page state and re-create the page to reclaim EvenHub focus
+            // System exit: the firmware killed our page (and the mic). ONLY mark state dead;
+            // do NOT rebuild here. systemExit is fired alongside the dashboard-close (08011A00)
+            // event for the same transition — if both rebuilt, the fresh page gets torn down
+            // again → rebuild→exit→rebuild loop. Recovery is owned by one place: the
+            // dashboard-close handler (and the reconcile page-down path). Don't touch
+            // micEnabled (user intent) — recovery reads it to re-arm; clobbering it strands the mic.
             if eventType == .systemExit || eventType == .abnormalExit {
-                // Bridge.log("G2: System exit detected")
                 pageCreated = false
-                // Firmware kills the mic on system exit; re-arm it if it should be on
-                DeviceStore.shared.apply("glasses", "micEnabled", false)
-                DeviceManager.shared.updateMicState()
-                // Force re-create the page to reclaim EvenHub focus
-                // Task {
-                //     try? await Task.sleep(nanoseconds: 1_000_000_000)  // 1000ms for glasses to finish transition
-                //     if !savedBitmap.isEmpty {
-                //         await self.displayBitmap(base64ImageData: savedBitmap)
-                //     } else {
-                //         self.sendTextWall(savedText.isEmpty ? " " : savedText)
-                //     }
-                // }
+                evenHubMicActive = false  // firmware killed the mic with the page
             }
             return
         }
@@ -4024,46 +4420,21 @@ class G2: NSObject, SGCManager {
         }
         lastGestureCtrlTimestamp = timestamp
 
-        // if we got 08011A00 that means we closed the dashboard, which means the mic is probably dead,
-        // so we need to revive it:
+        // 08011A00 is the dashboard open/close toggle. It fires on BOTH transitions, so we use
+        // the dashboardOpening latch (set by showDashboard) to tell them apart:
+        //   • First event after showDashboard → the OPEN confirm. Consume it, keep the dashboard
+        //     up, and do NOT recover (recovering would rebuild our page and snatch the screen back
+        //     — that's the "double-tap makes captions flicker but never opens the dashboard" bug).
+        //   • Next event → the real CLOSE. Reset state and recover our page + mic.
         if data == Data([0x08, 0x01, 0x1A, 0x00]) {
-            Bridge.log("G2: dashboard closed / shutdown - dashboardShowing=\(dashboardShowing)")
-            let useNativeDashboard =
-                DeviceStore.shared.get("bluetooth", "use_native_dashboard") as? Bool ?? false
-            if !useNativeDashboard {
-                dashboardShowing = 0
-                // rebuild state:
-                Task {
-                    await rebuildState()
-                    // set the mic back on if it should be on
-                    let micEnabled =
-                        DeviceStore.shared.get("glasses", "micEnabled") as? Bool ?? false
-                    if micEnabled {
-                        restartMic()
-                    }
-                }
+            Bridge.log("G2: dashboard toggle - dashboardShowing=\(dashboardShowing) opening=\(dashboardOpening)")
+            if dashboardOpening {
+                dashboardOpening = false  // open confirmed; dashboard now owns the screen
                 return
-            } else {
-                // if we aren't trying to show the dashboard
-                // then we need to turn the mic back on and display the mentra main page:
-                if dashboardShowing <= 1 {
-                    dashboardShowing = 0
-                    // rebuild state:
-                    await rebuildState()
-                    // set the mic back on if it should be on
-                    let micEnabled =
-                        DeviceStore.shared.get("glasses", "micEnabled") as? Bool ?? false
-                    if micEnabled {
-                        restartMic()
-                    }
-                    return
-                }
-                // do nothing this time since we just closed the dashboard
-                dashboardShowing -= 1
-                if dashboardShowing < 0 {
-                    dashboardShowing = 0
-                }
             }
+            dashboardShowing = 0
+            recoverPageAndMic(reason: "dashboard-close")
+            return
         }
 
         // if we got 08011097012200 that means we selected a menu item:
@@ -4258,6 +4629,8 @@ extension G2: CBCentralManagerDelegate {
             // Clear both sides to force re-discovery (like G1)
             self.leftPeripheral = nil
             self.rightPeripheral = nil
+            self.leftWriteQueue.removeAll()
+            self.rightWriteQueue.removeAll()
             self.leftInitialized = false
             self.rightInitialized = false
             self.leftWriteChar = nil
@@ -4271,6 +4644,7 @@ extension G2: CBCentralManagerDelegate {
             self.startupPageCreated = false
             self.pageCreated = false
             self.dashboardShowing = 0
+            self.dashboardOpening = false
             DeviceStore.shared.apply("glasses", "connected", false)
             DeviceStore.shared.apply("glasses", "fullyBooted", false)
 
@@ -4390,6 +4764,14 @@ extension G2: CBPeripheralDelegate {
     ) {
         guard let data = characteristic.value, error == nil else { return }
 
+        // Correlate an in-flight image-fragment ACK INLINE on the BLE callback queue, before hopping
+        // to the main actor. This keeps the ACK that sendImageData() awaits from being starved by a
+        // saturated main actor (packet burst / heartbeats / text-queue tick) — the cause of the
+        // intermittent "glasses stopped responding to image sends". See [ImgAckBox].
+        if characteristic.uuid == G2BLE.CHAR_NOTIFY {
+            correlateImageAck(data)
+        }
+
         Task { @MainActor [weak self] in
             guard let self = self else { return }
 
@@ -4403,6 +4785,50 @@ extension G2: CBPeripheralDelegate {
         }
     }
 
+    /// Read-only, SINGLE-PACKET parse of a raw notify frame that resolves an in-flight image ACK
+    /// directly (off the main actor). Does NOT touch the stateful `receiveManager` (main-actor only):
+    /// an ImgResCmd always fits in one BLE packet, so any multi-packet frame is left to the
+    /// main-thread path. Idempotent via [ImgAckBox], so the residual main-thread correlation and the
+    /// duplicate L/R ACK are both harmless.
+    nonisolated func correlateImageAck(_ rawData: Data) {
+        guard rawData.count >= 8 else { return }
+        let b = { (i: Int) -> UInt8 in rawData[rawData.startIndex + i] }
+        guard b(0) == G2BLE.HEADER_BYTE else { return }
+
+        let payloadLen = Int(b(3))
+        let expectedLen = payloadLen + 8
+        guard rawData.count >= expectedLen else { return }
+
+        let totalPackets = Int(b(4))
+        let serialNum = Int(b(5))
+        let serviceId = b(6)
+        let resultCode = (Int(b(7)) >> 1) & 0x0F
+        guard resultCode == 0 else { return }
+        guard serviceId == ServiceID.evenHub.rawValue else { return }
+        // Single complete packet only (ImgResCmd never spans packets).
+        guard totalPackets == 1, serialNum == 1 else { return }
+
+        // Strip the 2-byte CRC trailer on the (last == only) packet.
+        let payloadEnd = 8 + payloadLen - 2
+        guard payloadEnd >= 8, payloadEnd <= rawData.count else { return }
+        let payload = rawData.subdata(in: (rawData.startIndex + 8)..<(rawData.startIndex + payloadEnd))
+
+        var reader = ProtobufReader(payload)
+        let fields = reader.parseFields()
+        guard let resData = fields[6] as? Data else { return }  // field 6 = ImgResCmd
+        var resReader = ProtobufReader(resData)
+        let resFields = resReader.parseFields()
+        guard let errorCode = resFields[8] as? Int32,
+            let ackSession = resFields[3] as? Int32
+        else { return }
+        let ackFragment = (resFields[6] as? Int32) ?? 0
+        Bridge.log(
+            "G2: img_res: session=\(ackSession) fragment=\(ackFragment) errorCode=\(errorCode) success=\(errorCode == 4)"
+        )
+        completeImageAck(
+            session: Int(ackSession), fragmentIndex: ackFragment, success: errorCode == 4)
+    }
+
     nonisolated func peripheral(
         _: CBPeripheral, didWriteValueFor _: CBCharacteristic, error: Error?
     ) {
@@ -4412,4 +4838,18 @@ extension G2: CBPeripheralDelegate {
             }
         }
     }
+
+    /// CoreBluetooth's write-without-response buffer freed up. The paced drainer doesn't depend on
+    /// this (it's suppressed in the background), but in the foreground it's a cheap nudge to make
+    /// sure a drainer is running for that side.
+    nonisolated func peripheralIsReady(toSendWriteWithoutResponse peripheral: CBPeripheral) {
+        Task { @MainActor [weak self] in
+            guard let self = self else { return }
+            if peripheral === self.rightPeripheral {
+                self.startDrain(right: true)
+            } else if peripheral === self.leftPeripheral {
+                self.startDrain(right: false)
+            }
+        }
+    }
 }