feat(client): persist offline environment data and mobile preferences

[juliusmarminge]

Summary

Adds durable offline environment data, centralized mobile preferences, and scoped client-cache management.

Offline environment data

• Persists the last complete server configuration, including provider and model metadata, per environment.
• Persists complete, unfiltered Git ref lists for offline branch selection.
• Hydrates cached server configuration and refs while disconnected, then replaces them with live data after reconnecting.
• Debounces server configuration writes and flushes pending data during teardown.
• Uses live errors while connected instead of silently falling back to stale refs.
• Uses IndexedDB version 4 stores on web and a schema-versioned Expo SQLite database on mobile.
• Runs the mobile database through one scoped Effect layer with WAL enabled and a managed close finalizer.
• Reclaims the obsolete mobile file-cache directories on the first SQLite migration.

Mobile preferences

• Centralizes preference loading and updates behind an Effect service and keep-alive atoms.
• Stores non-secret preferences in SQLite and migrates the legacy SecureStore preference blob on first read.
• Keeps credentials, connection metadata, and device identity in SecureStore.
• Migrates appearance preferences away from component-level hydration effects.
• Preserves optimistic updates made before the initial preference read completes.
• Persists collapsed home-screen project groups through the shared preference state so they survive restarts.

Client storage controls

• Adds App → Client Storage settings with aggregate and per-environment cache inspection.
• Supports clearing one environment cache or all client caches.
• Cache clears intentionally preserve environment connections, credentials, account data, and app preferences.

Impact

Mobile users can configure pending tasks with their last-known model and branch while offline, inspect locally cached data, and reclaim it without disconnecting environments. Web clients share the durable environment-cache behavior. Mobile preferences now have one async state owner with predictable hydration and update semantics.

Validation

• vp check
• vp run typecheck
• vp run lint:mobile
• vp test apps/mobile/src (76 files, 427 tests)
• React Doctor on the changed React surface (no diagnostics)
• Expo public config evaluation

---

Note

Medium Risk
One-time SQLite and legacy file-cache migration on app start can leave partial data if migration fails; preference SQLite/SecureStore reconciliation affects appearance and Live Activity behavior across upgrades.

Overview
Mobile offline data moves from document-directory JSON files into Expo SQLite (expo-sqlite plugin, t3code-client.db) via a new MobileDatabase service and a dedicated EnvironmentCacheStore implementation for shell/thread snapshots, server config, and VCS refs. Legacy file caches are migrated on first DB upgrade; corrupt rows are dropped on read. The old inline cache logic is removed from connection/storage.ts; EnvironmentCacheStore is composed through persistence/layer and the app runtime.

Persistence refactor deletes lib/storage.ts in favor of MobileSecureStorage, MobileStorage, and MobilePreferencesStore (SQLite for preferences with SecureStore fallback/reconciliation). Connection catalog storage now yield*s secure storage instead of injected storage objects. persistence/imperative.ts keeps Promise APIs for legacy call sites on top of the shared managed runtime.

Preferences UX adds keep-alive atoms (mobilePreferencesAtom / updateMobilePreferencesAtom) with optimistic patches, wires appearance and settings to them, persists collapsed home project groups, and adds Settings → Client Storage to inspect and clear per-environment or all offline caches without touching connections/credentials.

Live Activities / cloud link uses linkEnvironmentToCloudWithPreference with explicit flags, updateAgentAwarenessRegistrationPreferences with in-flight preference overrides, and rolls back local and relay state when toggling fails.

Build/tooling: EAS profiles set NODE_OPTIONS=--max-old-space-size=4096; new dev:client:preview script. Effect service conventions doc gains dependency/runtime boundary guidance. Minor CursorAdapter test splits JSON log assertions.

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

Note

Persist offline environment data and mobile user preferences in the mobile app

• Introduces a SQLite-backed MobileDatabase service and a structured EnvironmentCacheStore to cache server configuration and VCS branch lists per environment, enabling cached data to be shown when offline and refreshed when connected.
• Adds MobilePreferencesStore backed by MobileSecureStorage (expo-secure-store) with optimistic update support; preferences now survive app restarts and failed saves attempt rollback.
• Replaces the deleted src/lib/storage.ts with a structured persistence layer under src/persistence/ comprising mobile-database.ts, mobile-preferences.ts, mobile-secure-storage.ts, mobile-storage.ts, and a unified layer.ts wired into the app runtime.
• Persists home screen project group collapse state and appearance preferences via the new atom-based preferences state (mobilePreferencesAtom); Live Activity preference changes now propagate to all linked cloud environments and revert locally and remotely on failure.
• Adds a "Client Storage" settings screen (SettingsClientStorageRouteScreen) showing per-environment SQLite cache usage with options to clear individual or all environment caches.
• Extends the web EnvironmentCacheStore and client-runtime persistence contracts to include loadServerConfig/saveServerConfig and loadVcsRefs/saveVcsRefs methods.
• Risk: IndexedDB schema version bumped from 2 to 4 on web; existing users will trigger a DB upgrade creating new server-config and vcs-refs object stores.

^{Macroscope summarized 9dd6245.}

[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: 4482278b-f0ec-4fe3-abf4-d60417ebb015

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 agent/offline-environment-cache

---

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

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

^{Reviewed by Cursor Bugbot for commit 43884b5. Configure here.}