--- title: Inbox alerts (how an agent gets your attention) --- # Inbox Alerts (agent-sourced persistent inbox rows) ## What it is **Inbox Alerts** is a primitive that lets any Claude Code session (or the CLI control server) drop a persistent inbox row on demand via `POST /alert`. Unlike ephemeral notifications that vanish after display, an alert survives restarts, syncs across sessions, and lives in the inbox until the user archives it or it expires via snooze. Alerts are **on by default** — the feature exists so any agent can surface **out-of-band** attention the user would otherwise miss (a background job, a failure in a session they've moved on from, a decision left after the work finished). It is **not** for repeating what you already say in a session's final message — that just double-shows the same thing in two places. A user who doesn't want agents posting cards turns that off at Settings → Features → **Allow agents to raise inbox alerts** (`agentAlertsEnabled`). That switch closes only the AGENT door: `POST /alert` answers `403` (an owner-critical fleet page still goes out), a plugin's inbox card is not posted, and a card the spool was holding for later replay is set aside in the spool’s dead-letter file instead of delivered. It never hides the cards Omniscio itself raises — the Alerts section of the inbox is always shown. (Until 2026-09-28 it hid every card, the app's own included, while agents' spooled cards still came back through the replay.) **One door, every rule.** Every card — whether an agent posted it, a scheduled script spooled it, or Omniscio raised it in-process — is written by one function, `createAlert`, and the delivery rules run inside it: the per-type mute, the first-day hold, the operator-only and developer-only drops, the cross-device "another machine owns this session" drop, the settling and digest holds, the owner-critical phone page, the cloud self-heal fixer, the team-chat bridge, and write-failure escalation. Every door that writes a card also runs it past the **Overseer's batch-and-judge hold** (urgent, scheduled and awaited cards are never held) and stays quiet while it is held. Before 2026-09-28 the phone page, the fixer and the bridge lived in the `raiseAgentAlert` wrapper and the CLI route, so a producer that called `createAlert` directly skipped them. Omniscio itself uses the same primitive for a handful of built-in advisories — the low-memory warnings; since 2026-07-04, the **"Mobile is loading slowly"** card (raised when the median of the last 10 phone loads exceeds 3.5 s; once per episode, at most one card per 24 h, standard Start-session button; see [mobile-perf-prevention.md](mobile-perf-prevention.md)); and the **"cleaned up stuck dependency installs"** notice (the Install Orphan Reaper's — see below). None of them reads `agentAlertsEnabled` — that switch governs only agents and plugins, and a build guard keeps it that way. A **backup-failure card** is also raised for each off-machine backup — Setup Backup to Gmail after 3 consecutive send failures, Backup Mirror on any unresolved auto-sync push failure — so a broken off-site backup surfaces in the inbox instead of silently failing; it self-clears once a backup succeeds (`backup-failure-alert-contract.md`). The dedicated **"Alerts" virtual project is hidden from the sidebar by default** (`alertsSidebarEnabled`, off). Its list of active alerts lives in **Settings → Notifications → Active alerts**, where a **"Show Alerts in sidebar"** switch flips the sidebar row back on. Sidebar visibility is a pure UI choice — independent of `agentAlertsEnabled` — and alerts still surface in the unified inbox either way (see [Inbox behaviour](#inbox-behaviour)). ## Where to find it In the **inbox**, where an alert appears as a card among your sessions and messages, and in the **Alerts** screen for a wider view including recently dismissed ones. The switch for turning a built-in notice off sits on the card itself, and the per-type controls are in **Settings → Notifications**. ## How it behaves ### Turning an alert type off Every kind of alert this app can raise has its own off switch. There are 688 of them, and each is declared in one place with a plain-language name, a category, and whether it may be silenced. **Two ways to turn one off:** - **From the card.** Nearly every alert card carries a quiet "Turn off these alerts" button. This is the usual path — you turn something off at the moment you decide you are done with it. The one exception is a card you can reply to directly: its bottom holds the reply box, that card's own action, and nothing else, so it carries no mute. Turn those types off in Settings → Notifications → Alert types instead. - **From Settings → Notifications → Alert types.** A browsable list of every type, grouped by category and searchable by name or internal key. Each row shows how often that type has actually fired on this machine, which is usually what decides it: "never seen on this computer" and "seen 12 times, yesterday" are very different cases. This is also where you turn one back on. **The list only shows alerts that can actually reach you.** A large block of alert types — around 180 of them — report on the shared cloud fleet and are raised _only_ on the one computer designated as its operator; everywhere else they are discarded before anything is written. Those are left out of this list rather than shown as switches that would control nothing, and the card says at the bottom how many were left out and why. On the operator machine itself they do appear, each tagged **Operator only**, so the one person who sees both kinds in one list can tell them apart at a glance. **Two smaller blocks are filtered for the same reason, from the other end.** - **Alerts about a development checkout** — the auto-lander, the worktree sweeper, master sync, the post-land build check, cloud machines this install started. Each is declared **developer-only**: it is dropped when Omniscio runs as an installed build, and delivered when it runs from source. So the developer running the checkout still gets their own machine's alerts, and nobody else gets a card about machinery they do not have. - **Some types ship switched off.** These report the app's own internals — crash reporting, telemetry pipelines, internal startup and IPC faults — where there is nothing for a reader to do. They are real alert types with a real switch, and the switch is simply **off when you first see it**: turn one on from this list and it behaves like any other. The card at the bottom of the list is your window into what is currently off. See `alert-type-registry-contract.md` (`only-what-can-fire-here-is-listed`, `a-cloud-fleet-row-declares-its-delivery-scope`). **It asks first, and tells you the real scope.** Most switches cover a whole FAMILY of alerts, not the one card you are looking at — so the button opens a confirmation that spells out what you are about to lose before anything changes. It names the reach ("every future _Calendar event added_ alert — not just this one card"), says the feature behind it keeps running and you just stop being told, lists the related alerts that stay on, and points at where to turn it back on. Cancel changes nothing and leaves the card where it was. The blunt "Turn off desktop notifications" button asks the same way, and makes the important part clear: nothing is lost, everything still arrives in your inbox, it just stops popping up over your other windows. **What "off" actually does.** The alert is dropped at the single point every alert passes through, before anything is written. That is what makes it cover alerts raised by background scripts and scheduled jobs over the local HTTP route, not just the ones raised inside the app — no producer has to remember to check. **Muting stops the card, never the cure.** Eighteen alert types automatically start a session to repair what they are warning about. Turning one of those off still lets the repair run; you just stop being told about it. **A few cannot be turned off**, and they say why. Sign-in expired, backup failures, critically low memory, low disk, and below-minimum hardware all show a disabled switch with its consequence ("silencing this would hide a backup problem until you needed the backup"), rather than simply not appearing. Each one is a way to lose the account, the data, or the machine — not a preference. **If anything goes wrong with the switch, you still get the alert.** An alert type nobody has described yet, an unreadable preference, a type declared un-silenceable — all deliver. An off switch must never fail toward silence. **Alerts that have fired here but are not listed** appear in a footer on that Settings screen, saying plainly that they cannot be turned off yet. A screen claiming to list every kind of alert while quietly omitting some would be lying. ### Alert types Each alert has a `contentType` discriminator: - **text** — free-form prose or Markdown. **Every alert renders its text through the same renderer as a chat message** — whether an agent or Omniscio itself raised it, live or archived, on desktop, phone or Simple Mode (one shared component, `AlertTextBody`) — so headings, lists, bold, inline code, links (including a tappable `omniscio://session/…` deep link) and images work as they do in the transcript. A question written in the standard chat shape renders as an **answerable question widget** on a card whose raising session can still receive the answer, and the answer is delivered back to that session; a question-shaped body posted with **no** session to answer it is refused at the door rather than delivered, so a question can never land as text nobody can act on. See [Answerable cards](#answerable-cards-the-standard). An agent-raised card draws that text inside the **same bubble a chat message uses** — one shared frame both surfaces compose — so the card reads as a message rather than as card prose. **Every newline in `text` is drawn as a line break and nothing rejoins wrapped lines**, so write each paragraph on ONE line, put a blank line between paragraphs, and fence pasted logs or command output in a code block — a sentence hard-wrapped in the source shows as a broken line on screen (inbox-alert-contract `alert-text-is-chat-markdown`). - **link** — URL with optional og: metadata (`linkTitle` / `linkDescription` / `linkImageUrl`) rendered as a preview card. - **file** — attachment stored under `userData/alerts//`. An **image file renders inline** (the picture itself, not a pill — see [Inline image alerts](#inline-image-alerts)); an **HTML file renders live as a styled page** (see [Rich HTML alerts](#rich-html-alerts)); any other file renders as a name/mime/size pill. - **embed** — a **hosted Omniscio Shares page** rendered **live inline** in an opaque-origin sandbox (see [Embedded Shares pages](#embedded-shares-pages)). The page URL rides `text` (like `link`) and is fail-closed to a genuine Shares-origin `/s/` URL. ### Answerable cards: the standard **If a card exists because an agent needs a decision, the question goes on the card.** An agent that asks in prose and waits for a reply makes the reader leave what they were doing, find the session, and type the answer back. A question written in the card body in the standard chat shape renders as an **answerable widget**: the reader picks an option (or types an answer) and submits, and the answer is delivered into the session that raised the card — which carries on from there. ```markdown **Approve the engine-parity contract?** - **A.** Approve - **B.** Reject - **C.** Explain what changes first ``` **A question that nobody can answer is refused, not delivered.** The answer has to go somewhere, so a card can only offer it when it has a session to hand it back to: a question-shaped body posted with no source session is rejected outright (`400`, and no card is raised) instead of arriving as a question with nothing to answer it with. The refusal names the missing piece — post it from the session that wants the answer. Nothing else changed: an ordinary report posted with no session, which is how every background monitor posts, delivers exactly as before. - **A question needs its options.** The widget fires only on a question carrying at least two lettered options (`- **A.** …`). A bare `**Question?**` renders as ordinary prose — a question the reader cannot act on. - **The raiser names no destination.** The card knows which session raised it; answers go there. - **Every agent-raised card also carries the chat bar.** Under the bubble sits the same composer the session has — the attachment button, quick replies, dictation and the split Send with its ▾ Send Later menu — so a reader answers a card the way they would answer in the session, and a file attached there rides the same send. It is present whether or not the body also carries a question: a chat message with a question still has its composer beneath it, and the answer is one-shot either way, so using both paths delivers once. - **The reply box is pinned to the bottom of the card** and does not scroll away: the message scrolls above it, however long or short that message is. Beside the reply box that card keeps its own action and the one-click "Go to Session", and carries neither "Start session" nor "Turn off these alerts" — the card you answer directly is the one card whose bottom belongs to the answer. - **A stopped session is resumed** by an answer, so the agent that asked is woken with the reply. - **Answering takes you to the next card, not to a spinner.** The moment you submit — Send, Enter, or the question widget's own button — the card clears and you are on the next item in your inbox. The answer goes out behind you: an answer takes a second or two to reach a running session and longer still when it has to wake a stopped one, and none of that is time you spend looking at a card you have already dealt with. - **If an answer cannot be delivered, the card comes back — with your answer in it.** Nothing reached the session, so the card returns to your inbox saying the send failed, and whatever you had typed or attached is still in the box. Press Send again; nothing has to be retyped. - **The interactive path needs the question-widget setting on.** With it off, the question renders as prose and the card stays readable. - **A purely informational card should carry no question** — an unneeded question costs the reader a tap. Its body still renders as markdown. - **The card names its sender once, inside the message.** An agent-raised **text** card draws its body in the same chat bubble a message uses, and the sender rides in that bubble's own header row: the kind glyph, the session link, and the timestamp — the way a chat message carries them. There is no separate “Updated {time}” pill and no “Generated by” line above the message, because those repeated what the pane's title already said and cost roughly 75px at the top of a phone screen. It holds whether or not the raising session still resolves: a reaped raiser keeps its message and shows a short-id link, and what it loses is the ANSWER path (no reply box), never the shape of the message. An unresolved raiser therefore still names where the card came from. ### Rich HTML alerts A `file` alert whose attachment is an **HTML page** (name ends `.html` / `.htm`, or `text/html` mime) renders **live as a styled page** the moment you open the alert — like opening an email — instead of the name/size pill. This is how an agent turns a report (a trending-repos digest, a build summary, a chart) into a formatted page in the inbox rather than plain Markdown. It **reuses Drip's HTML-preview stack verbatim** — the same `serveDripPreview` security core, the same sandboxed webview (desktop) / opaque-origin iframe (mobile), the same contained CSP — so the containment guarantees are identical: - **Self-contained only.** The sandbox is **no-network** (`connect-src 'none'`; no external fetch / script / frame) — the agent must inline everything: CSS in a `