Notifications: tell the user when a session is waiting and when a background job finishes

Provenance stamp: This issue was triaged on September 20, 2026 as part of the older-than-90-days GitHub issue triage exercise.

Source issues: #874, #915

Summary

Plannotator opens a browser tab, then goes quiet. Two old issues report the two halves of that silence: the agent host never says a review is waiting, and the browser never says a background job is done. Both leave the user watching a window that gives no signal, and in the Pi case the host itself looks frozen.

The common requirement is a notification contract: every time Plannotator either needs the user or has finished work the user asked for, it says so through the best channel available — the agent host's own notification surface, or the browser's, never neither.

What the source issues requested

• #874 requested a browser notification when a code review or Code Tour finishes generating, so the user does not have to keep checking the tab while an agent job runs.
• #915 reported that plannotator_submit_plan on Pi opens the browser with no TUI message, so Pi appears frozen while it awaits the decision. On GNOME/Wayland xdg-open does not raise the window either, so there is no cue at all. It proposed notifying from openBrowserForServer on a successful local open.

Triage determination

These were filed a week apart by different users about different surfaces, but they are one gap. Fixing only the host side leaves long agent jobs silent; fixing only the browser side leaves the "is it frozen?" moment intact. A single issue can define when Plannotator notifies, through which channel, and how the user turns it off — and keep the two halves consistent instead of growing two unrelated mechanisms.

Current state verified on main (2026-09-20):

• Zero Web Notification usage repo-wide; no completion toast for agent jobs. Tours auto-open and guides auto-switch on completion (packages/review-editor/App.tsx:1647-1684), which only helps a user already watching the tab.
• Pi notifies only for remote sessions and failed opens (apps/pi-extension/plannotator-browser.ts:196-203). The explicit commands gained an in-turn notice (sessionOpenedMessage, apps/pi-extension/index.ts:184-196), but the plan-review path did not (apps/pi-extension/index.ts:1353-1371) — exactly the case #915 reported.

Acceptance criteria

• Every host that opens a session emits one "review waiting" notice on the successful local path, not only on remote sessions or failures. Pi plan review is the named gap.
• The notice names what is waiting and carries the URL, so it doubles as a recovery path when the tab is closed.
• Background agent jobs (review agents, Code Tour, Guided Review) notify on completion and on failure, from the browser, when the tab is not focused.
• Browser notifications are permission-gated, requested on an explicit user action rather than at load, and never requested in read-only or shared sessions.
• Notification behavior is user-disableable, and off by default wherever requesting permission would be intrusive.
• A focused tab does not double-notify alongside the existing auto-open/auto-switch behavior.
• Host notification channels are documented per runtime (Claude Code, OpenCode, Pi, Codex, Amp, Droid), including which ones have no usable channel.
• #874 and #915 can be closed once their requirements are represented here.

Notes

Adjacent but deliberately separate: #1134 (always surface the review URL; stable port across resubmissions) and #1406 (Pi Web RPC sessions show no URL) are about reachability, i.e. where the URL is printed. This issue is about attention, i.e. being told at all. They should stay consistent but they are not the same change. The smallest useful first step is #915's one-line host notice on the Pi plan path.