Files
pipelines/docs/notes/audit-notifications.md
T

2.9 KiB

Run notification audit fixes

notify_mode=auto retains existing behavior: stage policies plus run-level waiting/failure defaults. on also alerts terminal success, even with no stage notification hook. off suppresses stage, run-level system and browser tray notifications. Needs you remains a status/action surface, not a delivery channel. Summaries and pushed events carry the mode; the browser seeds and folds it.

FinishRun and MarkWaiting enqueue the notification intent in the same SQLite transaction as the run/step state change. Enqueue failure rolls back the state; after commit, the worker can recover the intent without any runner callback. The store derives the mode, name, stage and sequence from stored rows. A failed FinishRun does not emit a terminal-success event or run alert. Terminal stage hooks run only after FinishRun commits. Waiting/terminal hooks and the worker share an atomic sending lease to avoid racing publications. Declared hooks get a one-minute initial opportunity to publish their artifacts; if a restart loses the callback, the generic outbox alert becomes eligible after that delay.

run_notifications is an additive, idempotent SQLite migration. Each run/sequence/event/channel has one durable outbox row. Its status is pending, sending, sent, failed, or covered (a stage already published this event). The worker polls once per second, uses an atomic 60-second sending lease and allows three total attempts with 5/10-second retry delays. Pending and expired leases survive restart. A final expired sending lease becomes failed with an unknown-acknowledgement diagnostic. Existing retention deletes associated rows. get_run exposes run-level notifications receipts (sequence, event, channel, status, attempts, diagnostic, message_id), separate from step receipts.

Successful stage publications cover the corresponding waiting/failure alert; a successful stage targeting #success also covers final success. Failed stage publication does not swallow the run-level fallback/retry. Stage artifact publications themselves are not made retryable by this change.

Publisher acknowledgement is not device reception. A crash after publish but before the acknowledgement is saved can duplicate a notification. State and intent commit together, closing the transition-to-enqueue crash window; this is still bounded retry, not guaranteed delivery. Browser delivery remains page-session best effort and requires permission plus HTTPS/localhost; successful runs do not become Needs you entries. The older L5 parity description is attention-only for auto; on now adds success.

Tests use temporary databases and fake HTTP publishers only, covering modes, no-hook success, stage dedupe, failed publisher retry/exhaustion, restart/lease recovery, audit persistence, and browser off/on. No live notifications, deployed database/configuration, service restart, binary installation or OS reception verification was part of this work. No new UI captures were taken.