fix(client-runtime): slow config snapshots no longer drop working connections

[saphid]

Model: built with Claude Opus 5.5, Claude Sonnet 5.5 in Claude Code.

Problem

A client gives each connection attempt one fixed setup budget (15 seconds per saved route). It covers resolving credentials, creating the session, opening the socket and receiving the first config snapshot. When a server is slow to build that snapshot (a cold restart with a large database on a loaded machine), the attempt times out with the socket already open and working. The client tears it down and retries against a server that is no faster, and loops. I saw this loop for about 10 minutes. Fixes #14516.

Change

EnvironmentSupervisor keeps the setup budget of 15 seconds per saved route. Each route that reaches the driver's synchronizing stage (the session exists and the socket is opening) adds 75 seconds to the attempt's deadline for the socket to open (still capped at 15 seconds by the RPC session) and the first config snapshot to arrive. A route that fails late in its snapshot therefore does not eat the next route's time. Attempts that never reach synchronizing time out as before. A socket that closes still fails the attempt immediately. The deadline uses monotonic time, so a wall-clock correction cannot cut it short.

The budget is pooled per attempt: 15 seconds for each saved route, plus 75 seconds for each route that reports synchronizing. It is not a separate 90-second cap per route. The trade-off: a socket that opens but never delivers a snapshot is now given up on after up to 90 seconds instead of 15 with one saved route. With two saved routes where the first opens and hangs, the attempt has 105 seconds (2 × 15 + 75), so falling back to the second route takes that much longer. Web, desktop and mobile share this code.

Scope and approval

Fixes triaged bug #14516. One timeout in packages/client-runtime/src/connection/supervisor.ts. No server, contract or UI changes.

Verification

Rebased on main 37de6cbde6, which added multi-route connections (#15467), and later merged with current main.

• New test "keeps a working socket open while a slow server config snapshot arrives": the snapshot arrives 40 seconds into the attempt and the connection is kept. It fails on main, where the attempt is torn down at 15 s.
• New test "gives the next route its own snapshot budget after a route fails while synchronizing": the LAN route fails 50 s into its snapshot and T3 Connect needs 40 s. It fails without the per-route budget and passes here.
• "retries when a session never becomes ready" now checks that the attempt survives 89 s (15 s setup plus 75 s snapshot) and times out at 90 s.
• vp test run packages/client-runtime/src/connection/supervisor.test.ts: 59 passed. Typecheck, lint and format are clean on the changed files.
• Real transport check (independent validation, GPT-6.1 Sol, at c511c0d on lxso3): a loopback WebSocket server answered Ping and delayed a valid config snapshot by 20 s, driven by the production RpcSession and EnvironmentSupervisor (driver and auth dependencies bypassed). This branch connected after 20.048 s on one socket. The same fixture against main (91e93a2) gave up and entered backoff at 15.025 s. This is a controlled transport fixture, not a full server or a cold 32.8 GB database; the ~10 minute loop in [Bug]: Client: a slow first config snapshot makes clients drop working connections and reconnect-loop #14516 was not remeasured.
• 2026-10-14, after merging current main (dff750b) with no conflicts (head f0e3657; main's supervisor changes only add a connectionLost span and a route type): vp test run on supervisor.test.ts, rpc/session.test.ts and connection/routes.test.ts: 97 passed in 3 files. packages/client-runtime typecheck exits 0 (only Effect suggestions in unrelated files). vp lint on the two changed files: clean.
• Not exercised in a real web, desktop or mobile client against a slow server.

Implemented and tested by Claude Sonnet 5.5 and Claude Opus 5.5 in Claude Code, running inside T3 Code. Reviewed by GPT-6.1 Sol in Codex. Merge with current main and re-verification: Claude Opus 5.5 (Claude Code) via T3 Code; review GPT-6.1 Sol.

🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Approved at c511c0d

Macroscope's review found this PR approvable — This is a focused client-runtime timeout bug fix that keeps healthy connections alive during slow configuration snapshots while preserving bounded setup behavior and fallback handling. Targeted tests cover the changed timing paths, with no schema, infrastructure, security, billing, or configuration-default changes.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 137d2009-4d28-420b-badf-ec2bde5b3f7a

📥 Commits

Reviewing files that changed from the base of the PR and between 592d051 and c511c0d.

📒 Files selected for processing (2)

• packages/client-runtime/src/connection/supervisor.test.ts
• packages/client-runtime/src/connection/supervisor.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

📝 Walkthrough

The connection supervisor now calculates a monotonic timeout deadline from a 15-second setup budget per route and a 75-second budget for each route that reaches synchronization. Tests cover delayed readiness, timeout, and route fallback.

Changes: Connection timeout handling

Layer / File(s)	Summary
Route-aware connection timeout packages/client-runtime/src/connection/supervisor.ts, packages/client-runtime/src/connection/supervisor.test.ts	The supervisor tracks routes that reach synchronization and recalculates the timeout deadline using per-route setup and synchronization budgets. Tests cover a 40-second synchronization, timeout after 90 seconds without readiness, and fallback to a relay route after the first route fails.

Priority: ⬆️ High

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to c511c

The extended snapshot wait appears consistent with the intended connection behavior. No actionable merge-blocking risk was established.

Security Architecture Review

Security architecture risk: 🔵 Low · up to c511c

The change gives slow servers more time to deliver their initial configuration, but also lets an unresponsive server hold a connection attempt longer. The inspected identity checks, readiness requirements, socket-open timeout and cleanup paths remain intact. No introduced security vulnerability was established.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — An already selected endpoint that delays or withholds its initial snapshot can retain that client's environment-connection attempt longer. The changed exposure is connection retention and delayed fallback, not additional identity or service authority. With a fixed finite route list, each route contributes at most one synchronization increment through the inspected sequential driver path.

Trust Boundaries and Controls

• observed — The extended wait does not remove the initial-configuration environment check or allow synchronization progress alone to expose a connected session. Those controls predate this PR and remain on the inspected establishment path.

Resilience and Maintainability Implications

• observed — Each attempt creates a fresh counter. Failed route scopes close before subsequent routes are attempted, supervisor attempts run within a scope, and lease references are cleared on exit. Timeout and interruption remain terminal establishment outcomes, preserving the inspected cleanup and failure-containment structure despite the longer deadline.

Pre-merge checks: 5

Passed checks: 5 passed

Check name	Status	Explanation
Linked Issues check		Issue #14516 requires the client to keep a working socket while waiting for the first config snapshot. EnvironmentSupervisor retains the 15-second setup budget until synchronizing, then adds a 75-…
Out of Scope Changes check		The current whole-PR summary lists changes only to supervisor.ts and its regression tests in supervisor.test.ts. The timeout change and tests directly support issue #14516. The earlier out-of-scop…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Title check		The title clearly and concisely describes the main change: preventing slow configuration snapshots from dropping working client connections.
Description check		The description includes the required Problem, Change, Scope and approval, and Verification sections. It explains the issue, implementation, scope, tests, observed results, limitations, and the models…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

_{Comment @coderabbitai help to get the list of available commands.}

[saphid]

Review requested

Date (UTC)	Reviewer	Where
2026-10-06	Julius	Discord DM

_{Logged so this PR shows when a maintainer was asked to review it.}