fix(push): make iOS background delivery actually work

[nannant666]

Problem

On a real iOS home-screen web app (iOS 16.4+ PWA), background web pushes never arrived: notifications only appeared while the app had just been backgrounded, and stopped completely after a while.

Investigation on production subscriptions (real web.push.apple.com endpoints) found three independent causes, all server/SW-side — the client subscription was never the problem:

1. Every send was rejected by Apple: 403 BadJwtToken

sendNotification used subject: "mailto:pi-web@localhost". Apple's web push service requires the VAPID subject to be a syntactically valid mailto: or https: URL; pi-web@localhost is not resolvable/valid and Apple answers 403 {"reason":"BadJwtToken"} for every request. Same subscription, same keys — changing only the subject to a valid HTTPS URL flips the response from 403 to 201:

A1 subject=mailto:pi-web@localhost  → ❌ 403 BadJwtToken
A2 subject=https://github.com/agegr/pi-web → ✅ 201

So background delivery never worked at all; users only ever saw the in-page new Notification() path (which works while the page is alive, masking the breakage).

2. The SW suppressed notifications for visible windows → iOS revokes the subscription

sw.js skipped showNotification whenever any app window was visible ("in-page path handles it"). Per Apple's docs and WebKit's Declarative Web Push post, handling a push without showing a notification revokes the push subscription — "for any reason", including "situations that are not the script author's fault".

Consequence: every session completion that the user watched in the foreground poisoned the subscription a little, until background delivery died entirely. This matches the classic reports ("works for a bit, then stops; opening the PWA floods queued notifications"). Worse, iOS does not fire pushsubscriptionchange, and APNs keeps returning 201 for revoked endpoints (see WebKit bug 319865), so the server prunes nothing and sees no error.

The SW now always shows the notification. Same-tag notifications replace each other instead of stacking, so a visible window simply sees the completion notification re-appear — no spam, no poisoned subscription.

3. No Urgency/TTL: iOS may defer delivery arbitrarily

Sends carried no Urgency and no explicit TTL. Apple's docs: to attempt immediate delivery, specify Urgency: high; omitted defaults to normal, which iOS may defer to a later device-activation window. Sends now use urgency: "high" + TTL: 2419200 (4 weeks, the web-push default made explicit).

Also: manual registration in Settings → General

iOS requires the Notification.requestPermission() call to happen inside a user gesture, and after a home-screen re-install the old code had no path to re-subscribe (the automatic trigger only ran after a task completion, and never surfaced the permission prompt itself). This adds a small "register push" control to Settings → General (next to the language section) that reuses setupPushSubscription() — it re-triggers the permission prompt when needed and re-registers the subscription with the server. This also doubles as a self-repair path for silently-revoked subscriptions, which iOS never signals (pushsubscriptionchange is not fired).

Testing

• node --test: push/sw suites 15/15 (updated SW tests assert the always-show behavior; new tests assert PUSH_OPTIONS immediacy and that the default subject is a valid URL that doesn't end in @localhost)
• npm run lint clean, tsc --noEmit clean
• Full suite: 931/932 — the single failure (lib/worktree.test.mjs "main and linked worktrees share one canonical project root") also fails on unmodified main in this environment (git-environment dependent), unrelated to this change
• End-to-end on a production deployment (patched build of 0.8.11 + real iPhone home-screen PWA, iOS 18.x): server sends now return 201; lock-screen notifications arrive while the app is frozen in background; the settings control successfully (re)registers the subscription after a home-screen reinstall

Notes for reviewers

• PI_WEB_PUSH_SUBJECT env var overrides the default subject for self-hosters who want their own contact URL.
• Deliberately did not switch the payload to Declarative Web Push (iOS 18.4+): it is a larger format change and the SW path works once the subscription isn't poisoned — happy to follow up if desired.