mirror of
https://github.com/stablyai/orca.git
synced 2026-09-22 08:02:28 +00:00
Jinwoo Hong
2dfdbc8657
* test(mobile): record main's task provider item, detail and board RPC behaviour 35 scenarios over 22 of the 25 files left in src/tasks/, recorded from main so the step-4 migration of the provider half has a frozen answer to compare against. Every one of the 70 references this branch will migrate reaches a recorded wire here, which is the check the workspace-creation half added after it lost three sites to fixtures that short-circuited before the call. Scenario params are observed, not written: a generator drove each adapter with nothing answered, read the projected sender calls back, and emitted the completion steps from them, so no `params` in the manifest is a guess about what the screen sends. Five adapter modules, split the way the screens are: one item's reads, the list and composer, the item mutations, the board's reads and the board's row mutations. `mountModelHook` holds the mount/dispatch/project boilerplate these twenty-two hooks share, so each adapter is only its fixture, its actions and its projection. Two fixture modules hold the task items and the project rows, shared so the same pull request looks the same to the comment hook, the merge hook and the checks hook — which is what makes their recordings comparable. `baseline` moves from50e752fc66(#20562) tofc525c355d(#20568), the commit this records from. The pinned baseline had drifted from main again when the workspace-creation half landed, and recording refuses to run against a tree that does not match it. This is main's product source, not the branch's: no product file changes in this commit. The 208 existing goldens change header-only — `baseline` and `recorderSha256`, the latter because any adapter is inside the recorder digest. Verified field by field: nothing else moved on any of the 208. Goldens: 208 -> 317, 3.8M -> 7.7M. 74 new matrix sites over 35 new families. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * refactor(mobile): send the task provider, detail and board domains through typed RpcOperations 22 of src/tasks/'s 25 remaining raw-port files now send through a declared operation instead of the raw request port: 70 references to 0, leaving 3 files and 3 references. No golden moved — `git show --stat` on this commit touches nothing under mobile/rpc-foundation/, which is the parity claim, and the 317 goldens recorded in the previous commit all pass against this tree. 56 operations over 58 methods, in five modules named for what they send: one item's detail reads, the list's provider loads, item comments and replies, item state/merge/check writes, and the GitHub Projects board. Five more operations are reused from the workspace-creation half rather than redeclared, because the list asks github.listWorkItems, gitlab.listWorkItems, linear.searchIssues, linear.listIssues and settings.update with the same acceptance the Smart picker does. Three methods carry two policies each, and all three pairs are named. `linear.status`: task hydration cannot list without the workspace and surfaces the host's message, the home probe degrades to "not connected". `linear.listTeams`: hydration reconciles a saved selection and needs it, the composer's picker just empties. `github.repoSlug`: the Projects board must tell "no slug" from "the ask failed" and caches the failure for retry, the paste lookup caches a refusal as "no slug" and carries on. Each pair shares one reader, so no method has two. No new acceptance policy. Ten sites picked a method with a ternary. Nine were a literal pair — a provider or an item type choosing between two methods — and each now selects between two operations instead, which also types each arm's params separately. Two of those were listed as unmigratable `{ method, params }` multiplexers: `use-mobile-tasks-project-file-merge-actions.tsx` and `use-mobile-tasks-hosted-metadata-actions.tsx` both assign `method` and `params` from local ternaries over `item.source.type` in the same function, not from a step a picker hands them, so both migrated and both reach zero. The Linear detail barrier keeps raw requests inside its `Promise.all`. main's group rejects as soon as one leg's transport does, and interpreting only after both settled is what lets the comments rejection win over the issue refusal — the b3 seed. `startRpcOperation` would wait for the slower peer. Every loading hook's `stale` or generation guard stays where it was, between the request and the state commit. Two preserved oddities, both recorded rather than repaired: - `gitlab.todos` keeps its payload spelled `response.result`. A reply that is neither an array nor nullish crashes in `.map`, and the message the screen shows is that expression's source text; renaming the local moved a golden, which is how this was found. - `github.listWorkItems` keeps sending `before`. The list's pagination cursor is not in that method's params schema, so the host has always dropped it and mobile's GitHub "load more" re-asks for the same page. Sent verbatim with a cast; making the host honour the cursor is a product fix with its own recording. Worth a ticket. `github-project-host-routing-source.test.ts` pinned method literals that have moved into the operation modules. It now pins the same guarantee in two halves — the board site carries the host or the row's `prRepo`, and the named operation still sends that method — so neither half can drift alone. The board's issue/PR update repeats its params rather than hoisting them, so each send textually carries its own host, which is what that test reads. The Mobile Tasks source-parity hashes move for the same reason the workspace half's did. The diff is evidence rather than a re-pin: `semantics` is a pure deletion, 148 lines out and none in — 70 `rpc:` call signatures, 75 method literals over 58 methods, and three duplicated `item.source.type` comparisons that only existed because one `sendRequest` had to pick both a method and a matching params shape from the same test. Statement, declaration, render and style counts are unchanged, and the render, declaration and style hashes are byte-identical. `b3: kills order` fails at this commit and only this commit. Its anchor names the send this migration rewrote, so it matches zero sites; the next commit rehomes it at the same defect and re-digests. Every other test passes. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): rehome the b3 barrier mutant and name the recorder's fixture cast The `order` mutant anchors the defect that the b3 seed exists to record: interpreting the issue leg inside the request chain instead of at the barrier, so the group rejects early and the sibling comment request is abandoned out of order. Its anchor named `client.sendRequest( 'linear.issueComments'`, which the previous commit rewrote, so it matched zero sites. Rehomed at the same defect in its new shape — a `.then` that interprets inside the chain — per the recording README, rather than deleted. It still kills, and for the same reason: the recorded error becomes the issue refusal instead of the comments transport drop. The adapters also stop casting per action. Sixty-five `as never` casts became one named `mountFixture`, which says once why these fixtures are deliberately partial: they carry only the members the mounted hook reads, and completing them into full domain objects would invent data no scenario observes. `check:code-quality:changed` is clean on all 39 changed files. Both edits are inside `recorderSha256`, so all 317 goldens carry a new digest and nothing else — verified field by field, `recorderSha256` is the only key that moved on any of them, and no golden was added or removed. Recorded from the pinned baselinefc525c355din a separate worktree with this branch's recorder laid over it, so the goldens stay attributable to main's product source rather than to the migration. The suite is green here with the migrated source, which is what makes the previous commit's "no golden moved" claim mean something. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): record a Linear detail whose issue leg is answered The acceptance census found one operation whose declared policy no golden observed: swapping `linear.issueComments` from skip-on-refusal to throw-on-refusal survived every test. The reason is the b3 seed. Its scenario refuses `linear.getIssue`, and the detail hook interprets the issue leg first, so the issue error is raised before the comment leg's policy is consulted — and the reply matrix drives one site per golden against the base scenario's other replies, so every partition at `linear.issueComments` still had a refused issue beside it. The comment leg's acceptance was unreachable, not merely untested. `tasks.item-detail-linear` mounts the same hook with the issue answered. Its matrix drives both legs with the other one fulfilled, which is what makes "a refused comment list leaves the sheet with no comments" an observation rather than a claim. The policy swap now kills it on two goldens. b3 is untouched: it still pins the defect it was written for. Goldens: three added, and the other 317 carry a new `recorderSha256` because the adapter gained a registration. Nothing else moved on any of them. Recorded from the pinned baselinefc525c355dwith this branch's recorder, as before. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): re-pin the two task parity hashes the import-form fix moved The migration commit pinned the hook and statement hashes before `oxlint` asked five task files to write `import type { X }` rather than `import { type X }`. Both readers walk import statements, so both hashes moved; the fix landed after the hashes and the suite was left red. Nothing observable changed. Hook, statement, declaration, render and style counts are all unchanged, and the declaration, render, style and `semantics` hashes are byte-identical — `semantics` is still the same pure 148-line deletion against main. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * docs(mobile): name the real second consumer and the real reason for deferred interpretation Two comments from the migration described code that does not exist. The `linear.status` note credited the skip policy to the home screen. The home screen does send `linear.status`, but through an unmigrated single-flight request in mobile-home-host-requests.ts, so it is not the other policy at all. The only consumer of `taskLinearStatusRead` is the Tasks runtime hydration hook, which is what actually treats an unanswered probe as "not connected". Naming the wrong caller makes the two-policy claim unverifiable for the next reader. The Linear detail group said "raw requests inside the group" while the code calls `linearIssueRead.request`. The requests are operations; what stays inside the group is the deferred interpretation. The reason is unchanged and still the point: this `Promise.all` rejects as soon as one leg's transport does, and interpreting only after both settled is what keeps the issue error winning over the comments error. Comment-only, so no golden and no recorder file moves. The two parity hashes do move, because `normalized()` captures a statement's full text and these comments sit inside the effect callbacks it captures; both element counts are unchanged at 350 and 417, which is what shows nothing structural shifted. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): move the task provider adapters into the per-golden adapter seam #20662 pins each golden to the one adapter module it was recorded through, and pins the engine directory to every golden. This branch's adapters sat in the engine directory, so leaving them there would have re-digested all 208 goldens main already has. They move into `adapters/` and register themselves, and the engine directory is now byte-identical to main's: `recorderSha256` computes to 2e90933db32e, which is the value main's goldens already pin. The seam forbids an adapter importing another file in the directory, and the register test requires every file there to be a registered module, so the shared fixtures and the shared mount helper could not follow the adapters in. Each module now carries the fixtures it actually mounts and its own copy of `mountModelHook`, which is how main's nine modules are already written. That is real duplication, about 55 lines of helper per module, and it is the price of a golden naming one file as its provenance. Five modules became eleven for the same reason: a self-contained module carrying its own fixtures crosses 300 lines, so each split at a hook boundary rather than taking a `max-lines` bump. One behaviour note. `task-mount-adapters.ts` mounts `use-mobile-tasks-item-detail-loading.tsx` for its own family, and this branch mounts the same hook for three more. With a loader per module, both modules' loaders applied the `order` mutant anchored in that file and `assertMutationApplied` saw two applications where it requires one. Deferring this module's load to mount time fixes it, and matches how `task-mount-adapters.ts` already loads it. The general hazard is worth an engine guard and is reported separately: any future module that eagerly loads a mutant-anchored file breaks that count, and nothing fails until someone runs the mutants. Goldens are untouched here. They still carry the pre-merge header and the re-record is the last commit in this sequence. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): type the recorder's fixture helper as a checked subset of what it stands in for `mountFixture<T>(value: unknown): T` accepted anything, which is what let three fixtures record a value the product cannot produce. It now takes `PartialRecorderFixture<NoInfer<T>>`: every member optional at every depth, but no member the real type lacks and none with the wrong type. `NoInfer` is what makes the parameter's type the target rather than the fixture's own. The type lives outside `rpc-recording/` because every golden pins that directory and the helper is copied per adapter module. A type cannot change a recording, so keeping it out is what stops eleven copies of a recursive conditional type from existing. Two deliberate allowances, both stated in the type. Functions pass through whole, since a stub with optional parameters is one the hook cannot call. And a member may be `null` where the product type says only optional, because these fixtures stand in for JSON the host sent and JSON spells an absent object `null`; four Linear fixtures rely on that, and rewriting them to `undefined` would move them away from what a host sends rather than towards it. The two `mountFixture(model.client)` calls become `context.client`, which is typed `RpcClient` and needs no cast at all. The model holds that same object under an `unknown` fixture record, and `observableModel` returns it unwrapped, so this is the same client read from the side that knows its type. No fixture value changes here, so this moves nothing a golden records. The three divergences the signature exposes are the next commit. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): fix the three fixtures that recorded values the product cannot produce Each of these was caught by the checked `mountFixture` signature in the previous commit, and each made a golden record a path no user can reach. Fixture changes, so the goldens they drive move at the re-record, and each moved golden is a claim listed there. The single-select field mutation sent `{ singleSelectOptionId: 'option-1' }`, which is not a member of `GitHubProjectFieldMutationValue`. `optimisticProjectFieldValue` fell through to the text fallback, so the golden recorded `{kind: 'text', text: ''}` for a SINGLE_SELECT field and the single-select branch was never exercised. The value is now `{kind: 'single-select', optionId: 'option-1'}`. That alone was not enough: the branch also tests `field.kind`, and `STATUS_FIELD` carried only `dataType`, so `kind` was undefined and the fallback still won. The field now carries its discriminant, and the option it selects is present in `options`, because a board that loaded a single-select field has its options and an empty list contradicts a user picking one. Without it the optimistic value would record the not-found `'Selected'` / `'GRAY'` fallback instead of the option's own name and colour. `ownerType` was `'ORGANIZATION'` against `'organization' | 'user'`. The value reaches wire params unchanged, so no branch was skipped, but six goldens pinned an owner type the product cannot send, and `githubProjectIdentityKey` interpolates that field without normalising it while it does lowercase `owner` and `host` — so the recorded settings key was one the product cannot produce either. The same file already spelled it `'organization'` in one of three places, which is how it went unnoticed. The issue-type fixture was missing `color` and `description`, both of which `GitHubIssueType` requires and neither of which is optional. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): move the fixture-shape type inside the recorder, where recording can see it `mobile/scripts/rpc-recording.mts` fences `mobile/src` against the pinned baseline and exempts only `mobile/src/test-support/rpc-recording`, by tracked diff and by an untracked-file check. A type file one directory up therefore fails recording outright as an unpinned product source, which is not a judgement about the type, just where the fence is drawn. So it lives in the engine directory. That has a cost worth naming: `recorderSha256` covers the engine, so all 208 goldens this branch shares with main now carry a new digest. That is the one thing #20662 removed and this is the case it cannot remove — a genuinely shared recorder input has nowhere to go that is both inside the fence and outside the whole-directory digest. `adapters/` is not available: its seam test requires every file there to be a registered module, and forbids one module importing another. The alternative was a copy of the type in each of eleven modules, which would also have forced a twelfth split, since the conversation module is already at 295 of its 300 lines. One shared type and one re-digest is the cheaper trade, and the re-digest is a single header line per golden with no recorded value moving. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): re-record every golden from the pinned baseline with the merged recorder Recorded fromc6a7216984in a detached worktree with this branch's recorder laid over it, per the README's migration-branch procedure, because this branch's product tree is migrated and recording in place would make the parity claim circular. Two adapter loads became lazy first, and that was not cosmetic. `golden-header-digest.test.ts` builds a temp tree holding only the product files one family needs, then calls `adapterSourceByOperation`, which invokes every registered module's `mounts`. Eight of this branch's factory functions loaded their hook while the table was being built, so they tried to read files that tree does not have and five engine tests failed. The same eager load made `assertMutationApplied` count two applications for the two mutants whose anchor file another module also mounts. Every factory now loads inside the mount, which is how main's modules were already written. Header movement, all 208 goldens this branch shares with main: `recorderSha256` only, from 2e90933db32e to 202244bdc6c5. Zero non-header lines. The cause is one added engine file, the fixture-shape type, explained in its own commit. Ten goldens moved beyond the header, all in the two families whose fixtures were corrected, and no family outside them moved: tk-project-row-fields and its updateitemfield, clearitemfield and updateissuetypebyslug matrices send `value: {kind, optionId}` where they sent `{singleSelectOptionId}`, which the host's `graphqlValueForFieldMutation` would have rejected as an unknown kind, and now record a single-select field value where they recorded the text fallback. The field carries its `kind` discriminant and its option, so the recorded value carries the option's name and colour. The issue-type row gains `color` and `description`, both required and neither on the wire. tk-project-board-load and its listaccessible, listviews, viewtable and resolveref matrices spell `ownerType` `organization`. The host derives that value from GraphQL `__typename` and only ever lowercases it, so the uppercase form was unreachable in both the reply and the params. `baseline` also moves on this branch's own goldens, fromfc525c355dto main'sc6a7216984, which the merge commit explains. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): pin Project host routing to the declared method, not the identifier prefix The guard matched `githubProject*.request(` sites, so an operation renamed off that prefix left the prefix match empty and the host could go with the rename: renaming `githubProjectFieldUpdate` to `projectFieldUpdate` at its definition and its one call site and deleting `host: activeGitHubProjectHost` from the `github.project.updateItemField` request kept all three tests and `tsc` green, and `host` is optional in the params type so nothing else caught it. Derive the list from the board module by the method each operation declares instead, and scan every product file under `mobile/src` rather than a hand-listed eight, so a site that moves stays covered. Coverage goes from 13 matched sites to 17 across all 16 declared operations, because the old regex also missed the `op\n .request(` form four of them use. An operation that stops being requested at all now fails too. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): share the recorder's fixture helper instead of copying it into eight adapters The seam forbids one adapter importing another, not an adapter importing the engine, and the adapters already take `hookMount` and `observableModel` from there. So the eight byte-identical copies of `mountFixture` bought nothing: eight doc comments and eight cast suppressions for one four-line function that has no per-domain part. Export it from `recorder-fixture-shape.ts`, next to the type it checks against, and leave one suppression instead of nine. `adapter-seam.test.ts` 7/7 and `pnpm --dir mobile typecheck` stay clean. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): fence what the recorder fixture shape accepts, and drop the one branch that is dead Review read the function branch and the `ReadonlySet | ReadonlyMap | Date` branch as dead because typecheck stays at zero without them. Zero was the wrong oracle: no fixture in the tree carries a callback, a set or a map, so nothing exercised them. Dropping both lets a `3` stand in for a callback the mounted hook will invoke, and lets `{}` stand in for a set. So pin them instead of asserting them. `recorder-fixture-shape-compile-fence.ts` is a non-test file, which is the only kind `pnpm --dir mobile typecheck` covers, and each case fails as an unused `@ts-expect-error` if the branch it stands on is removed: the callback case on the function branch, the set and map cases on the second branch, and the accepted case on `| null`, whose removal is 3 errors in the adapters. `Date` really was dead and is gone: its members are all methods, so the function branch already refuses a structural stand-in for it, and the fence keeps that honest. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): fail an adapter that loads product source while its table is built Nothing caught a `modules.load` hoisted out of `useHook` into the table literal, and the two things it breaks both report as engine faults far from the edit: a mutant anchored in a file two families share gets applied twice and `assertMutationApplied` reports the wrong count, and `golden-header-digest.test.ts` builds tables in a tree holding one family's files and throws `Module not found` for every other family. This PR hit both while splitting the task adapters. Build every registered module's table with a loader whose `load` throws, and assert none did. Hoisting the `use-mobile-tasks-item-detail-loading` load in `task-item-detail-mount-adapters.ts` fails it by name; `adapter-seam.test.ts` builds the same tables with a real loader and stays green, which is why it never saw this. The suite records nothing, so `recorderSha256` excludes it and no golden moves. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): keep the fixture-shape fence in the file it fences, not beside it A compile fence as its own file is an orphan the seam already rejects: `recorderSha256` pins every file in the recorder directory, and `mutant-seam.test.ts` requires each pinned file to be reachable from a recording driver, because anything pinned and unreachable re-digests all 320 goldens while being unable to move one. The separate file failed that check by name. Fold the cases into `recorder-fixture-shape.ts`, which the adapters already import, and drop the directory literal from the comment so the seam's name scan stays clean. Removing a branch still fails: function branch 2 errors, set-and-map branch 2, `| null` 4. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): re-record every golden for the shared fixture helper Recorded from the pinned baselinec6a7216984with this branch's recorder laid over it, per the README's migration-branch procedure. Two header fields move and nothing else does: `recorderSha256` on all 320, because the engine now carries `mountFixture` and the cases that fence its type, and `adapterSha256` on the 93 goldens recorded through the eight adapters that gave that helper up. Non-header lines changed: 0. The candidate suite is 387 passed, 3 skipped. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb * test(mobile): re-record every golden after merging main's recorder Recorded from the pinned baselinec6a7216984with the merged recorder laid over it, per the README's migration-branch procedure. One header field moves on all 453 goldens and nothing else does: `recorderSha256`, because this branch adds `recorder-fixture-shape.ts` to the engine that main's copy does not have. `adapterSha256` holds everywhere, since no adapter changed in the merge. Non-header lines changed: 0. The candidate suite is 523 passed, 3 skipped. Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb
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.
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 exec expo run:android
pnpm exec expo run:ios
pnpm start --dev-client
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 lint
cd ..
pnpm typecheck:node
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 either the App Store (mobile too old) or GitHub Releases (desktop too old).
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