cursedbelt-server 1.0.0

package/dist/server/incidents/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `cursedbelt-server/incidents` — the fleet's ONE owner-alert primitive: a
+ * condition that is true for a while, told to the owner exactly once, and told
+ * to him again when it clears.
+ *
+ * ── Why it exists (the owner, 2026-08-13) ───────────────────────────────────
+ * *"I found out from an agent my collection uploads were stuck … there are
+ * probably all kinds of possible problems I miss over time, such as every orch
+ * task failing to deploy and live sites falling over 10 commits behind."*
+ * The incident behind it: 42 videos / 35 GB sat in the collections dropzone and
+ * every scheduled ingest failed all 42 with EPIPE against binary-server, while
+ * binary-server logged that it was under its 12 GB disk reserve — and the
+ * dropzone deletes originals once they reach the catalog. Nothing told him. Two
+ * separate deterministic checks would each have caught it on the first run.
+ *
+ * ── Why it is HERE and not in `satellite-kit` ───────────────────────────────
+ * The queued task suggested satellite-kit ("beside the metrics buffer"), and
+ * that would have been wrong for one measurable reason: **binary-server is one
+ * of the three apps the owner named, it is a different repo, and it depends on
+ * `cursedbelt` and `cwip` — not on satellite-kit.** Putting the engine in the
+ * kit would have meant bs either growing its own copy or growing a dependency on
+ * the satellites' internal kit, and the first of those is the drift this whole
+ * queue exists to end. The fleet-shaped DETECTORS (the deploy ledger, launchd,
+ * backups) are satellite-shaped and do live in the kit; the engine is here.
+ *
+ * ── The four pieces ─────────────────────────────────────────────────────────
+ *  - {@link createIncidentStore} — one row per condition, and `reconcile`, which
+ *    is the entire dedupe guarantee. Nothing else in the system decides whether
+ *    something is new.
+ *  - {@link runIncidentSweep} — runs checks; a check that THROWS resolves
+ *    nothing, so a broken detector can never announce that an outage is over.
+ *  - channels — in-app (the fleet's existing notification centre), email, and a
+ *    text message from this Mac that reads `chat.db` back to prove it left.
+ *  - {@link createIncidentNotifier} — composes the three-sentence message and
+ *    sends it on OPEN, on ESCALATE and on RESOLVE. Never on an observation.
+ *
+ * ```ts
+ * const store = createIncidentStore(db);
+ * const notifier = createIncidentNotifier({ store, channels });
+ * const result = await runIncidentSweep(store, checks);
+ * await notifier.announce(result.transitions);   // usually sends nothing
+ * ```
+ */
+export { type ChannelMessage, type ChannelOutcome, type ChannelResult, createEmailChannel, createInAppChannel, createRelayEmailChannel, createTextChannel, type EmailChannelOptions, type IncidentChannel, type SendEmail, type TextChannelOptions, } from "./channels";
+export { type CheckOutcome, type IncidentCheck, runIncidentSweep, type SweepResult, } from "./checks";
+export { INCIDENT_MIGRATIONS, INCIDENTS_TABLE } from "./migrations";
+export { type AnnounceResult, composeOpened, composeResolved, type CreateNotifierOptions, createIncidentNotifier, type IncidentNotifier, } from "./notifier";
+export { createIncidentReporter, type IncidentReporter, type IncidentReporterOptions, } from "./reporter";
+export { type IncidentRoutesOptions, mountIncidentMachineRoutes, mountIncidentOwnerRoutes, } from "./routes";
+export { assertNoContent, createIncidentStore, type IncidentStore, type ReconcileOptions, } from "./store";
+export { fingerprint, type Incident, type IncidentFact, type IncidentReport, type IncidentSeverity, type IncidentState, type IncidentTransitions, } from "./types";

package/dist/server/incidents/index.js

@@ -0,0 +1,51 @@
+/**
+ * `cursedbelt-server/incidents` — the fleet's ONE owner-alert primitive: a
+ * condition that is true for a while, told to the owner exactly once, and told
+ * to him again when it clears.
+ *
+ * ── Why it exists (the owner, 2026-08-13) ───────────────────────────────────
+ * *"I found out from an agent my collection uploads were stuck … there are
+ * probably all kinds of possible problems I miss over time, such as every orch
+ * task failing to deploy and live sites falling over 10 commits behind."*
+ * The incident behind it: 42 videos / 35 GB sat in the collections dropzone and
+ * every scheduled ingest failed all 42 with EPIPE against binary-server, while
+ * binary-server logged that it was under its 12 GB disk reserve — and the
+ * dropzone deletes originals once they reach the catalog. Nothing told him. Two
+ * separate deterministic checks would each have caught it on the first run.
+ *
+ * ── Why it is HERE and not in `satellite-kit` ───────────────────────────────
+ * The queued task suggested satellite-kit ("beside the metrics buffer"), and
+ * that would have been wrong for one measurable reason: **binary-server is one
+ * of the three apps the owner named, it is a different repo, and it depends on
+ * `cursedbelt` and `cwip` — not on satellite-kit.** Putting the engine in the
+ * kit would have meant bs either growing its own copy or growing a dependency on
+ * the satellites' internal kit, and the first of those is the drift this whole
+ * queue exists to end. The fleet-shaped DETECTORS (the deploy ledger, launchd,
+ * backups) are satellite-shaped and do live in the kit; the engine is here.
+ *
+ * ── The four pieces ─────────────────────────────────────────────────────────
+ *  - {@link createIncidentStore} — one row per condition, and `reconcile`, which
+ *    is the entire dedupe guarantee. Nothing else in the system decides whether
+ *    something is new.
+ *  - {@link runIncidentSweep} — runs checks; a check that THROWS resolves
+ *    nothing, so a broken detector can never announce that an outage is over.
+ *  - channels — in-app (the fleet's existing notification centre), email, and a
+ *    text message from this Mac that reads `chat.db` back to prove it left.
+ *  - {@link createIncidentNotifier} — composes the three-sentence message and
+ *    sends it on OPEN, on ESCALATE and on RESOLVE. Never on an observation.
+ *
+ * ```ts
+ * const store = createIncidentStore(db);
+ * const notifier = createIncidentNotifier({ store, channels });
+ * const result = await runIncidentSweep(store, checks);
+ * await notifier.announce(result.transitions);   // usually sends nothing
+ * ```
+ */
+export { createEmailChannel, createInAppChannel, createRelayEmailChannel, createTextChannel, } from "./channels";
+export { runIncidentSweep, } from "./checks";
+export { INCIDENT_MIGRATIONS, INCIDENTS_TABLE } from "./migrations";
+export { composeOpened, composeResolved, createIncidentNotifier, } from "./notifier";
+export { createIncidentReporter, } from "./reporter";
+export { mountIncidentMachineRoutes, mountIncidentOwnerRoutes, } from "./routes";
+export { assertNoContent, createIncidentStore, } from "./store";
+export { fingerprint, } from "./types";

package/dist/server/incidents/migrations.d.ts

@@ -0,0 +1,20 @@
+import type { Migration } from "../migration/types";
+/** The one table this primitive owns. */
+export declare const INCIDENTS_TABLE = "incidents";
+/**
+ * ONE row per CONDITION, keyed by its fingerprint — not one row per observation.
+ *
+ * That is the whole dedupe design expressed as a schema: a poller that notices
+ * the same broken thing 288 times a day cannot produce 288 rows, because there
+ * is nowhere to put them. `seen_count` and `last_seen` absorb the repetition,
+ * and the notification columns record that the owner was told ONCE.
+ *
+ * 🔴 **Never retention-managed.** Every other telemetry table in this package
+ * is capped or aged out; this one is not, and must not be declared as a
+ * retention target. An incident is the record of something having gone wrong on
+ * a fleet whose owner's stated problem is *"I missed this for a long time"* —
+ * the row that answers "has this happened before?" six months later is the
+ * expensive one to have thrown away. The table is bounded by reality instead:
+ * a fingerprint is stable, so a recurring problem re-uses its row forever.
+ */
+export declare const INCIDENT_MIGRATIONS: readonly Migration[];

package/dist/server/incidents/migrations.js

@@ -0,0 +1,58 @@
+/** The one table this primitive owns. */
+export const INCIDENTS_TABLE = "incidents";
+/**
+ * ONE row per CONDITION, keyed by its fingerprint — not one row per observation.
+ *
+ * That is the whole dedupe design expressed as a schema: a poller that notices
+ * the same broken thing 288 times a day cannot produce 288 rows, because there
+ * is nowhere to put them. `seen_count` and `last_seen` absorb the repetition,
+ * and the notification columns record that the owner was told ONCE.
+ *
+ * 🔴 **Never retention-managed.** Every other telemetry table in this package
+ * is capped or aged out; this one is not, and must not be declared as a
+ * retention target. An incident is the record of something having gone wrong on
+ * a fleet whose owner's stated problem is *"I missed this for a long time"* —
+ * the row that answers "has this happened before?" six months later is the
+ * expensive one to have thrown away. The table is bounded by reality instead:
+ * a fingerprint is stable, so a recurring problem re-uses its row forever.
+ */
+export const INCIDENT_MIGRATIONS = [
+    {
+        name: "0001_incidents",
+        up(db) {
+            db.run(`
+				CREATE TABLE IF NOT EXISTS ${INCIDENTS_TABLE} (
+					fingerprint          TEXT PRIMARY KEY,
+					source               TEXT NOT NULL,
+					check_key            TEXT NOT NULL,
+					kind                 TEXT NOT NULL,
+					subject              TEXT NOT NULL,
+					severity             TEXT NOT NULL
+					                     CHECK (severity IN ('blocking', 'warning')),
+					state                TEXT NOT NULL
+					                     CHECK (state IN ('open', 'acknowledged', 'resolved')),
+					title                TEXT NOT NULL,
+					what_broke           TEXT NOT NULL,
+					what_it_blocks       TEXT NOT NULL,
+					what_to_do           TEXT NOT NULL,
+					facts_json           TEXT,
+					first_seen           INTEGER NOT NULL,
+					last_seen            INTEGER NOT NULL,
+					seen_count           INTEGER NOT NULL DEFAULT 1,
+					episodes             INTEGER NOT NULL DEFAULT 1,
+					acknowledged_at      INTEGER,
+					resolved_at          INTEGER,
+					notified_at          INTEGER,
+					notify_result        TEXT,
+					resolved_notified_at INTEGER
+				)
+			`);
+            // The read every screen starts from: what is wrong right now.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_incidents_state
+					ON ${INCIDENTS_TABLE} (state, severity, last_seen DESC)`);
+            // The read `reconcile` does on every sweep, for every check.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_incidents_check
+					ON ${INCIDENTS_TABLE} (check_key, state)`);
+        },
+    },
+];

package/dist/server/incidents/notifier.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Turning a state TRANSITION into a message, and sending it exactly once.
+ *
+ * Everything that decides "does the owner hear about this?" is here, and there
+ * is very little of it, because the hard part was done in `store.ts`: this
+ * module only ever sees `opened`, `escalated` and `resolved`. There is no
+ * de-duplication logic in this file and there must never be — a second dedupe,
+ * on a timer, is how a system ends up with two disagreeing answers to "have I
+ * already said this?".
+ *
+ * ── The message the owner actually gets ─────────────────────────────────────
+ * The owner's standing complaint about agent hand-offs is that they name a
+ * symptom, a command and a credential without saying what any of them are. So
+ * an incident message is three sentences with fixed jobs, in this order:
+ *
+ *   WHAT BROKE      — in words, naming the app. Assume he does not know what
+ *                     your daemon, flag, tab or port is.
+ *   WHAT IT BLOCKS  — what he cannot do until it is fixed. This is the sentence
+ *                     that earns a text message at 2am; if you cannot write it,
+ *                     the incident is a `warning`.
+ *   WHAT TO DO      — a next step. A command carries its own `cd`, because he
+ *                     opens terminals anywhere (`fleet/rules/
+ *                     commands-must-run-from-anywhere.md`).
+ *
+ * ── 🔴 What is deliberately NOT in a message ────────────────────────────────
+ * File names, note titles, vault keys, e-mail addresses, anything a person
+ * typed. `subject` is an identifier and `facts` are numbers, both enforced at
+ * the store (`assertNoContent`). A text message is the least private surface
+ * this fleet has and several of its apps are private by construction.
+ */
+import type { ChannelMessage, ChannelResult, IncidentChannel } from "./channels";
+import type { IncidentStore } from "./store";
+import type { Incident, IncidentTransitions } from "./types";
+export interface IncidentNotifier {
+    /** Send for every transition in `t`. Returns one result per message sent. */
+    announce: (t: IncidentTransitions) => Promise<AnnounceResult[]>;
+    /** The channels registered on this host, for the console's health row. */
+    readonly channels: readonly IncidentChannel[];
+}
+export interface AnnounceResult {
+    fingerprint: string;
+    transition: "opened" | "escalated" | "resolved";
+    results: ChannelResult[];
+}
+/**
+ * How long to wait before trying a BLOCKING incident again when no channel
+ * managed to deliver it.
+ *
+ * 🔴 This exists because of a real hole found on the first live sweep: `roms`'
+ * overdue backup opened as blocking while the email channel was still
+ * misconfigured, both channels failed, and — because `notifiedAt` was stamped —
+ * nothing would ever have tried again. The owner would have had a blocking
+ * incident on a board he had no reason to open. The dedupe promise is "you are
+ * told ONCE", not "we attempt once": an attempt that reached nobody has not told
+ * him anything.
+ *
+ * It retries at most hourly, and it STOPS the moment any channel reports
+ * `delivered` — so a permanently broken channel costs one send an hour, and a
+ * working one costs exactly one message, which is the guarantee.
+ */
+export declare const UNDELIVERED_RETRY_MS: number;
+/** The message for a newly-open (or newly-blocking) incident. */
+export declare function composeOpened(incident: Incident): ChannelMessage;
+/**
+ * The message for a resolve. It exists so "is it fixed?" is answered without
+ * him having to go and look — the same reason the open message exists.
+ */
+export declare function composeResolved(incident: Incident): ChannelMessage;
+export interface CreateNotifierOptions {
+    store: IncidentStore;
+    channels: readonly IncidentChannel[];
+    /**
+     * Called with every channel result, so a host can record channel health.
+     * `detectChannelHealth` in `detectors.ts` turns a run of failures into its
+     * own incident — which is why `ChannelMessage.avoid` exists.
+     */
+    onChannelResult?: (fingerprint: string, result: ChannelResult) => void;
+}
+export declare function createIncidentNotifier(options: CreateNotifierOptions): IncidentNotifier;

package/dist/server/incidents/notifier.js

@@ -0,0 +1,141 @@
+/**
+ * How long to wait before trying a BLOCKING incident again when no channel
+ * managed to deliver it.
+ *
+ * 🔴 This exists because of a real hole found on the first live sweep: `roms`'
+ * overdue backup opened as blocking while the email channel was still
+ * misconfigured, both channels failed, and — because `notifiedAt` was stamped —
+ * nothing would ever have tried again. The owner would have had a blocking
+ * incident on a board he had no reason to open. The dedupe promise is "you are
+ * told ONCE", not "we attempt once": an attempt that reached nobody has not told
+ * him anything.
+ *
+ * It retries at most hourly, and it STOPS the moment any channel reports
+ * `delivered` — so a permanently broken channel costs one send an hour, and a
+ * working one costs exactly one message, which is the guarantee.
+ */
+export const UNDELIVERED_RETRY_MS = 60 * 60 * 1000;
+/** Did any channel actually get it out? `skipped` is not delivery. */
+const wasDelivered = (notifyResult) => Boolean(notifyResult?.includes("=delivered"));
+const factLine = (incident) => {
+    const facts = Object.entries(incident.facts ?? {});
+    if (facts.length === 0)
+        return "";
+    return `\n${facts.map(([k, v]) => `${k}: ${v}`).join(" · ")}`;
+};
+/** The message for a newly-open (or newly-blocking) incident. */
+export function composeOpened(incident) {
+    const tag = incident.severity === "blocking" ? "BLOCKED" : "Heads up";
+    return {
+        severity: incident.severity,
+        subject: `[${tag}] ${incident.title}`,
+        text: [
+            `What broke: ${incident.whatBroke}`,
+            `What it blocks: ${incident.whatItBlocks}`,
+            `What to do: ${incident.whatToDo}`,
+            `(${incident.source} · ${incident.kind} · ${incident.subject})${factLine(incident)}`,
+        ].join("\n\n"),
+    };
+}
+/**
+ * The message for a resolve. It exists so "is it fixed?" is answered without
+ * him having to go and look — the same reason the open message exists.
+ */
+export function composeResolved(incident) {
+    const minutes = Math.max(1, Math.round(((incident.resolvedAt ?? 0) - incident.firstSeen) / 60000));
+    return {
+        severity: incident.severity,
+        subject: `[cleared] ${incident.title}`,
+        text: [
+            `This is no longer happening. It was open for about ${minutes} minute${minutes === 1 ? "" : "s"}.`,
+            `It was: ${incident.whatBroke}`,
+            `(${incident.source} · ${incident.kind} · ${incident.subject})`,
+        ].join("\n\n"),
+    };
+}
+export function createIncidentNotifier(options) {
+    const { store, channels } = options;
+    const dispatch = async (incident, message, transition) => {
+        // An incident that IS a channel failure must not be announced down the
+        // channel it is about. Without this the first SES outage produces an
+        // endless retry loop against SES.
+        const avoid = incident.kind === "notification-channel-failing" ? [incident.subject] : undefined;
+        const withAvoid = avoid ? { ...message, avoid } : message;
+        const results = [];
+        for (const channel of channels) {
+            // 🔴 The `avoid` guard lives HERE, not in each channel. It was in every
+            // channel first and a spy channel in the spec walked straight past it —
+            // which is the same hole any channel added later would have had. One
+            // enforcement point, and a new channel inherits it by existing.
+            if (withAvoid.avoid?.includes(channel.key)) {
+                results.push({
+                    channel: channel.key,
+                    outcome: "skipped",
+                    detail: "this message is ABOUT this channel — not sent down it",
+                });
+                continue;
+            }
+            // Channels are awaited in series on purpose: there are at most three,
+            // they are all fast, and a serial loop means the text channel's
+            // delivery-proof read cannot race the email channel's for the same
+            // laptop resources.
+            const result = await channel.send(withAvoid).catch((err) => ({
+                channel: channel.key,
+                outcome: "failed",
+                detail: err instanceof Error ? err.message.slice(0, 200) : String(err),
+            }));
+            results.push(result);
+            options.onChannelResult?.(incident.fingerprint, result);
+        }
+        return { fingerprint: incident.fingerprint, transition, results };
+    };
+    const summarise = (results) => results.map((r) => `${r.channel}=${r.outcome}`).join(" ");
+    return {
+        channels,
+        async announce(t) {
+            const out = [];
+            for (const incident of [...t.opened, ...t.escalated]) {
+                const transition = t.opened.includes(incident) ? "opened" : "escalated";
+                const result = await dispatch(incident, composeOpened(incident), transition);
+                // 🔴 Only stamp `notifiedAt` when there was actually a channel to try.
+                // A host with none (a prod deployment that only stores what the Mac
+                // pushes it) has not told him anything, and stamping it there is what
+                // made the resolve message below fire for an open he never saw.
+                if (result.results.length > 0) {
+                    store.markNotified([incident.fingerprint], summarise(result.results));
+                }
+                out.push(result);
+            }
+            // A blocking incident nobody could be told about is retried, hourly,
+            // until one channel lands it. See `UNDELIVERED_RETRY_MS`.
+            for (const incident of t.unchanged) {
+                if (incident.severity !== "blocking")
+                    continue;
+                if (incident.notifiedAt === null)
+                    continue;
+                if (wasDelivered(incident.notifyResult))
+                    continue;
+                if (Date.now() - incident.notifiedAt < UNDELIVERED_RETRY_MS)
+                    continue;
+                const result = await dispatch(incident, composeOpened(incident), "opened");
+                if (result.results.length > 0) {
+                    store.markNotified([incident.fingerprint], summarise(result.results));
+                }
+                out.push(result);
+            }
+            for (const incident of t.resolved) {
+                // Never announce a resolve for something whose OPEN was never
+                // announced — the owner would get "cleared: X" for an X he has never
+                // heard of, which reads as a bug in the alerting rather than as good
+                // news. This happens for real: an incident opened, acknowledged and
+                // resolved between two sweeps of a host that had no channels.
+                if (incident.notifiedAt === null)
+                    continue;
+                const result = await dispatch(incident, composeResolved(incident), "resolved");
+                store.markResolvedNotified([incident.fingerprint]);
+                out.push(result);
+            }
+            return out;
+        },
+    };
+}

package/dist/server/incidents/reporter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The other side of `POST /incidents/report` — how a service that is NOT the
+ * console tells the console what it can see.
+ *
+ * ── Why a service reports rather than being polled ──────────────────────────
+ * The console can measure a service's disk, its port and its HTTP status from
+ * outside. It cannot measure the things that actually go wrong inside one: an
+ * ingest run where every item failed, a queue whose worker is looping on the
+ * same error, a store that is refusing writes for a reason of its own. Those
+ * facts exist for a few milliseconds inside the process that has them, and the
+ * only place they can be turned into an incident is there.
+ *
+ * ── 🔴 Reporting is a HEARTBEAT, not an event ───────────────────────────────
+ * A reporter sends the complete set of conditions that are true right now — the
+ * same contract a local check has — and sends it on a schedule whether or not
+ * anything is wrong. That is what lets the console clear an incident when the
+ * service recovers. A reporter that only posts on failure can open an incident
+ * and can never close one, and the owner ends up with a permanently red board,
+ * which is the same uselessness as a permanently green one.
+ *
+ * The dedupe is entirely the console's: post the same thing every five minutes
+ * for a week and he is told once. So a reporter needs no state, no "have I said
+ * this?" flag, and no backoff — which is why this file is forty lines and not
+ * four hundred.
+ *
+ * ── It never throws, and never blocks the service ───────────────────────────
+ * A service whose real work fails because its ALERTING is unreachable is worse
+ * than one with no alerting. Every failure here is logged and swallowed, and the
+ * console notices the silence by other means (the service's own health probe).
+ */
+import type { IncidentReport } from "./types";
+export interface IncidentReporterOptions {
+    /** e.g. `http://127.0.0.1:3024/api/station/incidents/report`. */
+    url: string;
+    /** The shared bearer the console's `reporterToken` compares against. */
+    token: string;
+    /** This service's name — the `source` of everything it reports. */
+    source: string;
+    /** A stable key for this reporter, owning the incidents it opens. */
+    checkKey: string;
+    /**
+     * Every `kind` this reporter can produce. Required, not optional: without it
+     * the console cannot tell "nothing is wrong" from "nothing was said", so a
+     * recovered service would stay red for ever. See `ReconcileOptions`.
+     */
+    kinds: readonly string[];
+    /** Produce the current set of true conditions. Called on every beat. */
+    collect: () => Promise<IncidentReport[]> | IncidentReport[];
+    /** Default 5 minutes. The console dedupes, so this is chosen for the network. */
+    intervalMs?: number;
+    fetchImpl?: typeof fetch;
+    log?: (message: string) => void;
+}
+export interface IncidentReporter {
+    /** Send one beat now. Resolves `false` on any failure — it never throws. */
+    beat: () => Promise<boolean>;
+    start: () => void;
+    stop: () => void;
+}
+export declare function createIncidentReporter(options: IncidentReporterOptions): IncidentReporter;

package/dist/server/incidents/reporter.js

@@ -0,0 +1,49 @@
+export function createIncidentReporter(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const log = options.log ?? ((m) => console.warn(`[incidents] ${m}`));
+    const intervalMs = options.intervalMs ?? 5 * 60_000;
+    let timer = null;
+    const beat = async () => {
+        try {
+            const reports = await options.collect();
+            const res = await doFetch(options.url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${options.token}`,
+                },
+                body: JSON.stringify({
+                    checkKey: options.checkKey,
+                    source: options.source,
+                    kinds: options.kinds,
+                    reports,
+                }),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!res.ok) {
+                log(`the console answered ${res.status} — ${reports.length} finding(s) not filed`);
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            log(`could not reach the console: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    };
+    return {
+        beat,
+        start() {
+            if (timer)
+                return;
+            timer = setInterval(() => void beat(), intervalMs);
+            // Never hold the process open for the sake of its own alerting.
+            timer.unref?.();
+        },
+        stop() {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+        },
+    };
+}

package/dist/server/incidents/routes.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The mountable half — ordinary Hono routes, so any app can expose its incidents
+ * without adopting another app's rpc layer (the same reasoning, and the same
+ * shape, as `server/notifications/routes.ts`).
+ *
+ * ```ts
+ * // BEFORE the session gate — the machine doors carry their own bearer:
+ * mountIncidentMachineRoutes(app, { store, notifier, reporterToken });
+ * // INSIDE it — the owner's own surface:
+ * mountIncidentOwnerRoutes(app, { store, notifier, sweep, authorize: isOwner });
+ * ```
+ *
+ * ── 🔴 Two doors, two MOUNTS, and that is the whole point ───────────────────
+ * `authorize` is the OWNER's session — it guards the list, the acks, the manual
+ * sweep and the channel test. `reporterToken` is a shared bearer and guards the
+ * two routes a DAEMON uses. They answer different questions ("is this the
+ * owner's browser?" and "is this one of my own processes?"), so a reporter can
+ * never read the incident list and a browser session can never forge an
+ * incident.
+ *
+ * They were one function first, and the console mounted it inside its session
+ * gate. Every beat from binary-server and orch came back
+ * `{"error":"unauthorized"}` — from the GATE, so nothing in this module logged
+ * anything and the console showed a perfectly calm, empty board. A reporter
+ * cannot report that it could not reach the reporting door. Two functions make
+ * the mount order a thing you have to get right rather than a thing you can
+ * forget, and they stop the opposite mistake too: registering the owner's
+ * `GET /incidents` outside the gate, where Hono's first-match would shadow the
+ * real one for ever.
+ *
+ * 🔴 `POST /report` is the ONE route that accepts incident text from off-box, so
+ * it is also the one that has to be paranoid about it: every field is length-
+ * capped and `facts` is re-validated through the store's `assertNoContent`
+ * before anything is written. A reporter is trusted to be honest, not to be
+ * correct.
+ */
+import type { Hono } from "hono";
+import type { IncidentChannel } from "./channels";
+import type { IncidentNotifier } from "./notifier";
+import { type IncidentStore } from "./store";
+import type { SweepResult } from "./checks";
+export interface IncidentRoutesOptions {
+    store: IncidentStore;
+    /** Owner-only gate for the read + write surface. Return false to 403. */
+    authorize: (c: unknown) => boolean | Promise<boolean>;
+    /** Run the checks now. Omitted on a host that runs no detectors (prod). */
+    sweep?: () => Promise<SweepResult>;
+    /** Used to announce anything a remote report opens, and to list channel health. */
+    notifier?: IncidentNotifier;
+    /** Shared bearer for `POST /report`. Omitted, the route is not mounted. */
+    reporterToken?: string;
+    /**
+     * Deliver one message as this host. Mounted as `POST /relay-email` and used
+     * by the local console, which cannot reach SES — see `channels.ts`.
+     */
+    relayEmail?: (msg: {
+        subject: string;
+        text: string;
+        html?: string;
+    }) => Promise<{
+        sent: boolean;
+        reason?: string;
+    }>;
+    /** The last sweep, for the health route. */
+    lastSweep?: () => SweepResult | null;
+    /** Send a test message down one channel, so the owner can prove it works. */
+    channelsOf?: () => readonly IncidentChannel[];
+}
+/**
+ * The OWNER's surface: the list, the acks, the health strip, the manual sweep,
+ * the channel test. Mount it INSIDE the app's session gate.
+ */
+export declare function mountIncidentOwnerRoutes(app: Hono, options: IncidentRoutesOptions, basePath?: string): void;
+/**
+ * The MACHINE doors: `POST /report`, which another service beats its findings
+ * into, and `POST /relay-email`, which a host that cannot send mail hands a
+ * message to. Both carry a shared bearer.
+ *
+ * 🔴 **Mount this BEFORE the session gate, and never call it with `authorize`
+ * expecting it to matter — it registers no route a browser should reach.**
+ * Mounting the two together inside a cookie gate is the trap this split exists
+ * to make impossible: every beat from binary-server and orch came back
+ * `{"error":"unauthorized"}` from the gate, so no log line in this module said
+ * anything was wrong and the console rendered a perfectly calm, empty board.
+ * A reporter cannot report the failure to reach the reporting door.
+ *
+ * Keeping them in one function also risked the opposite mistake — registering
+ * the owner's `GET /incidents` outside the gate, where Hono's first-match would
+ * have shadowed the real one for ever.
+ */
+export declare function mountIncidentMachineRoutes(app: Hono, options: Pick<IncidentRoutesOptions, "store" | "notifier" | "reporterToken" | "relayEmail">, basePath?: string): void;