kijito-tools 0.2.7 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-tools",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Installer for kijito-tools: copies the context-tracking, session catch-up, and self-clear scripts plus the Kijito skills into ~/.claude.",
   "license": "Apache-2.0",
   "type": "commonjs",

package/providers/monitor/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to kijito-inbox-monitor are documented in this file.
 The format is based on Keep a Changelog, and this project follows Semantic Versioning.
 
+## [0.5.9] - 2026-09-26
+
+### Fixed
+- **A short server restart no longer raises an `alert`/`recovered` pair** (the dead-man `alert` now needs a
+  MEASURED span, not only a failure count: `--alert-floor-seconds`, default `(--alert-after - 1) *
+  --poll-seconds` = 120 s; DESIGN.md §7.1 rev 10). In long-poll mode a failed poll is retried after 1/2/4 s,
+  so `--alert-after 3` was reached ~3-7 s into any outage: every routine server restart (a ~10-20 s window
+  of edge 502s) woke the consumer twice for no mail. `seconds` is now the measured span and `floor_seconds`
+  names the floor; the first-failure stamp (`down_since`) is persisted so a supervisor restart mid-outage
+  resumes the span. Plain interval polling is unchanged (the default floor is what N failed polls take at
+  the configured interval); `--alert-floor-seconds 0` restores the count-only edge.
+  In long-poll mode the row's `consecutive_failures` is usually well above `--alert-after` (retries keep
+  counting until the floor is reached). A `down_since` that is not a finite, positive number makes the state
+  file CORRUPT, like any other malformed field (including a huge integer literal, which would otherwise crash
+  the strict read itself).
+
+### Added
+- **A failed long-poll honours the server's retry hint.** When the server answers a long-poll with an error
+  that carries `Retry-After` (delta-seconds or HTTP-date) or a JSON `retry_after_seconds`, the next attempt
+  waits at least that long (rounded up, capped at 120 s) instead of retrying at 1/2/4 s into a restarting
+  server. The hint only paces retries; the alert decision is still the measured floor.
+
 ## [0.5.8] - 2026-09-26
 
 ### Fixed

package/providers/monitor/README.md

@@ -295,7 +295,7 @@ Each line of the events file (and each `exec-per-event` invocation) is one event
 |---------|---------|----------------------|
 | `armed` | emitted once per persona on the first healthy poll (baseline set) | `KIJITOMON_CURSOR` |
 | `new` | a new inbox message | `KIJITOMON_ID`, `KIJITOMON_FROM`, `KIJITOMON_CONTENT`, `KIJITOMON_CREATED`, `KIJITOMON_PERSONA` |
-| `alert` | the source has been unreachable for `--alert-after` polls (dead-man), **or** mail is stranded in an inbox nobody watches, **or** the server holds unread mail this window did not show (all below) | `KIJITOMON_REASON`, `KIJITOMON_FAILURES`, `KIJITOMON_STRANDED` |
+| `alert` | the source has been failing for `--alert-after` polls **and** for a measured `--alert-floor-seconds` (dead-man; `seconds` is the measured span), **or** mail is stranded in an inbox nobody watches, **or** the server holds unread mail this window did not show (all below) | `KIJITOMON_REASON`, `KIJITOMON_FAILURES`, `KIJITOMON_SECONDS`, `KIJITOMON_FLOOR_SECONDS`, `KIJITOMON_STRANDED` |
 | `recovered` | the source came back after an `alert` | `KIJITOMON_CURSOR` |
 | `still_unread` | mail already announced as `new` is still **unread** `--still-unread-after` seconds (default 2 h) after it was sent. One event per poll names every such message; each message is reminded at most once per window and at most `--still-unread-max` (default 3) times; never for retired, reserved or write_only inboxes; nothing on the first poll after a restart. Read what you have handled with `mark_read=true` and it stops. | `KIJITOMON_IDS`, `KIJITOMON_OLDEST_AGE`, `KIJITOMON_REASON` |
 | `heartbeat` | optional liveness tick (`--heartbeat N`) | `KIJITOMON_CURSOR` |
@@ -549,9 +549,10 @@ four sat above it. Only the newest page's count answers the question "is there u
 | `--state-file-template PATH` | Like `--state-file`, with `{persona}` filled in by the producer (the component `--safe-persona` prints). Use it in a supervisor unit so the unit never spells a persona into a path. |
 | `--token-file-template PATH` | Like `--token-file`, with `{persona}` filled in by the producer for the one `--persona` target. |
 | `--safe-persona NAME` | Print the filename component the producer uses for NAME, then exit. Anything that needs to name a persona's files should ask this rather than re-implement the rule. |
-| `--wait N` | Long-poll hold (s) requested from the server so new mail wakes the watcher near-instantly at ~the same request rate (default 50; `0` disables). Falls back to interval polling against a server that doesn't support it, and auto-upgrades when it does. |
-| `--poll-seconds N` | Interval between polls when long-poll is off/unsupported (default 60). |
+| `--wait N` | Long-poll hold (s) requested from the server so new mail wakes the watcher near-instantly at ~the same request rate (default 50; `0` disables). Falls back to interval polling against a server that doesn't support it, and auto-upgrades when it does. A failed long-poll waits at least as long as the server's `Retry-After` (or `retry_after_seconds`) asks, capped at 120 s. |
+| `--poll-seconds N` | Interval between polls when long-poll is off/unsupported (default 60). Also sets the default alert floor in every mode: `(--alert-after - 1) * --poll-seconds` (see `--alert-floor-seconds`). |
 | `--alert-after N` | Consecutive failures before an `alert` (default 3, min 1). A single transient failure is normal. |
+| `--alert-floor-seconds N` | Measured seconds the source must have been failing before the `alert` fires, in addition to the failure count (min 0). Default `(--alert-after - 1) * --poll-seconds` - what N consecutive failed polls take at the configured interval - so long-poll's fast retries (1/2/4 s after a failure) cannot alert on a 10-15 s restart. `0` restores the count-only edge. The alert's `seconds` is the measured span, never a nominal product of flags. |
 | `--heartbeat N` | Emit a `heartbeat` every N seconds (external dead-man's switch). |
 | `--content-chars N` / `--no-content` | Truncate (default 220) or omit message content. |
 | `--suppress-author P` | Don't emit `new` events authored by persona P (repeatable); drops self-echo when watching all personas. |

package/providers/monitor/UPSTREAM

@@ -1,26 +1,26 @@
 # The upstream release providers/monitor is a byte-exact copy of (row M314).
 # Written by scripts/import-monitor.sh; verified by tests/vendored_monitor_test.sh. Never hand-edit.
 repo=KijitoAI/kijito-inbox-monitor
-sha=e3c69db68451e3e55b5b3da9c98546706fff7bff
-tree=70a8b4dfc04c7832aec37cb9124178e75f7248c9
-tag=v0.5.8
+sha=685341bdffcffdec6f8d0c4ce849fd93d7185928
+tree=a6ca2adec2156c5f9c6a25786ea45a65d8572c09
+tag=v0.5.9
 file=100644 8d88ccb0fd09b9144505f985b4f882db278fac1f .github/workflows/publish-npm.yml
 file=100644 19ce3471a2cffa689be9d261049c1e74e3e7a25e .github/workflows/publish-pypi.yml
 file=100644 4534290a5dd36d18d07a782b784b6b0ad5ee38fc .gitignore
-file=100644 b5cd0382bcfa90cd71fa39577a41a47707ac2bac CHANGELOG.md
+file=100644 d4204200a9f90a7fdecc4c97711c94e063a3856e CHANGELOG.md
 file=100644 d645695673349e3947e8e5ae42332d0ac3164cd7 LICENSE
 file=100644 f6b0e5634f3fd4156c1c000efb31578bfb068cf3 NOTICE
-file=100644 73d2bf5a5d5d6cb622db014285cd9ada4c705724 README.md
+file=100644 e74216a2bd031dd876ca84c4bcf29b9246b2fe67 README.md
 file=100644 72f0c148f1e721ac1bb4a38e5cae690355774314 RELEASING.md
 file=100755 fca1203267cb726736b0c8f239e2d74c40a7a895 arm-hive-monitor.sh
 file=100755 bbe3f07de13dab8a8a7a4798481156ae4a46ab8f bin/cli.js
 file=100644 fffa8bd23749a321285bd942a3f4f4a98936129c com.kijito.inbox-monitor.plist.template
-file=100644 b0c07b55c75e6061e6c82d5e23c2b7ddad5131cf docs/DESIGN.md
+file=100644 0dd1e5227afa4572b2324fc5982431b7519f5cea docs/DESIGN.md
 file=100644 4f5e53a8633e60e6c57c451e28546f8af8783fe8 kijito-inbox-monitor@.service.template
-file=100644 692aadd5fe603556e0ba0e9358c1487022b2bc05 kijito_inbox_monitor.py
-file=100644 53538cfa0dd2a25f68d54b2a62fb072d599cec83 package.json
-file=100644 44b676233aecdc02dc462a4144dd29120ff05d73 pyproject.toml
+file=100644 957c2dff0b2afb08ef52fb35ebde42e6fb896414 kijito_inbox_monitor.py
+file=100644 805473fa67b7e4934f9a3100803478b9a1213060 package.json
+file=100644 bf4529771d5564b4a29a766c76724fcdf8a13f76 pyproject.toml
 file=100755 b34a5c775385ecfaefd4b374c1fc1aa082a85d14 scripts/migrate-systemd-unit.sh
-file=100755 22acef6d6875395a81c701eb535030d0a78b0df1 scripts/mutation-check.py
+file=100755 9caeb0c317ce53c1a6669d1cce7dd41ce8a6d912 scripts/mutation-check.py
 file=100755 acba6196213736922fc4f7135749386d85d172a6 scripts/prepublish-gate.sh
-file=100644 affc54d7cf969631c3f2d9160995e933cde17a60 test_kijito_monitor.py
+file=100644 6a483356f839292caa207a4be418437b7b38b8ac test_kijito_monitor.py

package/providers/monitor/docs/DESIGN.md

@@ -1,6 +1,10 @@
 # Kijito Inbox Monitor: Design & Implementation Spec
 
-**Updated:** 2026-08-15 (rev 9: §6.5 Darwin `boottime` re-sourced from `CLOCK_MONOTONIC_RAW` - Darwin's
+**Updated:** 2026-09-26 (rev 10: §7.1 the dead-man edge needs a MEASURED span, not only a failure count -
+`--alert-floor-seconds`, default `(alert_after - 1) * poll_seconds`; `seconds` on the `alert` is now that
+measurement and `floor_seconds` names the floor; a failed poll's `Retry-After` paces the next retry. Before
+this, the count-only edge fired ~3-7 s into any short server restart, and `seconds` read a nominal 90.)
+Rev 9 (2026-08-15: §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
@@ -293,7 +297,7 @@ One object per line; every event carries `event`, `source`, `ts` (emit-time UTC
 ```
 {"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":"alert",       "source":"kijito-inbox","ts":"<iso>","reason":"unreachable","consecutive_failures":3,"seconds":121,"floor_seconds":120}
 {"event":"recovered",   "source":"kijito-inbox","ts":"<iso>","cursor":250}
 {"event":"still_unread","source":"kijito-inbox","ts":"<iso>","ids":[240,246],"senders":["river"],"oldest_age_seconds":9000,"after_seconds":7200,"reason":"..."}   # M229 backstop, bounded
 {"event":"heartbeat",   "source":"kijito-inbox","ts":"<iso>","cursor":250}     # only if --heartbeat; cursor may be null
@@ -301,12 +305,14 @@ One object per line; every event carries `event`, `source`, `ts` (emit-time UTC
 {"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.
+  with no marker; or it is omitted with `--no-content`. `seconds` in the reachability `alert` is the **measured**
+  monotonic span from the first failure of the run to the failure that crossed the edge (rev 10; it used to be the
+  nominal `consecutive_failures * poll_seconds`, routinely an order of magnitude off - `seconds:90` against an 11 s
+  outage). `floor_seconds` is the floor the run had to reach (§7.1). `ts - seconds` is a LOWER bound on how long the
+  source had been failing not the onset: the stamp is taken when the first failing
+  fetch RETURNS, so detection lag (a blackholed `--wait` hold plus its socket timeout, or a plain-poll interval)
+  precedes it; and after a supervisor restart the span resumes from the persisted stamp, so it can include time
+  nobody was observing (a forward wall-clock step at boot lengthens it; a backward one is clamped to zero).
 - **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
@@ -576,12 +582,30 @@ 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`.)
+- **Failure:** on the first failure of a run stamp `down_since` (monotonic + wall clock); `consecutive_failures += 1`;
+  the UP-to-DOWN edge is crossed on the first failure at which BOTH `consecutive_failures >= --alert-after` AND the
+  measured span since `down_since` `>= floor` hold while state is UP, where `floor = --alert-floor-seconds` if given,
+  else `(--alert-after - 1) * --poll-seconds` (rev 10). Then set DOWN and emit one `alert` carrying the measured
+  `seconds` and `floor_seconds`. (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`.) WHY A FLOOR: in long-poll mode a failed poll is retried
+  after 1/2/4 s, so the count alone was reached ~3 s into any outage and every planned restart alerted (measured
+  on 11-20 s server restarts); the default floor is exactly what N failed polls take at the
+  configured interval, so plain interval polling keeps alerting on the N-th failure. A run under the floor emits
+  neither edge. `down_since` (wall) is persisted with `consecutive_failures` (§7.3) so a supervisor restart
+  mid-outage resumes the span rather than restarting the floor; an older file without it measures from the restart.
 - `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.
+  bouncing in ~1-2s). SIGUSR1-triggered polls count toward `consecutive_failures` like any other; they do not
+  advance the measured span, so triggered polls alone cannot cross the floor - the floor is time, by design.
+  In long-poll mode `consecutive_failures` on the row is therefore usually well above `--alert-after` (the
+  1/2/4/8/16/30 s retries keep counting until the floor is reached); the count says how many retries were made,
+  the floor says when the edge was allowed.
+- **Server retry hint (rev 10).** A failed long-poll that carries the server's own hint - a `Retry-After` header
+  (delta-seconds or HTTP-date) or a JSON `retry_after_seconds` field, header first - waits AT LEAST that long
+  before the next attempt (rounded up, clamped to 0..120 s; the exponential 1/2/4/8/16/30 s backoff still
+  applies when it is longer). The hint only paces retries; it never touches the alert decision, which stays
+  the measured floor above. A later failure with no hint clears it, so a stale hint cannot pace an unrelated
+  failure.
 
 ### 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`)
@@ -601,11 +625,18 @@ read-state-neutral (DONE-WHEN #5 holds after self-test).
   `/api/notify/pending` read succeeded (a persona missing from a good response is a real 0 - the server omits
   personas with nothing pending); a poll without that read writes no `unread`, so its absence means UNKNOWN,
   never zero. A reader should also judge freshness from the file's mtime: the file is rewritten every poll.
+  `down_since` (number: wall-clock epoch of the first failure of the current run, written only while
+  `consecutive_failures > 0`; §7.1 rev 10).
 - **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.
+  `down_since` is the one float: it must be a finite, positive number (JSON's `-Infinity`/`NaN`/`1e400` all
+  parse, a 400-digit integer literal makes `math.isfinite` itself raise, and an infinite span would raise at the
+  alert edge - a crash loop fed by the file the supervisor re-reads; so the value is normalised through `float()`
+  with overflow caught, then checked). A bool, string, zero, negative or non-finite value makes the WHOLE file
+  CORRUPT (cursor discarded, pin forced), the same consequence as any other malformed field.
 - **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

package/providers/monitor/kijito_inbox_monitor.py

@@ -11,10 +11,12 @@ Authentication is required: set $KIJITOMON_TOKEN (or --token-file) to your Kijit
 """
 import argparse
 import datetime
+import email.utils
 import errno
 import hashlib
 import http.client
 import json
+import math
 import os
 import select
 import signal
@@ -33,7 +35,7 @@ try:
 except ImportError:  # pragma: no cover - Windows
     fcntl = None
 
-__version__ = "0.5.8"
+__version__ = "0.5.9"
 SOURCE = "kijito-inbox"
 # A named User-Agent is REQUIRED: api.kijito.ai is fronted by a WAF that 403s the default Python-urllib UA.
 USER_AGENT = "kijito-inbox-monitor/%s" % __version__
@@ -45,6 +47,7 @@ EXEC_TIMEOUT = 10
 HTTP_TIMEOUT = 5  # per-request timeout default (normal fetches)
 LONGPOLL_SLACK = 10  # client socket timeout = server hold (--wait) + this, so a half-open hold is always detected
 LONGPOLL_BACKOFF_CAP = 30  # cap (s) on exponential backoff between failed long-poll attempts
+RETRY_AFTER_CAP = 120  # cap (s) on a server-stated Retry-After; a larger hint is clamped, never obeyed blindly
 PIN_TRACKING_CAP = 5000    # max delivered ids remembered above a pinned watermark (bounds the state file)
 WALK_BACK_MAX_PAGES = 50   # page budget for an authoritative backward walk over an omitted span
 BROKEN_SINK_RETRY_S = 30   # cooldown before re-trying a persona sink we refused; the refusal's RELEASE
@@ -494,6 +497,59 @@ def fetch_unread_counts(opener, count_url, headers):
     return (True, counts)
 
 
+def next_longpoll_backoff(previous, hint):
+    """Seconds to wait before retrying a FAILED long-poll: exponential from 1 s, capped at
+    LONGPOLL_BACKOFF_CAP, and never shorter than the server's own Retry-After hint (already clamped)."""
+    backoff = min((previous * 2) or 1, LONGPOLL_BACKOFF_CAP)
+    if hint is not None:
+        backoff = max(backoff, hint)
+    return backoff
+
+
+# The retry hint of the LAST fetch_unread_counts_longpoll call: seconds (int) the server asked us to wait, or
+# None. A side channel rather than a fourth return value so the function's contract (and every caller and
+# test double of it) is unchanged; the main loop resets it before each call and reads it on failure.
+_RETRY_HINT = {"seconds": None}
+
+
+def _retry_after_seconds(headers, body=None):
+    """The server's own retry hint on a FAILED response, in whole seconds, or None when it gave none.
+
+    Two carriers, header first: `Retry-After` (delta-seconds, or an HTTP-date) and a JSON body field
+    `retry_after_seconds` (the edge's restart page carries both). A hint only ever LENGTHENS the wait
+    before the next retry - it is pacing, never a reason to alert - and it is clamped to
+    [0, RETRY_AFTER_CAP] so a hostile or mistaken value cannot park the producer.
+    """
+    secs = None
+    raw = None
+    try:
+        raw = headers.get("Retry-After") if headers is not None else None
+    except Exception:
+        raw = None
+    if isinstance(raw, str) and raw.strip():
+        raw = raw.strip()
+        if raw.isdigit():
+            secs = int(raw)
+        else:
+            try:
+                when = email.utils.parsedate_to_datetime(raw)
+                now = datetime.datetime.now(datetime.timezone.utc)
+                secs = int(math.ceil((when - now).total_seconds()))
+            except (TypeError, ValueError, IndexError, OverflowError):
+                secs = None
+    if secs is None and body:
+        try:
+            data = json.loads(body)
+        except (ValueError, UnicodeDecodeError, RecursionError):
+            data = None
+        v = data.get("retry_after_seconds") if isinstance(data, dict) else None
+        if isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v):
+            secs = int(math.ceil(v))
+    if secs is None:
+        return None
+    return max(0, min(secs, RETRY_AFTER_CAP))
+
+
 def fetch_unread_counts_longpoll(opener, headers, wait, cursor):
     """Long-poll variant of the fast-path. GET /api/notify/pending?wait=<sec>[&cursor=<opaque>].
 
@@ -512,11 +568,22 @@ def fetch_unread_counts_longpoll(opener, headers, wait, cursor):
         q["cursor"] = cursor
     url = NOTIFY_PENDING_URL + "?" + urllib.parse.urlencode(q)
     req = urllib.request.Request(url, headers=headers, method="GET")
+    _RETRY_HINT["seconds"] = None
     try:
         with opener.open(req, timeout=wait + LONGPOLL_SLACK) as resp:
             if not (200 <= resp.status < 300):
+                _RETRY_HINT["seconds"] = _retry_after_seconds(getattr(resp, "headers", None))
                 return (False, {}, cursor)
             data = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        # A 502/503 during a server restart. Read the edge's own "retry in N s" so the next attempt is
+        # paced by it; a bounded read, because this body is an error page, not data.
+        try:
+            body = e.read(4096)
+        except Exception:
+            body = None
+        _RETRY_HINT["seconds"] = _retry_after_seconds(e.headers, body)
+        return (False, {}, cursor)
     except Exception:
         return (False, {}, cursor)  # keep the old cursor → next attempt resumes losslessly
     counts = _parse_unread_rows(data)
@@ -1182,6 +1249,7 @@ class Emitter:
                 "created": "KIJITOMON_CREATED", "cursor": "KIJITOMON_CURSOR",
                 "persona": "KIJITOMON_PERSONA",
                 "reason": "KIJITOMON_REASON", "consecutive_failures": "KIJITOMON_FAILURES",
+                 "seconds": "KIJITOMON_SECONDS", "floor_seconds": "KIJITOMON_FLOOR_SECONDS",
                 "seeded": "KIJITOMON_SEEDED", "current_max": "KIJITOMON_CURRENT_MAX",
                 "capped_to": "KIJITOMON_CAPPED_TO", "dropped": "KIJITOMON_DROPPED",
                 "stranded_inboxes": "KIJITOMON_STRANDED",
@@ -1619,6 +1687,29 @@ class StateFile:
             sys.stderr.write("kijito-inbox-monitor: WARNING state-file 'pin_release_at' is not an integer (%r); "
                              "refusing to interpret it: %s\n" % (release_at, self.path))
             release_at, strict_ok = None, False
+        # §7.1 wall-clock stamp of the first failure of a DOWN run. Absent in older files. Read strictly:
+        # a bool is not a timestamp (the same `1`/`true` confusion as the pin flags above).
+        down_since = d.get("down_since", _MISSING)
+        if down_since is _MISSING or down_since is None:
+            down_since = None
+        else:
+            # json.loads accepts `-Infinity`/`NaN`, turns 1e400 into inf, and hands back a Python int for a
+            # 400-digit literal - on which math.isfinite ITSELF raises OverflowError. Any of those escaping
+            # load() is a traceback at startup or at the alert edge; under a supervisor that is a crash loop
+            # fed by the file it re-reads on every restart. So: normalise through float() with the overflow
+            # caught, then require finite and positive. A stamp is a finite positive epoch or it is nothing.
+            fv = None
+            if isinstance(down_since, (int, float)) and not isinstance(down_since, bool):
+                try:
+                    fv = float(down_since)
+                except OverflowError:
+                    fv = None
+            if fv is not None and math.isfinite(fv) and fv > 0:
+                down_since = fv
+            else:
+                sys.stderr.write("kijito-inbox-monitor: WARNING state-file 'down_since' is not a finite positive "
+                                 "number (%r); refusing to interpret it: %s\n" % (down_since, self.path))
+                down_since, strict_ok = None, False
         raw = d.get("emitted_above")
         if raw is None:
             emitted, intact = set(), True          # no pin was in force; the ordinary case
@@ -1671,7 +1762,8 @@ class StateFile:
         return {"cursor": cursor, "state": state, "failures": failures, "emitted_above": emitted,
                 "gap_alerted": alerted, "pin_evidence_intact": intact,
                 "pin_forced": pin_forced, "pin_release_at": release_at,
-                "state_corrupt": state_corrupt, "unread_hidden": hidden, "unread": unread}
+                "state_corrupt": state_corrupt, "unread_hidden": hidden, "unread": unread,
+                "down_since": down_since}
 
     def unlock(self):
         """Release the single-writer flock and close the sidecar fd.
@@ -1688,7 +1780,7 @@ class StateFile:
 
     def save(self, cursor, state, failures, emitted_above=None, gap_alerted=None,
              pin_forced=False, pin_evidence_intact=True, state_corrupt=False, pin_release_at=None,
-             unread_hidden=False, unread=None):
+             unread_hidden=False, unread=None, down_since=None):
         """Persist the cursor. Returns True IFF the write is DURABLE (Loom re-audit 8, HIGH 3).
 
         The directory fsync used to be called and its answer thrown away, so a failure returned success
@@ -1729,6 +1821,10 @@ class StateFile:
         # Omitted when this poll had no count, so its absence means "unknown", never "zero".
         if unread is not None:
             d["unread"] = unread
+        # §7.1 the wall-clock stamp of the first failure of the current DOWN run, so a supervisor restart
+        # mid-outage resumes the measured span instead of restarting the floor from zero.
+        if down_since is not None:
+            d["down_since"] = down_since
         dirn = os.path.dirname(os.path.abspath(self.path)) or "."
         # BOTH OF THESE ARE INSIDE THE GUARD, and they did not used to be (drill, 2026-08-05).
         # This function builds a careful "written but not provably durable" path - _fsync_dir fails ->
@@ -1826,6 +1922,20 @@ class WakeSeam:
             pass
 
 
+def alert_floor_seconds(args):
+    """§7.1 the MEASURED span a failing run must reach before the dead-man `alert` fires.
+
+    `--alert-floor-seconds` when given; otherwise `(--alert-after - 1) * --poll-seconds`, which is exactly
+    how long `--alert-after` consecutive failed polls take at the configured interval - so plain interval
+    polling still alerts on the N-th failure, while long-poll mode (which retries after 1/2/4 s on a
+    failure) can no longer reach the edge in ~3 s. Before this, the count-only edge fired on every
+    routine server restart, 11 s windows included.
+    """
+    if args.alert_floor_seconds is not None:
+        return args.alert_floor_seconds
+    return (args.alert_after - 1) * args.poll_seconds
+
+
 def _monotonic():
     import time as _t
     return _t.monotonic()
@@ -2024,6 +2134,7 @@ class WatchTarget:
         self.cursor = None
         self.fsm_state = "UP"
         self.failures = 0
+        self.down_since = None   # (monotonic, wall) of the FIRST failure of the current run; None while healthy
         self.armed = False
         self.fast_path = False
         self.last_unread = None
@@ -2082,6 +2193,15 @@ class WatchTarget:
                 elif loaded is not None:
                     self.cursor = loaded["cursor"]
                     self.fsm_state, self.failures = loaded["state"], loaded["failures"]
+                    # §7.1 the measured floor survives a restart mid-outage: the persisted wall-clock stamp of
+                    # the first failure supplies the span already elapsed. Absent (a file written by an older
+                    # version) the run is measured from now - the conservative direction (later alert, never
+                    # a spurious one).
+                    self.down_since = None
+                    if self.failures:
+                        wall = loaded.get("down_since")
+                        elapsed = max(0.0, time.time() - wall) if wall is not None else 0.0
+                        self.down_since = (_monotonic() - elapsed, wall if wall is not None else time.time())
                     self.emitted_above = loaded["emitted_above"]
                     self.gap_alerted = loaded["gap_alerted"]
                     self.pin_evidence_intact = loaded["pin_evidence_intact"]
@@ -2469,6 +2589,7 @@ class WatchTarget:
                 self.fsm_state = "UP"
                 self._alarm("recovered", "source recovered", cursor=self.cursor)
             self.failures = 0
+            self.down_since = None
         else:
             self.skips = 0
             poll = fetch(self.opener, self.url, self.headers)
@@ -2484,6 +2605,7 @@ class WatchTarget:
                     self.fsm_state = "UP"
                     recovered = True
                 self.failures = 0
+                self.down_since = None
 
                 items = poll.items
                 # §5.4 Record who AUTHORED what, from the window we already have. Done before any cursor
@@ -2847,21 +2969,30 @@ class WatchTarget:
                                         pinned=True, evidence_lost=True)
 
             else:
+                if self.failures == 0 or self.down_since is None:
+                    # First failure of this run: stamp it. Everything the floor measures starts here.
+                    self.down_since = (_monotonic(), time.time())
                 self.failures += 1
-                if self.failures == args.alert_after and self.fsm_state == "UP":
+                span = _monotonic() - self.down_since[0]
+                floor = alert_floor_seconds(args)
+                if self.failures >= args.alert_after and span >= floor and self.fsm_state == "UP":
                     # THE DEAD-MAN'S SWITCH. The FSM transition MUST commit (it drives the whole
-                    # liveness model, and the firing condition is an EQUALITY on `failures`, so a
-                    # reverted transition would never re-fire - the edge is crossed exactly once).
-                    # So the state commits and the ANNOUNCEMENT gets the guaranteed second channel
-                    # (re-audit 11, F1/A1). Before this, a broken sink meant the source could go down
-                    # and NOTHING was ever emitted or logged - the one event README sells as the
-                    # dead-man's switch, silently absent.
+                    # liveness model; the `fsm_state == "UP"` guard is what makes the edge cross exactly
+                    # once, so a reverted transition would never re-fire). So the state commits and the
+                    # ANNOUNCEMENT gets the guaranteed second channel (re-audit 11, F1/A1). Before this,
+                    # a broken sink meant the source could go down and NOTHING was ever emitted or
+                    # logged - the one event README sells as the dead-man's switch, silently absent.
+                    # §7.1 the edge needs BOTH the count and the MEASURED span (`>=`, not `==`: in
+                    # long-poll mode the count is reached in ~3 s and the floor is what waits). `seconds`
+                    # is now that measured span - it used to be the nominal failures * poll_seconds and
+                    # read 90 against outages of 11 s.
                     self.fsm_state = "DOWN"
                     down_reason = poll.reason or "unreachable"
                     self._alarm("alert", "source is DOWN: %s" % down_reason,
                                 reason=down_reason,
                                 consecutive_failures=self.failures,
-                                seconds=self.failures * args.poll_seconds)
+                                seconds=int(round(span)),
+                                floor_seconds=int(floor))
 
         if self.state_file is not None:
             durable = self.state_file.save(self.cursor, self.fsm_state, self.failures,
@@ -2871,7 +3002,8 @@ class WatchTarget:
                                  state_corrupt=self.state_corrupt,
                                  pin_release_at=self.pin_release_at,
                                  unread_hidden=self.unread_hidden,
-                                 unread=self.observed_unread)
+                                 unread=self.observed_unread,
+                                 down_since=(self.down_since[1] if self.down_since else None))
             # ★ CONSUME THE ANSWER (Loom re-audit 9, MEDIUM). Round 8 taught me to RETURN a durability
             # status; this is the same defect one layer out - I produced an answer and then discarded it
             # at the call site, which is the exact thing the previous round was about. A cursor whose
@@ -3639,6 +3771,7 @@ def run(args):
         count_target = next((t for t in targets if t.unread_persona), None)
         if count_target is not None and not args.no_fast_path:
             if args.wait > 0:
+                _RETRY_HINT["seconds"] = None
                 counts_available, unread_counts, new_cursor = fetch_unread_counts_longpoll(
                     count_target.opener, headers, args.wait, cursor)
                 if counts_available:
@@ -3650,7 +3783,7 @@ def run(args):
                 else:
                     # drop / blip / outage: back off, resume the SAME cursor next time (lossless), and this tick
                     # falls through to per-target full inbox polls (the by-message-id correctness backstop).
-                    lp_backoff = min((lp_backoff * 2) or 1, LONGPOLL_BACKOFF_CAP)
+                    lp_backoff = next_longpoll_backoff(lp_backoff, _RETRY_HINT["seconds"])
             else:
                 counts_available, unread_counts = fetch_unread_counts(
                     count_target.opener, count_target.count_url, headers)
@@ -3724,6 +3857,11 @@ def build_parser():
                         "Clean shutdown during a held poll can take up to --wait seconds (a supervisor's SIGKILL "
                         "mid-hold is safe - state is persisted every cycle).")
     p.add_argument("--alert-after", type=int, default=3, help="Consecutive failures before an alert (min 1).")
+    p.add_argument("--alert-floor-seconds", type=int, default=None,
+                   help="Measured seconds the source must have been failing before an `alert` fires, in addition "
+                        "to --alert-after failures (min 0). Default: (--alert-after - 1) * --poll-seconds - what "
+                        "N consecutive failed polls take at the configured interval - so long-poll's fast retries "
+                        "cannot alert on an 11 s restart. 0 restores the count-only edge.")
     p.add_argument("--emit", choices=("stdout-jsonl", "exec-per-event"), default="stdout-jsonl")
     p.add_argument("--exec", help="Command to run per event (required iff --emit exec-per-event).")
     p.add_argument("--suppress-author", action="append",
@@ -3803,6 +3941,8 @@ def build_parser():
 def validate_args(args):
     if args.alert_after < 1:
         raise FatalConfig("--alert-after must be >= 1")
+    if args.alert_floor_seconds is not None and args.alert_floor_seconds < 0:
+        raise FatalConfig("--alert-floor-seconds must be >= 0")
     if args.resync_every < 1:
         raise FatalConfig("--resync-every must be >= 1")
     if args.rediscover_every < 1:

package/providers/monitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kijito-inbox-monitor",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "Pointer to the Python package kijito-inbox-monitor. A zero-dependency watcher that wakes a running agent when new Kijito inbox mail arrives. Install the real tool with pipx/uv/pip.",
   "license": "Apache-2.0",
   "type": "commonjs",

package/providers/monitor/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kijito-inbox-monitor"
-version = "0.5.8"
+version = "0.5.9"
 description = "Zero-dependency watcher that wakes a running agent when new Kijito inbox mail arrives."
 readme = "README.md"
 requires-python = ">=3.9"

package/providers/monitor/scripts/mutation-check.py

@@ -281,7 +281,8 @@ M=[
   '                    self._alarm("alert", "source is DOWN: %s" % down_reason,\n'
   '                                reason=down_reason,\n'
   '                                consecutive_failures=self.failures,\n'
-  '                                seconds=self.failures * args.poll_seconds)',
+  '                                seconds=int(round(span)),\n'
+  '                                floor_seconds=int(floor))',
   '                    pass'),
  ("L11-F1: the DOWN alert loses its stderr fallback (undelivered == silent again)",
   '            sys.stderr.write("kijito-inbox-monitor: %s EVENT UNDELIVERED (persona %r): %s\\n"\n'
@@ -332,6 +333,27 @@ M=[
  ("A1: the urgent-unanswered alarm is re-coupled to --no-stranded-alerts (one flag silences both again)",
   "        if counts_available and not args.no_urgent_alerts:",
   "        if counts_available and not args.no_stranded_alerts:"),
+ # Row M375 (bug #19): a ~20 s server restart woke consumers twice (alert + recovered) because the
+ # dead-man edge was a failure COUNT reached in ~7 s of long-poll retries. The floor and the retry hint
+ # are the fix; each mutant below removes exactly one piece of it.
+ ("M375a: the default alert floor is zero again (count-only edge: a 20 s restart alerts)",
+  "    return (args.alert_after - 1) * args.poll_seconds",
+  "    return 0"),
+ ("M375b: the fast-path recovery announces `recovered` after a run that never alerted",
+  "            # count endpoint reachable + no unread increase = a HEALTHY poll with no new items\n            if self.fsm_state == \"DOWN\":",
+  "            # count endpoint reachable + no unread increase = a HEALTHY poll with no new items\n            if self.fsm_state == \"DOWN\" or self.failures:"),
+ ("M375c: a 502's Retry-After is read and thrown away",
+  "        _RETRY_HINT[\"seconds\"] = _retry_after_seconds(e.headers, body)",
+  "        pass"),
+ ("M375d: the backoff ignores the server's retry hint",
+  "        backoff = max(backoff, hint)",
+  "        pass"),
+ ("M375e: the retry hint is not clamped (a hostile Retry-After parks the producer)",
+  "    return max(0, min(secs, RETRY_AFTER_CAP))",
+  "    return max(0, secs)"),
+ ("M375f: a stale retry hint survives into the next, unrelated failure",
+  "    req = urllib.request.Request(url, headers=headers, method=\"GET\")\n    _RETRY_HINT[\"seconds\"] = None\n",
+  "    req = urllib.request.Request(url, headers=headers, method=\"GET\")\n"),
 ]
 def run(src):
     # RELEASE WHAT WE ACQUIRE (Loom re-audit 10, L6). The temp tree was never removed and the source file
@@ -340,7 +362,12 @@ def run(src):
     # both is not merely untidy - it is the harness exhibiting the class it is meant to detect.
     d=tempfile.mkdtemp()
     try:
-        shutil.copy(TESTS, os.path.join(d,"test_kijito_monitor.py"))
+        # COPY THE WHOLE TREE, not two files. The suite also reads the README and the supervisor templates
+        # (the state-file-name and opaque-output agreement tests), so a two-file copy made the BASELINE red
+        # and the gate refused to run at all - a harness that cannot run proves nothing, green or red.
+        shutil.copytree(os.path.dirname(SRC), os.path.join(d, "t"),
+                        ignore=shutil.ignore_patterns(".git", "__pycache__", "node_modules", ".venv"))
+        d=os.path.join(d, "t")
         with open(os.path.join(d,"kijito_inbox_monitor.py"),"w") as fh:
             fh.write(src)
         # PIN THE WARNING FILTER. Inherited PYTHONWARNINGS=error turns a mutant's leaked fd into an ERROR,
@@ -356,7 +383,7 @@ def run(src):
             return None, "HUNG"
         return p.returncode, p.stderr
     finally:
-        shutil.rmtree(d, ignore_errors=True)
+        shutil.rmtree(os.path.dirname(d) if d.endswith(os.sep + "t") else d, ignore_errors=True)
 with open(SRC) as fh: base=fh.read()
 rc,_=run(base)
 if rc!=0: print("BASELINE NOT GREEN"); sys.exit(1)

package/providers/monitor/test_kijito_monitor.py

@@ -1,3 +1,6 @@
+import datetime
+import email.message
+import email.utils
 import io
 import json
 import os
@@ -277,6 +280,11 @@ class ValidationGuardTest(unittest.TestCase):
         with self.assertRaises(km.FatalConfig):
             km.validate_args(self._args(["--persona", "argus", "--poll-seconds", "0"]))
 
+    def test_alert_floor_seconds_must_not_be_negative(self):
+        with self.assertRaises(km.FatalConfig):
+            km.validate_args(self._args(["--persona", "argus", "--alert-floor-seconds", "-1"]))
+        km.validate_args(self._args(["--persona", "argus", "--alert-floor-seconds", "0"]))  # must not raise
+
     def test_seed_at_rejected_in_multipersona(self):
         with self.assertRaises(km.FatalConfig):
             km.validate_args(self._args(["--all-personas", "--seed-at", "5"]))
@@ -1718,6 +1726,7 @@ class BoundedWindowEndToEndTest(unittest.TestCase):
         all_personas = False
         state_file_template = None
         alert_after = 3
+        alert_floor_seconds = None
         poll_seconds = 60
         heartbeat = 0
         max_replay = 50
@@ -1730,6 +1739,7 @@ class BoundedWindowEndToEndTest(unittest.TestCase):
         t.persona, t.url, t.headers = "argus", "http://x/api/inbox?persona=argus", {}
         t.opener, t.emitter, t.args = None, emitter, self.FullArgs()
         t.cursor, t.armed, t.fsm_state, t.failures = cursor, True, "UP", 0
+        t.down_since = None
         t.state_file = t.last_unread = None
         t.fast_path = False
         t.skips = t.first_poll = 0
@@ -1982,6 +1992,7 @@ class CorruptPinStateTest(unittest.TestCase):
         t.emitter, t.args = em, BoundedWindowEndToEndTest.FullArgs()
         t.args.max_replay = 1
         t.cursor, t.armed, t.fsm_state, t.failures = 100, False, "UP", 0
+        t.down_since = None
         t.state_file = t.last_unread = None
         t.fast_path = False
         t.skips = t.first_poll = 0
@@ -2702,6 +2713,15 @@ class ExecEnvTest(unittest.TestCase):
         self.assertEqual(env["KIJITOMON_ID"], "41")
         self.assertEqual(env["KIJITOMON_FROM"], "river")
 
+    def test_the_reachability_alert_exports_its_measured_span_and_floor(self):
+        # §7.1 rev 10: `seconds` is a measurement now, so an exec consumer gets it (and the floor it
+        # cleared) instead of having to infer onset from flags it cannot see.
+        env = self._env_for({"event": "alert", "source": "kijito-inbox", "ts": "t", "persona": "argus",
+                             "reason": "http 502", "consecutive_failures": 7, "seconds": 61,
+                             "floor_seconds": 60})
+        self.assertEqual((env["KIJITOMON_FAILURES"], env["KIJITOMON_SECONDS"], env["KIJITOMON_FLOOR_SECONDS"]),
+                         ("7", "61", "60"))
+
 
 class WarnOncePerPersonaTest(unittest.TestCase):
     def setUp(self):
@@ -4608,6 +4628,7 @@ class Loom11AlarmDeliveryTest(unittest.TestCase):
         t.opener, t.emitter = None, emitter
         t.args = BoundedWindowEndToEndTest.FullArgs()
         t.cursor, t.armed, t.fsm_state, t.failures = cursor, True, fsm, 0
+        t.down_since = None
         t.state_file = t.last_unread = None
         t.fast_path = False
         t.skips = t.first_poll = 0
@@ -4631,22 +4652,47 @@ class Loom11AlarmDeliveryTest(unittest.TestCase):
     def _down_fetch(reason="http 502"):
         return lambda opener, url, headers: km.Poll(False, reason=reason)
 
+    def _clock(self, start=1000.0):
+        """Take over km._monotonic for ONE test; returns the mutable [now]. §7.1 the alert floor is a
+        MEASURED span, so a liveness test has to say WHEN each poll happens, not only how many."""
+        clock = [start]
+        real = km._monotonic
+        km._monotonic = lambda: clock[0]
+        self.addCleanup(lambda: setattr(km, "_monotonic", real))
+        return clock
+
+    def _run_at(self, t, fetch_fn, clock, at):
+        """poll_once at each monotonic instant in `at` (seconds after the clock's start)."""
+        orig, km.fetch = km.fetch, fetch_fn
+        try:
+            for when in at:
+                clock[0] = 1000.0 + when
+                t.poll_once()
+        finally:
+            km.fetch = orig
+
     # ---- F2: the dead-man's switch had NO test. These are it. --------------------------------------
     def test_the_liveness_DOWN_alert_IS_EMITTED_after_alert_after_failures(self):
         # THE GAP A1 EXPOSED: deleting this alert entirely left all 242 tests green, because nothing
         # asserted the one event README sells as the dead-man's switch.
         em = self.Recorder()
+        clock = self._clock()
         t = self._target(em)
-        self._run(t, self._down_fetch(), times=t.args.alert_after)
+        # §7.1: alert_after failures AT THE CONFIGURED CADENCE (poll_seconds apart) - the count AND the
+        # measured floor ((alert_after - 1) * poll_seconds) are both reached on the third poll.
+        self._run_at(t, self._down_fetch(), clock, at=[0, 60, 120])
         alerts = [f for e, f in em.events if e == "alert"]
         self.assertEqual(len(alerts), 1, "the source went down and no alert was emitted")
         self.assertEqual(alerts[0]["reason"], "http 502")
         self.assertEqual(alerts[0]["consecutive_failures"], t.args.alert_after)
+        self.assertEqual(alerts[0]["seconds"], 120)          # MEASURED, not failures * poll_seconds
+        self.assertEqual(alerts[0]["floor_seconds"], 120)
         self.assertEqual(t.fsm_state, "DOWN")
 
     def test_the_DOWN_alert_does_not_fire_before_the_threshold(self):
         em = self.Recorder()
         t = self._target(em)
+        t.args.alert_floor_seconds = 0   # floor off, so this test is about the COUNT guard alone
         self._run(t, self._down_fetch(), times=t.args.alert_after - 1)
         self.assertEqual([f for e, f in em.events if e == "alert"], [])
         self.assertEqual(t.fsm_state, "UP")
@@ -4656,9 +4702,10 @@ class Loom11AlarmDeliveryTest(unittest.TestCase):
         # edge is crossed exactly once and a reverted transition would never re-fire). So the
         # announcement gets the guaranteed second channel instead.
         em = self.Recorder(deliver=False)
+        clock = self._clock()
         t = self._target(em)
         buf = _capture_stderr(self)
-        self._run(t, self._down_fetch(), times=t.args.alert_after)
+        self._run_at(t, self._down_fetch(), clock, at=[0, 60, 120])
         self.assertEqual(t.fsm_state, "DOWN")
         self.assertIn("UNDELIVERED", buf.getvalue())
         self.assertIn("http 502", buf.getvalue())
@@ -4743,6 +4790,273 @@ def _capture_stderr(test):
     return buf
 
 
+
+class RetryAfterPacingTest(unittest.TestCase):
+    """A failed long-poll is paced by the server's own Retry-After hint (row M375, bug #19).
+
+    The edge's restart page says "restarting; retry shortly" and carries `Retry-After` plus a JSON
+    `retry_after_seconds`. The hint only ever LENGTHENS the wait before the next retry, is clamped to
+    RETRY_AFTER_CAP, and never feeds the alert decision - that stays the measured floor's job.
+    """
+    class H(dict):
+        def get(self, k, d=None):
+            return dict.get(self, k, d)
+
+    def test_header_delta_seconds(self):
+        self.assertEqual(km._retry_after_seconds(self.H({"Retry-After": "15"})), 15)
+        self.assertEqual(km._retry_after_seconds(self.H({"Retry-After": " 0 "})), 0)
+
+    def test_header_http_date(self):
+        when = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(seconds=30)
+        got = km._retry_after_seconds(self.H({"Retry-After": email.utils.format_datetime(when, usegmt=True)}))
+        self.assertTrue(28 <= got <= 31, got)
+        past = email.utils.format_datetime(when - datetime.timedelta(hours=1), usegmt=True)
+        self.assertEqual(km._retry_after_seconds(self.H({"Retry-After": past})), 0)   # clamped, never negative
+
+    def test_body_field_when_no_header(self):
+        body = json.dumps({"error": "edge_bad_gateway", "retry_after_seconds": 7.2}).encode()
+        self.assertEqual(km._retry_after_seconds(self.H(), body), 8)       # rounded UP, never shorter
+        self.assertEqual(km._retry_after_seconds(self.H({"Retry-After": "3"}), body), 3)  # header wins
+
+    def test_garbage_and_absent_hints_are_none(self):
+        for h, b in [(None, None), (self.H(), None), (self.H({"Retry-After": "soon"}), None),
+                     (self.H({"Retry-After": "-5"}), None), (self.H(), b"<html>502</html>"),
+                     (self.H(), json.dumps({"retry_after_seconds": True}).encode()),
+                     (self.H(), json.dumps({"retry_after_seconds": "9"}).encode()),
+                     (self.H(), b'{"retry_after_seconds": NaN}'), (self.H(), json.dumps([1]).encode())]:
+            self.assertIsNone(km._retry_after_seconds(h, b), (h, b))
+
+    def test_hint_is_clamped_to_the_cap(self):
+        self.assertEqual(km._retry_after_seconds(self.H({"Retry-After": "86400"})), km.RETRY_AFTER_CAP)
+        self.assertEqual(km._retry_after_seconds(self.H(), b'{"retry_after_seconds": 1e308}'), km.RETRY_AFTER_CAP)
+
+    def test_longpoll_502_records_the_hint_and_keeps_the_cursor(self):
+        body = io.BytesIO(json.dumps({"error": "edge_bad_gateway", "retry_after_seconds": 10}).encode())
+        err = urllib.error.HTTPError(km.NOTIFY_PENDING_URL, 502, "Bad Gateway",
+                                     email.message.Message(), body)
+        err.headers["Retry-After"] = "12"
+        available, counts, cursor = km.fetch_unread_counts_longpoll(FakeOpener(exc=err), {}, 50, "keep")
+        self.assertEqual((available, counts, cursor), (False, {}, "keep"))
+        self.assertEqual(km._RETRY_HINT["seconds"], 12)
+        # a later failure WITHOUT a hint clears it - a stale hint must never pace an unrelated failure
+        km.fetch_unread_counts_longpoll(FakeOpener(exc=urllib.error.URLError("dropped")), {}, 50, "keep")
+        self.assertIsNone(km._RETRY_HINT["seconds"])
+
+    def test_backoff_never_shorter_than_the_hint_and_exponential_without_one(self):
+        seq, b = [], 0
+        for _ in range(7):
+            b = km.next_longpoll_backoff(b, None)
+            seq.append(b)
+        self.assertEqual(seq, [1, 2, 4, 8, 16, 30, 30])
+        self.assertEqual(km.next_longpoll_backoff(0, 15), 15)
+        self.assertEqual(km.next_longpoll_backoff(15, 15), 30)
+        self.assertEqual(km.next_longpoll_backoff(30, 90), 90)
+
+
+class MeasuredAlertFloorTest(unittest.TestCase):
+    """§7.1 THE DEAD-MAN EDGE NEEDS A MEASURED SPAN, NOT ONLY A FAILURE COUNT.
+
+    With `--wait` the loop retries a failed long-poll after 1/2/4 s, so `--alert-after 3` was reached
+    ~3 s into ANY outage and every routine server restart - 11 s edge windows included - alerted, while `seconds`
+    reported the nominal 90. The floor is now (alert_after - 1) * poll_seconds of MEASURED time since the
+    first failure (or --alert-floor-seconds), and `seconds` is that measurement.
+    """
+    # Borrow the liveness fixtures rather than subclass: subclassing re-runs the parent's tests.
+    Recorder = Loom11AlarmDeliveryTest.Recorder
+    _target = Loom11AlarmDeliveryTest._target
+    _down_fetch = staticmethod(Loom11AlarmDeliveryTest._down_fetch)
+    _clock = Loom11AlarmDeliveryTest._clock
+    _run_at = Loom11AlarmDeliveryTest._run_at
+
+    def test_the_count_alone_does_not_cross_the_edge_the_measured_floor_does(self):
+        em = self.Recorder()
+        clock = self._clock()
+        t = self._target(em)
+        # long-poll retry shape: failures at +0, +1, +3 - the count is reached in 3 s
+        self._run_at(t, self._down_fetch(), clock, at=[0, 1, 3])
+        self.assertEqual([f for e, f in em.events if e == "alert"], [], "count-only edge is the defect")
+        self.assertEqual((t.fsm_state, t.failures), ("UP", 3))
+        self._run_at(t, self._down_fetch(), clock, at=[7, 15, 31, 63])
+        self.assertEqual([f for e, f in em.events if e == "alert"], [], "still under the 120 s floor")
+        self._run_at(t, self._down_fetch(), clock, at=[120])
+        alerts = [f for e, f in em.events if e == "alert"]
+        self.assertEqual(len(alerts), 1)
+        self.assertEqual(alerts[0]["consecutive_failures"], 8)
+        self.assertEqual(alerts[0]["seconds"], 120)
+        self.assertEqual(alerts[0]["floor_seconds"], 120)
+        self.assertEqual(t.fsm_state, "DOWN")
+        # edge-once: more failures past the floor never re-alert
+        self._run_at(t, self._down_fetch(), clock, at=[130, 200])
+        self.assertEqual(len([f for e, f in em.events if e == "alert"]), 1)
+
+    def test_a_restart_bracket_under_the_floor_is_silent_and_leaves_no_debt(self):
+        em = self.Recorder()
+        clock = self._clock()
+        t = self._target(em)
+        self._run_at(t, self._down_fetch(), clock, at=[0, 1, 3, 7])
+        self._run_at(t, BoundedWindowEndToEndTest()._fetch([{"id": 101}], 0), clock, at=[12])
+        self.assertEqual([e for e, f in em.events if e in ("alert", "recovered")], [],
+                         "an 11 s bracket must produce neither edge")
+        self.assertEqual((t.fsm_state, t.failures, t.down_since), ("UP", 0, None))
+        self.assertEqual(em.new_ids, [101])   # and the mail from the healthy poll still flows
+
+    def test_bug19_a_20s_restart_of_502s_raises_zero_wake_events(self):
+        # Row M375 / bug #19: a ~20 s server restart answered every poll with 502 while the producer
+        # retried at its long-poll backoff (1, 2, 4, 8 s). Before the floor that was alert + recovered -
+        # two wakes, no mail. Now: nothing at all, and the mail after the restart still flows.
+        em = self.Recorder()
+        clock = self._clock()
+        t = self._target(em)
+        self._run_at(t, self._down_fetch(), clock, at=[0, 1, 3, 7, 15])
+        self._run_at(t, BoundedWindowEndToEndTest()._fetch([{"id": 101}], 0), clock, at=[20])
+        wake = [e for e, f in em.events if km._wake_class(e) == km.WAKE_CLASS_DIAGNOSTIC]
+        self.assertEqual(wake, [], "a 20 s restart must wake nobody")
+        self.assertEqual((t.fsm_state, t.failures, t.down_since), ("UP", 0, None))
+        self.assertEqual(em.new_ids, [101])
+
+    def test_bug19_a_20s_restart_recovering_on_the_count_fast_path_is_silent_too(self):
+        # The same restart, but the first healthy tick is the /api/notify/pending fast path (no unread
+        # increase, so the full inbox poll is skipped) - the path a long-polling producer usually
+        # recovers through. It must not announce a recovery nobody was told about.
+        em = self.Recorder()
+        clock = self._clock()
+        t = self._target(em)
+        t.args.no_fast_path = False
+        t.fast_path, t.last_unread = True, 0
+        self._run_at(t, self._down_fetch(), clock, at=[0, 1, 3, 7, 15])
+        self.assertEqual(t.failures, 5)
+        clock[0] = 1000.0 + 20
+        t.poll_once(counts_available=True, unread_counts={"argus": 0})
+        self.assertEqual([e for e, f in em.events if km._wake_class(e) == km.WAKE_CLASS_DIAGNOSTIC], [])
+        self.assertEqual((t.fsm_state, t.failures, t.down_since), ("UP", 0, None))
+
+    def test_an_outage_past_the_floor_raises_exactly_one_alert_then_one_recovered(self):
+        em = self.Recorder()
+        clock = self._clock()
+        t = self._target(em)
+        self._run_at(t, self._down_fetch(), clock, at=[0, 1, 3, 7, 15, 31, 61, 91, 121, 151])
+        self._run_at(t, BoundedWindowEndToEndTest()._fetch([{"id": 101}], 0), clock, at=[160, 170])
+        self.assertEqual([e for e, f in em.events if e in ("alert", "recovered")], ["alert", "recovered"])
+        self.assertEqual(t.fsm_state, "UP")
+
+    def test_plain_poll_cadence_alerts_on_the_Nth_failure_exactly_as_before(self):
+        em = self.Recorder()
+        clock = self._clock()
+        t = self._target(em)
+        self._run_at(t, self._down_fetch(), clock, at=[0, 60])
+        self.assertEqual([f for e, f in em.events if e == "alert"], [])
+        self._run_at(t, self._down_fetch(), clock, at=[120])
+        alerts = [f for e, f in em.events if e == "alert"]
+        self.assertEqual([a["consecutive_failures"] for a in alerts], [3])
+
+    def test_alert_floor_seconds_override_is_honoured_and_zero_restores_count_only(self):
+        em = self.Recorder()
+        clock = self._clock()
+        t = self._target(em)
+        t.args.alert_floor_seconds = 5
+        self._run_at(t, self._down_fetch(), clock, at=[0, 1, 3])
+        self.assertEqual([f for e, f in em.events if e == "alert"], [])
+        self._run_at(t, self._down_fetch(), clock, at=[6])
+        alerts = [f for e, f in em.events if e == "alert"]
+        self.assertEqual((alerts[0]["seconds"], alerts[0]["floor_seconds"]), (6, 5))
+        # 0 = the pre-fix count-only edge, for anyone who wants it back
+        em2 = self.Recorder()
+        t2 = self._target(em2)
+        t2.args.alert_floor_seconds = 0
+        self._run_at(t2, self._down_fetch(), clock, at=[300, 301, 303])
+        self.assertEqual([f["consecutive_failures"] for e, f in em2.events if e == "alert"], [3])
+
+    def test_a_run_restored_by_WatchTarget_init_resumes_the_measured_span(self):
+        # EXERCISES the restore path in __init__ (not a restatement of it - the review found that
+        # deleting the block, or flipping its sign, left the suite green when the fixture hand-set the
+        # attributes). A supervisor restart mid-outage rebuilds the target from the state file: the
+        # persisted wall stamp says the run began 100 s ago, so the floor (120 s) is reached 20 s after
+        # the restart, not 120 s after it.
+        d = tempfile.mkdtemp()
+        self.addCleanup(lambda: __import__("shutil").rmtree(d, ignore_errors=True))
+        base = os.path.join(d, "state.json")
+        url = "http://x/api/inbox?persona=argus"
+        clock = self._clock()
+        km.StateFile(km._state_path_for_persona(base, "argus"), km.canonical_identity(url)).save(
+            100, "UP", 2, down_since=time.time() - 100.0)
+
+        class A(BoundedWindowEndToEndTest.FullArgs):
+            state_file = base
+            seed_at = None
+        em = self.Recorder()
+        t = km.WatchTarget("argus", url, None, {}, A(), em)
+        self.addCleanup(t.state_file.unlock)
+        self.assertEqual(t.failures, 2)
+        self.assertAlmostEqual(t.down_since[0], 1000.0 - 100.0, delta=2.0)   # mapped onto the patched clock
+        self._run_at(t, self._down_fetch(), clock, at=[0])        # span ~100 < 120
+        self.assertEqual([f for e, f in em.events if e == "alert"], [])
+        self._run_at(t, self._down_fetch(), clock, at=[21])       # span ~121 >= 120
+        alerts = [f for e, f in em.events if e == "alert"]
+        self.assertEqual(alerts[0]["consecutive_failures"], 4)
+        self.assertGreaterEqual(alerts[0]["seconds"], 120)
+        # and the healthy poll that follows clears the persisted stamp
+        self._run_at(t, BoundedWindowEndToEndTest()._fetch([{"id": 101}], 0), clock, at=[30])
+        with open(km._state_path_for_persona(base, "argus")) as f:
+            self.assertNotIn("down_since", json.load(f))
+
+    def test_an_older_state_file_without_the_stamp_measures_from_the_restart(self):
+        d = tempfile.mkdtemp()
+        self.addCleanup(lambda: __import__("shutil").rmtree(d, ignore_errors=True))
+        base = os.path.join(d, "state.json")
+        url = "http://x/api/inbox?persona=argus"
+        clock = self._clock()
+        km.StateFile(km._state_path_for_persona(base, "argus"), km.canonical_identity(url)).save(100, "UP", 2)
+
+        class A(BoundedWindowEndToEndTest.FullArgs):
+            state_file = base
+            seed_at = None
+        em = self.Recorder()
+        t = km.WatchTarget("argus", url, None, {}, A(), em)
+        self.addCleanup(t.state_file.unlock)
+        self.assertEqual(t.failures, 2)
+        self.assertAlmostEqual(t.down_since[0], 1000.0, delta=2.0)          # the run starts NOW
+        self._run_at(t, self._down_fetch(), clock, at=[0, 60, 119])
+        self.assertEqual([f for e, f in em.events if e == "alert"], [], "conservative: never earlier")
+        self._run_at(t, self._down_fetch(), clock, at=[120])
+        self.assertEqual(len([f for e, f in em.events if e == "alert"]), 1)
+
+    def test_the_first_failure_stamp_round_trips_through_the_state_file_and_is_read_strictly(self):
+        d = tempfile.mkdtemp()
+        self.addCleanup(lambda: __import__("shutil").rmtree(d, ignore_errors=True))
+        path = os.path.join(d, "s.json")
+        sf = km.StateFile(path, "idx")
+        self.assertTrue(sf.save(100, "UP", 2, down_since=1234.5))
+        self.assertEqual(sf.load()["down_since"], 1234.5)
+        self.assertTrue(sf.save(100, "UP", 0))                  # healthy: the stamp is not written
+        with open(path) as f:
+            self.assertNotIn("down_since", json.load(f))
+        self.assertIsNone(sf.load()["down_since"])
+        with open(path, "w") as f:                               # a non-number is not a timestamp
+            json.dump({"identity": "idx", "cursor": 100, "state": "UP", "consecutive_failures": 2,
+                       "down_since": "yesterday"}, f)
+        _capture_stderr(self)
+        self.assertIs(sf.load(), km.CORRUPT_STATE)
+        with open(path, "w") as f:                               # and neither is a bool
+            json.dump({"identity": "idx", "cursor": 100, "state": "UP", "consecutive_failures": 2,
+                       "down_since": True}, f)
+        self.assertIs(sf.load(), km.CORRUPT_STATE)
+        # json accepts every one of these; the 400-digit int is the one math.isfinite itself chokes on
+        # (OverflowError, not False), and 0/-0.0 are finite but no stamp - a run cannot have begun at epoch 0.
+        for bad in ("-Infinity", "Infinity", "NaN", "-5", "1e400", "1" + "0" * 400, "0", "-0.0"):
+            with open(path, "w") as f:
+                f.write('{"identity": "idx", "cursor": 100, "state": "UP", "consecutive_failures": 2, '
+                        '"down_since": %s}' % bad)
+            self.assertIs(sf.load(), km.CORRUPT_STATE, bad)      # an infinite span would raise at the edge
+
+    def test_the_default_floor_is_derived_from_the_two_flags(self):
+        class A:
+            alert_after, poll_seconds, alert_floor_seconds = 3, 30, None
+        self.assertEqual(km.alert_floor_seconds(A()), 60)        # the VM units: 3 polls at 30 s
+        A.alert_floor_seconds = 7
+        self.assertEqual(km.alert_floor_seconds(A()), 7)
+        A.alert_after, A.alert_floor_seconds = 1, None
+        self.assertEqual(km.alert_floor_seconds(A()), 0)         # --alert-after 1 keeps its meaning
+
 class Loom10ClassSweepTest(unittest.TestCase):
     """Loom re-audit 10 - the CLASS, swept rather than patched one finding at a time.