How We Handle Network Interruptions Gracefully

If you've ever used a remote tool that shows a spinner after a brief network glitch and fails to recover, you understand why we obsess over reconnection reliability. In the world of mobile development tools, network interruptions aren't edge cases — they're the common case. Phones switch between Wi-Fi and cellular. Elevators block signals. Coffee shop networks are unreliable by nature.

Tactic Remote's reconnection engine is designed around one principle: network interruptions should be invisible to the user whenever possible, and gracefully communicated when they can't be.

The State Machine

At the heart of our reconnection logic is a finite state machine with six states:

┌──────────┐     connect     ┌───────────┐
│ INITIAL  │───────────────►│ CONNECTED │◄─────────────┐
└──────────┘                 └─────┬─────┘              │
                                   │                    │
                              disconnect           reconnect
                                   │              success │
                              ┌────▼─────┐              │
                              │ UNSTABLE │──── retry ───►│
                              └────┬─────┘    (1-3s)    │
                                   │                    │
                              3 failures           ┌────┴─────┐
                                   │               │RECOVERING│
                              ┌────▼─────┐        └────┬─────┘
                              │RECONNECT │── retry ────►│
                              │  ING     │  (5-30s)     │
                              └────┬─────┘              │
                                   │                    │
                              timeout (5min)            │
                                   │                    │
                              ┌────▼─────┐              │
                              │DISCONNEC │─── manual ───┘
                              │  TED     │   reconnect
                              └──────────┘

CONNECTED: Normal operation. Data flows freely.

UNSTABLE: A connection attempt failed, but we suspect it's transient. Retries happen at 1-3 second intervals. The UI shows a subtle warning indicator but doesn't interrupt the user.

RECONNECTING: Multiple failures suggest a real problem. Retry intervals increase exponentially (5s, 10s, 20s, 30s cap). The UI shows a clear "reconnecting" banner.

RECOVERING: Connection re-established, but we need to synchronize state. The client requests a state delta from the server, applies it, and transitions to CONNECTED once reconciliation completes.

DISCONNECTED: We've exceeded the retry timeout (default: 5 minutes). The user must manually trigger reconnection. This prevents infinite battery drain on truly offline devices.

The Reconciliation Protocol

Reconnection is easy. Reconciliation — getting the client and server back in sync — is the hard part.

When the iPhone reconnects after an interruption, it sends the server its last known state vector: the sequence number of the last terminal update it processed, the session ID, and a timestamp. The server uses this to compute exactly what the client missed.

Scenario 1: Short interruption (< 30 seconds). The server's output buffer still contains all missed updates. It replays them in order, and the client applies them sequentially. From the user's perspective, the terminal "catches up" in under a second — they see a brief burst of scrolling as missed output appears.

Scenario 2: Medium interruption (30 seconds - 5 minutes). The output buffer may have partially rotated. The server sends a partial replay followed by a full terminal snapshot. The client applies the replay, then validates against the snapshot to ensure consistency.

Scenario 3: Long interruption (> 5 minutes). The server sends only a full snapshot. The client replaces its entire state. This is the least efficient path but guarantees correctness regardless of how much was missed.

type ReconciliationResponse = {
  method: 'replay' | 'replay_and_snapshot' | 'snapshot'
  replay?: TerminalUpdate[]
  snapshot?: TerminalSnapshot
  sessions: SessionState[]
  pendingApprovals: ApprovalRequest[]
}

Notice that reconciliation also includes pendingApprovals. If Claude Code requested approval while the phone was offline, that request is delivered as part of reconnection. This is critical — without it, Claude Code could remain waiting for an approval the user did not see.

Edge Cases That Tried to Break Us

The Mid-Approval Disconnect

A user receives an approval notification, taps "Approve," and loses connectivity before the approval reaches the server. Does the action execute?

Our solution: approvals use an acknowledgment protocol. The server doesn't execute the approved action until it receives the client's approval message AND confirms receipt back to the client. If the connection drops mid-approval, the approval is retransmitted on reconnection. Duplicate approvals are idempotent — sending "approve request #47" twice has the same effect as sending it once.

The Session-Ended-While-Offline Case

Your Claude Code task completes while your phone is offline. When you reconnect, the session is in a terminated state. Should the client show the final output? The completion notification? Both?

We handle this by including a sessionEndState in the reconciliation response. The client renders the final terminal state and shows a "Task completed while offline" banner with a summary of what happened. The user sees the outcome immediately rather than staring at stale in-progress output.

The Mac-Restarted Case

The most challenging scenario: your Mac restarts while the phone is offline (due to a system update, power failure, or crash). When the phone reconnects, the server has no memory of previous sessions.

Our solution: the Mac companion app persists session metadata (session IDs, project paths, last known states) to disk. On restart, it reads this metadata and, where possible, reattaches to surviving tmux sessions. The reconciliation protocol detects the server restart via a server-epoch counter and initiates a full state rebuild rather than attempting incremental reconciliation.

Performance Characteristics

We measure reconnection performance across three metrics:

Time to visual recovery — how long from network restoration until the user sees current terminal state. Our P95 is 1.8 seconds for local network and 3.2 seconds for Cloudflare tunnel.

Data efficiency — how much data is transferred during reconciliation versus a full refresh. For interruptions under 60 seconds, our reconciliation protocol transfers 85% less data than a full refresh.

Correctness — zero tolerance for state inconsistency. We run continuous integration tests that simulate thousands of disconnect/reconnect cycles with randomized timing and verify that final client state matches server state byte-for-byte.

Lessons for Builder

If you're building any kind of real-time mobile application, our experience suggests three principles:

1. Design for disconnection from day one. Adding reconnection to a system designed for continuous connectivity is orders of magnitude harder than building with intermittent connectivity as a first-class concern.

2. Idempotency is your best friend. Every client-to-server message should be safe to replay. This single property eliminates entire categories of reconnection bugs.

3. Test with real networks, not simulators. Network condition simulators can't reproduce the full diversity of real-world failures — partial packet delivery, DNS resolution delays, TLS handshake timeouts. We test on actual cellular networks, in elevators, and on congested conference Wi-Fi.

Reliable reconnection isn't glamorous work. Users don't praise it when it works — they simply don't notice interruptions. But when it fails, trust evaporates instantly. We think the investment is worth it, and our users' willingness to rely on Tactic Remote for production workflows suggests they agree.