From 8c48402585eda3561d61391af60dbae694ffca0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Lucas?=
 <55464917+jlucaso1@users.noreply.github.com>
Date: Thu, 16 Jul 2026 22:25:25 -0300
Subject: [PATCH 1/3] fix(voip): serialize video upgrade transitions

---
 Cargo.toml                    |   2 +-
 examples/voip-cli/src/main.rs |  90 +++++--
 src/client/voip.rs            |   4 +
 src/handlers/call.rs          | 288 ++++++++++++++++------
 src/voip/facade.rs            | 406 +++++++++++++++++++++++++-----
 src/voip/mod.rs               |   2 +-
 wacore/src/types/call.rs      |  30 +++
 wacore/src/voip/engine.rs     |   6 +-
 wacore/src/voip/mod.rs        |   2 +-
 wacore/src/voip/registry.rs   | 451 ++++++++++++++++++++++++++++++++++
 10 files changed, 1118 insertions(+), 163 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index cf9aedf55..7579620f5 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -221,7 +221,7 @@ hmac = { workspace = true }
 libc = "0.2"
 metrics-exporter-prometheus = "0.18"
 sha2 = { workspace = true }
-tokio = { workspace = true, features = ["full"] }
+tokio = { workspace = true, features = ["full", "test-util"] }
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 uuid = { workspace = true, features = ["v4"] }
 wacore = { workspace = true, features = ["test-util"] }
diff --git a/examples/voip-cli/src/main.rs b/examples/voip-cli/src/main.rs
index b35eba802..9ab93b6f9 100644
--- a/examples/voip-cli/src/main.rs
+++ b/examples/voip-cli/src/main.rs
@@ -55,7 +55,7 @@ use whatsapp_rust::voip::audio::{WaOpusDecoder, WaOpusEncoder};
 use whatsapp_rust::voip::session::{MediaPipeline, MediaPipelineParams};
 #[cfg(feature = "voip-opus")]
 use whatsapp_rust::voip::{AudioCodec, EncodedAudioFrame};
-use whatsapp_rust::voip::{AudioFormat, CallHandle, VideoState};
+use whatsapp_rust::voip::{AudioFormat, CallHandle, VideoState, VideoUpgradeToken};
 
 mod video;
 use video::VideoOpts;
@@ -977,7 +977,7 @@ struct CallState {
 #[derive(Clone, Copy, PartialEq)]
 enum VideoUi {
     /// The peer asked for video (`UpgradeRequestV2`); `v` accepts it.
-    PendingPeerRequest,
+    PendingPeerRequest(VideoUpgradeToken),
     /// Our video plane is up; `v` downgrades.
     Active,
 }
@@ -1080,12 +1080,14 @@ impl EventHandler for CallObserver {
                     let audio = self.audio;
                     // Only answer with video when we're allowed to AND the offer is actually a video
                     // call; advertising `<video>` on an audio offer would be wrong.
-                    let video = self.video && *is_video;
+                    let initial_video = self.video && *is_video;
+                    let auto_video = self.video;
                     let state = self.state.clone();
                     let cid = call_id.clone();
                     begin_call_startup(&state, &cid);
                     tokio::spawn(async move {
-                        if let Err(e) = respond_to_offer(&client, &call, accept, video, audio).await
+                        if let Err(e) =
+                            respond_to_offer(&client, &call, accept, initial_video, audio).await
                         {
                             error!("call signaling failed: {e}");
                             complete_call_startup(&state, &cid);
@@ -1095,7 +1097,9 @@ impl EventHandler for CallObserver {
                             complete_call_startup(&state, &cid);
                             return;
                         }
-                        match start_media(&client, &call, video, audio, &state).await {
+                        match start_media(&client, &call, initial_video, auto_video, audio, &state)
+                            .await
+                        {
                             Ok(handle) => register_handle(&state, cid.clone(), handle).await,
                             Err(e) => {
                                 let peer_ended = peer_terminated_during_startup(&state, &cid);
@@ -1141,7 +1145,8 @@ impl EventHandler for CallObserver {
 async fn start_media(
     client: &Arc<Client>,
     call: &IncomingCall,
-    video: bool,
+    initial_video: bool,
+    auto_video: bool,
     audio: AudioMode,
     state: &Arc<Mutex<CallState>>,
 ) -> Result<Arc<CallHandle>> {
@@ -1149,7 +1154,7 @@ async fn start_media(
     let speaker = spawn_speaker()?;
     let event_speaker = speaker.clone();
     info!("🔌 connecting media via client.voip().accept(..)…");
-    let video_endpoints = if video {
+    let video_endpoints = if initial_video {
         let opts = VideoOpts::from_env().await?;
         let cid = call.action.call_id();
         Some((
@@ -1162,7 +1167,7 @@ async fn start_media(
     if peer_terminated_during_startup(state, call.action.call_id()) {
         bail!("peer ended the call during media preparation");
     }
-    send_final_accept(client, call, video, audio).await?;
+    send_final_accept(client, call, initial_video, audio).await?;
     let voip = client.voip();
     let mut builder = match audio {
         #[cfg(feature = "voip-mlow")]
@@ -1185,13 +1190,13 @@ async fn start_media(
         "🎙  {} media flow live for call {} — speak into the mic.{}",
         audio.name(),
         handle.call_id(),
-        if video { " 🎥 video on." } else { "" }
+        if initial_video { " 🎥 video on." } else { "" }
     );
     let handle = Arc::new(handle);
-    if video {
+    if initial_video {
         mark_video(state, handle.call_id(), Some(VideoUi::Active));
     }
-    spawn_call_event_listener(handle.clone(), event_speaker, video, state.clone());
+    spawn_call_event_listener(handle.clone(), event_speaker, auto_video, state.clone());
     Ok(handle)
 }
 
@@ -1258,6 +1263,27 @@ fn mark_video(state: &Arc<Mutex<CallState>>, call_id: &str, ui: Option<VideoUi>)
     }
 }
 
+fn clear_pending_peer_video(state: &Arc<Mutex<CallState>>, call_id: &str) {
+    let mut st = lock_call_state(state);
+    if matches!(
+        st.video_ui.get(call_id),
+        Some(VideoUi::PendingPeerRequest(_))
+    ) {
+        st.video_ui.remove(call_id);
+    }
+}
+
+fn activate_peer_video_request(
+    state: &Arc<Mutex<CallState>>,
+    call_id: &str,
+    request: VideoUpgradeToken,
+) {
+    let mut st = lock_call_state(state);
+    if st.video_ui.get(call_id) == Some(&VideoUi::PendingPeerRequest(request)) {
+        st.video_ui.insert(call_id.to_string(), VideoUi::Active);
+    }
+}
+
 /// Surface call diagnostics and drive the video upgrade handshake.
 fn spawn_call_event_listener(
     handle: Arc<CallHandle>,
@@ -1380,25 +1406,47 @@ fn spawn_call_event_listener(
                         "🎥 relay-send backpressure: dropped {video_access_units} complete video AUs / {packets} packets"
                     );
                 }
-                CallEvent::VideoStateChanged { state: vs, .. } => match vs {
+                CallEvent::VideoStateChanged {
+                    state: vs,
+                    upgrade_token,
+                    ..
+                } => match vs {
                     VideoState::UpgradeRequest | VideoState::UpgradeRequestV2 => {
+                        let Some(request) = upgrade_token else {
+                            warn!("peer video request arrived without an acceptance token");
+                            continue;
+                        };
+                        mark_video(
+                            &state,
+                            handle.call_id(),
+                            Some(VideoUi::PendingPeerRequest(request)),
+                        );
                         if auto_video {
                             info!("🎥 peer asked for video — auto-accepting (--video)");
-                            if let Err(e) = accept_peer_video(&handle).await {
+                            if let Err(e) = accept_peer_video(&handle, request).await {
                                 warn!("accepting peer video failed: {e}");
                             } else {
-                                mark_video(&state, handle.call_id(), Some(VideoUi::Active));
+                                activate_peer_video_request(&state, handle.call_id(), request);
                             }
                         } else {
                             info!("🎥 peer asked for video — press `v` + Enter to accept");
-                            mark_video(&state, handle.call_id(), Some(VideoUi::PendingPeerRequest));
                         }
                     }
                     VideoState::UpgradeAccept | VideoState::Enabled => {
                         info!("🎥 peer video {vs:?} — inbound video should start flowing");
                     }
-                    VideoState::Stopped | VideoState::Disabled => {
+                    VideoState::Stopped => {
                         info!("🎥 peer stopped its video");
+                        clear_pending_peer_video(&state, handle.call_id());
+                    }
+                    VideoState::Disabled
+                    | VideoState::UpgradeReject
+                    | VideoState::UpgradeRejectByTimeout
+                    | VideoState::UpgradeCancel
+                    | VideoState::UpgradeCancelByTimeout
+                    | VideoState::Error => {
+                        info!("🎥 video upgrade ended ({vs:?})");
+                        mark_video(&state, handle.call_id(), None);
                     }
                     other => info!("🎥 peer video state: {other:?}"),
                 },
@@ -1410,12 +1458,12 @@ fn spawn_call_event_listener(
 }
 
 /// Fresh ffmpeg/ffplay endpoints for a mid-call upgrade/accept on `handle`.
-async fn accept_peer_video(handle: &CallHandle) -> Result<()> {
+async fn accept_peer_video(handle: &CallHandle, request: VideoUpgradeToken) -> Result<()> {
     let opts = VideoOpts::from_env().await?;
     let src = video::spawn_video_source(&opts).await?;
     let sink = video::spawn_video_sink(&opts, handle.call_id()).await?;
     handle
-        .accept_video(src, sink)
+        .accept_video(request, src, sink)
         .await
         .map_err(|e| anyhow!("accept_video: {e}"))
 }
@@ -1580,12 +1628,12 @@ fn spawn_stdin_ui(client: Arc<Client>, state: Arc<Mutex<CallState>>) {
                             mark_video(&state, &cid, None);
                         }
                     }
-                    Some(VideoUi::PendingPeerRequest) => {
+                    Some(VideoUi::PendingPeerRequest(request)) => {
                         info!("🎥 accepting the peer's video request");
-                        if let Err(e) = accept_peer_video(&handle).await {
+                        if let Err(e) = accept_peer_video(&handle, request).await {
                             warn!("accept_video failed: {e}");
                         } else {
-                            mark_video(&state, &cid, Some(VideoUi::Active));
+                            activate_peer_video_request(&state, &cid, request);
                         }
                     }
                     None => {
diff --git a/src/client/voip.rs b/src/client/voip.rs
index 432aafab9..c134c7fef 100644
--- a/src/client/voip.rs
+++ b/src/client/voip.rs
@@ -68,6 +68,10 @@ pub enum CallError {
     #[cfg(feature = "voip-runtime")]
     #[error("media offer error: {0}")]
     Media(&'static str),
+    /// The peer cancelled or replaced the upgrade before its video source became ready.
+    #[cfg(feature = "voip-runtime")]
+    #[error("video upgrade request is no longer current")]
+    VideoUpgradeExpired,
     /// `call(peer)` resolved zero devices for the peer (nothing to address an offer to).
     #[cfg(feature = "voip-runtime")]
     #[error("peer has no resolvable devices")]
diff --git a/src/handlers/call.rs b/src/handlers/call.rs
index f295e5269..d95ebc4a4 100644
--- a/src/handlers/call.rs
+++ b/src/handlers/call.rs
@@ -14,7 +14,7 @@ use wacore::types::call::{CallAction, IncomingCall, MissedCall, MissedReason};
 use wacore::types::call::{CallEndedElsewhere, ElsewhereOutcome, VideoState};
 use wacore::types::events::Event;
 #[cfg(feature = "voip-runtime")]
-use wacore::voip::{CallEvent, VideoControl};
+use wacore::voip::{CallEvent, PeerVideoTransition, VideoControl};
 #[cfg(feature = "voip-runtime")]
 use wacore_binary::Jid;
 use wacore_binary::{OwnedNodeRef, Server};
@@ -220,15 +220,25 @@ impl StanzaHandler for CallHandler {
                     {
                         let call_id = call.action.call_id();
                         let registry = client.call_registry();
-                        let event_permit = registry.reserve_call_event(call_id);
-                        let generation = event_permit.as_ref().map(|permit| permit.generation());
+                        let Some((generation, transition_lock)) =
+                            registry.current_video_transition(call_id)
+                        else {
+                            warn!(
+                                "call: video state has no active call; leaving the transition unacknowledged"
+                            );
+                            return true;
+                        };
+                        let _transition_guard = transition_lock.lock().await;
+                        let event_permit = registry
+                            .is_current(call_id, generation)
+                            .then(|| registry.reserve_call_event(call_id))
+                            .flatten()
+                            .filter(|permit| permit.generation() == generation);
                         if event_permit.is_none() {
                             warn!(
                                 "call: video state event queue is unavailable; leaving the transition unacknowledged"
                             );
                         }
-                        // A typed ack commits the received transition. Without an event permit,
-                        // leave the generic ack in place so the peer reverts instead.
                         let acked = if event_permit.is_some() {
                             match build_call_video_ack(&call, nr) {
                                 Some(ack) => {
@@ -251,87 +261,127 @@ impl StanzaHandler for CallHandler {
                         } else {
                             false
                         };
-                        let mut transition_current = acked
-                            && generation
-                                .is_some_and(|generation| registry.is_current(call_id, generation));
-                        dispatch_call = transition_current;
-                        // Rejection ends our attempted upgrade locally even when its ack cannot get
-                        // out; retaining the camera cannot help a negotiation the peer already ended.
-                        if matches!(state, VideoState::UpgradeReject | VideoState::UpgradeCancel)
-                            && let Some(generation) = generation
-                        {
-                            registry.run_video_teardown(call_id, generation);
-                            registry.set_is_video(call_id, generation, false);
-                        }
-                        // Only drive our local plane once the peer has been acked; see above.
-                        if transition_current && let Some(generation) = generation {
-                            if *state == VideoState::UpgradeAccept
-                                && registry.is_current(call_id, generation)
-                            {
-                                let enabled = build_video_state(&VideoStateParams {
-                                    call_id,
-                                    to: &call.from,
-                                    id: &client.generate_request_id(),
-                                    call_creator: call.action.call_creator(),
-                                    state: VideoState::Enabled,
-                                    dec: None,
-                                    device_orientation: None,
-                                });
-                                if let Err(e) = client.send_node(enabled).await {
-                                    warn!("call: failed to announce accepted video upgrade: {e}");
-                                    if !registry.run_video_teardown(call_id, generation) {
-                                        registry.send_video_ctl(
-                                            call_id,
-                                            generation,
-                                            VideoControl::Disable,
-                                        );
-                                    }
-                                    registry.set_is_video(call_id, generation, false);
-                                    transition_current = false;
-                                }
+                        let mut transition_current =
+                            acked && registry.is_current(call_id, generation);
+                        let transition = if transition_current
+                            || matches!(
+                                state,
+                                VideoState::UpgradeReject
+                                    | VideoState::UpgradeRejectByTimeout
+                                    | VideoState::UpgradeCancel
+                                    | VideoState::UpgradeCancelByTimeout
+                                    | VideoState::Disabled
+                                    | VideoState::Error
+                            ) {
+                            registry.apply_peer_video_state(call_id, generation, *state)
+                        } else {
+                            PeerVideoTransition::Ignored
+                        };
+
+                        let mut upgrade_token = None;
+                        match transition {
+                            PeerVideoTransition::Ignored => {
+                                transition_current = false;
+                            }
+                            PeerVideoTransition::UpgradeRequested(token) => {
+                                upgrade_token = Some(token);
                             }
-                            transition_current &= registry.is_current(call_id, generation);
-                            if transition_current {
-                                if let Some(o) = orientation {
+                            PeerVideoTransition::Applied {
+                                enable_plane,
+                                teardown_local,
+                                answer_upgrade,
+                            } => {
+                                if teardown_local
+                                    && !registry.run_video_teardown(call_id, generation)
+                                {
                                     registry.send_video_ctl(
                                         call_id,
                                         generation,
-                                        VideoControl::SetOrientation(*o),
+                                        VideoControl::Disable,
                                     );
                                 }
-                                match state {
-                                    // The peer's video is (about to be) live; make sure our plane decodes
-                                    // it even when the consumer skipped `.video()` and only accepts later
-                                    // — decoding costs nothing until packets arrive.
-                                    VideoState::UpgradeAccept | VideoState::Enabled => {
-                                        registry.set_is_video(call_id, generation, true);
-                                        registry.send_video_ctl(
+                                if transition_current
+                                    && (answer_upgrade || *state == VideoState::UpgradeAccept)
+                                {
+                                    if answer_upgrade {
+                                        let accept = build_video_state(&VideoStateParams {
                                             call_id,
-                                            generation,
-                                            VideoControl::Enable,
-                                        );
+                                            to: &call.from,
+                                            id: &client.generate_request_id(),
+                                            call_creator: call.action.call_creator(),
+                                            state: VideoState::UpgradeAccept,
+                                            dec: Some("H264,AV1"),
+                                            device_orientation: None,
+                                        });
+                                        if let Err(e) = client.send_node(accept).await {
+                                            warn!(
+                                                "call: failed to answer concurrent video upgrade: {e}"
+                                            );
+                                            transition_current = false;
+                                        }
                                     }
-                                    // The peer stopped ITS video; our outbound is the consumer's call
-                                    // (stop_video), so only the flag is updated here.
-                                    VideoState::Disabled | VideoState::Stopped => {
-                                        registry.set_is_video(call_id, generation, false);
+                                    if transition_current {
+                                        let enabled = build_video_state(&VideoStateParams {
+                                            call_id,
+                                            to: &call.from,
+                                            id: &client.generate_request_id(),
+                                            call_creator: call.action.call_creator(),
+                                            state: VideoState::Enabled,
+                                            dec: None,
+                                            device_orientation: None,
+                                        });
+                                        if let Err(e) = client.send_node(enabled).await {
+                                            warn!(
+                                                "call: failed to announce accepted video upgrade: {e}"
+                                            );
+                                            transition_current = false;
+                                        }
+                                    }
+                                    if !transition_current {
+                                        if !registry.run_video_teardown(call_id, generation) {
+                                            registry.send_video_ctl(
+                                                call_id,
+                                                generation,
+                                                VideoControl::Disable,
+                                            );
+                                        }
+                                        registry.reset_video(call_id, generation);
                                     }
-                                    _ => {}
                                 }
-                                let event_delivered = event_permit.as_ref().is_some_and(|permit| {
-                                    permit.send(CallEvent::VideoStateChanged {
-                                        state: *state,
-                                        orientation: *orientation,
-                                    })
-                                });
-                                if !event_delivered {
-                                    warn!(
-                                        "call: video state event receiver closed after typed ack"
+                                if enable_plane && transition_current {
+                                    registry.send_video_ctl(
+                                        call_id,
+                                        generation,
+                                        VideoControl::Enable,
                                     );
                                 }
                             }
-                            dispatch_call = transition_current;
+                            _ => {
+                                transition_current = false;
+                            }
                         }
+
+                        transition_current &= registry.is_current(call_id, generation);
+                        if transition_current {
+                            if let Some(o) = orientation {
+                                registry.send_video_ctl(
+                                    call_id,
+                                    generation,
+                                    VideoControl::SetOrientation(*o),
+                                );
+                            }
+                            let event_delivered = event_permit.as_ref().is_some_and(|permit| {
+                                permit.send(CallEvent::VideoStateChanged {
+                                    state: *state,
+                                    orientation: *orientation,
+                                    upgrade_token,
+                                })
+                            });
+                            if !event_delivered {
+                                warn!("call: video state event receiver closed after typed ack");
+                            }
+                        }
+                        dispatch_call = transition_current;
                         // Keep the transition serialized through every committed side effect.
                         drop(event_permit);
                     }
@@ -679,6 +729,19 @@ mod tests {
         assert!(!cancelled);
     }
 
+    #[cfg(feature = "voip-runtime")]
+    async fn begin_local_upgrade(registry: &wacore::voip::CallRegistry, generation: u64) {
+        let transition_lock = registry
+            .video_transition_lock("CALL-ID-0001", generation)
+            .expect("active call");
+        let _guard = transition_lock.lock().await;
+        assert!(
+            registry
+                .begin_local_video_request("CALL-ID-0001", generation)
+                .is_some()
+        );
+    }
+
     // A <call><video> must be acked with the TYPED <ack class="call" type="video"> and the
     // generic router ack suppressed — an untyped ack makes the upgrade requester revert ~5s in.
     #[cfg(feature = "voip-runtime")]
@@ -772,6 +835,69 @@ mod tests {
         ));
     }
 
+    #[cfg(feature = "voip-runtime")]
+    #[tokio::test]
+    async fn cancelled_peer_request_invalidates_its_acceptance_token() {
+        use wacore::voip::CallEvent;
+
+        let client = make_sending_client().await;
+        let registry = client.call_registry();
+        let generation = registry.insert(wacore::voip::CallSession::new_incoming(
+            "CALL-ID-0001",
+            fake_caller_lid(),
+            fake_caller_lid(),
+        ));
+        let (event_tx, event_rx) = async_channel::unbounded::<CallEvent>();
+        let (control_tx, _control_rx) = video_control_channel();
+        registry.set_video_channels(
+            "CALL-ID-0001",
+            generation,
+            event_tx,
+            control_tx,
+            Box::new(|| {}),
+        );
+
+        let mut cancelled = false;
+        assert!(
+            CallHandler
+                .handle(
+                    client.clone(),
+                    node_to_owned_ref(&video_stanza("11")),
+                    &mut cancelled,
+                )
+                .await
+        );
+        let token = match event_rx.try_recv().expect("upgrade request event") {
+            CallEvent::VideoStateChanged {
+                state: VideoState::UpgradeRequestV2,
+                upgrade_token: Some(token),
+                ..
+            } => token,
+            event => panic!("unexpected event: {event:?}"),
+        };
+        assert!(registry.peer_video_request_is_current("CALL-ID-0001", token));
+
+        cancelled = false;
+        assert!(
+            CallHandler
+                .handle(
+                    client,
+                    node_to_owned_ref(&video_stanza("0")),
+                    &mut cancelled,
+                )
+                .await
+        );
+        assert!(!registry.peer_video_request_is_current("CALL-ID-0001", token));
+        assert!(matches!(
+            event_rx.try_recv(),
+            Ok(CallEvent::VideoStateChanged {
+                state: VideoState::Disabled,
+                upgrade_token: None,
+                ..
+            })
+        ));
+    }
+
     #[cfg(feature = "voip-runtime")]
     #[tokio::test]
     async fn video_transition_stays_serialized_through_enabled_announcement() {
@@ -793,6 +919,7 @@ mod tests {
             control_tx,
             Box::new(|| {}),
         );
+        begin_local_upgrade(&registry, generation).await;
 
         let node = node_to_owned_ref(&video_stanza("4"));
         let mut cancelled = false;
@@ -836,7 +963,7 @@ mod tests {
             fake_caller_lid(),
             fake_caller_lid(),
         ));
-        assert!(registry.set_is_video("CALL-ID-0001", generation, true));
+        begin_local_upgrade(&registry, generation).await;
         let (event_tx, event_rx) = async_channel::unbounded::<CallEvent>();
         let (control_tx, control_rx) = video_control_channel();
         let teardown_control = control_tx.clone();
@@ -891,6 +1018,7 @@ mod tests {
             stale_control_tx,
             Box::new(|| {}),
         );
+        begin_local_upgrade(&registry, stale_generation).await;
 
         let node = node_to_owned_ref(&video_stanza("4"));
         let mut cancelled = false;
@@ -977,6 +1105,7 @@ mod tests {
         let (ev_tx, ev_rx) = async_channel::unbounded::<CallEvent>();
         let (ctl_tx, ctl_rx) = video_control_channel();
         registry.set_video_channels("CALL-ID-0001", generation, ev_tx, ctl_tx, Box::new(|| {}));
+        begin_local_upgrade(&registry, generation).await;
         let enabled_waiter = client.wait_for_sent_node(crate::client::NodeFilter::tag("call"));
 
         let node = node_to_owned_ref(&video_stanza("4")); // UpgradeAccept
@@ -993,6 +1122,7 @@ mod tests {
             CallEvent::VideoStateChanged {
                 state: VideoState::UpgradeAccept,
                 orientation: Some(1),
+                ..
             }
         ));
         let ctls: Vec<VideoControl> = std::iter::from_fn(|| ctl_rx.try_recv().ok()).collect();
@@ -1022,13 +1152,13 @@ mod tests {
         assert_eq!(video.tag, "video");
         assert_eq!(video.attrs().optional_string("state").as_deref(), Some("1"));
 
-        // The peer stopping its video clears the flag but does NOT disable our plane.
+        // The peer stopping its direction does NOT stop ours or disable the shared plane.
         let node = node_to_owned_ref(&video_stanza("6"));
         let mut cancelled = false;
         assert!(CallHandler.handle(client, node, &mut cancelled).await);
         assert!(
-            !registry.snapshot("CALL-ID-0001").expect("session").is_video,
-            "Stopped clears the video flag"
+            registry.snapshot("CALL-ID-0001").expect("session").is_video,
+            "peer Stopped must preserve our enabled video direction"
         );
         let ctls: Vec<VideoControl> = std::iter::from_fn(|| ctl_rx.try_recv().ok()).collect();
         assert!(
@@ -1055,7 +1185,7 @@ mod tests {
                 fake_caller_lid(),
             );
             let generation = registry.insert(session);
-            registry.set_is_video("CALL-ID-0001", generation, true);
+            begin_local_upgrade(&registry, generation).await;
             let torn = Arc::new(AtomicUsize::new(0));
             let (ev_tx, _ev_rx) = async_channel::unbounded::<CallEvent>();
             let (ctl_tx, _ctl_rx) = video_control_channel();
@@ -1095,7 +1225,7 @@ mod tests {
             fake_caller_lid(),
         );
         let generation = registry.insert(session);
-        registry.set_is_video("CALL-ID-0001", generation, true);
+        begin_local_upgrade(&registry, generation).await;
         let torn = Arc::new(AtomicUsize::new(0));
         let (ev_tx, _ev_rx) = async_channel::unbounded::<CallEvent>();
         let (ctl_tx, _ctl_rx) = video_control_channel();
@@ -1138,6 +1268,7 @@ mod tests {
         let (ev_tx, _ev_rx) = async_channel::unbounded::<CallEvent>();
         let (ctl_tx, ctl_rx) = video_control_channel();
         registry.set_video_channels("CALL-ID-0001", generation, ev_tx, ctl_tx, Box::new(|| {}));
+        begin_local_upgrade(&registry, generation).await;
 
         let mut cancelled = false;
         assert!(
@@ -1173,6 +1304,7 @@ mod tests {
         ev_tx.try_send(CallEvent::RelayAllocated).expect("prefill");
         let (ctl_tx, ctl_rx) = video_control_channel();
         registry.set_video_channels("CALL-ID-0001", generation, ev_tx, ctl_tx, Box::new(|| {}));
+        begin_local_upgrade(&registry, generation).await;
 
         let mut cancelled = false;
         assert!(
diff --git a/src/voip/facade.rs b/src/voip/facade.rs
index 0107464a2..90fe03d37 100644
--- a/src/voip/facade.rs
+++ b/src/voip/facade.rs
@@ -7,6 +7,7 @@
 use std::net::SocketAddr;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
 
 use bytes::Bytes;
 use log::warn;
@@ -23,7 +24,7 @@ use wacore::voip::transport::RelayTransportFactory;
 use wacore::voip::{
     AudioConfig, AudioFormat, AudioRtpProfile, CallChannels, CallConfig, CallEngine, CallEvent,
     EncodedAudioFrame, VideoControl, VideoControlReceiver, VideoControlSender, VideoFrame,
-    video_control_channel,
+    VideoUpgradeToken, video_control_channel,
 };
 use wacore_binary::{Jid, JidExt as _, Server};
 use waproto::whatsapp as wa;
@@ -1286,6 +1287,14 @@ const VIDEO_OUT_CHANNEL_CAP: usize = 8;
 const VIDEO_DEC_REQUEST: &str = "H264";
 /// `dec` WA Web advertises on an UpgradeAccept.
 const VIDEO_DEC_ACCEPT: &str = "H264,AV1";
+/// WA's native upgrade timer downgrades an unanswered request after five seconds.
+const VIDEO_UPGRADE_TIMEOUT: Duration = Duration::from_secs(5);
+
+#[derive(Clone, Copy)]
+enum VideoUpgradeRole {
+    Initiate,
+    Accept(VideoUpgradeToken),
+}
 
 /// Per-call video plumbing shared between the [`CallHandle`], the registry (signaling handler),
 /// and the drive loop. Created for EVERY call at registration time — idle channels cost nothing,
@@ -1386,6 +1395,28 @@ fn video_teardown_hook(video: &Arc<VideoShared>) -> Box<dyn Fn() + Send + Sync>
     Box::new(move || video.detach_endpoints())
 }
 
+fn release_video_endpoints(
+    registry: &wacore::voip::CallRegistry,
+    pending_outgoing_calls: &std::sync::Mutex<std::collections::HashMap<String, PendingOutgoing>>,
+    video: &VideoShared,
+    call_id: &str,
+    generation: u64,
+) {
+    let pending_video = {
+        let mut pending = pending_outgoing_calls
+            .lock()
+            .unwrap_or_else(|e| e.into_inner());
+        pending
+            .get_mut(call_id)
+            .filter(|entry| entry.generation == generation)
+            .and_then(|entry| entry.video.take())
+    };
+    drop(pending_video);
+    if !registry.run_video_teardown(call_id, generation) {
+        video.detach_endpoints();
+    }
+}
+
 /// Forwards encoded AUs from the consumer's source into the drive loop. Bounded on the call's
 /// `ended` flag as well as the channels, so a source that stops producing after the call ends
 /// can't park this task on `recv()` forever.
@@ -1549,29 +1580,41 @@ impl CallHandle {
         S: VideoSource,
         K: VideoSink,
     {
-        self.begin_video(
-            Arc::new(source),
-            Arc::new(sink),
-            VideoState::UpgradeRequestV2,
-        )
-        .await
+        self.begin_video(Arc::new(source), Arc::new(sink), VideoUpgradeRole::Initiate)
+            .await
     }
 
     /// ACCEPT the peer's video upgrade request (a `VideoStateChanged { state: UpgradeRequestV2 }`
-    /// event): attaches the endpoints, enables the media plane, and answers
+    /// event): the token binds this action to that exact request, then the method attaches the
+    /// endpoints, enables the media plane, and answers
     /// `<video state=4 dec="H264,AV1">` followed by `<video state=1>` (Enabled).
-    pub async fn accept_video<S, K>(&self, source: S, sink: K) -> Result<(), CallError>
+    pub async fn accept_video<S, K>(
+        &self,
+        request: VideoUpgradeToken,
+        source: S,
+        sink: K,
+    ) -> Result<(), CallError>
     where
         S: VideoSource,
         K: VideoSink,
     {
-        self.begin_video(Arc::new(source), Arc::new(sink), VideoState::UpgradeAccept)
-            .await
+        self.begin_video(
+            Arc::new(source),
+            Arc::new(sink),
+            VideoUpgradeRole::Accept(request),
+        )
+        .await
     }
 
     /// Send the standalone `<video state=1>` used after a mid-call video upgrade. Captured
     /// video-from-start callees do not need this extra stanza.
     pub async fn announce_video_enabled(&self) -> Result<(), CallError> {
+        self.ensure_current()?;
+        let transition_lock = self
+            .client_registry
+            .video_transition_lock(&self.call_id, self.generation)
+            .ok_or(CallError::Media("call no longer active"))?;
+        let _transition_guard = transition_lock.lock().await;
         self.ensure_current()?;
         let client = self.upgrade_client()?;
         let stanza = build_video_state(&VideoStateParams {
@@ -1587,15 +1630,24 @@ impl CallHandle {
         Ok(())
     }
 
-    /// DOWNGRADE to audio: sends `<video state=6>` (Stopped, no marker), tears the local video
-    /// plane down, and releases the source/sink. The audio plane is untouched. Idempotent.
+    /// Stop our video direction: sends `<video state=6>` (Stopped, no marker), tears the local
+    /// video plane down, and releases the source/sink. The peer may keep sending its direction;
+    /// audio is untouched. Idempotent.
     pub async fn stop_video(&self) -> Result<(), CallError> {
         self.ensure_current()?;
-        let client = self.upgrade_client()?;
+        let transition_lock = self
+            .client_registry
+            .video_transition_lock(&self.call_id, self.generation)
+            .ok_or(CallError::Media("call no longer active"))?;
+        let _transition_guard = transition_lock.lock().await;
+        self.ensure_current()?;
         // Tear local media down FIRST, matching `Voip::terminate`: the app asked to stop video, so
         // a failed signaling send must NOT leave the camera streaming. If the peer misses the
         // Stopped it keeps sending video, but our plane is disabled so those PT-97 packets drop.
-        self.teardown_local_video();
+        self.release_local_video();
+        self.client_registry
+            .stop_local_video(&self.call_id, self.generation);
+        let client = self.upgrade_client()?;
         let stanza = build_video_state(&VideoStateParams {
             call_id: &self.call_id,
             to: &self.peer_jid(),
@@ -1609,29 +1661,15 @@ impl CallHandle {
         Ok(())
     }
 
-    /// Release the local video plane: detach the endpoints (stops the camera feed, drops the sink,
-    /// disables the drive-loop plane) and clear the session flag. Shared by `stop_video` and the
-    /// `begin_video` rollback.
-    fn teardown_local_video(&self) {
-        let pending_video = {
-            let mut pending = self
-                .pending_outgoing_calls
-                .lock()
-                .unwrap_or_else(|e| e.into_inner());
-            pending
-                .get_mut(&self.call_id)
-                .filter(|entry| entry.generation == self.generation)
-                .and_then(|entry| entry.video.take())
-        };
-        drop(pending_video);
-        if !self
-            .client_registry
-            .run_video_teardown(&self.call_id, self.generation)
-        {
-            self.video.detach_endpoints();
-        }
-        self.client_registry
-            .set_is_video(&self.call_id, self.generation, false);
+    /// Release local codec endpoints without changing the directional signaling state.
+    fn release_local_video(&self) {
+        release_video_endpoints(
+            &self.client_registry,
+            &self.pending_outgoing_calls,
+            &self.video,
+            &self.call_id,
+            self.generation,
+        );
     }
 
     /// Shared upgrade/accept body: attach endpoints, enable the plane, send the handshake stanzas.
@@ -1639,7 +1677,7 @@ impl CallHandle {
         &self,
         source: Arc<dyn VideoSource>,
         sink: Arc<dyn VideoSink>,
-        role: VideoState,
+        role: VideoUpgradeRole,
     ) -> Result<(), CallError> {
         // A stale handle (superseded by a same-call-id glare/retry) must not attach endpoints or
         // send `<video>` for a call it no longer owns — that would mutate the replacement's state.
@@ -1650,6 +1688,29 @@ impl CallHandle {
             ));
         }
         let client = self.upgrade_client()?;
+        let transition_lock = self
+            .client_registry
+            .video_transition_lock(&self.call_id, self.generation)
+            .ok_or(CallError::Media("call no longer active"))?;
+        let transition_guard = transition_lock.lock().await;
+        self.ensure_current()?;
+        let request_epoch = match role {
+            VideoUpgradeRole::Initiate => Some(
+                self.client_registry
+                    .begin_local_video_request(&self.call_id, self.generation)
+                    .ok_or(CallError::Media("video transition already in progress"))?,
+            ),
+            VideoUpgradeRole::Accept(request) => {
+                if request.generation() != self.generation
+                    || !self
+                        .client_registry
+                        .peer_video_request_is_current(&self.call_id, request)
+                {
+                    return Err(CallError::VideoUpgradeExpired);
+                }
+                None
+            }
+        };
         self.video
             .attach_endpoints(&client, &source, &sink, self.ended.clone());
         if !self.client_registry.set_video_teardown(
@@ -1658,19 +1719,20 @@ impl CallHandle {
             video_teardown_hook(&self.video),
         ) {
             self.video.detach_endpoints();
+            if let Some(epoch) = request_epoch {
+                self.client_registry
+                    .end_local_video_request(&self.call_id, self.generation, epoch);
+            }
             return Err(CallError::Media("call no longer active"));
         }
         // The upgrade INITIATOR holds outbound video until the peer accepts (the handler ungates on
         // the peer's UpgradeAccept/Enabled). The acceptor's peer already requested, so it may send
         // immediately.
-        let ctl = if role == VideoState::UpgradeRequestV2 {
-            VideoControl::EnableAwaitingAccept
-        } else {
-            VideoControl::Enable
+        let ctl = match role {
+            VideoUpgradeRole::Initiate => VideoControl::EnableAwaitingAccept,
+            VideoUpgradeRole::Accept(_) => VideoControl::Enable,
         };
         self.video.send_control(ctl);
-        self.client_registry
-            .set_is_video(&self.call_id, self.generation, true);
 
         let peer = self.peer_jid();
         let send_state = |state: VideoState, dec: Option<&'static str>| {
@@ -1687,35 +1749,108 @@ impl CallHandle {
             let client = client.clone();
             async move { client.send_node(stanza).await }
         };
-        match role {
-            VideoState::UpgradeRequestV2 => {
+        let send_result = match role {
+            VideoUpgradeRole::Initiate => {
                 if let Err(e) =
                     send_state(VideoState::UpgradeRequestV2, Some(VIDEO_DEC_REQUEST)).await
                 {
-                    self.teardown_local_video();
-                    return Err(e.into());
+                    Err(e)
+                } else {
+                    Ok(())
                 }
             }
-            _ => {
+            VideoUpgradeRole::Accept(_) => {
                 if let Err(e) = send_state(VideoState::UpgradeAccept, Some(VIDEO_DEC_ACCEPT)).await
                 {
-                    self.teardown_local_video();
-                    return Err(e.into());
-                }
-                if let Err(e) = send_state(VideoState::Enabled, None).await {
+                    Err(e)
+                } else if let Err(e) = send_state(VideoState::Enabled, None).await {
                     // The peer times out an incomplete handshake; keep local media aligned with it.
                     warn!(
                         "voip: video upgrade handshake failed call_id={} phase=enabled_after_accept error={e}",
                         self.call_id
                     );
-                    self.teardown_local_video();
-                    return Err(e.into());
+                    Err(e)
+                } else {
+                    Ok(())
+                }
+            }
+        };
+        if let Err(e) = send_result {
+            self.release_local_video();
+            if let Some(epoch) = request_epoch {
+                self.client_registry
+                    .end_local_video_request(&self.call_id, self.generation, epoch);
+            } else {
+                self.client_registry
+                    .reset_video(&self.call_id, self.generation);
+            }
+            return Err(e.into());
+        }
+
+        match role {
+            VideoUpgradeRole::Initiate => {
+                drop(transition_guard);
+                if let Some(epoch) = request_epoch {
+                    self.spawn_video_upgrade_timeout(epoch, client);
+                }
+            }
+            VideoUpgradeRole::Accept(request) => {
+                if !self
+                    .client_registry
+                    .complete_peer_video_request(&self.call_id, request)
+                {
+                    self.release_local_video();
+                    self.client_registry
+                        .reset_video(&self.call_id, self.generation);
+                    return Err(CallError::VideoUpgradeExpired);
                 }
             }
         }
         Ok(())
     }
 
+    fn spawn_video_upgrade_timeout(&self, epoch: u64, client: Arc<Client>) {
+        let runtime = client.runtime.clone();
+        let sleeper = runtime.clone();
+        let registry = self.client_registry.clone();
+        let pending = self.pending_outgoing_calls.clone();
+        let video = self.video.clone();
+        let weak_client = Arc::downgrade(&client);
+        let call_id = self.call_id.clone();
+        let generation = self.generation;
+        let peer = self.peer_jid();
+        let call_creator = self.call_creator.clone();
+        runtime
+            .spawn(Box::pin(async move {
+                sleeper.sleep(VIDEO_UPGRADE_TIMEOUT).await;
+                let Some(transition_lock) = registry.video_transition_lock(&call_id, generation)
+                else {
+                    return;
+                };
+                let _transition_guard = transition_lock.lock().await;
+                if !registry.end_local_video_request(&call_id, generation, epoch) {
+                    return;
+                }
+                release_video_endpoints(&registry, &pending, &video, &call_id, generation);
+                let Some(client) = weak_client.upgrade() else {
+                    return;
+                };
+                let stanza = build_video_state(&VideoStateParams {
+                    call_id: &call_id,
+                    to: &peer,
+                    id: &client.generate_request_id(),
+                    call_creator: &call_creator,
+                    state: VideoState::Disabled,
+                    dec: None,
+                    device_orientation: None,
+                });
+                if let Err(e) = client.send_node(stanza).await {
+                    warn!("voip: failed to announce video upgrade timeout call_id={call_id}: {e}");
+                }
+            }))
+            .detach();
+    }
+
     fn upgrade_client(&self) -> Result<Arc<Client>, CallError> {
         self.client
             .upgrade()
@@ -3681,6 +3816,22 @@ mod tests {
         (vin_rx, vout_tx)
     }
 
+    async fn peer_upgrade_request(handle: &CallHandle) -> VideoUpgradeToken {
+        let transition_lock = handle
+            .client_registry
+            .video_transition_lock(&handle.call_id, handle.generation)
+            .expect("active call");
+        let _guard = transition_lock.lock().await;
+        match handle.client_registry.apply_peer_video_state(
+            &handle.call_id,
+            handle.generation,
+            VideoState::UpgradeRequestV2,
+        ) {
+            wacore::voip::PeerVideoTransition::UpgradeRequested(token) => token,
+            transition => panic!("unexpected transition: {transition:?}"),
+        }
+    }
+
     struct TimedVideoSource {
         frames: async_channel::Receiver<Vec<u8>>,
         timestamp_stride: u32,
@@ -3696,6 +3847,23 @@ mod tests {
         }
     }
 
+    struct DropTrackedVideoSource {
+        frames: async_channel::Receiver<Vec<u8>>,
+        drops: Arc<AtomicUsize>,
+    }
+
+    impl VideoSource for DropTrackedVideoSource {
+        fn frames(&self) -> async_channel::Receiver<Vec<u8>> {
+            self.frames.clone()
+        }
+    }
+
+    impl Drop for DropTrackedVideoSource {
+        fn drop(&mut self) {
+            self.drops.fetch_add(1, Ordering::SeqCst);
+        }
+    }
+
     /// The action child of a sent `<call>` node.
     fn call_action_of(node: &wacore_binary::Node) -> wacore_binary::Node {
         node.as_node_ref().children().unwrap()[0].to_owned()
@@ -3808,11 +3976,12 @@ mod tests {
     #[tokio::test]
     async fn accept_video_sends_accept_then_enabled() {
         let (client, sent_count, handle, _relay_keepalive) = sending_handle().await;
+        let request = peer_upgrade_request(&handle).await;
         let (vsrc, vsink) = video_endpoints();
         let before = sent_count.load(Ordering::SeqCst);
         let waiter = client.wait_for_sent_node(crate::client::NodeFilter::tag("call"));
         handle
-            .accept_video(vsrc, vsink)
+            .accept_video(request, vsrc, vsink)
             .await
             .expect("accept_video");
         assert_eq!(
@@ -3867,13 +4036,127 @@ mod tests {
             ended: Arc::new(EndedFlag::default()),
         };
 
+        let request = peer_upgrade_request(&handle).await;
         let (source, sink) = video_endpoints();
-        assert!(handle.accept_video(source, sink).await.is_err());
+        assert!(handle.accept_video(request, source, sink).await.is_err());
         assert_eq!(sent.load(Ordering::SeqCst), 2);
         assert!(video.sink_slot.lock().unwrap().is_none());
         assert!(!registry.snapshot("CID-FACADE").unwrap().is_video);
     }
 
+    #[tokio::test]
+    async fn stale_peer_request_cannot_accept_a_newer_request() {
+        let (_client, _sent, handle, _relay_keepalive) = sending_handle().await;
+        let first = peer_upgrade_request(&handle).await;
+        let transition_lock = handle
+            .client_registry
+            .video_transition_lock(&handle.call_id, handle.generation)
+            .expect("active call");
+        let second = {
+            let _guard = transition_lock.lock().await;
+            assert!(matches!(
+                handle.client_registry.apply_peer_video_state(
+                    &handle.call_id,
+                    handle.generation,
+                    VideoState::UpgradeCancel,
+                ),
+                wacore::voip::PeerVideoTransition::Applied { .. }
+            ));
+            match handle.client_registry.apply_peer_video_state(
+                &handle.call_id,
+                handle.generation,
+                VideoState::UpgradeRequestV2,
+            ) {
+                wacore::voip::PeerVideoTransition::UpgradeRequested(token) => token,
+                transition => panic!("unexpected transition: {transition:?}"),
+            }
+        };
+        assert_ne!(first, second);
+
+        let drops = Arc::new(AtomicUsize::new(0));
+        let (frames_tx, frames) = async_channel::unbounded();
+        let source = DropTrackedVideoSource {
+            frames,
+            drops: drops.clone(),
+        };
+        let (_sink_rx, sink) = {
+            let (sink, receiver) = async_channel::unbounded::<VideoFrame>();
+            (receiver, sink)
+        };
+        assert!(matches!(
+            handle.accept_video(first, source, sink).await,
+            Err(CallError::VideoUpgradeExpired)
+        ));
+        drop(frames_tx);
+        assert_eq!(drops.load(Ordering::SeqCst), 1);
+        assert!(handle.video.sink_slot.lock().unwrap().is_none());
+        assert!(
+            handle
+                .client_registry
+                .peer_video_request_is_current(&handle.call_id, second)
+        );
+        handle.hangup().await;
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn unanswered_local_upgrade_times_out_and_releases_source() {
+        let (client, sends) = make_sending_client().await;
+        let registry = client.call_registry();
+        let generation = registry.insert(mk_session());
+        let video = Arc::new(VideoShared::new());
+        let (event_tx, events) = async_channel::unbounded::<CallEvent>();
+        registry.set_video_channels(
+            "CID-FACADE",
+            generation,
+            event_tx,
+            video.ctl_tx.clone(),
+            video_teardown_hook(&video),
+        );
+        let handle = CallHandle {
+            call_id: "CID-FACADE".into(),
+            generation,
+            peer_jid: caller(),
+            call_creator: caller(),
+            client_registry: registry.clone(),
+            pending_outgoing_calls: client.pending_outgoing_calls.clone(),
+            client: Arc::downgrade(&client),
+            muted: Arc::new(AtomicBool::new(false)),
+            video: video.clone(),
+            events,
+            ended: Arc::new(EndedFlag::default()),
+        };
+
+        let drops = Arc::new(AtomicUsize::new(0));
+        let (_frames_tx, frames) = async_channel::unbounded();
+        let source = DropTrackedVideoSource {
+            frames,
+            drops: drops.clone(),
+        };
+        let (sink, _sink_rx) = async_channel::unbounded::<VideoFrame>();
+        handle
+            .start_video(source, sink)
+            .await
+            .expect("request sent");
+        assert_eq!(sends.load(Ordering::SeqCst), 1);
+
+        tokio::task::yield_now().await;
+        tokio::time::advance(VIDEO_UPGRADE_TIMEOUT).await;
+        for _ in 0..10 {
+            if drops.load(Ordering::SeqCst) == 1 {
+                break;
+            }
+            tokio::task::yield_now().await;
+        }
+        assert_eq!(drops.load(Ordering::SeqCst), 1);
+        assert_eq!(sends.load(Ordering::SeqCst), 2);
+        assert!(!registry.snapshot("CID-FACADE").unwrap().is_video);
+        assert_eq!(
+            registry.video_states("CID-FACADE", generation),
+            Some((VideoState::Disabled, VideoState::Disabled))
+        );
+        handle.hangup().await;
+    }
+
     #[tokio::test]
     async fn stop_video_sends_stopped_and_releases_endpoints() {
         let (client, _sent, handle, _relay_keepalive) = sending_handle().await;
@@ -3951,7 +4234,12 @@ mod tests {
                 .is_some_and(|pending| pending.video.is_none()),
             "relay attach must not resurrect endpoints removed before its ack"
         );
-        assert!(!client.call_registry().snapshot(&call_id).unwrap().is_video);
+        let registry = client.call_registry();
+        assert_eq!(
+            registry.video_states(&call_id, handle.generation),
+            Some((VideoState::Stopped, VideoState::Enabled))
+        );
+        assert!(registry.snapshot(&call_id).unwrap().is_video);
         handle.hangup().await;
     }
 
diff --git a/src/voip/mod.rs b/src/voip/mod.rs
index 163a93bc0..d78e965e7 100644
--- a/src/voip/mod.rs
+++ b/src/voip/mod.rs
@@ -29,10 +29,10 @@ pub use audio::{AudioSink, AudioSource, EncodedAudioSink, EncodedAudioSource};
 pub use facade::{AcceptCall, CallHandle, OutgoingCall};
 pub use video::{VideoFrame, VideoSink, VideoSource};
 // CallHandle::events() yields these, so surface them next to CallHandle (they live in wacore).
-pub use wacore::voip::CallEvent;
 pub use wacore::voip::{
     AudioCodec, AudioConfig, AudioFormat, AudioIo, AudioRtpProfile, EncodedAudioFrame,
     OpusMlowPacketError, depacketize_opus_from_mlow, packetize_opus_for_mlow,
 };
+pub use wacore::voip::{CallEvent, VideoUpgradeToken};
 // `CallEvent::VideoStateChanged` carries this; surface it next to CallEvent (it lives in wacore).
 pub use wacore::types::call::VideoState;
diff --git a/wacore/src/types/call.rs b/wacore/src/types/call.rs
index 4b4c2ac29..95fff58a7 100644
--- a/wacore/src/types/call.rs
+++ b/wacore/src/types/call.rs
@@ -78,6 +78,8 @@ pub enum VideoState {
     Disabled,
     #[wire = 1]
     Enabled,
+    #[wire = 2]
+    Paused,
     #[wire = 3]
     UpgradeRequest,
     #[wire = 4]
@@ -86,14 +88,42 @@ pub enum VideoState {
     UpgradeReject,
     #[wire = 6]
     Stopped,
+    #[wire = 7]
+    UpgradeRejectByTimeout,
     #[wire = 8]
     UpgradeCancel,
+    #[wire = 9]
+    UpgradeCancelByTimeout,
+    #[wire = 10]
+    UnknownPeer,
     #[wire = 11]
     UpgradeRequestV2,
+    #[wire = 20]
+    Error,
     #[wire_fallback]
     Unknown(i32),
 }
 
+impl VideoState {
+    /// Matches WA Web's call-mode predicate: a call remains video while either direction is active.
+    pub const fn is_inactive_for_call_mode(self) -> bool {
+        matches!(
+            self,
+            Self::Disabled
+                | Self::UpgradeReject
+                | Self::Stopped
+                | Self::UpgradeRejectByTimeout
+                | Self::UpgradeCancel
+                | Self::UpgradeCancelByTimeout
+                | Self::Error
+        )
+    }
+
+    pub const fn is_upgrade_request(self) -> bool {
+        matches!(self, Self::UpgradeRequest | Self::UpgradeRequestV2)
+    }
+}
+
 /// Fields kept per-variant (not a shared `BasicCallMeta`) so the `serde` shape
 /// mirrors the stanza 1:1 for downstream JS consumers.
 #[derive(Debug, Clone, Serialize)]
diff --git a/wacore/src/voip/engine.rs b/wacore/src/voip/engine.rs
index e40859233..60b498546 100644
--- a/wacore/src/voip/engine.rs
+++ b/wacore/src/voip/engine.rs
@@ -377,11 +377,13 @@ pub enum CallEvent {
     RelayAllocateTimedOut,
     /// The peer's `<video state=N>` signaling arrived (upgrade requested/accepted, stopped, ...).
     /// Pushed by the signaling handler, not the engine; surfaced here so one event stream carries
-    /// the whole call. `UpgradeRequestV2` is the peer asking for video — answer with
-    /// `accept_video` or ignore to decline.
+    /// the whole call. For an upgrade request, pass `upgrade_token` to `accept_video`; a cancelled
+    /// or superseded token cannot attach video endpoints.
     VideoStateChanged {
         state: crate::types::call::VideoState,
         orientation: Option<u8>,
+        /// Present only for a peer upgrade request; accepting requires this exact request token.
+        upgrade_token: Option<super::VideoUpgradeToken>,
     },
     /// Authenticated peer RTCP. A referenced local video SSRC proves the peer built a receiver for
     /// our outbound stream; RR, NACK, PLI and FIR are all represented here.
diff --git a/wacore/src/voip/mod.rs b/wacore/src/voip/mod.rs
index fbe03ea8e..eeeb8fbec 100644
--- a/wacore/src/voip/mod.rs
+++ b/wacore/src/voip/mod.rs
@@ -48,7 +48,7 @@ pub use engine::{
 pub use h264::{AnnexBAuSplitter, VideoFrame};
 #[cfg(feature = "voip-mlow")]
 pub use mlow::{MlowDecoder, MlowEncoder};
-pub use registry::CallRegistry;
+pub use registry::{CallRegistry, PeerVideoTransition, VideoUpgradeToken};
 pub use session::{
     CallDirection, CallPhase, CallSession, MediaPipeline, MediaPipelineParams, VideoPipeline,
     VideoPipelineParams,
diff --git a/wacore/src/voip/registry.rs b/wacore/src/voip/registry.rs
index 9f2f14e6c..1739f6829 100644
--- a/wacore/src/voip/registry.rs
+++ b/wacore/src/voip/registry.rs
@@ -11,14 +11,93 @@ use std::collections::{HashMap, HashSet};
 use std::sync::atomic::Ordering;
 use std::sync::{Arc, Mutex};
 
+use async_lock::Mutex as AsyncMutex;
 use portable_atomic::{AtomicBool, AtomicU64};
 
 use crate::runtime::AbortHandle;
+use crate::types::call::VideoState;
 use crate::voip::driver::{VideoControl, VideoControlSender};
 use crate::voip::engine::CallEvent;
 use crate::voip::session::{CallPhase, CallSession};
 use wacore_binary::Jid;
 
+/// Identifies one peer video-upgrade request within one call generation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct VideoUpgradeToken {
+    generation: u64,
+    epoch: u64,
+}
+
+impl VideoUpgradeToken {
+    pub fn generation(self) -> u64 {
+        self.generation
+    }
+
+    pub fn epoch(self) -> u64 {
+        self.epoch
+    }
+}
+
+/// Result of applying a committed peer video-state transition.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum PeerVideoTransition {
+    Ignored,
+    UpgradeRequested(VideoUpgradeToken),
+    Applied {
+        enable_plane: bool,
+        teardown_local: bool,
+        answer_upgrade: bool,
+    },
+}
+
+#[derive(Debug, Clone, Copy)]
+struct VideoNegotiation {
+    self_state: VideoState,
+    peer_state: VideoState,
+    peer_request_epoch: u64,
+    pending_peer_request: Option<u64>,
+    self_request_epoch: u64,
+    pending_self_request: Option<u64>,
+}
+
+impl VideoNegotiation {
+    fn new(is_video: bool) -> Self {
+        let state = if is_video {
+            VideoState::Enabled
+        } else {
+            VideoState::Disabled
+        };
+        Self {
+            self_state: state,
+            peer_state: state,
+            peer_request_epoch: 0,
+            pending_peer_request: None,
+            self_request_epoch: 0,
+            pending_self_request: None,
+        }
+    }
+
+    fn is_video(self) -> bool {
+        !self.self_state.is_inactive_for_call_mode() || !self.peer_state.is_inactive_for_call_mode()
+    }
+
+    fn next_peer_request(&mut self, generation: u64) -> VideoUpgradeToken {
+        self.peer_request_epoch = self.peer_request_epoch.wrapping_add(1).max(1);
+        self.pending_peer_request = Some(self.peer_request_epoch);
+        VideoUpgradeToken {
+            generation,
+            epoch: self.peer_request_epoch,
+        }
+    }
+
+    fn next_self_request(&mut self) -> u64 {
+        self.self_request_epoch = self.self_request_epoch.wrapping_add(1).max(1);
+        self.pending_self_request = Some(self.self_request_epoch);
+        self.self_request_epoch
+    }
+}
+
 /// Runs its closure when dropped. Stored on a [`CallEntry`] to wake the call's `wait_ended()` waiter
 /// whenever the entry is removed (terminal stanza, disconnect, supersession) -- including in the
 /// window after registration but before a media task exists to carry the notify on its own teardown.
@@ -53,6 +132,9 @@ struct CallEntry {
     video_teardown: Option<Box<dyn Fn() + Send + Sync>>,
     /// Prevents concurrent video transitions from overtaking each other while an ack is in flight.
     event_publication_reserved: Arc<AtomicBool>,
+    /// Mirrors WA's stream mutex for user actions, peer signaling, and timeout callbacks.
+    video_transition_lock: Arc<AsyncMutex<()>>,
+    video: VideoNegotiation,
     /// Wakes this call's `wait_ended()` waiter on removal, even before a media task exists. Fires from
     /// `EndedNotify`'s Drop whenever the entry leaves the map.
     on_terminal: Option<EndedNotify>,
@@ -125,6 +207,7 @@ impl CallRegistry {
     /// OWN entry, never a newer replacement.
     pub fn insert(&self, session: CallSession) -> u64 {
         let generation = self.next_gen.fetch_add(1, Ordering::Relaxed);
+        let video = VideoNegotiation::new(session.is_video);
         // Registering a call as active answers (accept) or places (outgoing) it: it is no longer
         // merely ringing. A no-op for an outgoing call (never ringing); for an accepted incoming
         // offer this clears the ringing flag so a later `<terminate>` reads as ended, not missed.
@@ -142,6 +225,8 @@ impl CallRegistry {
                     video_ctl_tx: None,
                     video_teardown: None,
                     event_publication_reserved: Arc::new(AtomicBool::new(false)),
+                    video_transition_lock: Arc::new(AsyncMutex::new(())),
+                    video,
                     on_terminal: None,
                 },
             )
@@ -301,6 +386,263 @@ impl CallRegistry {
         })
     }
 
+    /// The current call generation and its shared video-transition lock.
+    pub fn current_video_transition(&self, call_id: &str) -> Option<(u64, Arc<AsyncMutex<()>>)> {
+        self.inner
+            .lock()
+            .expect("registry lock poisoned")
+            .get(call_id)
+            .map(|entry| (entry.generation, entry.video_transition_lock.clone()))
+    }
+
+    /// The video-transition lock for one known call generation.
+    pub fn video_transition_lock(
+        &self,
+        call_id: &str,
+        generation: u64,
+    ) -> Option<Arc<AsyncMutex<()>>> {
+        self.inner
+            .lock()
+            .expect("registry lock poisoned")
+            .get(call_id)
+            .filter(|entry| entry.generation == generation)
+            .map(|entry| entry.video_transition_lock.clone())
+    }
+
+    /// Apply a peer state while the caller holds this generation's video-transition lock.
+    pub fn apply_peer_video_state(
+        &self,
+        call_id: &str,
+        generation: u64,
+        state: VideoState,
+    ) -> PeerVideoTransition {
+        let mut map = self.inner.lock().expect("registry lock poisoned");
+        let Some(entry) = map
+            .get_mut(call_id)
+            .filter(|entry| entry.generation == generation)
+        else {
+            return PeerVideoTransition::Ignored;
+        };
+
+        let outcome = match state {
+            VideoState::UpgradeRequest | VideoState::UpgradeRequestV2 => {
+                if entry.video.peer_state.is_upgrade_request()
+                    && let Some(epoch) = entry.video.pending_peer_request
+                {
+                    PeerVideoTransition::UpgradeRequested(VideoUpgradeToken { generation, epoch })
+                } else if entry.video.self_state.is_upgrade_request()
+                    && entry.video.pending_self_request.is_some()
+                {
+                    entry.video.self_state = VideoState::Enabled;
+                    entry.video.peer_state = VideoState::Enabled;
+                    entry.video.pending_self_request = None;
+                    entry.video.pending_peer_request = None;
+                    PeerVideoTransition::Applied {
+                        enable_plane: true,
+                        teardown_local: false,
+                        answer_upgrade: true,
+                    }
+                } else if !entry.video.self_state.is_inactive_for_call_mode() {
+                    PeerVideoTransition::Ignored
+                } else {
+                    entry.video.peer_state = state;
+                    let token = entry.video.next_peer_request(generation);
+                    PeerVideoTransition::UpgradeRequested(token)
+                }
+            }
+            VideoState::UpgradeAccept => {
+                if entry.video.self_state.is_upgrade_request()
+                    && entry.video.pending_self_request.is_some()
+                {
+                    entry.video.self_state = VideoState::Enabled;
+                    entry.video.peer_state = VideoState::Enabled;
+                    entry.video.pending_self_request = None;
+                    PeerVideoTransition::Applied {
+                        enable_plane: true,
+                        teardown_local: false,
+                        answer_upgrade: false,
+                    }
+                } else {
+                    PeerVideoTransition::Ignored
+                }
+            }
+            VideoState::Enabled => {
+                if entry.video.self_state.is_upgrade_request() {
+                    entry.video.self_state = VideoState::Enabled;
+                    entry.video.pending_self_request = None;
+                }
+                entry.video.peer_state = VideoState::Enabled;
+                entry.video.pending_peer_request = None;
+                PeerVideoTransition::Applied {
+                    enable_plane: true,
+                    teardown_local: false,
+                    answer_upgrade: false,
+                }
+            }
+            VideoState::UpgradeReject | VideoState::UpgradeRejectByTimeout => {
+                if entry.video.self_state.is_upgrade_request()
+                    && entry.video.pending_self_request.is_some()
+                {
+                    entry.video.self_state = VideoState::Disabled;
+                    entry.video.peer_state = state;
+                    entry.video.pending_self_request = None;
+                    PeerVideoTransition::Applied {
+                        enable_plane: false,
+                        teardown_local: true,
+                        answer_upgrade: false,
+                    }
+                } else {
+                    PeerVideoTransition::Ignored
+                }
+            }
+            VideoState::Disabled
+            | VideoState::UpgradeCancel
+            | VideoState::UpgradeCancelByTimeout
+            | VideoState::Error => {
+                entry.video.self_state = VideoState::Disabled;
+                entry.video.peer_state = state;
+                entry.video.pending_self_request = None;
+                entry.video.pending_peer_request = None;
+                PeerVideoTransition::Applied {
+                    enable_plane: false,
+                    teardown_local: true,
+                    answer_upgrade: false,
+                }
+            }
+            VideoState::Stopped => {
+                entry.video.peer_state = VideoState::Stopped;
+                entry.video.pending_peer_request = None;
+                PeerVideoTransition::Applied {
+                    enable_plane: false,
+                    teardown_local: false,
+                    answer_upgrade: false,
+                }
+            }
+            VideoState::Paused | VideoState::UnknownPeer => {
+                entry.video.peer_state = state;
+                PeerVideoTransition::Applied {
+                    enable_plane: false,
+                    teardown_local: false,
+                    answer_upgrade: false,
+                }
+            }
+            VideoState::Unknown(_) => PeerVideoTransition::Ignored,
+        };
+        entry.session.is_video = entry.video.is_video();
+        outcome
+    }
+
+    /// Begin a local upgrade and return its timeout epoch.
+    pub fn begin_local_video_request(&self, call_id: &str, generation: u64) -> Option<u64> {
+        let mut map = self.inner.lock().expect("registry lock poisoned");
+        let entry = map
+            .get_mut(call_id)
+            .filter(|entry| entry.generation == generation)?;
+        if !entry.video.self_state.is_inactive_for_call_mode()
+            || entry.video.pending_peer_request.is_some()
+        {
+            return None;
+        }
+        entry.video.self_state = VideoState::UpgradeRequestV2;
+        let epoch = entry.video.next_self_request();
+        entry.session.is_video = entry.video.is_video();
+        Some(epoch)
+    }
+
+    /// Complete a peer request only when the same request is still pending.
+    pub fn complete_peer_video_request(&self, call_id: &str, token: VideoUpgradeToken) -> bool {
+        let mut map = self.inner.lock().expect("registry lock poisoned");
+        let Some(entry) = map
+            .get_mut(call_id)
+            .filter(|entry| entry.generation == token.generation)
+        else {
+            return false;
+        };
+        if entry.video.pending_peer_request != Some(token.epoch)
+            || !entry.video.peer_state.is_upgrade_request()
+        {
+            return false;
+        }
+        entry.video.self_state = VideoState::Enabled;
+        entry.video.peer_state = VideoState::Enabled;
+        entry.video.pending_peer_request = None;
+        entry.session.is_video = entry.video.is_video();
+        true
+    }
+
+    pub fn peer_video_request_is_current(&self, call_id: &str, token: VideoUpgradeToken) -> bool {
+        self.inner
+            .lock()
+            .expect("registry lock poisoned")
+            .get(call_id)
+            .filter(|entry| entry.generation == token.generation)
+            .is_some_and(|entry| {
+                entry.video.pending_peer_request == Some(token.epoch)
+                    && entry.video.peer_state.is_upgrade_request()
+            })
+    }
+
+    /// Roll back or expire one local request without touching a newer request.
+    pub fn end_local_video_request(&self, call_id: &str, generation: u64, epoch: u64) -> bool {
+        let mut map = self.inner.lock().expect("registry lock poisoned");
+        let Some(entry) = map
+            .get_mut(call_id)
+            .filter(|entry| entry.generation == generation)
+        else {
+            return false;
+        };
+        if entry.video.pending_self_request != Some(epoch)
+            || !entry.video.self_state.is_upgrade_request()
+        {
+            return false;
+        }
+        entry.video.self_state = VideoState::Disabled;
+        entry.video.pending_self_request = None;
+        entry.session.is_video = entry.video.is_video();
+        true
+    }
+
+    /// Clear both directions after a failed handshake or full downgrade.
+    pub fn reset_video(&self, call_id: &str, generation: u64) -> bool {
+        let mut map = self.inner.lock().expect("registry lock poisoned");
+        let Some(entry) = map
+            .get_mut(call_id)
+            .filter(|entry| entry.generation == generation)
+        else {
+            return false;
+        };
+        entry.video.self_state = VideoState::Disabled;
+        entry.video.peer_state = VideoState::Disabled;
+        entry.video.pending_self_request = None;
+        entry.video.pending_peer_request = None;
+        entry.session.is_video = false;
+        true
+    }
+
+    /// Mark only our direction stopped; the peer may keep sending video.
+    pub fn stop_local_video(&self, call_id: &str, generation: u64) -> bool {
+        let mut map = self.inner.lock().expect("registry lock poisoned");
+        let Some(entry) = map
+            .get_mut(call_id)
+            .filter(|entry| entry.generation == generation)
+        else {
+            return false;
+        };
+        entry.video.self_state = VideoState::Stopped;
+        entry.video.pending_self_request = None;
+        entry.session.is_video = entry.video.is_video();
+        true
+    }
+
+    pub fn video_states(&self, call_id: &str, generation: u64) -> Option<(VideoState, VideoState)> {
+        self.inner
+            .lock()
+            .expect("registry lock poisoned")
+            .get(call_id)
+            .filter(|entry| entry.generation == generation)
+            .map(|entry| (entry.video.self_state, entry.video.peer_state))
+    }
+
     /// Send a mid-call video-plane command to the current drive loop.
     pub fn send_video_ctl(&self, call_id: &str, generation: u64, ctl: VideoControl) {
         let tx = self
@@ -326,6 +668,7 @@ impl CallRegistry {
             && entry.generation == generation
         {
             entry.session.is_video = is_video;
+            entry.video = VideoNegotiation::new(is_video);
             true
         } else {
             false
@@ -560,6 +903,7 @@ mod tests {
         let event = || CallEvent::VideoStateChanged {
             state: crate::types::call::VideoState::Enabled,
             orientation: None,
+            upgrade_token: None,
         };
         let permit = reg.reserve_call_event("CID").expect("first reservation");
         assert!(
@@ -587,6 +931,113 @@ mod tests {
         assert!(reg.reserve_call_event("UNKNOWN").is_none());
     }
 
+    #[test]
+    fn peer_upgrade_tokens_reject_cancel_request_aba() {
+        let reg = CallRegistry::new();
+        let generation = reg.insert(session("CID"));
+        let first =
+            match reg.apply_peer_video_state("CID", generation, VideoState::UpgradeRequestV2) {
+                PeerVideoTransition::UpgradeRequested(token) => token,
+                transition => panic!("unexpected transition: {transition:?}"),
+            };
+        assert!(reg.peer_video_request_is_current("CID", first));
+        assert!(matches!(
+            reg.apply_peer_video_state("CID", generation, VideoState::UpgradeCancel),
+            PeerVideoTransition::Applied {
+                teardown_local: true,
+                ..
+            }
+        ));
+
+        let second =
+            match reg.apply_peer_video_state("CID", generation, VideoState::UpgradeRequestV2) {
+                PeerVideoTransition::UpgradeRequested(token) => token,
+                transition => panic!("unexpected transition: {transition:?}"),
+            };
+        assert_ne!(first, second);
+        assert!(!reg.peer_video_request_is_current("CID", first));
+        assert!(reg.peer_video_request_is_current("CID", second));
+        assert!(!reg.complete_peer_video_request("CID", first));
+        assert!(reg.peer_video_request_is_current("CID", second));
+        assert!(reg.complete_peer_video_request("CID", second));
+        assert_eq!(
+            reg.video_states("CID", generation),
+            Some((VideoState::Enabled, VideoState::Enabled))
+        );
+    }
+
+    #[test]
+    fn duplicate_peer_request_keeps_the_same_token() {
+        let reg = CallRegistry::new();
+        let generation = reg.insert(session("CID"));
+        let request = |state| match reg.apply_peer_video_state("CID", generation, state) {
+            PeerVideoTransition::UpgradeRequested(token) => token,
+            transition => panic!("unexpected transition: {transition:?}"),
+        };
+        assert_eq!(
+            request(VideoState::UpgradeRequest),
+            request(VideoState::UpgradeRequestV2)
+        );
+    }
+
+    #[test]
+    fn stopped_is_directional_but_disabled_is_a_full_downgrade() {
+        let reg = CallRegistry::new();
+        let generation = reg.insert(session("CID"));
+        let token =
+            match reg.apply_peer_video_state("CID", generation, VideoState::UpgradeRequestV2) {
+                PeerVideoTransition::UpgradeRequested(token) => token,
+                transition => panic!("unexpected transition: {transition:?}"),
+            };
+        assert!(reg.complete_peer_video_request("CID", token));
+
+        assert!(matches!(
+            reg.apply_peer_video_state("CID", generation, VideoState::Stopped),
+            PeerVideoTransition::Applied {
+                teardown_local: false,
+                ..
+            }
+        ));
+        assert_eq!(
+            reg.video_states("CID", generation),
+            Some((VideoState::Enabled, VideoState::Stopped))
+        );
+        assert!(reg.snapshot("CID").expect("session").is_video);
+
+        assert!(matches!(
+            reg.apply_peer_video_state("CID", generation, VideoState::Disabled),
+            PeerVideoTransition::Applied {
+                teardown_local: true,
+                ..
+            }
+        ));
+        assert_eq!(
+            reg.video_states("CID", generation),
+            Some((VideoState::Disabled, VideoState::Disabled))
+        );
+        assert!(!reg.snapshot("CID").expect("session").is_video);
+    }
+
+    #[test]
+    fn local_request_timeout_epoch_cannot_end_a_newer_request() {
+        let reg = CallRegistry::new();
+        let generation = reg.insert(session("CID"));
+        let first = reg
+            .begin_local_video_request("CID", generation)
+            .expect("first request");
+        assert!(reg.end_local_video_request("CID", generation, first));
+        let second = reg
+            .begin_local_video_request("CID", generation)
+            .expect("second request");
+        assert_ne!(first, second);
+        assert!(!reg.end_local_video_request("CID", generation, first));
+        assert_eq!(
+            reg.video_states("CID", generation),
+            Some((VideoState::UpgradeRequestV2, VideoState::Disabled))
+        );
+        assert!(reg.end_local_video_request("CID", generation, second));
+    }
+
     #[test]
     fn video_teardown_runs_after_registry_unlock() {
         let reg = Arc::new(CallRegistry::new());

From ad0d0def837bf1a9ca706791fd77651b0a91b54e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Lucas?=
 <55464917+jlucaso1@users.noreply.github.com>
Date: Thu, 16 Jul 2026 23:01:39 -0300
Subject: [PATCH 2/3] fix(voip): align video timeout signaling

---
 examples/voip-cli/src/main.rs | 22 ++++++++++++++--------
 src/voip/facade.rs            | 15 ++++++++++++++-
 wacore/src/voip/engine.rs     |  3 ++-
 wacore/src/voip/registry.rs   | 25 +++++++++++++++++++++----
 4 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/examples/voip-cli/src/main.rs b/examples/voip-cli/src/main.rs
index 9ab93b6f9..2db477c10 100644
--- a/examples/voip-cli/src/main.rs
+++ b/examples/voip-cli/src/main.rs
@@ -1279,8 +1279,10 @@ fn activate_peer_video_request(
     request: VideoUpgradeToken,
 ) {
     let mut st = lock_call_state(state);
-    if st.video_ui.get(call_id) == Some(&VideoUi::PendingPeerRequest(request)) {
-        st.video_ui.insert(call_id.to_string(), VideoUi::Active);
+    if let Some(ui) = st.video_ui.get_mut(call_id)
+        && *ui == VideoUi::PendingPeerRequest(request)
+    {
+        *ui = VideoUi::Active;
     }
 }
 
@@ -1413,7 +1415,7 @@ fn spawn_call_event_listener(
                 } => match vs {
                     VideoState::UpgradeRequest | VideoState::UpgradeRequestV2 => {
                         let Some(request) = upgrade_token else {
-                            warn!("peer video request arrived without an acceptance token");
+                            info!("🎥 concurrent video upgrade resolved automatically");
                             continue;
                         };
                         mark_video(
@@ -1423,11 +1425,15 @@ fn spawn_call_event_listener(
                         );
                         if auto_video {
                             info!("🎥 peer asked for video — auto-accepting (--video)");
-                            if let Err(e) = accept_peer_video(&handle, request).await {
-                                warn!("accepting peer video failed: {e}");
-                            } else {
-                                activate_peer_video_request(&state, handle.call_id(), request);
-                            }
+                            let handle = handle.clone();
+                            let state = state.clone();
+                            tokio::spawn(async move {
+                                if let Err(e) = accept_peer_video(&handle, request).await {
+                                    warn!("accepting peer video failed: {e}");
+                                } else {
+                                    activate_peer_video_request(&state, handle.call_id(), request);
+                                }
+                            });
                         } else {
                             info!("🎥 peer asked for video — press `v` + Enter to accept");
                         }
diff --git a/src/voip/facade.rs b/src/voip/facade.rs
index 90fe03d37..a7d344e90 100644
--- a/src/voip/facade.rs
+++ b/src/voip/facade.rs
@@ -1403,6 +1403,8 @@ fn release_video_endpoints(
     generation: u64,
 ) {
     let pending_video = {
+        // This synchronous map is shared with non-async setup paths; its lock covers only one
+        // lookup/take and is never held across an await.
         let mut pending = pending_outgoing_calls
             .lock()
             .unwrap_or_else(|e| e.into_inner());
@@ -1840,7 +1842,7 @@ impl CallHandle {
                     to: &peer,
                     id: &client.generate_request_id(),
                     call_creator: &call_creator,
-                    state: VideoState::Disabled,
+                    state: VideoState::UpgradeCancelByTimeout,
                     dec: None,
                     device_orientation: None,
                 });
@@ -4139,6 +4141,7 @@ mod tests {
             .expect("request sent");
         assert_eq!(sends.load(Ordering::SeqCst), 1);
 
+        let timeout_waiter = client.wait_for_sent_node(crate::client::NodeFilter::tag("call"));
         tokio::task::yield_now().await;
         tokio::time::advance(VIDEO_UPGRADE_TIMEOUT).await;
         for _ in 0..10 {
@@ -4149,6 +4152,16 @@ mod tests {
         }
         assert_eq!(drops.load(Ordering::SeqCst), 1);
         assert_eq!(sends.load(Ordering::SeqCst), 2);
+        let timeout_node = timeout_waiter.await.expect("timeout stanza");
+        let timeout_action = call_action_of(&timeout_node);
+        assert_eq!(
+            timeout_action
+                .as_node_ref()
+                .attrs()
+                .optional_string("state")
+                .as_deref(),
+            Some("9")
+        );
         assert!(!registry.snapshot("CID-FACADE").unwrap().is_video);
         assert_eq!(
             registry.video_states("CID-FACADE", generation),
diff --git a/wacore/src/voip/engine.rs b/wacore/src/voip/engine.rs
index 60b498546..80966be6a 100644
--- a/wacore/src/voip/engine.rs
+++ b/wacore/src/voip/engine.rs
@@ -382,7 +382,8 @@ pub enum CallEvent {
     VideoStateChanged {
         state: crate::types::call::VideoState,
         orientation: Option<u8>,
-        /// Present only for a peer upgrade request; accepting requires this exact request token.
+        /// Accepting requires this exact token. `None` means simultaneous local and peer requests
+        /// were already resolved by the signaling state machine.
         upgrade_token: Option<super::VideoUpgradeToken>,
     },
     /// Authenticated peer RTCP. A referenced local video SSRC proves the peer built a receiver for
diff --git a/wacore/src/voip/registry.rs b/wacore/src/voip/registry.rs
index 1739f6829..440a0765d 100644
--- a/wacore/src/voip/registry.rs
+++ b/wacore/src/voip/registry.rs
@@ -32,10 +32,6 @@ impl VideoUpgradeToken {
     pub fn generation(self) -> u64 {
         self.generation
     }
-
-    pub fn epoch(self) -> u64 {
-        self.epoch
-    }
 }
 
 /// Result of applying a committed peer video-state transition.
@@ -597,7 +593,9 @@ impl CallRegistry {
             return false;
         }
         entry.video.self_state = VideoState::Disabled;
+        entry.video.peer_state = VideoState::Disabled;
         entry.video.pending_self_request = None;
+        entry.video.pending_peer_request = None;
         entry.session.is_video = entry.video.is_video();
         true
     }
@@ -1038,6 +1036,25 @@ mod tests {
         assert!(reg.end_local_video_request("CID", generation, second));
     }
 
+    #[test]
+    fn cancelling_a_local_request_is_a_full_native_downgrade() {
+        let reg = CallRegistry::new();
+        let mut video_session = session("CID");
+        video_session.is_video = true;
+        let generation = reg.insert(video_session);
+        assert!(reg.stop_local_video("CID", generation));
+        let epoch = reg
+            .begin_local_video_request("CID", generation)
+            .expect("local request");
+
+        assert!(reg.end_local_video_request("CID", generation, epoch));
+        assert_eq!(
+            reg.video_states("CID", generation),
+            Some((VideoState::Disabled, VideoState::Disabled))
+        );
+        assert!(!reg.snapshot("CID").expect("session").is_video);
+    }
+
     #[test]
     fn video_teardown_runs_after_registry_unlock() {
         let reg = Arc::new(CallRegistry::new());

From 714651b4d9caef40d4161f6fd7ba3e55893db952 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Lucas?=
 <55464917+jlucaso1@users.noreply.github.com>
Date: Thu, 16 Jul 2026 23:24:07 -0300
Subject: [PATCH 3/3] fix(voip): restore video upgrade render metadata

---
 src/handlers/call.rs      | 17 ++++++++++++++---
 src/voip/facade.rs        | 28 ++++++++++++++++++++--------
 wacore/src/stanza/call.rs |  2 +-
 3 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/src/handlers/call.rs b/src/handlers/call.rs
index d95ebc4a4..6d03eed9a 100644
--- a/src/handlers/call.rs
+++ b/src/handlers/call.rs
@@ -311,7 +311,7 @@ impl StanzaHandler for CallHandler {
                                             call_creator: call.action.call_creator(),
                                             state: VideoState::UpgradeAccept,
                                             dec: Some("H264,AV1"),
-                                            device_orientation: None,
+                                            device_orientation: Some(0),
                                         });
                                         if let Err(e) = client.send_node(accept).await {
                                             warn!(
@@ -327,8 +327,8 @@ impl StanzaHandler for CallHandler {
                                             id: &client.generate_request_id(),
                                             call_creator: call.action.call_creator(),
                                             state: VideoState::Enabled,
-                                            dec: None,
-                                            device_orientation: None,
+                                            dec: Some("H264"),
+                                            device_orientation: Some(0),
                                         });
                                         if let Err(e) = client.send_node(enabled).await {
                                             warn!(
@@ -1151,6 +1151,17 @@ mod tests {
         let video = &children[0];
         assert_eq!(video.tag, "video");
         assert_eq!(video.attrs().optional_string("state").as_deref(), Some("1"));
+        assert_eq!(
+            video.attrs().optional_string("dec").as_deref(),
+            Some("H264")
+        );
+        assert_eq!(
+            video
+                .attrs()
+                .optional_string("device_orientation")
+                .as_deref(),
+            Some("0")
+        );
 
         // The peer stopping its direction does NOT stop ours or disable the shared plane.
         let node = node_to_owned_ref(&video_stanza("6"));
diff --git a/src/voip/facade.rs b/src/voip/facade.rs
index a7d344e90..2acaf685a 100644
--- a/src/voip/facade.rs
+++ b/src/voip/facade.rs
@@ -1573,7 +1573,8 @@ impl CallHandle {
     }
 
     /// UPGRADE the call to video (we initiate): attaches the endpoints, enables the media plane,
-    /// and sends `<video state=11 dec="H264" voip_settings="video">`. The peer answers with
+    /// and sends `<video state=11 dec="H264" device_orientation="0" voip_settings="video">`.
+    /// The peer answers with
     /// `UpgradeAccept`/`Enabled` (surfaced as [`CallEvent::VideoStateChanged`]); media flows as
     /// soon as both planes are up. Also the way to start media on a `.video()` call whose builder
     /// endpoints you skipped.
@@ -1589,7 +1590,8 @@ impl CallHandle {
     /// ACCEPT the peer's video upgrade request (a `VideoStateChanged { state: UpgradeRequestV2 }`
     /// event): the token binds this action to that exact request, then the method attaches the
     /// endpoints, enables the media plane, and answers
-    /// `<video state=4 dec="H264,AV1">` followed by `<video state=1>` (Enabled).
+    /// `<video state=4 dec="H264,AV1" device_orientation="0">` followed by
+    /// `<video state=1 dec="H264" device_orientation="0">` (Enabled).
     pub async fn accept_video<S, K>(
         &self,
         request: VideoUpgradeToken,
@@ -1608,8 +1610,8 @@ impl CallHandle {
         .await
     }
 
-    /// Send the standalone `<video state=1>` used after a mid-call video upgrade. Captured
-    /// video-from-start callees do not need this extra stanza.
+    /// Send the standalone `<video state=1 dec="H264" device_orientation="0">` used after a
+    /// mid-call video upgrade. Captured video-from-start callees do not need this extra stanza.
     pub async fn announce_video_enabled(&self) -> Result<(), CallError> {
         self.ensure_current()?;
         let transition_lock = self
@@ -1625,8 +1627,8 @@ impl CallHandle {
             id: &client.generate_request_id(),
             call_creator: &self.call_creator,
             state: VideoState::Enabled,
-            dec: None,
-            device_orientation: None,
+            dec: Some(VIDEO_DEC_REQUEST),
+            device_orientation: Some(0),
         });
         client.send_node(stanza).await?;
         Ok(())
@@ -1746,7 +1748,7 @@ impl CallHandle {
                 call_creator: &self.call_creator,
                 state,
                 dec,
-                device_orientation: None,
+                device_orientation: Some(0),
             });
             let client = client.clone();
             async move { client.send_node(stanza).await }
@@ -1765,7 +1767,9 @@ impl CallHandle {
                 if let Err(e) = send_state(VideoState::UpgradeAccept, Some(VIDEO_DEC_ACCEPT)).await
                 {
                     Err(e)
-                } else if let Err(e) = send_state(VideoState::Enabled, None).await {
+                } else if let Err(e) =
+                    send_state(VideoState::Enabled, Some(VIDEO_DEC_REQUEST)).await
+                {
                     // The peer times out an incomplete handshake; keep local media aligned with it.
                     warn!(
                         "voip: video upgrade handshake failed call_id={} phase=enabled_after_accept error={e}",
@@ -3893,6 +3897,10 @@ mod tests {
         assert_eq!(ar.tag, "video");
         assert_eq!(ar.attrs().optional_string("state").as_deref(), Some("11"));
         assert_eq!(ar.attrs().optional_string("dec").as_deref(), Some("H264"));
+        assert_eq!(
+            ar.attrs().optional_string("device_orientation").as_deref(),
+            Some("0")
+        );
         assert_eq!(
             ar.attrs().optional_string("voip_settings").as_deref(),
             Some("video"),
@@ -4002,6 +4010,10 @@ mod tests {
             ar.attrs().optional_string("dec").as_deref(),
             Some("H264,AV1")
         );
+        assert_eq!(
+            ar.attrs().optional_string("device_orientation").as_deref(),
+            Some("0")
+        );
         assert_eq!(
             ar.attrs().optional_string("voip_settings"),
             None,
diff --git a/wacore/src/stanza/call.rs b/wacore/src/stanza/call.rs
index 7d26810f1..64ffd1a38 100644
--- a/wacore/src/stanza/call.rs
+++ b/wacore/src/stanza/call.rs
@@ -844,7 +844,7 @@ pub struct VideoStateParams<'a> {
     pub id: &'a str,
     pub call_creator: &'a Jid,
     pub state: VideoState,
-    /// `dec` attr: codecs we can decode (`"H264"` on the upgrade request, `"H264,AV1"` on accept).
+    /// `dec` attr: codecs we can decode (`"H264"` on request/enabled, `"H264,AV1"` on accept).
     pub dec: Option<&'a str>,
     pub device_orientation: Option<u8>,
 }