fix: resync clients on broadcast lag (audit round 3, P4) (#27)

When a client's broadcast receiver overflowed, both forwarders logged the
RecvError::Lagged and continued, so a dropped GridDiff left the screen
corrupt until the next unrelated FullRefresh.

Add Session::focused_window_full_refresh, which rebuilds a FullRefresh for
every pane in the focused window, and call it from both forwarders on lag:

- IPC forwarder (session_dispatch): replay each pane's current grid to the
  client, capturing the sessions Arc + session name into the task.
- WebSocket forwarder (ws): same, converted to text for xterm.js.

Also update the audit report with the implementation status.

Tested: focused_window_full_refresh_covers_every_pane (ignore-gated like the
other PTY-spawning tests). cargo test / clippy -D warnings / fmt --check green.

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Happy <yesreply@happy.engineering>

Author: 3 people

docs/plans/audit-round3-2026h2.md

@@ -7,6 +7,11 @@
 - **Predecessors:** Round 1 (completed at v1.1.0), Round 2 (70 items, most HIGH resolved).
   This round only reports findings not already tracked or resolved there.
 
+## Implementation status
+
+- **Done:** P1, B1, P2, R1 (PR #26, squashed to `master`), P4 (this change).
+- **Deferred (still tracked below):** P3, C2, P5, P6, P7, S1 (LOW), R5/A5.
+
 ## Baseline statistics
 
 | Metric | Value | Note |

nexterm-server/src/ipc/session_dispatch.rs

@@ -79,6 +79,10 @@ pub(super) async fn handle_attach(ctx: &mut DispatchContext<'_>, session_name: &
             };
             if let Some(mut bcast_rx) = bcast_rx {
                 let fwd_tx = tx.clone();
+                // Captured so the forwarder can rebuild a full refresh when the
+                // broadcast receiver lags (audit round 3, P4).
+                let resync_sessions = manager.sessions();
+                let resync_name = session_name.to_string();
                 if let Some(h) = ctx.bcast_forwarder.take() {
                     let _: () = h.abort();
                 }
@@ -91,10 +95,35 @@ pub(super) async fn handle_attach(ctx: &mut DispatchContext<'_>, session_name: &
                                 }
                             }
                             Err(tokio::sync::broadcast::error::RecvError::Lagged(n)) => {
+                                // The client fell behind and lost `n` messages;
+                                // a dropped GridDiff would leave the screen
+                                // corrupt, so replay the current grid of every
+                                // pane in the focused window to resync (P4).
                                 tracing::warn!(
-                                    "broadcast: skipped {} messages (buffer overflow)",
+                                    "broadcast: client lagged by {} messages; resyncing with full refresh",
                                     n
                                 );
+                                let refreshes = {
+                                    let sessions = resync_sessions.lock().await;
+                                    sessions
+                                        .get(&resync_name)
+                                        .map(|s| s.focused_window_full_refresh())
+                                        .unwrap_or_default()
+                                };
+                                let mut disconnected = false;
+                                for (pane_id, grid) in refreshes {
+                                    if fwd_tx
+                                        .send(ServerToClient::FullRefresh { pane_id, grid })
+                                        .await
+                                        .is_err()
+                                    {
+                                        disconnected = true;
+                                        break;
+                                    }
+                                }
+                                if disconnected {
+                                    break;
+                                }
                                 continue;
                             }
                             Err(tokio::sync::broadcast::error::RecvError::Closed) => break,

nexterm-server/src/session.rs

@@ -137,6 +137,23 @@ impl Session {
         self.windows.get_mut(&self.focused_window_id)
     }
 
+    /// Build a full refresh for every pane in the focused window.
+    ///
+    /// Used to resync a client after its broadcast receiver lagged and dropped
+    /// `GridDiff` messages (audit round 3, finding P4). A single dropped diff can
+    /// leave the screen permanently corrupt, so on overflow the forwarder replays
+    /// the current grid of each pane instead of silently continuing.
+    pub fn focused_window_full_refresh(&self) -> Vec<(u32, nexterm_proto::Grid)> {
+        match self.focused_window() {
+            Some(window) => window
+                .pane_ids()
+                .into_iter()
+                .filter_map(|id| window.pane(id).map(|p| (p.id, p.make_full_refresh())))
+                .collect(),
+            None => Vec::new(),
+        }
+    }
+
     /// Attach a client and return its `broadcast::Receiver`.
     ///
     /// Supports multiple simultaneous clients. PTY output is automatically delivered to every
@@ -1400,6 +1417,30 @@ mod tests {
         assert!(!session.broadcast);
     }
 
+    #[tokio::test]
+    #[ignore = "spawns a PTY; hangs on interactive shell close in regular CI"]
+    async fn focused_window_full_refresh_covers_every_pane() {
+        // Audit round 3 (P4): the lag-resync path replays a full refresh for
+        // each pane in the focused window. Verify one entry per pane, keyed by id.
+        let shell = nexterm_config::ShellConfig::default();
+        let session =
+            Session::new("resync".to_string(), 80, 24, shell.program, shell.args).unwrap();
+
+        let expected_ids = session
+            .focused_window()
+            .map(|w| w.pane_ids())
+            .unwrap_or_default();
+        assert!(!expected_ids.is_empty(), "a new session has one pane");
+
+        let refreshes = session.focused_window_full_refresh();
+        assert_eq!(refreshes.len(), expected_ids.len());
+        for (pane_id, grid) in &refreshes {
+            assert!(expected_ids.contains(pane_id));
+            assert_eq!(grid.width, 80);
+            assert_eq!(grid.height, 24);
+        }
+    }
+
     #[tokio::test]
     #[ignore = "spawns a PTY; hangs on interactive shell close in regular CI"]
     async fn session_info_returns_correct_metadata() {

nexterm-server/src/web/handlers/ws.rs

@@ -123,7 +123,32 @@ async fn handle_socket(mut socket: WebSocket, manager: Arc<SessionManager>, sess
                             }
                     }
                     Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
-                    Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => {}
+                    Err(tokio::sync::broadcast::error::RecvError::Lagged(n)) => {
+                        // The browser fell behind and lost `n` diffs; replay the
+                        // focused window's panes so the terminal resyncs instead
+                        // of rendering on top of a corrupt screen (audit round 3, P4).
+                        warn!("WebSocket: client lagged by {} messages; resyncing", n);
+                        let refreshes = {
+                            let sessions = sessions_arc.lock().await;
+                            sessions
+                                .get(&session_name)
+                                .map(|s| s.focused_window_full_refresh())
+                                .unwrap_or_default()
+                        };
+                        let mut disconnected = false;
+                        for (pane_id, grid) in refreshes {
+                            let msg = nexterm_proto::ServerToClient::FullRefresh { pane_id, grid };
+                            if let Some(text) = pty_message_to_text(&msg)
+                                && socket.send(Message::Text(text)).await.is_err()
+                            {
+                                disconnected = true;
+                                break;
+                            }
+                        }
+                        if disconnected {
+                            break;
+                        }
+                    }
                 }
             }
             result = socket.recv() => {