Merge branch 'code/majorair/iphone-mirroring-doc-update'

05-troubleshooting/iphone-mirroring-connecting-hang-awdl-stall-beta.md

@@ -2,14 +2,52 @@
 title: "iPhone Mirroring Hangs on 'Connecting…' — AWDL Data Stall (27.0 Beta)"
 domain: troubleshooting
 category: macos
-tags: [macos, iphone-mirroring, continuity, awdl, rapport, quic, tailscale, mullvad, beta]
+tags: [macos, iphone-mirroring, continuity, awdl, rapport, quic, tailscale, mullvad, beta, channel-validation, aimesh, quicktime, usb]
 status: published
 created: 2026-06-09
-updated: 2026-06-09
+updated: 2026-06-14
 ---
 
 # iPhone Mirroring Hangs on 'Connecting…' — AWDL Data Stall (27.0 Beta)
 
+## Update 2026‑06‑14 — root cause refined (and what is *not* the cause)
+
+> Re‑investigated end‑to‑end on the **same OS seed** (build `26A5353q`, unchanged). The original "AWDL data stall / nothing local was wrong" call was close but mis‑attributed the secondary causes. Corrected understanding below — **practical outcome is unchanged: no user‑side fix, wait for a new seed.**
+
+**Refined root cause — the AWDL _bulk‑data_ path can't hold a 5 GHz channel.**
+Pulled the iPhone's own logs over USB (`sudo log collect --device --last 8m --output ~/Desktop/x.logarchive`). The kernel Wi‑Fi driver (`AppleBCMWLAN`, `wlan0:com.apple.p2p.awdl0`) shows, over 8 min on infra channel 36:
+- `isValidChannel … not match … channel 36 band 0x10` — **238×** (vs 32 passes): AWDL rejects the channel for the P2P group.
+- `Disable Steering on Timeout` — **159×**: can't steer to a better channel.
+- `isInfraRealtimePacketThresholdAllowed allowed:0` — **169/451**: bulk realtime packets blocked ~37 % of the time.
+
+Net: the Mac's `awdl0` carries **~90 B/s** (control keepalive only; real video is hundreds of KB/s–MB/s). The feed is **starved, not corrupted** — "missing icons" = frame data that never arrived (zero decode/`kVT` errors logged).
+
+**What is NOT the cause (each tested and ruled out):**
+- **Tailscale is not a hard RF blocker.** With accept‑routes on but **no exit node**, mirroring connects. Tailscale only *intermittently* breaks the **control plane** (QUIC endpoint binding → "Connection Interrupted"); with Tailscale **off** the session establishes but the **bulk video still starves**. So the old "disable Tailscale" step lets you *connect* but does **not** fix the video. (Mechanism is control‑plane endpoint flapping, not the RF‑layer block the original note implied.)
+- **Not congestion.** Router `chanim_stats` on ch36 = **90 % idle, 86 % txop, 3 % obss**; Mac link −39 dBm / −94 dBm noise. Pristine.
+- **Not the channel number — the whole UNII‑1 block is AWDL‑hostile on this seed.** ch36 → starved feed (~90 B/s, glitchy). **ch44** (same 36–48 block) → **worse**: times out before media starts (`Failed to find endpoint`, `MediaContinuityKit.TaskTimeoutError`, 0 B/s). Both fail → the validator rejects the entire UNII‑1 block, not just primary 36.
+- **ch149 (UNII‑3) untested.** It's the iPhone's preferred AWDL anchor and a *different* block, so it's the one channel that might work — but it's busier and the AiMesh controller resists pinning it (see infra notes). Deferred as not worth the disruption for a beta bug.
+
+**Wired workaround (works today, no AWDL):**
+iPhone Mirroring is **wireless‑only — there is no USB transport** (confirmed: cable connected throughout, every attempt still used `awdl0`). For a wired view of the screen:
+> **QuickTime Player → File → New Movie Recording → ⌄ next to record → select the iPhone** = full‑rate USB‑C screen mirror (view + record). Does **not** give remote control (tap/type) — that's unique to iPhone Mirroring.
+
+**Infra notes (RT‑AX82U, AiMesh controller):**
+- Router SSH is on **port 1025** (not 22); creds in Ansible vault (`router_username` / `router_password`).
+- The 5 GHz channel is **AiMesh‑coordinated** and **resists CLI changes** — `wl chanspec` / nvram `wl1_chanspec` get re‑asserted by `acsd2` + AiMesh within seconds, even after `restart_wireless`. Only setting Control Channel to an **explicit value in the Web UI** holds mesh‑wide. Left "Auto" → acsd2 picks **36** (the cleanest channel).
+- Any channel change triggers a **mesh re‑sync (~1 min) that drops all Wi‑Fi**; during it MajorAir falls back to the iPhone's **USB Personal Hotspot** (`en7` / `172.20.10.x`) and won't auto‑rejoin home Wi‑Fi while the hotspot feeds it internet (manual Wi‑Fi‑menu join needed).
+- **Current state: 5 GHz on ch44/80** (same clean UNII‑1 spectrum as 36; left here to avoid another re‑sync — the Deck streams identically on 44).
+
+**Revisit checklist — when a new iOS/macOS seed ships:**
+1. Confirm the seed changed: `sw_vers` BuildVersion ≠ `26A5353q` (both Mac and iPhone).
+2. Tailscale **off**; iPhone on home Wi‑Fi, near the Mac, **Personal Hotspot off**.
+3. Open iPhone Mirroring.
+4. Measure `awdl0` RX over a few seconds — **target hundreds of KB/s** (real video), not ~90 B/s.
+5. Pull the iPhone log (`log collect --device`) and check `isValidChannel` now **passes** for the infra channel.
+6. If still starved → no user fix; re‑file Feedback Assistant and keep waiting.
+
+---
+
 ## Symptom
 iPhone Mirroring on the Mac sits on **"Connecting…"** forever and never shows the iPhone screen.
 - Mac: **macOS 27.0 dev beta** (build 26A5353q), MajorAir