feat: notify when a chat needs input (desktop + web)

[radroid]

Closes #11

What

Fires a notification when a chat transitions into a state that needs you — approval requested, agent question (waiting for input), or turn finished — on both surfaces:

• Desktop (Electron): native OS notification from the main process. Clicking it reveals/focuses the window and navigates to the chat.
• Web (desktop or mobile browser): Web Notifications API from the client (works for background tabs, e.g. phone browser over Tailscale). Clicking focuses the tab and navigates to the chat.

How

• Detection rides the existing projectThreadAwareness() phase ladder (@t3tools/shared/agentAwareness) — the same source of truth the mobile push pipeline uses. A pure edge-detecting tracker (apps/web/src/notifications/needsAttention.logic.ts) diffs phases across thread-upserted shell updates: fires on transitions into waiting_for_approval / waiting_for_input, and on running → completed only (which also kills the spurious "Done" at thread birth). First observation of a thread never fires, so reloading with an already-waiting thread stays silent.
• One coordinator for both surfaces: Electron renders the same web bundle, so a single <NotificationCoordinator/> in the root route watches all threads across all connected environments and dispatches through a platform shim — desktopBridge.showNotification(...) when present, else new Notification(...) (guarded: Android Chrome's page-scope constructor throw is swallowed).
• Desktop IPC: new desktop:show-notification / desktop:notification-activated channels, an ElectronNotification Effect service (coalesces per-thread via the request id, retains live references), preload bridge members typed in @t3tools/contracts (optional, so older shells hosting newer bundles degrade to the web path).
• Suppression: no notification when the tab/window is focused and that exact chat is on screen (including the draft route right after promotion). Different chat on screen → still notifies.
• Settings: notifyOnNeedsInput client setting (default on), row in Settings → General ("Notify when an agent needs input"). On web, enabling requests browser permission from the toggle gesture; a denied permission shows an inline hint; a once-per-session toast nudges permission when a notification would have fired but permission was never asked.

Out of scope (per issue): Web Push for closed tabs (needs service worker + push infra; iOS Safari additionally requires an installed PWA).

Testing

• Unit: 40+ new tests across the tracker (every behavior rule + mutation-tested edges), the notifier shim (platform routing, constructor-throw guard), coordinator pure helpers (input building/dedupe, activation params), permission-prompt truth table, contracts decode defaults, and the Electron service/IPC method (fake-Electron harness: click→reveal→broadcast, coalescing, unsupported guard). Full suites green: web 172 files / 1505 tests, desktop 53 / 377, contracts 202. Typecheck + lint clean on all touched packages.
• Live end-to-end (real browser, real Claude CLI turns, isolated --home-dir instance): turn-completion and agent-question notifications fire exactly once with correct title/body/tag while the tab is genuinely blurred; startup grace on reload; suppression when viewing the firing chat (and the converse — other-route transitions do notify); settings toggle gates and persists; notification click navigates to the right thread. Re-smoked after the final fix wave.
• Desktop: pnpm build:desktop + pnpm test:desktop-smoke pass. (Native notification click path is unit-tested via fakes; not OS-driven e2e.)

Review process

Built task-by-task with per-task spec+quality reviews, a final whole-branch review, and a verified fix wave (notably: Android Chrome constructor guard, desktop Notification Center coalescing, draft-route suppression). Known accepted edges: notifications for since-deleted threads navigate to a dead route; a macOS click with zero open windows doesn't recreate one; permission state in the settings panel refreshes on interaction, not on browser-chrome changes.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 414baf24-9726-445c-833e-17e65b3ea373

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/chat-input-notifications

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}