# os-notifier

Native-first OS notifications when direct interactive Pi work completes or blocks awaiting input.

## Install / load

Loaded through the root pi-ext package.
Requires Pi 0.80.6 or newer for `agent_settled`.
See [root README](../../README.md).

## Commands / tools / settings

Commands: none.

Tools: none.

Settings: none.

Hooks:

- `session_start` attaches terminal focus tracking and publishes pane identity in TUI mode.
- `input` records candidate direct interactive input origin.
- `before_agent_start` confirms the accepted input that starts a lifecycle.
- `agent_start` starts duration measurement for the active lifecycle.
- `agent_end` records the latest low-level outcome.
- `ui_prompt_start` notifies once when eligible work blocks on an extension UI prompt while unfocused.
- `ui_prompt_end` rearms blocked-input notification delivery.
- `agent_settled` sends the final eligible notification while unfocused.
- `session_shutdown` clears in-memory state, pane identity, and focus tracking.

## Eligibility

Notifications require all of:

- `ctx.mode === "tui"`
- input source `interactive`
- terminal unfocused when the blocking prompt starts or at `agent_settled`

RPC, JSON, print, SDK-driven, extension-driven, and subagent-style turns stay silent.
The accepted input that starts the lifecycle determines eligibility.
Later steering and follow-ups do not reclassify extension-driven work.
Focused completions and prompt waits are discarded rather than deferred.
Only Pi extension UI prompts are detected; arbitrary subprocesses waiting on stdin are outside this extension's scope.

## Native delivery

The extension attempts one OS bridge:

- Linux: `notify-send`
- macOS: `osascript`
- Windows: PowerShell WinRT toast

A spawn error, nonzero exit, or five-second timeout emits one terminal fallback.
Kitty receives OSC 99; other terminals receive OSC 777.
No startup probe or warning notification is emitted.

Linux urgency maps `info` to low, `warning` to normal, and `error` to critical.
macOS and Windows communicate outcome through the title because these bridges expose no equivalent urgency.
OSC fallback prefixes warnings and errors.

## Content

Completion notifications include outcome, duration, project, Git branch, session name, model, bounded user prompt, and bounded failure detail.
Blocked-input notifications include prompt kind, title, project, Git branch, and session name.
The accepted starting prompt remains available when a retry's final event omits user messages.
Dynamic text is sanitized and passed without shell interpolation.

Focus tracking uses DECSET `?1004`, shared through `globalThis` and reference-counted.
TUI sessions publish agent identity, session name, and project as OSC 1337 pane user variables and clear them on shutdown.

## Debugging

Opt-in metadata-only tracing follows [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `notification.deliver.start`, `notification.deliver.finish`, `notification.deliver.error`.