The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Performance regression checks |
| 2 | |
| 3 | The v2 transport has a focused regression command: |
| 4 | |
| 5 | ```bash |
| 6 | vp run test:perf:v2-wire |
| 7 | ``` |
| 8 | |
| 9 | It exercises the real v2 projection and client reducers. This matters because the older |
| 10 | built-app benchmark fixtures seed v1 orchestration events; running those fixtures against a v2 |
| 11 | client can produce reassuring timings while missing the active transport path. |
| 12 | |
| 13 | The v2 checks pin these invariants: |
| 14 | |
| 15 | - Cold opens and history pages stop at about 1 MiB of encoded rows. A window that holds a user |
| 16 | turn also stops at 10 user turns (20 on older pages) or 500 rows, so ordinary turns stay whole. |
| 17 | Any other window, including the inside of one turn longer than 500 rows, stops at 75 rows. The |
| 18 | snapshot query applies the same rule before it decodes payloads. Clients can opt into deferring |
| 19 | large work groups until expansion. Messages and items outside those groups remain in normal |
| 20 | history paging. Required control records and |
| 21 | the at-least-one-row rule can exceed the byte target; it is not a hard cap. |
| 22 | - The bounded snapshot does not retain the full duplicate conversation-message table. Messages of |
| 23 | a run that is still in progress are the exception: all of them accompany the window. |
| 24 | - Older activity is fetched in bounded HTTP pages and merged without disturbing the live scroll |
| 25 | window. |
| 26 | - Clients with confirmed history paging opt into socket snapshot fallbacks that use the same |
| 27 | bounded recent-history window and carry the cursor needed to fetch older history. Older clients |
| 28 | and WebSocket-only starts retain the compatible full-snapshot fallback. |
| 29 | - Snapshot queries bound timeline reads per fork ancestor, not total rows: dependency and |
| 30 | control records still accompany the window. Smaller socket frames alone do not establish a |
| 31 | whole-server memory reduction. |
| 32 | - Resume catch-up checks the original 1 MiB persisted-payload budget before decoding, then |
| 33 | replays at most 128 thread events and 1 MiB of projected event JSON before falling back to a |
| 34 | snapshot. Raw JSON bytes are not a heap-memory cap. Raising this budget merely because output |
| 35 | projects small can increase server allocations on repeated large tool updates. |
| 36 | - Raw command output, dynamic-tool result bodies, and inline file-change bodies are omitted at |
| 37 | the wire boundary, including small outputs. Explicit failure flags and bounded result IDs |
| 38 | preserve status and grouped action counts without shipping those bodies. Reasoning text, |
| 39 | command lines, and search results ship when their work group loads. Subagent prompts and results |
| 40 | and checkpoint control records still accompany the initial window. |
| 41 | Persisted events remain complete; the existing diff endpoints still provide file content when |
| 42 | requested. |
| 43 | Explicit cross-environment transcript exports preserve full tool bodies so the destination |
| 44 | agent can read the context. The export rejects timeline JSON above the file attachment limit |
| 45 | before sending it, and before decoding any row when the tool output text alone is over that |
| 46 | limit; the client still applies its attachment limit to the complete file. |
| 47 | - Live command output reaches a client only through `orchestration.subscribeCommandOutput`, which |
| 48 | an expanded command row opens and closes with itself. Raw output deltas are never orchestration |
| 49 | events: adapters send them to the |
| 50 | [command output hub](../../apps/server/src/orchestration-v2/CommandOutputHub.ts) ahead of |
| 51 | ingestion, which keeps one bounded tail per running command and throttles each subscriber. Do not |
| 52 | route output deltas through `turn_item.updated`: a busy command would flood the event store and |
| 53 | block ingestion for every other thread. |
| 54 | - The initial shell contains active navigation rows only. Archived rows use the dedicated archive |
| 55 | query, and transcript message bodies stay in thread detail regardless of message size. |
| 56 | - Shell resume sends deltas plus compact repository-enrichment metadata, not another full project |
| 57 | and thread snapshot. A cursor at the head sequence always resumes, even below the pruned |
| 58 | boundary, so a client that just loaded the HTTP snapshot never downloads it again over the |
| 59 | socket. That client also names the snapshot's project identities, and a server whose |
| 60 | identities did not change since resends only the roots that resolved to no identity. |
| 61 | - Auto, steer, and restart sends resolve delivery from authoritative state inside the |
| 62 | server's per-thread dispatch lock. Model selection and identified-checkpoint rollback also |
| 63 | dispatch without first fetching a full thread projection when the server advertises support. |
| 64 | Older servers retain projection-based validation. Explicit start sends already skipped that |
| 65 | read, so this saving does not apply to every client send path. |
| 66 | |
| 67 | When changing projection schemas, paging, shell synchronization, or thread state, run this command |
| 68 | alongside the focused package typechecks and a real-client pass on every affected surface. The |
| 69 | transport performance fixtures validate contract encoding and compare pre-compression RPC JSON |
| 70 | for the same synthetic workload, preserving historical application-object counts separately. |
| 71 | These are neither compressed WebSocket captures nor measurements of server RSS, and command |
| 72 | fixtures exclude unrelated settings calls and subscription events. Payload budgets belong in |
| 73 | these tests so regressions fail locally. The transfer budget integration test |
| 74 | (`apps/server/integration/transferBudgetV2.integration.test.ts`) sends the opt-ins current clients |
| 75 | send. Its opt-in objects are typed `Required` against the contracts, so an opt-in added to a |
| 76 | contract fails typecheck until the test sends it; give a fixture the data the opt-in saves. The |
| 77 | test caps decoded bytes and rows for a 900-row agent turn in both states: while the turn runs (the |
| 78 | bounded snapshot and one older page) and after it finishes (the deferred cold open over HTTP and |
| 79 | over the socket alone, and the first page of its deferred work). It caps the socket bytes of three |
| 80 | resumes that must not send a snapshot: a thread after one ordinary turn, an idle thread, and a |
| 81 | shell cursor too old to replay. It caps the cold-connect shell for a sidebar of settled threads and |
| 82 | idle subagents, and the subscription a client opens from that snapshot with its project identities. |
| 83 | It caps both answers of the HTTP shell route to a client that holds rows and names their cursor: the |
| 84 | few bytes that keep them, and the snapshot that replaces rows too old to replay. It also caps the |
| 85 | bytes and |
| 86 | the node, subagent, plan, provider turn and checkpoint counts of the bounded snapshot for a thread |
| 87 | of 40 finished runs behind one working run, so finished runs cannot ride along with a window. The |
| 88 | working run has a ready context handoff, so its history cannot ride along either. |
| 89 | |
| 90 | CI prints every row in the job summary. The pull request comment compares the budgeted rows with |
| 91 | `main`, lists the rows that changed or failed, and names each ceiling a pull request raises. A row |
| 92 | added to `scenarioRows` in `TransferBudgetReport.integration.ts` reaches the pass/fail check, the |
| 93 | summary and the comment. |
| 94 | |
| 95 | The server config has its own budget in `apps/server/src/ws.test.ts`. A client that asks for |
| 96 | catalog digests and status deltas gets the provider list of its first config in under 1 KiB, for a |
| 97 | provider with 250 slash commands and 200 skills. The lists load with the first cwd snapshot, and a |
| 98 | machine refresh sends back an empty provider list. |
| 99 | |
| 100 | ## Event store and startup |
| 101 | |
| 102 | Sequence cursors must seek an index rather than scan retained history. The application sequence |
| 103 | index contains project events and v2 thread events; the per-thread sequence index contains only v2 |
| 104 | thread events. Legacy-only and unknown threads must return zero without scanning other threads. |
| 105 | Catch-up queries keep sequence ranges and optional thread or command predicates indexable. |
| 106 | |
| 107 | Startup selects recovery candidates from current projection state before reading full thread |
| 108 | projections. Candidate selection includes queued runs, pending runtime requests, live provider |
| 109 | sessions, background work, and unfinished delegated deliveries. Archived threads still participate |
| 110 | where recovery requires them. Completed thread history is not loaded merely to discover that no |
| 111 | work remains. |
| 112 | |
| 113 | Projection verification decodes canonical rows in bounded pages, including shared provider records |
| 114 | and fork ancestry. Rebuild replays event pages through a fixed sequence within its transaction; |
| 115 | it must not collect the entire event log before projecting it. |
| 116 | |
| 117 | The focused regression coverage lives in `OrchestrationEventStore.sequence.test.ts`, |
| 118 | `ProjectionRecovery.test.ts`, and the provider runtime recovery tests under `apps/server/src`. |
| 119 | |
| 120 | ## Background work and navigation |
| 121 | |
| 122 | The settlement worker reads active, unpinned threads without explicit settlement overrides from |
| 123 | `ProjectionStore.getSettlementCandidates`. It reads the latest run and user-message timestamps, |
| 124 | rejects active runs and pending requests, and checks background work using the same derivation as |
| 125 | the shell. It does not load archived histories, fork ancestry, transcript counts, or provider |
| 126 | sessions. The orchestrator still validates the current thread before applying settlement. |
| 127 | |
| 128 | Read receipts use `ProjectionStore.getThread` to load only canonical thread metadata. A visit |
| 129 | advances `lastVisitedAt` monotonically without changing `updatedAt` or decoding history. Shell |
| 130 | queries read item counts from a per-thread, per-run table that turn-item triggers keep exact, and |
| 131 | use a partial index for nonterminal background items, including idle items. Latest user-message |
| 132 | reads use an index ordered by update time. |
| 133 | |
| 134 | A projection read that orders messages by their first user or assistant turn item groups those |
| 135 | items by `$.messageId` through a partial index on that expression (migration 94), so it does not |
| 136 | parse every message item's payload; the index's expression and `WHERE` must stay identical to the |
| 137 | query's. Migration 94 scans the turn-item table once on first start; a message item whose payload |
| 138 | is not valid JSON is left out of the index. Each message-item write re-parses the old and new |
| 139 | payload for the index, so its cost grows with the payload. |
| 140 | |
| 141 | Command palette results keep live VCS and linked pull-request queries leased to the visible |
| 142 | viewport, including a small overscan region. Cached badges remain available while leases are |
| 143 | released. Local Git status reads skip divergence calculations; callers that need ahead/behind |
| 144 | counts keep the full status path. Cached fetch failures share the existing backoff and log only |
| 145 | the actual failed attempt. Unchanged desktop environment bootstrap reads retain their array |
| 146 | identity so polling does not invalidate subscribers. |
| 147 | |
| 148 | Local trace records and provider event logs use asynchronous, serialized file writes and rotation. |
| 149 | Batching synchronous appends still stalls the server event loop on slow storage, especially on |
| 150 | Windows. While a trace write is slow, producers keep up to one trace file of records, so the spans |
| 151 | that time a stall survive it; records drop only while the disk stays stuck. Provider logging |
| 152 | retains backpressure. Shutdown drains accepted writes before closing their scope. |
| 153 | |
| 154 | Relay awareness queues one pending publication per thread and retains a follow-up when the thread |
| 155 | changes during a send. Transcript deltas and tool output do not enqueue awareness work. Run, |
| 156 | request, and relevant thread metadata events do. Configuration is checked before shell reads, and |
| 157 | connection changes invalidate published identities so relinking can publish unchanged state. |
| 158 | Failed publications retry the latest state up to five times with exponential delays. A new |
| 159 | relevant event resets the budget; successful publication, disabling, or unlinking cancels retries. |
| 160 | After the budget is exhausted, publication waits for another relevant event instead of generating |
| 161 | continuous traffic during an outage. |
| 162 | |
| 163 | Focused coverage: `ProjectionSettlement.test.ts`, `ThreadSettlementService.test.ts`, |
| 164 | `runtimeLayer.test.ts`, `AgentAwarenessRelay.test.ts`, `GitVcsDriverCore.test.ts`, and |
| 165 | `desktopLocal.test.ts`. |
| 166 | |
| 167 | ## Mobile looping animations |
| 168 | |
| 169 | `apps/mobile/package.json` sets Reanimated's `DISABLE_COMMIT_PAUSING_MECHANISM` so keyboard avoiding |
| 170 | animates on iOS. Reanimated documents that flag as safe only alongside React Native's |
| 171 | `preventShadowTreeCommitExhaustion`, which defaults to off and needs React Native built from source, |
| 172 | so our builds run without it. Reanimated commits each animation frame to the shadow tree, and |
| 173 | without commit pausing those commits can starve React's: the JS thread keeps retrying its commit, |
| 174 | the screen freezes, and back does nothing. Release builds retry forever; dev builds abort with |
| 175 | `ShadowTree.cpp: assertion failed (attempts < 1024)`. Looping animations that stay on screen while |
| 176 | heavy content renders should use React Native's `Animated` with `useNativeDriver: true`, which |
| 177 | updates views without commits, not Reanimated's `withRepeat`. The running-thread shimmer in |
| 178 | `thread-work-log.tsx` is the example. |