Repository navigation
fix(notifications): one OS toast per event, only while the user is away - #12969
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify once on a real OS/packaged app that a hidden window shows exactly one approval banner — happy-dom can't exercise real notification-center behavior. [DESIGN-REVIEWED] 5a3dfe7 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify #3521 itself frames the focused-window toast as a defect — the defect/feature split there is the one provenance this review could not open. What this change shipsInventory (9 items) — 9 justifiedIntent: stop one approval producing two OS banners and stop OS toasts firing over a window the user is watching — a FIX (issue #3521's defect half).
[FIRST-PRINCIPLES-REVIEWED] 5a3dfe7 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsFINDING -- website/src/components/notifications/NotificationBanner.tsx:186 -- False positive or not applicable? A repository writer can comment: |
UX Review (Fable 5) — ✅ PASSUX-level review of UX-Verdict: PASS Verify a focused-window approval on another surface actually raises the in-app banner with its Review action — no capture shows this newly wired interrupt path. [UX-REVIEWED] 5a3dfe7 |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
The socket layer's `approval` case constructed its own page-context `Notification` (tag `kirocrew-approval`) and then dispatched `addNotification`, whose count increase made `useNativeNotification` construct a second one (tag `approval_id`). The OS collapses only equal tags, so a hidden window showed two banners for one approval. Delete the socket constructor: the feed entry is what reaches the OS, with the note's own title/body and a stable tag. `useNativeNotification` fired on every unacked arrival with no visibility check, so a note the in-app surfaces already showed also raised an OS banner over the focused window. Gate the constructor on the shared `isWindowAway()` (`document.hidden || !document.hasFocus()`), the same predicate the in-app banner and the chat-complete toast read, so a live note lands on exactly one surface. The best-effort permission prompt stays independent of focus. Remove the two catalog keys the deleted constructor used (13 catalogs), extend the existing toast tests to run in a hidden window, and pin both behaviours in nativeNotificationAwayGate.test.ts.
…age test follows the single constructor With the OS toast quiet for a focused window, an approval arriving while the user works on another surface had no visible interrupt: the socket layer never relayed its feed note to the in-app banner, so only the bell badge and the chime moved. Pair the approval `addNotification` with the same live relay the `notification` frame uses (suppressed during a reconnect catch-up), and carry the owning slot on the note so the banner's `targetsCurrentView` gate skips it while that chat and its inline permission card are on screen. Unowned approvals carry no slot and banner on every surface. UseWebSocketCoverage pinned the socket layer's own approval constructor; it now asserts the feed entry lands and the socket constructs nothing.
273e5e3 to
5a3dfe7
Compare
GPT 5.6 Review —
|
GPT 5.6 Review —
|
bolichen97
left a comment
There was a problem hiding this comment.
Approved after verified readiness: passed, PR Readiness success on this head, mergeable, no open change requests. [operator: bolichen97 batch review 2026-09-23]
…ay (kirodotdev#12969) * fix(notifications): one OS toast per event, only while the user is away The socket layer's `approval` case constructed its own page-context `Notification` (tag `kirocrew-approval`) and then dispatched `addNotification`, whose count increase made `useNativeNotification` construct a second one (tag `approval_id`). The OS collapses only equal tags, so a hidden window showed two banners for one approval. Delete the socket constructor: the feed entry is what reaches the OS, with the note's own title/body and a stable tag. `useNativeNotification` fired on every unacked arrival with no visibility check, so a note the in-app surfaces already showed also raised an OS banner over the focused window. Gate the constructor on the shared `isWindowAway()` (`document.hidden || !document.hasFocus()`), the same predicate the in-app banner and the chat-complete toast read, so a live note lands on exactly one surface. The best-effort permission prompt stays independent of focus. Remove the two catalog keys the deleted constructor used (13 catalogs), extend the existing toast tests to run in a hidden window, and pin both behaviours in nativeNotificationAwayGate.test.ts. * fix(notifications): approval frame relays to the in-app banner; coverage test follows the single constructor With the OS toast quiet for a focused window, an approval arriving while the user works on another surface had no visible interrupt: the socket layer never relayed its feed note to the in-app banner, so only the bell badge and the chime moved. Pair the approval `addNotification` with the same live relay the `notification` frame uses (suppressed during a reconnect catch-up), and carry the owning slot on the note so the banner's `targetsCurrentView` gate skips it while that chat and its inline permission card are on screen. Unowned approvals carry no slot and banner on every surface. UseWebSocketCoverage pinned the socket layer's own approval constructor; it now asserts the feed entry lands and the socket constructs nothing.
Fixes the defect half of #3521 (the two defects below). The feature half of that issue -- an independent bell/OS switch with per-category control, and turn completion delivered to the OS -- is a product addition, not a defect, and is left open on the issue.
What
Two changes to how a feed notification becomes an OS toast, plus one shared predicate.
useWebSocket.ts'sapprovalcase constructed its own page-contextNotification(tagkirocrew-approval) and then dispatchedaddNotification, whose count increase madeuseNativeNotificationconstruct a second one (tagapproval_id). The OS collapses only equal tags, so a hidden window showed two banners for one approval. The socket constructor is deleted; the feed entry is what reaches the OS, with the note's own title/body (Tool approval: Bash, the redacted command excerpt) and a stable per-approval tag.useNativeNotificationfired on every unacked arrival with no visibility check, so a note the in-app surfaces (bell badge, in-app banner, inline approval card) already showed also raised an OS toast on top of them. The constructor is now gated onisWindowAway(). For the gate to hold for approvals, theapprovalframe now also relays its feed note to the in-app banner (it never did), so a focused user on another surface gets the banner where the away user gets the toast.website/src/hooks/windowAway.ts:isWindowAway() = document.hidden || !document.hasFocus()(nodocument= away).chatCompleteNotify.ts(which spelled the same predicate inline) andNotificationBanner.tsx(windowFocused, its complement) read it too, so a live note lands on exactly one of the two surfaces and the three cannot drift.The two catalog keys only the deleted constructor used (
hooks.useWebSocket.approval_required,hooks.useWebSocket.a_task_needs_your_decision) are removed from all 13 catalogs that held them (en.json never had them;deadKeysbaseline unchanged).docs/system-specs/modules/app-notifications.mdgains an "OS toast (client)" section; thenotificationsbullet inwebsite/electron/permission-handler.jsno longer names an approval constructor inuseWebSocket.ts.Why
An OS toast is a surface for a user who is not looking at the app. Two constructors for one event doubled the banner; no visibility gate tripled the focused-window announcement. Both are defects in the existing delivery, not the missing feature: #8312 (permission grant in the packaged app) and #12670 (permission request from Settings, in-app banner) made the toasts real, which is what made the duplicate and the focused-window banner visible.
The gate sits inside the
permission === 'granted'branch on purpose: the best-effortrequestPermission()on an undecided permission is about capability, not attention, and must not depend on where the window is (pinned by a test).How
Every
new Notification()constructor site (renderer + main), with verdictsrc/hooks/useNativeNotification.tsapprovalframe'saddNotification)approval_id/job_id/task_id/kirocrew-notifisWindowAway()-- the single constructor for feed notessrc/hooks/useWebSocket.tsapprovalcasekirocrew-approvalsrc/hooks/useWebSocket.tschat_donemc-notify-chat-complete, default OFF)kirocrew-chat-done:<slot>shouldNotifyOnChatComplete(now throughisWindowAway()); not a feed note (TURN_DONE_KINDhas no Redux entry), so no overlap with row 1electron/auto-update.jsx3,electron/ipc-registrar.jsNotification, not the renderer's page-context APIBackend check:
ApprovalCoordinator.request(src/kiro_crew/dashboard/interaction_coordinator.py) emits exactly oneapprovalframe and no separate busnotificationfor it, so the feed gains exactly one entry per approval and row 1 fires at most once.Every
document.hidden/document.hasFocus()reader inwebsite/src, with verdicthooks/useNativeNotification.tsisWindowAway()hooks/chatCompleteNotify.ts:72isWindowAway()components/notifications/NotificationBanner.tsx:184windowFocused!isWindowAway()hooks/useWebSocket.ts:1824, :2421, :2802!hidden && hasFocus() && isSlotRenderedVisibly)hooks/useWebSocket.ts:958, :2785-2791sendFocushiddenon purpose (visibility transitions, not attention)pages/members/MembersPage.tsx:1677-1679hooks/usePushToTalk.ts:357,utils/popoutController.ts:284, :306hiddenon purposeTests
New
website/src/test/nativeNotificationAwayGate.test.ts(11 tests). Red on base: 5 of 11 fail onorigin/main(focused window constructs a toast; hidden-window approval constructs 2 not 1; socket layer alone constructs 1 not 0; a focused arrival is re-announced), 6 pass (pure predicate cases and behaviours already correct). Mutation checks, each killed by a named test: drop thehasFocus()axis -> "visible window behind another application" fails; move the gate outside the permission branch -> "still asks for permission from a focused window" fails; restore the socket constructor -> "the socket layer alone constructs no toast" fails.Existing toast tests now run in a hidden window (happy-dom's default is the focused state):
UseWebSocketCoverage.test.tsx(the approval case asserts the feed entry lands and the socket constructs no toast),notificationSilentOptions.test.ts(the approval case mounts both hooks and pins ONE silent toast),notificationConstructorGuard.test.ts(the throwing constructor is reached through the feed path),useNativeNotificationMuted.test.ts,integration/AppNotification.integration.test.tsx. Also run by path:chatCompleteNotify.test.ts,NotificationBanner.test.tsx,i18n/deadKeys.test.ts,i18n/catalogParity.test.ts-- 9 files, 165 tests green. Static gates:tsc -b --force, eslint on the changed files,i18n-check.mjs(I18N_BASE_REF=main),check-i18n-keys.mjs,check-i18n-strings.mjsall exit 0.Why no screenshot: the changed surface is the OS notification center (a banner count of 2 -> 1, and 1 -> 0 over a focused window); nothing the dashboard renders changes, and an OS banner cannot be captured from a headless Linux Playwright run. The measurable evidence is the constructor count in the tests above.
Pattern harvest
Rule candidate: one event, one OS-toast constructor. When an event already lands in the notification feed, it reaches the OS through
useNativeNotification; adding a secondnew Notification()on the producing path is a duplicate by construction unless it reuses the exact sametag.Rule candidate: an attention predicate ("is the user looking?") is spelled once and imported.
document.hiddenalone reports an occluded or unfocused window as visible; every surface that reads it alone will eventually announce over the screen it describes.Not generalizable: the choice to keep the read-relay gates in
useWebSocket.tson their own spelling -- they decide read state, not announcements, and share the helper only by coincidence of predicate.Other
approvalframe'saddNotificationwas never paired withdispatchLiveNotification, so with the OS toast quiet for a focused window a blocking approval on another surface had only the badge and the chime. The frame now relays its feed note to the banner exactly like anotificationframe (suppressed during reconnect catch-up), and the note carries the owningslotso the banner's existingtargetsCurrentViewgate skips it while that chat and its inline permission card are on screen; an unowned approval (no slot) banners on every surface. Pinned inuseWebSocket.liveNotification.test.ts(+4: live relay with slot, unowned relay without slot, gate verdicts per surface, reconnect silence; the two relay tests are red without the wiring).useNativeNotification.tsfor Web Push and will conflict textually with this change; it does not address either defect.nativeNotifyhelper (pane relay). Whichever lands first, the other rebases; neither removes the duplicate constructor or adds the gate.