Alerts and push
Two different mechanisms, for two different situations: a stream that keeps an open page current, and web 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. 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 an
authenticated request mints a single-use, 60-second ticket and only that
appears in the query string. Dropped connections mint a fresh one 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 the bell in the companion's header. Tap it and the browser subscribes; the Mac becomes its own push sender, encrypting each alert end-to-end against your subscription's keys — Apple's or Google's push service relays bytes it cannot read.
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.
Local notifications
Separately from push, an open companion page can raise an ordinary browser notification when an alert arrives. That needs nothing but notification permission, which the page asks for once.
Everything here rides on a pairing. Pair a device first.