kijito-tools 0.2.0

package/providers/monitor/docs/DESIGN.md

@@ -0,0 +1,984 @@
+# Kijito Inbox Monitor: Design & Implementation Spec
+
+**Updated:** 2026-08-15 (rev 9: §6.5 Darwin `boottime` re-sourced from `CLOCK_MONOTONIC_RAW` - Darwin's
+`CLOCK_MONOTONIC` is calendar-derived and read below `CLOCK_UPTIME_RAW` at fresh uptime - plus the
+inverted-pair quarantine at the emit chokepoint).
+Rev 8 (2026-07-25): the bounded-window / delivery-acknowledgement contracts, from seven rounds of
+adversarial audit - §5 pagination consistency, §7.0 acknowledged delivery + durability ordering, §7.3 strict
+persisted schema + corrupt-state recovery + case-only identity migration, §14.7 the three case layers.
+Rev 7 was remote-only: watches your Kijito inbox at `api.kijito.ai`, token required; the `--url`/SSRF-by-class
+machinery is gone - see §5, §8, §11. Builds on rev 6 (v2 multi-persona + supervised producer).
+**Status:** shipped and live (v2 under launchd).
+
+**Goal:** give Kijito a solid, usable client-side liveness watcher for its built-in inbox. The concrete
+Kijito-inbox monitor is the win. Agnosticism is a means (generalize only where it makes the tool more
+useful), not the end. Learn from prior art, and don't gold-plate.
+
+§1 through §13 are the v1 single-persona core, still accurate and load-bearing (one process watches one
+inbox; the cursor/dedup/FSM/self-test/state/seam contracts apply per-persona unchanged). §14 records
+the v2 deltas: the deployed build watches your whole Kijito account from one supervised process and writes
+one owned, self-rotating event log per persona. Read §14 alongside §1, §11, and §12 for current reality.
+
+---
+
+## 1. What it is
+
+A standalone, single zero-dependency Python-stdlib script (urllib, json, signal, select, fcntl, subprocess;
+no pip installs) that polls the Kijito inbox and emits one event per new message into whatever harness is
+running, as NDJSON on stdout and/or exec-a-command-per-event. It is the client-side liveness watcher: it
+keeps a running agent's inbox live by waking it between tool calls. It is not a server, and not a
+notification service. POSIX target (Linux/macOS); Windows runs interval-only (no SIGUSR1 seam, no flock,
+per §10/§7.3).
+
+## 2. The problem
+
+The "inbox-liveness" LLM-UX bug: agents predictably fail to keep an independent inbox check alive. They tie
+it to a work loop that ends, or never set one up. The fix is to move the burden off agent-discipline and
+onto a running guarantee: an independent process that watches and emits, decoupled from any work loop.
+(Dogfooded; adversarial review surfaced real bugs in its own early versions, which are folded into this rev.)
+
+## 3. The composition contract (locked with the server side)
+
+This is the client half of Kijito's server-side inbox-liveness system. Two complementary layers:
+
+| Layer | What | Where | Guarantee |
+|-------|------|-------|-----------|
+| **Banner** (server) | unread banner in every Kijito tool response | server-side, every client | zero-setup floor; delivery-on-next-call |
+| **Watcher** (this) | independent process polls and emits per-new-item | client-side, harnesses that run a process | proactive; wake-without-a-call |
+
+- One shared signal source (the `control_plane` urgent counter) so liveness never diverges; the watcher
+  consumes a server count over HTTP (§9) and never reimplements liveness.
+- v1 is a pure poller of the Kijito API plus the opaque-wake seam (§10), so a hosted bridge can later push wake-then-pull.
+- Marketplace: the goal is to surface it as "the local liveness watcher for your Kijito inbox."
+
+## 4. Architecture
+
+`SOURCE adapter (http-poll) → GENERIC CORE (cursor/dedup/alert-FSM/self-test/state/wake-seam) → EMIT (stdout-jsonl | exec-per-event)`.
+v1 ships one adapter (`http-poll`, the Kijito reference). Future adapters are explicitly deferred.
+
+## 5. The `http-poll` adapter: Kijito inbox contract (code-verified, audited 2026-06-17)
+
+- **Endpoint:** `GET /api/inbox?persona=<P>&mark_read=false`
+- **Response:** `{"result": [ {"id":<int>,"from":"<persona>","content":"<plaintext>","created":"<iso-str>","read":<bool>}, ... ]}`
+  (keys verbatim, in that order, per messaging.py:85-89). v1 hard-bakes this Kijito response shape (there is no
+  generic parse config; that's deferred, see §scope). The destination is the fixed Kijito API; only the persona varies.
+- **`mark_read` defaults to `true`** (web_api.py:504; SET m.read=true at messaging.py:90-96). The URL must carry
+  `&mark_read=false`. A watcher must peek, never consume: every fetch site (the poll loop and `--self-test`) uses
+  the `mark_read=false` URL. (Triple-confirmed; the original seed was fixed for this.)
+- **`id` is a SERIAL PK, so it is strictly monotonic** (schema.py:168), with gaps allowed. The cursor keys on
+  max-id, never on read/unread state.
+- ⚠️ **The window is BOUNDED and PAGINATED** (this supersedes the original "no pagination: the response is a full
+  list" note, which was true when it was audited and is not now - and assuming it still held is how a bounded window
+  turns into permanent mail loss). The endpoint returns the **newest** rows that fit a count limit AND an aggregate content budget, and
+  declares what it left out via `truncated` (rows withheld, quantity NOT stated), `size_dropped` (exactly N rows
+  withheld) and `size_truncated` (a lone oversized message had its BODY clipped - no row withheld, so it is NOT an
+  omission). Older rows are reached by passing the OLDEST id you were returned back as `before_id`.
+- **The omission declaration and the continuation are two halves of ONE statement.** The server sets
+  `next_before_id = <oldest row returned> if (truncated or size_dropped) else null` - "present exactly when mail was
+  withheld". So a window withheld rows **if and only if** it hands back a continuation, and either half contradicting
+  the other is a contract violation that PINS rather than something to interpret:
+  - withheld rows + `next_before_id: null` → "I hid rows" and "there is nothing older" (Loom re-audit 6, HIGH 3);
+  - withheld nothing + a non-null `next_before_id` → "I hid nothing" and "there is more" (Loom re-audit 7, HIGH 4).
+  The second also follows from how the window is BUILT: a page returns every older row that fit, so if it withheld
+  nothing there is nothing older left to point at. Believing either half steps over what the other one asserts.
+  Verified live across 14 pages including the exactly-at-limit edge (a page returning exactly `limit` rows with more
+  behind it declares `truncated: true`; one that exactly exhausts the mailbox declares nothing and terminates), so
+  the check cannot fire on healthy traffic. Emit only the diff (id > cursor); never dump the body.
+- **The window ALSO declares `unread_not_shown`** - how much unread mail the inbox holds that this response did
+  not hand over. It is a separate axis from the omission/continuation pair above: those describe THIS WINDOW's
+  completeness, while `unread_not_shown` counts unread mail anywhere in the inbox, including messages already
+  emitted to the stream that the agent simply has not read. So it is an OBSERVATION, never a diagnosis of missed
+  mail, and coverage of an un-emitted span is proven by the backward walk, never by this count (§5.2).
+- **Auth:** a Kijito API token is **required** (the API is authenticated). Supply it via `$KIJITOMON_TOKEN` or
+  `--token-file` (file wins over env); it is injected as `Authorization: Bearer <token>`, or with `--auth-header NAME`
+  as `NAME: <token>` verbatim. The header name (`--auth-header`) and the token-value source are independent axes. A
+  missing token is a fatal config error, and an unreadable `--token-file` is a fatal config error. Every request also
+  carries a named `User-Agent` (the API WAF rejects the default Python-urllib UA with a 403).
+- **A poll is healthy iff** HTTP 2xx, and the body parses, and the envelope is shape-valid (`result` is a list; every
+  row is an object with an integer `id`). Anything else (non-2xx, connection-refused, DNS failure, connection-reset,
+  timeout, parse-fail, shape-violation) is a liveness failure (UNKNOWN), never "no mail." (A 200 with a
+  truncated-but-parseable body that fails the shape check is a failure.)
+- **Empty `{"result":[]}`** is healthy, with no new items.
+- **Hive-off / 404 timing matters:** detected at startup or `--self-test`, it is a fatal config error (exit
+  non-zero). Appearing mid-run, it is a per-poll liveness failure (the daemon may have restarted or the hive toggled
+  transiently); it feeds the §7.1 FSM and does not kill the process (a transient server blip must not destroy the
+  dead-man's-switch).
+- **Config:** `poll_seconds` (default 60). The destination is the hard-baked Kijito API inbox URL including
+  `mark_read=false`; only the persona varies.
+
+### 5.1 A bounded window must not silently swallow mail (fail closed)
+
+The cursor is a **confirmed-contiguous watermark**: everything at or below it is known delivered. It may only
+advance over a span the watcher has actually seen.
+
+- **The discriminator.** If the returned window reaches back *past* the cursor, every omitted message is older
+  than the watermark and was already delivered - the ordinary case, since long-polling keeps the backlog to a
+  message or two. If the window starts *above* the cursor while the server admits it dropped rows, the span
+  between them may hold mail never emitted.
+- **Coverage comes from EXHAUSTION, not arithmetic.** `truncated` says rows were withheld without saying how
+  many, so no count can prove a span empty - a single recovered message would "close" an unbounded hole. The
+  watcher instead pages BACKWARD with `before_id` until it reaches the watermark or the chain ends. Walking
+  terminates; counting cannot. This is also what makes an *inexact* omission closable at all, and it reaches
+  mail someone has already read, which an unread-only reconcile structurally cannot see.
+- **A walk that does not complete is not coverage.** Transient failure, a non-advancing cursor, or the
+  `WALK_BACK_MAX_PAGES` budget leaves the watermark **PINNED** and raises an `alert`. Visible mail keeps
+  flowing while pinned; ids emitted above the pin are remembered (and persisted) so nothing is re-delivered.
+- **Pagination contract:** pass the OLDEST id you were returned as `before_id`; repeat until the page is empty
+  or `next_before_id` is null; OMIT the parameter for the newest page, because `0` is a real cursor rather
+  than "no cursor". A malformed cursor is a hard 400, never a silent fallback to the newest page - that
+  loudness is what makes a completed walk usable as evidence. Order by **`id`**, never `created`: timestamps
+  are stamped pre-lock while ids are assigned under it, so concurrent senders invert.
+
+### 5.2 `unread_not_shown`: a cheap alarm, never a coverage mechanism
+
+`unread_not_shown` reports how many unread messages the server holds that this response did not hand back
+(`max(0, unread_count - rows_returned_still_unread)`, evaluated after this fetch's `mark_read`). Above zero,
+the watcher raises an `alert`; it is a superset of "withheld by the budget", which is the right answer for an
+alarm because you want to know regardless of *why* mail is absent.
+
+Three properties keep it honest:
+
+- **It is an observation, not a diagnosis.** The count covers unread mail anywhere in the inbox, including
+  messages this watcher already delivered that the agent never read, so it is not by itself evidence of missed
+  mail. The event carries `above_watermark` - whether the window floor sits above the cursor - as the
+  discriminating fact, and leaves the interpretation to the reader. Coverage stays with §5.1's walk: this is a
+  COUNT with no cursor of its own, so it can say THAT something is out of view but never WHICH rows.
+- **A zero is not self-justifying.** The server computes the field ONLY when it withheld something;
+  otherwise it is `0` **by construction**. So the negative answer requires positive evidence - either the zero
+  was genuinely computed (`next_before_id` is not null), or the window is structurally complete (nothing older
+  and nothing withheld). A count the server never stated at all is a THIRD state, and asserts nothing in
+  either direction; coercing that silence to `0` would manufacture an all-clear.
+- **Evaluate it on the NEWEST-PAGE poll only.** On a backward-walk page, `next_before_id is null` means
+  merely "nothing older than this page". Measured live against an inbox holding four unread: the newest page
+  reported `0` (correct - all four were in it), a mid-walk page reported `4` (the whole inbox's unread, not
+  that window's), and the terminal page reported `0` with all four sitting above it. Feeding walk pages to the
+  check would invent alarms and clear real ones.
+
+It is evaluated on full inbox polls only, so the §9 fast path (which skips the inbox fetch while the unread
+count is not rising) can delay it by at most `--resync-every` skips. That is acceptable for an alarm whose
+whole point is cheapness: the condition it reports is not one anybody can act on faster for hearing sooner.
+
+Routing follows the stranded-mail alarm - an `alert` rather than a new event name, no ack, self-clearing when
+the condition goes away - but fails the OPPOSITE way on an unknown directory. The stranded alarm withholds,
+because alarming with no directory would flag every persona; this one concerns the target's own inbox, where
+the worst case of firing is a line in a stream nobody reads and the worst case of withholding is the silent
+wake gap the tool exists to prevent.
+
+### 5.4 Authorship: an attributable liveness signal, collected for free
+
+`--activity-file PATH` publishes, refreshed each tick, the newest message id each persona has been observed
+to have AUTHORED. It exists so a harness can answer "has X been active since my message?" without inventing
+its own scan.
+
+**Why authorship and not the obvious signals.** Two seemingly better sources are both forgeable by accident:
+
+- **inbox read-state** - any agent calling the inbox with the default `mark_read=true` produces X's read
+  bit, so "X read their mail" only means "somebody read X's mail". It also fails the other way: a member
+  consuming its `events.<persona>.ndjson` stream reads its mail without ever touching read-state.
+- **`/api/presence`** - a GET carrying `?persona=X` BEATS X into the active roster, so any observer probing
+  X makes X look alive. A diagnostic read that writes the state being diagnosed.
+
+Only B produces B's outbound, and no third party can manufacture or erase it. That is the whole selection
+criterion: a liveness check built on a bit any observer can flip is not a check.
+
+**It costs nothing.** All-personas mode already fetches every inbox every tick, the URL already hardcodes
+`mark_read=false`, and every row already carries `from`. The alternative - a client polling every inbox on a
+timer to reconstruct this - is not merely wasteful but dangerous: one missing `mark_read=false` in that loop
+destroys read-state fleet-wide, on a schedule.
+
+**Two coverage limits, both published, because a claim of silence is only as good as the watching.**
+
+- `observed_since` - this process saw nothing before it started.
+- `observation_floor_id` - the **MAXIMUM** of the per-inbox window floors, deliberately not the minimum. A
+  persona's outbound lands in whichever inbox they wrote to, so "they authored nothing" is only as strong as
+  the WORST-covered inbox; between the lowest and highest floor there are inboxes we have not seen into.
+  Measured live: the watcher had seen ids down to 1160 in one inbox while another reached only 1179, which
+  made a question about id 1165 look answerable when it was not.
+
+So `activity_since()` is a TRI-STATE - active / no-activity-in-a-span-we-covered / **NOT OBSERVABLE** - the
+same discipline as §5.2. Absence of evidence is evidence of absence only if you were actually watching.
+
+**Evaluating it: `--check-activity PERSONA --since-id N [--waits K]`.** A one-shot read of a published
+report, with no token, no network and no watch loop, so a shell heartbeat can call it. The exit codes are the
+contract, and 1 and 2 are distinct on purpose:
+
+| exit | meaning |
+|------|---------|
+| 0 | evidence of activity - nothing to report |
+| 1 | no activity in a span this report actually covered; the observation is printed |
+| 2 | NOT OBSERVABLE, or the report is missing/corrupt - no claim in either direction |
+
+Collapsing 2 into 1 would turn "I was not watching" into "they were silent", which is the false assertion the
+whole signal exists to refuse. Both the running watcher and the one-shot go through the same
+`evaluate_activity()`, because a second implementation of a tri-state this subtle is a second chance to get
+it wrong.
+
+**The observation states what was seen, never why.** `activity_observation()` renders the finding with the
+wait count and the last-evidence stamp alongside it, and a test asserts the text contains none of
+`FORBIDDEN_DIAGNOSES` - deadlocked, unreachable and still-working are indistinguishable from this data and
+need opposite responses (one wants a ping, one wants a human to restart a bridge). That rule lives in the
+code, not only here, because a rule that lives only in prose does not run.
+
+### 5.5 Urgent-unanswered: escalated mail nobody is answering
+
+    ALARM IF  unread_urgent > 0  AND  activity_since(persona) is False
+
+**Why this alarm can exist at all.** "Is this member stuck?" normally cannot be answered from outside,
+because a member idle BY DESIGN and one that is wedged look identical - so the alarm fires on every dormant
+persona and rots into noise, which is worse than not having it. What breaks the tie is a declared
+EXPECTATION. `unread_urgent` is one: not the recipient declaring liveness, but a **sender** declaring that
+this needs attention now. Silence only means something once something was expected, and this is the only
+place the hive records an expectation.
+
+The consequence is that a quiet persona with no urgent mail NEVER trips it. The alarm fires exactly where
+somebody escalated and nothing happened, which is the population worth waking a human for.
+
+**Both halves must be positive.** `activity_since` is a tri-state (§5.4) and only an explicit `False`
+qualifies - a NOT-OBSERVABLE answer means the watcher was not running for the span in question, and
+reporting that as silence would be the fabrication the tri-state exists to refuse.
+
+**It costs nothing.** `unread_urgent` arrives on the same `/api/notify/pending` row as the unread count the
+fast path already fetches every tick; the field was previously parsed and discarded.
+
+**Kept disjoint from stranded-mail (§ above) on purpose:** that alarm is for inboxes nobody OWNS, this one
+for real directory members who are not responding. Two alarms covering one inbox drift apart and then
+disagree about it, so this one skips any persona the directory does not know and lets the stranded check own
+that case.
+
+Routing and honesty follow the same rules as every other alarm here: an `alert` rather than a new event
+name, one summarising event per watcher so discovering several at once cannot become a wake storm, the
+OBSERVATION and never the diagnosis, and self-clearing when **either** half of the predicate clears - with
+no ack, since an ack would let someone silence "nobody is answering escalated mail" while it stayed true.
+
+> **Known uncovered property.** The alarm is evaluated AFTER the per-target polls, so this tick's authorship
+> is already recorded when it judges. That ordering is asserted by a comment and by review, not by a test -
+> it is a property of the run loop's composition that the unit suite does not reach. Its failure mode is
+> benign and self-correcting: a member who authored mail during the same tick could be reported quiet once,
+> and the next tick clears it.
+
+### 5.6 Alarm routing: evidence of a consumer, not just a name
+
+Account-level alarms (stranded-mail, urgent-unanswered) go to watchers, and "every directory persona" is the
+wrong list: a directory accumulates names, and long-dead test personas keep receiving alerts into streams
+nobody reads. That is the same defect as a broadcast amplifying phantoms, so it is fixed ONCE here rather
+than separately in each alarm - two predicates for one question drift apart and then disagree.
+
+`has_consumer_evidence(persona)` is POSITIVE and mirrors the stranded-mail ownership test deliberately:
+observed authorship, or memories the directory says they own. Authorship alone suffices, because a brand-new
+persona that has written mail but owns no memories yet is real - excluding it would break first contact. An
+unreported memory count leaves a persona eligible: no data is not evidence of absence.
+
+**It fails open, and that matters more than the filtering.** If the predicate would leave NOBODY, every
+directory watcher is used instead. An alarm delivered to a stream nobody reads costs one line; an alarm
+delivered to nobody is the silent failure this tool exists to prevent, and a filter that can silence every
+recipient at once is a worse bug than the noise it removes.
+
+Measured on a live account: recipients fell from 25 to 18. The seven dropped own zero memories and were
+never observed authoring; two remaining test personas own two memories each, so they carry positive evidence
+someone worked under those names and the same predicate keeps them - consistent with the ownership rule that
+decides whether an inbox is stranded.
+
+## 6. Emit modes (portability)
+
+"NDJSON-on-stdout is universal" is false on ingestion: Claude Code ingests per-event (hooks: JSON-on-stdin,
+exit-code, `additionalContext`; plus FileChanged); LangGraph/OpenAI-Agents/Cursor are in-process (no stdin/stdout
+event ingestion). So `exec-per-event` is the more portable primitive; `stdout-jsonl` is the ergonomic default.
+
+### 6.1 Event schema (stdout-jsonl)
+
+One object per line; every event carries `event`, `source`, `ts` (emit-time UTC ISO), `event_id` (§6.3),
+`nonce` (§6.4) and `emitted` (§6.5).
+```
+{"event":"new",         "source":"kijito-inbox","ts":"<iso>","id":246,"from":"river","content":"<≤N or omitted>","created":"<iso>"}
+{"event":"armed",       "source":"kijito-inbox","ts":"<iso>","cursor":250}
+{"event":"alert",       "source":"kijito-inbox","ts":"<iso>","reason":"unreachable","consecutive_failures":3,"seconds":180}
+{"event":"recovered",   "source":"kijito-inbox","ts":"<iso>","cursor":250}
+{"event":"heartbeat",   "source":"kijito-inbox","ts":"<iso>","cursor":250}     # only if --heartbeat; cursor may be null
+{"event":"seed_ahead",  "source":"kijito-inbox","ts":"<iso>","seeded":600,"current_max":539}      # seed > reality (§7.0)
+{"event":"replay_capped","source":"kijito-inbox","ts":"<iso>","capped_to":539,"dropped":389}      # backlog > --max-replay (§7.0)
+```
+- `new` carries `id`, `from`, `content`, `created`. `content` is a silent hard cut to `--content-chars` (default 220),
+  with no marker; or it is omitted with `--no-content`. `seconds` in `alert` is **config-derived, not a measurement**:
+  it is exactly `consecutive_failures * poll_seconds` (a function of two flags), while the failure path backs off
+  exponentially from 1 s and detection can lag inside a `--wait` long-poll, so it does not equal the outage duration
+  and is routinely off by more than an order of magnitude (e.g. `seconds:90` observed against a measured ~48 s outage).
+  Do NOT back-date onset as `ts - seconds`. A measured-monotonic replacement (stamp the first failure, subtract) is
+  queued; the row already carries `emitted.monotonic` for it.
+- **Within-poll emit order (deterministic, total):** `alert`/`recovered` (FSM edge), then `replay_capped`/`seed_ahead`,
+  then `armed`, then `new` (ascending id), then `heartbeat`. So `armed`/`recovered` set `cursor` before any `new`/`heartbeat`
+  in the same cycle, which means `recovered.cursor` is non-null whenever a baseline has occurred (a `recovered` on a poll
+  that also baselines carries the just-set cursor).
+
+### 6.2 `exec-per-event` (`--emit exec-per-event --exec 'CMD'`, `--exec` required iff this mode)
+
+Every event invokes `CMD`; inapplicable env vars are unset:
+
+| env var | new | armed | alert | recovered | heartbeat | seed_ahead | replay_capped |
+|---|---|---|---|---|---|---|---|
+| `KIJITOMON_EVENT`,`_SOURCE`,`_TS`,`_EVENT_ID`,`_NONCE` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `KIJITOMON_ID`,`_FROM`,`_CONTENT`,`_CREATED` | ✓ | - | - | - | - | - | - |
+| `KIJITOMON_CURSOR` | - | ✓ | - | ✓ | ✓ | - | - |
+| `KIJITOMON_REASON`,`_FAILURES` | - | - | ✓ | - | - | - | - |
+| `KIJITOMON_SEEDED`,`_CURRENT_MAX` | - | - | - | - | - | ✓ | - |
+| `KIJITOMON_CAPPED_TO`,`_DROPPED` | - | - | - | - | - | - | ✓ |
+
+The spawned command has a 10s timeout; a non-zero exit or timeout is logged to stderr and is non-fatal.
+
+🛑 **CORRECTED 2026-08-05 - THIS PARAGRAPH USED TO END "(and never holds the cursor back, per §7.0)", WHICH
+WAS THE EXACT OPPOSITE OF WHAT THE CODE DOES, AND HAD BEEN FOR AS LONG AS THE ACKNOWLEDGEMENT CONTRACT HAS
+EXISTED.** In `exec-per-event` mode **your command's exit status IS the acknowledgement**: exit 0 and the
+cursor advances; **exit non-zero or time out and the cursor is HELD below that message and it is re-delivered
+on the next poll** (`emit()` returns False - the Loom re-audit 7 HIGH 1 fix). Delivery also stops at the first
+failure, so a consumer never sees message N+1 before a retried N.
+**Measured, not reasoned:** the unacknowledged-delivery drill (2026-08-05, `evidence/unack-delivery-drill-20260805/`)
+ran an `--exec` that exits 7 and observed one message delivered **six times** with the persisted cursor held at
+the id below it throughout. The README described this correctly the whole time; only this section was wrong.
+★ **The lesson worth keeping: two documents disagreed about a safety-critical contract and nothing detected it,
+because each was internally consistent. A drill that exercises the behaviour is what adjudicated them - a doc
+review comparing prose to prose could not have.**
+
+**`KIJITOMON_NONCE` is AUTHORITATIVE and must NOT be re-derived by consumers** (river's ruling, 2026-08-05,
+after a drill measured that the nonce reached the ndjson wire but never the exec env - so the one channel the
+docs recommend first could not see it). It is derivable from `KIJITOMON_EVENT_ID`, and that is precisely the
+hazard: re-derivation is a second implementation of sha256 + base62 + a pinned alphabet + an 11-char
+truncation, and two implementations diverge - the unpinned alphabet has already produced one false integrity
+alarm against correct data. The divergence surfaces in the *receiving* system as a delivery fault that never
+occurred, not in the consumer that caused it. ⇒ **Duplicate instruments, transmit data:** for a measurement,
+two independent implementations are a safety property; for a shared identifier, divergence *is* the defect.
+
+### 6.3 `event_id`: the producer owns event identity
+
+Every emitted event carries an `event_id`, stamped at the single `Emitter.emit()` chokepoint so a future event
+kind cannot forget one. It exists because leaving identity absent does not remove the need for it - it
+relocates the problem into N consumers, each of whom invents a key and some of whom get it wrong. The observed
+case: a consumer deduping ID-less events by `event+ts`, which is unique only while two events never land inside
+one clock tick, and our `ts` is stamped at emit time.
+
+Two identities, because messages and signals need opposite guarantees:
+
+| kind | id | guarantee |
+|------|----|-----------|
+| `new` | `<persona>:new:<message id>` | the SAME message always yields the SAME id - across a restart, a re-delivery after state loss, and two watchers of one inbox |
+| everything else | `<persona>:<event>:<run>-<n>` | unique to that emission; a recurrence is a different event and does not collapse into its earlier self |
+
+The asymmetry follows from the cost of being wrong in each direction: a duplicated message is duplicated WORK,
+while a duplicated signal is only noise - and conversely, collapsing two outages into one hides the second.
+Repeated announcements of an *unchanged* condition are suppressed at the source (the alarms are edge-triggered
+and self-clearing, §5.2), which is where suppression belongs.
+
+`<run>` is 8 random bytes per process. A bare in-process counter is specifically ruled out: it restarts at 1 and
+issues ids a consumer has already seen to brand-new events, so a correct consumer DROPS live mail - a worse
+failure than the duplicate the id was introduced to prevent.
+
+Deliberately NOT a hash of the emitted line. Byte-hashing couples the consumer to our serialisation, so a change
+to key order, spacing, or `--content-chars` silently changes the dedupe key and re-delivers old events. Verified
+by emitting the same mail from two processes with different `--content-chars`: the `new` ids are identical.
+
+### 6.4 `nonce`: a wake label DERIVED from the event_id, never minted beside it
+
+`nonce = base62(sha256(event_id))[:11]` - 11 base62 characters, top-level, on every event.
+
+⚠️ **THE ALPHABET IS PART OF THE DERIVATION, AND "base62" DOES NOT PIN IT.** The alphabet is
+**lowercase-first**: `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789`, consumed
+**least-significant-digit first** (`s += A[v % 62]; v //= 62`, eleven times, over the big-endian integer of
+the SHA-256 digest). An auditor who assumes the conventional **digit-first** ordering recomputes a different
+string and concludes the nonce does not verify - **a false integrity alarm against correct data**, which is
+worse than no check at all. Found by a reviewer reproducing the recompute independently; recorded here so the
+next one does not have to.
+
+```python
+A = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+v = int.from_bytes(hashlib.sha256(event_id.encode("utf-8")).digest(), "big")
+nonce = "".join(A[(v // 62**i) % 62] for i in range(11))
+```
+
+It exists so a consumer-side wake ledger can join a delivered wake to the queue entry that carried it. The
+obvious implementation - a fresh random value per emission - is **wrong here, and wrong in a way that pages.**
+This producer already has an identity with deliberate semantics (§6.3): a `new` event keeps the SAME id across a
+restart, a re-delivery after state loss, and two watchers of one inbox. A per-emission random nonce would call
+one re-delivered message **two different wakes**; the consumer would find no queue entry containing the second,
+score it LOST, and alarm - on precisely the recovery path this producer exists to survive.
+
+Deriving from the `event_id` makes the nonce stable exactly where that id is stable and distinct exactly where it
+is distinct, so **one rule serves both identity families and neither family's meaning changes.** It also makes
+"recompute-asserted uniqueness" literally true: an auditor recomputes the nonce from the `event_id` in the same
+row, needing nothing else.
+
+The deeper reason, and the one that survives any change in failure rates: **a random nonce DESTROYS information at
+the producer** - "this is the same work re-delivered" becomes unrecoverable downstream, because the identity that
+would have said so was never minted. A derived nonce merely **defers a decision to the consumer**, where a
+`LATE-AFTER-DELIVERED` outcome can absorb it. Between two schemes that each have a false-alarm mode, prefer the
+one whose defect is repairable.
+
+**11 is forced, not chosen.** The consumer contract wants ≥64 bits in ≤11 base62 characters: 10 chars is 59.54
+bits and fails the floor; 12 breaks the ceiling. There is no slack in either direction.
+
+Two constraints on consumers:
+
+- ⛔ **It is an attribution label, not a capability.** It is deterministic and therefore guessable by anyone who
+  knows the `event_id`. Nothing may treat nonce-presence as evidence of authenticity - a forger able to write
+  transcript rows already has what it needs and gains nothing from this value. A consumer requiring an
+  *unguessable* nonce needs a different mechanism, not this one.
+- ⚠️ **It identifies a WAKE, not a DELIVERY.** Two different panes delivered the same message carry the SAME
+  nonce - correctly, it is the same work. Ledgers must key rows on `(nonce, session_id)`, never the nonce alone,
+  or two panes' deliveries collide into one row and per-nonce outcomes silently overwrite each other.
+
+⚠️ **ERRATUM (2026-08-05) - "a re-delivery after state loss" conflates two components.** That phrase, used
+above and in §6.3, names an **emitter capability** and a **watcher trigger** as though they were one thing.
+The emitter does handle a re-delivery correctly when one occurs. **The watcher does not produce one by losing
+its state file:** an absent state file baselines to the newest visible id (§7.0), so the backlog is skipped
+rather than re-emitted - measured, not inferred. The path that *does* reach re-delivery is an **unacknowledged
+delivery** (a refused sink, a non-zero `--exec`), where the cursor is held below the message and the next poll
+re-delivers it. **Do not cite the state-loss case as evidence that re-delivery works: it is the one case that
+cannot reach it.** Written down because the original sentence misled a reviewer into designing a drill around
+the one trigger that cannot fire.
+
+⚠️ **AND THE BEHAVIOUR THAT ERRATUM EXPOSED IS NOW ANNOUNCED.** An absent state file means two things that
+demand opposite responses - a **first launch** (baseline; never flood a new agent with inbox history) and a
+**lost state file** (everything since the vanished cursor is owed to someone). The producer cannot tell them
+apart, because **absence leaves no evidence** - which is why the neighbouring *exists-but-corrupt* case can
+fail closed and this one cannot. The baseline therefore stands, but it now emits a **`baseline_skipped`**
+lifecycle event naming the skipped count, the id range, and the persona's unread count. Nothing is re-emitted;
+the anti-flood behaviour is unchanged. A known-zero unread count stays silent; an **unknown** one announces,
+because reading "I could not determine the count" as "there is none" is the same defect one level up.
+⚠️ Scope of the loss, stated at its true size: the fetch is non-consuming (`mark_read=false`), so **the mail
+survives and stays readable in the inbox. What goes dark is the WAKE** - nothing will announce it.
+
+### 6.5 `emitted`: three clocks read together, so dwell is measurable rather than assumed
+
+`emitted` carries `wall`, `monotonic`, `boottime` and `src`, all read at the same instant at the `emit()`
+chokepoint. It is stamp 1 of a three-stamp wake ledger; the consumer supplies the other two.
+
+⛔ **THE KEYS NAME SEMANTICS, NOT OS CONSTANTS - AND ON DARWIN THE TWO ARE INVERTED.**
+
+| key | semantic |
+|---|---|
+| `monotonic` | does **not** advance while the machine is not executing |
+| `boottime` | **does** advance while the machine is not executing |
+
+| platform | `monotonic` ← | `boottime` ← |
+|---|---|---|
+| Linux | `CLOCK_MONOTONIC` | `CLOCK_BOOTTIME` |
+| Darwin | `CLOCK_UPTIME_RAW` | `CLOCK_MONOTONIC_RAW` |
+
+On Linux the names coincide with the meanings. **On macOS they do not, and there are two separate traps.**
+First, `CLOCK_UPTIME_RAW` is the sleep-excluding clock, `CLOCK_MONOTONIC_RAW` includes sleep (it carries Linux
+`CLOCK_BOOTTIME`'s semantic), and `CLOCK_BOOTTIME` does not exist. Measured on a real Mac: the sleep-including
+clocks ran **18.20 h** ahead of `CLOCK_UPTIME_RAW` - a difference that *is* the accumulated sleep, matching an
+independent `kern.boottime` derivation to two decimals. Second, **Darwin's `CLOCK_MONOTONIC` is
+calendar-derived**: measured 2026-08-15 it read *exactly* `wall − kern.boottime` (201341.498, to three
+decimals), so it absorbs NTP adjustments to the wall clock. (On Linux, `CLOCK_MONOTONIC_RAW` EXCLUDES suspend -
+the same constant name carries a different semantic per platform, which is why the dispatch is on semantics.)
+
+Two prior revisions each fell into one trap. The first read `CLOCK_MONOTONIC` on every platform: on a Mac that
+publishes the *sleep-including* clock under the key `monotonic` and drops the sleep-excluding quantity
+altogether, a consumer differencing wall against `monotonic` measures **~0 freeze forever, on every Mac row,
+with nothing raising** - and a Linux-only test suite cannot see it, because there the names are honest. The
+second sourced Darwin's `boottime` from `CLOCK_MONOTONIC` - right direction, wrong clock: on a fresh-uptime Mac
+whose wall clock NTP-stepped back ~8.3 s after boot, it emitted `boottime 4957.865 < monotonic 4966.194`
+(measured 2026-08-14), violating the definitional invariant `boottime ≥ monotonic`. Both semantics must come
+from **raw** clocks; `CLOCK_MONOTONIC_RAW` and `CLOCK_UPTIME_RAW` share one tick source, so the invariant holds
+by construction.
+
+**The invariant is also enforced at the chokepoint**: if a platform ever hands the producer an inverted pair,
+the `boottime` reading is quarantined - removed from the stamp set (omitted, never faked) and preserved under
+`emitted.clock_defect` (`kind: "boottime_below_monotonic"`, with the rejected value and its source constant) -
+so the row reports the broken mapping loudly instead of feeding it to consumers as data. A positive-control
+test proves the quarantine fires on a deliberately inverted pair.
+
+`src` records which constant supplied each semantic (`{"monotonic":"CLOCK_UPTIME_RAW", ...}`), so the mapping is
+**auditable from the row** rather than resting on the reader's assumptions about the platform.
+
+Three clocks because none answers alone: **wall** is comparable across hosts and to every other timestamp in the
+system, but it *steps* (NTP, hypervisor time sync), so a wall delta is not an elapsed time; **monotonic** never
+steps or goes backwards, but *stops while the machine is not executing*; **boottime** keeps counting through a
+suspend.
+
+Differencing them across two events is what separates two states a single clock conflates: `wall delta −
+monotonic delta` over an interval is time the machine **did not execute**, which is the difference between "this
+wake sat in a queue for three hours" and "the host was frozen". That is not hypothetical - measured on a
+Parallels guest, **72.79 h of hypervisor freeze presented as ordinary elapsed wall time**, while
+`BOOTTIME − MONOTONIC` read exactly `0.00 s` throughout, because a hypervisor pause stops the guest's clocks
+*together* and the guest is not executing to notice.
+
+A key is **omitted, never faked**, where its *semantic* is genuinely unavailable on the platform. A fabricated
+value would be indistinguishable from a genuine zero-freeze reading, which is the failure this field exists to
+prevent. Note the omission rule applies to the semantic, not the constant: Darwin lacks `CLOCK_BOOTTIME` but
+still supplies the sleep-including semantic via `CLOCK_MONOTONIC_RAW`, so `boottime` is present there.
+
+`ts` is deliberately left alone: it is stamped microseconds earlier in the convenience constructors and existing
+consumers depend on it. Use `emitted.wall` when you need the wall reading coherent with the other two clocks.
+
+## 7. Robustness contract
+
+### 7.0 Cursor / dedup algorithm
+- A "re-arm" is a cursor-initialization at startup (resume / seed / baseline). It is not a §7.1 FSM `recovered`
+  (recovery resumes normal diffing with the cursor already tracking; the replay cap below never re-applies on
+  recovery).
+- **Cursor and FSM resolve independently at startup** (they are two separate resolutions, not one ladder):
+  - **Cursor:** (1) explicit `--seed-at <id>` sets `cursor = id` (operator intent wins, overriding any state-file
+    cursor); else (2) a valid identity-matching `--state-file` (§7.3) with an integer cursor sets `cursor =
+    resumed value`; else (3) `cursor = UNSET`.
+  - **FSM** (`state`, `consecutive_failures`): a valid identity-matching `--state-file` always supplies it,
+    independent of `--seed-at` (so `--seed-at` plus a DOWN state-file resumes DOWN, preserving dead-man's-switch
+    continuity); an absent/mismatched/invalid state-file means the FSM starts `UP`/`0`.
+- **`armed` fires on the first healthy poll** (never before a fetch). There is exactly one `armed` per (re)arm,
+  carrying the post-decision `cursor`. A failed first poll does not baseline (it's a §7.1 failure; `armed` waits).
+- **Each healthy poll:** select items with `id > cursor`; sort ascending; emit one `new` per item; then advance
+  `cursor` **only over what was ACKNOWLEDGED**. `cursor` is monotonic.
+  - **The cursor IS the acknowledgement** (Loom re-audit 7, HIGH 1). Advancing past an id means that message is
+    never fetched again, so it may only advance over a message the emitter reports as delivered: `exec` exit 0,
+    or a successful write to the events file/stdout. A non-zero exit, an exec timeout, a failed spawn or a failed
+    write is **not** a delivery: the cursor holds below that id and the message is re-delivered next poll. This
+    replaces the previous "best-effort/at-most-once, an exec failure neither holds back nor re-emits" contract,
+    which silently dropped mail on the one path (`--exec`) whose entire purpose is waking an agent - while the
+    README promised exactly-once. Two documents cannot state opposite guarantees; this one is the guarantee.
+  - **Delivery stops at the FIRST failure in a batch**, so a consumer never sees message N+1 ahead of a retried N.
+    The guarantee is **at-least-once, IN ORDER**; consumers must be idempotent on `id`.
+  - A `--suppress-author` drop is a deliberate POLICY drop and counts as acknowledged (otherwise suppressing an
+    author would pin the watermark on that author's next message forever).
+  - **LIFECYCLE events (`armed`, `alert`, `recovered`, `heartbeat`, diagnostics) are deliberately NOT
+    acknowledged and NOT gated.** The guarantee is about MESSAGES, which the cursor is a record of; a lifecycle
+    event carries no cursor obligation, and holding the watermark because a heartbeat failed to deliver would
+    freeze mail for an unrelated reason. They are best-effort, and an `--exec` consumer will see them re-run
+    only when the message beside them is re-delivered. Note this means a broken `--exec` produces a failed
+    `armed`/`heartbeat` too - that is expected, not a second defect.
+  - **A delivery failure is reported on stderr, never as an `alert` event.** The event channel is the thing that
+    just failed, so an alarm about it would be routed down the broken pipe (exec mode re-runs the same failing
+    command; sink mode writes to the file that just refused a write). Reporting a fault through the faulty
+    channel is how the fault stays invisible. It is keyed on the condition and self-clears, like every other
+    alarm here (§ALARM HONESTY).
+  - **Durability ordering** (Loom re-audit 7, MEDIUM): the event is `fsync`ed BEFORE the cursor that acknowledges
+    it is persisted, and the state-file's directory is `fsync`ed after `os.replace` so the rename itself is
+    durable. Otherwise a power loss can leave a cursor that has forgotten an event no consumer ever received.
+    If the sink cannot be synced, NOTHING emitted in that poll counts as delivered - the acknowledgement is
+    withdrawn wholesale rather than left half-true.
+- **First-healthy-poll branches** (mutually exclusive; each emits exactly one `armed`):
+  - **UNSET baseline** (cursor was UNSET, including a state-file resume whose cursor was `null`): `cursor = max(id)`
+    (or 0 if empty); emit `armed`; no `new`, no cap (nothing to replay). This branch is exempt from the cap.
+  - **Non-null re-arm** (cursor came from `--seed-at` or a non-null state-file resume): let `n = count(id > cursor)`,
+    `current_max = max(ids) if result else 0`.
+    - if `cursor > current_max` (seed/resume ahead of reality): emit `armed{cursor}` plus `seed_ahead{seeded=cursor,
+      current_max}` (real ids ≤ cursor are intentionally skipped); no `new`.
+    - elif `n > --max-replay`: fast-forward `cursor = current_max`; emit `armed{cursor}` plus `replay_capped{capped_to=
+      current_max, dropped=n}`; no `new`.
+    - else (`n ≤ --max-replay`): emit `armed{cursor}`, then replay all `n` as `new` (so exactly `--max-replay`
+      replay at the boundary; `>` is the cut).
+
+Seven lessons (mandatory): use a standalone file, not inline-shell; use a single long-lived process with per-line
+flush; dedup/cursor by max-id plus peek; emit the diff, not the body; a parse/shape/HTTP failure is UNKNOWN, not
+"no mail" (§5); re-arm via `--state-file` or `--seed-at-last-handled`; avoid auto-stop-on-volume (handled by dedup,
+peek, edge-alerts, and the replay cap).
+
+### 7.1 Liveness alert FSM (dead-man's-switch)
+States are **UP** (default) and **DOWN**; `consecutive_failures` counts from 0. A "failure" is any non-healthy poll (§5).
+- **Healthy poll:** set `consecutive_failures = 0`; if DOWN, go UP and emit one `recovered`.
+- **Failure:** `consecutive_failures += 1`; the UP-to-DOWN edge is crossed when `consecutive_failures` first
+  reaches `--alert-after` while state is UP. Then set DOWN and emit one `alert`. (The `state==UP` guard is what makes
+  it edge-once; a resumed `state==DOWN` never re-crosses the edge, so there is no duplicate `alert`.)
+- `alert`/`recovered` are per-edge: a run may alert, recover, then alert again. A sub-threshold blip emits neither.
+- `--alert-after` has a minimum of 1 (0 is rejected) and a default of 3 (a single transient failure is normal,
+  bouncing in ~1-2s). SIGUSR1-triggered polls participate identically.
+
+### 7.2 `--self-test`: runs once and exits (no poll loop)
+Runs for the selected persona(s) (default: every persona in the account). (a) One real peek-mode (`mark_read=false`)
+fetch, checked healthy per §5 (so hive-off/404/unreachable correctly fails self-test); (b) a synthetic `new` through the real emit path (stdout: line
+written and flushed is ok; exec: spawn `--exec` with a fake `new`, child exit 0 within timeout is ok). Exit 0 iff
+both healthy and emit-ok; else non-zero. The fetch result is printed regardless. The probe is peek-mode, so it is
+read-state-neutral (DONE-WHEN #5 holds after self-test).
+
+### 7.3 State persistence (`--state-file PATH`, optional, recommended under a supervisor)
+- **Content (JSON):** `{"identity":<canonical-id>, "cursor":<int|null>, "state":"UP|DOWN",
+  "consecutive_failures":<int>}`, plus the optional pin fields written only when they are in force:
+  `emitted_above` (list of int), `gap_alerted` (int), `pin_forced` (true), `pin_evidence_intact` (false),
+  `state_corrupt` (true), `pin_release_at` (int).
+- **Every persisted field is read STRICTLY, and anything unrecognised fails CLOSED** (Loom re-audit 7, HIGH 2).
+  Booleans must be JSON booleans and integers must be real integers - a JSON `1` for `pin_forced` used to
+  normalise to `false` and silently UNPIN the watermark, letting the replay cap cross the very span the pin was
+  protecting; `pin_evidence_intact: 0` had the mirror bug. A malformed field is evidence the file cannot be
+  trusted, so it is treated as CORRUPT (below), never as a permissive default. `true` is not a message id.
+- **Canonical identity (`<canonical-id>`)** is computed before DNS resolution so trivial URL variations don't flip
+  it. From the effective inbox URL, it is the tuple `(scheme.lower(), host.lower(), effective_port, path,
+  sorted(query_params except the constant mark_read))`. Normalize by stripping a trailing `/` on path, filling the
+  scheme's default port, sorting query params, and lowercasing host. (So `?persona=river&mark_read=false` ≡
+  `?mark_read=false&persona=river`.) `persona` is encoded via the `persona=` query param already in the URL.
+- **Single-writer lock:** on startup, acquire an exclusive `fcntl.flock` on the state-file (LOCK_EX|LOCK_NB); if it's
+  held, exit non-zero ("state-file in use"), which prevents two watchers tearing the cursor backwards. Hold the lock fd
+  open for the whole process lifetime. flock is advisory and auto-released by the OS on process exit
+  (normal/SIGTERM/SIGKILL/crash), so there is no stale lockfile to clean (unlike a pidfile).
+- **Write:** after each poll, write atomically: `mkstemp` in the same dir, then write, `fsync`, `os.replace`;
+  best-effort remove of stale temps.
+- **Resume validity:** valid iff it parses as the schema (integer-or-null `cursor`, `state ∈ {UP,DOWN}`, integer
+  `consecutive_failures`) and `identity` matches the current canonical-id. On a valid match, resume per §7.0 (cursor
+  unless `--seed-at` overrides; FSM always). A present-but-unreadable path is a fatal config error.
+- **ABSENT and CORRUPT are different answers, and the difference is the whole point** (Loom re-audit 5 HIGH 2,
+  re-audit 6 HIGH 4). ⚠️ This supersedes the earlier "a parse/schema-invalid or empty file is treated as absent
+  (fall through)" contract, which was the exact fail-open it describes:
+  - **Absent** (no file) → first launch → baseline the cursor to the newest visible id.
+  - **Present but unusable** - unparseable, zero-byte/whitespace, valid-envelope-with-invalid-fields, or a
+    malformed pin field → **CORRUPT**. A file that EXISTS is evidence a cursor existed here, so baselining would
+    silently skip everything between that lost cursor and now. Instead the watcher arms **below** the visible
+    window (`cursor = min(visible) - 1`), re-emits that window, forces the pin, marks its evidence unusable, and
+    emits a `state_corrupt` diagnostic. Duplicates are recoverable; skips are not.
+  - **The corruption pin must be DISCHARGEABLE** (Loom re-audit 7, HIGH 5). Because it parks the watermark one
+    below the window it re-emits, the ordinary release test ("a complete window reaches back to at-or-below the
+    watermark") can never be met by that window - its floor is always `cursor+1`. So the pin records
+    `pin_release_at = min(visible)`, persisted with it, and releases when a complete window reaches that floor.
+    A fail-open repaired into a permanent fail-closed is not a repair: it re-emitted the same window on every
+    poll, forever, across restarts.
+- **Identity mismatch → re-baseline, EXCEPT a case-only difference, which MIGRATES** (Loom re-audit 7, HIGH 3).
+  A mismatch normally means a different source, so the cursor is not resumed (that would yield a silently-blind
+  watcher): log a loud warning, re-baseline the cursor as UNSET, start the FSM fresh (UP/0). But the state PATH
+  casefolds the persona while the identity keeps the directory's spelling, so one file written as `persona=Loom`
+  is reloaded by a run that discovered `loom` - and "mismatch" there destroys a live cursor and skips everything
+  since. When the stored identity differs ONLY by the case of a query VALUE (scheme, host, port, path and every
+  query KEY must match exactly), it is the same watched source spelled differently: resume it and rewrite the
+  identity on the next save. See §14.7 - this is a THIRD case layer, not a harmonisation of the other two.
+- **Without `--state-file`:** no lock and no persistence, so the FSM is per-process (a restart resets it), and two
+  no-state watchers for the same inbox would both emit `new` (duplicate delivery; they don't corrupt read-state since
+  both peek, but the harness is woken twice). Run a single instance, or use `--state-file` under a supervisor (which
+  both locks and persists). The external dead-man's-switch (`--heartbeat` to healthchecks.io / Dead Man's Snitch) is
+  then the cross-restart liveness guarantee, and DONE-WHEN #3's "no re-emit while down" scopes to a single process.
+
+## 8. Security (connection hardening + creds)
+
+- **No user-supplied URL to guard.** The destination is the fixed Kijito API host, so there is no SSRF surface from
+  config and no destination-class allow/deny machinery. Two hardenings remain as defense-in-depth: **(IP-pin)**
+  resolve the host once and pin the connection to that IP - no re-resolve at connect time, so no TOCTOU
+  (`_PinnedHTTPSConnection` connects to the pinned IP while verifying the cert against the real hostname via SNI);
+  **(no redirects)** redirects are never followed - a redirect is treated as an unhealthy poll, never chased.
+  Per-request timeout default is 5s. Stdlib: no-redirect via `HTTPRedirectHandler.redirect_request → None`; IP-pin via
+  a custom `HTTPConnection` through `do_open`; `urlopen(timeout=)`.
+- **Creds via env/file, never argv** (`$KIJITOMON_TOKEN` / `--token-file`; §5 for header and precedence).
+- ⚠️ **ON-DISK CONFIDENTIALITY: THE EVENT STREAM IS AS SENSITIVE AS THE TOKEN** (Loom re-audit 8 HIGH 1,
+  re-audit 9 HIGH 1/2). It contains message bodies unless `--no-content`. Attention naturally follows the
+  word "secret", so the token was 0600 from the start while the file full of plaintext was created with a
+  plain `open()` and inherited the umask - 0644 on any normal machine, verified live across 53 files.
+  The contract now:
+  - Event streams, their rotated archives, the state file and its lock sidecar are **exactly 0600**; every
+    directory this tool creates is 0700, at **every level** (`os.makedirs(mode=)` applies the mode to the
+    leaf only, so a nested path silently left its parents 0755).
+  - **Existing** artifacts are repaired on startup, not just newly created ones - the creation mode does
+    nothing for a file that already leaked, and those files are never recreated.
+  - ★ **The repair FAILS CLOSED, and this is the part that was wrong first.** The initial fix followed
+    symlinks, validated neither owner nor file type, and wrote the mail anyway when the chmod failed - so
+    it chmod'ed and appended to a link's *target*, and a *dangling* link caused it to create that target
+    elsewhere. **A passive disclosure had been turned into an active write primitive.** Opens now use
+    `O_NOFOLLOW` (the final component must not be a symlink) and `O_NONBLOCK` (a FIFO planted at the path
+    would otherwise block the writer forever - a hang, which is worse than a crash because nothing
+    reports it), then validate **on the fd we already hold** that it is a regular file owned by us at
+    0600. Anything else raises and the caller turns it into a **failed delivery**: the cursor holds, the
+    mail is retried, and nothing is written or diverted. "Best-effort so we do not crash" is the wrong
+    instinct for a file we are about to append private mail to.
+  - A directory anyone else can write is reported (sticky directories like `/tmp` excluded, since the
+    sticky bit is exactly what makes a shared writable directory safe).
+- **Opaque mode:** content is fetched over the authenticated channel; `--no-content` omits message bodies entirely,
+  and any future hosted bridge carries an opaque wake only.
+
+## 9. Signal strategy: the all-unread fast-path (implemented, server PR#66)
+
+- **Baseline:** the inbox-list poll (§5) is always the floor and the source of truth. The max-id cursor decides
+  what to emit, so the fast-path can never cause a missed or duplicate emit.
+- **Fast-path (cheap O(1) pre-check):** `GET /api/notify/pending` (SLASH path; the hyphen `/api/notify-pending`
+  404s), read-only, never marks read. Response `{"result":[{"persona","unread","unread_urgent"},...]}`; `unread` is
+  all read=false for that persona (a persona with 0 unread is absent, treat as 0). The watcher probes it once on
+  arm; if available it consumes `unread` for its persona and does the full inbox-list fetch only when `unread`
+  increases, saving the full-list diff on quiet polls. It auto-falls-back to baseline if the endpoint is absent or
+  non-2xx (a server without the field simply runs baseline).
+- **Safety floor (`--resync-every`, default 10):** the watcher never skips more than N consecutive polls; it
+  forces a full inbox poll regardless. So a stale / wrong / unsupported count can at worst add latency, never blind
+  the watcher. `unread` is only the wake trigger.
+- `--no-fast-path` forces baseline (always full-poll). Note: a self-sent message does not bump your own `unread`
+  (the server doesn't treat your own outgoing mail as unread-for-you), so the fast-path wakes you on incoming mail,
+  which is the intended liveness behaviour.
+
+## 10. Opaque-wake seam (build the hook, not the bridge)
+
+An internal "poll now" trigger besides the interval, wired to SIGUSR1 (POSIX only). Mandatory race-free mechanics:
+- **Install a no-op Python handler** `signal.signal(SIGUSR1, lambda *_: None)`. This is required, or the default
+  disposition terminates the process and `set_wakeup_fd` writes nothing.
+- **Self-pipe via a non-blocking `socketpair`** (more portable than `os.pipe` for `set_wakeup_fd`): set both ends
+  non-blocking, `signal.set_wakeup_fd(w)`; the main loop blocks in `select.select([r],[],[],timeout)`. A signal at
+  any instant either interrupts the in-progress `select` or leaves a byte that makes the next `select` return
+  immediately, so no wakeup is lost.
+- **Read-and-clear by draining the pipe** (`os.read(r, 4096)`) at the start of each poll (before fetch). Any
+  SIGUSR1 after that drain, even during the same poll's fetch/emit, leaves a byte guaranteeing a subsequent poll.
+  This gives "at most one extra poll per quiescent signal" with no signal lost once a poll has begun.
+- **One polling site on the main loop; the handler does no work**, so re-entrancy is structurally impossible.
+- v1 opens no remote listener. A later hosted bridge turns an opaque wake into a SIGUSR1/FIFO poke, then pull over
+  the authenticated channel (the client-side consumer in Kijito's notify-then-pull matrix). Windows: interval-only.
+
+## 11. CLI / config surface (v1)
+
+```
+kijito-inbox-monitor \
+  [--persona P]... [--personas A,B] [--all-personas] \  # default: every persona in the account
+  [--rediscover-every 600] \                          # all-persona mode: pick up new personas
+  [--poll-seconds 60] [--alert-after 3] \             # --alert-after min 1
+  [--emit stdout-jsonl|exec-per-event] [--exec 'CMD'] \ # --exec required iff emit=exec-per-event
+  [--content-chars 220 | --no-content] \
+  [--seed-at LAST_HANDLED_ID] [--max-replay 50] \
+  [--state-file PATH] [--heartbeat SECONDS] \
+  [--auth-header NAME] [--token-file PATH] \          # also $KIJITOMON_TOKEN (a token is required)
+  [--self-test]
+```
+**Arg matrix:** with no persona flag, every persona in the account is watched (`--all-personas` is the explicit
+spelling); `--persona`/`--personas` select an explicit subset. An explicit `--seed-at` overrides a state-file cursor
+(single-persona target only).
+**`--heartbeat SECONDS`:** emitted on the poll cycle (healthy or failed; it proves the watcher is alive) once at
+least SECONDS have elapsed since process start / last heartbeat; carries `cursor` (null before baseline); resolution
+is `--poll-seconds`.
+
+## 12. v1 scope & DONE-WHEN (binary)
+
+**In v1:** the generic core plus `http-poll` (Kijito reference, hard-baked shape) plus `stdout-jsonl` and
+`exec-per-event` plus the full §7 contract (cursor/FSM/self-test/state-file) plus §8 connection-hardening/creds plus
+the §10 SIGUSR1 self-pipe seam plus the §9 baseline poll and the all-unread fast-path (`/api/notify/pending`) with the
+`--resync-every` no-blindness safety floor.
+**Deferred (explicit, not dropped):** the generic parse-config (`list_path`/`id_field`/arbitrary `fields`) for
+non-Kijito REST shapes, the adapter zoo (file/IMAP/Slack/GitHub), native A2A/MCP, pip packaging, notification fan-out,
+the hosted wake bridge, and the final published name (§13). (The server all-unread count and its consumption are now
+done, see §9.)
+
+**DONE-WHEN (each independently verifiable):**
+1. `--self-test` exits 0 (one real peek-mode shape-valid fetch healthy and synthetic emit ok); exits non-zero
+   against an unreachable or hive-off source. Reachability is printed.
+2. (stdout-jsonl mode) Armed against the live inbox; after observing the `armed` event (cursor=C), send a test hive
+   message M, and the watcher emits exactly one `new` with `id=M.id` (M.id > C); no `new` is emitted for any message
+   with `id ≤ C`. (Framed as the cursor boundary, not wall-clock "pre-existing", so it's deterministic against a live
+   multi-writer inbox.)
+3. `--alert-after 3` with `--state-file`: force a source-down condition (e.g. a bad token / non-2xx response, or a
+   network-unreachable interval) for ≥3 consecutive polls, giving one `alert`; restore, giving one `recovered`; no
+   re-emit while down.
+4. **Restart-safe (cursor + dedup):** Stop the watcher at cursor=C (state-file written). Send message M (id>C) while
+   stopped. Relaunch with the same `--state-file` (or `--seed-at C`). Pass means M emitted exactly once and no message
+   ≤C re-emitted.
+5. **Peek-stable:** after a poll and after `--self-test`, an unread message's `read` field is unchanged. Verify by a
+   direct `GET /api/inbox?persona=P&mark_read=false` before and after (the target row's `read` stays the same).
+6. **Connection hardening:** a redirect response is refused (treated as an unhealthy poll, never chased); the
+   connection is pinned to the resolved IP with no re-resolve at connect time (no TOCTOU); the per-request timeout is
+   enforced.
+7. **Replay cap:** with `cursor` set below a backlog of more than `--max-replay` items, the first poll emits
+   `replay_capped` plus `armed` and zero `new`; with a backlog ≤ `--max-replay`, all replay as `new`.
+8. **Shape/empty:** empty `{"result":[]}` is healthy no-new; a non-2xx / non-JSON / shape-invalid body is a liveness
+   failure (counts toward alert), never a false "no mail."
+9. **State-file safety:** a state-file whose `identity` mismatches the current persona target does not resume its
+   cursor (it re-baselines with a warning); a second watcher on the same state-file exits non-zero (flock).
+10. Lives in `monitor/` as a single zero-dep stdlib file, committed and pushed (private GitHub
+    `KijitoAI/kijito-inbox-monitor`, 2026-06-20; stays private until the public-flip gate), with a README
+    documenting the supervision requirement plus `--state-file` (§7.3) and the CLI (§11). (v2: still one file; see §14
+    for the multi-persona DONE-WHEN that supersede the single-persona framing of #2/#4 above. They hold per-persona.)
+
+## 13. Naming: decided (2026-06-20; renamed 2026-06-24)
+
+**Name: Kijito Inbox Monitor** (package `kijito-inbox-monitor`; GitHub `KijitoAI/kijito-inbox-monitor`,
+matching the `Kijito`/`KijitoWeb` siblings). **Argus** is retained as the builder persona and internal codename, not
+the product name. The name describes the product (marketplace tagline: "the local liveness watcher for your Kijito
+inbox"), and it is collision-safe against the crowded "Argus" monitoring/observability namespace.
+
+> **Rename note (2026-06-24):** the original 2026-06-20 call was `Kijito Monitor` / `kijito-monitor`, justified
+> partly by "zero churn" since the deployed surface already encoded it. Before any external user existed, the choice
+> was made to do it right and rename to the more descriptive **Kijito Inbox Monitor**, accepting the one-time internal
+> churn (launchd label `com.kijito.inbox-monitor`, cache dir `~/.cache/kijito-inbox-monitor`, script
+> `kijito_inbox_monitor.py`, repo) as a coordinated migration rather than ship an under-described public name.
+> `KIJITOMON_*` env vars are unchanged.
+
+For the record: the names `mailwatch`/`mail-watcher`/`agent-watch`/`nudge` were taken or avoided; the Kijito-ward
+shortlist was `kijito-watch`/`kijito-inbox-watch`. Confirm `kijito-inbox-monitor` on PyPI/npm before any public
+package publish (verified free 2026-06-24).
+
+---
+
+## 14. v2: multi-persona hive watch + supervised producer (shipped + deployed, 2026-06-19/20)
+
+The deployed build watches your whole Kijito account from one process and is supervised by launchd. The §1 through §13
+single-persona contracts are unchanged and apply per persona; this section records what was added on top. (Origin:
+the multi-persona fold-in, folded into the canonical `monitor/` tree; per-persona event streams; the current arming
+recipe.)
+
+### 14.1 Multi-persona watch (one process, N inboxes)
+- **Default (no `--persona`/`--personas`):** watch every persona returned by `GET /api/personas`. A new
+  persona comes online with no new process or flag. `--all-personas` is the explicit spelling.
+- **Explicit subsets:** `--persona P` (repeatable) / `--personas A,B`.
+- **Per-persona isolation:** each watched persona has its own cursor, alert FSM, state-file, and flock, derived from
+  the `--state-file` base path as `hive.<persona>.json` (so `--state-file ~/.cache/kijito-inbox-monitor/hive.json`
+  yields `hive.argus.json`, `hive.river.json`, and so on). All §7.0/§7.1/§7.3 semantics hold independently per persona.
+- **Periodic rediscovery (`--rediscover-every`, default 600s):** in all-persona mode, re-scan `/api/personas` and add
+  newly-created personas without a restart. It is add-only; it never drops a persona mid-run. Explicit
+  `--persona`/`--personas` subsets stay fixed (no rediscovery).
+
+### 14.2 One signal fetch per tick, fanned out in-process
+The §9 fast-path generalizes cleanly to the whole account: one `GET /api/notify/pending` per tick returns the per-persona
+`{persona, unread, unread_urgent}` map; the watcher fans it out in-process to each persona's wake decision, and does not
+issue one request per watched persona. A persona's full inbox-list poll (§5) still fires only on arm, on its `unread`
+increase, on its `--resync-every` floor, or on fast-path fallback. The `--resync-every` no-blindness floor (§9)
+applies per persona.
+
+### 14.3 Owned, self-rotating EVENT sinks (the consume-your-own fix)
+Two emit-to-file modes for supervised runs (both write NDJSON the watcher owns and size-rotates in-process, with no
+`newsyslog`/`logrotate`/`sudo`, so there is no orphaned-fd silent-blinding; consumers `tail -F`):
+- **`--events-file PATH`**: one shared log. Correct for a single-target supervised watch.
+- **`--events-file-template PATH`**: one log per persona, e.g. `events.{persona}.ndjson` (one `RotatingFileSink` per
+  persona, created lazily, all closed on shutdown). The `{persona}` placeholder is required, and it is mutually
+  exclusive with `--events-file`. This is what the deployed hive producer runs.
+- **Rotation:** `--max-bytes` (default 5_000_000; `<=0` disables) keeping `--keep-logs` archives (default 5, min 1).
+- **`--suppress-author P`** (repeatable): drop `new` events authored by P, which kills the self-echo an all-persona
+  watcher gets for mail it sent (a dogfood finding). Liveness events (`alert`/`recovered`/`heartbeat`) are unaffected;
+  the cursor still advances (no re-emit).
+
+**Why per-persona event files (LLM-UX):** off a single shared log, a session can only get its own mail by inventing
+an undocumented consumer-side `grep "persona": "X"` filter, which is not discoverable and which each agent improvises
+differently. One file per persona makes "subscribe to only my own mail" a self-evident `tail -F
+events.<persona>.ndjson`: zero filtering, discoverable by filename.
+
+**Disambiguation (load-bearing):** `hive.<persona>.json` is internal state (cursor/FSM bookkeeping; do not tail);
+`events.<persona>.ndjson` is the event stream a session tails to consume its mail.
+
+**Migration trap:** the older single shared `events.ndjson` is retired. A consumer still tailing it goes silently
+blind (no writer appends). Repoint to `events.<persona>.ndjson`. (This was hit live during cutover; silence is not
+success.)
+
+### 14.4 Deployment: single supervised producer, many tailing consumers
+- **Producer:** one launchd user LaunchAgent `com.kijito.inbox-monitor` (`~/Library/LaunchAgents/`, RunAtLoad +
+  KeepAlive) runs the all-persona producer with `--events-file-template`. KeepAlive covers the `kill -9` /
+  process-death gap a bare file-tail can't see (kill-9-proven). stderr goes to `~/.cache/kijito-inbox-monitor/monitor.err`.
+- **Consumers:** each agent session is a consumer that tails only its own `events.<persona>.ndjson` into its harness's
+  wake mechanism. A session does not start its own watcher; a second producer would collide on the per-persona
+  state-file flock.
+- **Cutover discipline:** retire any existing detached producer first (the per-persona flocks permit one writer), then
+  `launchctl bootstrap` and `kickstart` the agent. Self-rotating event files mean consumers reattach across rotations
+  via `tail -F` (follow-by-name) with no gap.
+
+### 14.5 v2 DONE-WHEN (supersede the single-persona framing of §12 #2/#4; they hold per-persona)
+- **m1.** Bare arm (no flags) watches every `/api/personas` persona from one process; each gets its own
+  `hive.<persona>.json` (separate cursor/FSM/lock), with no shared `hive.json` and no replay flood on restart.
+- **m2.** Exactly one `/api/notify/pending` request per tick regardless of persona count (fanned out in-process).
+- **m3.** `--events-file-template` writes one `events.<persona>.ndjson` per persona; a session tailing its own file
+  receives only its own `new` events; rotation reopens in-process (the consumer reattaches via `tail -F`).
+- **m4.** `--all-personas` plus `--suppress-author P` drops `new` events authored by P; liveness events still flow.
+- **m5.** Supervised under `com.kijito.inbox-monitor` (RunAtLoad + KeepAlive): a `kill -9` of the producer is recovered
+  automatically; exactly one producer runs; per-persona cursors resume (no replay flood).
+
+### 14.6 Still open (not blocking; tracked elsewhere)
+- **Name decided** (Kijito Inbox Monitor, §13) and pushed private (`KijitoAI/kijito-inbox-monitor`, 2026-06-20).
+  ✔ **DONE, all three parts, verified 2026-07-29** - this item read as open long after it was finished, which is
+  its own lesson: a "still open" list is a claim like any other and nothing re-checks it. The repository is PUBLIC;
+  this spec is VENDORED into the repo and tracked at `docs/DESIGN.md`; and the README link is the in-repo relative
+  `docs/DESIGN.md`, which resolves on GitHub. An older copy of this spec also survives in the private workspace that
+  hosts this repo; it is a STALE rev, and the in-repo file is the only spec. Read the rev from a file's own header
+  rather than from any prose that claims one.
+- **Marketplace** surfacing, at launch-time.
+- **Codex-side consumer bridge:** Codex sessions aren't yet woken by their event file; the Claude harness Monitor
+  tool is the native consumer (done).
+
+
+### 14.7 The three case layers (they point different ways ON PURPOSE - do not "harmonise" them)
+
+Reading the source, the case rules look inconsistent and invite a tidy-up. They are not: they answer different
+questions about different systems. `CaseAsymmetryInvariantTest` is the defence, and it fails BOTH harmonisations.
+
+1. **PATH (`_state_safe_persona`) CASEFOLDS.** The local filesystem is case-INSENSITIVE (APFS, NTFS), so
+   `Claude-chat` and `claude-chat` name the SAME file. Not casefolding made the producer block on a flock it
+   already held, leaving that persona with no event stream at all - a silent wake gap.
+2. **SERVER NAMESPACE (`stranded_inboxes`) DOES NOT CASEFOLD.** The server's inbox namespace is case-SENSITIVE:
+   the `Claude-chat` inbox held a genuinely different message set from `claude-chat`. Casefolding here merges two
+   real inboxes and hides stranded mail - shipped that way for an hour, and it stopped detecting the very incident
+   it exists for.
+3. **STATE-FILE IDENTITY (`identity_migratable`) MIGRATES A CASE-ONLY DIFFERENCE** (Loom re-audit 7, HIGH 3). This
+   follows FROM layer 1 rather than contradicting layer 2: because the path already collapses the variants, ONE
+   state file can only ever describe ONE of them, so a casefold-equal identity in that file is the same watched
+   source spelled differently - a migration to accept and rewrite, not a different source to baseline over.
+   Deliberately narrow: only the query VALUE is compared case-insensitively; scheme, host, port, path and every
+   query KEY must match exactly, so nothing here invents case-insensitivity for a URL path.
+
+The variant inbox remains unwatchable locally (layer 1) AND unwatched remotely (layer 2), which is precisely why
+it is ALARMED on rather than adopted - while layer 3 keeps a live cursor from being destroyed by a spelling change.
+
+### 14.8 The safety-state register: what SETS it, what CLEARS it (Loom re-audit 10, the class sweep)
+
+Ten consecutive RED audit rounds shared one generator, named by loom after round 10:
+
+> **Safety repair checks are locally correct but their RESULT/LIFECYCLE is not propagated end-to-end; test
+> or recovery surfaces then preserve the old unsafe state or create permanent liveness loss.**
+
+It has exactly two halves, and they are the same bug facing opposite ways - one loses the ANSWER, the other
+loses the EXIT:
+
+* **WHO CONSUMES THIS?** A check that computes a correct verdict which nobody reads.
+* **WHAT CLEARS THIS?** A safety STATE that is set and never released.
+
+Rather than patch instances (which produced the next round's findings three times running), the whole file
+was swept. **Two rules now bind, and both are mechanically checkable:**
+
+1. **A call to a bool-returning safety helper may not appear as a bare statement** unless the comment at
+   that site says the verdict is deliberately ignored AND why. There is exactly ONE such site today:
+   `_repair_mode(archive)` in `RotatingFileSink._open`, because refusing to open the live events file
+   because a months-old ARCHIVE is unreadable would convert a stale-permission leak into a delivery outage.
+2. **Every safety flag has a release condition, written here.** "Nothing releases it" is an acceptable
+   answer only when it is the ANSWER (a property re-evaluated from scratch at process start), never when
+   it is an oversight.
+
+| state | set when | **cleared when** |
+|---|---|---|
+| `RotatingFileSink._pending` | bytes written, not yet fsynced | a successful `sync()` |
+| `RotatingFileSink._dir_pending` | a directory ENTRY was created/rotated | the directory fsync succeeds |
+| `RotatingFileSink._sync_failed` | an fsync we can never retry failed (fd rotated away) | reopen - a new fd makes it retryable |
+| `RotatingFileSink._broken` | reopen after rotation failed | the next `write()` reopens successfully |
+| `Emitter._broken_sinks[key]` | a persona sink could not be opened safely | `BROKEN_SINK_RETRY_S` elapses **and** the reopen succeeds |
+| `_WARNED_PERSONAS` entry | a per-persona warning was emitted once | `_clear_persona_warning()` on that persona's recovery |
+| `_REPORTED_STRANDED` | a stranded inbox was alarmed on | `intersection_update` drops it when it is no longer stranded |
+| `StateFile.unsafe` | `_repair_mode` could not prove the state file private | *nothing in-process, deliberately* - it is a property of the path on disk, re-derived at next start |
+| `WatchTarget.delivery_blocked` | an emit failed; the cursor is held | the next successful delivery |
+| `WatchTarget.state_not_durable` | a cursor write could not be proven durable | the next durable cursor write |
+| `WatchTarget.pin_forced` / `state_corrupt` | a pin was forced / state was corrupt on load | the pin discharges against `_pin_release_floor()` |
+| `WatchTarget.pin_evidence_intact` | *(false)* pin tracking overflowed or was corrupt | an authoritative read only - never by counting (invariant 3) |
+| `WatchTarget.emitted_above` | ids delivered above a pinned watermark | reassigned empty when the pin releases |
+
+**Invariant 2 restated, because it is what half B protects:** every pin must be DISCHARGEABLE. A permanent
+fail-closed is the same defect as a fail-open - it just fails in the direction that looks responsible.
+
+**⚠️ The class does NOT cover everything audit 10 found, and pretending otherwise is how the next round
+gets missed.** H1, H2 and M3 are instances of the two halves above. M4 (a repair loop whose RANGE came from
+CURRENT config, so a shrunk `keep` stranded `.7` at 0644 forever), M5 (a gate whose fall-through arm was the
+optimistic one, so a mutant that killed the interpreter scored as CAUGHT) and L6 (a harness leaking the temp
+trees and descriptors it opened) are three DIFFERENT shapes. Sweeping for loom's two halves alone would have
+left all three in place. The mechanical detectors that do reach them: a loop bound derived from live config
+rather than from the directory; an if/elif chain whose terminal `else` is the success arm; an `open()`/
+`mkdtemp()` whose handle or tree is never released.
+
+### 14.9 Which lifecycle events are GUARANTEED, and which are deliberately not (re-audit 11, F1)
+
+§14.8 required every safety VERDICT to have a consumer. Re-audit 11 found a third half of the class that
+neither of those questions reaches:
+
+> **(C) What did we WRITE DOWN as if the action had succeeded?** - a state committed as if an operation
+> succeeded, ordered before and independently of whether it did.
+
+Every alarm committed its "already alarmed" state BEFORE emitting and discarded the emit's answer, and
+three of the four had no second channel. So an alarm that was never delivered was never re-raised - not
+when the channel recovered, and not after a restart, because `gap_alerted` is persisted. **Mail was never
+at risk** (the cursor holds correctly throughout); the ALARMS vanished. That is worse than it sounds,
+because the headline promise is that a walk which cannot complete pins **loudly** rather than in silence.
+
+★ **The class as previously stated did not merely miss this - it CLEARED it.** Asked "who consumes
+`lifecycle()`'s answer?", the correct answer is "nobody, deliberately" (§14.7 / §170 below). A satisfying
+answer to the class's question sat directly on top of the defect.
+
+**THE RULE NOW, and it is a two-tier one:**
+
+| tier | events | contract |
+|---|---|---|
+| **GUARANTEED** | `alert`, `recovered` | emitted via `WatchTarget._alarm`, which RETURNS delivery. An undelivered one is written to **stderr** - never retried down the event channel, which is the thing that just failed. A **pure announcement latch** (`gap_alerted`) commits ONLY on delivery; a **behavioural** state (`fsm_state`, `pin_evidence_intact`) commits regardless, because refusing to record evidence loss would trade a lost alarm for a lost invariant. |
+| **INFORMATIONAL** | `armed`, `heartbeat`, `persona_added`, `seed_ahead`, `replay_capped`, `state_corrupt` | deliberately NOT acknowledged and NOT gated (§170 stands). They record something that already happened; nothing latches "we announced it", so a lost one costs a notification, not a fact. |
+
+`stranded-mail` is a third case: its unconditional `stderr` write happens BEFORE the event, so an
+undelivered alert is already on the record.
+
+⚠️ **"Do not gate the cursor on a lifecycle event" and "do not record that you alarmed when you did not"
+are DIFFERENT propositions, and only the first was ever documented.** §170 is unchanged and correct; it
+was never a licence for the second.
+
+★ AND THE IRONY THAT MAKES THIS WORTH REMEMBERING: this codebase gets acknowledge-before-deliver **exactly
+right for MAIL** - the cursor IS the acknowledgement, delivery stops at the first failure, the durability
+barrier retracts wholesale - and got it **exactly backwards for its own ALARMS**. The architecture knew the
+principle by name and did not apply it to itself.