fix(voice): make calls actually deliver media — five root-cause fixes (#673)

Voice/video calls connected (roster visible) but no audio/video ever
reached the remote peer. Root-cause investigation
(docs/reports/2026-06-07-voice-media-connectivity-investigation.md)
found five independent, compounding bugs; all but cross-NAT traversal
are fixed here and proven by a new 2-peer Playwright media test.

RC0 — voice wire addressed by channel name, gates validate UUIDs.
VoiceJoin/VoiceLeave/VoiceSignal carried the UI's channel *name*, but
the SEC-V-03 existence gates check ServerState.channels (keyed by
UUID), so every voice message was dropped — presence and signaling
never crossed at all. The wire now carries the canonical channel_id:
senders resolve name->id (channel_id_for_voice), the listener gates
resolve id->name and keep voice state / ClientEvents name-keyed to
match the UI. Security tests updated to the UUID-on-wire contract.

RC2 — 4 KB SIGNALING_CAP silently dropped video SDP. Video offers
run 5-15 KB; unpack_wire discarded them post-decode so the offerer
never got an answer. VoiceSignal now has a dedicated 64 KB SDP_CAP
(still inside the 256 KB transport cap); oversize is still rejected.

RC3 — early remote ICE candidates were lost. addIceCandidate rejects
while remoteDescription is null (browsers don't buffer remote
candidates) and the rejection was swallowed with `let _`. Candidates
arriving before the offer/answer (gossip has no ordering; ICE handling
was synchronous while offer/answer were spawned) are now queued in a
per-peer PendingIceCandidates buffer and flushed after
setRemoteDescription resolves; rejections are logged.

RC4 — RefCell<VoiceManager> borrow held across await. The "safe on
single-threaded WASM, no preemption" comment was wrong: await is a
yield point, and a concurrent VoiceSignal task could double-borrow and
panic mid-negotiation. VoiceManager now owns its state behind interior
mutability with &self methods; the handle is Rc<VoiceManager> (no
outer RefCell), and the clippy::await_holding_refcell_ref allows are
gone, so the lint enforces the invariant from now on.

Perfect negotiation — the collision check tested only making_offer,
not signalingState != stable (the canonical MDN condition), which
breaks renegotiation (screen share added mid-call). Extracted as the
pure should_ignore_offer(polite, making_offer, stable) and fixed.
Also: self-offer filter (don't offer to our own echoed VoiceJoin),
ICE/connection state-change logging (failures were invisible), and
TURN credential plumbing — build_rtc_config only ever set urls, so it
could not drive TURN even if configured; a new
window.__WILLOW_ICE_SERVERS knob carries {urls, username, credential}
(legacy __WILLOW_STUN_URLS still honored).

NOT fixed here (follow-up, needs infra + spec): cross-NAT traversal.
iceServers stays empty by default (privacy-first, issue #179); the
plan is self-hosted coturn beside the relay — see the report's
recommendation. Same-host/LAN calls work without it; the "iroh relay
path for ICE" idea was researched and is infeasible for browsers
(relay-only WebSocket, not TURN/ICE-compatible).

Tests: ~10 KB SDP wire round-trip (native); ICE buffer, collision
rule, TURN credential propagation, ICE-server config knobs
(wasm-pack); new e2e/voice-video.spec.ts under a voice-chrome
Playwright project with fake media devices proving remote audio both
ways + screen-share renegotiation over a real RTCPeerConnection.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: intendednull

crates/client/src/listeners.rs

@@ -644,19 +644,24 @@ pub(crate) async fn process_received_message<T: TopicHandle>(
             // per channel) dimensions of `VoiceState.participants`.
             // Without these gates, any signed peer can flood arbitrary
             // `channel_id`s and exhaust receiving clients' memory.
-            let known = willow_actor::state::select(&ctx.event_state, {
+            //
+            // The wire carries the canonical `channel_id` (UUID); voice state
+            // and UI events are keyed by the channel *name* (the whole UI is
+            // name-keyed). Resolve id -> name here: `None` both fails the
+            // existence gate and means "unknown channel".
+            let name = willow_actor::state::select(&ctx.event_state, {
                 let ch = channel_id.clone();
-                move |es| es.channels.contains_key(&ch)
+                move |es| es.channels.get(&ch).map(|c| c.name.clone())
             })
             .await;
-            if !known {
+            let Some(name) = name else {
                 tracing::debug!(
                     %signer, channel_id = %channel_id,
                     "dropping VoiceJoin: channel_id not in ServerState.channels"
                 );
                 return;
-            }
-            let ch = channel_id.clone();
+            };
+            let ch = name.clone();
             let inserted = willow_actor::state::mutate(&ctx.voice, move |v| {
                 let new_channel = !v.participants.contains_key(&ch);
                 if new_channel && v.participants.len() >= MAX_VOICE_CHANNELS {
@@ -680,7 +685,7 @@ pub(crate) async fn process_received_message<T: TopicHandle>(
             warn_if_err(
                 ctx.event_broker
                     .do_send(willow_actor::Publish(ClientEvent::VoiceJoined {
-                        channel_id,
+                        channel_id: name,
                         peer_id,
                     })),
                 "event_broker.do_send Publish(VoiceJoined)",
@@ -695,19 +700,21 @@ pub(crate) async fn process_received_message<T: TopicHandle>(
             // UI. The `participants` map is unaffected even without the
             // gate (`get_mut` returns None), but the event-broker fanout
             // would still leak attacker-controlled `channel_id`s.
-            let known = willow_actor::state::select(&ctx.event_state, {
+            // Resolve the wire `channel_id` (UUID) to the name used by voice
+            // state + UI events; `None` fails the existence gate.
+            let name = willow_actor::state::select(&ctx.event_state, {
                 let ch = channel_id.clone();
-                move |es| es.channels.contains_key(&ch)
+                move |es| es.channels.get(&ch).map(|c| c.name.clone())
             })
             .await;
-            if !known {
+            let Some(name) = name else {
                 tracing::debug!(
                     %signer, channel_id = %channel_id,
                     "dropping VoiceLeave: channel_id not in ServerState.channels"
                 );
                 return;
-            }
-            let ch = channel_id.clone();
+            };
+            let ch = name.clone();
             willow_actor::state::mutate(&ctx.voice, move |v| {
                 if let Some(p) = v.participants.get_mut(&ch) {
                     p.remove(&peer_id);
@@ -717,7 +724,7 @@ pub(crate) async fn process_received_message<T: TopicHandle>(
             warn_if_err(
                 ctx.event_broker
                     .do_send(willow_actor::Publish(ClientEvent::VoiceLeft {
-                        channel_id,
+                        channel_id: name,
                         peer_id,
                     })),
                 "event_broker.do_send Publish(VoiceLeft)",
@@ -734,22 +741,22 @@ pub(crate) async fn process_received_message<T: TopicHandle>(
                 // event handlers. Signals do not mutate `participants`
                 // directly, but the existence check shuts the same fanout
                 // gap as Join/Leave.
-                let known = willow_actor::state::select(&ctx.event_state, {
+                let name = willow_actor::state::select(&ctx.event_state, {
                     let ch = channel_id.clone();
-                    move |es| es.channels.contains_key(&ch)
+                    move |es| es.channels.get(&ch).map(|c| c.name.clone())
                 })
                 .await;
-                if !known {
+                let Some(name) = name else {
                     tracing::debug!(
                         %signer, channel_id = %channel_id,
                         "dropping VoiceSignal: channel_id not in ServerState.channels"
                     );
                     return;
-                }
+                };
                 warn_if_err(
                     ctx.event_broker
                         .do_send(willow_actor::Publish(ClientEvent::VoiceSignal {
-                            channel_id,
+                            channel_id: name,
                             from_peer: signer,
                             signal,
                         })),
@@ -1604,6 +1611,18 @@ mod tests {
             .expect("test_client must seed at least one channel")
     }
 
+    /// The display name of the first seeded channel. Voice state + events are
+    /// keyed by name (the wire carries the UUID `channel_id`, which the
+    /// listener resolves to this name), so state assertions look up by name.
+    async fn known_channel_name<N: willow_network::Network>(client: &ClientHandle<N>) -> String {
+        let snap = client.state_snapshot().await;
+        snap.channels
+            .values()
+            .next()
+            .map(|c| c.name.clone())
+            .expect("test_client must seed at least one channel")
+    }
+
     /// VoiceJoin against an unknown `channel_id` must not mutate
     /// `VoiceState.participants` (defends against attackers flooding
     /// random channel ids until memory is exhausted).
@@ -1652,7 +1671,10 @@ mod tests {
             .await
             .expect("subscribe must succeed");
         let ctx = make_ctx(&client);
+        // Wire is addressed by canonical channel_id (UUID); voice state is
+        // keyed by the resolved channel name.
         let channel_id = known_channel_id(&client).await;
+        let channel_name = known_channel_name(&client).await;
 
         let attacker = willow_identity::Identity::generate();
         let attacker_id = attacker.endpoint_id();
@@ -1665,7 +1687,7 @@ mod tests {
 
         let stored = poll_until_some(
             || {
-                let ch = channel_id.clone();
+                let ch = channel_name.clone();
                 willow_actor::state::select(&client.voice_state_addr, move |v| {
                     v.participants
                         .get(&ch)
@@ -1679,7 +1701,7 @@ mod tests {
         assert_eq!(
             stored,
             Some(1),
-            "VoiceJoin on a known channel must record the participant"
+            "VoiceJoin on a known channel must record the participant (keyed by name)"
         );
     }
 
@@ -1748,10 +1770,12 @@ mod tests {
             .await
             .expect("subscribe must succeed");
         let ctx = make_ctx(&client);
+        // Wire is addressed by channel_id (UUID); state is keyed by name.
         let channel_id = known_channel_id(&client).await;
+        let channel_name = known_channel_name(&client).await;
 
-        // Fill the cap with synthetic participants on the real channel.
-        let cap_channel = channel_id.clone();
+        // Fill the cap with synthetic participants on the real channel (by name).
+        let cap_channel = channel_name.clone();
         willow_actor::state::mutate(&client.voice_state_addr, move |v| {
             let set = v.participants.entry(cap_channel).or_default();
             for _ in 0..MAX_PARTICIPANTS_PER_CHANNEL {
@@ -1763,7 +1787,7 @@ mod tests {
         // Confirm preconditions.
         let pre = voice_snapshot(&client).await;
         assert_eq!(
-            pre.participants.get(&channel_id).map(|s| s.len()),
+            pre.participants.get(&channel_name).map(|s| s.len()),
             Some(MAX_PARTICIPANTS_PER_CHANNEL),
             "test setup must fill participants to cap"
         );
@@ -1781,7 +1805,7 @@ mod tests {
         let snap = voice_snapshot(&client).await;
         let set = snap
             .participants
-            .get(&channel_id)
+            .get(&channel_name)
             .expect("channel set must still exist");
         assert_eq!(
             set.len(),

crates/client/src/mutations.rs

@@ -156,6 +156,30 @@ impl<N: willow_network::Network> ClientMutations<N> {
         channel_id.ok_or_else(|| anyhow::anyhow!("channel not found: {channel}"))
     }
 
+    /// Resolve a channel reference (already a `channel_id`, or a display name)
+    /// to the canonical `channel_id` (UUID) used on the wire.
+    ///
+    /// Voice signaling (`VoiceJoin`/`VoiceLeave`/`VoiceSignal`) must address
+    /// channels by their canonical id so the receiver's existence gate — which
+    /// validates against `ServerState.channels` (keyed by id) — accepts them.
+    /// The UI keys voice state by name, so this accepts either form: an exact
+    /// id match wins, otherwise it falls back to a name lookup. Returns `None`
+    /// if the channel is unknown.
+    pub(crate) async fn channel_id_for_voice(&self, channel: &str) -> Option<String> {
+        let ch = channel.to_string();
+        willow_actor::state::select(&self.event_state, move |es| {
+            if es.channels.contains_key(&ch) {
+                Some(ch.clone())
+            } else {
+                es.channels
+                    .iter()
+                    .find(|(_, c)| c.name == ch)
+                    .map(|(id, _)| id.clone())
+            }
+        })
+        .await
+    }
+
     /// Sync event_state mirror from ManagedDag, persist, and emit
     /// ClientEvents. Called after build_event succeeds — ManagedDag has
     /// already applied the event to its internal state atomically.
@@ -699,21 +723,33 @@ impl<N: willow_network::Network> ClientMutations<N> {
 
 impl<N: willow_network::Network> ClientMutations<N> {
     /// Join a voice channel.
-    pub async fn join_voice(&self, channel_id: &str) {
+    ///
+    /// `channel` is a channel name (the UI's identifier) or a `channel_id`.
+    /// Local voice state stays keyed by the channel *name* (consistent with the
+    /// name-keyed UI); the broadcast `VoiceJoin` carries the canonical
+    /// `channel_id` (UUID) so remote peers' existence gate accepts it.
+    pub async fn join_voice(&self, channel: &str) {
         let in_voice =
             willow_actor::state::select(&self.voice, |v| v.active_channel.is_some()).await;
         if in_voice {
             self.leave_voice().await;
         }
-        let ch = channel_id.to_string();
+        // Local voice state is keyed by the caller's reference (the UI's
+        // channel name), so the UI — which reads the same key — matches.
         let my_peer_id = self.identity.endpoint_id();
+        let ch = channel.to_string();
         willow_actor::state::mutate(&self.voice, move |v| {
             v.active_channel = Some(ch.clone());
             v.participants.entry(ch).or_default().insert(my_peer_id);
         })
         .await;
+        // Broadcast addressed by canonical channel_id so peers accept it.
+        let Some(channel_id) = self.channel_id_for_voice(channel).await else {
+            tracing::warn!(%channel, "join_voice: unknown channel, not broadcasting");
+            return;
+        };
         let msg = ops::WireMessage::VoiceJoin {
-            channel_id: channel_id.to_string(),
+            channel_id,
             peer_id: my_peer_id,
         };
         if let Some(data) = ops::pack_wire(&msg, &self.identity) {
@@ -736,8 +772,14 @@ impl<N: willow_network::Network> ClientMutations<N> {
         })
         .await;
         if let Some(ch) = maybe_ch {
+            // `ch` is the local key (channel name); address the wire message
+            // by canonical channel_id so peers' existence gate accepts it.
+            let Some(channel_id) = self.channel_id_for_voice(&ch).await else {
+                tracing::warn!(channel = %ch, "leave_voice: unknown channel, not broadcasting");
+                return;
+            };
             let msg = ops::WireMessage::VoiceLeave {
-                channel_id: ch,
+                channel_id,
                 peer_id: my_peer_id,
             };
             if let Some(data) = ops::pack_wire(&msg, &self.identity) {

crates/client/src/voice.rs

@@ -40,14 +40,23 @@ impl<N: willow_network::Network> ClientHandle<N> {
         willow_actor::state::select(&self.voice_state_addr, |v| v.deafened).await
     }
 
-    pub fn send_voice_signal(
+    /// Send a WebRTC signaling message to a peer.
+    ///
+    /// `channel` is the UI's channel reference (name) or a `channel_id`; it is
+    /// resolved to the canonical `channel_id` (UUID) so the receiver's
+    /// existence gate accepts it. Async because resolution reads event state.
+    pub async fn send_voice_signal(
         &self,
-        channel_id: &str,
+        channel: &str,
         target: willow_identity::EndpointId,
         signal: ops::VoiceSignalPayload,
     ) {
+        let Some(channel_id) = self.mutation_handle.channel_id_for_voice(channel).await else {
+            tracing::warn!(%channel, "send_voice_signal: unknown channel");
+            return;
+        };
         let msg = ops::WireMessage::VoiceSignal {
-            channel_id: channel_id.to_string(),
+            channel_id,
             target_peer: target,
             signal,
         };