Inbox alerts (how an agent gets your attention)
The cards an agent, a cron job or the app itself raises into your inbox to ask for something: what an alert looks like, which types exist, how you answer one, and how duplicates and repeat problems are kept from flooding you. How they are authored and what happens after you act continue on the parts.
On this page
What it is
Inbox Alerts is how any session — or you, from the command line — puts a persistent card in your inbox and leaves it there. Unlike a notification that vanishes after display, an alert survives restarts, syncs across sessions, and lives in the inbox until you archive it or it expires via snooze.
Alerts are on by default — they exist so any agent can surface out-of-band attention you would otherwise miss (a background job, a failure in a session you have moved on from, a decision left after the work finished). They are not for repeating what a session already says in its final message. To stop agents posting cards, turn off Settings → Features → Allow agents to raise inbox alerts (agentAlertsEnabled). That switch closes only the AGENT door: agent posts answer 403 (an owner-critical fleet page still goes out), a plugin's card is not posted, and a spooled card is set aside instead of delivered. It never hides the cards Omniscio itself raises — the Alerts section of the inbox is always shown.
One door, every rule. Every card — whether an agent posted it, a scheduled script spooled it, or Omniscio raised it itself — is written by one function, so one set of delivery rules applies: 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).
Omniscio itself uses the same primitive for a handful of built-in advisories — the low-memory warnings; the "Mobile is loading slowly" card (when the median of the last 10 phone loads exceeds 3.5 s; once per episode, at most one card per 24 h); and the "cleaned up stuck dependency installs" notice. None of them reads agentAlertsEnabled — that switch governs only agents and plugins. 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 instead of silently failing; it self-clears once a backup succeeds.
The dedicated "Alerts" virtual project shows in the sidebar by default (alertsSidebarEnabled), nested under the System group. It is the sidebar home of the inbox's System section, so app-raised notices always have a hub row. Turn it off with the "Show Alerts in sidebar" switch in Settings → Notifications → Active alerts, which also lists the active alerts in place and opens a card inline. Sidebar visibility is a pure UI choice — independent of agentAlertsEnabled — and alerts still surface in the unified inbox either way.
Existing installs were switched on once at their next launch, so a saved off setting becomes on and a later switch-off sticks; a brand-new install starts with the same on default, and the phone and the Settings switch fall back to it when the value is missing.
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 — 688 of them, each declared in one place with a plain-language name, a category, and whether it may be silenced. Every kind of alert this app can raise has its own off switch. Each is declared in one place with a plain-language name, a category, and whether it may be silenced — and a build check fails if a type that can be raised is missing from that list, so a card can never arrive with a switch you cannot reach.
Two ways to turn one off:
- From the card. Nearly every alert card carries a quiet Options button at its foot, and "Turn off these alerts" is the row inside that menu. This is the usual path — you turn something off at the moment you decide you are done with it. When the card is one kind of alert (the DeepSeek balance warning, say), one press turns it off and a message confirms it, with a link to undo. When one press would turn off a whole group of alerts, a box first says exactly what will stop and what stays on, and nothing changes until you confirm. 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.
- From Settings → Notifications → Alert types, the Phone switch. Each row also has a Phone switch: on means that kind of alert reaches your phone, off means it stays in the inbox and is silent on the phone. It starts on for the seven types that page today — the internet outage, the heartbeat/alerting-substrate ones, a failed release worker, the two shared-session pages, and the "does my phone work?" test — and off for everything else, so turning it on for a type you care about is the whole decision. A type you switch on is held inside your quiet hours unless it is a critical alert, and phone sends are capped at ten an hour so no type can buzz you in a loop; the seven built-in pages keep their own ten-minute re-page cooldown and are never dropped by that cap. Task reminders have no Phone switch here — they already reach your phone through their own reminder transport, which the Tasks notification switches control.
The list only shows alerts that can actually reach you. A large block of alert types are about Omniscio's own shared services rather than this computer, and are discarded before anything is written anywhere else. 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.
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. The post-land build check and its cards run only on the main
computer (the one whose
masterSyncMainComputersetting is on); every other developer computer skips that build, because it never lands work. - 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.
Cloud work is filed for the crew that runs it, not for you. Every alert type about running the cloud fleet — work still owed home, a launch step that did not finish, a machine created and never claimed, a refused wake, a warm pool running dry, a cleanup that could not run — is written for the crew that owns the fleet and never enters your inbox. The card still exists: the crew's lead receives a copy, and it is readable through the alert list.
Which types these are is written down one by one, and a new cloud alert type without that answer fails the build. On a computer with no crew running (an ordinary install) nothing is filed away at all: the card stays with you, because a card nobody can receive is silence.
Some cloud alerts behave instead of filing. A cloud alert that is a decision only you can make stays with you: money (approving a new fleet machine, a billing budget, cloud credit running low, spend nothing accounts for, or a spend watch), a security or privacy exposure (a machine not on the trusted image, its outbound lockdown failing to apply, the runtime security watch, or the alarm channel going dark), and the fleet digest's own outage. An alert that asks you a question is never filed away. Requests to approve new fleet machines gather into a single card: the first request opens it, the card's title carries how many are waiting, and the body lists each one, so a burst of ten asks reads as one card instead of ten. One click answers every request on that card, and the card stays put until all of them are answered or already settled — a request answered elsewhere, or one the ledger no longer holds, does not block the rest.
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.
A switch you already flipped survives a split. When one type is split into several so each can be turned off on its own, a one-shot startup step copies your old choice onto every new part: if you had turned the old type off, all of its parts start off too, and you can then turn any one back on. Calendar change notices (added / changed) and Omni's project alerts ("Omni notes about your projects", "Omni's daily action limit") were both split this way. A card whose type points at an older dedicated setting uses that setting as its switch instead — "Turn off" on "What changed yesterday" switches the daily digest itself off, so the two controls can never disagree.
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 ID codes
Every alert type carries a stable code such as AL-7K2M9Q, shown on its card and on its row in
Settings → Notifications → Alert types. Clicking the code copies it, and the Settings search matches
it. A code names the type, not the card: every card of one type shows the same code, including a
per-account member of a family such as a single mailbox. The code is derived from the type's own key,
so it never changes when the catalogue is rebuilt and the same type shows the same code on every
machine — which is what makes it safe to quote in a bug report or a support reply.
On the card itself the code stays out of the way: it sits at the bottom of the alert, folded behind a small "Alert code" row that opens it in place, so a reader who does not need it never sees it and a reader who does is one tap from copying. It belongs to the alert, not to the pane — it scrolls with the card rather than sitting under the reply box.
Choosing which hub an alert appears in
Each row in Settings → Notifications → Alert types also carries a Hub picker. Automatic keeps the built-in behaviour and is what every type starts on. Choosing a hub files that type's NEW cards under the chosen hub instead — the Alerts hub, the Omniscio hub, System, Mission Control, AI Project Manager, Team Chat, Tasks reminders, Cron failures, Training Hub, or any project hub — and the type stops appearing in the Alerts hub.
Routing only moves a card. It never mutes, drops, delays, or changes how it reaches you, and a hub
that is later deleted simply falls back to Automatic. A card's own producer can still pin it to a
project — a scan of project X stays about project X — while the hub you chose decides which inbox
section lists it. See alert-routing-and-identity-contract.md.
Alert types
Each alert has a contentType:
- text — free-form prose or Markdown, rendered through the same renderer as a chat message (live or archived, desktop, phone or Simple Mode), so headings, lists, bold, inline code, links (including a tappable
omniscio://session/…deep link), images and GFM pipe tables work as they do in the transcript. A table needs a blank line before it like any other block, and in a pane narrower than 480px each row becomes its own label/value card instead of scrolling sideways. A question written in the standard chat shape renders as an answerable question widget when the raising session can still receive the answer, which is delivered back to it; a question-shaped body posted with no session to answer it is refused at the door. An agent-raised card draws that text inside the same bubble a chat message uses. Every newline intextis drawn as a line break and nothing rejoins wrapped lines, so write each paragraph on ONE line, leave a blank line between paragraphs, and fence pasted logs or command output — a hard-wrapped sentence shows as a broken line on screen. A notice that carries ANOTHER PERSON'S text — a Team Chat notice, whose body is a member's message — draws in the restricted mode instead: it still reads through the same shared body, but a link in it is a web link only and can mint no in-app file button, app deep link or pre-filled session draft (untrusted-markdown-render-contract.md). - link — URL with optional og: metadata (
linkTitle/linkDescription/linkImageUrl) rendered as a preview card. - file — attachment stored under
userData/alerts/<alertId>/. An image file renders inline (the picture itself, not a pill — see Inline image alerts); an HTML file renders live as a styled page (see 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). The page URL rides
text(likelink) and is fail-closed to a genuine Shares-origin/s/<token>URL.
How alert text is shaped. Omniscio writes its own cards to the shape an agent's card should have: the first paragraph says what happened and whether you need to do anything, each idea after it is a short paragraph, lists are real - items (a typed • draws as a plain line), and anything you would copy — a command, a path, a branch name, another tool's output — sits in code formatting or a code box, so it copies exactly as shown. A Windows path always shows every backslash, even before a folder whose name starts with a dot or an underscore, and copying a message gives you the path exactly as written. A card that also pages your phone opens on a plain sentence, because the phone shows that first paragraph as plain text.
Omni's everyday cards wear the Omni frame
Omni's everyday cards (the "What changed yesterday" digest, shift reports, deadline and at-risk notes, page notes and the abilities card) open in the same template a Mission Control item card uses: the text sits in a bordered panel with a faint Omni logo behind it, and an Omni brand strip closes the card with the Omni logo, the name the card's "From" line shows, and "Last update" with the time. Omni's problem alerts (its daily action limit, an action or move that failed, the AI limit warning) keep the plain alert look. Which card is which is decided in one place, getAlertVisual in src/renderer/src/features/alerts/alert-visuals.ts: a card whose look is brand: 'omni' gets the frame (OmniCardFrame in src/renderer/src/components/ui/OmniBrand.tsx). Both brand strips are the shared InboxBrandStrip.
Mission Control alerts wear the Mission Control frame
Mission Control's own alert cards (the board-change card, due-date and overdue cards, automation notices, and automations waiting for approval) open in the Mission Control frame: the text sits in a bordered panel with a faint Mission Control logo behind it, and the Mission Control brand strip closes the card with the logo, the name Mission Control, and "Last update" with the time. It is decided by the same getAlertVisual: a card whose look is brand: 'mission-control' gets MissionControlCardFrame from src/renderer/src/components/ui/MissionControlBrand.tsx.
The board-change card ("3 changes on Sprint Board: 2 status update, 1 comment") lists each change in its body as the item followed by what happened, up to 8 lines and then "N more changes". A due date is announced once, by its own due-soon or overdue card; it never comes back later as a board-change card after the app restarts.
Which alerts reach your phone
Most alerts stay in the inbox. Only three things reach your phone, and all three are yours to control.
- An alert the app itself marks critical pages the phone. That is what the red "critical" mark means, and it needs no setting — a new critical alert starts paging the day it is written.
- A short built-in list always pages, even with the switch below turned off — the things that must never wait in an inbox: this computer going offline, the app itself going quiet, the app's own alerting being broken, a cloud release worker failing (on the cloud-fleet machine only), someone sharing a session with you, a guest message waiting for your approval, and the built-in "does my phone work?" test.
- Any other type you switch on. Settings → Notifications → Alert types lists every type with a Phone switch; turning one on adds it.
Everything else is inbox-only. A card with no entry in that list can never page your phone at all, whatever an agent or a script asks for.
The off switch. The first control on that same card is Send critical alerts to my phone, on by default. Turn it off and everything goes back exactly as it was before severity existed: only the built-in list and the types you switched on yourself page. Nothing else changes — email, text and phone-call alerts are untouched. Turning a single critical type's own Phone switch off keeps that one type quiet without touching the rest.
What a page respects. A page goes through even inside quiet hours — a critical condition at 3 AM is what quiet hours are not for. The same alert never pages twice inside ten minutes, and no one kind of alert can page more than six times an hour, so a noisy kind can never use up the budget a different kind needs — a flood of one thing will not silence a security page. Muting notifications entirely still silences pages, and an inbox card is always written whether or not the phone rings.
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.
**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. The box also carries the same state-aware hint the session's own composer shows for that session, so it is never a blank strip and the two boxes can never disagree about what typing there will do: "Answer the question…" on a card waiting on an answer, "Approve or modify the plan…" on one waiting on a plan, "Send now (interrupts the current step)…" while the agent is still running on an engine that can take the message immediately, "Queued: sends when the current step finishes…" on one that cannot, "Send a message to resume…" on a card whose session has stood down — each with a shorter form on a phone. It is the app's ONE shared chat box (the same one the Overseer hub and the crew board use), so on a desktop it shows every desktop-only button the session's own box shows — the FlowVoice mic and clipboard history included — and an answer you start typing and leave is still there when you come back to the card, until you send it. A staged file looks and behaves exactly as it does in the session's composer: an image is a thumbnail you can click to open full size (right-click for its menu), a document is a labelled chip, the grip reorders them, a PDF chip offers Convert to Markdown, and the ✕ or a middle-click removes any of them with Ctrl+Z to undo — there is no reduced, card-only attachment view. 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. That card carries neither "Start session", nor "Turn off these alerts", nor the "Go to Session" button — you are already answering the session in the box below, and the "Generated by" line in the header is the link to it — so the card you answer directly is the one card whose bottom belongs to the answer alone. The same goes for a card whose own button would only open that session (for example "Open the session" on a broken cloud machine card): the button, its Enter shortcut and the bar under the reply box are all left off. A card whose button does something else keeps it.
- The cursor lands in the reply box when you open the card — if you have Auto-Focus Input on Session Switch turned on (Settings → Workflow), the same setting that does this for sessions. You can start typing your answer straight away instead of setting off a shortcut. Moving on to the next card puts the cursor in that card's box too. With the setting off, the card opens without the cursor in the box and R puts it there. On a phone the box is never focused for you, so the keyboard does not pop up on every card.
- Your keyboard works on the card the way it works in a session. The bar is the real chat bar, so the session's composer keys are all here: R puts the cursor in the reply box (a question on the card forwards R to the same box), Enter sends, Alt+Z sends your configured quick reply, Alt+S opens the quick-reply picker, Ctrl+U attaches files and Ctrl+Shift+L opens Send Later for what you have typed. Q jumps to a question the card is asking, and Ctrl+Shift+Q opens the first link in it, and V flips the card between its Plain Speak summary and the original when it carries one. The keys that belong to a session's transcript — stepping through messages, the permission banner's allow/deny — have nothing to act on here: the card is a single message, not a conversation.
- The card has the chat message's ⋯ menu. The same ⋯ button a chat message carries sits at the
end of the card's header row (always shown — the card is the only message on screen). It offers
Copy Markdown, Copy Formatted, Copy link (an
omniscio://alert/<id>link that reopens this card), Export to Word / PDF / Google Docs and Save to scratchpad, and each copies what the card is SHOWING: the Plain Speak summary in that view, otherwise the message without its hidden summary. The chat menu's Copy everything, Re-run from here, bookmark, public Share link and report flags are absent — they work on a session's transcript, and a card is not part of one. - 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. 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.
- The card carries the message's own controls, in that same header row. Two of them, each
appearing only when the card actually has something for it to do. A question chip — a
question-mark icon and a count — sits at the far end of the row whenever the body shows a live
question; press it to scroll straight to that question and focus it (the
Qkey does the same, and hovering the chip shows the current key). It needs the card to be answerable as well as question-shaped, so a card whose session has ended keeps its question as plain text rather than offering a button that leads nowhere. And when an agent wrote its short Plain Speak summary into the card, a ⇄ toggle sits beside the chip and flips the card between that summary and the full report, exactly as the same toggle does on a chat message. A card with neither control draws neither — the header row is just the sender, as before.
Reply box
Every agent-sourced card that carries a sourceSessionId shows a free-text reply box below the body content. The reader types a message, taps Send (or presses Ctrl+Enter), and the text is delivered to the originating session on the same path the answerable widget uses, so a stopped session is resumed automatically.
- Every answer names the card it answers. Whether it came from the reply box or from a question widget's option, what the SESSION receives opens with one line naming the card — its title and its alert id — so a session holding several cards knows which one was answered. The line rides inside an agent-only marker, so it is stripped from the on-screen message and the bubble shows the reader's own words — including on an answer carrying a pasted block. A slash command typed in the box (
/model,/clear, …) is sent as-is, with no header; a reply that merely starts with a slash, like a file path, is still an answer and is named. This holds for a reply scheduled with Send Later too, and for one queued behind the agent's current turn: the line travels with the words and is added when the answer is actually delivered, so it names the card however late it arrives. The picker still previews, counts and hands back only the reader's own words, so Undo returns their text and not the line. - Independent of the question widget. A card can have both an answerable question widget and a reply box — they serve different purposes (structured answer vs free-text follow-up) and are visually distinct.
- Submitting clears the card. The card leaves the active inbox the instant an answer is sent, and the reader moves to the next item while the delivery finishes behind them — a modal question widget answer and a reply-box send behave the same way here. Both paths are one-shot per card.
- No empty sends. The Send button is disabled while the textarea is empty or a send is in flight.
- A card you already answered says so when it comes back. If an answered card returns to the inbox — you pressed Undo, or an agent un-archived it — its questions show as plain text with a small "✓ You answered this 4:24 PM" line under the message, and the reply box stays locked so the same question can't be answered twice. This holds after an app restart too, because the card remembers the answer itself. If the agent later posts new wording on that card, it counts as a new question: the line disappears and the question widget is live again. A repost with the same words keeps it answered.
- Error handling. A failed delivery shows a humanized toast, the card comes back, and the typed text, files and pasted blocks are restored so the reader can retry without retyping.
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 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<style>block orstyle=attributes, images asdata:URIs. An external<link>/<img src="https://…">is blocked, so the page must not depend on one. - Isolated. Opaque origin, no same-origin access, no reach into Omniscio internals or your token — a hostile page can display but can't touch anything.
- Size. The ~750 KB alert-file ceiling applies first at post time (a larger file is rejected before it's stored); the preview stack additionally enforces a shared 5 MB ceiling.
- Kill switch. One shared
dripHtmlPreviewEnabledsetting (on by default) governs both Drip and agent HTML alerts; off → the alert falls back to the plain file pill. - On a phone the page gets the whole pane. The frame fills the detail view instead of standing as a fixed-height card, and the pane's own “Updated …” / “Generated by …” lines are not drawn above it. A live preview is a separate scroller, so anything stacked over it can never be swiped out of the way — it would simply eat the top of the screen for good. Those lines still show on desktop (in the pinned header) and on a phone for every card whose body scrolls with the pane — except an agent-raised text card, which carries no such lines at all (its sender row is inside the message).
Only source_kind = 'agent' alerts take this path (a drip-sourced row resolves via Drip's own lookup first).
Inline image alerts
A file alert whose attachment is an image (fileMime starts with image/) renders the picture inline in the alert view — the same way a released Drip image item does — instead of the name/size pill. This is how an agent delivers a screenshot, a chart, or a rendered card (e.g. an X "tweet card" captured as an image) straight into the inbox.
- How. On open, the alert view reads the image's bytes, scoped to the alert's OWN file (
source_kind = 'agent'and animage/*mime), and shows them as adata:URL. It shares one inline-image component with Drip, the image mirror of the shared HTML preview. - Reachable on your phone, like Drip images (the channel is on the mobile WS-bridge allow-list).
- Fallback. A reaped / unreadable / non-decodable image falls back to the plain file pill — never a broken image.
- No setting, no network. Image alerts ALWAYS render inline — there is no toggle (only HTML has the
dripHtmlPreviewEnabledgate). The bytes are read locally; nothing is fetched. An<img>can't execute a script, so even an odd image type (e.g. SVG) is inert.
Only source_kind = 'agent' alerts take this path.
Overseer tag debug chip on inbox cards
With the developer-only Overseer tag debug switch on, an overseer's inbox card draws the same tag chip the transcript draws under the overseer's message (see overseers.md).
- How. The card looks up the newest agent message in its source session whose published key matches the card's dedup key and reads its kind, written labels and correction. With no such message, a category card key from a V2 overseer yields
updateand a report key yieldsreport; the bare standing-card key yields nothing. - Switch off — no read is made and no chip is drawn. A failed read draws no chip and no error.
- Reachable on your phone (the channel is on the mobile WS-bridge allow-list). It has no CLI twin: it is classified
dev-diagnostic. - Known limit. A card last refreshed by a publish that stamps no message reads the newest stamped message; its kind and label match by key construction, and only a correction can lag.
Embedded Shares pages
An embed alert (contentType: "embed") carries the URL of a hosted Omniscio Share — an https://shares.omniscio.com/s/<token> page you already published (see share-cli.md) — and renders it live inline in the alert view, in the same opaque-origin sandbox a developer broadcast uses. This is how an agent surfaces a full published Share (a dashboard, chart, or interactive report — unlimited size) in the inbox, versus inlining a self-contained .html file (the file path above, capped ~750 KB).
- Fail-closed to the Shares origin. The page URL rides the
textfield and is validated at post time — only a genuinehttps://shares.omniscio.com/s/<token>URL is accepted; an off-origin, wrong-scheme, or non-/s/<token>URL is rejected with a400, so a leaked CLI token can never embed an arbitrary page in the trusted inbox. The renderer independently falls back to a plain text card if a stored URL is ever invalid. - Only a share with an inline page. The card frames the share's
/s/<token>/runpage, which only an HTML or React share has (video and screen-recording shares are stored as HTML and have one too). An embed naming a share this app knows that has no inline page — a Markdown, text, image, PDF or conversation share — is refused400namingcontentType "link"as the way to send it, because the card would otherwise open a "Share Not Found" page. A share this app has no record of is accepted. - Sandboxed like every embed. Opaque origin,
allow-scriptsbut noallow-same-origin— the page's JS and forms run, but it can't read your cookies, storage, or token, or navigate the app; the height is clamped so one card can't take over the inbox. - Optional heading. Set
linkTitlefor the card's heading; omit it and the heading defaults to the alerttitle(parity with a developer-broadcast embed).
# Publish an artifact to Shares first (see share-cli.md), then embed its share URL:
curl -X POST http://127.0.0.1:19519/alert \
-H "Authorization: Bearer $AMC_CLI_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title":"Weekly metrics","contentType":"embed","text":"https://shares.omniscio.com/s/<token>"}'
Two cards that watch the inbox itself
The two cards the app raises about the inbox itself — a sudden jump in its card count, and a full alert route table — are described on part 4.
Deduplication
Supply a dedupKey to group related alerts into a single row with a ×N badge. On each new alert with the same dedupKey, the existing row's dedupCount is incremented and its updatedAt refreshed — a single row stays at the top of the inbox rather than accumulating duplicate rows. The row also takes on the latest raiser's session (or none, when the new raise came from no session), so a card always shows under whoever raised its current words — never under an older session that happened to raise the same key first.
The limits on raising and withdrawing one
Four numbers govern the CLI surface an agent uses, and each is worth knowing before you build a detector on top of it.
- One click on Archive archives ONE card — never the next one. The archive control lives in the open card's header, and archiving a card advances you to the next: a second click belonging to the same double click would therefore land on the card that just came up, filing a card you never saw. The control ignores a repeat click from the same gesture, so an impatient double click — or a stuck key — still archives exactly the card you were reading.
- A source may raise at most 60 alerts a minute. Past that the alert is dropped — it is not
created, and the call is refused with
429. One runaway loop therefore cannot flood your inbox. - Listing stops at 1000.
GET /alertreturns at most 1000 active cards and says nothing about the truncation, so a listing of exactly 1000 means there are more behind it. POST /alert/clearwithdraws a card; a human's Archive is the same disposition. A detector that raised a card bydedupKeycallsclearwith that key as soon as the condition it warned about is gone. It archives the row rather than deleting it — recoverable, still visible to the dismissed-window reader, exactly what clicking Archive produces. The two differ only in who acts: a person archives a card they have read, a detector clears a card whose problem fixed itself, whether or not anyone ever looked at it. "Nothing to clear" is a success, not an error — a detector calls this on every clean tick, so no matching card answers200 { cleared: false }— which is what makes it safe to call unconditionally.- A key whose alert declares a
liveCheckbelongs to the reconciler, not to its detector. Those cards re-check themselves in the app and are withdrawn within a minute of their probe reading "not firing", witharchivedVia = 'live-check'on the row. A detector's own recoveryclearfor such a key is redundant, soclearanswers200 { cleared: false, deferredTo: 'live-check' }and leaves the card alone; "nothing to clear" and "not yours to clear" read the same to a caller, which is what keeps an unconditional clear safe. The detector's counter and its page stamp still reset, so a deferred clear costs one reconciler tick and nothing else — seealert-live-check-contract.md. - A card saved for later is withdrawn by its PRODUCER, not by the app. When a script asked for
a card while the app was not listening, the card is held in the alert spool and replayed on the
next start. Nothing re-checks it at delivery time, so a producer whose finding clears before that
start must delete its own saved copy:
purgeSpooledAlerts(dedupKey)inscripts/lib/alert-spool.mjs. The launch guard does this — a launch that finds the main folder already level with its commit clears the "files left alone" card an earlier launch saved, so the notice is never shown for a state that healed before anyone could read it. The condition to purge on is the producer's own proof the finding is spent, never a guess at "sounds fine now": the launch guard clears only on acleanorrepairedpass, and keeps the card on adeferredorpartialone that still leaves a real gap. - "Your app started on code that is behind" comes only from a start (2026-11-13). Only a launch, a restart, or the tidy-up after you quit raises this card. The every-30-minutes job that keeps the main folder current runs the same check as a background pass: it updates every file the running app does not use, leaves the app's own files for its next start, and raises no card. Before this, that job raised the card about every half hour while one app kept running, with no restart at all.
DELETE /alert/:idis the one irreversible call here. It removes the card permanently: there is no un-delete route and no un-delete button anywhere in the app, andPOST /alert/:id/unarchiverestores an archived card, which is a different state. Useclearor Archive when you mean to put a card away; reach forDELETEonly when the row itself should cease to exist.
Related
- Inbox alerts — authoring them — the developer-facing route, the special characters it has to survive, and the app-generated cards with their own actions.
- Inbox alerts — the lifecycle — what happens on the Alerts screen and over an alert's life, from the dismissal cooldown to auto-remediation.
- Inbox alerts (part 4) — how a card behaves once it is in your inbox.
- Adding an alert — one command, one file, no conflicts: the route for adding a new alert type.
- The Alert Triage Desk — where an alert goes instead of starting its own session: one standing crew lead judges it, and a card the desk cannot take still reaches the crew.
- inbox-overview.md — the inbox they land in.
- Security alerts by email — the copy of every security-category alert that also leaves this computer, so deleting the records here cannot erase the notice.
Last verified 2026-11-09