@mentra/glasses-media 3.2.0-dev.265 → 3.2.1-beta.312

package/README.md

@@ -37,15 +37,22 @@ Before merging/releasing, exercise iPhone + glasses: first-use local-network per
 `PhoneStreamCoordinator` provisions Cloudflare and owns subscribers for the entire route:
 
 ```text
-Glasses -- WHIP over SoftAP --> shared receiver -- decoded video/PCM --> phone WHIP publisher --> Cloudflare
+Glasses -- video-only WHIP over SoftAP --> shared receiver --> phone WHIP publisher --> Cloudflare
+Glasses MCU -- BLE LC3 --> phone PCM decoder ----------------------^
 ```
 
 Only `ingest: "whip"` selects this route. Default SRT and explicit RTMP continue publishing directly from the glasses. WHIP never falls back to SRT/RTMP when Cloudflare omits its WHIP URL. The phone needs mobile data; the glasses need no internet Wi-Fi credentials. Livestreamer's Stream Here path skips its glasses Wi-Fi setup gate accordingly.
 
 `MentraGlassesMediaRelay.prepare` joins the persistent hotspot, prepares both native peers, and returns a local WHIP URL for the BLE start command. Cloudflare credentials stay on the phone. Video queues hold at most one frame; decoded PCM is downmixed/resampled into a bounded 200ms, 48kHz mono queue. WebRTC re-encodes both tracks. No phone microphone is captured. Android uses the WebRTC library's external AudioRecord buffer mode; iOS uses a custom `RTCAudioDevice`.
 
+On Android hosts with microphone pinning and native PCM input, managed streams use the same BLE LC3 capture path as ACS SoftAP calls. An engine-owned `livestream` microphone session requests continuous glasses PCM; it leaves the configured gain in force and disables the call-specific loudness gate. The glasses receive `captureAudio: false`, avoiding SoC microphone capture and audio encoding, while the phone publishes video plus LC3-derived audio to Cloudflare. Attempt-scoped callbacks and native PCM gating reject late audio after stop/retry. Explicit `captureAudio: false` disables audio entirely. iOS and older hosts retain WHIP audio, matching ACS capability gating. ACS's measured 170ms audio delay is specific to its outgoing pipeline and is not applied to the Cloudflare publisher without calibration.
+
 Android's process-wide network inventory exposes both the scoped hotspot and real cellular handles during a relay. Per-factory masks keep the receiver on Wi-Fi and the publisher off Wi-Fi; signaling also uses the cellular network's socket factory and DNS. ACS retains its existing hotspot-only inventory. iOS uses corresponding per-factory masks after validating the cellular default route.
 
+The iOS internet publisher posts its offer on the first server-reflexive candidate, complete ICE gathering, or a 1.5-second gather deadline, matching the glasses publisher's STUN policy. It posts once and ignores late triggers after stop. The local SoftAP receiver still waits for complete host-only gathering. Incident logs record the outgoing negotiation stage, candidate counts, HTTP result and first decoded video frame without SDP or publish credentials.
+
+Android temporarily lifts the cellular process pin while creating the local WHIP listener, then restores it before starting the outgoing publisher. Otherwise the listener inherits the cellular socket mark and cannot reply to the glasses. The outgoing audio callback supplies its own PCM frame clock: WebRTC's external-recording mode does not pace callbacks and reports zero captured bytes, so the callback fills the entire buffer and waits for the next frame interval without opening the phone microphone.
+
 An attempt-specific ID isolates late callbacks and glasses status. Reconnect tears down the glasses publisher, both phone peers and hotspot before rebuilding against the same provisioned input. Three retries bound consecutive failures; a minute of stable streaming renews the retry budget. Last-subscriber stop cancels startup/backoff, awaits native cleanup and disables the hotspot. Failed cleanup retains ownership and can be retried by stop. BLE-unreachable stop/hotspot commands are deferred until reconnection. ACS and managed streaming share a hotspot reservation. Native media queues keep running when the UI is backgrounded; Android holds a partial wake lock and uses the engine's background timers for retry/readiness.
 
 Device qualification for this outgoing pipeline must include Android and iPhone: audio/video playback on the provisioned WHEP URL, mute/video-only capture, last-subscriber stop, cancellation at each setup step, cellular/hotspot/BLE loss and recovery, repeated starts, screen-off/background operation and a sustained thermal/audio-sync run. Unit tests and platform compilation cover lifecycle/format contracts; they do not establish those hardware results.

package/android/src/main/java/com/mentra/glassesmedia/GlassesMediaRelayModule.kt

@@ -5,8 +5,11 @@ import android.os.Handler
 import android.os.Looper
 import android.os.PowerManager
 import android.provider.Settings
+import android.util.Base64
+import android.util.Log
 import com.mentra.glassesmedia.network.*
 import com.mentra.glassesmedia.publisher.PhoneWhipPublisher
+import com.mentra.glassesmedia.publisher.RelayPcmInput
 import com.mentra.glassesmedia.source.*
 import expo.modules.kotlin.Promise
 import expo.modules.kotlin.modules.Module
@@ -22,6 +25,7 @@ class GlassesMediaRelayModule : Module() {
   private var source: LocalWhipIngestSource? = null
   private var publisher: PhoneWhipPublisher? = null
   private var wakeLock: PowerManager.WakeLock? = null
+  private val pcmInput = RelayPcmInput()
 
   override fun definition() = ModuleDefinition {
     Name("MentraGlassesMediaRelay")
@@ -64,14 +68,21 @@ class GlassesMediaRelayModule : Module() {
           val outgoing = PhoneWhipPublisher(context, endpoint, options["captureAudio"] != false,
             (options["bitrate"] as? Number)?.toInt() ?: 2_000_000) { state, reason -> emit(id, state, reason) }
           publisher = outgoing
+          val bleAudio = options["captureAudio"] != false && options["audioTransport"] == "ble-lc3"
+          if (bleAudio) pcmInput.attach(id, outgoing::onPcm)
+          Log.i("ManagedRelay", "Audio transport=${options["audioTransport"] ?: "whip"} attempt=$id")
           val incoming = LocalWhipIngestSource(context, VideoFrameListener(outgoing::onVideoFrame),
             PcmListener(outgoing::onPcm), scopedNetwork = scoped)
           source = incoming
           incoming.setStateListener { state, reason ->
             if (state == SourceState.FAILED) emit(id, "failed", "Glasses receiver: $reason")
           }
-          incoming.setPcmDeliveryEnabled(options["captureAudio"] != false)
-          incoming.start(SourceConfig("", SourceKind.SOFTAP, scoped.localIpv4()))
+          incoming.setPcmDeliveryEnabled(options["captureAudio"] != false && !bleAudio)
+          // A listener created while pinned to cellular cannot reply to the glasses over Wi-Fi.
+          // Restore cellular before opening the outgoing publisher, including when the bind fails.
+          hold.withProcessUnpinned {
+            incoming.start(SourceConfig("", SourceKind.SOFTAP, scoped.localIpv4()))
+          }
           wakeLock = context.getSystemService(PowerManager::class.java)
             .newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "Mentra:managed-relay").apply { acquire() }
           outgoing.start()
@@ -83,6 +94,11 @@ class GlassesMediaRelayModule : Module() {
       }
     }
 
+    Function("pushOutgoingPcm") { attemptId: String, base64: String, sampleRate: Int, channels: Int ->
+      val bytes = try { Base64.decode(base64, Base64.DEFAULT) } catch (_: IllegalArgumentException) { null }
+      bytes != null && pcmInput.push(attemptId, bytes, sampleRate, channels)
+    }
+
     AsyncFunction("stop") { attemptId: String, promise: Promise ->
       worker.execute {
         try {
@@ -100,6 +116,7 @@ class GlassesMediaRelayModule : Module() {
   }
 
   private fun cleanup() {
+    pcmInput.detach()
     source?.setStateListener(null)
     // Try every cleanup even if one fails. Keep the slot occupied on any failure.
     var failure: Exception? = null

package/android/src/main/java/com/mentra/glassesmedia/network/InternetHold.kt

@@ -239,6 +239,21 @@ class InternetHold(private val context: Context) {
         return@synchronized ok
     }
 
+    /**
+     * Create a SoftAP listener without inheriting the cellular socket mark, then restore the pin.
+     * Holding the lock prevents a network callback from re-pinning during the bind. The previous
+     * routing state is restored even when creating the listener fails.
+     */
+    fun <T> withProcessUnpinned(bind: () -> T): T = synchronized(lock) {
+        val wasPinned = processPinned
+        unbindProcess()
+        try {
+            bind()
+        } finally {
+            if (wasPinned) bindProcessToCellular()
+        }
+    }
+
     /** Undo [bindProcessToCellular]. Safe to call when nothing is pinned, and safe to call twice. */
     fun unbindProcess() = synchronized(lock) {
         if (closed) return@synchronized

package/android/src/main/java/com/mentra/glassesmedia/publisher/PhoneWhipPublisher.kt

@@ -40,6 +40,7 @@ class PhoneWhipPublisher(
   private val closeDone = CountDownLatch(1)
   @Volatile private var cleanupFailure: Throwable? = null
   private val pcm = RelayPcmBuffer()
+  private val audioInput = RelayAudioInput(pcm)
   private var factory: PeerConnectionFactory? = null
   private var egl: EglBase? = null
   private var adm: JavaAudioDeviceModule? = null
@@ -78,12 +79,10 @@ class PhoneWhipPublisher(
         adm = JavaAudioDeviceModule.builder(context)
           .setInputSampleRate(48_000).setUseStereoInput(false)
           .setUseHardwareAcousticEchoCanceler(false).setUseHardwareNoiseSuppressor(false)
-          .setAudioBufferCallback { buffer, _, channels, sampleRate, bytes, _ ->
-            if (channels == 1 && sampleRate == 48_000) pcm.read(buffer, bytes)
-            else for (i in 0 until minOf(bytes, buffer.capacity())) buffer.put(i, 0)
-            System.nanoTime()
+          .setAudioBufferCallback { buffer, _, channels, sampleRate, _, _ ->
+            audioInput.read(buffer, channels, sampleRate)
           }.createAudioDeviceModule().also {
-            // WebRTC's external-buffer mode: paced callbacks without AudioRecord/microphone.
+            // External mode has no blocking AudioRecord.read; our callback supplies the clock.
             it.setAudioRecordEnabled(false)
           }
         factory = PeerConnectionFactory.builder()

package/android/src/main/java/com/mentra/glassesmedia/publisher/RelayAudioInput.kt

@@ -0,0 +1,33 @@
+package com.mentra.glassesmedia.publisher
+
+import java.nio.ByteBuffer
+import java.util.concurrent.TimeUnit
+
+/** Supplies the clock normally provided by a blocking AudioRecord.read, without using the mic. */
+class RelayAudioInput(
+  private val pcm: RelayPcmBuffer,
+  private val nowNs: () -> Long = System::nanoTime,
+  private val sleepNs: (Long) -> Unit = { TimeUnit.NANOSECONDS.sleep(it) },
+) {
+  private var nextFrameAtNs: Long? = null
+
+  /** Called only by WebRTC's audio recording thread, with a complete PCM16 frame to fill. */
+  fun read(buffer: ByteBuffer, channels: Int, sampleRate: Int): Long {
+    require(channels > 0 && sampleRate > 0 && buffer.capacity() >= channels * 2)
+    val durationNs = (buffer.capacity() / (channels * 2)).toLong() * 1_000_000_000L / sampleRate
+    val deadline = nextFrameAtNs ?: nowNs()
+    var now = nowNs()
+    while (now < deadline) {
+      sleepNs(deadline - now)
+      now = nowNs()
+    }
+    // Preserve cadence across small scheduling delays, but never replay a backlog after a stall.
+    nextFrameAtNs = if (now - deadline >= durationNs) now + durationNs else deadline + durationNs
+
+    // External-recording mode reports bytesRead=0, then sends buffer.capacity() bytes to native.
+    // Fill that entire frame; using bytesRead would send only the library's prefilled silence.
+    if (channels == 1 && sampleRate == 48_000) pcm.read(buffer, buffer.capacity())
+    else for (i in 0 until buffer.capacity()) buffer.put(i, 0)
+    return now
+  }
+}

package/android/src/main/java/com/mentra/glassesmedia/publisher/RelayPcmInput.kt

@@ -0,0 +1,25 @@
+package com.mentra.glassesmedia.publisher
+
+/** Gates JS microphone callbacks by attempt, without queueing audio behind network operations. */
+class RelayPcmInput {
+  private var attemptId: String? = null
+  private var sink: ((ByteArray, Int, Int) -> Unit)? = null
+
+  @Synchronized fun attach(id: String, target: (ByteArray, Int, Int) -> Unit) {
+    attemptId = id
+    sink = target
+  }
+
+  @Synchronized fun push(id: String, bytes: ByteArray, sampleRate: Int, channels: Int): Boolean {
+    if (id != attemptId || bytes.isEmpty() || sampleRate !in 8_000..192_000 || channels !in 1..8) return false
+    val target = sink ?: return false
+    target(bytes, sampleRate, channels)
+    return true
+  }
+
+  /** Wait for any in-flight push before the owner closes the publisher. */
+  @Synchronized fun detach() {
+    attemptId = null
+    sink = null
+  }
+}

package/android/src/main/java/com/mentra/glassesmedia/source/WhipIngestServer.kt

@@ -104,9 +104,19 @@ class WhipIngestServer(
       val bound = WhipIngestProtocol.Endpoint(address.hostAddress ?: "127.0.0.1", socket.localPort)
       server = socket
       endpoint = bound
-      closed = CountDownLatch(1)
+      val listenerClosed = CountDownLatch(1)
+      closed = listenerClosed
       state = WhipIngestProtocol.State()
-      acceptThread = Thread({ acceptLoop(socket) }, "whip-ingest-accept").apply {
+      acceptThread = Thread({
+        try {
+          acceptLoop(socket)
+        } finally {
+          // close() can return while a blocked accept still owns the native descriptor.
+          // Only the accept thread can signal that the listener has really released its port.
+          socket.close()
+          listenerClosed.countDown()
+        }
+      }, "whip-ingest-accept").apply {
         isDaemon = true
         start()
       }
@@ -156,9 +166,11 @@ class WhipIngestServer(
 
   /** Hard teardown barrier: no request may still create a peer after this returns. */
   fun closeAndAwait(timeoutMs: Long = 15_000): Boolean {
+    val deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(timeoutMs)
     closeNow()
     connections.shutdownNow()
-    return connections.awaitTermination(timeoutMs, TimeUnit.MILLISECONDS)
+    if (!awaitClosed(timeoutMs)) return false
+    return connections.awaitTermination((deadline - System.nanoTime()).coerceAtLeast(0), TimeUnit.NANOSECONDS)
   }
 
   /**
@@ -178,9 +190,7 @@ class WhipIngestServer(
       endpoint = null
       current
     }
-    // Counted down even on the early return: a second close must not leave a waiter parked on a
-    // latch that nothing will ever open again.
-    closed.countDown()
+    // The accept thread owns the close barrier; concurrent closes must not open it early.
     if (socket == null) return
     runCatching { socket.close() }
     activeSockets.forEach { runCatching { it.close() } }
@@ -203,6 +213,7 @@ class WhipIngestServer(
       }
       if (!registered) { runCatching { connection.close() }; return }
       accepted.incrementAndGet()
+      SoftApTrace.stage("whip_socket_accepted")
       // Each connection on its own thread: a negotiation blocks for the length of an ICE gather,
       // and a DELETE arriving during one must not queue behind it.
       try {
@@ -361,6 +372,7 @@ class WhipIngestServer(
       val (method, target) = WhipIngestProtocol.parseRequestLine(
         reader.readLine() ?: return null,
       ) ?: return null
+      SoftApTrace.stage("whip_request_line_read", "method" to method)
 
       val headers = mutableMapOf<String, String>()
       while (true) {
@@ -373,6 +385,7 @@ class WhipIngestServer(
 
       val contentType = WhipIngestProtocol.headerValue(headers, "Content-Type")
       val contentLength = WhipIngestProtocol.headerValue(headers, "Content-Length")?.toLongOrNull()
+      SoftApTrace.stage("whip_request_headers_read", "contentLength" to contentLength)
 
       // Do not read a body we have already decided to refuse. decide() checks the length first for
       // exactly this reason.
@@ -388,6 +401,7 @@ class WhipIngestServer(
         val count = reader.read(body, read, body.size - read)
         if (count < 0) break
         read += count
+        SoftApTrace.stage("whip_request_body_read", "read" to read, "expected" to body.size)
       }
       return WhipIngestProtocol.Request(method, target, contentType, contentLength, String(body, 0, read))
     }

package/ios/CoreKit/Sources/GlassesMediaCore/HotspotInternetPolicy.swift

@@ -0,0 +1,16 @@
+/// A usable default route is independent of the glasses' local-only Wi-Fi hotspot.
+/// This classifies network paths; actual server reachability is established by the call.
+public enum HotspotInternetPolicy {
+    public static func route(satisfied: Bool, cellular: Bool, ethernet: Bool,
+                             restoredWifiSSID: String? = nil, glassesSSID: String? = nil) -> String?
+    {
+        guard satisfied else { return nil }
+        if cellular { return "cellular" }
+        if ethernet { return "ethernet" }
+        // Callers supply a Wi-Fi SSID only after releasing the glasses hotspot.
+        if let restoredWifiSSID, !restoredWifiSSID.isEmpty, restoredWifiSSID != glassesSSID {
+            return "wifi"
+        }
+        return nil
+    }
+}

package/ios/CoreKit/Sources/GlassesMediaCore/LocalMediaPolicy.swift

@@ -39,6 +39,14 @@ public enum LocalMediaPolicy {
         return bytes[3] > 0 && bytes[3] < 255
     }
 
+    /// A Mac may join through its host network controls. Reuse that connection only
+    /// after both its SSID and DHCP address match the hotspot advertised over BLE.
+    public static func canReuseHotspot(requestedSSID: String, currentSSID: String?, address: String?, gateway: String?) -> Bool {
+        guard !requestedSSID.isEmpty, requestedSSID == currentSSID,
+              let address, let gateway else { return false }
+        return isHotspotClientAddress(address, gateway: gateway)
+    }
+
     /// Keep only concrete host candidates on the local link. Never rewrite a cellular socket's
     /// advertised address: a candidate must already belong to the interface it claims.
     public static func localSdp(_ sdp: String, address: String, answer: Bool) throws -> String {

package/ios/CoreKit/Sources/GlassesMediaCore/LocalNetworkAccessRequest.swift

@@ -0,0 +1,134 @@
+import Foundation
+import Network
+
+protocol LocalNetworkAccessConnection: AnyObject {
+    var onState: ((NWConnection.State, NWPath.UnsatisfiedReason?) -> Void)? { get set }
+    func start(queue: DispatchQueue)
+    func cancel()
+}
+
+/// Wait for permission to use the verified local route before starting timed media work.
+/// Connect to the glasses' existing gallery HTTP endpoint to prove local access (TN3179).
+/// Network.framework retries when access is granted. A denied path can also mean that the
+/// alert is still open, so it must not be treated as a terminal error or given a media timeout.
+/// Ordinary connection setup has a 30-second budget, paused while permission is required.
+public final class LocalNetworkAccessRequest {
+    private let queue: DispatchQueue
+    private let connection: LocalNetworkAccessConnection
+    private let now: () -> TimeInterval
+    private let scheduleTimeout: (TimeInterval, DispatchWorkItem) -> Void
+    private var remainingConnectivityTime: TimeInterval = 30
+    private var timeoutDeadline: TimeInterval?
+    private var timeoutWork: DispatchWorkItem?
+    private var completion: ((Result<Void, Error>) -> Void)?
+    private var waiting: (() -> Void)?
+    private var finished = false
+    private var reportedPermission = false
+
+    public convenience init(localAddress: String, gateway: String, queue: DispatchQueue) {
+        self.init(connection: LocalNetworkPermissionConnection(localAddress: localAddress, gateway: gateway), queue: queue)
+    }
+
+    init(connection: LocalNetworkAccessConnection, queue: DispatchQueue,
+         now: @escaping () -> TimeInterval = { ProcessInfo.processInfo.systemUptime },
+         scheduleTimeout: ((TimeInterval, DispatchWorkItem) -> Void)? = nil)
+    {
+        self.connection = connection
+        self.queue = queue
+        self.now = now
+        self.scheduleTimeout = scheduleTimeout ?? { delay, work in queue.asyncAfter(deadline: .now() + delay, execute: work) }
+    }
+
+    public func start(onPermissionRequired: @escaping () -> Void, completion: @escaping (Result<Void, Error>) -> Void) {
+        queue.async {
+            guard !self.finished, self.completion == nil else { return }
+            self.completion = completion
+            self.waiting = onPermissionRequired
+            self.connection.onState = { [weak self] state, reason in
+                guard let self, !self.finished else { return }
+                switch state {
+                case .ready: self.finish(.success(()))
+                case .waiting where reason == .localNetworkDenied:
+                    self.pauseConnectivityTimeout()
+                    if !self.reportedPermission {
+                        self.reportedPermission = true
+                        self.waiting?()
+                    }
+                // Waiting errors are nonfatal; NWConnection retries when its path recovers.
+                // A nil path is not proof of denied permission, but must not fail immediately.
+                case .setup, .preparing, .waiting: self.resumeConnectivityTimeout()
+                case let .failed(error): self.finish(.failure(error))
+                case .cancelled: self.finish(.failure(CancellationError()))
+                @unknown default: break
+                }
+            }
+            self.resumeConnectivityTimeout()
+            self.connection.start(queue: self.queue)
+        }
+    }
+
+    public func cancel() {
+        queue.async { self.finish(.failure(CancellationError())) }
+    }
+
+    private func resumeConnectivityTimeout() {
+        guard timeoutDeadline == nil else { return }
+        let deadline = now() + remainingConnectivityTime
+        timeoutDeadline = deadline
+        let work = DispatchWorkItem { [weak self] in
+            guard let self, self.timeoutDeadline == deadline else { return }
+            self.finish(.failure(LocalMediaError("Local connection to the glasses timed out")))
+        }
+        timeoutWork = work
+        scheduleTimeout(remainingConnectivityTime, work)
+    }
+
+    private func pauseConnectivityTimeout() {
+        if let deadline = timeoutDeadline { remainingConnectivityTime = max(0, deadline - now()) }
+        timeoutDeadline = nil
+        timeoutWork?.cancel()
+        timeoutWork = nil
+    }
+
+    private func finish(_ result: Result<Void, Error>) {
+        guard !finished else { return }
+        finished = true
+        pauseConnectivityTimeout()
+        connection.onState = nil
+        connection.cancel()
+        let reply = completion
+        completion = nil
+        waiting = nil
+        reply?(result)
+    }
+}
+
+private final class LocalNetworkPermissionConnection: LocalNetworkAccessConnection {
+    var onState: ((NWConnection.State, NWPath.UnsatisfiedReason?) -> Void)?
+    private let connection: NWConnection
+
+    init(localAddress: String, gateway: String) {
+        let parameters = NWParameters.tcp
+        parameters.requiredLocalEndpoint = .hostPort(host: NWEndpoint.Host(localAddress), port: .any)
+        connection = NWConnection(host: NWEndpoint.Host(gateway), port: 8089, using: parameters)
+    }
+
+    func start(queue: DispatchQueue) {
+        connection.stateUpdateHandler = { [weak self] state in
+            guard let self else { return }
+            onState?(state, connection.currentPath?.unsatisfiedReason)
+        }
+        // The path reason can arrive after a waiting update with no currentPath yet.
+        connection.pathUpdateHandler = { [weak self] path in
+            guard let self else { return }
+            onState?(connection.state, path.unsatisfiedReason)
+        }
+        connection.start(queue: queue)
+    }
+
+    func cancel() {
+        connection.stateUpdateHandler = nil
+        connection.pathUpdateHandler = nil
+        connection.cancel()
+    }
+}

package/ios/CoreKit/Sources/GlassesMediaCore/MacE2EHotspotLease.swift

@@ -0,0 +1,20 @@
+#if MENTRA_E2E
+    import Foundation
+
+    /// Test-build dependency input, not a production network discovery mechanism.
+    /// The Mac harness owns association and verifies the USB fixture, gateway MAC,
+    /// DHCP address, local health and Ethernet before launching this process.
+    public struct MacE2EHotspotLease: Decodable {
+        public let ssid: String
+        public let gateway: String
+        public let address: String
+        public let issuedAt: TimeInterval
+
+        public func matches(ssid: String, gateway: String?, address: String?, now: TimeInterval) -> Bool {
+            let age = now - issuedAt
+            return age >= 0 && age <= 300 && self.gateway == gateway && self.address == address &&
+                LocalMediaPolicy.canReuseHotspot(requestedSSID: ssid, currentSSID: self.ssid,
+                                                 address: address, gateway: gateway)
+        }
+    }
+#endif

package/ios/CoreKit/Sources/GlassesMediaCore/WhipOfferGate.swift

@@ -0,0 +1,24 @@
+/// Internet WHIP uses the same bounded STUN gather as the glasses publisher.
+/// The local, host-only SoftAP receiver must still wait for complete gathering.
+public struct WhipOfferGate {
+    public enum Signal { case localDescriptionSet, serverReflexiveCandidate, gatheringComplete, deadline, stop }
+
+    private var localSet = false
+    private var ready = false
+    private var posted = false
+    private var stopped = false
+
+    public init() {}
+
+    /// True once per publisher, after both the description and a POST trigger exist.
+    public mutating func observe(_ signal: Signal) -> Bool {
+        switch signal {
+        case .localDescriptionSet: localSet = true
+        case .serverReflexiveCandidate, .gatheringComplete, .deadline: ready = true
+        case .stop: stopped = true
+        }
+        guard localSet, ready, !posted, !stopped else { return false }
+        posted = true
+        return true
+    }
+}

package/ios/GlassesHotspotNetwork.swift

@@ -2,9 +2,11 @@ import Darwin
 import Foundation
 import Network
 import NetworkExtension
+import OSLog
 
 /// Same persistent hotspot join as gallery (`joinOnce=false`). Only local traffic uses Wi-Fi.
 public final class GlassesHotspotNetwork {
+    private let logger = Logger(subsystem: "com.mentra.glassesmedia", category: "hotspot")
     private let queue = DispatchQueue(label: "com.mentra.glassesmedia.hotspot")
     private var ssid: String?
     private var lastHotspotSSID: String?
@@ -12,11 +14,17 @@ public final class GlassesHotspotNetwork {
     private var gatewayAddress: String?
     private var generation = 0
     private var applying = false
+    private var ownsConfiguration = false
     private var cancelled = false
     private var joinReply: ((Result<String, Error>) -> Void)?
     private var leaveReplies: [() -> Void] = []
     private var monitor: NWPathMonitor?
+    private var localAccess: LocalNetworkAccessRequest?
+    #if MENTRA_E2E
+        private var testLeaseConsumed = false
+    #endif
     public var onLost: ((String) -> Void)?
+    public var onPermissionRequired: (() -> Void)?
     public init() {}
 
     public func join(ssid: String, passphrase: String, gateway: String? = nil, completion: @escaping (Result<String, Error>) -> Void) {
@@ -31,28 +39,58 @@ public final class GlassesHotspotNetwork {
             self.lastHotspotSSID = ssid
             self.gatewayAddress = gateway
             self.cancelled = false
-            self.applying = true
+            self.applying = false
+            self.ownsConfiguration = false
             self.joinReply = completion
-            let config = NEHotspotConfiguration(ssid: ssid, passphrase: passphrase, isWEP: false)
-            config.joinOnce = false
-            NEHotspotConfigurationManager.shared.apply(config) { error in
-                self.queue.async {
-                    guard gen == self.generation else { return }
-                    self.applying = false
-                    if self.cancelled { self.finishLeave(); return }
-                    if let error, (error as NSError).code != NEHotspotConfigurationError.alreadyAssociated.rawValue {
-                        self.finishJoin(.failure(error)); self.finishLeave(); return
+            if ProcessInfo.processInfo.isiOSAppOnMac {
+                #if MENTRA_E2E
+                    if let raw = ProcessInfo.processInfo.environment["MENTRA_E2E_PREJOINED_HOTSPOT"] {
+                        let address = Self.wifiAddress()
+                        guard !self.testLeaseConsumed,
+                              let lease = try? JSONDecoder().decode(MacE2EHotspotLease.self, from: Data(raw.utf8)),
+                              lease.matches(ssid: ssid, gateway: gateway, address: address, now: Date().timeIntervalSince1970),
+                              let address
+                        else {
+                            self.finishJoin(.failure(LocalMediaError("Mac E2E network lease is invalid, expired or already consumed")))
+                            self.finishLeave()
+                            return
+                        }
+                        self.testLeaseConsumed = true
+                        self.localAddress = address
+                        self.logger.notice("HOTSPOT_JOIN test_harness_connection native_association_untested")
+                        self.startMonitor(generation: gen)
+                        self.waitForLocalAccess(address: address, generation: gen)
+                        return
+                    }
+                #endif
+                NEHotspotNetwork.fetchCurrent { network in
+                    self.queue.async {
+                        guard gen == self.generation, !self.cancelled else { return }
+                        let address = Self.wifiAddress()
+                        if let address, LocalMediaPolicy.canReuseHotspot(requestedSSID: ssid, currentSSID: network?.ssid,
+                                                                         address: address, gateway: gateway)
+                        {
+                            self.localAddress = address
+                            self.logger.info("HOTSPOT_JOIN reuse_verified_macos_connection")
+                            self.startMonitor(generation: gen)
+                            self.waitForLocalAccess(address: address, generation: gen)
+                        } else {
+                            self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen)
+                        }
                     }
-                    self.waitForAddress(ssid: ssid, generation: gen, remaining: 60)
                 }
+            } else {
+                self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen)
             }
             self.queue.asyncAfter(deadline: .now() + 60) {
-                guard gen == self.generation, self.joinReply != nil else { return }
+                // Once associated, the user may still be reading the Local Network alert.
+                // Its response time is not a hotspot association timeout.
+                guard gen == self.generation, self.joinReply != nil, self.localAccess == nil else { return }
                 self.cancelled = true
                 self.finishJoin(.failure(LocalMediaError("Hotspot join timed out")))
                 // apply() cannot be cancelled. Retain the reservation until its callback and remove the
                 // late configuration before another call is permitted to acquire the network.
-                NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid)
+                if self.ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
                 if !self.applying { self.finishLeave() }
             }
         }
@@ -63,7 +101,7 @@ public final class GlassesHotspotNetwork {
             self.cancelled = true
             self.leaveReplies.append(completion)
             self.finishJoin(.failure(LocalMediaError("Hotspot join cancelled")))
-            if let ssid = self.ssid { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
+            if let ssid = self.ssid, self.ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
             if !self.applying { self.finishLeave() }
         }
     }
@@ -84,7 +122,13 @@ public final class GlassesHotspotNetwork {
             guard let address = self.localAddress else { completion(false, "No joined hotspot"); return }
             let gateway = self.gatewayAddress ?? address.split(separator: ".").prefix(3).joined(separator: ".") + ".1"
             let parameters = NWParameters.tcp
-            parameters.requiredInterfaceType = .wifi
+            if ProcessInfo.processInfo.isiOSAppOnMac {
+                // The Mac route probe rejects the Wi-Fi type constraint on an otherwise
+                // usable en0 route. Restrict this connection to the verified source IP.
+                parameters.requiredLocalEndpoint = .hostPort(host: NWEndpoint.Host(address), port: .any)
+            } else {
+                parameters.requiredInterfaceType = .wifi
+            }
             let connection = NWConnection(host: NWEndpoint.Host(gateway), port: 8089, using: parameters)
             var finished = false
             let finish: (Bool, String) -> Void = { reachable, detail in
@@ -106,7 +150,7 @@ public final class GlassesHotspotNetwork {
         }
     }
 
-    public func awaitInternet(requireCellular: Bool = true, completion: @escaping (Bool, String) -> Void) {
+    public func awaitInternet(allowWifiAfterRelease: Bool = false, completion: @escaping (Bool, String) -> Void) {
         queue.async {
             let monitor = NWPathMonitor()
             var finished = false
@@ -117,21 +161,57 @@ public final class GlassesHotspotNetwork {
                 completion(usable, detail)
             }
             monitor.pathUpdateHandler = { path in
-                if path.status == .satisfied, path.usesInterfaceType(.cellular) { finish(true, "cellular") }
+                if let route = HotspotInternetPolicy.route(satisfied: path.status == .satisfied,
+                                                           cellular: path.usesInterfaceType(.cellular),
+                                                           ethernet: path.usesInterfaceType(.wiredEthernet))
+                {
+                    finish(true, route)
+                    return
+                }
                 // Once the hotspot is released, a return to the user's Wi-Fi is also valid.
                 // Do not mistake the departing glasses AP's local-only path for restored internet.
-                if !requireCellular, path.status == .satisfied, path.usesInterfaceType(.wifi) {
+                if allowWifiAfterRelease, path.status == .satisfied, path.usesInterfaceType(.wifi) {
                     NEHotspotNetwork.fetchCurrent { network in
                         self.queue.async {
-                            guard let network, !network.ssid.isEmpty, network.ssid != self.lastHotspotSSID else { return }
-                            finish(true, "wifi")
+                            guard let route = HotspotInternetPolicy.route(satisfied: true, cellular: false, ethernet: false,
+                                                                          restoredWifiSSID: network?.ssid, glassesSSID: self.lastHotspotSSID)
+                            else { return }
+                            finish(true, route)
                         }
                     }
                 }
             }
             monitor.start(queue: self.queue)
             self.queue.asyncAfter(deadline: .now() + 15) {
-                finish(false, requireCellular ? "Cellular internet did not become the default route" : "Internet did not return after leaving the glasses hotspot")
+                finish(false, allowWifiAfterRelease ? "Internet did not return after leaving the glasses hotspot" : "Cellular or Ethernet internet did not become the default route")
+            }
+        }
+    }
+
+    private func applyConfiguration(ssid: String, passphrase: String, generation gen: Int) {
+        let config = NEHotspotConfiguration(ssid: ssid, passphrase: passphrase, isWEP: false)
+        config.joinOnce = false
+        applying = true
+        ownsConfiguration = true
+        logger.info("HOTSPOT_JOIN apply_start ios_on_mac=\(ProcessInfo.processInfo.isiOSAppOnMac)")
+        NEHotspotConfigurationManager.shared.apply(config) { error in
+            self.queue.async {
+                guard gen == self.generation else { return }
+                self.applying = false
+                if self.cancelled { self.finishLeave(); return }
+                if let error {
+                    let nativeError = error as NSError
+                    let alreadyAssociated = nativeError.domain == NEHotspotConfigurationErrorDomain &&
+                        nativeError.code == NEHotspotConfigurationError.alreadyAssociated.rawValue
+                    if !alreadyAssociated {
+                        // Error identifiers are useful without credentials or full userInfo.
+                        let underlying = nativeError.userInfo[NSUnderlyingErrorKey] as? NSError
+                        self.logger.error("HOTSPOT_JOIN apply_failed domain=\(nativeError.domain, privacy: .public) code=\(nativeError.code) underlying_domain=\(underlying?.domain ?? "none", privacy: .public) underlying_code=\(underlying.map { String($0.code) } ?? "none", privacy: .public)")
+                        self.finishJoin(.failure(error)); self.finishLeave(); return
+                    }
+                }
+                self.logger.info("HOTSPOT_JOIN apply_accepted")
+                self.waitForAddress(ssid: ssid, generation: gen, remaining: 60)
             }
         }
     }
@@ -146,7 +226,7 @@ public final class GlassesHotspotNetwork {
                 {
                     self.localAddress = address
                     self.startMonitor(generation: gen)
-                    self.finishJoin(.success(address))
+                    self.waitForLocalAccess(address: address, generation: gen)
                 } else if remaining > 0 {
                     self.queue.asyncAfter(deadline: .now() + 0.5) { self.waitForAddress(ssid: ssid, generation: gen, remaining: remaining - 1) }
                 } else {
@@ -163,14 +243,35 @@ public final class GlassesHotspotNetwork {
         let monitor = NWPathMonitor(requiredInterfaceType: .wifi)
         self.monitor = monitor
         monitor.pathUpdateHandler = { [weak self] _ in
-            guard let self, gen == self.generation, !self.cancelled else { return }
+            guard let self, gen == generation, !self.cancelled else { return }
             // This AP intentionally has no internet. Loss of its default internet path is not
             // loss of the local link; use the actual interface address instead.
-            if Self.wifiAddress() != self.localAddress { self.onLost?("Glasses hotspot connection was lost") }
+            if Self.wifiAddress() != localAddress { onLost?("Glasses hotspot connection was lost") }
         }
         monitor.start(queue: queue)
     }
 
+    private func waitForLocalAccess(address: String, generation gen: Int) {
+        let gateway = gatewayAddress ?? address.split(separator: ".").prefix(3).joined(separator: ".") + ".1"
+        let request = LocalNetworkAccessRequest(localAddress: address, gateway: gateway, queue: queue)
+        localAccess = request
+        request.start(onPermissionRequired: { [weak self] in
+            guard let self, gen == generation, !cancelled else { return }
+            NSLog("GLASSES-MEDIA local_network_permission=waiting")
+            onPermissionRequired?()
+        }) { [weak self] result in
+            guard let self, gen == generation, !cancelled else { return }
+            switch result {
+            case .success:
+                NSLog("GLASSES-MEDIA local_network_permission=ready")
+                finishJoin(.success(address))
+            case let .failure(error):
+                finishJoin(.failure(error))
+                finishLeave()
+            }
+        }
+    }
+
     private func finishJoin(_ result: Result<String, Error>) {
         let reply = joinReply
         joinReply = nil
@@ -179,8 +280,10 @@ public final class GlassesHotspotNetwork {
 
     private func finishLeave() {
         generation += 1
+        localAccess?.cancel(); localAccess = nil
         monitor?.cancel(); monitor = nil
-        if let ssid { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
+        if let ssid, ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
+        ownsConfiguration = false
         ssid = nil
         localAddress = nil
         gatewayAddress = nil

package/ios/GlassesMediaRelayModule.swift

@@ -74,6 +74,12 @@ private final class ManagedRelaySession {
     {
         ready = completion
         hotspot.onLost = { reason in onState("failed", reason) }
+        hotspot.onPermissionRequired = { [weak self] in
+            self?.queue.async {
+                guard let self, !self.stopped else { return }
+                onState("permission_required", "Allow Local Network access to connect to your glasses. If you previously denied access, enable it in Settings, or cancel to return home.")
+            }
+        }
         hotspot.join(ssid: ssid, passphrase: password, gateway: gateway) { result in
             self.queue.async {
                 guard !self.stopped else { return }
@@ -83,7 +89,7 @@ private final class ManagedRelaySession {
                     self.hotspot.awaitInternet { usable, _ in
                         self.queue.async {
                             guard !self.stopped else { return }
-                            guard usable else { self.finish(.failure(LocalMediaError("Turn on phone mobile data to stream through the glasses hotspot"))); return }
+                            guard usable else { self.finish(.failure(LocalMediaError("Connect cellular or Ethernet internet to stream through the glasses hotspot"))); return }
                             let publisher = PhoneWhipPublisher(endpoint: endpoint, captureAudio: captureAudio, bitrate: bitrate, onState: onState)
                             self.publisher = publisher
                             let receiver = LocalWhipIngestSource()
@@ -117,6 +123,7 @@ private final class ManagedRelaySession {
         stopped = true
         finish(.failure(LocalMediaError("Relay cancelled")))
         hotspot.onLost = nil
+        hotspot.onPermissionRequired = nil
         let group = DispatchGroup()
         if let receiver {
             group.enter(); receiver.stop { group.leave() }

package/ios/LocalWhipIngestSource.swift

@@ -171,7 +171,9 @@ public final class LocalWhipIngestSource: NSObject, DecodedGlassesMediaSource {
             publisherFailed: { [weak self] in self?.state == .failed }
         )
         self.server = server
-        server.start(address: address) { [weak self] result in
+        // Keep the listener bound to the verified hotspot IP on iOS-on-Mac.
+        // Requiring the Wi-Fi interface type rejects that local route on this host.
+        server.start(address: address, wifiOnly: !ProcessInfo.processInfo.isiOSAppOnMac) { [weak self] result in
             guard let self else { completion(.failure(LocalMediaError("Receiver released"))); return }
             self.queue.async {
                 guard gen == self.generation, !self.stopping else { completion(.failure(LocalMediaError("Receiver cancelled"))); return }

package/ios/PhoneWhipPublisher.swift

@@ -2,7 +2,7 @@ import CoreVideo
 import Foundation
 import WebRTC
 
-/// ASG's full-ICE WHIP negotiation, fed from the shared decoded receiver. One peer per attempt.
+/// ASG's bounded STUN-gather WHIP negotiation, fed from the shared decoded receiver.
 final class PhoneWhipPublisher: NSObject {
     private let queue = DispatchQueue(label: "com.mentra.glassesmedia.whip.publish")
     private let frameSlot = DispatchSemaphore(value: 1)
@@ -17,7 +17,10 @@ final class PhoneWhipPublisher: NSObject {
     private var capturer: RTCVideoCapturer?
     private var resource: URL?
     private var posted = false
-    private var localSet = false
+    private var offerGate = WhipOfferGate()
+    private var candidateCount = 0
+    private var phase = "creating offer"
+    private var firstFrameSeen = false
     private var stopped = false
     private var failed = false
     private var connected = false
@@ -81,13 +84,19 @@ final class PhoneWhipPublisher: NSObject {
                         self.queue.async {
                             guard !self.stopped else { return }
                             guard error == nil else { self.fail("WHIP local description failed"); return }
-                            self.localSet = true; self.maybePost()
+                            self.phase = "gathering ICE"
+                            self.maybePost(.localDescriptionSet)
+                            if peer.iceGatheringState == .complete { self.maybePost(.gatheringComplete) }
+                            // STUN gathering can stall longer than the entire start request.
+                            // Match the glasses publisher's 1.5s cap; the remote ICE-lite
+                            // candidates in the answer let this peer initiate connectivity.
+                            self.queue.asyncAfter(deadline: .now() + 1.5) { self.maybePost(.deadline) }
                         }
                     }
                 }
             }
             self.queue.asyncAfter(deadline: .now() + 35) {
-                if !self.connected { self.fail("WHIP connection timed out") }
+                if !self.connected { self.fail("WHIP connection timed out while \(self.phase) (\(self.candidateCount) candidates)") }
             }
         }
     }
@@ -97,6 +106,10 @@ final class PhoneWhipPublisher: NSObject {
         queue.async {
             defer { self.frameSlot.signal() }
             guard !self.stopped, let source = self.videoSource, let capturer = self.capturer else { return }
+            if !self.firstFrameSeen {
+                self.firstFrameSeen = true
+                self.onState("diagnostic", "First decoded glasses video frame reached the phone publisher")
+            }
             self.lastTimestamp = max(Int64(ProcessInfo.processInfo.systemUptime * 1_000_000_000), self.lastTimestamp + 1)
             let frame = RTCVideoFrame(buffer: RTCCVPixelBuffer(pixelBuffer: buffer), rotation: ._0, timeStampNs: self.lastTimestamp)
             source.capturer(capturer, didCapture: frame)
@@ -107,9 +120,12 @@ final class PhoneWhipPublisher: NSObject {
         if captureAudio { audioDevice.pcm.push(data, sampleRate: rate, channels: channels) }
     }
 
-    private func maybePost() {
-        guard !stopped, !posted, localSet, let peer, peer.iceGatheringState == .complete, let offer = peer.localDescription else { return }
+    private func maybePost(_ signal: WhipOfferGate.Signal) {
+        guard !stopped, !failed, let peer, offerGate.observe(signal) else { return }
+        guard let offer = peer.localDescription else { fail("WHIP local description unavailable"); return }
         posted = true
+        phase = "sending offer"
+        onState("diagnostic", "Posting WHIP offer (\(candidateCount) candidates)")
         var request = URLRequest(url: endpoint)
         request.httpMethod = "POST"
         request.setValue("application/sdp", forHTTPHeaderField: "Content-Type")
@@ -128,9 +144,16 @@ final class PhoneWhipPublisher: NSObject {
                       let data, let answer = String(data: data, encoding: .utf8), !answer.isEmpty
                 else {
                     if let location { self.delete(location) }
-                    self.fail("WHIP server rejected publish (HTTP \(response?.statusCode ?? 0))"); return
+                    if let error = error as NSError? {
+                        self.fail("WHIP signaling failed (\(error.domain) \(error.code))")
+                    } else {
+                        self.fail("WHIP server rejected publish (HTTP \(response?.statusCode ?? 0))")
+                    }
+                    return
                 }
                 self.resource = location
+                self.phase = "connecting ICE"
+                self.onState("diagnostic", "WHIP server accepted publish (HTTP 201)")
                 peer.setRemoteDescription(RTCSessionDescription(type: .answer, sdp: answer)) { error in
                     self.queue.async { if error != nil { self.fail("WHIP answer failed") } }
                 }
@@ -154,6 +177,7 @@ final class PhoneWhipPublisher: NSObject {
         queue.async {
             if !self.stopped {
                 self.stopped = true
+                _ = self.offerGate.observe(.stop)
                 self.peer?.close()
                 // Drain the external audio callback while its native delegate/factory is still alive.
                 _ = self.audioDevice.terminateDevice()
@@ -176,6 +200,7 @@ extension PhoneWhipPublisher: RTCPeerConnectionDelegate {
     func peerConnection(_ peerConnection: RTCPeerConnection, didChange state: RTCIceConnectionState) {
         queue.async {
             guard self.peer === peerConnection, !self.stopped else { return }
+            self.onState("diagnostic", "WHIP ICE state \(state.rawValue)")
             switch state {
             case .connected, .completed:
                 self.connected = true; self.disconnectGeneration += 1
@@ -192,11 +217,22 @@ extension PhoneWhipPublisher: RTCPeerConnectionDelegate {
         }
     }
 
-    func peerConnection(_ peerConnection: RTCPeerConnection, didChange _: RTCIceGatheringState) {
-        queue.async { if self.peer === peerConnection { self.maybePost() } }
+    func peerConnection(_ peerConnection: RTCPeerConnection, didChange state: RTCIceGatheringState) {
+        queue.async {
+            guard self.peer === peerConnection, !self.stopped else { return }
+            self.onState("diagnostic", "WHIP ICE gathering state \(state.rawValue) (\(self.candidateCount) candidates)")
+            if state == .complete { self.maybePost(.gatheringComplete) }
+        }
+    }
+
+    func peerConnection(_ peerConnection: RTCPeerConnection, didGenerate candidate: RTCIceCandidate) {
+        queue.async {
+            guard self.peer === peerConnection, !self.stopped else { return }
+            self.candidateCount += 1
+            if candidate.sdp.contains(" typ srflx ") { self.maybePost(.serverReflexiveCandidate) }
+        }
     }
 
-    func peerConnection(_: RTCPeerConnection, didGenerate _: RTCIceCandidate) {}
     func peerConnection(_: RTCPeerConnection, didRemove _: [RTCIceCandidate]) {}
     func peerConnection(_: RTCPeerConnection, didOpen _: RTCDataChannel) {}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/glasses-media",
-  "version": "3.2.0-dev.265",
+  "version": "3.2.1-beta.312",
   "description": "Shared native glasses media receivers and local network transport",
   "license": "MIT",
   "author": "Mentra Community",