Merge branch 'main' of git.arirex.me:iris/ai-app

PLAN.md

@@ -647,6 +647,37 @@ connectivity/lifecycle. The app keeps no persistent transcript store — the
 backend's transcript is the source of truth; the app caches only for the
 screen it's showing.
 
+### Notifications: two places, never both (decided 2026-08-30)
+
+The backend's `GET /notifications` is one SSE stream of attention-wanting
+moments, and the app decides where each one is said. Three outcomes, in one
+place (`NotificationService.show`):
+
+- **Nothing at all** if the session is the one on screen. The transcript in
+  front of the reader is already saying it.
+- **A banner over the app** if the app is up — `SessionAlerts`, queued, one
+  per session replacing that session's own, dismissable by a push in either
+  direction, and otherwise retiring itself when the bar across its foot runs
+  out. Tapping one opens the session, through the same path a tapped
+  notification uses.
+- **A row in Android's drawer** otherwise, which is what the foreground
+  service exists for.
+
+Never two of them for one moment. A notification that has already been shown
+in the app is not something to also find in the shade afterwards, and a
+drawer that fills up behind an app that showed you each one is a drawer
+nobody reads.
+
+Which of the three applies is answered without a flag anybody has to keep
+level: the session on screen is registered by the one composable that draws
+one, and "the app is up" *is* the banner queue being collected, since it
+collects only while it is on screen.
+
+The alternative considered and rejected was giving the app its own
+connection to `/notifications` while it is in front. That is a second stream
+per device saying the same thing, and it puts the "which of these two shows
+it" decision in two processes' worth of code instead of one function.
+
 ### Deferred polish
 
 Noticed and deliberately not fixed yet, so they are not re-found from