* feat(github): add a PR auto-refresh cadence setting that caps background PR/checks polling (STA-8667) Timed PR, review and checks refreshes were hardcoded (1/2 min visible, 15 min no-review), with no way to slow them on a busy headless `orca serve` or a shared GitHub Enterprise Server. Adds `prAutoRefresh: default | reduced | minimal | off` (5x / 10x / no timed refresh). Selecting a workspace, pushing, returning to the window and manual refresh still read at once in every mode. - shared policy scales every timed interval from one process-wide cadence, set from settings in main (desktop and serve) and in the renderer - main re-plans queued visible follow-ups when the cadence changes - a paired server's cadence also caps clients' timed `github.prForBranch` reads (reuses the last answer for the same head) and stretches the hosted review branch cache TTLs, so more clients add no GitHub calls - CI-line watches slow to the minimal cadence instead of stopping when off - Settings > Git & Source Control gains a host-aware PR Auto-Refresh control * feat(github): make the PR Auto-Refresh control say how often it checks and whose host it changes (STA-8667) UX round UX-I1: the hint under the segmented control states the actual cadence for the selection, derived from the shared policy, and when a paired server is the Settings host the control says it applies to that host and every connected client. Adds a presentational PRAutoRefreshControl with fixtures and a component test. * fix(github): make the PR auto-refresh cadence per execution host and close the C1 polling gaps (STA-8667) Review round C1 on #40541 found seven places where the new cadence did not hold. This settles the contract as one cadence per execution host and fixes each gap with a regression test: - The renderer schedules each workspace by the cadence of the host that runs its GitHub reads: its own setting for local work, the paired host's setting (read on contact, on settingsChanged and from the Settings control) for that host's workspaces. A local Off no longer stops a remote Default and the reverse. Policy, timers and the checks panel re-plan on any cadence change. - github.prForBranch and github.prChecks: a paired client's timer reads carry reason swr/visible and the host answers them from its last read at its cadence; window return, screen open, manual refresh and changed-state reads carry foreground/noCache and always reach the provider. Mobile sends the same intent for its own timer. - Off stops ordinary failure retries (main coordinator, renderer scheduler, checks detail policy); CI-line watches keep retrying at Minimal. - Earlier-head CI watches follow the same watch cadence as the current head. - The paced PR cache identity includes acceptMergedFallbackPR. * fix(github): close the C2 PR auto-refresh gaps: checks cache freshness and scope, retry and settings-sync races, focus return under Off, mobile foreground reads (STA-8667) - github.prChecks: every successful full read (timed, foreground, manual, noCache) is recorded as the host's last answer with start-order protection, so a later timed client never gets an older result back; the paced key now carries the execution scope, review generation and resolved gh read scope like the provider read itself. - Renderer visible scheduler: a retry armed after a failure is dropped when the owning host's cadence becomes Off and re-timed when it is stretched, instead of firing once under the old cadence. - Remote host cadence sync: a settingsChanged (or regained contact) during an in-flight settings.get marks it dirty and triggers one trailing read; a slow answer never reverts a value the Settings control wrote or re-adds an unpaired host. - Checks panel: a focus-only window return (document never hidden) reads once under Off with the usual cooldown and in-flight guards, unless the checks are settled. - Settings: the remote PR Auto-Refresh control shows the one shared, subscribed copy of the host's setting, so another client's change is reflected while mounted and the displayed option can be chosen back. - Mobile: a branch read right after the app comes to the foreground is sent as foreground and bypasses the host's 30 s reuse of its own desktop lookup. Each new test fails without its fix. * fix(github): close the C3 PR auto-refresh gaps: queued main error retries on cadence change, window return under Reduced/Minimal, older paired host fallback (STA-8667) * perf(github): share and pace timed pull request reads on the host Reuse exact completed results for automatic refreshes, back off unchanged settled pull requests, and route server revalidation through the existing host budget while preserving foreground reads and older clients. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * fix(github): preserve shared producer settlement and selected demand Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * test(github): cover paired receipt retries and watch fairness * test(github): explain shared fake-clock fixture * test(github): typecheck host and renderer integration together * test(github): name exported fixture mock types * Revert "test(github): typecheck host and renderer integration together" This reverts commit756a38787c. * test(github): place host and renderer loops in cross-layer suite * fix(github): say what the PR auto-refresh setting actually limits (STA-8667) The Off hint now says CI checks a chat follows are still read at the Minimal interval, the interval hint no longer promises a one-minute read for settled pull requests, and the description no longer claims a cap on every client: clients on older Orca versions keep their Default timer, and returning to the window reads data older than its Default interval. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(github): close the auto-refresh review gaps (STA-8667) - A window return or re-shown row that is due under the Default interval now reads past the stretched timed cache instead of being answered from it. - Turning auto-refresh Off also retires a host revalidation that was waiting for quota, so it never starts or requeues afterwards. - A newer manual checks answer stays authoritative while an older read of the same checks is still out, even when 256 other checks fill the cache. - A paired host keeps no auto-refresh state after it is forgotten; a read from before unpairing never answers for it, and a re-paired host is read afresh. - A host's cadence change re-plans only the visible rows that host runs, and this app's own setting re-plans its rows in main instead of re-reporting. - Settled rows wait at least a minute on return under a stretched cadence; Default keeps its cooldown. - The setting's copy no longer promises a read on selecting a workspace. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(github): preserve refresh policy and shared callers Use the same validated freshness for cached queue reads and their follow-up. Keep forced mergeability rereads and detach cancelled consumers independently from the shared lookup. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * fix(github): give checks, host reads and cadence replans their actual owners (STA-8667) - Checks: the running read of a resource, not the cache, decides which answer is current. A manual answer that finishes while an older read of the same checks still runs is handed to that read, which answers with it and never publishes its own; a read replaced as stale answers with its replacement. The completed cache is held to 256 answers at all times. - A cadence change on one paired host re-plans only that host's visible targets from their own Default interval, without rebuilding any rows. - Off no longer re-queues a failed row at its gate when the cadence is retimed; Off back to Default still resumes timed reads and error retries. - Tests cover a full cache of rows being read again, mixed-host replans and the full life of a forgotten host's read, including a failing one. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(github): let a replaced checks read answer only with its successor (STA-8667) Overlapping reads of one PR head share the newest accepted answer while any of them runs. A read replaced as stale or by a user refresh publishes nothing and answers its callers with that newer answer, even after it was evicted from the completed cache, or with its successor still running; its own result is used only when no newer answer exists, and its error only when there is no answer. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(github): preserve refresh policy and shared callers Use the same validated freshness for cached queue reads and their follow-up. Keep forced mergeability rereads and detach cancelled consumers independently from the shared lookup. Carried fromfc3b99db2a(#42033). Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * fix(github): keep queued PR reads on their own job and validated freshness (STA-8667) - A host revalidation retired by Off while it awaited quota, then replaced by a new read of the same PR, can no longer start, delete or requeue over that new read; the quota pause it learned still holds the key for the new read. - A queued local read decides whether its cached answer is fresh with the same validated interval that schedules its follow-up; a foreground return is judged by the Default interval that made it due, and later follow-ups go back to the cadence (none under Off). Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(github): keep overlap authority, foreground reads and failure retries owned (STA-8667) - Checks: overlapping reads of one PR head share one record kept until the last of them settles, so a read replaced by a user refresh that has already ended still answers with a newer manual answer after it was evicted, rechecked after waiting on its successor. - A row shown again after its settled age reads instead of being answered by a cached settled result; one foreground age decides both whether the return earns a read and whether the current cached answer satisfies it. - Off back to Default restores a failed row's own retry from its failure, still an error retry the next Off retires, without a new report or manual action. - Test fixes: advance the replaced job's start cooldown, run the checks reads without command-slot limits, typed fixtures and clock-rule notes. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(github): refresh settled rows when exposed again Use the same finite foreground age to admit and consume the queued read. A recent exact result can still satisfy it, and settled rows do not acquire a recurring timer. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * test(github): keep the real command slots in the checks capacity proof (STA-8667) The all-live case now runs through the real four-slot command limiter: 256 rereads are live while four gh commands run, the new manual read waits its turn and then reads, and cleanup settles every queued read through its slot. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(github): keep a failure's retry and a restored follow-up automatic (STA-8667) - Each exact PR read now has one resource record (its timed and fresh probes, the provider reads running for it and the newest start). A failed full read claims that record for the retry it owes even when the exact cache had no room to keep the outcome, so the retry keeps its original failure time and count, Off retires it, and Default restores it as a retry. A newer read of the same request, a scope change or another HEAD ends the claim; a failure that a newer read had already replaced owes no retry. - A row no longer shown releases its failure's claim; dropping an old gate index entry no longer forgets a visible row's failure. - When timed cadence resumes, a row without a failure gets the automatic follow-up its interval gives it, still a follow-up, so the next Off retires it; one derivation decides creation, retiming and the check after a quota wait. A genuine return or action already queued keeps its own reason. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(mobile): run the PR timer as a client Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * fix(github): plan automatic PR reads from the newest read and end them with their demand (STA-8667) - A newer provider read of the same request starting retires a failure that is already settled: its queued retry and its claim go, while its count and rate gate stay. The retry check before a start, including after a quota wait, re-validates that the failure still owns the request and row. - A full read whose caller brings no settlement of its own (another client's read, a host job, a provider lookup) plans the visible row's next automatic work, as the row's own read would. A late failure that a newer read replaced owes no retry and leaves the newer read's plan in place. - A routine report of a row still shown as the same request keeps its automatic work automatic. Only a return, a new row or another request earns a read the cadence does not give. - After a quota wait an automatic read takes its current plan: retired, later (it waits for the plan and the learned pause, without displacing work queued since) or ready. - Visibility ends a row's demand where it is removed: a report that drops it, a window cleared or pruned once its renderer is gone, a removed workspace. Only the affected window's rows are checked, so a report no longer walks every window's rows. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(github): accept only current PR read completions Keep shared publication and retry planning on the accepted actual read. Preserve legacy own replies, terminal loading and ordinary work after a superseded lookup, and honor the accepted error gate before automatic recovery. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * test(github): follow moved request contracts * fix(github): keep PR refresh delivery and demand current Use the accepted provider completion for publication and retry planning. Recheck live demand before automatic starts, preserve user actions under Off, and keep the current failure schedule after interval changes. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * test(github): explain the partial event fixture type assertion * fix(github): resolve a PR read's scope once per demand decision An admission decision now resolves the request's current scope once and compares each window's row in it through the same exact-key definition, instead of resolving the project account for the captured request and again for every compared alias. A row with other repository or execution inputs is still another request; the decision after preparation still checks the prepared read's own scope. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(github): preserve queued deadlines and detachable PR waits * fix(github): compare refresh wakes on the elapsed clock * test(github): format queued refresh deadline cases * fix(github): charge actual producers and fence retry gates * fix(github): preserve fresh intent and producer error policy * fix(github): retain owned cold-read retry gates * fix(github): refresh checks after a delayed background return Keep one qualified foreground return after a delayed automatic read, preserve GitLab background guards, and use the existing fresh fetch path when the panel returns. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * Keep retimed PR retry gates on their current request * Remove unused PR admission adapter restored by main merge * Clarify watch plan types and fake-clock regression fixtures * Align PR refresh fixtures with current read ownership and elapsed time * fix: retain shown pull request aliases through admission * fix: preserve new pull request row exposure with timers off * test: match fake clock exceptions to TSX lint rules * test: explain deliberate fake timer fixture waits * test: align PR revisit recording and remove duplicate fixture * test: honor default freshness in Off exposure proof * refactor(mobile): simplify PR read intent branches * fix(github): preserve alias actions and foreground refresh intent Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * fix(github): release obsolete failures before queued restoration Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * fix(github): retain provider retry holds on foreground return Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * test(github): keep both quota aliases visibly demanded Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * test(github): use fixed intervals for provider hold proof Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * test: align PR refresh mocks with existing request types Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * perf(github): compare PR demand without rediscovering account ownership Keep live scope fences on prepared reads and compare captured request inputs for demand. Tighten the existing fleet contract, keep narrow settings panels readable, and follow the moved mobile polling owner. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * fix(github): retain project account authority in shared PR demand Treat explicit and implicit bindings alike for a known project, and retire that equivalence when project ownership changes. Preserve unknown-account separation without restoring inventory scans. Use the existing muted icon button variant for PR Updates. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> * test(settings): mount PR Updates with its tooltip provider Keep the late-response ordering regression focused on host state and option selection, without assertions on UI copy. Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com> --------- Co-authored-by: Brennan Benson <79079362+brennanb2025@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Orca Mobile
React Native companion app for Orca. Monitor worktrees, view terminal output, and send commands from your phone.
Local development uses two processes:
- Orca desktop/Electron from the repo root. This hosts the mobile WebSocket RPC server on port
6768. - Expo Metro from
mobile/. This serves the React Native app on port8081.
Unless a command says otherwise, run mobile app commands from the mobile/ directory.
The Node commands pnpm rpc:diff and pnpm rpc:record use a development dependency linked to ../src/packages/process-host. Mobile's install supplies the link, and tsx runs its source with the orca-source condition, so these command wrappers do not require a desktop install or package build. Keep that source directory in sparse checkouts. The recording suites still need root dependencies when they exercise desktop modules. The React Native app does not import this host package.
Prerequisites
- Node.js 24+
- pnpm
- Xcode and/or Android Studio tooling for simulator or device builds
- Expo Go on your phone, or a development client build when native modules are needed
- Phone and desktop on the same LAN when testing a physical phone
Start Desktop Orca
From the repository root:
pnpm install
pnpm dev
Confirm the mobile RPC server is listening:
lsof -nP -iTCP:6768 -sTCP:LISTEN
Restart pnpm dev after changing Electron main-process code. Metro hot reload only applies to the mobile JavaScript bundle.
Start The Mobile App
cd mobile
pnpm install
pnpm start
Scan the Expo QR code with your phone's camera on iOS, or Expo Go on Android.
For a native dev-client build:
pnpm native ensure ios # or: pnpm native ensure android [--device <name|udid|serial>]
pnpm start --dev-client
ensure computes the Expo fingerprint of the native inputs (native dependencies, config plugins,
modules/, patches/, and the Expo config). On a HIT it installs the cached build on the booted
simulator or the running emulator in a few seconds. On a MISS it regenerates ios/ or android/,
runs expo run:<platform>, and caches the result. --rebuild forces a fresh build.
Builds are cached per fingerprint in the user cache directory (~/Library/Caches/orca-mobile/native-builds
on macOS, $XDG_CACHE_HOME/orca-mobile/native-builds on Linux, %LOCALAPPDATA%\orca-mobile\native-builds
on Windows, or ORCA_MOBILE_NATIVE_BUILD_CACHE_DIR), so every worktree reuses them. The newest three
per platform are kept. app.config.js also registers the cache as Expo's buildCacheProvider, so a
plain pnpm ios / pnpm android installs a cached build instead of compiling. Only ensure writes to
the cache, because expo run reuses an existing ios/ or android/ directory even when it was
generated from older inputs. Expo caches iOS Simulator builds only, not physical devices.
pnpm native fingerprint prints the current hashes. On pull requests, the Mobile native fingerprint
job reports in its summary whether the PR changes them, which means dev clients need a native rebuild.
Pair With Desktop Orca
- Open Orca desktop.
- Go to Settings > Mobile.
- Scan the pairing QR code from the mobile app.
- Confirm the mobile host endpoint is
ws://<desktop-ip>:6768.
For the Android emulator, use ws://10.0.2.2:6768. For a physical phone, use the desktop LAN IP, for example ws://192.168.0.179:6768.
If the phone has a stale host entry, remove it from the app and pair again.
Development Paths
Android Phone
- Install Expo Go from Google Play
- Run
pnpm start, scan QR with Expo Go - For native modules:
pnpm exec expo run:android - Run with
pnpm start --dev-client
iOS Simulator
- Install Xcode from the App Store
- Run
pnpm start --iosto open in iOS Simulator
Physical Phone Debugging
The phone can be inspected through the connected device tooling:
orca snapshot --json
orca click --element @e3 --json
orca fill --element @e1 --value "ls" --json
orca screenshot --json
Use snapshot first to find the current element refs, then click/fill those refs. After mobile file edits, Metro usually hot reloads automatically, but navigating out of and back into the session screen can be useful because it re-runs terminal.subscribe.
Terminal Streaming Repro Without A Phone
Use this when terminal output does not render on device and you need to split server streaming bugs from WebView/UI bugs:
cd mobile
ORCA_MOBILE_WS_URL=ws://127.0.0.1:6768 pnpm exec tsx scripts/test-subscribe.ts <deviceToken> <serverPublicKeyB64>
You can pass a worktree selector as the third argument:
pnpm exec tsx scripts/test-subscribe.ts <deviceToken> <serverPublicKeyB64> "id:<worktreeId>"
pnpm exec tsx scripts/test-subscribe.ts <deviceToken> <serverPublicKeyB64> "path:/absolute/worktree/path"
pnpm exec tsx scripts/test-subscribe.ts <deviceToken> <serverPublicKeyB64> "name:my-worktree"
The expected result includes:
streamSawMarker: true
readSawMarker: true
If this repro fails, debug the desktop runtime/PTY path before the mobile WebView. If it passes but the phone is blank, debug the session screen or TerminalWebView readiness/queueing path.
Terminal Color Repro Without A Phone
Use this when terminal colors disappear after switching tabs. Open a Claude Code terminal and at least one other terminal in the target worktree, then run:
cd mobile
ORCA_MOBILE_WS_URL=ws://127.0.0.1:6768 pnpm exec tsx scripts/repro-terminal-colors.ts \
<deviceToken> <serverPublicKeyB64> "id:<worktreeId>"
The script captures terminal.subscribe snapshots in an A → B → A sequence and writes raw snapshots to mobile/terminal-color-repro/. If the two A snapshots have different sgrColor counts, the desktop snapshot changed during the switch. If they match, the ANSI color data is still present and the bug is in mobile replay/rendering.
Validation
Run these checks before committing mobile terminal changes:
cd mobile
pnpm exec tsc --noEmit
pnpm run check:tests-typecheck
pnpm lint
cd ..
pnpm typecheck:node
tsc --noEmit reads tsconfig.json, which excludes test files so Metro never bundles them.
tsconfig.test.json puts them back, and pnpm run typecheck:tests shows their errors in full.
check:tests-typecheck is the gate over it: a ratchet against tests-typecheck-baseline.txt, the
127 test files that do not typecheck yet. It fails when a file that checks today stops checking,
and when a baseline entry starts checking (prune it with
node scripts/check-tests-typecheck-ratchet.mjs --prune). The list may only shrink.
The same gate censuses the program first: every *.test.ts(x) on disk must be in it, or named in
the script's TESTS_OUTSIDE_PROGRAM with a reason. Without that, a test excluded from
tsconfig.test.json — or a Foo.test.tsx shadowed by a Foo.test.ts beside it, which a wildcard
include drops for the higher-priority extension — would leave the ratchet silently.
Localization
UI copy goes through src/i18n, with the same call shape and languages as desktop:
- In components and hooks:
const t = useMobileTranslation(), thent('area.thing.label', 'English text'). The function changes with the language, so list it in memo and callback dependencies. - In helpers and imperative code (alerts, notifications):
translate(key, fallback, options)fromsrc/i18n/mobile-i18n, called when the text is shown, never at module scope. - Counts:
count === 1 ? t('x.files_one', '{{count}} file', { count }) : t('x.files_other', '{{count}} files', { count }). - Dates and numbers: pass
getUiIntlLocale()toIntlformatters instead ofundefined. - Keep identity separate from display text: never compare or key on a translated string.
Run pnpm sync:mobile-localization from the repo root to add new keys to src/i18n/locales/en.json;
other catalogs may lag and fall back to English. pnpm verify:mobile-localization and
pnpm verify:mobile-localization-coverage run in CI. iOS permission prompts live in locales/<lang>.json.
Android Release Signing
plugins/android-release-signing.js adds a release signing config to the generated
android/app/build.gradle. It reads ORCA_ANDROID_KEYSTORE_PATH, ORCA_ANDROID_KEYSTORE_PASSWORD,
ORCA_ANDROID_KEY_ALIAS and ORCA_ANDROID_KEY_PASSWORD at build time; nothing is written into the
project. Without them, local release builds keep Expo's debug key.
.github/workflows/mobile-android-release.yml turns release signing on once the
ORCA_ANDROID_RELEASE_CERT_SHA256 repository variable (or ORCA_ANDROID_REQUIRE_RELEASE_SIGNING=true)
is set. Until then it signs with the debug key as before and adds a warning to the run. Once it is
on, the workflow fails before building if any of these is missing:
| Name | Kind | Value |
|---|---|---|
ORCA_ANDROID_KEYSTORE_BASE64 |
secret | the release keystore, base64-encoded |
ORCA_ANDROID_KEYSTORE_PASSWORD |
secret | keystore password |
ORCA_ANDROID_KEY_ALIAS |
secret | key alias |
ORCA_ANDROID_KEY_PASSWORD |
secret | key password (same as the keystore password for PKCS12) |
ORCA_ANDROID_RELEASE_CERT_SHA256 |
variable | the key's certificate SHA-256 fingerprint |
After a release-signed build, the workflow checks that the APK's signing certificate matches
ORCA_ANDROID_RELEASE_CERT_SHA256 and is not the debug key, and publishes the fingerprint in the
release notes. Android only installs an update signed by the same key as the installed app, so
the keystore must be backed up: losing it means no existing install can be updated in place.
Protocol Version Compatibility
Mobile and desktop talk over a versioned protocol. Because mobile updates lag desktop by 24-48h via the App Store, both sides exchange version numbers on status.get so a genuinely incompatible combo can hard-block instead of silently misbehaving.
Constants live in two files (Metro can't resolve outside mobile/):
src/shared/protocol-version.ts—DESKTOP_PROTOCOL_VERSION,MIN_COMPATIBLE_MOBILE_VERSIONmobile/src/transport/connection/protocol-version.ts—MOBILE_PROTOCOL_VERSION,MIN_COMPATIBLE_DESKTOP_VERSION
Today all four are set so evaluateCompat always returns { kind: 'ok' } — nothing blocks. The wire format is in place to flip a switch when needed.
When to bump
Bump DESKTOP_PROTOCOL_VERSION (and the mobile mirror MOBILE_PROTOCOL_VERSION when relevant) for breaking changes:
- Removed RPC method or required parameter that mobile uses
- Changed meaning (units, nullability) of an existing field mobile reads
- Changed encryption, framing, or auth handshake
Do not bump for additive changes:
- New RPC methods
- New optional fields on existing methods
- New event types in
terminal.subscribe
Set MIN_COMPATIBLE_MOBILE_VERSION (kill-switch) when desktop ships a change that requires a minimum mobile version to function safely. Same for MIN_COMPATIBLE_DESKTOP_VERSION from the mobile side.
When a verdict is blocked, mobile/src/components/host-connection/ProtocolBlockScreen.tsx renders a screen pointing the user at the update that clears it. When mobile is too old it opens the newest release if the installed app's update check knows one, otherwise the App Store (iOS) or GitHub Releases (Android). When desktop is too old it opens GitHub Releases.
To exercise the block screen locally: set MIN_COMPATIBLE_DESKTOP_VERSION = 999 in mobile/src/transport/connection/protocol-version.ts, rebuild, pair to any desktop. Revert before merging.
Mock Server
Develop the mobile app without a running Orca desktop instance:
pnpm mock-server # starts mock WebSocket server on port 6768
Connect from the app using endpoint ws://localhost:6768 and token mock-device-token.
Environment variables
MOCK_NATIVE_CHAT=1— serve the native-chat scenario (one live agent tab, empty transcript, image upload) instead of the default terminal fixtures.MOCK_FORKED_CHATS=1— serve one workspace whose native chats include a fork, a fork of a fork, an unnamed fork and an older-build… forkname, across chat tabs, agent rows, Session History and the naming feed (for the fork mark).MOCK_CHAT_AGENT=omp— withMOCK_NATIVE_CHAT=1, present an OMP tab and four decoded transcript messages, including a tool call and result, instead of the default Claude scenario. It deliberately omitstranscriptPathto exercise legacy-hook readability discovery; current OMP hooks may report a path.MOCK_SERVER_KEY_FILE— persist the server keypair across restarts so a paired device keeps its public-key pin. A missing or invalid file is re-keyed with a warning, which forces a re-pair.
Scenario control files
Read on every request, so behaviour can be flipped mid-session without a restart (a restart would re-key E2EE and force a re-pair). Write the mode into the file, or delete it for the default.
MOCK_SEND_MODE_FILE(defaultorca-mock-send-modein the system temporary directory) —accept(default) accepts the send,errorfails it withmobile_input_floor_unavailable, anything else reports the send as rejected.MOCK_TERMINAL_LIST_MODE_FILE(defaultorca-mock-terminal-list-modein the system temporary directory) —omitreturns an empty terminal list,otherreturns a list that omits the chat handle, anything else lists it.MOCK_TERMINAL_STREAM_MODE_FILE(defaultorca-mock-terminal-stream-modein the system temporary directory) —deadanswers a subscribe withsubscribedthenend(a gone PTY), which is what exercises the rearm bound and terminal prune; anything else streams normally.
Connecting to Real Orca
- Start Orca desktop with WebSocket transport enabled
- In Orca, go to Settings > Mobile and scan the QR code with this app
- The QR encodes the connection endpoint, device token, and TLS fingerprint
Project Structure
mobile/
├── app/ # Expo Router screens (file-based routing)
│ ├── _layout.tsx # Root layout with navigation stack
│ ├── index.tsx # Home screen — paired hosts list
│ └── pair-scan.tsx # QR code scanning screen
├── src/
│ ├── terminal/ # Terminal WebView and xterm bridge
│ └── transport/ # WebSocket RPC client
├── scripts/
│ ├── test-subscribe.ts # Desktop streaming repro without a phone
│ └── mock-server.ts # Standalone mock WebSocket server
└── assets/ # App icons and splash screen