Notifications guide

Notifications should move decisions to the right human without turning ROST into noisy chat. Notify for exceptions, approvals, and stale commitments.

Notify when

• An agent hits a must-escalate condition.
• A tool or credential approval is needed.
• An agent holds a durable command behind a pending confirmation — the seat's steward is notified so the held action does not sit silent. A human pausing their own gated command does not self-notify.
• A Signal is broken or stale.
• A Friction item needs a decision.
• A Sync decision creates a handoff.
• A seat's reporting line or parent changes (seat.reparent, a seat merge, or agent_setup.update) — the affected seat's Steward and the tenant owners get an in-app notification, so a structural change is never silent (the DER-1388 incident this closes was only caught because a human happened to notice the org chart looked wrong).

Diagnose failed deliveries

rost notification errors --limit 10 / notification.list_errors / rost_list_notification_errors returns recent failed deliveries. When a failed notification links to a product error, it includes error_log_id, source, and any linked seat_id / run_id; source=run means the notification is tied to an agent run and can be followed with agent.get_run for the transcript reference and run errors.

Telegram channel

Telegram is an opt-in delivery channel that sits alongside email. A workspace admin connects a Telegram bot once (create it with @BotFather, paste the token in Settings → Notifications; the token is stored in the vault as a credential reference, never in env or logs). Each person then opts in from the same page: ROST shows a one-time deep link, you start the bot, and ROST verifies your chat. Once verified, held approvals, escalations, briefs, and the daily digest are delivered to Telegram, with email as the fallback. Messages are bounded and secret-free and link back to the relevant ROST item. Opt out any time from Settings → Notifications.

Keep notifications useful

Every notification should include the seat, cause, evidence, and requested decision. Avoid status-only messages when no action is needed.