# mesh-mail-notifier — the default holder of mail-notifier

Built from mesh-mail's source (novox/hq ADR 0378 §9, as amended by ADR 0379, issue 800 part B): it carries a
byte-identical copy of mesh-mail's event shape (`mailevent.go`, pinned by `copies_test.go`, the way
`modules/networkmanager`'s `uplink-tools` carries `ifwatchd`'s own file, ADR 0241). Nothing here names
Betterbird (ADR 0379 §3), and nothing here reaches a mailbox: it only hears what mesh-mail already said.

## What it does

It claims `mail-notifier` (held once per machine, needing `node-notifier` there) and shows each new inbox mail
on this machine's notifier, through `node-notifier.send`, at most once:

- quiet during a first sync or a resync (mesh-mail already says nothing then, `imap.go` ~387)
- quiet for a mail from the account's own address (its address, from `mail-store.accounts`; not known, the
  notice is shown)
- quiet for a mail already marked read (`\Seen` in its flags)
- quiet for anything outside the inbox
- of one account's qualifying mail within a sliding minute, the first three are shown one by one; the rest of
  that minute's mail is folded into one notice naming the count and the latest sender, rather than shown one
  by one

A notice `node-notifier.send` refuses stays pending and is tried again, at most once a minute, without holding
up any other account's notice; nothing is deleted before it is shown. Each notice shown emits this module's
own event `shown` (account and message id, never sender or subject), and is kept in its own state (`shown`) so
a redelivered event is never counted or shown twice — by the mail's message id wherever it has one, so a
UIDVALIDITY reset cannot make an already-shown mail look new.

## Where it runs

**Its own account** (`runs-as`), because it hears mesh-mail's restricted stream `MAIL` (novox/hq ADR 0376 §2):
the machine's runtime runs as the operator's account, which every agent shares and which never hears a
restricted stream. Held once per machine (wherever `mail-notifier` is assigned); the operator grants it the
accounts it announces, in mesh-mail's trusted setting `grants` (`mail-store`'s stream).

## Tools

| tool | does |
|---|---|
| `mail-notifier.status` | every account it is granted, when it last showed each one a notice, and any notice still failing to send (its count, last error, since when). Read-only |
| `mail_notifier_health` | how it is: unhealthy once a notice has failed to show for more than ten minutes, healthy otherwise, even mid-retry. Not (yet) the node-engine's own check — this is one process, judged only by its own tool (ADR 0227 rule 8); a watching process of its own is issue 841, not yet decided. Read-only |