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 / push-notification-delivery

Push notification delivery

Push notification delivery carries selected desktop events to a paired mobile device when a live client connection is not enough. The desktop proves its host identity to the cloud push gateway, targets a stored mobile registration, and accepts durable delivery before the gateway sends it through APNs or FCM. The cloud relay admission and continuity page covers live sessions. The cloud operational deployment controls page covers service change and operations.

Delivery model

The push path is an out-of-band path beside the live relay or socket path. A push can therefore remain useful when the mobile app is closed or the live connection is idle, while a provider delay cannot block normal desktop notification fan-out.

Delivery lifecycle

The delivery lifecycle starts with host admission and ends with mobile presentation or a recorded terminal result. The gateway owns registration and queue state. The mobile client owns permission, local suppression, route selection, and tray state.

This diagram shows how a desktop event crosses the cloud boundary and returns to the mobile client as an alert or dismissal.

sequenceDiagram
    participant Desktop as Desktop host
    participant Gateway as Push gateway
    participant Queue as Durable delivery state
    participant Provider as APNs or FCM
    participant Phone as Mobile client

    Desktop->>Gateway: Prove host identity
    Gateway-->>Desktop: Short-lived session
    Phone->>Desktop: Register native push token
    Desktop->>Gateway: Submit targeted event
    Gateway->>Queue: Accept delivery
    Gateway-->>Desktop: Per-device queue result
    Queue->>Provider: Send due delivery
    Provider-->>Phone: Native push
    Phone->>Desktop: Report dismissal when needed
    Desktop->>Gateway: Submit dismissal

References: src/…/desktop-push-service.ts• L74-99 cloud/…/push-server.ts• L181-282 cloud/…/durable-push-worker.ts• L16-83

Service contract

The service contract keeps identity, registration, event content, and delivery status consistent across the desktop, gateway, and mobile client. The shared contract in src/…/mobile-push-contract.ts is the desktop and mobile view. The cloud package defines the wire validation used at the gateway boundary.

Host authentication

The desktop does not use cloud account sign-in as the push identity. It proves control of its host key pair through a challenge and receives a short-lived bearer session tied to a host fingerprint. Each later registration or send is checked against that session, so one host cannot target another host's registrations.

The gateway treats transport failure, rate limiting, and request refusal as different outcomes. The desktop can retry a temporary reachability problem without repeating a request that the gateway rejected as invalid.

References: src/…/push-gateway-session.ts• L74-131 src/…/push-gateway-response.ts• L35-60 cloud/…/push-server.ts• L146-175 cloud/…/host-challenge-store.test.ts• L29-158

Device registration

A mobile device registration joins a host-owned device identity to a native provider token. The registration records the platform and, for iOS, the APNs environment. It also carries the user's delivery filter and an expiry so the host can continue to send after a restart without requiring the phone to be online.

Registration is host-scoped. The gateway returns an opaque registration ID that the desktop stores with the paired device. A registration change replaces the old provider route only after the old route is cleaned up, which avoids sending to a stale token during token rotation.

Contract areaMeaning
Device identityThe paired mobile device selected for delivery
Provider tokenThe APNs or FCM destination owned by the mobile operating system
Registration IDThe gateway-owned handle used by later sends and deletes
ExpiryThe point after which the desktop must stop targeting the route
Delivery filterWhether to send only when the desktop is away and whether to use sound

References: src/…/mobile-push-contract.ts• L18-49 cloud/…/device-registration-messages.ts• L4-24 src/…/desktop-push-service.ts• L157-207 cloud/…/push-server-auth.test.ts• L45-153

Notification submission

The desktop offers an event to push only after its normal notification path has accepted it. The dispatcher maps desktop-specific agent states into the smaller mobile states needs-input and finished, keeps source names within the shared contract, and limits title and body size before submission.

The send request names one or more registration IDs and one notification identity. The gateway checks that every target belongs to the authenticated host, then returns a result for each target. queued means the gateway accepted durable work. It does not mean that APNs or FCM has already shown the alert.

References: src/…/push-dispatcher.ts• L41-63 src/…/push-dispatcher.ts• L119-191 cloud/…/send-messages.ts• L9-66 cloud/…/push-server.ts• L249-282 cloud/…/push-server-send.test.ts• L41-76

Device targeting

Targeting happens in two stages. The desktop first selects eligible paired devices from its local registry. The gateway then confirms ownership and liveness before it accepts each delivery, so local preference state and cloud registration state both take part in routing.

Desktop selection

The desktop skips expired registrations and events that the desktop has marked as disallowed. A device with the onlyWhenDesktopAway filter receives an event only when the desktop is away. The dispatcher also applies a short burst cooldown per device and worktree, then splits targets into bounded sends and sound groups.

Dismissals use the same registration targets but bypass alert filters. They are silent control events that let a phone remove an alert which the desktop has already dismissed.

References: src/…/push-dispatcher.ts• L54-63 src/…/push-dispatcher.ts• L93-117 src/…/push-dispatcher.ts• L119-191

The mobile client registers only after the user enables remote push and the paired host advertises the capability. It requests the operating-system token, sends the current delivery filter through the host connection, and records which hosts are registered.

Disabling push creates durable unregister intent before the client forgets the host route. The intent can be retried when the host returns. A removed host loses local registration ownership first, so a late response cannot restore a route that the user removed.

References: mobile/…/push-registration.ts• L127-204 mobile/…/push-registration.ts• L252-303 mobile/…/notification-delivery-preferences.ts• L4-49

Provider delivery

The gateway converts an accepted event into the provider shape only after it has durable queue state. It preserves the host and notification identity in provider data so the mobile client can validate the source, suppress duplicates, and route a tap to the correct paired host and worktree.

Provider payload

APNs and FCM carry the same logical Orca payload in different native envelopes. The mobile reader accepts the APNs nested form and the FCM string data form, then extracts the host fingerprint, notification identity, and optional worktree, pane, or execution-host target.

The gateway derives a collapse identity from the host and notification identity. This lets the provider replace an equivalent pending alert without treating an event for one host as equivalent to an event for another host.

References: cloud/…/push-delivery-message.ts• L4-77 mobile/…/push-payload.ts• L1-45 cloud/…/send-messages.ts• L9-42 cloud/…/push-server-send.test.ts• L121-171

Durable delivery

The gateway stores each host-and-device delivery as durable work. Workers claim only the current delivery head for a registration, renew a lease while the provider call runs, and release the work for a later attempt when the provider reports a temporary error. This preserves order for one device while allowing work for other devices to proceed.

The queue admits one event only once for a host and registration. It uses the notification identity and content to reject conflicting reuse while repeated submissions remain safe. Each delivery has a bounded lifetime, so expired work is discarded rather than sent. Event, recipient, and dismissal records are pruned in bounded sweeps after their retention period.

Claims use a shared coordination boundary across worker revisions and a per-device head check. This prevents an older worker from leasing the same delivery or a later delivery behind an active head. Background claims and cleanup also leave request capacity available for new sends and device requests.

The worker polls for due work and can wake after a new enqueue. It runs several drains, renews active leases, applies provider retry delays with backoff, and leaves unclaimed work for a later worker during shutdown.

References: cloud/…/durable-push-store.ts• L9-16 cloud/…/durable-push-store.ts• L42-165 cloud/…/durable-push-store.ts• L179-262 cloud/…/durable-push-worker.ts• L17-105 cloud/…/push-background-database.ts• L3-33 cloud/…/durable-push-claim-mixed-revision.test.ts• L46-103 cloud/…/durable-push-retention.test.ts• L30-80

Provider outcomes

Provider results are reduced to three useful delivery classes: sent, dead, or retryable error. A dead provider token clears the matching desktop registration, while a temporary provider or transport error keeps the work eligible until its expiry. The gateway reports the earlier queue decision to the desktop and records the later provider result separately.

References: cloud/…/push-provider-outcome.ts• L1-6 cloud/…/durable-push-worker.ts• L80-95 src/…/push-dispatcher.ts• L224-269 cloud/…/push-server-send.test.ts• L78-119

Mobile client boundary

The mobile client treats a provider push as untrusted input that must pass local checks before it can display or navigate. The cloud service delivers an event. The mobile client decides whether that event is still valid for this installation and how it affects the user interface.

Push intake

The mobile client accepts both provider payload shapes, but it recognizes a remote push only when the payload carries a host fingerprint. It maps that fingerprint to a paired host before presentation or routing. This keeps a remote payload from using unrelated local data to select a host.

Recognized pushes are suppressed when remote consent is off, the host is no longer known, the user is viewing the same host workspace, or the alert was already dismissed. Viewing suppression includes the execution host when the event names a server workspace, so a desktop workspace and a server workspace with the same worktree remain distinct. A duplicate provider callback is also suppressed after the first valid foreground claim.

Suppression checks use one delivery-preference snapshot for the decision. If a recognized push cannot pass its checks, the client fails closed. Unrecognized local notifications keep their normal local behavior.

References: mobile/…/push-receive.ts• L48-112 mobile/…/push-receive.ts• L123-151 mobile/…/push-payload.ts• L24-44 mobile/…/notification-viewing-policy.ts• L3-20

Notification routing

When a user taps a valid push, the mobile client maps the provider's host fingerprint to its local host ID. An optional worktree and pane key become a host-scoped session target. A runtime execution-host value further scopes a server workspace; other execution-host forms do not change the desktop workspace route.

The same target rules apply to cold and warm starts. The host context is established before a worktree target replaces the current session, so a tap cannot open a valid worktree under another paired host. Missing credentials lead to a retry or re-pair route instead of opening the wrong host. A host-only notification opens the host screen without a session target.

References: mobile/…/push-receive.ts• L123-151 mobile/…/notification-routing.ts• L15-68 mobile/…/notification-routing.test.ts• L7-91

Dismissal reconciliation

Dismissal is a control flow rather than a new alert. The desktop sends a silent dismissal with the notification identity. The mobile client records the identity, removes matching tray entries, and reconciles provider-delivered entries with the desktop when the live connection returns.

Socket dismissal events can carry a delivery fence with the notification epoch and sequence. The mobile client resolves the event's host ID to its current host fingerprint before it removes a presented push. If the host is no longer known, it performs no dismissal; if the fence is incomplete, it uses only the notification identity. This keeps a late dismissal from removing a newer delivery that reused the same notification ID.

Catch-up sends delivered identities instead of requesting old alerts. The desktop confirms only the alerts it knows were dismissed. If the tray or the connection cannot be read, the client leaves the remaining entries for a later pass. Host restart retirement removes the original alert while preserving newer notification identities.

References: mobile/…/desktop-notification-events.ts• L1-11 mobile/…/push-socket-dismissal.ts• L1-24 src/…/push-dispatcher.ts• L119-145 mobile/…/push-receive.ts• L79-112 mobile/…/push-dismissal-reconciliation.ts• L16-81 mobile/…/push-background-dismissal.ts• L9-33 mobile/…/push-original-delivery-retirement.test.ts• L51-86

Failure handling

Push is best effort and must not break the live desktop-to-client path. The desktop treats gateway work as an independent fan-out, retries one temporary transport miss, and keeps unregister work in a durable local outbox when the gateway is unavailable.

Registration recovery

A failed registration does not replace the last known good route. A failed unregister remains pending and retries with backoff. If the gateway accepts a new route but local storage fails, the desktop queues deletion of that route so an unreachable registration does not remain active without an owner.

References: src/…/desktop-push-service.ts• L171-207 src/…/desktop-push-service.ts• L209-331 src/…/push-gateway-response.ts• L35-60

Delivery isolation

The dispatcher does not await push delivery from the socket notification path. A gateway refusal records an outcome without repeating the same invalid request. A temporary reachability failure gets one short retry, while a dead provider registration is removed only if it is still the current registration for that device.

The gateway also limits unauthenticated requests by client IP. It uses the platform-provided forwarded hop rather than a spoofable alternate header, bounds the number of tracked IP buckets, and returns 429 rate_limited after a client uses its allowance. This protects the admission path without changing the host-scoped delivery quota.

References: src/…/push-dispatcher.ts• L93-117 src/…/push-dispatcher.ts• L195-269 src/…/push-gateway-client.ts• L126-170 cloud/…/client-ip-rate-limit.test.ts• L16-150 cloud/…/push-server-send.test.ts• L192-215

Stale notification suppression

The mobile client fails closed for a recognized push when it cannot prove consent, host ownership, or dismissal state. This protects against banners for removed hosts and against a late provider event reopening an alert that the desktop already dismissed.

References: mobile/…/push-receive.ts• L48-112 mobile/…/push-dismissal-reconciliation.ts• L42-81 mobile/…/push-background-dismissal.ts• L9-33

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep src/…/mobile-push-contract.ts, cloud/…/device-registration-messages.ts, and cloud/…/send-messages.ts aligned. They define the same platform, source, state, identity, and status values at different boundaries.
  • Keep provider payload fields aligned with cloud/…/push-delivery-message.ts, mobile/…/push-payload.ts, and mobile/…/notification-routing.ts. A field can arrive successfully yet fail to route if its name or nesting changes.
  • Preserve the distinction between a queued result and a provider result. Desktop retry behavior, durable worker retry behavior, and dead-token cleanup depend on that distinction.
  • Change registration lifecycle with the mobile capability probe, consent records, durable unregister outbox, host removal, and token rotation in mind.
  • Change notification identity or dismissal handling with provider collapse IDs, foreground duplicate claims, desktop dismissal replay, background dismissal, and tray catch-up in mind.
  • Keep the host fingerprint boundary intact. The mobile client must resolve it to a known local host before it creates tap route data or dismisses a presented push.
  • Keep the optional dismissal fence aligned across socket events and tray removal. An epoch without a sequence must not become a partial fence.
  • Keep execution-host data aligned across provider payloads, viewing suppression, and tap routing. Only a valid runtime target may change a worktree's host context.
  • Keep missing and temporary host credential states mapped to their intended recovery route. A notification must not open a session that lacks the host credentials needed to use it.
  • Keep durable queue claim coordination compatible with older worker revisions. A change to locks or device-head checks can duplicate delivery or let a later event pass an active head.
  • Keep request-path database capacity separate from worker and prune capacity. Background work must not consume the connection needed to accept sends or manage devices.
  • Keep notification expiry, retry delay, and retention behavior aligned. A retry must not outlive its event, and deduplication records must outlive the event quota window.
  • Keep the service image and runtime dependency graph aligned with the push app build. The deployed image must include the generated push contract and database schema artifacts used by the gateway.

Important failure modes

TriggerConsequenceGuard
A provider token is invalid or expiredThe provider cannot deliver and later sends would keep failingMark the result dead and remove only the matching current registration
The gateway is unreachable during unregisterThe cloud route remains active after local consent or pairing changesPersist unregister intent and retry it with backoff
A send request is accepted but the provider is slow or offlineThe desktop cannot know delivery is complete from the queue responseStore durable work with a lease, expiry, and retry state
A late push names a removed or unknown hostThe phone could show an alert that has no valid action targetResolve the host fingerprint against the local host catalog and suppress on failure
A duplicate provider callback reaches the foreground handlerThe user sees repeated banners for one eventClaim the host, epoch, notification ID, and sequence identity once
A dismissal arrives while the phone is offlineThe tray can keep an alert after the desktop removed itSend silent dismissal events and reconcile delivered identities after reconnect
A dismissal carries only part of its delivery fenceA late dismissal can remove the wrong notification generationUse the epoch and sequence fence only when both values are present
A push names a server workspace with an invalid execution-host valueThe tap can lose its intended server context or open the wrong workspace classAccept only the recognized runtime form and keep other values on the desktop workspace route
Host credentials are missing or temporarily unavailable at tap timeThe phone cannot safely open the requested sessionRoute to re-pair or retry instead of opening an unready session
Concurrent workers use mismatched claim coordinationTwo workers can deliver one event or skip the device headShare the claim boundary across revisions and verify the per-device head before leasing
Worker or prune traffic fills the database poolNew sends or device changes wait behind background workReserve request capacity and cap background concurrency
A client flood uses one source IP or spoofs forwarded headersUnauthenticated admission can consume excess resources or rate-limit the wrong clientCount the trusted forwarded hop, bound tracked buckets, and return 429 rate_limited
A provider retry delay extends beyond event expiryThe worker keeps stale delivery state or sends an expired alertDrop work when the next retry reaches the delivery expiry

Key files

FileWhy to read it
src/…/mobile-push-contract.tsShared desktop and mobile registration, filter, source, state, and result contract
src/…/desktop-push-service.tsDesktop registration ownership, unregister recovery, and push service lifecycle
src/…/push-dispatcher.tsEvent filtering, device targeting, batching, retry, and dead-registration cleanup
src/…/push-gateway-session.tsHost challenge, proof, short-lived session, and refusal handling
src/…/push-gateway-client.tsDesktop calls for registration, deletion, and notification submission
cloud/…/send-messages.tsGateway send payload, identity, size, and per-device status contract
cloud/…/push-server.tsCloud authentication, registration ownership checks, queue admission, and service routes
cloud/…/durable-push-store.tsDurable acceptance, per-device ordering, leases, deduplication, expiry, retention, and bounded cleanup
cloud/…/durable-push-worker.tsClaim, wake, provider delivery, retry timing, and shutdown behavior
cloud/…/push-background-database.tsSeparation of request capacity from worker and cleanup traffic
cloud/…/push-delivery-message.tsProvider payload, collapse identity, and mobile routing data
cloud/…/client-ip-rate-limit.tsUnauthenticated request admission limits and client address selection
cloud/apps/push/DockerfileProduction image boundary for the gateway and its generated dependencies
mobile/…/push-registration.tsMobile consent, token registration, capability checks, and unregister recovery
mobile/…/push-payload.tsProvider-shape parsing and the trusted routing fields extracted from a push
mobile/…/push-receive.tsMobile validation, foreground suppression, duplicate control, and remote route data
mobile/…/notification-viewing-policy.tsWorkspace-aware suppression while the user views a matching desktop or server workspace
mobile/…/notification-routing.tsHost, worktree, pane, execution-host, and credential-recovery navigation targets
mobile/…/desktop-notification-events.tsSocket dismissal event shape and optional delivery fence
mobile/…/push-socket-dismissal.tsHost-scoped dismissal and safe translation from socket event to tray removal
mobile/…/push-dismissal-reconciliation.tsTray catch-up and desktop confirmation of dismissed provider alerts