feat(hud): phone-Wi-Fi interference advisory + faster off-air recovery (0.1.9)

Two improvements driven by the 2026-06-30 field logs (HUD 0.1.8 confirmed the
self-heal works: on arriving home it logged "recovered after 33.8s off-air
(restart x1 reassoc x4 toggle x3)" and came back with no reboot; the toggle
running proves the Motoeye E6 is API<=28, so the full toolkit is available).

1) Faster severe-case recovery. The 33.8s recovery was slow because the ladder
   reached the WiFi toggle (the rung that actually clears it on this device)
   only on the 3rd action and ticked every 3s. Now:
   - recoveryStepFor front-loads the toggle (RESTART -> TOGGLE -> REASSOC -> ...)
     since the field log showed reassociate alone did not clear the off-air state.
   - RECOVERY_INTERVAL_MS 3s -> 1.5s, OFF_AIR_GRACE_TICKS 1 -> 0, toggle settle
     1.5s -> 1.0s. Expected ~8-12s instead of ~34s. (LinkWatchdogTest updated.)

2) "Phone Wi-Fi is interrupting the HUD" rider advisory. Root cause confirmed by
   the rider observing the HUD drop the instant the phone joined home Wi-Fi on
   arrival: single-radio STA+AP channel-follow -- any phone Wi-Fi STA transition
   re-tunes the shared hotspot radio and drops the link. The HUD can't see this
   (it only knows the hotspot), so the PHONE detects it and tells the HUD:
   - hud-protocol WifiInterferenceDetector (pure, unit-tested): flags interference
     only when an established-link HUD drop lands within ~20s of one of the
     phone's OWN Wi-Fi STA transitions, >=2 times; auto-clears after stable.
   - app HudServer feeds it (STA transitions from the NetworkCallback incl. a new
     onLost; established-link drops via a wasOpen-gated onFailure) and publishes
     HudState.phoneWifiInterfering (wire proto minor 9 -> 10, additive).
   - HUD shows a BottomStart advisory badge in the SAME chrome family as the
     existing version/disconnect badges (0xE6111111 fill, 1.dp stroke, info-yellow,
     icon + stacked title/detail) reading "Phone Wi-Fi interrupting HUD / Turn off
     phone Wi-Fi for a stable link".

HUD bumped to 0.1.9 (300010). Needs the matching phone app (proto 10) for the
advisory; older phones simply never set the flag.

Verified: hud-protocol unit tests 39/39 (incl. 5 new detector + updated ladder);
:hud and :app compile clean; both debug APKs assemble; installed on emulator-5554
(API 36) and launched -- neither app crashes, watchdog logs verdict=HEALTHY at idle
(peerKnown=false correctly NOT treated as off-air). On-device radio recovery still
needs the tester to confirm the faster timing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fpo6EKJ9QYwyb9FkKQWrTn

Author: eried

app/src/main/java/com/eried/eucplanet/service/hud/HudServer.kt

@@ -20,6 +20,7 @@ import com.eried.eucplanet.hud.protocol.HudDebug
 import com.eried.eucplanet.hud.protocol.HudDiscovery
 import com.eried.eucplanet.hud.protocol.HudState
 import com.eried.eucplanet.hud.protocol.RadarTargetWire
+import com.eried.eucplanet.hud.protocol.WifiInterferenceDetector
 import com.eried.eucplanet.nav.NavigationEngine
 import com.eried.eucplanet.ui.theme.AccentOptions
 import com.eried.eucplanet.ui.theme.AccentTeal
@@ -169,6 +170,13 @@ class HudServer @Inject constructor(
     /** Currently-registered ConnectivityManager callback; cleared on doStop. */
     @Volatile private var netCallback: ConnectivityManager.NetworkCallback? = null
 
+    /** Detects when the phone's OWN home/other Wi-Fi keeps interrupting the HUD
+     *  link (single-radio channel-follow): correlates established-link drops
+     *  with the phone's Wi-Fi STA transitions. When it fires we set
+     *  [HudState.phoneWifiInterfering] so the HUD advises the rider to turn the
+     *  phone's Wi-Fi off. */
+    private val wifiInterference = WifiInterferenceDetector()
+
     init {
         // Watch the toggle ourselves so the link starts the moment the
         // rider flips `Enable data link` -- no dependency on WheelService
@@ -339,8 +347,17 @@ class HudServer @Inject constructor(
             override fun onAvailable(network: Network) {
                 Log.i(TAG, "network onAvailable: kicking dial loop")
                 log("Network came up, retrying immediately")
+                // The phone's own home/other Wi-Fi just (re)joined: on a single
+                // radio this re-tunes the hotspot and tends to drop the HUD a
+                // few seconds later. Feed the detector so a correlated drop is
+                // recognised as channel-follow, not a plain out-of-range loss.
+                wifiInterference.onStaTransition(System.currentTimeMillis())
                 reconnectKick.trySend(Unit)
             }
+            override fun onLost(network: Network) {
+                Log.i(TAG, "network onLost: home WiFi gone")
+                wifiInterference.onStaTransition(System.currentTimeMillis())
+            }
             override fun onLosing(network: Network, maxMsToLive: Int) {
                 // DO NOT close the WS here. This callback filters for
                 // TRANSPORT_WIFI + NET_CAPABILITY_INTERNET, so the only network
@@ -357,6 +374,7 @@ class HudServer @Inject constructor(
                 Log.i(TAG, "network onLosing (${maxMsToLive}ms): home WiFi leaving; " +
                     "leaving hotspot WS intact")
                 log("Home WiFi dropping in ${maxMsToLive}ms (hotspot link unaffected)")
+                wifiInterference.onStaTransition(System.currentTimeMillis())
             }
         }
         try {
@@ -676,9 +694,14 @@ class HudServer @Inject constructor(
             .build()
         val listener = object : WebSocketListener() {
             private var sendJob: Job? = null
+            /** True once this socket actually opened, so onFailure can tell an
+             *  ESTABLISHED-link drop (a real interruption worth correlating with
+             *  Wi-Fi) from a plain "couldn't find/connect to the HUD" dial miss. */
+            @Volatile private var wasOpen = false
             override fun onOpen(webSocket: WebSocket, response: Response) {
                 Log.i(TAG, "HUD link open: $peer")
                 log("Connected to $peer ✓")
+                wasOpen = true
                 ws = webSocket
                 // Push a frame every PUBLISH_INTERVAL_MS off the snapshot
                 // buffer. We don't dedupe: even when no field changed, the
@@ -733,6 +756,12 @@ class HudServer @Inject constructor(
             override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
                 Log.w(TAG, "HUD link failure: ${t.message} (${response?.code})")
                 log("Not found: ${t.message ?: t::class.simpleName}")
+                // Only an ESTABLISHED link dropping is a candidate channel-follow
+                // event; a failed dial (never opened) is just discovery missing.
+                if (wasOpen) {
+                    val correlated = wifiInterference.onHudDrop(System.currentTimeMillis())
+                    if (correlated) log("Drop correlated with a phone Wi-Fi change")
+                }
                 sendJob?.cancel()
                 ws = null
                 commandSink.onHudDisconnected()
@@ -749,6 +778,9 @@ class HudServer @Inject constructor(
     }
 
     private suspend fun snapshot(): HudState {
+        // Let the Wi-Fi-interference advisory decay once the link has been
+        // stable for a while (this runs every publish tick, ~5 Hz).
+        wifiInterference.onStableTick(System.currentTimeMillis())
         val s = settingsRepository.get()
         val wd = wheelRepository.wheelData.value
         val state = wheelRepository.connectionState.value
@@ -885,7 +917,8 @@ class HudServer @Inject constructor(
                         level = it.threatLevel.ordinal
                     )
                 }.orEmpty(),
-            timestampMs = System.currentTimeMillis()
+            timestampMs = System.currentTimeMillis(),
+            phoneWifiInterfering = wifiInterference.advisoryActive
         )
     }
 

hud-protocol/src/main/java/com/eried/eucplanet/hud/protocol/HudWire.kt

@@ -189,7 +189,16 @@ data class HudState(
      * and lets the dedup-by-content snapshot pipeline force a re-emit by
      * just bumping the timestamp when no other field changed.
      */
-    val timestampMs: Long = 0L
+    val timestampMs: Long = 0L,
+
+    /**
+     * True when the phone has detected that its OWN home/other Wi-Fi keeps
+     * interrupting the HUD link (single-radio STA+AP channel-follow): repeated
+     * HUD drops each landing right after one of the phone's Wi-Fi transitions.
+     * The HUD shows a rider-facing advisory ("turn phone Wi-Fi off for a stable
+     * link") when set. Added at PROTOCOL_MINOR 10; older HUDs ignore it.
+     */
+    val phoneWifiInterfering: Boolean = false
 ) {
     companion object {
         /**
@@ -217,8 +226,11 @@ data class HudState(
          * 9: added [HudCommand.Pair.recoveryNote] so the HUD can report its
          *    WiFi self-heal story back into the phone's shareable diagnostics.
          *    Older phones ignore the field; nothing else on the wire changed.
+         * 10: added [HudState.phoneWifiInterfering] so the phone can tell the
+         *    HUD to advise the rider that the phone's own Wi-Fi is interrupting
+         *    the link. Older HUDs ignore it.
          */
-        const val PROTOCOL_MINOR: Int = 9
+        const val PROTOCOL_MINOR: Int = 10
 
         /** Legacy alias. New code should read [PROTOCOL_MAJOR] / [PROTOCOL_MINOR]. */
         @Deprecated(

hud-protocol/src/main/java/com/eried/eucplanet/hud/protocol/LinkWatchdog.kt

@@ -44,20 +44,24 @@ object LinkWatchdog {
 
     /**
      * The recovery action to take for the Nth consecutive off-air recovery
-     * attempt. Escalates cheap -> aggressive and then alternates forever rather
+     * attempt. Escalates cheap -> decisive and then alternates forever rather
      * than ever surrendering -- the only alternative to "keep trying" is the
      * rider rebooting the HUD, which is the failure we are removing.
      *
      *   0      -> [RecoveryStep.RESTART_SOCKETS]  (re-resolve IP, restart
      *             beacon/mDNS/finder, bounce the WiFi lock; no radio state change)
-     *   odd    -> [RecoveryStep.REASSOCIATE]      (WifiManager.reconnect/reassociate)
-     *   even>0 -> [RecoveryStep.TOGGLE_WIFI]      (off/on; only effective pre-API29,
-     *             the caller falls back to REASSOCIATE where it is a no-op)
+     *   odd    -> [RecoveryStep.TOGGLE_WIFI]      (off/on; the DECISIVE rung,
+     *             front-loaded because a Motoeye E6 field log showed reassociate
+     *             alone did not clear the off-air state -- the toggle did. Only
+     *             effective pre-API29; the caller falls back to REASSOCIATE where
+     *             it is a no-op)
+     *   even>0 -> [RecoveryStep.REASSOCIATE]      (WifiManager.reconnect/reassociate;
+     *             cheap, fills the gaps, and the only effective path on API29+)
      */
     fun recoveryStepFor(attempt: Int): RecoveryStep = when {
         attempt <= 0 -> RecoveryStep.RESTART_SOCKETS
-        attempt % 2 == 1 -> RecoveryStep.REASSOCIATE
-        else -> RecoveryStep.TOGGLE_WIFI
+        attempt % 2 == 1 -> RecoveryStep.TOGGLE_WIFI
+        else -> RecoveryStep.REASSOCIATE
     }
 }
 

hud-protocol/src/main/java/com/eried/eucplanet/hud/protocol/WifiInterferenceDetector.kt

@@ -0,0 +1,70 @@
+package com.eried.eucplanet.hud.protocol
+
+/**
+ * Phone-side detector for "my own home/other Wi-Fi is interrupting the HUD".
+ *
+ * On a single-radio phone, every time the home-Wi-Fi STA changes state while
+ * the hotspot is up, the shared radio re-tunes and the live HUD link drops.
+ * The HUD only knows the hotspot, so the PHONE must detect this and tell it.
+ *
+ * The fingerprint: a HUD link drop that lands within [correlationWindowMs] of
+ * one of the phone's OWN Wi-Fi STA transitions (join / weaken / leave). A drop
+ * with no nearby Wi-Fi event (rode out of hotspot range, HUD glitch) is NOT
+ * counted, which is what keeps the advisory from false-firing. We require
+ * [minCorrelatedDrops] within [rollingWindowMs] before raising the advisory,
+ * and auto-clear it once the link has been stable for [clearAfterStableMs].
+ *
+ * Pure: the caller passes the clock ([nowMs]) so this is unit-testable and has
+ * no Android dependency. Not thread-safe; call from a single coroutine/thread.
+ */
+class WifiInterferenceDetector(
+    private val correlationWindowMs: Long = 20_000L,
+    private val minCorrelatedDrops: Int = 2,
+    private val rollingWindowMs: Long = 5 * 60_000L,
+    private val clearAfterStableMs: Long = 3 * 60_000L,
+) {
+    private var lastStaTransitionMs: Long = 0L
+    private val correlatedDropTimes = ArrayDeque<Long>()
+
+    /** True while we believe the phone's Wi-Fi is the thing dropping the HUD. */
+    var advisoryActive: Boolean = false
+        private set
+
+    /** The phone's home/other Wi-Fi STA just changed state (onAvailable /
+     *  onLosing / onLost of an internet-capable Wi-Fi network). */
+    fun onStaTransition(nowMs: Long) {
+        lastStaTransitionMs = nowMs
+    }
+
+    /** Record an established-link HUD drop. Returns true if it correlated with a
+     *  recent STA transition (i.e. it looks like channel-follow, not a plain
+     *  out-of-range drop). */
+    fun onHudDrop(nowMs: Long): Boolean {
+        val correlated = lastStaTransitionMs != 0L &&
+            nowMs - lastStaTransitionMs in 0..correlationWindowMs
+        if (correlated) {
+            correlatedDropTimes.addLast(nowMs)
+            prune(nowMs)
+            if (correlatedDropTimes.size >= minCorrelatedDrops) advisoryActive = true
+        }
+        return correlated
+    }
+
+    /** Call on a healthy/stable tick. Clears the advisory once the link has gone
+     *  [clearAfterStableMs] with no fresh correlated drop. */
+    fun onStableTick(nowMs: Long) {
+        prune(nowMs)
+        val lastDrop = correlatedDropTimes.lastOrNull()
+        if (advisoryActive && (lastDrop == null || nowMs - lastDrop >= clearAfterStableMs)) {
+            advisoryActive = false
+            correlatedDropTimes.clear()
+        }
+    }
+
+    private fun prune(nowMs: Long) {
+        while (correlatedDropTimes.isNotEmpty() &&
+            nowMs - correlatedDropTimes.first() > rollingWindowMs) {
+            correlatedDropTimes.removeFirst()
+        }
+    }
+}

hud-protocol/src/test/java/com/eried/eucplanet/hud/protocol/LinkWatchdogTest.kt

@@ -70,14 +70,19 @@ class LinkWatchdogTest {
 
     // ---- recovery ladder ------------------------------------------------
 
-    @Test fun ladder_starts_cheap_then_escalates_and_never_gives_up() {
+    @Test fun ladder_tries_cheap_then_front_loads_the_decisive_toggle() {
+        // One cheap socket restart first, then the WiFi toggle -- field logs
+        // (Motoeye E6, Android 7/8) showed reassociate alone did NOT clear the
+        // off-air state; the toggle is what recovered it, so it is reached on
+        // the very next rung instead of third. Reassociate fills the gaps
+        // (cheaper, and the effective path on API29+ where toggle is a no-op).
         assertEquals(RecoveryStep.RESTART_SOCKETS, LinkWatchdog.recoveryStepFor(0))
-        assertEquals(RecoveryStep.REASSOCIATE, LinkWatchdog.recoveryStepFor(1))
-        assertEquals(RecoveryStep.TOGGLE_WIFI, LinkWatchdog.recoveryStepFor(2))
-        // Past the toggle we keep alternating reassociate/toggle forever rather
-        // than surrendering -- the alternative is the rider rebooting anyway.
-        assertEquals(RecoveryStep.REASSOCIATE, LinkWatchdog.recoveryStepFor(3))
-        assertEquals(RecoveryStep.TOGGLE_WIFI, LinkWatchdog.recoveryStepFor(4))
+        assertEquals(RecoveryStep.TOGGLE_WIFI, LinkWatchdog.recoveryStepFor(1))
+        assertEquals(RecoveryStep.REASSOCIATE, LinkWatchdog.recoveryStepFor(2))
+        // Keep alternating toggle/reassociate forever rather than surrendering
+        // -- the alternative is the rider rebooting anyway.
+        assertEquals(RecoveryStep.TOGGLE_WIFI, LinkWatchdog.recoveryStepFor(3))
+        assertEquals(RecoveryStep.REASSOCIATE, LinkWatchdog.recoveryStepFor(4))
     }
 
     @Test fun ladder_clamps_negative_to_first_step() {

hud-protocol/src/test/java/com/eried/eucplanet/hud/protocol/WifiInterferenceDetectorTest.kt

@@ -0,0 +1,68 @@
+package com.eried.eucplanet.hud.protocol
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The phone-side "is my own Wi-Fi interrupting the HUD?" detector.
+ *
+ * Background: on a single-radio phone, every time the home-Wi-Fi STA changes
+ * state while the hotspot is up, the shared radio re-tunes and the live HUD
+ * link drops. The HUD can't see this (it only knows the hotspot), so the PHONE
+ * has to detect it and tell the HUD. The fingerprint is a HUD link drop that
+ * lands within a few seconds of one of the phone's OWN Wi-Fi transitions; a
+ * drop with no nearby Wi-Fi event (rode out of hotspot range, HUD glitch) is
+ * NOT this. We require it twice before speaking up, and auto-clear once stable.
+ *
+ * Pure (caller passes the clock) so it is unit-testable.
+ */
+class WifiInterferenceDetectorTest {
+
+    private fun det() = WifiInterferenceDetector(
+        correlationWindowMs = 20_000L,
+        minCorrelatedDrops = 2,
+        rollingWindowMs = 300_000L,
+        clearAfterStableMs = 60_000L,
+    )
+
+    @Test fun single_correlated_drop_does_not_trigger() {
+        val d = det()
+        d.onStaTransition(1_000L)
+        assertTrue("drop 4s after STA event is correlated", d.onHudDrop(5_000L))
+        assertFalse("one correlated drop must not raise the advisory", d.advisoryActive)
+    }
+
+    @Test fun two_correlated_drops_raise_the_advisory() {
+        val d = det()
+        d.onStaTransition(1_000L); d.onHudDrop(5_000L)
+        d.onStaTransition(30_000L); d.onHudDrop(40_000L)
+        assertTrue(d.advisoryActive)
+    }
+
+    @Test fun drop_without_a_recent_sta_transition_is_not_correlated() {
+        val d = det()
+        d.onStaTransition(1_000L)
+        assertFalse("drop 25s later is outside the 20s window", d.onHudDrop(26_000L))
+        assertFalse(d.onHudDrop(60_000L))
+        assertFalse(d.advisoryActive)
+    }
+
+    @Test fun advisory_clears_after_a_stable_period() {
+        val d = det()
+        d.onStaTransition(1_000L); d.onHudDrop(5_000L)
+        d.onStaTransition(10_000L); d.onHudDrop(15_000L)
+        assertTrue(d.advisoryActive)
+        d.onStableTick(15_000L + 60_000L + 1L)
+        assertFalse("stable for longer than clearAfterStableMs clears it", d.advisoryActive)
+    }
+
+    @Test fun advisory_persists_while_drops_keep_coming() {
+        val d = det()
+        d.onStaTransition(1_000L); d.onHudDrop(5_000L)
+        d.onStaTransition(10_000L); d.onHudDrop(15_000L)
+        assertTrue(d.advisoryActive)
+        d.onStableTick(20_000L) // only 5s since last drop -> not yet stable
+        assertTrue(d.advisoryActive)
+    }
+}

hud/build.gradle.kts

@@ -38,8 +38,8 @@ android {
         // Offset by 300000 so the HUD APK's version line never collides with
         // the phone (1..99999) or the wear companion (100000-prefixed) when
         // both are visible in the same release notes.
-        versionCode = 300009
-        versionName = "0.1.8"
+        versionCode = 300010
+        versionName = "0.1.9"
     }
 
     signingConfigs {

hud/src/main/java/com/eried/eucplanet/hud/net/HudServer.kt

@@ -89,15 +89,20 @@ class HudServer(private val context: Context) {
         private const val WAKE_LOCK_TAG = "eucplanet-hud:server"
         /** Faster watchdog cadence once the link looks unhealthy, so an
          *  off-air radio is detected and the recovery ladder escalates within
-         *  seconds instead of the lazy 10 s healthy interval. */
-        private const val RECOVERY_INTERVAL_MS: Long = 3_000L
+         *  seconds instead of the lazy 10 s healthy interval. Tightened from 3 s
+         *  to 1.5 s after a field log showed a real off-air recovery take ~34 s;
+         *  combined with the front-loaded toggle this brings a severe drop back
+         *  in ~8-12 s. */
+        private const val RECOVERY_INTERVAL_MS: Long = 1_500L
         /** Timeout for the "can I still reach the phone I was talking to"
          *  reachability probe. Short: the hotspot link is sub-10 ms when up. */
         private const val PEER_PROBE_TIMEOUT_MS: Int = 1_200
         /** Consecutive off-air ticks tolerated before the recovery ladder
-         *  starts. One grace tick rides out a single transient peer-probe miss
-         *  without kicking the radio. */
-        private const val OFF_AIR_GRACE_TICKS: Int = 1
+         *  starts. 0 = act on the first confirmed off-air tick: the first rung
+         *  ([RecoveryStep.RESTART_SOCKETS]) is harmless and the radio-touching
+         *  rungs still need the off-air state to persist across ticks, so there
+         *  is no churn risk -- but recovery starts a tick sooner. */
+        private const val OFF_AIR_GRACE_TICKS: Int = 0
     }
 
     /** Connection state surfaced to the UI status banner. */
@@ -683,7 +688,7 @@ class HudServer(private val context: Context) {
                     releaseWifiLock()
                     @Suppress("DEPRECATION")
                     runCatching { wifi?.isWifiEnabled = false }
-                    delay(1_500L)
+                    delay(1_000L)
                     @Suppress("DEPRECATION")
                     runCatching { wifi?.isWifiEnabled = true }
                     acquireWifiLock()