Alerts and push
Two different mechanisms, for two different situations: a stream that keeps an open client current, and push, which reaches a phone in a pocket.
While the page is open
The companion holds a server-sent events stream. Snapshots arrive on every beat, and edge-detected alerts arrive when a session changes into a state worth naming — needs you, finished, failed, or ready for review. A fifth kind, notice, is not an edge Saggar inferred: a program in the shell raised it itself over OSC 9, 99, or 777, so it carries its own title and body. All five reach the stream and web push alike. A dot in the header goes quiet when no heartbeat has arrived recently, which usually means the Mac went to sleep.
The stream is bought with a ticket rather than a token: a bearer token
must never appear in a URL, and an
EventSource cannot set headers. So
authenticated requests mint two single-use tickets — a 60-second one
from the Mac and a 15-second one from the relay — and only those appear
in the query string; the relay redeems and strips its own before
forwarding. Dropped connections mint fresh ones and
back off; a refused mint means the pairing itself is gone, and the
client returns to the pairing screen rather than showing a live-looking
page that refuses everything.
When it isn't
Web push is Lock-screen alerts in the companion's settings, behind the ⋯ button in its header. Turn it on and the browser subscribes; the Mac becomes its own push sender, encrypting each alert end-to-end against your subscription's keys — Apple's, Google's, or Mozilla's push service relays bytes it cannot read. Those three are the only services the Mac will deliver to.
Browsers put conditions on this, and they are worth knowing up front:
The origin must be one the browser fully trusts, because a service worker will not run anywhere else. This site qualifies. Reaching a Mac directly never did, which is one of the things the relay fixed.
On iOS, push is offered only to an installed web app: share sheet → Add to Home Screen, then open it from there.
A subscription belongs to the grant that made it. Revoke the device on the Mac and its alerts stop.
In the native app
The bell in the iPhone app registers a native push token against the same device grant. Its lock-screen copy names only the alert type, such as a session needing you or all jobs having finished. No session name, project name, transcript, account credential, or session identifier passes through Expo or Apple. Opening the app fetches the real state over Saggar's end-to-end encrypted channel.
The Mac sends native alerts only to Expo's one fixed endpoint, and a revoked grant loses its native subscription with its browser ones. In the iPhone app's Settings, you can turn needs-you, finished, failed, ready-for-review, program, and all-jobs-finished alerts on or off independently.
Only when you are away
By default the phone stays quiet while you are at the Mac. The Mac counts itself attended for a minute after your last keystroke or mouse movement anywhere, not only in Saggar, and treats a locked screen as away at once. Switch the phone app's setting to Always to hear every alert regardless.
A prompt is owed to you until it is answered. If an agent asks for approval while you are at the Mac and you walk away without answering, the phone hears about it on the beat the Mac decides you have gone, not never. Finished and failed alerts are not carried over: the Mac banner already said them, and nothing is waiting on you.
Local notifications
Separately from push, an open companion page can raise an ordinary browser notification when a session needs you, is ready for review, or raises a notice. That needs nothing but notification permission, which the page asks for once, right after pairing.
Everything here rides on a pairing. Pair a device first.