[devswha]

What

Pane alerts (agent blocked / done, terminal ended) now reach a device with the app closed. Tapping the bell on a device served over HTTPS subscribes it to Web Push. On iPhone this needs the home-screen app, iOS 16.4+. A confirmation push ("Alerts are on for this device") checks the whole path end to end. Without push support the bell falls back to the old tab-only alerts, and its title says which of the two you have.

How

Server (server/push.ts)

• Builds each request with web-push's generateRequestDetails (RFC 8291 aes128gcm + RFC 8292 VAPID) and sends it with fetch. sendNotification isn't used: it goes through node:https and a proxy agent.
• The VAPID key pair and the subscriptions persist in HERDR_WEB_STATE_DIR (default ~/.config/herdr-web-ui), owner-only, written atomically.
• A malformed key file is an error, not a silent rotation, because every subscription is bound to that key. A 404/410 from a push service drops the subscription.
• The alert policy lives in shared/notify-policy.ts, so the tab and the server fire on the same transitions.
• The collector now reports every pane from each reconcile (onBaseline), so the first change after a server restart still alerts. Without it, that change would count as a "first sighting" and be dropped.
• Routes, all behind the token gate: GET /api/push, POST|DELETE /api/push/subscribe, POST /api/push/test.
• Payload { pane_id, title, body, tag }, TTL 12h, Urgency: high for blocked.
• A broken state file only costs the alert; the rejection is caught, so the server keeps running.

Client (src/lib/push.ts, src/App.tsx, public/sw.js)

• Bell flow: permission → subscribe (reusing an existing subscription, replacing one made for another server key) → register → confirmation push.
• A device that already allowed alerts re-registers on every load (idempotent). Lock unsubscribes the device before signOut.
• The SW shows each push with the pane's tag, silently when a window of the app is visible. It still shows it then, because Safari revokes subscriptions whose pushes show nothing.
• Tap: focus the window and select-pane, or open /?pane=<id>. pushsubscriptionchange re-registers the new endpoint.
• Tab alerts now go through registration.showNotification. Android Chrome has no new Notification(). A device with push skips tab alerts, so it doesn't get the same alert twice.

New dependency: web-push@^3.6.7 (runtime), @types/web-push (dev).

Verification

Check	Result
bun test	86 pass / 0 fail, 11 files
bun run typecheck / bun run build	clean
Mutation: collector never calls onBaseline	restart test fails (first push after restart not received)
Mutation: index.ts doesn't forward status to push	live status test + restart test fail
Mutation: index.ts ignores the baseline	restart test fails
Contract file ×3	29 pass each run
Corrupt push-subscriptions.json probe	server stays up, logs web push: JSON Parse error…
Browser QA (headless Chrome; stand-in PushManager; pushes delivered into the real SW over CDP)	14/14: token gate → bell → confirmation push decrypted → subscription stored 0600 → live status push → SW notification with pane tag/data, silent while visible → App's select-pane listener (synthetic message) → ?pane= open + strip → lock removes the subscription server- and browser-side
Real push service (FCM): headed Chrome under Xvfb, real pushManager.subscribe, no stubs	3/3 runs: FCM endpoint stored; confirmation push arrived through Google's push service in under 300 ms; a live pane going blocked arrived as a notification with its pane tag and data
Browser QA: one subscribe() on the first tap	pass (15/15 total)
Test isolation	every test server uses a temp state dir; ~/.config/herdr-web-ui never created; no leftover test workspaces

The fake push service (server/push.fake.ts) decrypts with an independent RFC 8291 implementation and verifies the VAPID JWT. The tests check the payload a device would actually show.

Found by the real-FCM check (fixed in e429a8d)

The bell's first tap called subscribe() twice: the click, plus the load-time registration that the permission grant starts. Real Chrome issued two different subscriptions and kept only the later one, so the confirmation push often went to the dead endpoint and never arrived (3 of 4 runs). ensurePushSubscription is now single-flight. src/lib/push.test.ts covers it with a stand-in PushManager that, like Chrome, issues a new subscription on every call; without the fix that test fails. After the fix: one subscribe, one endpoint, confirmation delivered 3/3.

Not covered / follow-ups

• The SW's notificationclick handler wasn't executed. CDP can't click a notification, so focusing the window, posting select-pane and openWindow('/?pane=…') were checked by reading the code only. Both ends were exercised separately: App's listener and the ?pane= open.
• Not tested on a phone. Delivery through FCM was verified end to end with a real desktop Chrome (above). APNs (iPhone) and display on a phone still have to be checked by hand: see the README section "Alerts with the app closed".
• A running real server alerts on bun test's own panes. If your real server has devices subscribed, the suite's report_agent calls on herdr-web-ui-test-* panes will reach your phone, the same way tab alerts already did.
• Changing HERDR_WEB_TOKEN doesn't unsubscribe existing devices. This is documented: lock them, or delete push-subscriptions.json.

🤖 Generated with Claude Code