The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Connection runtime |
| 2 | |
| 3 | Web, the desktop renderer, and mobile share one connection owner per environment |
| 4 | in `packages/client-runtime`. Platform code supplies storage, credentials, network |
| 5 | signals, and application lifecycle events. React views consume the runtime. |
| 6 | Keeping retries and session lifetime here prevents competing reconnect loops when |
| 7 | several views need the same environment. |
| 8 | |
| 9 | ## One transport retry owner |
| 10 | |
| 11 | The [supervisor](../../packages/client-runtime/src/connection/supervisor.ts) owns |
| 12 | transport retry policy; resolving an endpoint and opening an RPC session are single |
| 13 | attempts. Transient failures retry with jittered exponential backoff, capped at |
| 14 | five minutes, that resets only after a connection stays up. Without jitter, every |
| 15 | client of a restarted server reconnects in the same second; with a short cap, a |
| 16 | client that can never connect retries all day. Offline states and authentication |
| 17 | failures wait for a wakeup instead of spending attempts on unchanged conditions. |
| 18 | |
| 19 | Foregrounding, a network change, an explicit retry, and an offline report probe |
| 20 | the established session, and only a failed probe reconnects. Offline reports are |
| 21 | often wrong, for example for a loopback server. The OS can kill a suspended |
| 22 | socket without a close event, so a probe still unanswered after 500 ms asks the |
| 23 | host for its public descriptor over a fresh request, again each second until it |
| 24 | answers. If the host answers while the socket delivers no frame, the socket is |
| 25 | dead and is replaced, even while the network reports offline: at once on |
| 26 | loopback and LAN, and 2.5 seconds after the check starts elsewhere, where one |
| 27 | lost packet can stall a live socket. Without that evidence the probe deadline |
| 28 | decides: 3 seconds on loopback and LAN routes and after a long mobile |
| 29 | suspension, when the data on screen is stale; 15 seconds elsewhere, because a |
| 30 | tailnet over DERP or a VPN can be slower than that on a live socket. A long |
| 31 | suspension's probe that times out also replaces the socket regardless of the |
| 32 | network report. The web and desktop foreground probe skips the fresh request, |
| 33 | because a busy host can answer it before a queued probe. Foregrounding also |
| 34 | wakes a pending retry immediately. A long suspension restarts an in-flight |
| 35 | attempt; a short one leaves it alone. |
| 36 | |
| 37 | The [registry](../../packages/client-runtime/src/connection/registry.ts) scopes |
| 38 | connections by environment. An involuntary disconnect retains the registration |
| 39 | and cached data. Explicit removal closes the scope and clears credentials, |
| 40 | projections, and platform-owned state such as drafts. Cloud-account changes apply |
| 41 | to relay registrations; they must not discard directly paired environments. |
| 42 | |
| 43 | ## HTTP authorization |
| 44 | |
| 45 | RPC sessions authenticate at socket upgrade, while HTTP requests need current |
| 46 | credentials from the |
| 47 | [authorization service](../../packages/client-runtime/src/authorization/service.ts). |
| 48 | Replacing a healthy socket for HTTP renewal would interrupt conversations and |
| 49 | change the transport generation without a transport failure. Refresh failure |
| 50 | belongs to the HTTP operation. |
| 51 | |
| 52 | The server closes a socket when its session is revoked or expires. T3 Connect |
| 53 | access tokens last one hour, so the driver renews a live socket's token in its |
| 54 | last minute. The server then moves the socket to the newer session for the same |
| 55 | DPoP key, subject, and scopes |
| 56 | ([`SessionStore.awaitInvalidation`](../../apps/server/src/auth/SessionStore.ts)). |
| 57 | If renewal fails, the socket closes at expiry and the supervisor reconnects. |
| 58 | |
| 59 | Session listings must retain unrevoked connected sessions after credential expiry |
| 60 | so an open connection does not disappear from connection management. This does |
| 61 | not extend the credential's lifetime. New HTTP requests and socket upgrades still |
| 62 | require valid credentials. |
| 63 | |
| 64 | ## Transport health and data freshness are separate |
| 65 | |
| 66 | A socket opening is insufficient evidence that the environment is usable. The |
| 67 | [RPC session](../../packages/client-runtime/src/rpc/session.ts) waits for the |
| 68 | initial server configuration before becoming ready. Shell and thread data then |
| 69 | have their own synchronization state. A failed shell subscription can coexist |
| 70 | with a healthy connection; labeling that state "reconnecting" promises a |
| 71 | transport retry that will never happen. |
| 72 | |
| 73 | Cached projections remain readable offline. They must neither imply a live |
| 74 | connection nor overwrite newer live data during a reconnect. Loading and |
| 75 | resuming snapshots belongs to the shared state services, so every view agrees |
| 76 | on which data is current. |
| 77 | |
| 78 | The shell snapshot loads over HTTP, which needs only the prepared connection, so |
| 79 | the [shell state](../../packages/client-runtime/src/state/shell.ts) can ask for |
| 80 | it before the socket and the config are ready. Two constraints follow. The live |
| 81 | config stays the authority: rows loaded early for a build or with omissions that |
| 82 | it does not confirm are replaced, never resumed. And an HTTP answer must never |
| 83 | land on rows the socket has moved on: the subscription waits for the answer, and |
| 84 | when held rows can resume, it ends the request 3 seconds after the socket is |
| 85 | ready. A proxy that drops `/api` without an answer then does not hold the |
| 86 | connect for the HTTP timeout. |
| 87 | |
| 88 | Each environment synchronizes at its own time, so a thread list that follows every |
| 89 | snapshot moves once per environment on each cold start and resume. Mobile lists read |
| 90 | [steady shells](../../packages/client-runtime/src/state/steadyShells.ts): an |
| 91 | environment's rows stay as shown until its connection's server snapshot arrives, |
| 92 | it is synchronized, or it disconnects, and environments that get there within two |
| 93 | seconds of each other show together. Only an environment that is connected or on |
| 94 | its first attempt, and still owes its snapshot, is waited for; a retry can take |
| 95 | minutes. A move in a list is refused while its rows wait, because its plan would |
| 96 | use order keys the server may have replaced. Every other row action looks up the |
| 97 | live row before it reads thread state, so an undo plan or a guard never uses a held |
| 98 | row. The hold stops only changes the user |
| 99 | did not cause: a command that moves or removes a row (settle, snooze, pin, archive, |
| 100 | delete, and their reverses) makes that environment's rows follow the live snapshot |
| 101 | until it is live. Point reads (a |
| 102 | thread's own shell, route checks) keep the live snapshot, where a row the server just |
| 103 | sent must not look missing. The decision reads the snapshot's own sequence: a second |
| 104 | atom derived from the same shell state can be one update behind the rows. The mobile |
| 105 | splash screen also waits, for a bounded time, until every enabled environment has |
| 106 | read its cached shell and Home's list has laid out those rows, so the first frame |
| 107 | holds all cached rows. |
| 108 | |
| 109 | Shell snapshots can leave rows out when the client asks. Servers that advertise |
| 110 | `shellThreadFamilies` leave out idle subagent children: a child stays while it |
| 111 | has a live or queued run, a pending request or background work, or a subagent |
| 112 | child of its own, so badge and working walks never meet a gap. Servers that also |
| 113 | advertise `shellOlderSettled` keep only the 25 newest settled top-level threads |
| 114 | (and any tied with the 25th, pinned, snoozed, live, or above a kept child); the |
| 115 | snapshot's `olderSettled` names that cut and counts the rest per project. Left-out |
| 116 | rows load on demand and merge behind shell rows |
| 117 | ([thread families](../../packages/client-runtime/src/state/threadFamilies.ts)): |
| 118 | the family a thread view or a queued message mounts holds every active thread |
| 119 | sharing the thread's root, so it also brings back an old settled thread opened by |
| 120 | link; the Settled shelf reads pages below the cut; searches return the rows of |
| 121 | older matches. A missing shell row therefore does not prove a thread is gone: |
| 122 | code that deletes data or a worktree on absence must check the family or the |
| 123 | server first. |
| 124 | |
| 125 | The Settled count is local Settled rows, minus local rows below the cut, plus the |
| 126 | server's counts |
| 127 | ([older settled threads](../../packages/client-runtime/src/state/olderSettledThreads.ts)). |
| 128 | The counts are re-read when a removal or an old row's arrival or change could |
| 129 | move them, so archiving any thread costs one small read. A shelf lists an older |
| 130 | row only above the highest page frontier of the environments that can still |
| 131 | load, so the merged list stays a correct prefix while a page loads. An |
| 132 | environment with no snapshot this session, or a failed page, holds no one back. |
| 133 | On-demand reads wait for the session's first authoritative snapshot |
| 134 | (`generation > 0`), and each is keyed by generation. A resume that skips that |
| 135 | snapshot must still bump `generation` once verified, and may reuse a cached |
| 136 | snapshot only when its omissions match what the session asks for. |
| 137 | |
| 138 | [Thread detail](../../packages/client-runtime/src/state/threads.ts) separates |
| 139 | subscription lifetime from cache lifetime. Mounted consumers share one live |
| 140 | stream, which stops when the last consumer unmounts; hidden mounted routes still |
| 141 | count. A registry-local cache retains state and its replay cursor for five idle |
| 142 | minutes so back navigation can resume without another snapshot download. |
| 143 | |
| 144 | The desktop app adds one consumer: a |
| 145 | [keep-alive](../../apps/web/src/state/threads.ts) mounts every thread whose |
| 146 | session is starting or running, in each enabled environment. Opening a running |
| 147 | thread then needs no replay. The shell and detail streams are independent, so |
| 148 | the shell can report a stop before the detail loads or catches up. A stopped |
| 149 | thread stays mounted until its own stream is live and shows the stop, and the |
| 150 | stream then closes and saves the settled state. |
| 151 | Web and mobile do not keep threads alive. |
| 152 | |
| 153 | Retain state and cursor together only after an update finishes. Cancellation must |
| 154 | not advance the cached cursor beyond the applied data, and an old scope must not |
| 155 | overwrite its successor's cache. Preserve pagination data on reuse, but clear |
| 156 | canceled loading state. |
| 157 | |
| 158 | The [RPC boundary](../../packages/client-runtime/src/rpc/client.ts) resolves |
| 159 | requests against the current session at execution time. Durable subscriptions |
| 160 | follow replacement sessions. After a transport failure they wait for the |
| 161 | supervisor; an expected domain failure may resubscribe on the same healthy |
| 162 | session. Reconnection does not automatically replay mutations, whose retry and |
| 163 | idempotency rules belong to the operation. |