How does a phone terminal survive reconnects without losing work?

Direct answer

A phone terminal reconnect works when the terminal session lives on the server and the browser connection is treated as an attachable, replaceable transport. The UI reconnects to a stable session_id, the server re-attaches to the existing session, and the server replays a bounded buffer of recent output so the operator can pick up where the session left off.

Mechanism (what has to be true)

1) Session identity is separate from the connection

The key design decision: a connection is not a “session.” It is a pipe.

A durable terminal needs a stable identifier:

• The UI chooses a session_id (for example, derived from “window + tab” state).
• The server uses session_id as the primary key for:
  • the terminal process
  • output buffers
  • metadata (created time, last-seen time)

When the connection drops, the session does not go away unless you explicitly choose that policy.

2) Attach/detach is explicit

On connect:

• if session_id exists -> attach
• if it does not exist -> create and attach (or return a “missing” error)

On disconnect:

• mark the session as “no active client”
• keep the session alive for a bounded time
• continue buffering output (bounded)

This is “long-lived compute with short-lived clients.”

3) Output continuity requires buffering

Without buffering, a reconnect can attach to the session, but the operator still loses the output that occurred while they were offline. On mobile, that gap is common.

A practical buffering contract:

• buffer the last K output chunks (ring buffer)
• replay the buffer on attach
• then switch to live streaming

This is enough to answer “what happened while I was away?” without turning the system into a logging platform.

4) Reconnect must be treated as normal traffic

If reconnect is “exceptional,” it won’t get tested. A phone-first terminal should assume:

• the OS will suspend the tab
• the carrier will drop a TCP connection
• the user will switch apps and come back later

Design for that reality:

• use a reconnect loop with backoff
• keep attach idempotent (connecting twice should not spawn two sessions)
• surface session state in the UI (connected / reconnecting / detached)

Common failure modes

Failure mode: “Reconnect creates a new session”

Symptom: each reconnect spawns a fresh shell; the old one keeps running or is lost.

Root cause: the server treats “connect” as “create” without a stable key, or the client generates a new ID each time.

Fix: make session_id stable and creation idempotent.

Failure mode: “Reconnect attaches, but output is confusing”

Symptom: the terminal appears blank after reconnect, or the user misses critical output (build finished, error printed).

Root cause: no replay buffer (or replay happens after live streaming and the ordering is wrong).

Fix: replay buffer first, then live stream; keep chunk order stable.

Failure mode: “Sessions leak forever”

Symptom: old sessions accumulate; CPU/memory slowly increases.

Root cause: sessions never expire, and the system assumes clients always disconnect cleanly.

Fix: implement TTL reaping based on last_seen and explicit “drop session” admin controls.

Failure mode: “Network flaps cause cascading reconnect loops”

Symptom: UI keeps reconnecting; server keeps creating/closing connections; the terminal becomes unusable.

Root cause: reconnect loop has no backoff, or server sends hard close codes aggressively.

Fix: exponential backoff with jitter; treat transient disconnects as expected.

How to verify (practical checks)

1. Hard drop network

   • On a phone: toggle airplane mode for 5–10 seconds, then restore connectivity.
   • Expected: the UI reconnects; output from the offline interval is visible (replayed), then live resumes.

2. Background the tab

   • Switch apps for a minute; return.
   • Expected: either the connection stayed up or it reconnects; the session is the same.

3. Attach idempotency

   • Open the same terminal in two browser tabs (or simulate rapid reconnect).
   • Expected: you either get a clean “already attached” policy or a controlled handoff; you do not get two sessions.

4. TTL reaping

   • Detach; wait past TTL; attempt reconnect.
   • Expected: you get a clear “session expired” result and a new session can be created intentionally.

Link up (pillar)

• Phone Terminal Codex
• Join for $37/mo

Read next (sibling)

• Output buffering and replay for long-running sessions

Scope boundary

This note describes behavioral contracts and verification checks. It does not provide a deployable public terminal recipe. Any exposure to untrusted networks requires authentication, TLS, and strict filesystem and process boundaries.