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 area | Meaning |
|---|---|
| Device identity | The paired mobile device selected for delivery |
| Provider token | The APNs or FCM destination owned by the mobile operating system |
| Registration ID | The gateway-owned handle used by later sends and deletes |
| Expiry | The point after which the desktop must stop targeting the route |
| Delivery filter | Whether 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
Mobile consent
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
| Trigger | Consequence | Guard |
|---|---|---|
| A provider token is invalid or expired | The provider cannot deliver and later sends would keep failing | Mark the result dead and remove only the matching current registration |
| The gateway is unreachable during unregister | The cloud route remains active after local consent or pairing changes | Persist unregister intent and retry it with backoff |
| A send request is accepted but the provider is slow or offline | The desktop cannot know delivery is complete from the queue response | Store durable work with a lease, expiry, and retry state |
| A late push names a removed or unknown host | The phone could show an alert that has no valid action target | Resolve the host fingerprint against the local host catalog and suppress on failure |
| A duplicate provider callback reaches the foreground handler | The user sees repeated banners for one event | Claim the host, epoch, notification ID, and sequence identity once |
| A dismissal arrives while the phone is offline | The tray can keep an alert after the desktop removed it | Send silent dismissal events and reconcile delivered identities after reconnect |
| A dismissal carries only part of its delivery fence | A late dismissal can remove the wrong notification generation | Use the epoch and sequence fence only when both values are present |
| A push names a server workspace with an invalid execution-host value | The tap can lose its intended server context or open the wrong workspace class | Accept only the recognized runtime form and keep other values on the desktop workspace route |
| Host credentials are missing or temporarily unavailable at tap time | The phone cannot safely open the requested session | Route to re-pair or retry instead of opening an unready session |
| Concurrent workers use mismatched claim coordination | Two workers can deliver one event or skip the device head | Share the claim boundary across revisions and verify the per-device head before leasing |
| Worker or prune traffic fills the database pool | New sends or device changes wait behind background work | Reserve request capacity and cap background concurrency |
| A client flood uses one source IP or spoofs forwarded headers | Unauthenticated admission can consume excess resources or rate-limit the wrong client | Count the trusted forwarded hop, bound tracked buckets, and return 429 rate_limited |
| A provider retry delay extends beyond event expiry | The worker keeps stale delivery state or sends an expired alert | Drop work when the next retry reaches the delivery expiry |
Key files
| File | Why to read it |
|---|---|
| src/…/mobile-push-contract.ts | Shared desktop and mobile registration, filter, source, state, and result contract |
| src/…/desktop-push-service.ts | Desktop registration ownership, unregister recovery, and push service lifecycle |
| src/…/push-dispatcher.ts | Event filtering, device targeting, batching, retry, and dead-registration cleanup |
| src/…/push-gateway-session.ts | Host challenge, proof, short-lived session, and refusal handling |
| src/…/push-gateway-client.ts | Desktop calls for registration, deletion, and notification submission |
| cloud/…/send-messages.ts | Gateway send payload, identity, size, and per-device status contract |
| cloud/…/push-server.ts | Cloud authentication, registration ownership checks, queue admission, and service routes |
| cloud/…/durable-push-store.ts | Durable acceptance, per-device ordering, leases, deduplication, expiry, retention, and bounded cleanup |
| cloud/…/durable-push-worker.ts | Claim, wake, provider delivery, retry timing, and shutdown behavior |
| cloud/…/push-background-database.ts | Separation of request capacity from worker and cleanup traffic |
| cloud/…/push-delivery-message.ts | Provider payload, collapse identity, and mobile routing data |
| cloud/…/client-ip-rate-limit.ts | Unauthenticated request admission limits and client address selection |
cloud/apps/push/Dockerfile | Production image boundary for the gateway and its generated dependencies |
| mobile/…/push-registration.ts | Mobile consent, token registration, capability checks, and unregister recovery |
| mobile/…/push-payload.ts | Provider-shape parsing and the trusted routing fields extracted from a push |
| mobile/…/push-receive.ts | Mobile validation, foreground suppression, duplicate control, and remote route data |
| mobile/…/notification-viewing-policy.ts | Workspace-aware suppression while the user views a matching desktop or server workspace |
| mobile/…/notification-routing.ts | Host, worktree, pane, execution-host, and credential-recovery navigation targets |
| mobile/…/desktop-notification-events.ts | Socket dismissal event shape and optional delivery fence |
| mobile/…/push-socket-dismissal.ts | Host-scoped dismissal and safe translation from socket event to tray removal |
| mobile/…/push-dismissal-reconciliation.ts | Tray catch-up and desktop confirmation of dismissed provider alerts |