Session notification broker

Host implementation checkpoint, 2026-09-24. No notification UI, keyboard focus, touch interaction, or board proof is claimed here. This service supplies actual runtime data to the coherent shell’s shade rather than a mock list.

k230-notifications serve owns a private Unix socket, normally /run/shell-notifications/events.sock. The daemon accepts one bounded newline JSON request per connection. k230-notifications history, emit, dismiss ID, dismiss-all, and action ID are CLI clients of the same protocol. A native shell client can use the socket directly without launching a process per poll.

The history response has schema: 1, count, events, and nullable preview. Each history event has id, source, icon, summary, body, priority, timestamp (Unix seconds), error, dismissible, and action_available. Preview has id, source, summary, icon, priority, ongoing, and focus: false. The client must keep unsolicited previews outside the keyboard and focused input; that client behavior remains to be tested.

Requests use operation: history|emit|dismiss|dismiss-all|action. Dismiss/action also carry integer id. Emit accepts summary, body, tag, priority, private, ongoing, and optional Sway container target. Sender-supplied source labels are ignored. Linux peer credentials establish root/system or a Nix-pinned executable identity from the --trusted JSON map; other session senders are unknown, ordinary, private, with no app icon or action authority.

Unsolicited private previews reveal neither source identity nor summary/body. Opening history reveals the retained content. Previews expire after five seconds without deleting history; ongoing critical events retain a preview and cannot be dismissed. Only their trusted source’s matching tag can update them to resolved. Ordinary history expires after an hour. At most 64 events remain; a full history of ongoing critical events rejects further input. Source/tag deduplication updates one record. Missing action targets remain in history with an error; action always revalidates the actual Sway tree before focus and never executes an event-supplied command.

The broker accepts at most eight simultaneous clients, 4096 request bytes, and two seconds per connection. An unfinished client does not stall other clients. The socket and runtime directory are private to the session user. An exclusive broker lock supports stale-socket recovery after a killed daemon. History is session memory, not a claim of reboot persistence or freedesktop notification API coverage.

python3 tests/test_notification_center.py passed nine host tests: priority, privacy, retention/deduplication/expiry, unknown-source downgrade, preview timeout, disappeared target/retry, retained/resolved critical events, bounded critical flood, and a real Unix-socket daemon with a stalled client and killed daemon restart. UI-specific typing-focus/scroll/swipe cases deliberately remain unimplemented and are rejected if requested; they require the actual client.

nix build .#handheld-notifications --no-link --print-out-paths --max-jobs 1 --cores 8 passed, producing /nix/store/n9p1qlrflc463v3siyrhj49n5hdbh1fd-k230-notifications. The package uses the board package graph and excludes XWayland; an initial overbroad dependency selection was stopped and corrected before this build.

Remaining: service integration, pinned source registration, shade rendering and interaction, real compositor focus test, and board evidence.