[codex] Rewrite client connection architecture

[juliusmarminge]

Summary

Replace the independent web and mobile connection implementations with a shared Effect-based client runtime.

• introduce environment descriptors, connection drivers, resolution, supervision, authorization, relay discovery, RPC sessions, and lifecycle ownership in @t3tools/client-runtime
• move runtime state to explicit environment-scoped modules for auth, connections, projects, threads, shell, terminal, filesystem, source control, review, and presentation
• migrate web, desktop, and mobile integrations to explicit client-runtime subpath exports
• add persisted connection catalogs for web, mobile, and desktop, including encrypted desktop storage and mobile legacy migration
• centralize retry/backoff, connectivity wakeups, credential refresh, account-transition cleanup, session ownership, subscription recovery, and mobile outbox draining
• preserve scoped relay tracing across the rewritten runtime and release configuration
• harden local relay startup and agent-activity credential reconciliation

Scope

The native mobile composer, markdown renderer, Clerk sheet routing, turn-fold presentation, and Pierre icons were reviewed separately in #3101 and are now part of main. This PR contains the client connection/runtime rearchitecture on top of that merged base.

Validation

• node scripts/release-smoke.ts
• vp check
• vp run typecheck
• vp run lint:mobile
• 96 changed test files passed, covering 741 tests including every changed backend test

---

Note

High Risk
Touches encrypted credential persistence, legacy migrations, and breaking desktop IPC channels while reshaping mobile connection lifecycle and cloud account transitions—errors in migration or catalog reads can strand users' environments.

Overview
Desktop drops the saved-environment registry IPC surface in favor of get / set / clear connection catalog handlers backed by a new DesktopConnectionCatalogStore: Electron safe-storage encryption, atomic writes, one-time migration from legacy relay/SSH/bearer records, and read errors for corrupt or undecryptable catalogs instead of silent empty state. DesktopSavedEnvironments now propagates ReadError for malformed registry JSON (used only for migration). Minor fixes: cloud auth header typing, SSH imports split to client-runtime subpaths.

Mobile adds a full connection stack (connectionPlatformLayer, secure catalog + legacy migration, shell/thread snapshot caches, pairing onboarding commands, environmentCatalog atoms) and rewires the app to useWorkspaceState, useConnectionController, and useAtomCommand for environments, pairing, settings, and favicons via useAssetUrl. Cloud settings/environments UI gains status dots, switches, trace IDs, and serialized account cleanup on Clerk sign-in/out (activateCloudRelayAccount / deactivateCloudRelayAccount). Agent-awareness relay device registration is queued and coalesced; settings/async flows use settleAsyncResult. Adds expo-network, iOS modular CocoaPods for App Check deps, and EAS push prompt tweak.

CI removes the dedicated Playwright browser test job from ci.yml.

^{Reviewed by Cursor Bugbot for commit 1551f69. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace client connection architecture with atom-based environment-scoped state

• Introduces a layered connection subsystem (ConnectionRegistry, ConnectionDriver, ConnectionResolver, EnvironmentSupervisor) that manages environment lifecycle with retry/backoff, network awareness, and tracing, replacing the previous WebSocket RPC client approach.
• Replaces Zustand stores and React Query throughout web and mobile with atom families scoped per environment (shell state, thread detail, VCS, terminal, preview, server config, assets, auth).
• Introduces a typed ConnectionCatalogDocument (targets, profiles, credentials) backed by IndexedDB on web, secure storage on mobile, and encrypted desktop storage, replacing the legacy saved environment registry and secrets APIs.
• Adds a mobile thread outbox with durable per-message JSON persistence and an automatic drain hook (useThreadOutboxDrain) that retries on transient failures.
• @t3tools/client-runtime now requires explicit subpath imports (e.g. @t3tools/client-runtime/state/shell); the root export is removed and a lint rule enforces subpath usage.
• Desktop IPC channels switch from saved-environment registry/secret methods to getConnectionCatalog, setConnectionCatalog, and clearConnectionCatalog.
• Risk: Breaking change — any code importing from the @t3tools/client-runtime root or calling removed APIs (syncProjects, syncThreads, connectSavedEnvironment, useRemoteEnvironmentBootstrap, etc.) will fail at compile or runtime.

^{Macroscope summarized 1551f69.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 95e29028-8ce5-4832-9923-acff2a69a2d3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/connection-state-audit

---

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

[github-actions]

🚀 Expo continuous deployment is ready!

• Project → t3-code
• Platforms → android, ios
• Scheme → t3code-preview

	🤖 Android	🍎 iOS
Fingerprint	b0da31fdd85a1becc2a86a825c791b045a5afa58	eb056ff68ca484dcf1b32e25342b2824e89824cc
Build Details	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 App version: 0.1.0 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc App version: 0.1.0 Git commit: 5c744a980761a8e18b4c7a78c1b3bd7ed0e9e6c7
Update Details	Update Permalink Details Branch: pr-2978 Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Update Permalink Details Branch: pr-2978 Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae
Update QR

[macroscopeapp]

🟡 Mediumconnection/webConnectionStorage.ts:87

When indexedDB.open() needs to upgrade the schema but another tab holds an older version, the blocked event fires and the Effect never completes — neither success nor error handlers execute until the blocking tab closes. If that tab never closes, openDatabase hangs indefinitely. Consider handling the blocked event by resuming with a descriptive error or triggering a retry with timeout.

+ request.addEventListener("blocked", () => {+ resume(Effect.fail(catalogError("open", "Database upgrade blocked by another tab")));+ });

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/connection/webConnectionStorage.ts around lines 87-113:
When `indexedDB.open()` needs to upgrade the schema but another tab holds an older version, the `blocked` event fires and the Effect never completes — neither `success` nor `error` handlers execute until the blocking tab closes. If that tab never closes, `openDatabase` hangs indefinitely. Consider handling the `blocked` event by resuming with a descriptive error or triggering a retry with timeout.
Evidence trail:
apps/web/src/connection/webConnectionStorage.ts lines 87-114 at REVIEWED_COMMIT: `openDatabase` registers handlers for `upgradeneeded` (line 96), `error` (line 107), and `success` (line 110), but not for `blocked`. IndexedDB spec: https://w3c.github.io/IndexedDB/#request-api — the `blocked` event fires on IDBOpenDBRequest when the open operation is blocked by existing connections, and `success`/`error` don't fire until the block is resolved.

[macroscopeapp]

🟡 Mediumcloud/managedAuth.tsx:59

On first render when signed out, previousAccount is undefined, so undefined !== null evaluates to true and queueAccountCleanup() runs unnecessarily. This triggers removeRelayEnvironments() and relay client token cache reset even though no account was ever established. Change the condition to if (previousAccount) so cleanup only happens when transitioning from an actual signed-in state.

- if (previousAccount !== null) {+ if (previousAccount) {

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/cloud/managedAuth.tsx around line 59:
On first render when signed out, `previousAccount` is `undefined`, so `undefined !== null` evaluates to `true` and `queueAccountCleanup()` runs unnecessarily. This triggers `removeRelayEnvironments()` and relay client token cache reset even though no account was ever established. Change the condition to `if (previousAccount)` so cleanup only happens when transitioning from an actual signed-in state.
Evidence trail:
apps/web/src/cloud/managedAuth.tsx lines 26, 35, 37, 57-61, 63 at REVIEWED_COMMIT. Line 26: ref initialized to `undefined`. Line 35: `previousAccount = observedAccountRef.current` (undefined on first render). Line 59: condition `previousAccount !== null` doesn't account for `undefined`. Line 63: correctly checks all three states (`!== undefined && !== null && !== userId`).

[macroscopeapp]

🟡 Mediumcomponents/ChatView.tsx:1119

The refactored code removed the guard that excluded the primary environment from unavailability checks. Now activeEnvironmentUnavailable is computed for all environments including the primary, so if the primary's connection.phase is temporarily "connecting" or "available" during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/components/ChatView.tsx around line 1119:
The refactored code removed the guard that excluded the primary environment from unavailability checks. Now `activeEnvironmentUnavailable` is computed for all environments including the primary, so if the primary's `connection.phase` is temporarily `"connecting"` or `"available"` during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.
Evidence trail:
Old guard at MERGE_BASE in ChatView.tsx: `activeThread.environmentId !== primaryEnvironmentId` check in `activeSavedEnvironmentRecord` assignment; new code at REVIEWED_COMMIT ChatView.tsx lines 1119-1123 with no primary guard; `AVAILABLE_CONNECTION_STATE` defined at packages/client-runtime/src/connection/model.ts:148-154 with `phase: "available"`; `activeEnvironmentUnavailable` used to block sends at ChatView.tsx:2806, ChatView.tsx:3427; used to block revert at ChatView.tsx:2746; used for banner at ChatView.tsx:1353; `isConnecting` always false at ChatView.tsx:904 (`_setIsConnecting` unused).

[juliusmarminge]

Summary

Replace the independent web and mobile connection implementations with a shared Effect-based client runtime.

• introduce environment descriptors, connection drivers, resolution, supervision, authorization, relay discovery, RPC sessions, and lifecycle ownership in @t3tools/client-runtime
• move runtime state to explicit environment-scoped modules for auth, connections, projects, threads, shell, terminal, filesystem, source control, review, and presentation
• migrate web, desktop, and mobile integrations to explicit client-runtime subpath exports
• add persisted connection catalogs for web, mobile, and desktop, including encrypted desktop storage and mobile legacy migration
• centralize retry/backoff, connectivity wakeups, credential refresh, account-transition cleanup, session ownership, subscription recovery, and mobile outbox draining
• preserve scoped relay tracing across the rewritten runtime and release configuration
• harden local relay startup and agent-activity credential reconciliation

Scope

The native mobile composer, markdown renderer, Clerk sheet routing, turn-fold presentation, and Pierre icons were reviewed separately in #3101 and are now part of main. This PR contains the client connection/runtime rearchitecture on top of that merged base.

Validation

• node scripts/release-smoke.ts
• vp check
• vp run typecheck
• vp run lint:mobile
• 96 changed test files passed, covering 741 tests including every changed backend test

---

Note

High Risk
Touches encrypted credential persistence, legacy migrations, and breaking desktop IPC channels while reshaping mobile connection lifecycle and cloud account transitions—errors in migration or catalog reads can strand users' environments.

Overview
Desktop drops the saved-environment registry IPC surface in favor of get / set / clear connection catalog handlers backed by a new DesktopConnectionCatalogStore: Electron safe-storage encryption, atomic writes, one-time migration from legacy relay/SSH/bearer records, and read errors for corrupt or undecryptable catalogs instead of silent empty state. DesktopSavedEnvironments now propagates ReadError for malformed registry JSON (used only for migration). Minor fixes: cloud auth header typing, SSH imports split to client-runtime subpaths.

Mobile adds a full connection stack (connectionPlatformLayer, secure catalog + legacy migration, shell/thread snapshot caches, pairing onboarding commands, environmentCatalog atoms) and rewires the app to useWorkspaceState, useConnectionController, and useAtomCommand for environments, pairing, settings, and favicons via useAssetUrl. Cloud settings/environments UI gains status dots, switches, trace IDs, and serialized account cleanup on Clerk sign-in/out (activateCloudRelayAccount / deactivateCloudRelayAccount). Agent-awareness relay device registration is queued and coalesced; settings/async flows use settleAsyncResult. Adds expo-network, iOS modular CocoaPods for App Check deps, and EAS push prompt tweak.

CI removes the dedicated Playwright browser test job from ci.yml.

^{Reviewed by Cursor Bugbot for commit 1551f69. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace client connection architecture with atom-based environment-scoped state

• Introduces a layered connection subsystem (ConnectionRegistry, ConnectionDriver, ConnectionResolver, EnvironmentSupervisor) that manages environment lifecycle with retry/backoff, network awareness, and tracing, replacing the previous WebSocket RPC client approach.
• Replaces Zustand stores and React Query throughout web and mobile with atom families scoped per environment (shell state, thread detail, VCS, terminal, preview, server config, assets, auth).
• Introduces a typed ConnectionCatalogDocument (targets, profiles, credentials) backed by IndexedDB on web, secure storage on mobile, and encrypted desktop storage, replacing the legacy saved environment registry and secrets APIs.
• Adds a mobile thread outbox with durable per-message JSON persistence and an automatic drain hook (useThreadOutboxDrain) that retries on transient failures.
• @t3tools/client-runtime now requires explicit subpath imports (e.g. @t3tools/client-runtime/state/shell); the root export is removed and a lint rule enforces subpath usage.
• Desktop IPC channels switch from saved-environment registry/secret methods to getConnectionCatalog, setConnectionCatalog, and clearConnectionCatalog.
• Risk: Breaking change — any code importing from the @t3tools/client-runtime root or calling removed APIs (syncProjects, syncThreads, connectSavedEnvironment, useRemoteEnvironmentBootstrap, etc.) will fail at compile or runtime.

^{Macroscope summarized 1551f69.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 95e29028-8ce5-4832-9923-acff2a69a2d3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/connection-state-audit

---

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

[github-actions]

🚀 Expo continuous deployment is ready!

• Project → t3-code
• Platforms → android, ios
• Scheme → t3code-preview

	🤖 Android	🍎 iOS
Fingerprint	b0da31fdd85a1becc2a86a825c791b045a5afa58	eb056ff68ca484dcf1b32e25342b2824e89824cc
Build Details	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 App version: 0.1.0 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc App version: 0.1.0 Git commit: 5c744a980761a8e18b4c7a78c1b3bd7ed0e9e6c7
Update Details	Update Permalink Details Branch: pr-2978 Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Update Permalink Details Branch: pr-2978 Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae
Update QR

[macroscopeapp]

🟡 Mediumconnection/webConnectionStorage.ts:87

When indexedDB.open() needs to upgrade the schema but another tab holds an older version, the blocked event fires and the Effect never completes — neither success nor error handlers execute until the blocking tab closes. If that tab never closes, openDatabase hangs indefinitely. Consider handling the blocked event by resuming with a descriptive error or triggering a retry with timeout.

+ request.addEventListener("blocked", () => {+ resume(Effect.fail(catalogError("open", "Database upgrade blocked by another tab")));+ });

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/connection/webConnectionStorage.ts around lines 87-113:
When `indexedDB.open()` needs to upgrade the schema but another tab holds an older version, the `blocked` event fires and the Effect never completes — neither `success` nor `error` handlers execute until the blocking tab closes. If that tab never closes, `openDatabase` hangs indefinitely. Consider handling the `blocked` event by resuming with a descriptive error or triggering a retry with timeout.
Evidence trail:
apps/web/src/connection/webConnectionStorage.ts lines 87-114 at REVIEWED_COMMIT: `openDatabase` registers handlers for `upgradeneeded` (line 96), `error` (line 107), and `success` (line 110), but not for `blocked`. IndexedDB spec: https://w3c.github.io/IndexedDB/#request-api — the `blocked` event fires on IDBOpenDBRequest when the open operation is blocked by existing connections, and `success`/`error` don't fire until the block is resolved.

[macroscopeapp]

🟡 Mediumcloud/managedAuth.tsx:59

On first render when signed out, previousAccount is undefined, so undefined !== null evaluates to true and queueAccountCleanup() runs unnecessarily. This triggers removeRelayEnvironments() and relay client token cache reset even though no account was ever established. Change the condition to if (previousAccount) so cleanup only happens when transitioning from an actual signed-in state.

- if (previousAccount !== null) {+ if (previousAccount) {

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/cloud/managedAuth.tsx around line 59:
On first render when signed out, `previousAccount` is `undefined`, so `undefined !== null` evaluates to `true` and `queueAccountCleanup()` runs unnecessarily. This triggers `removeRelayEnvironments()` and relay client token cache reset even though no account was ever established. Change the condition to `if (previousAccount)` so cleanup only happens when transitioning from an actual signed-in state.
Evidence trail:
apps/web/src/cloud/managedAuth.tsx lines 26, 35, 37, 57-61, 63 at REVIEWED_COMMIT. Line 26: ref initialized to `undefined`. Line 35: `previousAccount = observedAccountRef.current` (undefined on first render). Line 59: condition `previousAccount !== null` doesn't account for `undefined`. Line 63: correctly checks all three states (`!== undefined && !== null && !== userId`).

[macroscopeapp]

🟡 Mediumcomponents/ChatView.tsx:1119

The refactored code removed the guard that excluded the primary environment from unavailability checks. Now activeEnvironmentUnavailable is computed for all environments including the primary, so if the primary's connection.phase is temporarily "connecting" or "available" during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/components/ChatView.tsx around line 1119:
The refactored code removed the guard that excluded the primary environment from unavailability checks. Now `activeEnvironmentUnavailable` is computed for all environments including the primary, so if the primary's `connection.phase` is temporarily `"connecting"` or `"available"` during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.
Evidence trail:
Old guard at MERGE_BASE in ChatView.tsx: `activeThread.environmentId !== primaryEnvironmentId` check in `activeSavedEnvironmentRecord` assignment; new code at REVIEWED_COMMIT ChatView.tsx lines 1119-1123 with no primary guard; `AVAILABLE_CONNECTION_STATE` defined at packages/client-runtime/src/connection/model.ts:148-154 with `phase: "available"`; `activeEnvironmentUnavailable` used to block sends at ChatView.tsx:2806, ChatView.tsx:3427; used to block revert at ChatView.tsx:2746; used for banner at ChatView.tsx:1353; `isConnecting` always false at ChatView.tsx:904 (`_setIsConnecting` unused).

[juliusmarminge]

Summary

Replace the independent web and mobile connection implementations with a shared Effect-based client runtime.

• introduce environment descriptors, connection drivers, resolution, supervision, authorization, relay discovery, RPC sessions, and lifecycle ownership in @t3tools/client-runtime
• move runtime state to explicit environment-scoped modules for auth, connections, projects, threads, shell, terminal, filesystem, source control, review, and presentation
• migrate web, desktop, and mobile integrations to explicit client-runtime subpath exports
• add persisted connection catalogs for web, mobile, and desktop, including encrypted desktop storage and mobile legacy migration
• centralize retry/backoff, connectivity wakeups, credential refresh, account-transition cleanup, session ownership, subscription recovery, and mobile outbox draining
• preserve scoped relay tracing across the rewritten runtime and release configuration
• harden local relay startup and agent-activity credential reconciliation

Scope

The native mobile composer, markdown renderer, Clerk sheet routing, turn-fold presentation, and Pierre icons were reviewed separately in #3101 and are now part of main. This PR contains the client connection/runtime rearchitecture on top of that merged base.

Validation

• node scripts/release-smoke.ts
• vp check
• vp run typecheck
• vp run lint:mobile
• 96 changed test files passed, covering 741 tests including every changed backend test

---

Note

High Risk
Touches encrypted credential persistence, legacy migrations, and breaking desktop IPC channels while reshaping mobile connection lifecycle and cloud account transitions—errors in migration or catalog reads can strand users' environments.

Overview
Desktop drops the saved-environment registry IPC surface in favor of get / set / clear connection catalog handlers backed by a new DesktopConnectionCatalogStore: Electron safe-storage encryption, atomic writes, one-time migration from legacy relay/SSH/bearer records, and read errors for corrupt or undecryptable catalogs instead of silent empty state. DesktopSavedEnvironments now propagates ReadError for malformed registry JSON (used only for migration). Minor fixes: cloud auth header typing, SSH imports split to client-runtime subpaths.

Mobile adds a full connection stack (connectionPlatformLayer, secure catalog + legacy migration, shell/thread snapshot caches, pairing onboarding commands, environmentCatalog atoms) and rewires the app to useWorkspaceState, useConnectionController, and useAtomCommand for environments, pairing, settings, and favicons via useAssetUrl. Cloud settings/environments UI gains status dots, switches, trace IDs, and serialized account cleanup on Clerk sign-in/out (activateCloudRelayAccount / deactivateCloudRelayAccount). Agent-awareness relay device registration is queued and coalesced; settings/async flows use settleAsyncResult. Adds expo-network, iOS modular CocoaPods for App Check deps, and EAS push prompt tweak.

CI removes the dedicated Playwright browser test job from ci.yml.

^{Reviewed by Cursor Bugbot for commit 1551f69. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace client connection architecture with atom-based environment-scoped state

• Introduces a layered connection subsystem (ConnectionRegistry, ConnectionDriver, ConnectionResolver, EnvironmentSupervisor) that manages environment lifecycle with retry/backoff, network awareness, and tracing, replacing the previous WebSocket RPC client approach.
• Replaces Zustand stores and React Query throughout web and mobile with atom families scoped per environment (shell state, thread detail, VCS, terminal, preview, server config, assets, auth).
• Introduces a typed ConnectionCatalogDocument (targets, profiles, credentials) backed by IndexedDB on web, secure storage on mobile, and encrypted desktop storage, replacing the legacy saved environment registry and secrets APIs.
• Adds a mobile thread outbox with durable per-message JSON persistence and an automatic drain hook (useThreadOutboxDrain) that retries on transient failures.
• @t3tools/client-runtime now requires explicit subpath imports (e.g. @t3tools/client-runtime/state/shell); the root export is removed and a lint rule enforces subpath usage.
• Desktop IPC channels switch from saved-environment registry/secret methods to getConnectionCatalog, setConnectionCatalog, and clearConnectionCatalog.
• Risk: Breaking change — any code importing from the @t3tools/client-runtime root or calling removed APIs (syncProjects, syncThreads, connectSavedEnvironment, useRemoteEnvironmentBootstrap, etc.) will fail at compile or runtime.

^{Macroscope summarized 1551f69.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 95e29028-8ce5-4832-9923-acff2a69a2d3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/connection-state-audit

---

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

[github-actions]

🚀 Expo continuous deployment is ready!

• Project → t3-code
• Platforms → android, ios
• Scheme → t3code-preview

	🤖 Android	🍎 iOS
Fingerprint	b0da31fdd85a1becc2a86a825c791b045a5afa58	eb056ff68ca484dcf1b32e25342b2824e89824cc
Build Details	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 App version: 0.1.0 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc App version: 0.1.0 Git commit: 5c744a980761a8e18b4c7a78c1b3bd7ed0e9e6c7
Update Details	Update Permalink Details Branch: pr-2978 Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Update Permalink Details Branch: pr-2978 Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae
Update QR

[macroscopeapp]

🟡 Mediumconnection/webConnectionStorage.ts:87

When indexedDB.open() needs to upgrade the schema but another tab holds an older version, the blocked event fires and the Effect never completes — neither success nor error handlers execute until the blocking tab closes. If that tab never closes, openDatabase hangs indefinitely. Consider handling the blocked event by resuming with a descriptive error or triggering a retry with timeout.

+ request.addEventListener("blocked", () => {+ resume(Effect.fail(catalogError("open", "Database upgrade blocked by another tab")));+ });

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/connection/webConnectionStorage.ts around lines 87-113:
When `indexedDB.open()` needs to upgrade the schema but another tab holds an older version, the `blocked` event fires and the Effect never completes — neither `success` nor `error` handlers execute until the blocking tab closes. If that tab never closes, `openDatabase` hangs indefinitely. Consider handling the `blocked` event by resuming with a descriptive error or triggering a retry with timeout.
Evidence trail:
apps/web/src/connection/webConnectionStorage.ts lines 87-114 at REVIEWED_COMMIT: `openDatabase` registers handlers for `upgradeneeded` (line 96), `error` (line 107), and `success` (line 110), but not for `blocked`. IndexedDB spec: https://w3c.github.io/IndexedDB/#request-api — the `blocked` event fires on IDBOpenDBRequest when the open operation is blocked by existing connections, and `success`/`error` don't fire until the block is resolved.

[macroscopeapp]

🟡 Mediumcloud/managedAuth.tsx:59

On first render when signed out, previousAccount is undefined, so undefined !== null evaluates to true and queueAccountCleanup() runs unnecessarily. This triggers removeRelayEnvironments() and relay client token cache reset even though no account was ever established. Change the condition to if (previousAccount) so cleanup only happens when transitioning from an actual signed-in state.

- if (previousAccount !== null) {+ if (previousAccount) {

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/cloud/managedAuth.tsx around line 59:
On first render when signed out, `previousAccount` is `undefined`, so `undefined !== null` evaluates to `true` and `queueAccountCleanup()` runs unnecessarily. This triggers `removeRelayEnvironments()` and relay client token cache reset even though no account was ever established. Change the condition to `if (previousAccount)` so cleanup only happens when transitioning from an actual signed-in state.
Evidence trail:
apps/web/src/cloud/managedAuth.tsx lines 26, 35, 37, 57-61, 63 at REVIEWED_COMMIT. Line 26: ref initialized to `undefined`. Line 35: `previousAccount = observedAccountRef.current` (undefined on first render). Line 59: condition `previousAccount !== null` doesn't account for `undefined`. Line 63: correctly checks all three states (`!== undefined && !== null && !== userId`).

[macroscopeapp]

🟡 Mediumcomponents/ChatView.tsx:1119

The refactored code removed the guard that excluded the primary environment from unavailability checks. Now activeEnvironmentUnavailable is computed for all environments including the primary, so if the primary's connection.phase is temporarily "connecting" or "available" during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/components/ChatView.tsx around line 1119:
The refactored code removed the guard that excluded the primary environment from unavailability checks. Now `activeEnvironmentUnavailable` is computed for all environments including the primary, so if the primary's `connection.phase` is temporarily `"connecting"` or `"available"` during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.
Evidence trail:
Old guard at MERGE_BASE in ChatView.tsx: `activeThread.environmentId !== primaryEnvironmentId` check in `activeSavedEnvironmentRecord` assignment; new code at REVIEWED_COMMIT ChatView.tsx lines 1119-1123 with no primary guard; `AVAILABLE_CONNECTION_STATE` defined at packages/client-runtime/src/connection/model.ts:148-154 with `phase: "available"`; `activeEnvironmentUnavailable` used to block sends at ChatView.tsx:2806, ChatView.tsx:3427; used to block revert at ChatView.tsx:2746; used for banner at ChatView.tsx:1353; `isConnecting` always false at ChatView.tsx:904 (`_setIsConnecting` unused).

[juliusmarminge]

Summary

Replace the independent web and mobile connection implementations with a shared Effect-based client runtime.

• introduce environment descriptors, connection drivers, resolution, supervision, authorization, relay discovery, RPC sessions, and lifecycle ownership in @t3tools/client-runtime
• move runtime state to explicit environment-scoped modules for auth, connections, projects, threads, shell, terminal, filesystem, source control, review, and presentation
• migrate web, desktop, and mobile integrations to explicit client-runtime subpath exports
• add persisted connection catalogs for web, mobile, and desktop, including encrypted desktop storage and mobile legacy migration
• centralize retry/backoff, connectivity wakeups, credential refresh, account-transition cleanup, session ownership, subscription recovery, and mobile outbox draining
• preserve scoped relay tracing across the rewritten runtime and release configuration
• harden local relay startup and agent-activity credential reconciliation

Scope

The native mobile composer, markdown renderer, Clerk sheet routing, turn-fold presentation, and Pierre icons were reviewed separately in #3101 and are now part of main. This PR contains the client connection/runtime rearchitecture on top of that merged base.

Validation

• node scripts/release-smoke.ts
• vp check
• vp run typecheck
• vp run lint:mobile
• 96 changed test files passed, covering 741 tests including every changed backend test

---

Note

High Risk
Touches encrypted credential persistence, legacy migrations, and breaking desktop IPC channels while reshaping mobile connection lifecycle and cloud account transitions—errors in migration or catalog reads can strand users' environments.

Overview
Desktop drops the saved-environment registry IPC surface in favor of get / set / clear connection catalog handlers backed by a new DesktopConnectionCatalogStore: Electron safe-storage encryption, atomic writes, one-time migration from legacy relay/SSH/bearer records, and read errors for corrupt or undecryptable catalogs instead of silent empty state. DesktopSavedEnvironments now propagates ReadError for malformed registry JSON (used only for migration). Minor fixes: cloud auth header typing, SSH imports split to client-runtime subpaths.

Mobile adds a full connection stack (connectionPlatformLayer, secure catalog + legacy migration, shell/thread snapshot caches, pairing onboarding commands, environmentCatalog atoms) and rewires the app to useWorkspaceState, useConnectionController, and useAtomCommand for environments, pairing, settings, and favicons via useAssetUrl. Cloud settings/environments UI gains status dots, switches, trace IDs, and serialized account cleanup on Clerk sign-in/out (activateCloudRelayAccount / deactivateCloudRelayAccount). Agent-awareness relay device registration is queued and coalesced; settings/async flows use settleAsyncResult. Adds expo-network, iOS modular CocoaPods for App Check deps, and EAS push prompt tweak.

CI removes the dedicated Playwright browser test job from ci.yml.

^{Reviewed by Cursor Bugbot for commit 1551f69. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace client connection architecture with atom-based environment-scoped state

• Introduces a layered connection subsystem (ConnectionRegistry, ConnectionDriver, ConnectionResolver, EnvironmentSupervisor) that manages environment lifecycle with retry/backoff, network awareness, and tracing, replacing the previous WebSocket RPC client approach.
• Replaces Zustand stores and React Query throughout web and mobile with atom families scoped per environment (shell state, thread detail, VCS, terminal, preview, server config, assets, auth).
• Introduces a typed ConnectionCatalogDocument (targets, profiles, credentials) backed by IndexedDB on web, secure storage on mobile, and encrypted desktop storage, replacing the legacy saved environment registry and secrets APIs.
• Adds a mobile thread outbox with durable per-message JSON persistence and an automatic drain hook (useThreadOutboxDrain) that retries on transient failures.
• @t3tools/client-runtime now requires explicit subpath imports (e.g. @t3tools/client-runtime/state/shell); the root export is removed and a lint rule enforces subpath usage.
• Desktop IPC channels switch from saved-environment registry/secret methods to getConnectionCatalog, setConnectionCatalog, and clearConnectionCatalog.
• Risk: Breaking change — any code importing from the @t3tools/client-runtime root or calling removed APIs (syncProjects, syncThreads, connectSavedEnvironment, useRemoteEnvironmentBootstrap, etc.) will fail at compile or runtime.

^{Macroscope summarized 1551f69.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 95e29028-8ce5-4832-9923-acff2a69a2d3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/connection-state-audit

---

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

[github-actions]

🚀 Expo continuous deployment is ready!

• Project → t3-code
• Platforms → android, ios
• Scheme → t3code-preview

	🤖 Android	🍎 iOS
Fingerprint	b0da31fdd85a1becc2a86a825c791b045a5afa58	eb056ff68ca484dcf1b32e25342b2824e89824cc
Build Details	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 App version: 0.1.0 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc App version: 0.1.0 Git commit: 5c744a980761a8e18b4c7a78c1b3bd7ed0e9e6c7
Update Details	Update Permalink Details Branch: pr-2978 Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Update Permalink Details Branch: pr-2978 Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae
Update QR

[macroscopeapp]

🟡 Mediumconnection/webConnectionStorage.ts:87

When indexedDB.open() needs to upgrade the schema but another tab holds an older version, the blocked event fires and the Effect never completes — neither success nor error handlers execute until the blocking tab closes. If that tab never closes, openDatabase hangs indefinitely. Consider handling the blocked event by resuming with a descriptive error or triggering a retry with timeout.

+ request.addEventListener("blocked", () => {+ resume(Effect.fail(catalogError("open", "Database upgrade blocked by another tab")));+ });

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/connection/webConnectionStorage.ts around lines 87-113:
When `indexedDB.open()` needs to upgrade the schema but another tab holds an older version, the `blocked` event fires and the Effect never completes — neither `success` nor `error` handlers execute until the blocking tab closes. If that tab never closes, `openDatabase` hangs indefinitely. Consider handling the `blocked` event by resuming with a descriptive error or triggering a retry with timeout.
Evidence trail:
apps/web/src/connection/webConnectionStorage.ts lines 87-114 at REVIEWED_COMMIT: `openDatabase` registers handlers for `upgradeneeded` (line 96), `error` (line 107), and `success` (line 110), but not for `blocked`. IndexedDB spec: https://w3c.github.io/IndexedDB/#request-api — the `blocked` event fires on IDBOpenDBRequest when the open operation is blocked by existing connections, and `success`/`error` don't fire until the block is resolved.

[macroscopeapp]

🟡 Mediumcloud/managedAuth.tsx:59

On first render when signed out, previousAccount is undefined, so undefined !== null evaluates to true and queueAccountCleanup() runs unnecessarily. This triggers removeRelayEnvironments() and relay client token cache reset even though no account was ever established. Change the condition to if (previousAccount) so cleanup only happens when transitioning from an actual signed-in state.

- if (previousAccount !== null) {+ if (previousAccount) {

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/cloud/managedAuth.tsx around line 59:
On first render when signed out, `previousAccount` is `undefined`, so `undefined !== null` evaluates to `true` and `queueAccountCleanup()` runs unnecessarily. This triggers `removeRelayEnvironments()` and relay client token cache reset even though no account was ever established. Change the condition to `if (previousAccount)` so cleanup only happens when transitioning from an actual signed-in state.
Evidence trail:
apps/web/src/cloud/managedAuth.tsx lines 26, 35, 37, 57-61, 63 at REVIEWED_COMMIT. Line 26: ref initialized to `undefined`. Line 35: `previousAccount = observedAccountRef.current` (undefined on first render). Line 59: condition `previousAccount !== null` doesn't account for `undefined`. Line 63: correctly checks all three states (`!== undefined && !== null && !== userId`).

[macroscopeapp]

🟡 Mediumcomponents/ChatView.tsx:1119

The refactored code removed the guard that excluded the primary environment from unavailability checks. Now activeEnvironmentUnavailable is computed for all environments including the primary, so if the primary's connection.phase is temporarily "connecting" or "available" during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/components/ChatView.tsx around line 1119:
The refactored code removed the guard that excluded the primary environment from unavailability checks. Now `activeEnvironmentUnavailable` is computed for all environments including the primary, so if the primary's `connection.phase` is temporarily `"connecting"` or `"available"` during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.
Evidence trail:
Old guard at MERGE_BASE in ChatView.tsx: `activeThread.environmentId !== primaryEnvironmentId` check in `activeSavedEnvironmentRecord` assignment; new code at REVIEWED_COMMIT ChatView.tsx lines 1119-1123 with no primary guard; `AVAILABLE_CONNECTION_STATE` defined at packages/client-runtime/src/connection/model.ts:148-154 with `phase: "available"`; `activeEnvironmentUnavailable` used to block sends at ChatView.tsx:2806, ChatView.tsx:3427; used to block revert at ChatView.tsx:2746; used for banner at ChatView.tsx:1353; `isConnecting` always false at ChatView.tsx:904 (`_setIsConnecting` unused).

[juliusmarminge]

Summary

Replace the independent web and mobile connection implementations with a shared Effect-based client runtime.

• introduce environment descriptors, connection drivers, resolution, supervision, authorization, relay discovery, RPC sessions, and lifecycle ownership in @t3tools/client-runtime
• move runtime state to explicit environment-scoped modules for auth, connections, projects, threads, shell, terminal, filesystem, source control, review, and presentation
• migrate web, desktop, and mobile integrations to explicit client-runtime subpath exports
• add persisted connection catalogs for web, mobile, and desktop, including encrypted desktop storage and mobile legacy migration
• centralize retry/backoff, connectivity wakeups, credential refresh, account-transition cleanup, session ownership, subscription recovery, and mobile outbox draining
• preserve scoped relay tracing across the rewritten runtime and release configuration
• harden local relay startup and agent-activity credential reconciliation

Scope

The native mobile composer, markdown renderer, Clerk sheet routing, turn-fold presentation, and Pierre icons were reviewed separately in #3101 and are now part of main. This PR contains the client connection/runtime rearchitecture on top of that merged base.

Validation

• node scripts/release-smoke.ts
• vp check
• vp run typecheck
• vp run lint:mobile
• 96 changed test files passed, covering 741 tests including every changed backend test

---

Note

High Risk
Touches encrypted credential persistence, legacy migrations, and breaking desktop IPC channels while reshaping mobile connection lifecycle and cloud account transitions—errors in migration or catalog reads can strand users' environments.

Overview
Desktop drops the saved-environment registry IPC surface in favor of get / set / clear connection catalog handlers backed by a new DesktopConnectionCatalogStore: Electron safe-storage encryption, atomic writes, one-time migration from legacy relay/SSH/bearer records, and read errors for corrupt or undecryptable catalogs instead of silent empty state. DesktopSavedEnvironments now propagates ReadError for malformed registry JSON (used only for migration). Minor fixes: cloud auth header typing, SSH imports split to client-runtime subpaths.

Mobile adds a full connection stack (connectionPlatformLayer, secure catalog + legacy migration, shell/thread snapshot caches, pairing onboarding commands, environmentCatalog atoms) and rewires the app to useWorkspaceState, useConnectionController, and useAtomCommand for environments, pairing, settings, and favicons via useAssetUrl. Cloud settings/environments UI gains status dots, switches, trace IDs, and serialized account cleanup on Clerk sign-in/out (activateCloudRelayAccount / deactivateCloudRelayAccount). Agent-awareness relay device registration is queued and coalesced; settings/async flows use settleAsyncResult. Adds expo-network, iOS modular CocoaPods for App Check deps, and EAS push prompt tweak.

CI removes the dedicated Playwright browser test job from ci.yml.

^{Reviewed by Cursor Bugbot for commit 1551f69. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace client connection architecture with atom-based environment-scoped state

• Introduces a layered connection subsystem (ConnectionRegistry, ConnectionDriver, ConnectionResolver, EnvironmentSupervisor) that manages environment lifecycle with retry/backoff, network awareness, and tracing, replacing the previous WebSocket RPC client approach.
• Replaces Zustand stores and React Query throughout web and mobile with atom families scoped per environment (shell state, thread detail, VCS, terminal, preview, server config, assets, auth).
• Introduces a typed ConnectionCatalogDocument (targets, profiles, credentials) backed by IndexedDB on web, secure storage on mobile, and encrypted desktop storage, replacing the legacy saved environment registry and secrets APIs.
• Adds a mobile thread outbox with durable per-message JSON persistence and an automatic drain hook (useThreadOutboxDrain) that retries on transient failures.
• @t3tools/client-runtime now requires explicit subpath imports (e.g. @t3tools/client-runtime/state/shell); the root export is removed and a lint rule enforces subpath usage.
• Desktop IPC channels switch from saved-environment registry/secret methods to getConnectionCatalog, setConnectionCatalog, and clearConnectionCatalog.
• Risk: Breaking change — any code importing from the @t3tools/client-runtime root or calling removed APIs (syncProjects, syncThreads, connectSavedEnvironment, useRemoteEnvironmentBootstrap, etc.) will fail at compile or runtime.

^{Macroscope summarized 1551f69.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 95e29028-8ce5-4832-9923-acff2a69a2d3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/connection-state-audit

---

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

[github-actions]

🚀 Expo continuous deployment is ready!

• Project → t3-code
• Platforms → android, ios
• Scheme → t3code-preview

	🤖 Android	🍎 iOS
Fingerprint	b0da31fdd85a1becc2a86a825c791b045a5afa58	eb056ff68ca484dcf1b32e25342b2824e89824cc
Build Details	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 App version: 0.1.0 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc App version: 0.1.0 Git commit: 5c744a980761a8e18b4c7a78c1b3bd7ed0e9e6c7
Update Details	Update Permalink Details Branch: pr-2978 Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Update Permalink Details Branch: pr-2978 Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae
Update QR

[macroscopeapp]

🟡 Mediumconnection/webConnectionStorage.ts:87

When indexedDB.open() needs to upgrade the schema but another tab holds an older version, the blocked event fires and the Effect never completes — neither success nor error handlers execute until the blocking tab closes. If that tab never closes, openDatabase hangs indefinitely. Consider handling the blocked event by resuming with a descriptive error or triggering a retry with timeout.

+ request.addEventListener("blocked", () => {+ resume(Effect.fail(catalogError("open", "Database upgrade blocked by another tab")));+ });

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/connection/webConnectionStorage.ts around lines 87-113:
When `indexedDB.open()` needs to upgrade the schema but another tab holds an older version, the `blocked` event fires and the Effect never completes — neither `success` nor `error` handlers execute until the blocking tab closes. If that tab never closes, `openDatabase` hangs indefinitely. Consider handling the `blocked` event by resuming with a descriptive error or triggering a retry with timeout.
Evidence trail:
apps/web/src/connection/webConnectionStorage.ts lines 87-114 at REVIEWED_COMMIT: `openDatabase` registers handlers for `upgradeneeded` (line 96), `error` (line 107), and `success` (line 110), but not for `blocked`. IndexedDB spec: https://w3c.github.io/IndexedDB/#request-api — the `blocked` event fires on IDBOpenDBRequest when the open operation is blocked by existing connections, and `success`/`error` don't fire until the block is resolved.

[macroscopeapp]

🟡 Mediumcloud/managedAuth.tsx:59

On first render when signed out, previousAccount is undefined, so undefined !== null evaluates to true and queueAccountCleanup() runs unnecessarily. This triggers removeRelayEnvironments() and relay client token cache reset even though no account was ever established. Change the condition to if (previousAccount) so cleanup only happens when transitioning from an actual signed-in state.

- if (previousAccount !== null) {+ if (previousAccount) {

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/cloud/managedAuth.tsx around line 59:
On first render when signed out, `previousAccount` is `undefined`, so `undefined !== null` evaluates to `true` and `queueAccountCleanup()` runs unnecessarily. This triggers `removeRelayEnvironments()` and relay client token cache reset even though no account was ever established. Change the condition to `if (previousAccount)` so cleanup only happens when transitioning from an actual signed-in state.
Evidence trail:
apps/web/src/cloud/managedAuth.tsx lines 26, 35, 37, 57-61, 63 at REVIEWED_COMMIT. Line 26: ref initialized to `undefined`. Line 35: `previousAccount = observedAccountRef.current` (undefined on first render). Line 59: condition `previousAccount !== null` doesn't account for `undefined`. Line 63: correctly checks all three states (`!== undefined && !== null && !== userId`).

[macroscopeapp]

🟡 Mediumcomponents/ChatView.tsx:1119

The refactored code removed the guard that excluded the primary environment from unavailability checks. Now activeEnvironmentUnavailable is computed for all environments including the primary, so if the primary's connection.phase is temporarily "connecting" or "available" during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/components/ChatView.tsx around line 1119:
The refactored code removed the guard that excluded the primary environment from unavailability checks. Now `activeEnvironmentUnavailable` is computed for all environments including the primary, so if the primary's `connection.phase` is temporarily `"connecting"` or `"available"` during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.
Evidence trail:
Old guard at MERGE_BASE in ChatView.tsx: `activeThread.environmentId !== primaryEnvironmentId` check in `activeSavedEnvironmentRecord` assignment; new code at REVIEWED_COMMIT ChatView.tsx lines 1119-1123 with no primary guard; `AVAILABLE_CONNECTION_STATE` defined at packages/client-runtime/src/connection/model.ts:148-154 with `phase: "available"`; `activeEnvironmentUnavailable` used to block sends at ChatView.tsx:2806, ChatView.tsx:3427; used to block revert at ChatView.tsx:2746; used for banner at ChatView.tsx:1353; `isConnecting` always false at ChatView.tsx:904 (`_setIsConnecting` unused).

[juliusmarminge]

Summary

Replace the independent web and mobile connection implementations with a shared Effect-based client runtime.

• introduce environment descriptors, connection drivers, resolution, supervision, authorization, relay discovery, RPC sessions, and lifecycle ownership in @t3tools/client-runtime
• move runtime state to explicit environment-scoped modules for auth, connections, projects, threads, shell, terminal, filesystem, source control, review, and presentation
• migrate web, desktop, and mobile integrations to explicit client-runtime subpath exports
• add persisted connection catalogs for web, mobile, and desktop, including encrypted desktop storage and mobile legacy migration
• centralize retry/backoff, connectivity wakeups, credential refresh, account-transition cleanup, session ownership, subscription recovery, and mobile outbox draining
• preserve scoped relay tracing across the rewritten runtime and release configuration
• harden local relay startup and agent-activity credential reconciliation

Scope

The native mobile composer, markdown renderer, Clerk sheet routing, turn-fold presentation, and Pierre icons were reviewed separately in #3101 and are now part of main. This PR contains the client connection/runtime rearchitecture on top of that merged base.

Validation

• node scripts/release-smoke.ts
• vp check
• vp run typecheck
• vp run lint:mobile
• 96 changed test files passed, covering 741 tests including every changed backend test

---

Note

High Risk
Touches encrypted credential persistence, legacy migrations, and breaking desktop IPC channels while reshaping mobile connection lifecycle and cloud account transitions—errors in migration or catalog reads can strand users' environments.

Overview
Desktop drops the saved-environment registry IPC surface in favor of get / set / clear connection catalog handlers backed by a new DesktopConnectionCatalogStore: Electron safe-storage encryption, atomic writes, one-time migration from legacy relay/SSH/bearer records, and read errors for corrupt or undecryptable catalogs instead of silent empty state. DesktopSavedEnvironments now propagates ReadError for malformed registry JSON (used only for migration). Minor fixes: cloud auth header typing, SSH imports split to client-runtime subpaths.

Mobile adds a full connection stack (connectionPlatformLayer, secure catalog + legacy migration, shell/thread snapshot caches, pairing onboarding commands, environmentCatalog atoms) and rewires the app to useWorkspaceState, useConnectionController, and useAtomCommand for environments, pairing, settings, and favicons via useAssetUrl. Cloud settings/environments UI gains status dots, switches, trace IDs, and serialized account cleanup on Clerk sign-in/out (activateCloudRelayAccount / deactivateCloudRelayAccount). Agent-awareness relay device registration is queued and coalesced; settings/async flows use settleAsyncResult. Adds expo-network, iOS modular CocoaPods for App Check deps, and EAS push prompt tweak.

CI removes the dedicated Playwright browser test job from ci.yml.

^{Reviewed by Cursor Bugbot for commit 1551f69. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace client connection architecture with atom-based environment-scoped state

• Introduces a layered connection subsystem (ConnectionRegistry, ConnectionDriver, ConnectionResolver, EnvironmentSupervisor) that manages environment lifecycle with retry/backoff, network awareness, and tracing, replacing the previous WebSocket RPC client approach.
• Replaces Zustand stores and React Query throughout web and mobile with atom families scoped per environment (shell state, thread detail, VCS, terminal, preview, server config, assets, auth).
• Introduces a typed ConnectionCatalogDocument (targets, profiles, credentials) backed by IndexedDB on web, secure storage on mobile, and encrypted desktop storage, replacing the legacy saved environment registry and secrets APIs.
• Adds a mobile thread outbox with durable per-message JSON persistence and an automatic drain hook (useThreadOutboxDrain) that retries on transient failures.
• @t3tools/client-runtime now requires explicit subpath imports (e.g. @t3tools/client-runtime/state/shell); the root export is removed and a lint rule enforces subpath usage.
• Desktop IPC channels switch from saved-environment registry/secret methods to getConnectionCatalog, setConnectionCatalog, and clearConnectionCatalog.
• Risk: Breaking change — any code importing from the @t3tools/client-runtime root or calling removed APIs (syncProjects, syncThreads, connectSavedEnvironment, useRemoteEnvironmentBootstrap, etc.) will fail at compile or runtime.

^{Macroscope summarized 1551f69.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 95e29028-8ce5-4832-9923-acff2a69a2d3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/connection-state-audit

---

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

[github-actions]

🚀 Expo continuous deployment is ready!

• Project → t3-code
• Platforms → android, ios
• Scheme → t3code-preview

	🤖 Android	🍎 iOS
Fingerprint	b0da31fdd85a1becc2a86a825c791b045a5afa58	eb056ff68ca484dcf1b32e25342b2824e89824cc
Build Details	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 App version: 0.1.0 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc App version: 0.1.0 Git commit: 5c744a980761a8e18b4c7a78c1b3bd7ed0e9e6c7
Update Details	Update Permalink Details Branch: pr-2978 Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Update Permalink Details Branch: pr-2978 Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae
Update QR

[macroscopeapp]

🟡 Mediumconnection/webConnectionStorage.ts:87

When indexedDB.open() needs to upgrade the schema but another tab holds an older version, the blocked event fires and the Effect never completes — neither success nor error handlers execute until the blocking tab closes. If that tab never closes, openDatabase hangs indefinitely. Consider handling the blocked event by resuming with a descriptive error or triggering a retry with timeout.

+ request.addEventListener("blocked", () => {+ resume(Effect.fail(catalogError("open", "Database upgrade blocked by another tab")));+ });

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/connection/webConnectionStorage.ts around lines 87-113:
When `indexedDB.open()` needs to upgrade the schema but another tab holds an older version, the `blocked` event fires and the Effect never completes — neither `success` nor `error` handlers execute until the blocking tab closes. If that tab never closes, `openDatabase` hangs indefinitely. Consider handling the `blocked` event by resuming with a descriptive error or triggering a retry with timeout.
Evidence trail:
apps/web/src/connection/webConnectionStorage.ts lines 87-114 at REVIEWED_COMMIT: `openDatabase` registers handlers for `upgradeneeded` (line 96), `error` (line 107), and `success` (line 110), but not for `blocked`. IndexedDB spec: https://w3c.github.io/IndexedDB/#request-api — the `blocked` event fires on IDBOpenDBRequest when the open operation is blocked by existing connections, and `success`/`error` don't fire until the block is resolved.

[macroscopeapp]

🟡 Mediumcloud/managedAuth.tsx:59

On first render when signed out, previousAccount is undefined, so undefined !== null evaluates to true and queueAccountCleanup() runs unnecessarily. This triggers removeRelayEnvironments() and relay client token cache reset even though no account was ever established. Change the condition to if (previousAccount) so cleanup only happens when transitioning from an actual signed-in state.

- if (previousAccount !== null) {+ if (previousAccount) {

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/cloud/managedAuth.tsx around line 59:
On first render when signed out, `previousAccount` is `undefined`, so `undefined !== null` evaluates to `true` and `queueAccountCleanup()` runs unnecessarily. This triggers `removeRelayEnvironments()` and relay client token cache reset even though no account was ever established. Change the condition to `if (previousAccount)` so cleanup only happens when transitioning from an actual signed-in state.
Evidence trail:
apps/web/src/cloud/managedAuth.tsx lines 26, 35, 37, 57-61, 63 at REVIEWED_COMMIT. Line 26: ref initialized to `undefined`. Line 35: `previousAccount = observedAccountRef.current` (undefined on first render). Line 59: condition `previousAccount !== null` doesn't account for `undefined`. Line 63: correctly checks all three states (`!== undefined && !== null && !== userId`).

[macroscopeapp]

🟡 Mediumcomponents/ChatView.tsx:1119

The refactored code removed the guard that excluded the primary environment from unavailability checks. Now activeEnvironmentUnavailable is computed for all environments including the primary, so if the primary's connection.phase is temporarily "connecting" or "available" during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/components/ChatView.tsx around line 1119:
The refactored code removed the guard that excluded the primary environment from unavailability checks. Now `activeEnvironmentUnavailable` is computed for all environments including the primary, so if the primary's `connection.phase` is temporarily `"connecting"` or `"available"` during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.
Evidence trail:
Old guard at MERGE_BASE in ChatView.tsx: `activeThread.environmentId !== primaryEnvironmentId` check in `activeSavedEnvironmentRecord` assignment; new code at REVIEWED_COMMIT ChatView.tsx lines 1119-1123 with no primary guard; `AVAILABLE_CONNECTION_STATE` defined at packages/client-runtime/src/connection/model.ts:148-154 with `phase: "available"`; `activeEnvironmentUnavailable` used to block sends at ChatView.tsx:2806, ChatView.tsx:3427; used to block revert at ChatView.tsx:2746; used for banner at ChatView.tsx:1353; `isConnecting` always false at ChatView.tsx:904 (`_setIsConnecting` unused).

[juliusmarminge]

Summary

Replace the independent web and mobile connection implementations with a shared Effect-based client runtime.

• introduce environment descriptors, connection drivers, resolution, supervision, authorization, relay discovery, RPC sessions, and lifecycle ownership in @t3tools/client-runtime
• move runtime state to explicit environment-scoped modules for auth, connections, projects, threads, shell, terminal, filesystem, source control, review, and presentation
• migrate web, desktop, and mobile integrations to explicit client-runtime subpath exports
• add persisted connection catalogs for web, mobile, and desktop, including encrypted desktop storage and mobile legacy migration
• centralize retry/backoff, connectivity wakeups, credential refresh, account-transition cleanup, session ownership, subscription recovery, and mobile outbox draining
• preserve scoped relay tracing across the rewritten runtime and release configuration
• harden local relay startup and agent-activity credential reconciliation

Scope

The native mobile composer, markdown renderer, Clerk sheet routing, turn-fold presentation, and Pierre icons were reviewed separately in #3101 and are now part of main. This PR contains the client connection/runtime rearchitecture on top of that merged base.

Validation

• node scripts/release-smoke.ts
• vp check
• vp run typecheck
• vp run lint:mobile
• 96 changed test files passed, covering 741 tests including every changed backend test

---

Note

High Risk
Touches encrypted credential persistence, legacy migrations, and breaking desktop IPC channels while reshaping mobile connection lifecycle and cloud account transitions—errors in migration or catalog reads can strand users' environments.

Overview
Desktop drops the saved-environment registry IPC surface in favor of get / set / clear connection catalog handlers backed by a new DesktopConnectionCatalogStore: Electron safe-storage encryption, atomic writes, one-time migration from legacy relay/SSH/bearer records, and read errors for corrupt or undecryptable catalogs instead of silent empty state. DesktopSavedEnvironments now propagates ReadError for malformed registry JSON (used only for migration). Minor fixes: cloud auth header typing, SSH imports split to client-runtime subpaths.

Mobile adds a full connection stack (connectionPlatformLayer, secure catalog + legacy migration, shell/thread snapshot caches, pairing onboarding commands, environmentCatalog atoms) and rewires the app to useWorkspaceState, useConnectionController, and useAtomCommand for environments, pairing, settings, and favicons via useAssetUrl. Cloud settings/environments UI gains status dots, switches, trace IDs, and serialized account cleanup on Clerk sign-in/out (activateCloudRelayAccount / deactivateCloudRelayAccount). Agent-awareness relay device registration is queued and coalesced; settings/async flows use settleAsyncResult. Adds expo-network, iOS modular CocoaPods for App Check deps, and EAS push prompt tweak.

CI removes the dedicated Playwright browser test job from ci.yml.

^{Reviewed by Cursor Bugbot for commit 1551f69. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace client connection architecture with atom-based environment-scoped state

• Introduces a layered connection subsystem (ConnectionRegistry, ConnectionDriver, ConnectionResolver, EnvironmentSupervisor) that manages environment lifecycle with retry/backoff, network awareness, and tracing, replacing the previous WebSocket RPC client approach.
• Replaces Zustand stores and React Query throughout web and mobile with atom families scoped per environment (shell state, thread detail, VCS, terminal, preview, server config, assets, auth).
• Introduces a typed ConnectionCatalogDocument (targets, profiles, credentials) backed by IndexedDB on web, secure storage on mobile, and encrypted desktop storage, replacing the legacy saved environment registry and secrets APIs.
• Adds a mobile thread outbox with durable per-message JSON persistence and an automatic drain hook (useThreadOutboxDrain) that retries on transient failures.
• @t3tools/client-runtime now requires explicit subpath imports (e.g. @t3tools/client-runtime/state/shell); the root export is removed and a lint rule enforces subpath usage.
• Desktop IPC channels switch from saved-environment registry/secret methods to getConnectionCatalog, setConnectionCatalog, and clearConnectionCatalog.
• Risk: Breaking change — any code importing from the @t3tools/client-runtime root or calling removed APIs (syncProjects, syncThreads, connectSavedEnvironment, useRemoteEnvironmentBootstrap, etc.) will fail at compile or runtime.

^{Macroscope summarized 1551f69.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 95e29028-8ce5-4832-9923-acff2a69a2d3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/connection-state-audit

---

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

[github-actions]

🚀 Expo continuous deployment is ready!

• Project → t3-code
• Platforms → android, ios
• Scheme → t3code-preview

	🤖 Android	🍎 iOS
Fingerprint	b0da31fdd85a1becc2a86a825c791b045a5afa58	eb056ff68ca484dcf1b32e25342b2824e89824cc
Build Details	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 App version: 0.1.0 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc App version: 0.1.0 Git commit: 5c744a980761a8e18b4c7a78c1b3bd7ed0e9e6c7
Update Details	Update Permalink Details Branch: pr-2978 Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Update Permalink Details Branch: pr-2978 Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae
Update QR

[macroscopeapp]

🟡 Mediumconnection/webConnectionStorage.ts:87

When indexedDB.open() needs to upgrade the schema but another tab holds an older version, the blocked event fires and the Effect never completes — neither success nor error handlers execute until the blocking tab closes. If that tab never closes, openDatabase hangs indefinitely. Consider handling the blocked event by resuming with a descriptive error or triggering a retry with timeout.

+ request.addEventListener("blocked", () => {+ resume(Effect.fail(catalogError("open", "Database upgrade blocked by another tab")));+ });

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/connection/webConnectionStorage.ts around lines 87-113:
When `indexedDB.open()` needs to upgrade the schema but another tab holds an older version, the `blocked` event fires and the Effect never completes — neither `success` nor `error` handlers execute until the blocking tab closes. If that tab never closes, `openDatabase` hangs indefinitely. Consider handling the `blocked` event by resuming with a descriptive error or triggering a retry with timeout.
Evidence trail:
apps/web/src/connection/webConnectionStorage.ts lines 87-114 at REVIEWED_COMMIT: `openDatabase` registers handlers for `upgradeneeded` (line 96), `error` (line 107), and `success` (line 110), but not for `blocked`. IndexedDB spec: https://w3c.github.io/IndexedDB/#request-api — the `blocked` event fires on IDBOpenDBRequest when the open operation is blocked by existing connections, and `success`/`error` don't fire until the block is resolved.

[macroscopeapp]

🟡 Mediumcloud/managedAuth.tsx:59

On first render when signed out, previousAccount is undefined, so undefined !== null evaluates to true and queueAccountCleanup() runs unnecessarily. This triggers removeRelayEnvironments() and relay client token cache reset even though no account was ever established. Change the condition to if (previousAccount) so cleanup only happens when transitioning from an actual signed-in state.

- if (previousAccount !== null) {+ if (previousAccount) {

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/cloud/managedAuth.tsx around line 59:
On first render when signed out, `previousAccount` is `undefined`, so `undefined !== null` evaluates to `true` and `queueAccountCleanup()` runs unnecessarily. This triggers `removeRelayEnvironments()` and relay client token cache reset even though no account was ever established. Change the condition to `if (previousAccount)` so cleanup only happens when transitioning from an actual signed-in state.
Evidence trail:
apps/web/src/cloud/managedAuth.tsx lines 26, 35, 37, 57-61, 63 at REVIEWED_COMMIT. Line 26: ref initialized to `undefined`. Line 35: `previousAccount = observedAccountRef.current` (undefined on first render). Line 59: condition `previousAccount !== null` doesn't account for `undefined`. Line 63: correctly checks all three states (`!== undefined && !== null && !== userId`).

[macroscopeapp]

🟡 Mediumcomponents/ChatView.tsx:1119

The refactored code removed the guard that excluded the primary environment from unavailability checks. Now activeEnvironmentUnavailable is computed for all environments including the primary, so if the primary's connection.phase is temporarily "connecting" or "available" during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/components/ChatView.tsx around line 1119:
The refactored code removed the guard that excluded the primary environment from unavailability checks. Now `activeEnvironmentUnavailable` is computed for all environments including the primary, so if the primary's `connection.phase` is temporarily `"connecting"` or `"available"` during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.
Evidence trail:
Old guard at MERGE_BASE in ChatView.tsx: `activeThread.environmentId !== primaryEnvironmentId` check in `activeSavedEnvironmentRecord` assignment; new code at REVIEWED_COMMIT ChatView.tsx lines 1119-1123 with no primary guard; `AVAILABLE_CONNECTION_STATE` defined at packages/client-runtime/src/connection/model.ts:148-154 with `phase: "available"`; `activeEnvironmentUnavailable` used to block sends at ChatView.tsx:2806, ChatView.tsx:3427; used to block revert at ChatView.tsx:2746; used for banner at ChatView.tsx:1353; `isConnecting` always false at ChatView.tsx:904 (`_setIsConnecting` unused).

[juliusmarminge]

Summary

Replace the independent web and mobile connection implementations with a shared Effect-based client runtime.

• introduce environment descriptors, connection drivers, resolution, supervision, authorization, relay discovery, RPC sessions, and lifecycle ownership in @t3tools/client-runtime
• move runtime state to explicit environment-scoped modules for auth, connections, projects, threads, shell, terminal, filesystem, source control, review, and presentation
• migrate web, desktop, and mobile integrations to explicit client-runtime subpath exports
• add persisted connection catalogs for web, mobile, and desktop, including encrypted desktop storage and mobile legacy migration
• centralize retry/backoff, connectivity wakeups, credential refresh, account-transition cleanup, session ownership, subscription recovery, and mobile outbox draining
• preserve scoped relay tracing across the rewritten runtime and release configuration
• harden local relay startup and agent-activity credential reconciliation

Scope

The native mobile composer, markdown renderer, Clerk sheet routing, turn-fold presentation, and Pierre icons were reviewed separately in #3101 and are now part of main. This PR contains the client connection/runtime rearchitecture on top of that merged base.

Validation

• node scripts/release-smoke.ts
• vp check
• vp run typecheck
• vp run lint:mobile
• 96 changed test files passed, covering 741 tests including every changed backend test

---

Note

High Risk
Touches encrypted credential persistence, legacy migrations, and breaking desktop IPC channels while reshaping mobile connection lifecycle and cloud account transitions—errors in migration or catalog reads can strand users' environments.

Overview
Desktop drops the saved-environment registry IPC surface in favor of get / set / clear connection catalog handlers backed by a new DesktopConnectionCatalogStore: Electron safe-storage encryption, atomic writes, one-time migration from legacy relay/SSH/bearer records, and read errors for corrupt or undecryptable catalogs instead of silent empty state. DesktopSavedEnvironments now propagates ReadError for malformed registry JSON (used only for migration). Minor fixes: cloud auth header typing, SSH imports split to client-runtime subpaths.

Mobile adds a full connection stack (connectionPlatformLayer, secure catalog + legacy migration, shell/thread snapshot caches, pairing onboarding commands, environmentCatalog atoms) and rewires the app to useWorkspaceState, useConnectionController, and useAtomCommand for environments, pairing, settings, and favicons via useAssetUrl. Cloud settings/environments UI gains status dots, switches, trace IDs, and serialized account cleanup on Clerk sign-in/out (activateCloudRelayAccount / deactivateCloudRelayAccount). Agent-awareness relay device registration is queued and coalesced; settings/async flows use settleAsyncResult. Adds expo-network, iOS modular CocoaPods for App Check deps, and EAS push prompt tweak.

CI removes the dedicated Playwright browser test job from ci.yml.

^{Reviewed by Cursor Bugbot for commit 1551f69. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace client connection architecture with atom-based environment-scoped state

• Introduces a layered connection subsystem (ConnectionRegistry, ConnectionDriver, ConnectionResolver, EnvironmentSupervisor) that manages environment lifecycle with retry/backoff, network awareness, and tracing, replacing the previous WebSocket RPC client approach.
• Replaces Zustand stores and React Query throughout web and mobile with atom families scoped per environment (shell state, thread detail, VCS, terminal, preview, server config, assets, auth).
• Introduces a typed ConnectionCatalogDocument (targets, profiles, credentials) backed by IndexedDB on web, secure storage on mobile, and encrypted desktop storage, replacing the legacy saved environment registry and secrets APIs.
• Adds a mobile thread outbox with durable per-message JSON persistence and an automatic drain hook (useThreadOutboxDrain) that retries on transient failures.
• @t3tools/client-runtime now requires explicit subpath imports (e.g. @t3tools/client-runtime/state/shell); the root export is removed and a lint rule enforces subpath usage.
• Desktop IPC channels switch from saved-environment registry/secret methods to getConnectionCatalog, setConnectionCatalog, and clearConnectionCatalog.
• Risk: Breaking change — any code importing from the @t3tools/client-runtime root or calling removed APIs (syncProjects, syncThreads, connectSavedEnvironment, useRemoteEnvironmentBootstrap, etc.) will fail at compile or runtime.

^{Macroscope summarized 1551f69.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 95e29028-8ce5-4832-9923-acff2a69a2d3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/connection-state-audit

---

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

[github-actions]

🚀 Expo continuous deployment is ready!

• Project → t3-code
• Platforms → android, ios
• Scheme → t3code-preview

	🤖 Android	🍎 iOS
Fingerprint	b0da31fdd85a1becc2a86a825c791b045a5afa58	eb056ff68ca484dcf1b32e25342b2824e89824cc
Build Details	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 App version: 0.1.0 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Build Permalink Details Distribution: INTERNAL Build profile: preview:dev Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc App version: 0.1.0 Git commit: 5c744a980761a8e18b4c7a78c1b3bd7ed0e9e6c7
Update Details	Update Permalink Details Branch: pr-2978 Runtime version: b0da31fdd85a1becc2a86a825c791b045a5afa58 Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae	Update Permalink Details Branch: pr-2978 Runtime version: eb056ff68ca484dcf1b32e25342b2824e89824cc Git commit: 332763aebc5ea21c488142ee4a8a3a0bf4c15eae
Update QR

[macroscopeapp]

🟡 Mediumconnection/webConnectionStorage.ts:87

When indexedDB.open() needs to upgrade the schema but another tab holds an older version, the blocked event fires and the Effect never completes — neither success nor error handlers execute until the blocking tab closes. If that tab never closes, openDatabase hangs indefinitely. Consider handling the blocked event by resuming with a descriptive error or triggering a retry with timeout.

+ request.addEventListener("blocked", () => {+ resume(Effect.fail(catalogError("open", "Database upgrade blocked by another tab")));+ });

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/connection/webConnectionStorage.ts around lines 87-113:
When `indexedDB.open()` needs to upgrade the schema but another tab holds an older version, the `blocked` event fires and the Effect never completes — neither `success` nor `error` handlers execute until the blocking tab closes. If that tab never closes, `openDatabase` hangs indefinitely. Consider handling the `blocked` event by resuming with a descriptive error or triggering a retry with timeout.
Evidence trail:
apps/web/src/connection/webConnectionStorage.ts lines 87-114 at REVIEWED_COMMIT: `openDatabase` registers handlers for `upgradeneeded` (line 96), `error` (line 107), and `success` (line 110), but not for `blocked`. IndexedDB spec: https://w3c.github.io/IndexedDB/#request-api — the `blocked` event fires on IDBOpenDBRequest when the open operation is blocked by existing connections, and `success`/`error` don't fire until the block is resolved.

[macroscopeapp]

🟡 Mediumcloud/managedAuth.tsx:59

On first render when signed out, previousAccount is undefined, so undefined !== null evaluates to true and queueAccountCleanup() runs unnecessarily. This triggers removeRelayEnvironments() and relay client token cache reset even though no account was ever established. Change the condition to if (previousAccount) so cleanup only happens when transitioning from an actual signed-in state.

- if (previousAccount !== null) {+ if (previousAccount) {

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/cloud/managedAuth.tsx around line 59:
On first render when signed out, `previousAccount` is `undefined`, so `undefined !== null` evaluates to `true` and `queueAccountCleanup()` runs unnecessarily. This triggers `removeRelayEnvironments()` and relay client token cache reset even though no account was ever established. Change the condition to `if (previousAccount)` so cleanup only happens when transitioning from an actual signed-in state.
Evidence trail:
apps/web/src/cloud/managedAuth.tsx lines 26, 35, 37, 57-61, 63 at REVIEWED_COMMIT. Line 26: ref initialized to `undefined`. Line 35: `previousAccount = observedAccountRef.current` (undefined on first render). Line 59: condition `previousAccount !== null` doesn't account for `undefined`. Line 63: correctly checks all three states (`!== undefined && !== null && !== userId`).

[macroscopeapp]

🟡 Mediumcomponents/ChatView.tsx:1119

The refactored code removed the guard that excluded the primary environment from unavailability checks. Now activeEnvironmentUnavailable is computed for all environments including the primary, so if the primary's connection.phase is temporarily "connecting" or "available" during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/components/ChatView.tsx around line 1119:
The refactored code removed the guard that excluded the primary environment from unavailability checks. Now `activeEnvironmentUnavailable` is computed for all environments including the primary, so if the primary's `connection.phase` is temporarily `"connecting"` or `"available"` during startup, the UI shows an unavailable banner and blocks message dispatch — behavior that never occurred before.
Evidence trail:
Old guard at MERGE_BASE in ChatView.tsx: `activeThread.environmentId !== primaryEnvironmentId` check in `activeSavedEnvironmentRecord` assignment; new code at REVIEWED_COMMIT ChatView.tsx lines 1119-1123 with no primary guard; `AVAILABLE_CONNECTION_STATE` defined at packages/client-runtime/src/connection/model.ts:148-154 with `phase: "available"`; `activeEnvironmentUnavailable` used to block sends at ChatView.tsx:2806, ChatView.tsx:3427; used to block revert at ChatView.tsx:2746; used for banner at ChatView.tsx:1353; `isConnecting` always false at ChatView.tsx:904 (`_setIsConnecting` unused).