Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / remote-runtime-transport

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:

RouteWork location
Execution hostThe selected workspace or runtime host.
Paired desktopThe desktop that relays the phone request.
Default-scope hostThe 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:

PathMain useBoundary
Unix socket or named pipeLocal CLI and desktop workLocal authentication, newline-delimited JSON, and connection cancellation.
Direct WebSocketPaired device accessPer-device authentication, encrypted frames, and binary streams.
Desktop relay linkPhone access to a configured serverDelegated access and one link per phone connection and server.
SSH or host pathReachability and host setupHost 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:

  1. Open a direct or relay WebSocket.
  2. Exchange the encrypted handshake and authenticate the device.
  3. Negotiate client capabilities.
  4. Send an RPC request and route its response by ID.
  5. 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.

ResourceLimitResult
Outbound JSON payload4 MiBThe client rejects the payload or the reply path returns an oversize result.
Inbound WebSocket frame1 MiBThe host rejects an oversized control frame.
Binary stream frame8 MiBA binary payload stays within one bounded frame.
Pending requests per connection256New work is refused before the pending map grows.
Pending requests per process512Multiple sockets cannot bypass the process bound.
Retained pending RPC text32 MiB per connection; 64 MiB per processPrepared request memory stays bounded.
Subscriptions256Replay and callback state stays bounded.
Subscription parameters1 MiB each; 16 MiB per channelRetained replay input stays bounded.
Outbound queued frames per process16,384A backed-up socket cannot grow the process queue without limit.
Outbound queued bytes per process128 MiBQueued 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

TriggerConsequenceGuard
A device is revoked while its socket stays openA 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 identityA 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 hostWork 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 closedThe 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 budgetThe 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 limitInflation 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 fullNew work is rejected while existing work remains protected.Use selector, global, lane, and retained-memory caps.
A long-poll pool is fullSlow 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 roamingCalls 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 runA 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 replayA 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 collectedThe client can receive a stale or inconsistent inventory.Buffer changes, replay by sequence, and fail after repeated unstable censuses.
Terminal output exceeds an acknowledgement windowThe client can miss output or stall.Use bounded queues and authoritative snapshot recovery.
A terminal handle points to another process incarnationInput, resize, or release can affect the wrong process.Check the exact handle and incarnation immediately before use.

Key files

FileWhy to read it
src/…/runtime-rpc-websocket-dispatch.tsShows device revalidation, mobile routing, execution-host forwarding, long-poll admission, and dispatch context.
src/…/e2ee-channel.tsShows encrypted handshake, authentication, capability capture, and text or binary frame routing.
src/…/runtime-rpc-lifecycle.tsShows local and WebSocket transport startup, endpoint metadata, exposure choice, and socket cleanup.
src/…/runtime-rpc-mobile-method-routing.tsDefines the mobile allowlist and the three execution route classes.
src/…/rpc-response.tsDefines the response envelope and the error codes that clients use for recovery decisions.
src/…/remote-runtime-memory-limits.tsDefines payload, frame, pending-request, and subscription budgets.
src/…/mobile-e2ee-desktop-outbound-owner.tsShows shared text and binary backpressure and outbound queue ownership.
src/…/runtime-rpc-call-queue.tsShows client-side concurrency, priority lanes, overload limits, and cancellation.
src/…/account-subscription-method.tsIllustrates an account stream's initial snapshot, updates, ownership, and cleanup.
src/…/session-tabs.tsShows session-tab snapshots, updates, projection, and subscription cleanup.
src/…/session-tabs-inventory.tsShows inventory census, change buffering, sequence replay, and bounded recovery.
src/…/terminal-lifecycle-methods.tsShows remote terminal creation, background presentation, handle checks, resize, and close.
src/…/terminal-stream-protocol.tsDefines versioned terminal records, opcodes, sequences, and input acknowledgement meanings.
src/…/orchestration-mutation-receipt.tsShows stable mutation identity and recovery when a reply is lost.