[bug] notifyUser has no duplicate suppression — the push `tag` hides the repetition in the tray while every alert still fires

[serge-ivo]

No floor under the notification layer

notifyUser (routes/push.ts:196-206) is the single funnel every notification passes through:

export async function notifyUser(env, userId, type, title, body, url?) {
	await createNotification(env.DB, userId, type, title, body, undefined, url).catch(() => undefined);
	await sendPushToUser(env, userId, { title, body, url, tag: type }).catch(() => undefined);
}

No coalescing, no rate limit, no recent-duplicate check. Whatever a caller asks for, every caller,
every time.

The tag: type argument makes this look solved and is not: a web-push tag collapses the OS
tray visually, so N identical notifications show as one entry — while each still fires its own
alert and sound. And createNotification keeps every copy, so the in-app bell list accumulates all
N. The tray is the only surface that hides the duplication, and it is the one nobody audits.

Why a floor, rather than only fixing the callers

#359 is a caller bug: the deploy watcher polls every workflow in the repo, so one push produced 2–4
notifications and a three-hour session produced 40–80. That bug should be fixed on its own terms and
is.

But it reached the user's phone at full volume because nothing between the bug and the device was
willing to say "I have already sent this". That is the fourth notification defect in this area
(#338, #344, #349, #359); a floor is what makes the next one an annoyance instead of an incident.

Shape

Suppress a push whose (user_id, type, title, body) matches one already sent inside a short window —
minutes, not hours. Two properties matter:

• Suppress the push, keep the row. The in-app list is a log and should stay complete; it is the
  interruption that needs bounding. Same principle as the Push notifications: suppress when user is actively using the app (tab visible / online) #176 visibility gate, which suppresses the
  banner and still forwards the payload so the badge updates.
• The window is a floor, not a policy. It exists to bound a malfunction. Legitimate repeated
  notifications — two different agents needing a CAPTCHA — differ in title/body and are unaffected.

Cheapest implementation is a read of the notifications table notifyUser is already writing to, so
there is no new store and no new state to keep consistent.

Relationship to the others

• [bug] 2-4 "PAGS is live" notifications per push — the deploy watcher polls every workflow and calls a green CI run a deploy #359 — the caller bug this would have bounded. Fix both; neither substitutes for the other.
• Notifications have no per-type mute and no notion of "you caused this" — #176's visibility gate cannot cover your other devices #360 — per-type mute lets the user stop a class of notification. This stops a malfunction
  the user should never have had to notice. Different jobs, both worth having.

Noted originally as the closing section of #359 and split out so it is not lost when that one closes.

[serge-ivo]

Shipped in 5641598 (migration 0093_notification_floor.sql, lib/notifications.ts, notifyUser).

The key is over the EVENT, not the prose. The issue proposed (user_id, type, title, body);
that is the fallback here, not the primary, because prose fails as identity in both directions:

• Same event, different prose. One push to this repo starts several workflows and the run number
  is per-workflow, so the same deploy of the same commit arrives as ✅ Deployed #412 and
  ✅ Deployed #88. A title compare sees two events and buzzes twice — i.e. it would not have
  bounded [bug] 2-4 "PAGS is live" notifications per push — the deploy watcher polls every workflow and calls a green CI run a deploy #359, the bug it is here for.
• Different events, same prose. Two agents stuck on a CAPTCHA on the same site produce
  byte-identical titles. A title compare drops the second, and the second is a run genuinely
  waiting on a human.

So a caller that knows what its event is declares it — deploy:<repo>:sha:<commit>,
coding-handoff:<session>:<reason>:<round>, trigger-skip:<trigger>:offline — and the layer
hashes (type, event) into notifications.dedupe_key. Title+body remains as the weaker key for a
caller that has not declared one, so every caller has a floor from day one.

Suppress the push, keep the row — as specified, and the same split as #176. pushed_at is the
new part: it records whether a copy actually interrupted anyone, so the window is measured
against a real buzz rather than against a row. A genuinely repeating event therefore gets through
once per window instead of being silenced forever by its own first copy, which a
created_at-based window would have done.

Window is 10 minutes — longer than any sweep or retry loop in this codebase (deploy sweep is
per-minute, handoff polls are 5s), short enough that it cannot become a policy about how often the
product may speak.

Both reads (preferences, duplicate probe) fall open on error: a notification must not be lost
because the floor could not be evaluated.

Also landed here: kind (alert | update) on the row, which is what #360's mute is allowed to
hide. Per-call rather than per-type, because coding carries both "🙋 needs you" and "✅ finished".

[serge-ivo]

Re-verified against production today, and the floor is doing what it promised — but it cannot see the
fifth defect in this area, filed as #708.

Measured over 52h: 198 deploy rows for 32 real deploys. The floor suppressed 25 of them — every
one a same-commit re-fire that happened to land inside the 10-minute window. It could never suppress
the rest, because the repeats carry different commits and therefore different event keys: the
deploy watcher's watermark is an equality check that can move backwards (lib/deploy-watch.ts:158
compares, :288-292 writes unconditionally), so a stale GitHub runs page — reproduced live, 1 of 30
identical requests returned a 3½-week-old snapshot — makes the watcher announce an old commit and then
announce the current one again a minute later.

Nothing is wrong with this ticket's shape. The note is only that #338/#344/#349/#359 and this floor
are all about the identity of an event, and #708 is about its order; another identity
mechanism (including the unique index that was proposed) would miss it again. DUPLICATE_WINDOW_MINUTES
should stay at 10 and idx_notifications_dedupe should stay non-unique — #708 argues both, and the
decisive counter-example is SLEEP_NOTIFY_KEY (lib/coding-session-sweeper.ts:396), a constant event
key that a unique index would deliver once per account for all time.