Skip to content

fix(notifications): one OS toast per event, only while the user is away - #12969

Merged
bolichen97 merged 2 commits into
mainfrom
fix/os-notification-double-banner-focus-gate-3521
Sep 23, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/os-notification-double-banner-focus-gate-3521

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

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.

  1. One approval, one banner. useWebSocket.ts'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. 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.
  2. No banner over a focused window. useNativeNotification fired 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 on isWindowAway(). For the gate to hold for approvals, the approval frame 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.
  3. One spelling of "away". New website/src/hooks/windowAway.ts: isWindowAway() = document.hidden || !document.hasFocus() (no document = away). chatCompleteNotify.ts (which spelled the same predicate inline) and NotificationBanner.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; deadKeys baseline unchanged). docs/system-specs/modules/app-notifications.md gains an "OS toast (client)" section; the notifications bullet in website/electron/permission-handler.js no longer names an approval constructor in useWebSocket.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-effort requestPermission() 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 verdict

Site Event Tag Verdict
src/hooks/useNativeNotification.ts any new unacked, unsilenced feed note (approvals included, via the approval frame's addNotification) approval_id / job_id / task_id / kirocrew-notif kept, now gated on isWindowAway() -- the single constructor for feed notes
src/hooks/useWebSocket.ts approval case same approval kirocrew-approval deleted -- second constructor for the same event, different tag; the case now relays its feed note to the in-app banner instead (see Other)
src/hooks/useWebSocket.ts chat_done finished background chat, opt-in (mc-notify-chat-complete, default OFF) kirocrew-chat-done:<slot> unchanged -- already away-gated via shouldNotifyOnChatComplete (now through isWindowAway()); not a feed note (TURN_DONE_KIND has no Redux entry), so no overlap with row 1
electron/auto-update.js x3, electron/ipc-registrar.js main-process updater nudges / IPC relay n/a out of scope -- Electron main Notification, not the renderer's page-context API

Backend check: ApprovalCoordinator.request (src/kiro_crew/dashboard/interaction_coordinator.py) emits exactly one approval frame and no separate bus notification for it, so the feed gains exactly one entry per approval and row 1 fires at most once.

Every document.hidden / document.hasFocus() reader in website/src, with verdict

Reader Purpose Verdict
hooks/useNativeNotification.ts OS toast gate now isWindowAway()
hooks/chatCompleteNotify.ts:72 OS toast gate converted to isWindowAway()
components/notifications/NotificationBanner.tsx:184 in-app banner windowFocused converted to !isWindowAway()
hooks/useWebSocket.ts:1824, :2421, :2802 passive read-relay gates (!hidden && hasFocus() && isSlotRenderedVisibly) excluded -- they decide "mark as read", not "announce"; coupling relay semantics to the notification helper would let a future notification-only change move read state
hooks/useWebSocket.ts:958, :2785-2791 workflow-run heal on reveal; focus tracking sendFocus excluded -- single-axis hidden on purpose (visibility transitions, not attention)
pages/members/MembersPage.tsx:1677-1679 page-visible state for the crew page excluded -- component state, not a notification surface
hooks/usePushToTalk.ts:357, utils/popoutController.ts:284, :306 disarm PTT / pause popout on hide excluded -- single-axis hidden on purpose

Tests

New website/src/test/nativeNotificationAwayGate.test.ts (11 tests). Red on base: 5 of 11 fail on origin/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 the hasFocus() 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.mjs all 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 second new Notification() on the producing path is a duplicate by construction unless it reuses the exact same tag.

Rule candidate: an attention predicate ("is the user looking?") is spelled once and imported. document.hidden alone 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.ts on their own spelling -- they decide read state, not announcements, and share the helper only by coincidence of predicate.

Other

  • Approvals now reach the in-app banner. The approval frame's addNotification was never paired with dispatchLiveNotification, 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 a notification frame (suppressed during reconnect catch-up), and the note carries the owning slot so the banner's existing targetsCurrentView gate skips it while that chat and its inline permission card are on screen; an unowned approval (no slot) banners on every surface. Pinned in useWebSocket.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).
  • Fork PR feat(notifications): Web Push for the notification bus #7821 rewrites useNativeNotification.ts for Web Push and will conflict textually with this change; it does not address either defect.
  • PRs fix(dashboard): relay a pane's native notifications to the main frame #12843 / fix(desktop): unblock macOS notifications for panes and local builds #12886 refactor the same two constructor sites behind a nativeNotify helper (pane relay). Whichever lands first, the other rebases; neither removes the duplicate constructor or adds the gate.

@CrysisDeu
CrysisDeu requested review from a team and patrigao September 23, 2026 01:55
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 23, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 ships

Inventory (9 items) — 9 justified

Intent: 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).

  1. A hidden window shows one banner per approval, not two — justified
  2. No OS toast while the window is visible and focused; a note seen while focused is never re-announced — justified
  3. Approvals now raise the in-app banner for a focused user on another surface — justified
  4. The approval toast carries the note's own title/body instead of generic "Approval Required" — justified
  5. One shared "away" predicate (windowAway.ts) replaces two inline spellings — justified
  6. Two dead catalog keys removed from 13 locales — justified
  7. The approval note carries its owning slot so the banner skips the on-screen chat — justified
  8. Spec doc gains the "OS toast (client)" section — justified
  9. Approval banners stay silent during reconnect catch-up replay — justified

[FIRST-PRINCIPLES-REVIEWED] 5a3dfe7

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- website/src/components/notifications/NotificationBanner.tsx:186 -- "windowFocused: !isWindowAway()" still admits away arrivals, queueing an in-app banner alongside the OS toast -> Fix: return early when isWindowAway() is true.
[GPT-REVIEWED] 5a3dfe7

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5a3dfe7

Verdict parsed from the review's SHA-scoped output markers for commit 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988: <one-sentence reason>

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.
@CrysisDeu
CrysisDeu force-pushed the fix/os-notification-double-banner-focus-gate-3521 branch from 273e5e3 to 5a3dfe7 Compare September 23, 2026 02:23
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for 273e5e3b2fbc66b85d51f8c4dbe7705e3bc70068; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 273e5e3b2fbc66b85d51f8c4dbe7705e3bc70068: <one-sentence reason>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5a3dfe7f4d21a966e9809d0e83ded1ecdac4d988: <one-sentence reason>

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 23, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after verified readiness: passed, PR Readiness success on this head, mergeable, no open change requests. [operator: bolichen97 batch review 2026-09-23]

@bolichen97
bolichen97 merged commit 867f2a2 into main Sep 23, 2026
97 of 106 checks passed
@bolichen97
bolichen97 deleted the fix/os-notification-double-banner-focus-gate-3521 branch September 23, 2026 04:38
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 23, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants