Remote runtime transport
Remote runtime transport lets a desktop, CLI, mobile client, or another runtime use an Orca runtime on another device. It carries authenticated RPC calls, event subscriptions, and interactive terminal data over local sockets, encrypted WebSockets, and relay links while preserving caller scope, routing, size limits, and recovery rules.
The remote connectivity page explains how a client finds an endpoint. The pairing and device trust page explains how a device becomes trusted. This page explains how an established path carries work.
Connection model
Remote work crosses several boundaries. The transport proves the channel and caller first. The RPC layer then checks the method, target runtime, feature readiness, and path support before it runs the work.
This diagram shows the common path from a client action to a runtime result or stream.
flowchart LR
Client[Client] --> Endpoint[Direct endpoint or relay]
Endpoint --> Secure[Handshake and device authentication]
Secure --> Scope[Caller scope and capability checks]
Scope --> Route[Local runtime or execution host]
Route --> Dispatch[RPC method or subscription]
Dispatch --> Reply[Reply or event stream]
Dispatch --> PTY[Binary terminal stream]
RPC contract
The RPC contract gives each call an ID, method name, parameters, and a response with the same ID. Responses carry the runtime ID that handled the call. This lets a client detect when work reached another runtime. The method registry separates one-result methods from streaming methods and assigns each method a caller permission.
The dispatcher admits work before it invokes a handler. It checks the method, caller scope, runtime source, parameters, transport support, and any startup feature that the method needs. A feature that is still starting waits for a bounded time. If it does not become ready, the caller gets a retryable unavailable result. Stable error codes distinguish a refusal, an unavailable feature, a lost connection, and an operation whose delivery is unknown.
Written mutations can carry a receipt and a stable request identity. If the reply is lost, the caller can inspect that receipt or request status instead of applying the side effect twice. The response layer keeps these codes and structured recovery data visible to clients.
References: src/…/runtime-rpc-websocket-dispatch.ts• L139-233 src/…/rpc-method-registry.ts• L125-153 src/…/rpc-response.ts• L61-77 src/…/orchestration-mutation-receipt.ts• L204-228
Authentication and caller scope
The WebSocket path completes an encrypted handshake and authenticates a paired device. Version 2 proves the device key over the exact handshake transcript. Older pairings can use the legacy token path. The runtime resolves the device again for each request, so revocation takes effect before the socket closes. Request fields cannot replace the identity proved by the socket.
The transport places caller scope in the RPC context. Owner, mobile, delegated phone, and paired runtime callers have different permissions. Mobile callers also use an explicit method allowlist. A client negotiates capabilities on the authenticated socket, so an unsupported feature can be refused without treating the whole connection as broken. Relay sockets bind the outer relay device to the authenticated device before RPC dispatch.
References: src/…/e2ee-channel.ts• L185-275 src/…/runtime-rpc-websocket-dispatch.ts• L156-185 src/…/runtime-rpc-websocket-dispatch.ts• L186-205 src/…/runtime-rpc-websocket-dispatch.ts• L260-280
Execution-host routing
An execution host is the runtime that owns a workspace or process. A mobile request may name an execution host, but the desktop decides whether that route is valid and whether its relay can reach the server. If the selected server is not reachable, the client receives an explicit unavailable result. The request does not silently run on the desktop.
Mobile methods use three route classes:
| Route | Work location |
|---|---|
| Execution host | The selected workspace or runtime host. |
| Paired desktop | The desktop that relays the phone request. |
| Default-scope host | The desktop's configured default host when a tracker call has no target. |
The paired desktop and the workspace server remain separate peers. A scoped client view keeps its selected host across calls and subscriptions. Closing that view does not close the shared physical client.
References: src/…/runtime-rpc-mobile-method-routing.ts• L6-8 src/…/runtime-rpc-mobile-method-routing.ts• L296-300 src/…/runtime-rpc-websocket-dispatch.ts• L37-126 src/…/runtime-rpc-mobile-tracker-methods.ts• L3-61
Connection paths
The runtime exposes a local Unix socket or Windows named pipe for local clients. It can also expose an encrypted WebSocket for paired devices. A desktop can relay an allowlisted phone request to a configured server over a separate encrypted link. SSH can provide reachability to a managed server or to a legacy relay before the runtime RPC contract begins.
These paths share the RPC contract but have different ownership boundaries:
| Path | Main use | Boundary |
|---|---|---|
| Unix socket or named pipe | Local CLI and desktop work | Local authentication, newline-delimited JSON, and connection cancellation. |
| Direct WebSocket | Paired device access | Per-device authentication, encrypted frames, and binary streams. |
| Desktop relay link | Phone access to a configured server | Delegated access and one link per phone connection and server. |
| SSH or host path | Reachability and host setup | Host forwarding ends before runtime RPC dispatch. |
The runtime publishes live transport metadata only after the endpoint is ready. WebSocket exposure defaults to loopback unless network access is enabled by configuration or a connected network pairing. A failed supplementary WebSocket does not stop the local socket.
References: src/…/runtime-rpc-lifecycle.ts• L46-109 src/…/runtime-rpc-lifecycle.ts• L111-174 src/…/runtime-rpc-lifecycle.ts• L196-209
WebSocket framing
WebSocket carries encrypted text for handshake and RPC control. It carries encrypted binary frames for terminal streams and other binary payloads. Text and binary traffic share an authenticated socket but use separate routing rules.
Control frames
Control text frames contain handshake messages, authentication replies, RPC replies, and subscription events. The client routes replies by request ID. The runtime bounds JSON structure and reply size before an oversized result can close the socket for unrelated calls. A capable client can receive large text as a compressed binary frame and restore it to the same control payload.
The normal request sequence is:
- Open a direct or relay WebSocket.
- Exchange the encrypted handshake and authenticate the device.
- Negotiate client capabilities.
- Send an RPC request and route its response by ID.
- Keep the connection for subscriptions or close it when its work ends.
An oversized payload is refused at the appropriate boundary. Malformed input, failed authentication, repeated decryption failure, or an outbound queue overflow ends the affected channel.
References: src/…/e2ee-channel.ts• L120-183 src/…/e2ee-channel.ts• L242-275 src/…/runtime-rpc-websocket-dispatch.ts• L139-180 src/…/runtime-rpc-websocket-dispatch.ts• L217-233
Compressed frames
Compressed frames reduce the cost of large text and selected text-like binary payloads without changing their meaning. The sender uses them only after capability negotiation and only when compression makes the payload smaller. Dense binary data such as ordinary images stays uncompressed unless its sender marks it as text-like.
The receiver checks the declared size before inflation and then routes the restored payload as control text or binary data. A peer that does not support compressed frames receives ordinary frames instead.
References: src/…/mobile-e2ee-v2-compressed-frame.ts• L12-43 src/…/remote-runtime-memory-limits.ts• L8-32
Binary stream frames
Binary frames carry versioned terminal records. Their header identifies the opcode, stream ID, and sequence. The payload can carry output, snapshots, input, resize data, metadata, acknowledgements, or recovery notices.
The client routes a frame to the stream that registered its stream ID. Unknown terminal frames cause that stream to report an error and refresh from a new snapshot instead of applying bytes that the client cannot interpret. New opcodes are sent only after the matching capability is negotiated.
References: src/…/terminal-stream-protocol.ts• L3-68 src/…/terminal-stream-protocol.ts• L85-105 src/…/terminal-stream-protocol.ts• L149-171
Socket boundaries
The WebSocket server bounds raw connections, upgraded connections, handshake time, and inbound payload size. It can bind to loopback or a network interface. It can retain a fallback port when the configured port is unavailable. The runtime publishes only live transport metadata.
The local socket accepts newline-delimited JSON. It bounds messages and connections and aborts active dispatch when a socket closes. Long polls can request application keepalives. Short calls do not pay that timer cost.
References: src/…/runtime-rpc-lifecycle.ts• L127-160 src/…/runtime-rpc-lifecycle.ts• L162-193 src/…/runtime-rpc-state.ts• L44-119
Feature readiness
Some managed runtimes receive RPC traffic before their account, session search, orchestration, or placement services finish startup. Methods declare these needs. The dispatcher waits only for the declared features and stops waiting when the caller disconnects or the bounded startup period ends.
This keeps early requests safe without delaying methods that do not need the unfinished service. A request that needs a closed feature returns an unavailable result instead of running with incomplete state.
References: src/…/runtime-feature-interaction.ts• L46-63 src/…/runtime-rpc-websocket-dispatch.ts• L217-225 src/…/accounts.ts• L259-269
Shared control channels
A shared control channel places many logical RPC calls and subscriptions on one authenticated WebSocket. It separates logical work from the physical socket, which gives subscriptions one place for readiness, replay, liveness, and cleanup.
Shared socket lifecycle
The channel becomes ready after host identity and device authentication. It keeps pending requests and subscriptions across a replaceable socket. Each replacement receives a new generation, so late frames from an old socket cannot change current state.
An intentional close removes logical work. A transport close can retain work that supports recovery. A replacement authenticates first, then restores subscriptions and accepts new calls. Diagnostics can expose connection state, generation, pending request count, subscription count, and recovery progress.
References: src/…/remote-runtime-shared-control-connection.ts• L30-55 src/…/remote-runtime-shared-control-connection.ts• L110-145 src/…/remote-runtime-shared-control-connection.ts• L167-237
Subscription ownership
Each logical subscription retains its method, parameters, callbacks, and remote registration identity. That record lets the client wait for readiness, replay after authentication, and send cleanup to the registration that it created.
Closing before registration sends neither a request nor cleanup. Closing after registration sends the matching unsubscribe when one exists. Registration versions stop an old unsubscribe from removing a newer registration that reused a host slot. Follow-up calls use the subscription's socket and fail when that socket is not writable.
References: src/…/remote-runtime-shared-control-protocol.ts• L50-99 src/…/remote-runtime-shared-control-subscription-start.ts• L1-140 src/…/remote-runtime-shared-control-subscription-close.ts• L1-120
Admission limits
Admission control protects the client and runtime from large messages, retained subscriptions, slow peers, and too many waits. A refusal means the work did not enter the affected queue.
Payload and connection budgets
The client measures JSON before encryption. The runtime checks the reply at its boundary. This accounts for sealing overhead and prevents one large result from closing sibling RPC work.
| Resource | Limit | Result |
|---|---|---|
| Outbound JSON payload | 4 MiB | The client rejects the payload or the reply path returns an oversize result. |
| Inbound WebSocket frame | 1 MiB | The host rejects an oversized control frame. |
| Binary stream frame | 8 MiB | A binary payload stays within one bounded frame. |
| Pending requests per connection | 256 | New work is refused before the pending map grows. |
| Pending requests per process | 512 | Multiple sockets cannot bypass the process bound. |
| Retained pending RPC text | 32 MiB per connection; 64 MiB per process | Prepared request memory stays bounded. |
| Subscriptions | 256 | Replay and callback state stays bounded. |
| Subscription parameters | 1 MiB each; 16 MiB per channel | Retained replay input stays bounded. |
| Outbound queued frames per process | 16,384 | A backed-up socket cannot grow the process queue without limit. |
| Outbound queued bytes per process | 128 MiB | Queued encrypted work stays within a process budget. |
Long results use paging, chunking, bounded reads, or snapshots instead of raising the normal JSON ceiling.
References: src/…/remote-runtime-memory-limits.ts• L8-32 src/…/mobile-e2ee-outbound-memory-budget.ts• L1-33 src/…/mobile-e2ee-outbound-admission.ts• L40-67
Client call queues
The client also limits work before it reaches the transport. Each target selector has a bounded queue and the process has a global queue bound. Foreground work takes priority over background refreshes, while long waits and bulk reads use separate lanes so they do not block normal workspace actions.
The queue allows eight ordinary calls per selector, two background calls, and two bulk reads. It rejects a full selector, full global queue, or full retained-memory budget with a retryable overload result. An aborted queued call leaves no retained work.
References: src/…/runtime-rpc-call-queue.ts• L4-17 src/…/runtime-rpc-call-queue.ts• L67-98 src/…/runtime-rpc-call-queue.ts• L100-174
Long-poll admission
Long-poll admission covers calls that wait for a worker, prompt, browser host, terminal, or orchestration result. Short RPCs bypass this pool so slow work cannot block status, control, or recovery calls.
The shared long-poll cap is 16. Orchestration asks and browser-host waits use reserved shares, and browser-host waits also have a per-device share. A full pool returns runtime_busy. Only admitted waits receive keepalives, and disconnect releases their slot.
References: src/…/runtime-rpc-state.ts• L25-30 src/…/runtime-rpc-state.ts• L112-119 src/…/runtime-rpc-websocket-dispatch.ts• L217-225
Backpressure
Backpressure protects a peer that receives encrypted replies or terminal output. One outbound queue accounts for text and binary work together. It measures queued bytes before encryption and shares a memory budget across socket sources. It refuses new work or closes the affected session when the peer cannot drain the queue.
Terminal output has per-stream and total acknowledgement windows. When a window is full, later output stays in a bounded queue. If that queue overflows, the runtime sends an authoritative snapshot rather than claiming that dropped bytes reached the client.
References: src/…/mobile-e2ee-desktop-outbound-owner.ts• L25-43 src/…/mobile-e2ee-desktop-outbound-owner.ts• L77-128 src/…/mobile-e2ee-outbound-memory-budget.ts• L53-93
Reconnect and keepalive
Liveness and recovery depend on the work type. A one-shot request fails when its connection fails. A logical client retains subscriptions while it migrates to a replacement session. A written mutation whose reply is lost remains delivery-unknown because the runtime may already have applied it.
Keepalive probes
The mobile client records authenticated inbound activity with wall-clock time. Direct and relay sessions probe after idle periods. A normal probe tolerates several misses. A decisive foreground or network-change probe can terminate the session after one missed response. A new authenticated frame clears the miss count. This wall-clock evidence remains meaningful when the mobile runtime suspends its timers.
The mobile app nudges recovery after a background-to-active transition or a connected network change. A focus nudge probes a connected socket without replacing it. A network change can force a replacement when the old TCP path is no longer usable.
On the runtime side, WebSocket and local long-poll keepalive rules remain transport-specific. A closed WebSocket aborts its dispatches, subscriptions, and binary handlers.
References: mobile/…/rpc-session-liveness-watchdog.ts• L3-7 mobile/…/rpc-session-liveness-watchdog.ts• L68-110 mobile/…/rpc-session-liveness-watchdog.ts• L178-279 mobile/…/connection-revival-triggers.ts• L5-31 src/…/runtime-rpc-lifecycle.ts• L268-325 src/…/runtime-rpc-websocket-dispatch.ts• L224-325
Direct reconnect
Direct reconnect uses short increasing delays and then slow trickle attempts after its retry limit. Authentication resets the attempt count. A socket must complete its connection and encrypted-handshake deadlines before it can become the active session. A foreground event can abandon a stale dial or advance a scheduled reconnect without opening parallel sockets.
Requests written before a close are rejected as delivery-unknown. Subscriptions are marked for replay after the replacement authenticates. An authentication refusal can retry with updated credentials. A latched authentication failure stops retries and asks the user to re-pair.
References: mobile/…/direct-rpc-client.ts• L46-134 mobile/…/direct-rpc-client.ts• L175-313 mobile/…/rpc-client-socket-session.ts• L107-221 mobile/…/rpc-client-reconnect-schedule.ts• L1-67 mobile/…/rpc-client-request-tracker.ts• L61-113 src/…/e2ee-channel.ts• L101-104
Relay recovery
Relay recovery shares one cooldown across resume failures, foreground nudges, lease rotation, and direct-to-relay fallback. It uses jittered backoff for transport failures and slower reprobes when credentials are rejected or unavailable. A known offline desktop receives a separate retry pace instead of being treated as a generic network fault.
The mobile endpoint supervisor prefers a working direct path when it returns, but it does not flap between paths. It uses direct observation, a minimum dwell time, and a grace period before replacing a live path. Background state suspends active relay work without reopening billed relay links, while foreground state resumes recovery.
References: mobile/…/mobile-relay-reconnect-controller.ts• L27-49 mobile/…/mobile-relay-reconnect-controller.ts• L62-105 mobile/…/mobile-relay-reconnect-controller.ts• L200-279 mobile/…/mobile-relay-retry-delays.ts• L1-47 mobile/…/mobile-endpoint-supervisor.ts• L33-190
Connection health
Connection health turns transport evidence into a user-facing state. It reports connection progress first, then a warning after repeated failures, and an unreachable state after sustained failure or stale last-success evidence.
Explicit relay evidence has priority over retry-count inference. It can identify a signed-out desktop, an offline host, expired relay access, or an unreachable relay. A pairing refusal asks for re-pairing instead of sending more retries. Direct LAN, direct Tailscale, and relay paths have distinct labels and hints. Readable host status also supplies protocol and feature gates; an unreadable status fails closed until a later connection proves them again.
Status reads are tied to the current logical-client generation and connection time. A cutover retries quickly, while other failures use increasing delays. A readable status can update the live and last-known host descriptor, including the machine name, platform, and machine kind. The mobile page uses the server's status when a workspace is routed to a server, so its feature gates do not come from the paired desktop by mistake.
References: mobile/…/connection-health.ts• L7-220 mobile/…/host-status-gates.ts• L11-179 mobile/…/host-status-reply-schema.ts• L6-30 mobile/…/runtime-status-probe.ts• L9-81 mobile/…/host-descriptor-recorder.ts• L1-14 mobile/…/host-name-identity.ts• L77-107 mobile/…/workspace-server.ts• L31-53
Delivery outcomes
Remote callers must distinguish a refused operation from an operation whose delivery is unknown. A refusal means the protected side effect did not enter the handler. A delivery-unknown result means the request may have reached the runtime and needs a receipt, status check, or authoritative snapshot before a retry.
The same rule applies to terminal input. Sequenced input is ordered per PTY and client session. The host acknowledges applied, delivery-unknown, or resend, so a lost acknowledgement does not turn one command into two.
References: src/…/orchestration-mutation-receipt.ts• L21-75 src/…/orchestration-mutation-receipt.ts• L204-228 src/…/rpc-response.ts• L175-266
Subscriptions
A subscription changes one RPC request into a logical stream. The runtime emits an opening state, later events, and an end or error. The client closes the logical stream. The transport then releases the matching runtime registration.
Subscription families
The RPC surface uses subscriptions for account state, runtime events, notifications, file watches, session tabs, terminals, browser screencasts, and agent sessions. Each family owns its opening snapshot or event shape. The transport supplies common cleanup, replay, and socket-liveness behavior.
The account stream sends an initial snapshot and then changes. A paired viewer can keep usage polling active without reopening the account screen. It keys cleanup by connection and subscription sequence so concurrent streams do not remove each other.
References: src/…/account-subscription-method.ts• L8-65 src/…/accounts.ts• L247-256 src/…/rpc-method-registry.ts• L186-214
Session tab streams
Session tab subscriptions provide a view of workspace tabs and their agent, browser, and file-host state. A stream registers before it waits for the first snapshot, so an unsubscribe or socket close can cancel setup. The stream emits a snapshot first and then emits updates only for accepted worktree changes.
The inventory stream performs a bounded census, buffers changes that arrive during that census, and replays only changes newer than the census sequence. It coalesces redundant changes and stops after repeated unstable censuses. Mobile projection removes desktop-only fields and can add unread marks from the host's agent status feed.
References: src/…/session-tabs.ts• L67-134 src/…/session-tabs-inventory.ts• L21-50 src/…/session-tabs-inventory.ts• L232-300 src/…/session-tabs-client-projection.ts• L6-23 src/…/session-tab-unread-projection.ts• L32-55
Replay state
Replay restores the logical subscription, not an unknown byte position. The first replay response or snapshot becomes the client's current view. A stream that needs exact history must use its cursor or snapshot contract.
Subscription cleanup is tied to the connection and the resolved resource identity. An unsubscribe by alias can remove the intended stream after the host resolves that alias. A newer stream is protected from an older worktree-wide unsubscribe.
References: src/…/session-tabs.ts• L101-133 src/…/session-tabs-unsubscribe.test.ts• L11-44 src/…/session-tabs-subscribe-admission.test.ts• L143-229
Remote PTY access
Remote PTY access gives a client a controlled view of a terminal owned by another runtime. RPC resolves the terminal and its current process identity. Binary frames then carry screen state, output, input, resize, acknowledgements, and recovery notices.
Terminal lifecycle
Remote terminal creation starts work on the selected host and keeps it in the background for a paired viewer. The runtime deduplicates repeated creates by caller, workspace, and client mutation ID. A remote viewer cannot use a host-only window-tab action or reveal a pane on the local machine.
Resize and close operations resolve the live terminal handle before they touch the PTY. A stale handle or a terminal without a connected PTY is refused. This prevents a late remote action from reaching a different process incarnation.
References: src/…/terminal-lifecycle-methods.ts• L23-141 src/…/terminal-lifecycle-methods.ts• L183-240 src/…/terminal-lifecycle-methods.ts• L243-269
Terminal multiplex
terminal.multiplex carries many terminal slots on one authenticated binary stream. A slot becomes usable only after the runtime resolves the terminal, binds its stream handler, and publishes an initial state. Detach, cancellation, and socket close release the wait, listeners, viewport record, input authority, and binary routing for that slot.
The stream advertises capabilities such as output pause, input acknowledgements, write-unavailable notices, and desktop viewport claims. The client sends the related opcodes only when the negotiated capabilities allow them.
References: src/…/terminal-multiplex-method.ts• L18-79 src/…/terminal-multiplex-frame-delivery.ts• L24-134 src/…/terminal-stream-protocol.ts• L12-38
Snapshot recovery
A terminal snapshot is the authoritative screen image. The runtime sends it as bounded start, chunk, and end frames. It holds or trims live output while the image is prepared, then releases only output newer than the snapshot sequence.
Snapshots carry the screen size and can carry scrollback, working directory, title, terminal owner, alternate-screen state, keyboard flags, links, and an explicit unavailable or truncated marker. When output buffering overflows or acknowledgement windows saturate, the runtime requests a recovery snapshot. A missing or empty snapshot is not proof that the terminal had no content.
References: src/…/terminal-snapshot-publication.ts• L21-87 src/…/terminal-snapshot-publication.ts• L167-229 src/…/terminal-multiplex-flow-control.ts• L29-110
Input and viewport ownership
Terminal input has separate authority and safety checks. The authority decides which client may drive a shared PTY. The safety checks confirm the exact terminal handle, process incarnation, agent state, and write settlement immediately before input is applied.
Desktop viewers can report a viewport and can claim it when that capability is negotiated. Mobile input follows its own authority path. A stale or rejected send returns a refusal rather than writing to another PTY. If the endpoint is lost, a negotiated write-unavailable notice can reach the client before the next keystroke.
References: src/…/terminal-lifecycle-methods.ts• L183-205 src/…/terminal-stream-protocol.ts• L40-61 src/…/terminal-multiplex-slot-frames.ts• L78-142
Change checklist
When these files or sections are changed, remember to consider these:
- Keep handshake identity, transcript proof, legacy-token fallback, per-request device revalidation, caller scope, mobile method allowlists, and capability negotiation aligned.
- Keep execution-host routing explicit. An unreachable server must not fall back to the desktop.
- Keep request and reply size checks consistent across JSON serialization, encryption overhead, compressed frames, binary frames, and relay forwarding.
- Keep process-wide outbound queue budgets aligned with per-socket backpressure and with the close evidence reported to clients.
- Preserve logical-client generation fencing when changing migration, close, replay, or reconnect behavior.
- Preserve subscription registration identity and version fencing when changing stream methods or unsubscribe parameters.
- Keep long-poll classification, total caps, reserved shares, keepalive arming, abort handling, and release paths aligned.
- Keep host status epochs, protocol windows, capability gates, and last-known descriptors tied to the runtime and host that produced them.
- Keep mobile projections aligned with the fields that desktop and phone clients are allowed to receive.
- Keep terminal opcodes, capability bits, frame limits, stream routing, sequence cutoffs, and snapshot metadata compatible across peers.
- Preserve the difference between refused, applied, delivery-unknown, and resend outcomes for RPC mutations and terminal input.
- Keep PTY wait cancellation tied to slot removal so a late terminal mount cannot install a hidden listener.
- Preserve client queue lanes and overload codes when changing call priority or adding a slow remote method.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A device is revoked while its socket stays open | A later request could use stale credentials. | Resolve the authenticated device and credential revision for every request. |
| A relay socket authenticates a device different from its outer relay identity | A phone could use a relay path for the wrong device. | Bind relay device identity before the socket becomes ready. |
| A phone names an unreachable execution host | Work could run on the desktop by mistake. | Require desktop-approved execution-host routing and return explicit unavailable state. |
| A method needs a runtime feature that is still closed | The handler could run with incomplete state or duplicate a retry. | Use a bounded readiness wait with request and connection abort signals. |
| A request or reply exceeds a frame budget | The request fails or one result could close sibling work. | Apply pre-send serialization limits and per-request reply admission. |
| A compressed frame claims more bytes than the remote limit | Inflation could consume unsafe memory or misroute a corrupt frame. | Bound the declared size and require the inflated length to match. |
| A client or process call queue is full | New work is rejected while existing work remains protected. | Use selector, global, lane, and retained-memory caps. |
| A long-poll pool is full | Slow work returns runtime_busy; short control calls remain available. | Use total, specialized, and per-device long-poll caps. |
| A socket is half-open after sleep or network roaming | Calls or streams can wait without a close event. | Use wall-clock activity checks, decisive probes, and close-triggered aborts. |
| A request loses its reply after a mutation may have run | A blind retry can apply the side effect twice. | Return delivery-unknown and recover with a receipt or status check. |
| A subscription closes during setup or replay | A remote registration or local callback can leak. | Register early, check cancellation after waits, and use matching cleanup. |
| A session-tab census changes while it is collected | The client can receive a stale or inconsistent inventory. | Buffer changes, replay by sequence, and fail after repeated unstable censuses. |
| Terminal output exceeds an acknowledgement window | The client can miss output or stall. | Use bounded queues and authoritative snapshot recovery. |
| A terminal handle points to another process incarnation | Input, resize, or release can affect the wrong process. | Check the exact handle and incarnation immediately before use. |
Key files
| File | Why to read it |
|---|---|
| src/…/runtime-rpc-websocket-dispatch.ts | Shows device revalidation, mobile routing, execution-host forwarding, long-poll admission, and dispatch context. |
| src/…/e2ee-channel.ts | Shows encrypted handshake, authentication, capability capture, and text or binary frame routing. |
| src/…/runtime-rpc-lifecycle.ts | Shows local and WebSocket transport startup, endpoint metadata, exposure choice, and socket cleanup. |
| src/…/runtime-rpc-mobile-method-routing.ts | Defines the mobile allowlist and the three execution route classes. |
| src/…/rpc-response.ts | Defines the response envelope and the error codes that clients use for recovery decisions. |
| src/…/remote-runtime-memory-limits.ts | Defines payload, frame, pending-request, and subscription budgets. |
| src/…/mobile-e2ee-desktop-outbound-owner.ts | Shows shared text and binary backpressure and outbound queue ownership. |
| src/…/runtime-rpc-call-queue.ts | Shows client-side concurrency, priority lanes, overload limits, and cancellation. |
| src/…/account-subscription-method.ts | Illustrates an account stream's initial snapshot, updates, ownership, and cleanup. |
| src/…/session-tabs.ts | Shows session-tab snapshots, updates, projection, and subscription cleanup. |
| src/…/session-tabs-inventory.ts | Shows inventory census, change buffering, sequence replay, and bounded recovery. |
| src/…/terminal-lifecycle-methods.ts | Shows remote terminal creation, background presentation, handle checks, resize, and close. |
| src/…/terminal-stream-protocol.ts | Defines versioned terminal records, opcodes, sequences, and input acknowledgement meanings. |
| src/…/orchestration-mutation-receipt.ts | Shows stable mutation identity and recovery when a reply is lost. |