mirror of
https://github.com/stablyai/orca.git
synced 2026-11-13 17:37:40 +00:00
Brennan Benson
a56e6de883
* Keep opened GitHub work items bound to their exact repository
* Bind GitHub work item ownership through consumers and dispatch
* Keep empty mention lists from consuming selection keys
* Preserve GitHub action and consumer ownership across resource changes
* Exercise repository account updates through their production store action
* Exercise account publication and cache settlement through GitHub consumers
* Simplify fork PR contract verification
* Make contract verification imports and clocks deterministic
* Correct mobile task test fixtures and model types
* Correct task recording fixtures and CI types
* Correct task fixture types and static checks
* Consolidate replay test RPC imports
* Separate GitHub metadata imports from Linear hooks
* Scope mobile PR sidebar reads to the selected resource
* Separate desktop GitHub changes from phone updates
* Preserve complete phone GitHub repository identity updates
* Fix relay authority probe census across topology cases
* Repair repository owner proof fixtures and compiler allocation
* Preserve repository row observation in host lookup
* Seed metadata fixture before server-side store acquisition
* Preserve nullable fixture settings and discover mixed test types
* Refetch phone reviewer list after a connection change
A disconnect or session change while the reviewer list loaded left the drawer showing an empty list until it was reopened. The drawer now shows its loading state while disconnected and fetches the same repository again once connected, still ignoring the cancelled load's result. Also merges a duplicate type import that failed mobile lint.
* Keep phone reviewer rows through connection changes
The reviewer picker now owns one query per open visit of a client, worktree and repository. A connection or session change retires the in-flight request at once but keeps the people already loaded; reconnecting refreshes them in the background. Without loaded people the drawer shows its spinner, or the existing connection explanation once an outage is revealed, and never a false empty list. Closing, retargeting or reopening starts a fresh visit that no earlier reply can paint. Also wraps the synchronous bridge teardown steps so the cleanup loop awaits only promises.
* Keep the viewed phone PR through connection changes
A relay/direct switch or reconnect selected a fresh, hidden PR observation in Source Control and Diff Review, so the next render unmounted the PR, closed the reviewer picker and erased an unsent comment. The PR observation is now scoped to the client, worktree and branch. One connection listener retires the in-flight reads when the connection changes and repeats the query the screen already asked for once connected, so accepted content stays mounted and refreshes in place. A failed background refresh keeps the accepted result. Task PR files likewise keep their loaded contents and expansion across a connection loss and read an interrupted file again on reconnect.
* Show a failed PR refresh over kept content; recover task files on every connection change
A failed refresh of an accepted PR (or no-PR) result now keeps the content and shows the existing "Failed to refresh pull request." line with Retry above it, whoever started the read, until the next good read. Task PR file reads are retired and re-read from the task selection's own connection listener, so a reconnect batched into one render or a connection switch at the same state also recovers an interrupted file. The reviewer-picker contract test leaves the React Native test program for now; its checked owner follows.
* Typecheck the phone/host contract tests through emitted declarations
The reviewer-picker contract test and the recorded request params test import real desktop sources, which do not typecheck under the phone's React Native libraries. Both source graphs now emit declarations under their own compiler settings, and a strict Node program checks the two test bodies against them; Vitest still runs them against the original sources through path aliases. The tests typecheck ratchet runs this program and fails unless both bodies are in it and it passes, the CI test runner checks that Bun ran and passed both, and the Mobile workflow finishes compiler work before starting tests. The six other excluded tests stay runtime-only and are labelled that way.
* Name the types phone declaration emission needs
Declaration emission for the phone/host contract program could not name the i18n instance's type or the buffered terminal draft send type; annotate the one and export the other. Also types the drawer mock's children in the Source Control scenario so the React Native test program checks it.
* Stub every icon in the Source Control scenario
Source Control modules read icons at import time, so the scenario's fixed icon list failed to load the file under Bun.
* Give the recorded params check's stand-in method a permission
The recorded request params test is now typechecked and its stand-in method lacked the permission every RPC method declares; parsing never reads it.
* Use the real composer styles in the Source Control scenario
Source Control's list styles read composer style constants at import time, so stubbing that module failed the file under Bun.
* Mock the PR sidebar hooks without loading their native modules
Only the PR sidebar reads these hooks, so the Source Control scenario's mocks need not load the real modules, whose imports reach Expo native code that does not run under Vitest.
* Count recording-internal observations apart from recorded ordinals
The scripted transport runs the real request tracker, and its connection wait, id allocation, completion, late-reply and terminal observations each took the shared write ordinal that requests, frames and effects record. Every recording's ordinals shifted although the same frames went out in the same order. Those observations now use their own counter, keeping their association with the native request, so recorded ordinals match the existing recordings again.
* Record a cleanup checkpoint only when teardown adds effects
Comparing the whole snapshot before and after teardown added a cleanup checkpoint whenever a pending request settled at dispose, which changed about 166 recordings without new evidence. Restore the condition the recordings were made with: teardown effects alone add the checkpoint.
* Run the bridged recording corpus on Node
Its goldens hold V8's TypeError wording, which the Bun pass reports differently, so ten exact error comparisons failed only on engine text. It now runs with family-recordings on Node; the comparison stays exact.
* Bind the probe test's fresh status.get by its actual child
* Edit the GitLab status scenario's GitHub issue only after opening it
* Type the Source Control scenario's composer adapters with the real component props
* Mock the Source Control scenario's icons and protocol gates without loading the real modules
* Give the PR sidebar probe test the shared typed fake client
* Select the GitLab status scenario's GitHub issue as a typed task item
* Declare the buffered terminal draft send as an exported type
* Run the Source Control scenario's focus effect only when its callback changes, as the router does
The router mock ran the loaders' focus effect after every commit, so each status read re-rendered and re-ran it. Also mock AppState for the comments section and stop act from awaiting held PR reloads.
* Re-record the GitHub and Tasks goldens for the selected-repository requests
Re-recorded with pnpm --dir mobile rpc:record for the 71 scenario IDs: 66 changed and 5 added for the exact-target status.get probe, 0 removed. The goldens now carry the selected repository on GitHub requests, the exact-target probe before GitHub operations, the skipped hidden metadata loads and the new item-detail failure copy.
* Declare the probed GitHub operations' params in the order the app sends them
The bridge probe test compares the forwarded frame byte for byte with the declared params, so tk-item-detail-github, tk-item-status-gitlab and tk-project-row-files-merge now declare the exact key order their goldens record. Values are unchanged, and completion matching ignores key order.
* Close the native connection before the page in recordings, and make late replies and inherited timers explicit
Recording teardown now closes the native client, flushes its rejection through the bridge, then closes the page, so page callers see the relayed native close. Sibling rejections name the stable logical site in every mode. Replies scripted after a timeout or disconnect are explicit late replies that must resolve nothing. Four product timers inherited from main are declared by producer, scenario, owner and delay and still reported; every other run keeps zero residual timers. The bridge probe oracle for tk-item-status-gitlab expects the published deadline failure and the exact retained issue.
* Judge unchanged bridged recordings as main does and changed ones by their own outcomes
Unchanged producers follow main's order again: identical earns identical, History keeps its strict path, and other divergences take a legacy label from the reply-meta counterfactual's typed evidence. A bounded guard pins zero unclassified, small-class membership and the branch-base tally less each named moved or removed producer; eight moved producers without a base pin are named as old-class-pending until their baseline replay. The re-recorded producers are judged directly in both page modes against their reviewed goldens, with only the page's refusal of the injected absent result applied, or by their exact strict own-undefined stop, and are pinned as bridge contracts. Bridge-only preludes are observed after their action, and the pending invocation's relayed native close is read from its own page promise. Every producer must be routed exactly once.
* Say what to do when the GitHub server check fails, and share one deadline with the action
The exact-target check runs before a GitHub action is sent, so a timeout or lost connection now shows the existing 'The Orca server connection changed. Try again.' and a refused or unreadable answer shows the existing 'Update Orca on the executing server' message, instead of raw text naming status.get. The check's own connection-changed error passes through. On native, the checks and the action share one 30-second budget, so a dead server fails in 30 seconds instead of 60.
* Pass the scenario manifest to the changed-producer comparison
* Correct the bridged corpus repairs from their first full run
The re-recorded producers no longer stop on the strict own-undefined matcher and all replay in bridge mode, so they are all judged directly; the page's refusal of the GitHub server check now expects the connection-changed copy. Unchanged legacy labels read their first difference from the replay without injected metadata. The sibling timeout and each interruption, including the cutover, end the requests the goldens record as ended, so those replies are explicit late replies. New producers in pinned families get their bridge-contract pins, and an unexpected timer or changed outcome now names its scenario and values.
* Restore six unchanged scenarios to their single own-undefined steps
tw-smart-search-all-providers, tw-smart-search-linear-listed, tk-list-gitlab-items, review-mark-reviewed-persists, review-mark-reviewed-rolls-back and session-create-terminal-without-active-tab had their own-undefined steps split into native and bridge copies, so the page replay no longer reached the strict own-undefined stop and these unchanged producers left their baseline labels. Their steps are the branch-base steps again; native recordings are unchanged.
* Fill the eight moved producers' base classes from the admitted baseline replay
pr-read-surface was identical and the seven github.pr-read matrices were result-absent-settlement at the branch base, so the unchanged tally is exact again with no pending members.
* Deliver the sibling disconnect's trailing replies as late replies too
A disconnect rejects preflight.check, linear.status and jira.status before the suffix replays their replies, exactly as the sibling timeout does, so those declared replies are late in both variants; the cutover stays strict.
* Expect the page's refusal in the two Linear producers' result-absent checkpoints
Natively the injected { ok: true } reads as an empty result, so the Linear detail and status update finish; the page refuses that frame and the screen shows the refusal instead. Each producer now has one finite expectation for that checkpoint, guarded on the reviewed golden's final effects, and everything else must still equal the golden.
* Share one deadline between the shell's server check and the GitHub action
The shell gave the exact-target check and the forwarded action each the page's full timeout unless the page asked otherwise, so a dead server took twice as long to fail on the hosted page as on native. The two legs now always share the page's one deadline; the forwarded options are unchanged.
* Deliver the sibling client cutover's trailing replies as late replies too
* Build the changed producers' page expectations from one finite table before comparing
* Re-record the three exact-target check goldens for the mapped copy
The GitHub check now shows the update-server or connection-changed copy instead of raw reply text; the item detail's empty-message cases now also record their detailError effect. Recorded on the admitted run (check-3949 Job 1).
* Declare the traced inherited timers per inner scenario and recording mode
Each declaration now names the modes where its inner scenario leaves the timer. Adds the inner scenarios traced in check-3949/qa-report-trace.md Job 2, with the ruled delays and owner chains: the reveal's 300 ms first-poll timer for all ten reply partitions of tabs.list-1 and tabs.activate-1 in both modes, and the pr-triage 20,000 ms reconnect waiter for transport-rejection and transport-rejection-no-message in both modes and result-absent through the page only. Exact counts, owners and delays stay enforced.
* Expect the compiler wait before Mobile verify's tests and only the fastlane tools after
* Call recorded timer callbacks through a typed signature
* Show the reviewer picker's no-rows wait with the screen header's connection verdict
The drawer classified only its client's state and counters, so during relay recovery it flipped between Disconnected and Connecting on every dial and never showed relay or pairing verdicts. The source control and diff review screens now pass the host's own verdict inputs (reconnect attempts, last connect, relay recovery status), re-read on host state and path changes, so the drawer shows the same steady verdict as the header.
* Say a timed-out GitHub target check timed out, on native and in the shell
A server check that ran out its own deadline on a connection that never changed now reads "Timed out confirming the executing Orca server.", as the shell's budget already did, and the native shared budget running out uses the same copy. A lost or changed connection still reads "The Orca server connection changed. Try again."
* Name the paired desktop when it is the build missing the exact-target check
When the phone's paired desktop relays to an updated executing server but lacks the exact-target capability itself, the edit now says "Update Orca desktop" instead of pointing at the executing server. An old executing server still gets the executing-server copy.
* Preserve GitHub detail argument types and optional capabilities
* Say what updating the paired desktop enables, as the executing-server copy does
* Drop the tab-reveal timer declarations now that main removed the reveal operation
* Let keyed details queries own pending read replacement
* Repair GitHub RPC and relay test fixture boundaries
* Own the new PR tab's caches, sheets, confirmations and polls by the complete PR
Fork #N and upstream #N were one owner to the tab: check details, open sheets and confirmations keyed by worktree and number survived a repository change, so a fork draft or decision could act on upstream and fork check data could show for upstream. Each is now owned by the PR incarnation (client, worktree, branch and full resource key), selected during render, so a departure closes old requests without retargeting them, A -> B -> A starts fresh, an outgoing sheet renders nothing and sends nothing, a late save closes only its own request, and a departed PR's poll neither blocks nor re-arms its successor.
* Load the reviewers sheet's people through the selected repository's resource-owned query
The new sheet read people once on the first search with no repository, connection recovery or retry, so a fork PR listed the wrong repository and a search while reconnecting stuck on an error. The first search of an open sheet now demands the selected repository's list through the exact-target helper; the query reads only while connected, retires its attempt on every real state or generation change, recovers on reconnect, keeps accepted rows and search through refreshes, and shows the header's own calm connection verdict while it has no candidates. Closing or a PR departure ends the visit; reopening starts fresh.
* Mark a failed PR discovery from every caller, polls included, and keep a poll's checks-only failure quiet
Main's poller made a failed background discovery silent, narrowing the ruled all-caller contract. Any current failed discovery over an accepted PR or no-PR result now keeps it and shows the one refresh-failed row with Retry, and the poll still backs off on 'failed'. A poll whose discovery succeeded but whose checks read failed for the same complete PR lands its discovery (clearing an older warning) and keeps the prior checks, reporting 'failed' once; equal numbers in another repository no longer count as the same PR. A viewed-file update from a departed observation changes nothing.
* Send the phone's addressed details reads with the server's read intent where it is advertised
github.workItemDetails accepts optional canonical:false (ordinary) / true (Refresh), advertised by github.exact-details-read-intent.v1; missing intent means ordinary. The phone's addressed details reads (PR tab and Tasks) now pass that intent through the existing exact-target preparation: a host advertising it gets canonical:false for ordinary loads, recovery and polls and canonical:true for the user's explicit Refresh; a canonical-only host gets ordinary reads without the owner and Refresh with the owner only; hosts with neither keep today's params, and an explicit Refresh there is refused as unsupported. Refresh intent travels only with the Refresh command, never as reconnect demand. The poll's checks-only settling moves into pr-sidebar-load-result to keep the controller within its size limit.
* Keep today's details params for a host with neither read-intent capability, Refresh included
* Drive the reviewer target contract through the new tab's reviewers sheet, first search included
* Cover a poll's discovery warning, its clearing, and a same-PR checks-only poll failure in the controller
* Prove the Source Control PR tab's demand, retained sheet and draft, failure line and fork/upstream request ownership on the new navigation
* Cover the details read intent the phone sends to explicit-intent, canonical-only and older hosts
* Fix the round's test typecheck and assertion findings: awaited controller loads, the diff review props, typed doubles
* Send Refresh's owner to a canonical-only server outside the exact-target check, as the desktop does
* Restore the base's mobile change-scope test, which the base merge dropped by mistake
* Prove the PR poller keeps each fork/upstream incarnation's poll, backoff and cadence its own
* Verify expected GitHub account at repository execution capture
* Give the Linear detail recording adapter the detail Refresh request its loader reads
* Keep the detail Refresh request ref out of the recorded owner projection, like the other ref
* Count cancelled GitHub probes against the desktop request cap main introduced
* Keep the comment tree out of the diff review controller test, as its drawers already are
* Restore the Source Control action icons the scenario rewrite dropped from its icon mock
* Supply the settled-list setter main added to the Tasks list fixture
* Preserve captured GitHub account expectations through client dispatch
* Re-record the Linear team-context goldens for this PR's actionItem owner effect
* Retain observed runtime status after switching environments
* Fix account contract fixture types and RPC setup timing
* Restore the negative-capability switch probe assertion
* Align account fixtures with runtime identity and configured origin
* Consolidate details test imports
* Type the reviewer test's search stand-in locally so native declarations stay out of its Node-checked program
* Add the PR tab Retry label's English entry the localization check requires
* Restore the PR tab Retry label's translations in the other mobile locales
* Pass the phone write reread through the reviewer contract.
The sheet fixture omitted the required reread, so the phone typecheck failed. Desktop settlement tests that main already removed were still on this branch and pulled telemetry into the web typecheck.
* Declare the phone pull request refresh failure.
The sidebar already shows this sentence when a refresh fails. The English catalog omitted it, and the boot bundle still carried two strings no startup call needs.
* Let the phone sidebar tests subscribe to connection state.
The sidebar records the client's connection before it loads a pull request. These tests drive that through the screen's connection prop, so the stand-in client only has to accept the subscription.
* Justify the phone sidebar test client.
The changed-code check rejects a new cast unless the line says why it is sound. These tests still only subscribe and read connection state.
* Name the repository on the phone sidebar details fixture.
A same-numbered pull request in another repository is not this one. The loaded body has to name the repository the test selected.
* Keep phone review-thread feedback on its accepted detail revision
* Capture phone review actions from the current render
* Align phone recording fixtures with the integrated detail loader
* Keep provider-switch detail fixtures addressed to the selected item
* Preserve same-turn bridge refusal evidence across client call shapes
* Publish phone detail revisions through one synchronous owner
* Type the queued publication regression with its provider contract
* Conform phone regression and relay types to static analysis
* Trim duplicate phone RPC tests and focus recorded observations
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.
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/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/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/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_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