[jayleaton]

JJ's phone connects after a Tailscale reset, drops about 30 s later, then shows "reconnecting" for minutes. The server logs show the phone's path dying, not the app stalling. This PR keeps a foregrounded app retrying at least every 15 s, and gives the phone a connection log so the next failure explains itself.

Evidence (2026-11-04)

Source	Finding
dev-box ws log	Phone (T3Agents/10, iOS) connected at 16:42:08 and sent its last frame at 16:42:33.6 (the 25 s activity report). The server reset it as client-silent at 16:44:03.8. Every phone socket that day (11:42, 11:44, 11:46, 15:27, 16:44) ended the same way. 0 send-stalled.
Studio-01 ws log	0 send-stalled, 9 client-silent, all from mobile. The 16:42:10 socket ended after 103 s as Interrupted.
After the drop	Only one phone request reached either server in the next 12+ minutes (a descriptor GET at 16:44:16). The phone wasn't hammering a dead socket; it was barely reaching anything.
dev-box tailscaled	The iPhone's endpoint flapped every 10–15 s between cellular IPv4 and two IPv6 addresses, with no path from 16:40:48 to 16:43:48. A direct tailscale ping worked again at ~17:03 (46 ms).
Shell fetch timing	10–15 s server-side for the phone over cellular, vs 0.8 s at 11:42 and 0.6 s for the Mac. Network, not CPU.
JS stall bench	Decoding and applying a real shell snapshot is far below the 25 s/90 s budgets. Ruled out.

What each hypothesis does now

• JS stall: ruled out by the bench above. No change.
• "Reconnecting forever" while foregrounded: fixed. On a supervisor failure, backoff is capped at 15 s while the app is foregrounded (AppState on mobile, visibilityState on web/desktop). Backgrounded clients keep the existing exponential backoff, so a pocketed phone doesn't drain the battery. TestClock test: 40×15 s foregrounded gives ≥30 attempts (fails at 9 without the cap); backgrounded gives <10 in 10 min.
• Hard timeouts / hung fetch or socket: already bounded. HTTP steps time out at 10 s, socket open at 15 s, ping at 30 s, and the supervisor has an establishment budget. Release is a synchronous ws.close, and fetches abort on interrupt. I found no path that hangs.
• Watchdog restarting the supervisor fiber: declined. The run loop can't hang (above), and a second loop that restarts the first risks two competing reconnect loops, the class of bug fix(client-runtime): connections stay put and offline machines stop saying reconnecting #191 fixed. If the log ever shows a stuck attempt, it'll name the stage, and we fix that stage.
• Stale pooled connection: no header or URL trick forces a new connection on iOS. NSURLSession ignores Connection: close (and it's illegal in h2), and a unique URL still reuses the per-origin pool. The WebSocket (SocketRocket) opens a fresh TCP connection every attempt, and route checks already use cache: "no-store". A code comment by checkDescriptor records this.
• Route failover: already present. Silent routes are deferred behind ones that answer, and fix(client-runtime): connections stay put and offline machines stop saying reconnecting #191's "strictly better" upgrade rule is unchanged.
• fix(client-runtime): restore fork connection fixes lost in upstream syncs #192's send-stalled theory: 0 send-stalled on both hosts, so I left wsClientLiveness.ts alone for fix(client-runtime): restore fork connection fixes lost in upstream syncs #192 to own. This PR doesn't touch fix(client-runtime): ride out packet-loss bursts on mobile tailnet connections #106's probe/ping timeouts or fix(client-runtime): a dropped session request no longer locks the composer #150's session retry.

Diagnostics

• client-runtime keeps a per-environment log of the last 50 transitions (attempt / connected / failed / lost / waiting), each with route, stage, reason, detail (≤160 chars), network, and fg/bg.
• Settings → Environments → → Connection log shows the newest 10 and copies all 50.
• Mobile activity reports carry up to 10 new failed/lost events (connectionTrouble, optional, schema-capped). The server logs them as client reported connection trouble and doesn't store them.

Surfaces

• Mobile: foreground cap, log UI, trouble reporting.
• Web/desktop: foreground cap via page visibility. Log UI is mobile only (desktop users can read devtools).
• Server: one log line. The contract change is an optional field, so old clients and servers interoperate.
• Providers: n/a.

Checks

vp run check:changed: format, lint, knip, tests, and react compiler pass. Its typecheck step can't spawn in this sandbox (seccomp SUN_LEN), so I ran tsc --noEmit directly in client-runtime, contracts, mobile, web, server, and desktop: clean. lint:mobile only runs native checks, and ktlint/swiftlint aren't installed here; no native code changed.

Shipping: JJ's iOS build has OTA disabled, so this needs a new TestFlight build.

Opus 5.5 via Claude Code in T3 Code.

🤖 Generated with Claude Code