Alerts and push

Two different mechanisms, for two different situations: a stream that keeps the open app current, and push, which reaches a phone in a pocket.

While the app is open

The Saggar phone app 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 push alike. When no heartbeat has arrived recently, which usually means the Mac went to sleep, the app says so.

The stream is bought with a ticket rather than a token: a bearer token must never appear in a URL, and a server-sent events stream 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 app returns to pairing rather than showing a live-looking screen that refuses everything.

Lock-screen alerts

The bell in the app registers a native push token against the 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 alerts only to Expo's one fixed endpoint, and a subscription belongs to the grant that made it: revoke the device on the Mac and its alerts stop. In the 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.

Everything here rides on a pairing. Pair a device first.