Notice when the Watchdog alert stops arriving

Everything this server does assumes alerts arrive. If Prometheus stops
evaluating, or Alertmanager cannot reach us, nothing arrives — and
silence is indistinguishable from everything being fine. The cluster has
shipped the alert for exactly this case all along: Watchdog is
expr: vector(1), so it fires permanently and is re-sent forever, and it
is worth nothing unless something downstream notices it stop. Nothing
did. It arrived, opened no incident because a repeat_interval re-send is
not a new occurrence, and when the monitoring stack died the sweeper
quietly expired it and paged nobody.

So the handling is inverted for a configurable set of alerts: receiving
one opens no incident, and the absence of one does. TERDUT_DEADMAN_MATCHERS
selects them as label matchers, defaulting to alertname=Watchdog.

The unit of monitoring is the fingerprint rather than the alert name. Two
clusters sending the same Watchdog are two independent switches, so a
healthy one can never mask a dead one. Every matcher must name an
alertname, which keeps the sweeper's candidate query on alerts_name_idx
instead of JSON-extracting labels from every row, and leaves matching
with a single implementation.

A switch is dormant until its first heartbeat: a matcher nothing has ever
sent opens nothing, so a fresh deploy or a restored database does not
page. Resolving the incident by hand sticks, exactly as it does for an
alert-backed one, so a decommissioned source is a one-time page rather
than a nag; the switch re-arms only when the heartbeat comes back, and
dying again is a new incident.

The incident has no member alerts on purpose. Linking the heartbeat would
have the settled-incident cascade close it on the very sweep that opened
it, and there is no alert describing the problem anyway — the problem is
that no alert arrived. What happened is on the timeline instead, and
recovery is the only automatic way out.

One narrow exemption in the ingest guard makes recovery possible at all.
A heartbeat we declared dead is marked resolved, and the one that proves
us wrong carries the unchanged startsAt of an alert that never stopped
firing — so "resolution is terminal within an instance" would discard it
forever and a switch could die exactly once. The exemption is scoped to
resolution_source = 'deadman', which is the only resolution this server
infers from silence on a timeout of its own, so nothing another writer
set can be undone by a stale retry. Matched alerts are also held back
from the generic staleness expiry, which would otherwise resolve a
heartbeat as 'expiry' long before its own tighter deadline.

The timeout points the opposite way to TERDUT_STALE_AFTER: staleness is a
generous grace period around a repeat_interval you do not control, while
this is a deadline you set deliberately and configure the heartbeat's
route to beat. Inheriting a 4h or 12h repeat_interval gives a dead man's
switch with a twelve hour fuse, so the README spells out the route the
heartbeat needs.

README.md

@@ -100,6 +100,9 @@ Set `backupSidecar.enabled=false` if you back the volume up some other way.
 | `TERDUT_DB_PATH` | `terdut.db` | Path to the SQLite database file |
 | `TERDUT_ARCHIVE_AFTER` | `168h` (7d) | How long a resolved alert or incident stays in the default list before being auto-archived |
 | `TERDUT_STALE_AFTER` | `6h` | How long a firing alert may go without a refreshing webhook before it is treated as resolved — **must exceed your Alertmanager `repeat_interval`** |
+| `TERDUT_DEADMAN_MATCHERS` | `alertname=Watchdog` | Which alerts are [dead man's switches](#dead-mans-switch). `;` separates matchers, `,` the label conditions within one, `=` is exact equality. Every matcher must name an `alertname` |
+| `TERDUT_DEADMAN_TIMEOUT` | `15m` | How long a heartbeat may go unheard before its switch is declared dead — **must be shorter than the `repeat_interval` of the route carrying it**. `0` disables dead man's switch handling |
+| `TERDUT_DEADMAN_SEVERITY` | `critical` | Severity a dead man's switch incident opens at |
 | `TERDUT_NTFY_URL` | — | ntfy server to publish push notifications to. Empty disables notifications entirely |
 | `TERDUT_NTFY_TOKEN` | — | Bearer token for an access-controlled ntfy |
 | `TERDUT_NTFY_FALLBACK_TOPIC` | — | Topic used when nobody is on call |
@@ -108,7 +111,11 @@ Set `backupSidecar.enabled=false` if you back the volume up some other way.
 
 Durations use Go syntax (`30m`, `12h`, `168h`). An unparseable value falls back to the default.
 
-In the Helm chart the two sweeper durations are set via `sweeper.staleAfter` and `sweeper.archiveAfter`, and notifications via the `notify.*` values.
+Note that `TERDUT_STALE_AFTER` and `TERDUT_DEADMAN_TIMEOUT` point in opposite directions. Staleness
+is a generous grace period around a `repeat_interval` you do not control; a dead man's switch is a
+deadline you set deliberately, and the heartbeat's route is configured to beat faster than it.
+
+In the Helm chart the two sweeper durations are set via `sweeper.staleAfter` and `sweeper.archiveAfter`, dead man's switches via the `deadman.*` values, and notifications via the `notify.*` values.
 
 ---
 
@@ -129,6 +136,30 @@ route:
 
 The webhook endpoint requires no authentication.
 
+If you use the [dead man's switch](#dead-mans-switch) — and the default configuration does — give
+the heartbeat a route of its own, because the deadline is only as tight as the interval feeding it:
+
+```yaml
+route:
+  receiver: terdut
+  repeat_interval: 4h
+  routes:
+    - matchers: [ 'alertname = "Watchdog"' ]
+      receiver: terdut
+      group_wait: 0s
+      group_interval: 1m
+      repeat_interval: 1m
+```
+
+That delivers a heartbeat every **2 minutes**, not every minute. Alertmanager only reconsiders a
+group every `group_interval`, and at exactly one elapsed interval `repeat_interval` has not *quite*
+passed, so the send slips to the next tick — equal values give 2×. Two minutes against the 15 minute
+default is seven heartbeats per window, which is the point; use `group_interval: 30s` if you want
+the numbers to mean what they say.
+
+kube-prometheus-stack users get the `Watchdog` alert (`expr: vector(1)`) for free; it just needs
+routing to terdut rather than to `null`.
+
 ---
 
 ## Alerts and incidents
@@ -179,6 +210,10 @@ alert that never stopped firing.
   that group opens a *new* incident rather than reopening this one. If the alert
   underneath never stops firing, the incident stays closed — that is what
   resolving by hand asserts.
+- **On recovery**, for a [dead man's switch](#dead-mans-switch) incident whose
+  heartbeat started arriving again (`"resolution_source": "recovered"`). These
+  incidents have no member alerts, so the automatic cascade above cannot reach
+  them.
 
 To quieten an incident you expect to come back, snooze it instead
 (`POST /api/incidents/{id}/snooze`). A snooze hides the incident from the default
@@ -267,6 +302,72 @@ to distinguish them from a real Alertmanager resolve (`"alertmanager"`).
 An expiry cascades: once it leaves an incident with nothing firing under it, the
 incident resolves too, in the same sweep.
 
+### Dead man's switch
+
+Everything above assumes alerts arrive. If Prometheus stops evaluating, or
+Alertmanager cannot reach this server, nothing arrives — and silence looks
+exactly like everything being fine. A dead man's switch inverts the handling for
+one designated alert so that silence is the signal:
+
+- **receiving** it opens no incident, and
+- the **absence** of it does.
+
+kube-prometheus-stack already ships the alert for this. `Watchdog` is
+`expr: vector(1)`, so it fires permanently and is re-sent forever; it is worth
+nothing unless something downstream notices it stop. That is what
+`TERDUT_DEADMAN_MATCHERS` defaults to.
+
+A matcher is a set of exact label conditions, one of which must be the
+`alertname`:
+
+```
+TERDUT_DEADMAN_MATCHERS="alertname=Watchdog,cluster=prod; alertname=EdgeHeartbeat"
+```
+
+**The unit of monitoring is the fingerprint, not the alert name.** Two clusters
+sending the same `Watchdog` are two independent switches, so a healthy one can
+never mask a dead one.
+
+#### The lifecycle
+
+A switch is **dormant** until its first heartbeat arrives. A configured matcher
+that has never been heard from opens nothing, so a fresh deploy or a restored
+database does not page. It also means a matcher that never matches anything is
+silently inert — check the startup log line, which lists the matchers that
+survived parsing.
+
+Once armed, the sweeper declares it **dead** when either the heartbeat has not
+been refreshed within `TERDUT_DEADMAN_TIMEOUT`, or Alertmanager explicitly
+resolved it — the sender saying the heartbeat stopped needs no further waiting.
+That opens an incident at `TERDUT_DEADMAN_SEVERITY`, assigned and paged like any
+other, and marks the heartbeat alert `"resolution_source": "deadman"` so the
+alert list stops claiming a dead switch is firing.
+
+It **recovers** when the heartbeat starts arriving again: the incident resolves
+with `"resolution_source": "recovered"` and the all-clear goes to whoever was
+paged.
+
+Resolving the incident by hand sticks, the same way it does for an alert-backed
+one. While the switch stays silent nothing new opens — so a decommissioned
+source is a one-time page rather than a nag. The switch **re-arms** on the next
+heartbeat: come back and die again, and that is a new incident.
+
+#### Two things to know
+
+`TERDUT_DEADMAN_TIMEOUT` must be **shorter** than the `repeat_interval` of the
+route carrying the heartbeat, which is the exact opposite of
+`TERDUT_STALE_AFTER`. Inheriting a default `repeat_interval` of 4h gives you a
+switch that takes four hours to notice anything, so give the heartbeat
+[its own route](#alertmanager-configuration). Matched alerts are exempt from
+stale-alert expiry — a heartbeat answers to its own timeout and nothing else.
+
+A dead man's switch incident has **no member alerts**:
+`GET /api/incidents/{id}/alerts` returns an empty list. There is no alert
+describing the problem, because the problem is that no alert arrived. What
+happened is on the timeline instead, as a `deadman_silent` event carrying the age
+of the last heartbeat, and the heartbeat's labels are on the incident's
+`group_labels`.
+
 ---
 
 ## API reference
@@ -345,7 +446,7 @@ only by their author. The rest of the timeline is a record of what happened.
 | `assigned_to_id` / `assigned_to` | | *optional* — user id, username |
 | `snoozed_until` | timestamp | *optional* — a value in the past reads as not snoozed |
 | `resolved_at` | timestamp | *optional* |
-| `resolution_source` | string | *optional* — `"alerts"` or `"manual"` |
+| `resolution_source` | string | *optional* — `"alerts"`, `"manual"` or `"recovered"` |
 | `archived_at` | timestamp | *optional* |
 | `alerts` | array | Only on `GET /api/incidents/{id}` |
 
@@ -366,9 +467,9 @@ name: degrade unknown values to "resolved, reason unknown".
 
 Types written today: `triggered`, `alert_added`, `alert_resolved`,
 `acknowledged`, `unacknowledged`, `assigned`, `snoozed`, `unsnoozed`, `resolved`,
-`note`, `notified`, `notify_failed`. On an `assigned` event `user_id` is the
-**assignee**, not the actor. New types may be added; render unknown ones
-generically rather than dropping them.
+`note`, `notified`, `notify_failed`, `deadman_silent`. On an `assigned` event
+`user_id` is the **assignee**, not the actor. New types may be added; render
+unknown ones generically rather than dropping them.
 
 On `notified` and `notify_failed`, `detail` carries the notification kind
 (`triggered` | `reminder` | `resolved`), and on a failure the reason after it.
@@ -390,7 +491,8 @@ Archived alerts are hidden from `GET /api/alerts` unless `?archived=true` is
 passed; alert archiving is automatic housekeeping by the sweeper, not a user
 action. Resolved alerts carry `resolution_source`: `"alertmanager"` for a real
 resolved webhook, `"expiry"` when the sweeper inferred it (see
-[Stale alert expiry](#stale-alert-expiry)).
+[Stale alert expiry](#stale-alert-expiry)), `"deadman"` for a heartbeat declared
+dead (see [Dead man's switch](#dead-mans-switch)).
 
 #### The alert object
 
@@ -411,7 +513,7 @@ when unset, so clients must treat them as nullable.
 | `generator_url` | string | Link back to the originating Prometheus |
 | `received_at` | timestamp | When the server last accepted a webhook for this alert — see below |
 | `incident_id` | integer | *optional* — the most recent incident this alert belongs to |
-| `resolution_source` | string | *optional* — `"alertmanager"` or `"expiry"` |
+| `resolution_source` | string | *optional* — `"alertmanager"`, `"expiry"` or `"deadman"` |
 | `archived_at` | timestamp | *optional* — set while archived |
 
 ##### `received_at` is a liveness heartbeat
@@ -466,6 +568,13 @@ which happened. Clients may rely on this:
   worthwhile, since `"expiry"` can also mean the alert is still firing and the
   notification path broke.
 
+- **`"deadman"` — a heartbeat was declared dead** (see
+  [Dead man's switch](#dead-mans-switch)). Like `"expiry"`, an inference from
+  silence rather than an observed end, so `ends_at` is approximate — but a much
+  tighter one, bounded by `TERDUT_DEADMAN_TIMEOUT`. It is also the one resolution
+  a re-fire under the same `starts_at` can undo, since the switch coming back is
+  exactly the evidence that the inference was wrong.
+
 Treat the value as an open set and tolerate ones you do not recognise — new
 sources may be added, and unknown values should degrade to "resolved, reason
 unknown" rather than being rejected.
@@ -522,6 +631,26 @@ Nothing about the two documented alert contracts changes: `received_at` is still
 advanced on every accepted webhook, and `resolution_source` still means what it
 did.
 
+## Upgrading to dead man's switches
+
+Dead man's switch handling is **on by default**, watching `alertname=Watchdog`
+with a 15 minute timeout. If you already route `Watchdog` to this server, the
+behaviour of that alert changes on upgrade, in both directions:
+
+- it stops opening incidents when it arrives, and
+- it starts opening one when it stops arriving.
+
+**Check your `repeat_interval` before upgrading.** The switch pages whenever a
+heartbeat has not been refreshed within `TERDUT_DEADMAN_TIMEOUT`, so a `Watchdog`
+route inheriting a 4h or 12h `repeat_interval` will page constantly against the
+15 minute default. Either give the heartbeat
+[its own fast route](#alertmanager-configuration) — the point of the feature — or
+set `TERDUT_DEADMAN_TIMEOUT` above your current `repeat_interval` until you have.
+`TERDUT_DEADMAN_TIMEOUT=0` turns the whole thing off.
+
+There is no migration and no schema change. An existing open incident from a
+`Watchdog` that arrived under the old behaviour is unaffected; resolve it by hand.
+
 ---
 
 ## Development