feat(notifications): tell me when a turn finishes

[JairEsk]

Roxy goes quiet when the agent finishes: the only way to know a turn is done is to sit and watch it. This adds a completion notification -- a chime plus a native OS toast that opens the session it fired for.

The setting is one switch

The first pass had four controls -- a never/unfocused/always picker, a sound toggle, a toast toggle, a volume slider -- plus a file picker for a custom sound. That is a lot of surface for one question ("tell me when it's done"), and most of the combinations it allows (toast but no sound, sound only when unfocused) are decisions nobody wants to make about a chime.

So: notifyOnComplete, one row, defaults on. It is a key in the existing key-value settings table, so there is no migration -- getSettings reads the row as on when absent.

Staying quiet while the window is focused is not a preference either -- it is what the feature should always do -- so it lives in shouldNotify. hasFocus() rather than document.hidden, because a window sitting visible behind the editor is still one you are not watching.

Volume is a constant (NOTIFY_VOLUME = 0.7). The chime is mastered at -6 dBFS, so it lands near -9 -- audible over an editor, not startling. Per-app volume is the OS's job; if the number is wrong the fix is to change it, not to hand everyone a slider.

There are no custom sound files, and so no copy-into-userData dance, no path-traversal guard, no size cap, no extra IPC channels. The Play button earns its place: it is the only way to hear what you signed up for, and the click doubles as the gesture that unlocks Chromium's autoplay policy -- which is also why it is never disabled, since the person who just switched notifications on and touched nothing else is exactly the one who needs to make that gesture.

Split across the two processes

• The sound plays in the renderer. The main process has no audio output at all. One reused Audio element, so rapid completions restart the chime instead of stacking copies. Never throws -- a locked autoplay policy must not take the turn's cleanup down with it.
• The toast is posted from main. The renderer's Web Notification also reaches the OS, but gives no way to focus the window on click, which is the entire point.
• Whether to notify is the renderer's call, because only it knows whether the user stopped the turn, whether a queue is still draining, and whether the window is focused. The trigger reads the queue before draining it: drainQueue awaits the whole chain it starts, so notifying after would fire once per queued prompt as the recursion unwound.

Clicking the toast lands on the right session

The toast carries the chat id; main sends notify:activated back on click so the renderer selects that session. Raising the window is not enough -- it comes back on whatever was last open, which is exactly the session you were not notified about. If the session was deleted in between, the handler refreshes and bails rather than blanking the view.

The window it raises is the one createWindow registers, not getAllWindows()[0]: the agent browser opens its own BrowserWindow with the same preload, so the first entry can be a browser window, and a click would then raise that and send the event to a renderer with no handler for it. The rest of main broadcasts to every window, which is right for a data push and wrong here -- this handler focuses what it sends to.

Shown Notifications are held in a Set, because one that nothing references can be garbage collected along with its click handler while the toast is still live in the Action Center. The set is capped at 20, oldest evicted first: close does not reliably fire for a toast dismissed from the Action Center, so an uncapped set would retain one Notification per completed turn forever. Windows keeps roughly 20 toasts per app anyway, so what gets evicted is already unclickable.

macOS presentation and behavior

• No duplicate/misplaced icons: On macOS, the squircle icon badge on the left is managed exclusively by the OS from the application's .app bundle. Electron's options.icon maps to contentImage, which macOS places on the right edge of the banner as an attachment preview. We omit icon on macOS so that only the clean, native app badge on the left is displayed. In development (npm run dev), predev.mjs copies build/icon.icns into node_modules/electron/dist/Electron.app so even unbundled dev runs display Roxy's icon instead of the default Electron atom; packaged production builds (Roxy.app) receive this automatically via electron-builder.
• Focus theft: BrowserWindow.focus() only raises a window within the frontmost app. On macOS the frontmost app is the editor you were working in, so the window came forward behind it and the click looked ignored. app.focus({ steal: true }) brings the entire application forward when the user clicks the toast.
• Reopening closed windows: window-all-closed deliberately does not quit on darwin, so Roxy can sit in the dock with no window at all while its toasts sit in Notification Center. Clicking one reopens a window through createWindow.
• Race-free session navigation: To get the session id to a newly spawned window on macOS without races, main holds the pending id and the preload pulls it (notify:takePending) when onActivated registers.

Windows presentation

The toast is titled with the session name -- with several sessions running, which one finished is the only thing you need from it, and the Windows header above already says Roxy. The app icon goes through a ToastGeneric template with appLogoOverride hint-crop="circle"; Electron's icon option is ignored for that slot. Text is XML-escaped, and the file:/// src is encodeURI'd because the app can sit under a path with spaces (a user folder like "Jair Escamilla") and an unencoded space silently drops the image.

The AUMID is set with app.setAppUserModelId directly rather than @electron-toolkit/utils, which substitutes process.execPath in dev -- Windows prints the AUMID verbatim as the toast header, which is how a full C:\Users\... path ended up above every notification.

silent: true always, on all platforms: Roxy plays its own chime, and letting the OS add its default alert on top makes two noises for one event.

Testing

• npm run typecheck (node + web)
• npm run smoke:app, npm run smoke:shared (1079 checks), npm run smoke:store
• npm run smoke:i18n -- 18 checks, all 590 keys resolve in en and es; npm run i18n reports every catalog in sync
• npm run format:check
• Verified on Windows and macOS: toasts show the session name, trigger the chime, and clicking them raises the window directly on that session.