@celilo/cli 0.13.3 → 0.14.0

package/src/services/alerting/deploy-hooks.ts

@@ -0,0 +1,111 @@
+/**
+ * What a deploy does to alerting.
+ *
+ * Two things, both of which have to happen around the deploy rather than
+ * inside it:
+ *
+ *   1. A deploy is noisy. Restarting a service fails its own health check, so
+ *      a deploy without suppression pages the operator about the deploy they
+ *      are personally running. The window opens at start and closes at the
+ *      end, INCLUDING on failure — a failed deploy that left the window open
+ *      would silence that module forever, which is the worst possible way to
+ *      get this wrong.
+ *
+ *   2. A module declaring `hooks.health_check.interval` gets a monitor on
+ *      first deploy, so watching a module is the default rather than something
+ *      to remember.
+ *
+ * Everything here is best-effort: alerting bookkeeping must never be able to
+ * fail a deploy. A missing window means noise; a failed deploy means an outage.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { and, eq, isNull } from 'drizzle-orm';
+import type { DbClient } from '../../db/client';
+import { modules, suppressionWindows } from '../../db/schema';
+import type { ModuleManifest } from '../../manifest/schema';
+import { ensureMonitorForModule } from './monitors';
+
+/** Open a deploy suppression window for a module. Returns its id, or null. */
+export function openDeployWindow(db: DbClient, moduleId: string, now: Date): string | null {
+  try {
+    // Reuse an already-open window rather than stacking them: a redeploy
+    // during a deploy should not need two closes to become audible again.
+    const existing = db
+      .select()
+      .from(suppressionWindows)
+      .where(and(eq(suppressionWindows.scopeModuleId, moduleId), isNull(suppressionWindows.endsAt)))
+      .get();
+    if (existing) return existing.id;
+
+    const id = randomUUID();
+    db.insert(suppressionWindows)
+      .values({ id, source: 'deploy', scopeModuleId: moduleId, startedAt: now })
+      .run();
+    return id;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Close every open deploy window for a module.
+ *
+ * Called on success AND failure. Closing by module rather than by id means a
+ * crashed deploy that never returned its window id still gets cleaned up on
+ * the next attempt.
+ */
+export function closeDeployWindows(db: DbClient, moduleId: string, now: Date): number {
+  try {
+    const open = db
+      .select({ id: suppressionWindows.id })
+      .from(suppressionWindows)
+      .where(and(eq(suppressionWindows.scopeModuleId, moduleId), isNull(suppressionWindows.endsAt)))
+      .all();
+
+    for (const window of open) {
+      db.update(suppressionWindows)
+        .set({ endsAt: now })
+        .where(eq(suppressionWindows.id, window.id))
+        .run();
+    }
+    return open.length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Modules currently inside an open deploy window. */
+export function modulesInDeployWindow(db: DbClient): Set<string> {
+  try {
+    return new Set(
+      db
+        .select({ moduleId: suppressionWindows.scopeModuleId })
+        .from(suppressionWindows)
+        .where(isNull(suppressionWindows.endsAt))
+        .all()
+        .map((row) => row.moduleId),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Create a monitor for a freshly deployed module that asks for one.
+ *
+ * Never overwrites: the manifest's interval is the author's suggestion, and an
+ * operator's setting must survive module upgrades.
+ */
+export function ensureMonitorOnDeploy(db: DbClient, moduleId: string): boolean {
+  try {
+    const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+    if (!module) return false;
+
+    const manifest = module.manifestData as ModuleManifest;
+    const interval = manifest.hooks?.health_check?.interval;
+    return ensureMonitorForModule(db, moduleId, interval) !== null;
+  } catch {
+    return false;
+  }
+}

package/src/services/alerting/escalation.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  type EscalatableAlert,
+  type EscalationInput,
+  type EscalationStep,
+  type RouteForEscalation,
+  decideEscalation,
+  meetsSeverityFloor,
+} from './escalation';
+
+const START = new Date('2026-07-28T03:00:00Z');
+const at = (minutes: number) => new Date(START.getTime() + minutes * 60_000);
+
+/** peter-signal at 0m, wife-signal at 10m, peter-email at 30m. */
+const STEPS: EscalationStep[] = [
+  { stepIndex: 0, routeId: 'peter-signal', delayMinutes: 0 },
+  { stepIndex: 1, routeId: 'wife-signal', delayMinutes: 10 },
+  { stepIndex: 2, routeId: 'peter-email', delayMinutes: 30 },
+];
+
+const ROUTES = new Map<string, RouteForEscalation>([
+  ['peter-signal', { id: 'peter-signal', severityFloor: 'warning', enabled: true }],
+  ['wife-signal', { id: 'wife-signal', severityFloor: 'critical', enabled: true }],
+  ['peter-email', { id: 'peter-email', severityFloor: 'warning', enabled: true }],
+]);
+
+function alert(over: Partial<EscalatableAlert> = {}): EscalatableAlert {
+  return {
+    id: 'a1',
+    severity: 'critical',
+    escalationStep: 0,
+    acked: false,
+    resolved: false,
+    suppressed: false,
+    awaitingConfirmation: false,
+    silencedUntil: null,
+    graceUntil: START,
+    escalationStartedAt: START,
+    ...over,
+  };
+}
+
+const decide = (over: Partial<EscalationInput> = {}) =>
+  decideEscalation({ alert: alert(), steps: STEPS, routes: ROUTES, now: START, ...over });
+
+describe('meetsSeverityFloor', () => {
+  test('critical clears a warning floor', () => {
+    expect(meetsSeverityFloor('critical', 'warning')).toBe(true);
+  });
+
+  test('warning does not clear a critical floor', () => {
+    expect(meetsSeverityFloor('warning', 'critical')).toBe(false);
+  });
+
+  test('equal severities clear', () => {
+    expect(meetsSeverityFloor('critical', 'critical')).toBe(true);
+  });
+});
+
+describe('the happy path', () => {
+  test('step 0 notifies the primary immediately', () => {
+    expect(decide()).toEqual({
+      type: 'notify',
+      routeId: 'peter-signal',
+      stepIndex: 0,
+      nextStepDueAt: at(10),
+    });
+  });
+
+  test('step 1 is not due before its delay elapses', () => {
+    expect(decide({ alert: alert({ escalationStep: 1 }), now: at(9) })).toEqual({
+      type: 'skip',
+      reason: 'not_yet_due',
+    });
+  });
+
+  test('unacked at 10m escalates to the secondary', () => {
+    expect(decide({ alert: alert({ escalationStep: 1 }), now: at(10) })).toEqual({
+      type: 'notify',
+      routeId: 'wife-signal',
+      stepIndex: 1,
+      nextStepDueAt: at(30),
+    });
+  });
+
+  test('the final step has no following step', () => {
+    const decision = decide({ alert: alert({ escalationStep: 2 }), now: at(30) });
+    expect(decision).toEqual({
+      type: 'notify',
+      routeId: 'peter-email',
+      stepIndex: 2,
+      nextStepDueAt: null,
+    });
+  });
+
+  test('past the last step the policy is exhausted', () => {
+    expect(decide({ alert: alert({ escalationStep: 3 }), now: at(60) })).toEqual({
+      type: 'skip',
+      reason: 'policy_exhausted',
+    });
+  });
+});
+
+describe('reasons to stay silent', () => {
+  // The alert self-resolved at minute four. Nobody further should hear about it.
+  test.each([
+    ['resolved', { resolved: true }],
+    ['acked', { acked: true }],
+    ['suppressed', { suppressed: true }],
+    ['awaiting_confirmation', { awaitingConfirmation: true }],
+  ] as const)('skips when %s', (reason, over) => {
+    expect(decide({ alert: alert({ escalationStep: 1, ...over }), now: at(10) })).toEqual({
+      type: 'skip',
+      reason,
+    });
+  });
+
+  test('skips while silenced, and resumes once the silence expires', () => {
+    const silenced = alert({ escalationStep: 1, silencedUntil: at(20) });
+    expect(decide({ alert: silenced, now: at(10) })).toEqual({ type: 'skip', reason: 'silenced' });
+    expect(decide({ alert: silenced, now: at(21) })).toMatchObject({ type: 'notify' });
+  });
+
+  // A check that fails once and passes 30s later must never page.
+  test('skips inside the grace window', () => {
+    const pending = alert({ graceUntil: at(1) });
+    expect(decide({ alert: pending, now: START })).toEqual({
+      type: 'skip',
+      reason: 'within_grace',
+    });
+  });
+
+  test('notifies once the grace window elapses', () => {
+    const pending = alert({ graceUntil: at(1) });
+    expect(decide({ alert: pending, now: at(2) })).toMatchObject({ type: 'notify' });
+  });
+});
+
+describe('severity floors', () => {
+  // wife-signal takes critical only. A warning must not burn ten minutes of
+  // silence waiting to skip her — it should fall through to the next route.
+  test('a filtered route is passed over immediately, not waited on', () => {
+    const warn = alert({ severity: 'warning', escalationStep: 1 });
+    expect(decide({ alert: warn, now: at(30) })).toEqual({
+      type: 'notify',
+      routeId: 'peter-email',
+      stepIndex: 2,
+      nextStepDueAt: null,
+    });
+  });
+
+  test('a disabled route is passed over the same way', () => {
+    const routes = new Map(ROUTES);
+    routes.set('wife-signal', { id: 'wife-signal', severityFloor: 'warning', enabled: false });
+    expect(decide({ alert: alert({ escalationStep: 1 }), routes, now: at(30) })).toMatchObject({
+      routeId: 'peter-email',
+    });
+  });
+
+  // Distinct from policy_exhausted: the steps existed, nobody was eligible.
+  test('reports no_eligible_route when every remaining route is filtered out', () => {
+    const routes = new Map<string, RouteForEscalation>([
+      ['peter-signal', { id: 'peter-signal', severityFloor: 'critical', enabled: true }],
+      ['wife-signal', { id: 'wife-signal', severityFloor: 'critical', enabled: true }],
+      ['peter-email', { id: 'peter-email', severityFloor: 'critical', enabled: true }],
+    ]);
+    expect(decide({ alert: alert({ severity: 'warning' }), routes, now: at(60) })).toEqual({
+      type: 'skip',
+      reason: 'no_eligible_route',
+    });
+  });
+
+  // A route deleted out from under a policy must degrade, not crash — and it
+  // reports no_eligible_route, since the step existed but had nobody to reach.
+  test('an unknown route id is passed over rather than throwing', () => {
+    const steps: EscalationStep[] = [{ stepIndex: 0, routeId: 'deleted', delayMinutes: 0 }];
+    expect(decide({ steps, now: at(5) })).toEqual({ type: 'skip', reason: 'no_eligible_route' });
+  });
+});
+
+describe('the escalation clock restarts after suppression', () => {
+  // Suppressed at fire, un-suppressed 40 minutes later. If the clock still ran
+  // from firstFiredAt, all three steps would fire at once — exactly the storm
+  // suppression exists to prevent.
+  test('a long suppression does not fire every step at once', () => {
+    const unsuppressed = alert({ escalationStartedAt: at(40), graceUntil: at(40) });
+    expect(decide({ alert: unsuppressed, now: at(41) })).toEqual({
+      type: 'notify',
+      routeId: 'peter-signal',
+      stepIndex: 0,
+      nextStepDueAt: at(50),
+    });
+  });
+
+  test('the secondary still waits its full delay from the restart', () => {
+    const unsuppressed = alert({
+      escalationStep: 1,
+      escalationStartedAt: at(40),
+      graceUntil: at(40),
+    });
+    expect(decide({ alert: unsuppressed, now: at(45) })).toEqual({
+      type: 'skip',
+      reason: 'not_yet_due',
+    });
+    expect(decide({ alert: unsuppressed, now: at(50) })).toMatchObject({ routeId: 'wife-signal' });
+  });
+});

package/src/services/alerting/escalation.ts

@@ -0,0 +1,151 @@
+/**
+ * Escalation — deciding whether an alert notifies anyone right now, and who.
+ *
+ * Driven by a sweep on the event bus's existing `timer.tick.5m`. The sweep
+ * re-evaluates current state before acting rather than trusting what was true
+ * when the step was scheduled: an alert that resolved four minutes ago must not
+ * wake the secondary at minute ten.
+ *
+ * Every reason to stay silent is enumerated as an explicit `skip` reason rather
+ * than an early `return null`, because "why didn't I get paged?" is the
+ * question an alerting system most needs to be able to answer.
+ *
+ * See openspec/changes/add-alerting/design.md D2, S1, S2, S3.
+ */
+
+import type { AlertSeverity } from '../../db/schema';
+
+const MINUTE_MS = 60_000;
+
+/** Only `critical` pages; `warning` is recorded and never escalates. */
+const SEVERITY_RANK: Record<AlertSeverity, number> = { warning: 0, critical: 1 };
+
+export function meetsSeverityFloor(severity: AlertSeverity, floor: AlertSeverity): boolean {
+  return SEVERITY_RANK[severity] >= SEVERITY_RANK[floor];
+}
+
+export interface EscalationStep {
+  stepIndex: number;
+  routeId: string;
+  /** Minutes after escalation begins — not after the previous step. */
+  delayMinutes: number;
+}
+
+export interface RouteForEscalation {
+  id: string;
+  severityFloor: AlertSeverity;
+  enabled: boolean;
+}
+
+export interface EscalatableAlert {
+  id: string;
+  severity: AlertSeverity;
+  /** Index of the NEXT step to run. */
+  escalationStep: number;
+  acked: boolean;
+  resolved: boolean;
+  /** Currently explained by an ancestor or a deploy window. */
+  suppressed: boolean;
+  /** True between un-suppression and the next successful run. */
+  awaitingConfirmation: boolean;
+  silencedUntil: Date | null;
+  /** Notification is withheld until this instant. */
+  graceUntil: Date;
+  /**
+   * Escalation clock origin. Set to the un-suppression moment when suppression
+   * lifts, so leaving a maintenance window does not instantly fire every step
+   * whose delay has nominally elapsed since the alert first fired.
+   */
+  escalationStartedAt: Date;
+}
+
+export type SkipReason =
+  | 'resolved'
+  | 'acked'
+  | 'suppressed'
+  | 'awaiting_confirmation'
+  | 'silenced'
+  | 'within_grace'
+  | 'not_yet_due'
+  | 'policy_exhausted'
+  | 'no_eligible_route';
+
+export type EscalationDecision =
+  | { type: 'skip'; reason: SkipReason }
+  | { type: 'notify'; routeId: string; stepIndex: number; nextStepDueAt: Date | null };
+
+export interface EscalationInput {
+  alert: EscalatableAlert;
+  steps: EscalationStep[];
+  routes: Map<string, RouteForEscalation>;
+  now: Date;
+}
+
+/**
+ * Decide what escalation should do for one alert at `now`.
+ *
+ * Returns the route to notify and when the following step falls due, or the
+ * reason nothing happens.
+ */
+export function decideEscalation(input: EscalationInput): EscalationDecision {
+  const { alert, now } = input;
+
+  // State re-check (S2). Order is deliberate: the cheapest and most decisive
+  // conditions first, so the reason reported is the most informative one.
+  if (alert.resolved) return { type: 'skip', reason: 'resolved' };
+  if (alert.acked) return { type: 'skip', reason: 'acked' };
+  if (alert.suppressed) return { type: 'skip', reason: 'suppressed' };
+  if (alert.awaitingConfirmation) return { type: 'skip', reason: 'awaiting_confirmation' };
+  if (alert.silencedUntil && alert.silencedUntil > now) {
+    return { type: 'skip', reason: 'silenced' };
+  }
+
+  // The grace window (S1): a failure that clears before it elapses never
+  // notifies at all, which is what stops a flapping check from paging.
+  if (alert.graceUntil > now) return { type: 'skip', reason: 'within_grace' };
+
+  const ordered = [...input.steps].sort((a, b) => a.stepIndex - b.stepIndex);
+
+  // Walk forward from the current step. A route filtered out by its severity
+  // floor is passed over immediately rather than costing its delay in silence —
+  // waiting ten minutes to skip somebody is ten minutes nobody is told.
+  for (let i = alert.escalationStep; i < ordered.length; i++) {
+    const step = ordered[i];
+    const dueAt = new Date(alert.escalationStartedAt.getTime() + step.delayMinutes * MINUTE_MS);
+    if (dueAt > now) return { type: 'skip', reason: 'not_yet_due' };
+
+    const route = input.routes.get(step.routeId);
+    if (!route?.enabled) continue;
+    if (!meetsSeverityFloor(alert.severity, route.severityFloor)) continue;
+
+    const next = ordered[i + 1];
+    return {
+      type: 'notify',
+      routeId: route.id,
+      stepIndex: step.stepIndex,
+      nextStepDueAt: next
+        ? new Date(alert.escalationStartedAt.getTime() + next.delayMinutes * MINUTE_MS)
+        : null,
+    };
+  }
+
+  // Fell off the end. Distinguish "the policy had no steps left" from "every
+  // remaining step was filtered out" — they look identical to the alert but
+  // mean very different things to whoever configured the policy.
+  const hadRemainingSteps = alert.escalationStep < ordered.length;
+  return {
+    type: 'skip',
+    reason: hadRemainingSteps ? 'no_eligible_route' : 'policy_exhausted',
+  };
+}
+
+/**
+ * Where the escalation clock restarts when suppression lifts.
+ *
+ * Not `firstFiredAt`: an alert suppressed for forty minutes under a policy with
+ * steps at 0/10/30 would otherwise fire all three at once the instant the
+ * ancestor resolves, which is precisely the storm suppression exists to avoid.
+ */
+export function escalationOriginAfterUnsuppression(unsuppressedAt: Date): Date {
+  return unsuppressedAt;
+}

package/src/services/alerting/format.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, test } from 'bun:test';
+import type { Alert } from '../../db/schema';
+import {
+  alertDetail,
+  humaniseAge,
+  humaniseRemaining,
+  moduleHealthCell,
+  renderAlertTable,
+  sortAlertRows,
+  toAlertRow,
+} from './format';
+
+const NOW = new Date('2026-07-28T12:00:00Z');
+const ago = (minutes: number) => new Date(NOW.getTime() - minutes * 60_000);
+const ahead = (minutes: number) => new Date(NOW.getTime() + minutes * 60_000);
+
+function alert(over: Partial<Alert> = {}): Alert {
+  return {
+    id: 'a1',
+    key: 'module:caddy/check:disk-space',
+    activeKey: 'module:caddy/check:disk-space',
+    monitorId: 'mon-1',
+    state: 'firing',
+    severity: 'critical',
+    firstFiredAt: ago(30),
+    lastSeenAt: NOW,
+    graceUntil: ago(29),
+    suppressedByAlertId: null,
+    suppressedByWindowId: null,
+    unsuppressedAt: null,
+    awaitingConfirmation: false,
+    ackedBy: null,
+    ackedAt: null,
+    silencedUntil: null,
+    escalationStep: 0,
+    nextEscalationAt: null,
+    escalationPolicyId: null,
+    message: '/var 94% used',
+    details: null,
+    resolvedAt: null,
+    ...over,
+  } as Alert;
+}
+
+describe('humaniseAge', () => {
+  test.each([
+    [0, '0s'],
+    [0.5, '30s'],
+    [5, '5m'],
+    [90, '1h'],
+    [60 * 26, '1d'],
+  ])('%p minutes → %p', (minutes, expected) => {
+    expect(humaniseAge(ago(minutes), NOW)).toBe(expected);
+  });
+
+  test('a future instant clamps to zero rather than going negative', () => {
+    expect(humaniseAge(ahead(5), NOW)).toBe('0s');
+  });
+});
+
+describe('humaniseRemaining — rounds up so a countdown never overstates', () => {
+  test.each([
+    [90, '2h'],
+    [59, '59m'],
+    [61, '2h'],
+    [0, '0s'],
+  ])('%p minutes remaining → %p', (minutes, expected) => {
+    expect(humaniseRemaining(ahead(minutes), NOW)).toBe(expected);
+  });
+
+  test('a past instant clamps to zero', () => {
+    expect(humaniseRemaining(ago(5), NOW)).toBe('0s');
+  });
+});
+
+describe('alertDetail — says the most actionable thing', () => {
+  test('an acked alert says so, not its message', () => {
+    expect(alertDetail(alert({ state: 'acked' }), NOW)).toBe('acked');
+  });
+
+  test('a suppressed alert explains that something upstream covers it', () => {
+    expect(alertDetail(alert({ state: 'suppressed', suppressedByAlertId: 'x' }), NOW)).toBe(
+      'explained by an upstream alert',
+    );
+  });
+
+  test('a deploy window is named specifically, not lumped in', () => {
+    expect(alertDetail(alert({ state: 'suppressed', suppressedByWindowId: 'w' }), NOW)).toBe(
+      'deploy in progress',
+    );
+  });
+
+  // Rounded UP: with 1h30m left, "1h" would read as nearly over.
+  test('a silenced alert reports how long is left, rounded up', () => {
+    expect(alertDetail(alert({ silencedUntil: ahead(90) }), NOW)).toBe('silenced for 2h');
+  });
+
+  test('a silence just short of its full duration does not read as an hour less', () => {
+    expect(alertDetail(alert({ silencedUntil: ahead(119) }), NOW)).toBe('silenced for 2h');
+  });
+
+  test('an expired silence no longer claims to be silenced', () => {
+    expect(alertDetail(alert({ silencedUntil: ago(5) }), NOW)).toBe('/var 94% used');
+  });
+
+  test('an alert awaiting confirmation says so', () => {
+    expect(alertDetail(alert({ awaitingConfirmation: true }), NOW)).toBe('awaiting confirmation');
+  });
+
+  test('a pending alert inside its grace window says so', () => {
+    expect(alertDetail(alert({ state: 'pending', graceUntil: ahead(1) }), NOW)).toBe(
+      'within grace window',
+    );
+  });
+
+  test('otherwise the alert message earns the column', () => {
+    expect(alertDetail(alert(), NOW)).toBe('/var 94% used');
+  });
+});
+
+describe('sortAlertRows — most actionable first', () => {
+  test('firing outranks pending, acked, and suppressed', () => {
+    const rows = [
+      toAlertRow(alert({ key: 'k-suppressed', state: 'suppressed' }), NOW),
+      toAlertRow(alert({ key: 'k-acked', state: 'acked' }), NOW),
+      toAlertRow(alert({ key: 'k-pending', state: 'pending' }), NOW),
+      toAlertRow(alert({ key: 'k-firing', state: 'firing' }), NOW),
+    ];
+    expect(sortAlertRows(rows).map((r) => r.key)).toEqual([
+      'k-firing',
+      'k-pending',
+      'k-acked',
+      'k-suppressed',
+    ]);
+  });
+});
+
+describe('renderAlertTable', () => {
+  test('an empty list says so rather than printing bare headers', () => {
+    expect(renderAlertTable([])).toBe('No alerts.');
+  });
+
+  test('columns line up and the header is present', () => {
+    const shortKey = 'module:a';
+    const longKey = 'module:a-much-longer-module-name';
+    const table = renderAlertTable([
+      toAlertRow(alert({ key: shortKey }), NOW),
+      toAlertRow(alert({ key: longKey, state: 'acked' }), NOW),
+    ]);
+    const lines = table.split('\n');
+    expect(lines[0]).toContain('KEY');
+    expect(lines[0]).toContain('DETAIL');
+
+    // The second column begins at the widest key plus the two-space gutter,
+    // on every line including the header.
+    const offset = longKey.length + 2;
+    for (const line of lines) {
+      expect(line[offset]).not.toBe(' ');
+    }
+  });
+
+  test('no trailing whitespace on any line', () => {
+    const table = renderAlertTable([toAlertRow(alert(), NOW)]);
+    for (const line of table.split('\n')) {
+      expect(line).toBe(line.trimEnd());
+    }
+  });
+});
+
+describe('moduleHealthCell', () => {
+  // The lie this column exists to stop telling.
+  test('an unmonitored module reads as "not observed", never "ok"', () => {
+    const cell = moduleHealthCell({ monitored: false, firingCount: 0, suppressed: false });
+    expect(cell).toBe('not observed');
+    expect(cell).not.toBe('ok');
+  });
+
+  test('a healthy monitored module reads ok', () => {
+    expect(moduleHealthCell({ monitored: true, firingCount: 0, suppressed: false })).toBe('ok');
+  });
+
+  test('a failing module reports how many alerts', () => {
+    expect(moduleHealthCell({ monitored: true, firingCount: 2, suppressed: false })).toBe(
+      '2 firing',
+    );
+  });
+
+  test('suppressed outranks the firing count — it is why you should not chase it', () => {
+    expect(moduleHealthCell({ monitored: true, firingCount: 3, suppressed: true })).toBe(
+      'suppressed',
+    );
+  });
+});