feat: remote control — Expo mobile app + desktop proxy

[sethwebster]

Summary

• Expo mobile app (apps/mobile/) connects to the desktop app over the local network via an authenticated WebSocket proxy, providing full remote control of coding sessions
• Desktop remote access server (apps/desktop/src/remoteAccess.ts) — HTTP+WS proxy on port 3773 with token auth, QR code pairing, and network address discovery
• Shared deep link utilities (packages/shared/src/remote.ts) — t3remote:// URL scheme for QR-code and URL-based pairing between mobile and desktop
• Server-side thread message pagination — ThreadMessageHistoryQuery service with offset-based pagination for mobile's lazy-load feed
• Web remote settings UI — sidebar integration for enabling/disabling remote access, displaying endpoints, and generating QR codes
• Security hardening — constant-time token comparison, TOCTOU mutex on server start, bounded WS message buffer, upgrade error logging
• React architecture cleanup — all bare useEffect calls extracted into named custom hooks, inline closures wrapped in useCallback, markdown styles and glyph tables hoisted to module constants

Test plan

• Desktop: enable remote in settings, verify QR code and endpoint URLs appear
• Mobile: scan QR code or enter URL+token manually, verify connection establishes
• Mobile: browse projects/threads, open thread detail, send a message
• Mobile: verify approval requests and user input prompts render and respond correctly
• Mobile: kill desktop app, verify reconnect with backoff and "Reconnecting" UI
• Mobile: verify deep link t3remote://connect?serverUrl=...&authToken=... auto-connects
• Web: verify sidebar, chat, and settings still function after refactor
• npx vitest run passes in all packages (shared: 62, desktop: 53, web: 615, server: 597)

---

Note

Medium Risk
Introduces a large new apps/mobile Expo client that can connect to remote servers and issue orchestration commands, plus changes desktop runtime (single-instance lock, optional devtools) and dev scripts; issues are likely to be integration/runtime regressions rather than isolated UI bugs.

Overview
Adds a new Expo/React Native mobile app (apps/mobile) for remote orchestration control: connect via server URL + optional auth token (with preflight health check), persist credentials, browse projects/threads, view a thread feed with lazy message pagination, send/queue messages with attachments, respond to approvals/user-input prompts, interrupt running turns, and handle reconnecting UI.

Updates desktop development and runtime behavior: replaces the desktop dev script with a coordinator (scripts/dev.mjs) for bundler/Electron lifecycle, adjusts Electron launcher resolution for dev on macOS, adds a single-instance lock with “focus existing window” behavior, and gates auto-opening DevTools behind T3_DESKTOP_OPEN_DEVTOOLS=1. Also adds a tested closeWebSocket helper to safely close vs terminate depending on close code.

Documentation and repo hygiene: expands REMOTE.md with mobile remote setup/architecture notes and updates .gitignore for Expo/native artifacts.

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

Note

Add Expo mobile app and desktop proxy for remote control of the T3 chat interface

• Introduces a new apps/mobile Expo/React Native app that connects to a running desktop instance over WebSocket, displays thread lists and chat feeds, and supports composing messages with image attachments
• Adds a RemoteClient class with reconnection logic, RPC over WebSocket, and a /api/remote/health health-check endpoint on the server for preflight validation
• Adds getThreadMessagesPage as a paginated RPC method wired through contracts, server WS handler, and the web NativeApi surface
• Adds deep-link URL helpers (buildRemoteAppConnectionUrl, parseRemoteAppConnectionUrl) and a QR code component in web settings so users can connect the mobile app by scanning
• Rewrites the web app's visual theme with oklch-based palettes, gradient overlays, and blur/saturation surface classes across the sidebar, chat, and composer
• Risk: the mobile app requires Expo SDK 55 and React Native 0.83, adding a large dependency footprint to the monorepo lockfile and root package.json

^{Macroscope summarized 16ed6cc.}

[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: 1fb853f2-1eba-48ae-8dc9-00e0e52229c1

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[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.}

[sethwebster]

Squashed to a single commit and resolved all review feedback:

Cursor Bugbot / Macroscope — Critical & High

• Infinite re-render in useStartupConnection and useQueueDrain — destructured the deps parameter so individual stable callback refs appear in the dependency array instead of a fresh object literal
• RemoteClient.connect() orphaned sockets — now calls clearReconnectTimer() before openWebSocket() to prevent a pending reconnect from creating a second concurrent socket
• dev.mjs spawn error hang — children.delete(scriptName) before shutdown() so maybeExit() doesn't wait for a dead child

Macroscope — Medium

• useAutoScrollToLatest animated flag always true — merged the two effects into one so isNewThread is computed before previousThreadIdRef is updated
• AppText leading-none token ordering — deferred lineHeight = fontSize assignment to after the full token loop, so leading-none works regardless of class order
• .expo/, root App.tsx, app.json, tsconfig.json committed — removed from repo, added to .gitignore

[sethwebster]

Resolved second round of review feedback:

Cursor Bugbot — High

• Missing error handler on upstream response — added upstreamResponse.on("error") to prevent unhandled error crash during response streaming

Cursor Bugbot — Medium

• Failed queued messages retry infinitely — removeQueuedMessage() now called in the catch block so failed dispatches don't create an infinite retry loop

Macroscope — High

• Stale socket close handler corrupts new socket state — close handler now returns early when this.socket !== socket, preventing state corruption when old sockets close after a new connection is established

Macroscope — Medium

• stopServer() ordering causes hang — now calls server.close() before destroying sockets; also awaits startingPromise so setEnabled(false) during startup waits for startup to complete before stopping
• connect() doesn't reset reconnectAttempt — added this.reconnectAttempt = 0 so re-connections after disconnect emit "connecting" not "reconnecting"

[sethwebster]

Resolved third round:

Macroscope — High

• Clipboard paste blocks text when at image limit — moved remainingSlots check inside hasImageAsync() branch so text-only paste still works at the image cap
• Pending socket not tracked, leaks on rapid connect() — this.socket = socket assigned immediately after new WebSocket() so closeSocket() can close it before open fires

Macroscope — Medium

• Thread activities filtered out when loadedMessages is empty — flipped condition to oldestLoadedMessageCreatedAt === null || so activities show when no messages are loaded yet

Cursor Bugbot — Medium

• stopServer hangs on keep-alive connections — moved socket destroy before server.close() so connections are torn down before waiting for the close callback

[cursor]

Custom sort/reverse reimplements standard array methods unnecessarily

Low Severity

sortCopy and reverseCopy are hand-rolled reimplementations of [...arr].sort(fn) and [...arr].reverse() with 42 lines of custom insertion-sort and manual-reverse logic. They add no functional benefit over the standard methods (Hermes in Expo SDK 55 supports stable sort per ES2019). Notably, remoteClient.ts in the same app already uses Array.prototype.sort directly, making the custom utilities inconsistent within the codebase itself.

 

[cursor]

Auth token exposed in HTTP image URL query params

Low Severity

messageImageUrl places the auth token in the query string of plain HTTP image URLs. While query-param auth is unavoidable for WebSocket connections, HTTP image requests support Authorization headers. Query-param tokens can leak through server access logs, HTTP caches, and Referer headers when images are loaded. Combined with the NSAllowsArbitraryLoads / usesCleartextTraffic settings allowing unencrypted traffic, this means the auth token can be transmitted and logged in cleartext.

 

[cursor]

Auth token passed in URL query parameter

Medium Severity

The auth token is passed as a query parameter (?token=...) in the WebSocket URL and image attachment URLs. Query parameters are commonly logged by proxies, web servers, and browser history, and may appear in Referer headers. The REMOTE.md doc even describes this as "Auth via query param on WebSocket URL" under the security model. Using an Authorization header or a subprotocol for WebSocket auth, and a cookie or header for image fetches, would avoid leaking the token in logs and URLs.

Additional Locations (1)

• apps/mobile/src/features/threads/threadPresentation.ts#L56-L61

 

[cursor]

Insertion sort silently injects undefined into typed arrays

Low Severity

In sortCopy, when candidate at insertionIndex is undefined (line 16), the while loop doesn't break and writes candidate (i.e. undefined) into next[insertionIndex + 1] on line 20. This shifts undefined values through the array without the type system catching it, since next is typed as T[]. For dense arrays this is a no-op, but if T includes values that happen to be at holes, the sort can corrupt the output. Using [...values].sort(compareFn) would be simpler and correct.

 

[cursor]

Signal lost in dev.mjs shutdown, uses exit code instead

Low Severity

The SIGINT and SIGTERM handlers call shutdown() with only a code (130 / 143) but no signal property. The maybeExit function (line 27-28) only re-raises the signal via process.kill(process.pid, exitSignal) when exitSignal is set. Without it, the process calls process.exit(130) instead of re-raising SIGINT, which breaks signal-chain conventions — parent processes (like shells) can't distinguish a numeric exit from a proper signal death.

 

[macroscopeapp]

🟢 Low connection/ConnectionSheet.tsx:165

allowSwipeDismissal is not a valid prop on the React Native Modal component, so it will be silently ignored. On iOS with presentationStyle="pageSheet", swipe-to-dismiss is already enabled by default; if the intent was to disable it, this prop won't achieve that and the modal will still dismiss on swipe. Consider removing the invalid prop, or if swipe prevention is required, use a third-party modal library that supports this feature.

    <Modal
      animationType="slide"
      presentationStyle="pageSheet"
-      allowSwipeDismissal
      visible={props.visible}

🤖 Copy this AI Prompt to have your agent fix this:

In file apps/mobile/src/features/connection/ConnectionSheet.tsx around lines 165-171:

`allowSwipeDismissal` is not a valid prop on the React Native `Modal` component, so it will be silently ignored. On iOS with `presentationStyle="pageSheet"`, swipe-to-dismiss is already enabled by default; if the intent was to disable it, this prop won't achieve that and the modal will still dismiss on swipe. Consider removing the invalid prop, or if swipe prevention is required, use a third-party modal library that supports this feature.

Evidence trail:
apps/mobile/src/features/connection/ConnectionSheet.tsx lines 1 (import shows Modal from 'react-native') and lines 165-171 (Modal usage with allowSwipeDismissal prop). apps/mobile/package.json shows react-native version 0.83.2. Web research confirms React Native 0.83.x Modal does not have allowSwipeDismissal as a valid prop - verified against React Native source (Modal.js, ModalHost.js, ReactModalHostManager.java).

[cursor]

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

There are 6 total unresolved issues (including 5 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 16ed6cc. Configure here.}

[cursor]

Signal re-delivery caught by own once handler

Low Severity

When a child process dies from a signal during shutdown, maybeExit calls process.kill(process.pid, exitSignal) to re-signal itself. However, the process.once("SIGTERM") handler is still registered and catches that signal, calling shutdown() which returns early since shuttingDown is already true. The once handler is then removed, but no process.exit() is ever called. The event loop drains and the process exits with code 0 instead of the intended non-zero exit code. The signal handlers need to be removed before re-signaling, e.g. via process.removeAllListeners on the target signal.

Additional Locations (1)

• apps/desktop/scripts/dev.mjs#L115-L118

 

^{Reviewed by Cursor Bugbot for commit 16ed6cc. Configure here.}