Fix self-sustaining WebRTC reconnect storm in remote transport

[MarvinSchenkel]

Problem

In remote (WebRTC) mode the transport could enter a perpetual reconnect loop: a healthy connection — data channel open, ICE connected — was torn down and rebuilt roughly every 2 seconds and never stabilised. On iOS PWAs this surfaced as an endless connecting → connected → reconnecting cycle after backgrounding the app, and server-side as a new WebRTC session created and destroyed every ~2s.

Root cause

Three compounding issues in WebRTCTransport (src/plugins/remote/webrtc-transport.ts):

1. cleanup() re-triggered recovery (the engine of the loop). Each reconnect runs cleanup() then connect(). cleanup() closed the data channel while its onclose handler was still attached, and that handler calls scheduleReconnect(). So the act of tearing down to reconnect scheduled another reconnect — and since connect() re-creates a healthy channel, the next cleanup closed a healthy channel and re-armed the loop. Once entered it never stopped.
2. connect() / scheduleReconnect() were not serialised. Multiple recovery drivers (dataChannel.onclose, signaling peer-disconnected, ICE/connection failed) — all of which fire together on a real network drop or iOS resume — ran concurrently and corrupted the shared peer connection / SDP state (InvalidModificationError: setLocalDescription ... SDP does not match). The previous guard only blocked while RECONNECTING with a pending timer.
3. Backoff never escalated. reconnectAttempts reset to 0 on every successful connect; because each storm cycle briefly succeeds, the delay stayed flat (~1.5s) instead of backing off.

Changes

• Detach handlers before close in cleanup() (data channel + peer connection) so teardown no longer re-enters the recovery path.
• Serialise connect() via an in-flight guard, and bail from scheduleReconnect() when a reconnect is already pending or a connect is in flight.
• Defer the backoff reset until the connection has been stable for 5s, and add jitter to the reconnect delay.
• Only treat the terminal ICE failed state as a failure; let the transient disconnected state self-heal (it usually recovers on its own; the browser escalates disconnected → failed if it does not). This aligns with WebRTC guidance.

Verification

Reproduced deterministically against a local debug server (frontend dev build connected over real WebRTC/signaling), correlating client console + server logs:

	Before	After
Concurrent connect()	InvalidModificationError, teardown	extra calls bail cleanly, single negotiation
Sustained flapping	stuck reconnecting 25s+ after triggers stop	recovers to connected, no pending timer, attempts reset
Server sessions	new session every ~2s, indefinitely	churn bounded to the trigger window, then quiet

vue-tsc --noEmit, ESLint, and the vitest suite (176 tests) all pass.

Follow-up (not in this PR)

In-place ICE restart recovery (restartIce()). The WebRTC-recommended way to recover from a connectivity drop is an in-place ICE restart, which preserves DTLS keys and data channels instead of tearing down and rebuilding the whole RTCPeerConnection. This PR makes the existing teardown-and-rebuild path correct and bounded; it does not adopt restartIce().

Adopting it requires the server to support in-place renegotiation on an existing peer connection (today the gateway creates a fresh RTCPeerConnection per signaling session), so it is best done alongside the planned switch to a server-side WebRTC library with trickle-ICE support. At that point the natural companion change is to add a short grace timer on ICE disconnected that triggers restartIce() (cheap recovery) rather than waiting for failed. The serialised-negotiation guard added here is the foundation that work builds on.

[Copilot]

Pull request overview

This PR addresses a self-sustaining reconnect loop (“reconnect storm”) in the remote WebRTC transport by preventing teardown from re-triggering recovery, serializing connection attempts to avoid SDP/PC state corruption, and making reconnect backoff behave correctly under flapping connections.

Changes:

• Detach DataChannel/PeerConnection handlers before closing in cleanup() to avoid teardown re-entering reconnection logic.
• Serialize connect() and gate scheduleReconnect() to prevent concurrent negotiations and duplicate reconnect scheduling.
• Improve reconnect backoff behavior by adding jitter and only resetting the backoff after the connection remains stable for 5 seconds; also treat ICE failed (not disconnected) as the failure signal.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[stvncode]

LGTM ✅