Epic: notifications — rock-solid system v2 (tracking)

[Axelj00]

Goal

When an agent needs your attention, exactly one banner fires carrying the agent's actual message. Click it → the originating tab and pane is focused. You never miss the signal. You never get noise.

That's it. That's the bar. This issue tracks getting from "current state" to that bar across all the small bugs and missing pieces that prevent it from being true today.

North-star principles

1. One producer. OSC 9;2 from agents is the only thing that fires a system notification. Everything else (server-started, command-finished, errors) is in-app state, never a banner. (Achieved in notifications: rebuild around OSC 9;2 only — drop server-event noise, fix duplicates, make click-to-tab actually work #547 phases 1+2.)
2. One sink. Every notification flows through NotificationManager.notifyAgentAttention. No parallel code paths that can drift.
3. Suppress when redundant. Active focus → no banner. Mute → no banner. Already-shown-in-the-grace-window → no banner.
4. Surface when invisible. When the user isn't watching, fire — reliably, with the agent's actual message, with a click that gets them back to the right place.
5. Audible only via the OS. No app-side chime; the OS controls notification sound (and respects Focus / DND). (Achieved by the sound-drop commit.)

What's solid today

After #547 and the follow-up sound drop:

• Single producer (OSC 9;2 → notifyAgentAttention)
• No banners on Local: http://localhost:5173 or any matcher event
• No duplicates ("Command finished in X" + "X: <msg>" was firing on every OSC — fixed)
• Mute silences both surfaces (sidebar dot + banner)
• Active-tab suppression
• No Web Audio chime bypassing macOS Focus / DND
• Web Notification API onclick works for live banners

What's still wrong, ranked by impact

#	Issue	Bug or gap	Phase
#548	Native click handler via UNUserNotificationCenter	Click from Notification Center after dismissal is unreliable — the long-standing one	C
#549	Pane-scoped active-tab suppression	Split-pane tabs swallow notifications for non-focused panes	B
#550	Silent failure when OS permission denied	User has no way to discover why nothing fires	B
#551	Per-tab cooldown for runaway OSC	A misbehaving agent can banner-storm	B
#554	"Missed events" tray	Banners are ephemeral; the message text is lost after dismissal	D
#553	Settings UI	Notification controls are config-file-only	D
#552	Non-Claude command completion	Long shell tasks in background tabs go unnotified — pre-existing gap, needs product call	E

Implementation plan — phased so each phase ships independently

✅ Phase A — Foundations (done)

• notifications: rebuild around OSC 9;2 only — drop server-event noise, fix duplicates, make click-to-tab actually work #547 phases 1+2 closed
• Sound drop committed (08ae5a0)

Phase B — Tighten the OSC path (the cheap wins)

Three small fixes, each <100 lines, each independently mergeable:

• notifications: pane-scoped active-tab suppression — split-pane agents go unnoticed #549 — Pane-scoped suppression. Forward the originating Pane through onOscNotification; check focused pane, not just active tab.
• notifications: silent failure when OS permission denied — surface state to user #550 — Permission-denied UX. Detect denial, surface a one-time toast with "Open Settings" deep link; recheck on window focus.
• notifications: per-tab cooldown to prevent runaway-OSC banner storms #551 — Per-tab cooldown. ~4s map of tabId → lastSentAt, drop duplicates within window.

Rationale for ordering Phase B before Phase C: all three are cheap, well-scoped, testable without running the full app. They tighten the OSC path so when we replace the click handler in Phase C, the rest of the system is already correct. Doing Phase C first would mean re-validating these three after the bigger rewrite.

Phase C — Reliable click from Notification Center

• notifications: native UNUserNotificationCenter click handler so NC-after-dismissal click focuses the right tab #548 — Native UNUserNotificationCenter Rust plugin. Owns the delegate; emits notification-clicked Tauri events with tab_id payload.

The big one. Substantial Rust work (objc2 + delegate retention + authorization flow). Needs iterative testing in the running app. Once this lands, click-from-NC-after-dismissal works for the first time ever.

Phase D — Catch up on missed events

After Phase C, the click path is reliable. Now help the user see what they missed.

• notifications: in-app 'missed events' tray — what did I miss while away #554 — In-app notifications tray. Cmd+Shift+N opens a panel listing the last 50 OSC events with message text and click-to-focus.
• notifications: settings UI — current controls are config-file-only #553 — Settings UI. Make notification config discoverable (currently config-file-only). Includes permission status from notifications: silent failure when OS permission denied — surface state to user #550.

These two are loosely coupled — could be parallel. #554 has higher per-effort impact (the tray solves a real "what did I miss" problem); #553 is more polish.

Phase E — Optional, requires product decision

• notifications: command-completion for non-Claude long-running tasks #552 — Notify on non-Claude command completion. Long shell tasks (builds, tests) in background tabs. Pre-existing gap.

Needs a call on whether we want this at all (some users hate completion notifications), and if yes whether opt-in. See the issue for the full design discussion (PID-based vs OSC 133 shell integration).

What "done" looks like

Acceptance for the full vision (achieved when all of B + C + D ship):

1. ✅ Claude OSC 9;2 on background tab → exactly one banner with the agent's message
2. ✅ No banner for any non-agent event (server, error, completion of generic commands unless Phase E ships)
3. ⏳ Click banner (live or in NC after dismissal) → focuses the correct tab + correct pane
4. ⏳ Multi-pane tab: only the focused pane suppresses
5. ✅ Muted tab → silent both surfaces
6. ⏳ Permission-denied → surfaced to user with path to fix
7. ⏳ Banner storms throttled per-tab
8. ⏳ Missed banners recoverable via in-app tray
9. ⏳ Settings discoverable without editing JSON

Sequencing summary

Phase A (done)
   │
   ▼
Phase B  ── #549 ── #550 ── #551  (cheap parallel-friendly fixes)
   │
   ▼
Phase C  ── #548                  (the hard one — iterative testing needed)
   │
   ▼
Phase D  ── #554 ── #553          (quality-of-life)
   │
   ▼
Phase E  ── #552                  (only if we decide we want it)

Notes

• All phases preserve the one-producer, one-sink rule. New features add behavior on top of notifyAgentAttention, never new parallel paths.
• Each sub-issue is self-contained and can be picked up independently. The phase grouping is a recommendation, not a hard dependency (except Phase C → Phase D, where the tray UX is much better if click is reliable).
• macOS-only scope throughout — matches the rest of Clawterm's current targeting.

[Axelj00]

Phase B complete — all three cheap wins shipped:

• ✅ notifications: pane-scoped active-tab suppression — split-pane agents go unnoticed #549 — pane-scoped suppression (62577f9)
• ✅ notifications: silent failure when OS permission denied — surface state to user #550 — permission-denied UX (61228b1)
• ✅ notifications: per-tab cooldown to prevent runaway-OSC banner storms #551 — per-tab cooldown (6e0880e)

Plus the sound drop landed earlier (08ae5a0).

Phase B acceptance from the epic is now ✅ across the board for items in scope: multi-pane fires correctly, denied permission is surfaced + auto-recovers on grant, banner storms are throttled per-tab.

Next up: Phase C — #548 (native UNUserNotificationCenter delegate). That's the substantial one; needs iterative testing in the running app.

[Axelj00]

Big batch of progress today: Phase D (#553 settings UI + #554 missed-events tray) and Phase E (#552 opt-in command-completion) all shipped. Phase B (#549 / #550 / #551) was already in main per the code comments.

Status of acceptance checklist:

1. ✅ Claude OSC 9;2 on background tab → exactly one banner with the agent's message
2. ✅ No banner for any non-agent event (still gated; notifications: command-completion for non-Claude long-running tasks #552 only fires when opted-in)
3. ⏳ Click banner (live or in NC after dismissal) → focuses the correct tab + correct pane — only notifications: native UNUserNotificationCenter click handler so NC-after-dismissal click focuses the right tab #548 remains
4. ✅ Multi-pane tab: only the focused pane suppresses (notifications: pane-scoped active-tab suppression — split-pane agents go unnoticed #549)
5. ✅ Muted tab → silent both surfaces
6. ✅ Permission-denied → surfaced to user with path to fix (notifications: silent failure when OS permission denied — surface state to user #550 + notifications: settings UI — current controls are config-file-only #553)
7. ✅ Banner storms throttled per-tab (notifications: per-tab cooldown to prevent runaway-OSC banner storms #551)
8. ✅ Missed banners recoverable via in-app tray (notifications: in-app 'missed events' tray — what did I miss while away #554)
9. ✅ Settings discoverable without editing JSON (notifications: settings UI — current controls are config-file-only #553)

Only Phase C (#548) remains. Leaving this epic open so it tracks #548 to completion — once that lands the system is at the bar.