Notifications and the inbox
A bell in the app bar shows what is waiting on you, from every page rather than only from the chat.
Two things could be held for your answer — an email from an unknown sender, and a reply the bot drafted but has not sent — and both used to be visible only if you happened to open the chat. A message held while you were on the money pages sat there until you did. The bell replaces that with a durable list: every item that needs you gets a row, the row survives a failed push, and answering anywhere closes it everywhere.
Two things with similar names
This page is about the inbox: notifications/store.py, the notifications table, and the bell. It is not notifications/delivery.py, which is delivery — the dispatcher that sends a message out over Talk, email or ntfy.
Raising a notification does both, and they are separate: a row is written to the table, and separately the text fans out through the delivery layer. A user with no alerts channel loses nothing, because the bell is always there. A push that failed to send leaves the row untouched.
The bell and the panel
The badge is the count of open rows — one number, no dot, no second concept. Every open row means the same thing: something is waiting on you, whether it is waiting to be done or waiting to be looked at. Having seen an item is not the same as having dealt with it, so a held task you have looked at and not answered still counts.
Clicking the bell opens a panel with two tabs:
- All — everything open.
- Needs action — only the items with a button to press.
The panel opens on All every time, and the filter deliberately does not survive a close. Some items are informational and carry no action; under a sticky "Needs action" tab those would never render, never be seen, never resolve, and the badge would climb forever for anyone who lived in that filter.
Tab counts come from the list itself rather than from the badge, so "Needs action (3)" can never sit above a visibly shorter list. The footer reads "Showing N of M open" on both tabs — on "Needs action" it will say something like "Showing 4 of 60 open", which is what that tab means.
A row shows a severity dot, the title, how long ago it last changed, and ×N when the same thing has happened more than once. Opening a row gives the full text, any status note, and every action. Unseen rows differ by weight only, so they read as new rather than important — severity is the dot's job.
Dismiss appears only on a row with no actions. Where there are actions, answering is how the item closes, and offering Dismiss beside Confirm and Discard would ask you to tell apart two pairs of buttons that look alike and are not.
What raises a row
These are the main sources.
| Source | What it is | What you can do | Closes when |
|---|---|---|---|
confirmation | A task parked waiting for your approval — a gated email from an unknown sender, or a question the model asked mid-run | Confirm, Discard; for a relay question, a room post or a guest's held reply, Open (your private chat, where the full text is) and Discard | The task leaves pending_confirmation |
outbound_draft | A reply the bot composed and held at the delivery gate | Send, Discard, and Open, which goes to the email thread's note in your private chat (or, with no note, the room the draft was filed under) | The draft is sent or discarded |
cron_job | A scheduled job the scheduler switched off after five consecutive failures | Nothing in-app; the status note names !cron enable <name> | The job's failure counter returns to zero |
connected_service | A stored credential the remote rejected (Garmin today) | Reconnect, which links to Settings | The service reports connected again |
health_panel | A lab panel left in draft after OCR | Review, which links to the Labs page | The panel leaves draft |
task_alert | One-shot alerts: a task that failed, a mail throttle notice, a confirmation that timed out, a DMARC warning, a result that reached nobody, a private note with no private chat to go to, and the push for an email thread's note in a web-only private chat | Nothing; it clears itself once you have seen it | You open the panel with it visible |
relay_question | A relay question another user asked you, waiting for your answer | Open, for a question in a room, which opens that room; the view shows the question | The relay is answered, expires, fails or is cancelled |
message_relay | A change to a relay question you asked: delivered, failed, answered, or an answer kept back | Nothing; !relay show has the detail | You open the panel with it visible, or the answer reaches you |
assignment | An assignment handed you a step, was paused, says it is done, is low on budget, reported progress, or completed | Links to its page, chat and its folder; you answer on its page or in chat | A step, pause, proposed completion or budget notice when its condition clears; a report or "completed" notice when you see it |
Six are object-backed: something outside the table changes and the row closes. task_alert and message_relay are fire-and-forget — nothing will ever close them, so they close when you see them. assignment is both, by kind: its step, pause, proposed-completion and budget notices are object-backed, and its progress reports and its "completed" notice close when seen.
Three of these are worth spelling out because the obvious reading is wrong.
A suspended cron job is tracked by its suspension, not by whether it is enabled. CRON.md owns the enabled flag, and auto-disable after five failures never writes it: the scheduler records the suspension in auto_disabled_at, which the file cannot express and the CRON.md sync never touches (see failure handling). The row closes when the suspension is lifted: a successful run, !cron enable, or an edit in CRON.md to what the job dispatches. A module job is the exception below.
A module job (_module.*) raises nothing here at all. Those are re-enabled hourly whether or not anything was fixed, so a row would be raised, marked stale by the rescue, and reopened an hour later — and a reopen delivers. That turns a permanently broken module job into an hourly push with no command to run against it. A module job failing for a reason you can act on has a source of its own: a dead Garmin credential raises connected_service.
A task_alert the model wrote itself comes in three grades, and only two of them interrupt you. security and action_needed are written to the panel and pushed. note is written and never pushed: info severity, no action chip, closed on the first render. It is also the fallback, so the two loud grades have to be named — an unrecognised type, or an alert with no type key at all, is a note. That direction is deliberate. It used to collapse onto security, and the example in the bot's own email guideline wrote the file with no type, so the shape a model copies landed on the loudest grade in the system: an ordinary polite refusal to a stranger arrived as "Action needed", and their follow-up as "Security alert" at danger severity. A grade that interrupts somebody was reachable by saying nothing.
How an item closes
Five ways, and the first is the one that normally happens:
- The producer closes it when it closes the object. Approving a confirmation, sending a draft, reconnecting a service, reviewing a panel.
- The liveness backstop. Every time the panel opens, each open row is re-checked against the thing it is about. An item answered over Talk, by email, or by timeout is found already handled and marked stale. This is why a question answered on another surface can never sit in the panel looking unanswered.
- Seeing it, for fire-and-forget rows.
- Dismiss, on a row with no actions.
- Age, for fire-and-forget rows nobody ever rendered — see retention below.
The backstop is a backstop. Every producer closes its own rows; the re-check exists so that nothing depends on a producer having remembered to.
Repeats collapse
The same thing happening again bumps one row rather than adding another. A nightly job failing four nights running is one entry marked four times, not four entries. Fifty forged messages in one burst leave a single entry, counted fifty times, naming the senders it has room for.
This is the deduplication a chat channel structurally cannot do — in Talk, four failures are four messages.
A repeat does not re-notify; a reopen does. If you dismissed an item and the same thing happens again, that is a second thing to hear about, so the row reopens and pushes. Dismissing means "not now", not "never again".
Retention
Two windows, neither configurable:
- Fire-and-forget rows nobody read are closed after 14 days, so the count cannot climb forever.
- Closed rows are deleted after 30 days.
Open object-backed rows are never deleted at any age. They are held items, and the thing holding them is still there. A held draft still waiting after a year is still waiting.
Delivery, and the three postures
The inbox does not change how anything is routed. A row is written; separately, the text goes out through the same Talk / email / ntfy dispatcher as before. Which destinations that reaches is unchanged — see per-user configuration.
A confirmation's push goes to ntfy and email only. A question waiting for your approval is already in a room: your private chat, the web room you asked it in, the Talk room, or the alerts room as the email gate's own prompt. Its push therefore skips every destination with a room behind it (Talk and web, and SMS and WhatsApp, which record the push in your phone room), so the same question never lands in a second room. If your alert routing names neither ntfy nor email, the question is not pushed, and the bell row stands. A question that is in no room is pushed to your whole alert routing instead: one asked about a shared room when you have no private chat, and an email gate prompt that could not be delivered.
What varies is whether a producer sends at all, and that is decided per producer rather than per source:
- Write and deliver — most sources. A dead Garmin credential delivers because the wiped credential takes the sync job with it, so nothing would ever notice again.
- Deliver only where nothing else alerts you — a relay question. One that went to your room pushes; one that went to WhatsApp or SMS is written and not pushed, since the message on your phone already is the alert. The pushed text never contains the question.
- Write, never deliver — a draft lab panel. The producer is the upload handler and you are looking at the review screen it just returned you to, so pushing "lab results are waiting" at that moment is a notice about something you are in the middle of doing.
- Deliver to ntfy and email only — the note about an email thread when your private chat is web-only. The note is already in a room, so its one push skips every destination with a room behind it, as a confirmation's does. A Talk or WhatsApp private chat gets the note as a post and no bell row.
- The producer keeps its own send — the DMARC canary, the mail throttle, the expired-confirmation notice. Each has its own delivery window already and stamps the row rather than sending twice.
Configuration
The inbox itself has no configuration. The retention windows above, the 500-row scan ceiling and the panel's 50-row page are constants in the code. Native push has deployment settings described below.
The bell polls every 30 seconds from whatever page you are on, backing off after repeated failures. On a page that already holds a room's event stream open, the count also rides that stream, so an item parked while you are reading a room lights the bell in about a second rather than up to thirty. That fast path is an optimization, not the contract: turning the room stream's tick off (room_stream_room_check_seconds = 0) leaves the 30-second poll doing the job.
Push notifications
Native push adds iOS alerts alongside your existing Talk, email or ntfy routing. A new or reopened inbox item can reach each registered device. Unread chat messages wait briefly before sending, so a message you read in the open room usually needs no alert. Messages arriving together produce one alert per room, with a count and the newest text. Archived, dismissed and hidden email rooms do not alert.
The app badge counts open inbox items from enabled categories plus unread messages in rooms set to alerts or badge. The bell, inbox list and ordinary chat unread counts stay complete regardless of push preferences. Reading on another device causes a quiet badge update on the next sweep. Old messages after a scheduler outage update the badge without a burst of banners. A failed alert is not retried; the next sweep can still repair the badge.
Settings → Notifications holds your personal push preferences. The page is available in browsers and older apps too. Category switches, the chat default and message previews use the shared Save button; edits survive a switch to another settings section and save together. Removing a device takes effect immediately.
Push preferences are personal:
- Inbox categories: each registered source can be turned off for push alerts and the app badge. Missing choices default to enabled, including new sources. Turning a category off leaves its inbox items and other delivery channels alone. Alerts suppressed during a sweep are acknowledged, so turning the category on later restores its open-item badge contribution without replaying those alerts.
- Chat notifications: alerts and badge, badge only, or off is the account default. Each room can inherit that default or choose its own mode. An explicit alerts setting works even under an off account default. The choice affects only your handle, including in a shared room where you are not the host. It does not mark messages read or change room unread chips. Enabling a room restores its unread badge contribution without replaying messages already passed by the sender.
- Show message previews: on a standard installation, Apple receives the title and a short body as part of the APNs payload. APNs is not end-to-end encrypted. On an installation with private push, below, the preview travels encrypted and Apple sees only a fixed alert. Turning previews off replaces the text with a generic notice or room label and an empty body; the badge and navigation data remain.
Registration requires an iOS shell with native push support (0.11.0 or newer). In that app, use Register in the settings card and allow notifications when iOS asks. If permission is denied, the card opens iOS Settings and rechecks permission when you return. Registration completes only after the server accepts the device token. Browsers and older shells show a stand-in message. Remove a device from the card to stop further pushes to it. APNs accepting a request does not establish that iOS displayed it: notification settings and focus modes can suppress it.
The preference APIs are available in browsers too. GET /push/categories lists the live source registry with server-owned labels. PUT /settings/profile accepts push_inbox_categories as an object of registered source IDs and booleans; {} restores all categories. PATCH /chat/rooms/{id} accepts push_notifications as default, alerts, badge or off, after checking your handle ownership and current membership. GET /notifications/count keeps its ordinary counts and adds push_badge. The dispatcher and test-send command use the same filtered calculation. The native app reads that filtered total on every route, preserves it across partial live updates, and refreshes it after reads, saved preferences and a return to the foreground. A failed count fetch keeps the previous badge; an offline launch does not assume zero. These preferences also round-trip through settings plans and snapshots, with the usual managed-field restrictions.
Logging out removes only the device registration made in that session, and only while it still belongs to that account and registration generation. Another device or a newer registration is kept. Enrollment is persistent: cookie expiry alone does not remove it, and a browser cannot identify a registration from a different or expired session. Use device removal to revoke those registrations. The sender rechecks the enrolled authentication method and credential epoch against the same account rules as web sessions before each send. Disabled accounts, revoked credentials and unavailable authentication methods stop delivery; email/local-code accounts also require an identity and profile. Nextcloud follows its existing session rules, including support for accounts without a local email identity. Registrations from before this auth binding was introduced require registration again. APNs detects invalid tokens, not application logout; a request already in flight cannot be recalled.
Operators must enable Push Notifications on the app's Apple App ID, provision the shell, install the server's push extra and configure [push] with an APNs auth key before enabling dispatch, unless the installation sends through a push relay (below). The default dispatch interval is five seconds, chat delay is fifteen seconds and maximum alert age is five minutes. Keep the key file private to the service account. istota doctor checks its presence and permissions; istota push test --user U sends a diagnostic to that user's registered devices. Debug builds use sandbox tokens and TestFlight uses production tokens.
Private push
With [push] content = "private" and a signing key (from istota push keygen; on the stack from istota-stack push-key create, or the management role's istota_push task where the role manages the stack), no notification the installation sends puts its text or routing where Apple can read it. What each device receives depends on how it enrolled:
- Private previews: a device that enrolled a device key (iOS 17 or newer, on a shell that supports it) gets the title, body and tap target encrypted to that key and signed by the installation. The phone decrypts the preview itself, with no network request. Apple delivers the fixed alert described in the next item, and the phone replaces it with the decrypted preview.
- Private, no preview: every other device gets a fixed alert, the bot's name and "You have new activity.", with no preview and no tap target. That covers iOS 15 and 16, older shells, and a device enrolled before the signing key was replaced, until it enrolls again. A private installation never falls back to a plaintext preview.
What Apple still sees: when each notification is sent, its size rounded up to one of four padding sizes, the badge count, the device token, and opaque identifiers that change with the signing key. It does not see room names, room tokens, notification IDs, routes or account names. Badge-only updates are the same as on a standard installation, since they carry only the count.
If the signing key goes missing or cannot be read, the dispatcher logs one warning and sends every device the generic alert until it can read the key again, so phones still hear that something arrived and badges stay current. No text is sent in that time, and no preview is recovered later. A device whose stored key cannot be used records private_payload as its last error and the other devices are still sent. Switching back to content = "legacy" returns every device to plaintext previews, and is the operator's choice. The wire format is private push v1.
Relay delivery
With [push] delivery = "relay", the installation sends every push through a push relay instead of to Apple directly, and needs no APNs key and no HTTP/2 library of its own. The relay holds the APNs key for the app and forwards only what the installation has already sealed. Relay delivery is private push only: it requires content = "private", a signing key, and an https:// relay_url such as https://relay.example.com/istota.
When a phone enables notifications, the app enrolls with the relay and hands the installation a route and a send capability for that one device. When the app's device token changes, the relay keeps the route and the app registers again under the new token; the installation then removes the registration under the old token, without revoking the route. The installation keeps the capability in a file of its own, mode 0600, in the push credentials directory, push/relay beside the framework database (/data/db/push/relay on the stack). The database holds the file name, never the capability. Devices on iOS 15 or 16 cannot enroll a device key, so on a relay installation they get no push at all.
What the relay sees: when each notification is sent, the sealed envelope (padded, signed, encrypted to the device), the badge count, and the route, which it maps to the device token. It cannot read the title, the body or where a tap leads. Apple sees what it sees for any private push.
Each push is one request to the relay, and nothing is resent. If the relay is unreachable, busy or rate-limiting, that alert is lost and the device stays registered; the next one goes as usual, and the badge catches up with the next badge update. If the relay says a device's route has expired or was revoked, or the installation finds its credential file missing, the device is marked as needing to enroll again and is skipped until the app enrolls it again from Settings → Notifications. A device enrolled under an older signing key gets badge updates but no alerts, since the relay forwards only sealed envelopes; Settings → Notifications shows it as needing to enroll again too. If the relay reports the device itself invalid, as Apple reports an uninstalled app, the registration is removed.
Removing a device, signing out of the session that registered it, or a new enrollment that replaces a device's route also revokes the old route at the relay. The request does not wait for the relay: the route is queued in the same database write that removes the device, and the daemon sends the revocations with its push sweep, up to 20 at a time. A revocation the relay does not accept is retried with a growing delay, starting at 30 seconds and capped at six hours, or longer when the relay asks for that; after seven days it is dropped and the route lapses when its lease ends. The capability file is deleted once its revocation is done or dropped. istota doctor --only push.relay warns when revocations have been waiting for more than a day, and counts devices that need to enroll again.
There is no fallback between relay and direct delivery; which one an installation uses is the operator's setting. A device registered before a switch to relay delivery has no route, so it is marked as needing to enroll again. After a switch back to direct delivery, devices marked that way are sent to directly again, and a route removed later is still revoked at the relay that issued it, which the installation records with each route. With push turned off on a relay installation, registering a device says that notifications are off on this server.
Safety notes
Titles and bodies carry text somebody else wrote — an email subject, a sender's name, a value parsed out of a mail header. Two rules follow, and both are enforced rather than assumed:
- Every field renders as text, never as markup. There is no HTML injection point anywhere in the feature. Formatting characters are stripped from titles; bodies keep their line breaks and every character that cannot make a link, a code span, raw HTML or a table, because deleting more corrupts what the text says.
- Every link and every action target is checked against an allowlist — a relative in-app path and nothing else — at the moment it is rendered, on both the server and the client. A resolver that builds one path wrongly has its whole view downgraded rather than just the bad field.
Keys are bounded on every axis they are built from, so a value an attacker chooses cannot mint one durable row per value, each firing a push.
Upgrading
Items already held when you upgrade are carried over. The first run seeds the inbox from the two queues that already existed — tasks parked for confirmation and drafts held at the gate — so nothing waiting is lost. That seeding writes rows and delivers nothing, so an upgrade does not fan your whole backlog out to Talk at once.
One scope note: a draft that was already mid-send at upgrade time is not seeded, and stays invisible to the bell.
Related
- Web interface — the app bar, the pages, the API routes
- Web chat — the in-transcript confirmation and draft cards, which are unchanged
- Email — the inbound confirmation gate and the outbound approval gate, the two biggest producers
- Scheduling — cron jobs and the five-failure auto-disable
- Database — the table
Push enrollment is bound to the login that registered it. Signing out removes that login's device registrations even if an older polling response arrives after registration. Older sessions may ask you to sign out and back in before registering. Local mode without sign-in uses the device Remove button.
A phone that was offline can retain an old badge after you read items elsewhere. Opening the app refreshes it. Push acceptance does not confirm that the phone received the update.