id: PX-RESEARCH-A8255D90
type: research
title: OS Notifier Evolution
Scope
This records notification-design decisions from legacy material against present extensions/os-notifier behavior.
Legacy sources are recoverable from Git commit 88660125c313dd5eff4f8c4dee431caa8e0ddd22.
Historical decisions
The redesign replaced the historical terminal-focused notifier identity with os-notifier, removed an unused extension event bridge, and deliberately added no settings, commands, tools, daemon, dependency, or persistent state.
Eligibility was defined by accepted direct interactive TUI input, not merely observed input, because handled input, steering, and extension-triggered turns otherwise leak notification authority across lifecycles.
Final completion was placed at agent_settled rather than low-level end events so retries, compaction, and queued follow-ups cannot produce premature notices.
Focused work is discarded rather than deferred, preserving notifications as an absence-of-attention signal instead of a backlog.
Native OS bridges were preferred over terminal protocols, with one terminal fallback only after native spawn failure, nonzero exit, or bounded delivery timeout.
Direct executable arguments, bounded sanitized dynamic text, and no shell interpolation were chosen to prevent notification content from becoming a command-injection boundary.
Verified current behavior
extensions/os-notifier requires TUI mode, direct interactive accepted input, and an unfocused terminal for both settled-completion and extension-UI-prompt notices.
Its in-memory candidate, prepared, and active lifecycle state preserves the accepted starting prompt across retries while preventing later input from reclassifying work.
It reports only Pi extension UI prompts, so arbitrary subprocess stdin waits remain outside scope.
Linux uses notify-send, macOS uses osascript, and Windows uses a PowerShell WinRT toast.
Linux maps info, warning, and error to low, normal, and critical urgency, while other native bridges communicate outcome through titles.
Failure of the five-second native attempt falls back exactly once to Kitty OSC 99 or generic OSC 777, and delivery never blocks Pi lifecycle handling.
Completion content retains outcome, duration, project, Git branch, session, model, bounded prompt, and bounded failure detail.
DECSET focus tracking is reference-counted, and TUI sessions publish then clear pane identity metadata through OSC 1337 variables.
Lessons
Notification correctness depends on lifecycle provenance and focus at delivery time, not duration thresholds or terminal capability probes.
Best-effort native delivery should degrade locally and silently, never make user work fail.
Minimal state local to one extension instance is sufficient when event dispatch is serialized.
Legacy sources
docs/super/specs/2026-07-12-os-notifier-design.md records eligibility, delivery, safety, and lifecycle rationale.
docs/super/plans/2026-07-12-os-notifier.md records reconciliation that implementation shipped and the cross-platform fallback verification intent.
---
id: PX-RESEARCH-A8255D90
type: research
title: OS Notifier Evolution
---
## Scope
This records notification-design decisions from legacy material against present `extensions/os-notifier` behavior.
Legacy sources are recoverable from Git commit `88660125c313dd5eff4f8c4dee431caa8e0ddd22`.
## Historical decisions
The redesign replaced the historical terminal-focused notifier identity with `os-notifier`, removed an unused extension event bridge, and deliberately added no settings, commands, tools, daemon, dependency, or persistent state.
Eligibility was defined by accepted direct interactive TUI input, not merely observed input, because handled input, steering, and extension-triggered turns otherwise leak notification authority across lifecycles.
Final completion was placed at `agent_settled` rather than low-level end events so retries, compaction, and queued follow-ups cannot produce premature notices.
Focused work is discarded rather than deferred, preserving notifications as an absence-of-attention signal instead of a backlog.
Native OS bridges were preferred over terminal protocols, with one terminal fallback only after native spawn failure, nonzero exit, or bounded delivery timeout.
Direct executable arguments, bounded sanitized dynamic text, and no shell interpolation were chosen to prevent notification content from becoming a command-injection boundary.
## Verified current behavior
`extensions/os-notifier` requires TUI mode, direct interactive accepted input, and an unfocused terminal for both settled-completion and extension-UI-prompt notices.
Its in-memory candidate, prepared, and active lifecycle state preserves the accepted starting prompt across retries while preventing later input from reclassifying work.
It reports only Pi extension UI prompts, so arbitrary subprocess stdin waits remain outside scope.
Linux uses `notify-send`, macOS uses `osascript`, and Windows uses a PowerShell WinRT toast.
Linux maps info, warning, and error to low, normal, and critical urgency, while other native bridges communicate outcome through titles.
Failure of the five-second native attempt falls back exactly once to Kitty OSC 99 or generic OSC 777, and delivery never blocks Pi lifecycle handling.
Completion content retains outcome, duration, project, Git branch, session, model, bounded prompt, and bounded failure detail.
DECSET focus tracking is reference-counted, and TUI sessions publish then clear pane identity metadata through OSC 1337 variables.
## Lessons
Notification correctness depends on lifecycle provenance and focus at delivery time, not duration thresholds or terminal capability probes.
Best-effort native delivery should degrade locally and silently, never make user work fail.
Minimal state local to one extension instance is sufficient when event dispatch is serialized.
## Legacy sources
`docs/super/specs/2026-07-12-os-notifier-design.md` records eligibility, delivery, safety, and lifecycle rationale.
`docs/super/plans/2026-07-12-os-notifier.md` records reconciliation that implementation shipped and the cross-platform fallback verification intent.