Designing Reconnect-Safe Event Streams for Remote Coding Agents

Reconnecting remote coding agent interfaces can be deceptive due to data-consistency issues, despite the socket appearing to be operational. The WebSocket protocol only confirms the ability to exchange frames in real-time, not the completeness of event data. For a remote agent client to function correctly, it must determine which events exist for a given session, which ones have already been rendered by the client, which actions have reached a terminal state, and whether another client has sent a newer command. Additionally, the protocol must address replaying history without duplicating live output.

There are four main gaps that cause these problems: the transport gap, the persistence gap, the rendering gap, and the semantic gap. To resolve these issues, every session should have a monotonic event log with stable identities and ordering. This ensures that replaying events is harmless and child events refer to stable parents rather than array positions.

Cold history and live events must share a deduplication key, so the client can safely merge them without displaying duplicates or making inaccurate guesses based on text and timestamps.

Terminal states must only move forward, meaning permissions, questions, tool calls, scheduled jobs, and subagents should have a monotonic UI state progression from pending to completed or failed. Merge state by version or sequence, treating terminal states as terminal and preferring the state with stronger evidence when two sources disagree.

Multi-client control adds a write-coordination problem, requiring idempotency keys for every write. The relay should acknowledge the command ID, and the agent bridge should remember enough accepted IDs to reject accidental retries. Observability should test invariants, not just uptime, to detect issues like lost data during reconnections. By addressing these considerations, remote coding agent interfaces can be designed to reliably reconnect and maintain data consistency.