@celilo/cli 0.22.0 → 0.24.0

package/src/services/alerting/builtin-monitors.test.ts

@@ -116,7 +116,7 @@ describe('failingKeysFromFindings', () => {
 });
 
 describe('healthCoverageFailingKeys', () => {
-  const base = { hasHealthCheckHook: true, hasEnabledMonitor: true } as const;
+  const base = { hasHealthCheckHook: true, cadence: { minutes: 15 } } as const;
 
   test('a monitored module produces no finding', () => {
     expect(healthCoverageFailingKeys([{ id: 'caddy', state: 'VERIFIED', ...base }])).toEqual([]);
@@ -124,16 +124,26 @@ describe('healthCoverageFailingKeys', () => {
 
   test('a module with no health_check hook is surfaced', () => {
     const keys = healthCoverageFailingKeys([
-      { id: 'signal', state: 'INSTALLED', hasHealthCheckHook: false, hasEnabledMonitor: false },
+      { id: 'signal', state: 'INSTALLED', hasHealthCheckHook: false, cadence: null },
     ]);
     expect(keys).toHaveLength(1);
     expect(keys[0].key).toBe('builtin:health_coverage/module:signal');
     expect(keys[0].message).toContain('no health_check hook');
   });
 
-  test('a module with a hook but no monitor is surfaced differently', () => {
+  test('an operator opt-out raises no finding — it is a decision, not a gap', () => {
+    // The finding would ask for the action they just declined, so nothing they
+    // could do would ever clear it.
+    expect(
+      healthCoverageFailingKeys([
+        { id: 'lunacycle', state: 'VERIFIED', hasHealthCheckHook: true, cadence: 'manual' },
+      ]),
+    ).toEqual([]);
+  });
+
+  test('a module with a hook but no cadence is surfaced differently', () => {
     const keys = healthCoverageFailingKeys([
-      { id: 'caddy', state: 'VERIFIED', hasHealthCheckHook: true, hasEnabledMonitor: false },
+      { id: 'caddy', state: 'VERIFIED', hasHealthCheckHook: true, cadence: null },
     ]);
     expect(keys).toHaveLength(1);
     expect(keys[0].message).toContain('nothing schedules it');
@@ -142,7 +152,7 @@ describe('healthCoverageFailingKeys', () => {
   // A coverage gap is real but is not an outage — it must never page.
   test('findings are warning severity', () => {
     const keys = healthCoverageFailingKeys([
-      { id: 'caddy', state: 'VERIFIED', hasHealthCheckHook: false, hasEnabledMonitor: false },
+      { id: 'caddy', state: 'VERIFIED', hasHealthCheckHook: false, cadence: null },
     ]);
     expect(keys[0].severity).toBe('warning');
   });
@@ -153,9 +163,7 @@ describe('healthCoverageFailingKeys', () => {
     'ignores a module in state %s',
     (state) => {
       expect(
-        healthCoverageFailingKeys([
-          { id: 'x', state, hasHealthCheckHook: false, hasEnabledMonitor: false },
-        ]),
+        healthCoverageFailingKeys([{ id: 'x', state, hasHealthCheckHook: false, cadence: null }]),
       ).toEqual([]);
     },
   );
@@ -163,8 +171,8 @@ describe('healthCoverageFailingKeys', () => {
   test('reports only the modules that are actually uncovered', () => {
     const keys = healthCoverageFailingKeys([
       { id: 'caddy', state: 'VERIFIED', ...base },
-      { id: 'signal', state: 'INSTALLED', hasHealthCheckHook: false, hasEnabledMonitor: false },
-      { id: 'forgejo', state: 'INSTALLED', hasHealthCheckHook: true, hasEnabledMonitor: false },
+      { id: 'signal', state: 'INSTALLED', hasHealthCheckHook: false, cadence: null },
+      { id: 'forgejo', state: 'INSTALLED', hasHealthCheckHook: true, cadence: null },
     ]);
     expect(keys.map((k) => k.key)).toEqual([
       'builtin:health_coverage/module:signal',

package/src/services/alerting/cadence-migration.test.ts

@@ -0,0 +1,155 @@
+/**
+ * The migrate step, and the invariant it protects.
+ *
+ * A `module_hook` monitor's stored `intervalMinutes` and `enabled` are no
+ * longer read: cadence resolves from `module_configs`. That is only safe on an
+ * existing fleet because `celilo system migrate` — which the `.deb` postinst
+ * runs on every apt upgrade — carries the diverging rows over first. Without
+ * it, the upgrade that shipped this change would silently revert every
+ * operator's hand-set cadence and resume watching modules they had disabled.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb, getDb } from '../../db/client';
+import { runMigrations } from '../../db/migrate';
+import { modules, monitors } from '../../db/schema';
+import { getModuleConfigValue, upsertModuleConfig } from '../module-config';
+import { migrateMonitorCadences } from './cadence-migration';
+import { HEALTH_CHECK_INTERVAL_CONFIG_KEY, loadModuleHealthCadences } from './health-cadence';
+
+function addModule(id: string, interval?: string): void {
+  getDb()
+    .insert(modules)
+    .values({
+      id,
+      name: id,
+      sourcePath: `/tmp/${id}`,
+      version: '1.0.0',
+      state: 'INSTALLED',
+      manifestData: {
+        id,
+        hooks: { health_check: { script: './health.ts', ...(interval ? { interval } : {}) } },
+      },
+    })
+    .run();
+}
+
+function addMonitor(target: string, intervalMinutes: number, enabled = true): void {
+  getDb()
+    .insert(monitors)
+    .values({
+      id: `monitor-${target}`,
+      kind: 'module_hook',
+      target,
+      intervalMinutes,
+      enabled,
+    })
+    .run();
+}
+
+function override(moduleId: string): string | undefined {
+  const row = getModuleConfigValue(moduleId, HEALTH_CHECK_INTERVAL_CONFIG_KEY, getDb());
+  return row === null ? undefined : String(row.value);
+}
+
+describe('migrateMonitorCadences', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-cadence-migration-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    await runMigrations(process.env.CELILO_DB_PATH);
+  });
+
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a cadence that diverges from the manifest is carried over, so the upgrade can't revert it", () => {
+    addModule('caddy', '15m');
+    addMonitor('caddy', 60); // an operator re-cadenced this to hourly
+
+    const report = migrateMonitorCadences(getDb());
+
+    expect(override('caddy')).toBe('hourly');
+    expect(report.written.get('caddy')).toBe('hourly');
+  });
+
+  test('a disabled monitor becomes manual, so a module nobody wanted watched stays unwatched', () => {
+    addModule('lunacycle', '15m');
+    addMonitor('lunacycle', 15, false);
+
+    migrateMonitorCadences(getDb());
+
+    expect(override('lunacycle')).toBe('manual');
+  });
+
+  test('a cadence matching the manifest writes nothing — it must stay free to follow corrections', () => {
+    addModule('forgejo', '15m');
+    addMonitor('forgejo', 15);
+
+    const report = migrateMonitorCadences(getDb());
+
+    expect(override('forgejo')).toBeUndefined();
+    expect(report.unchanged).toContain('forgejo');
+  });
+
+  test('an existing override is never overwritten', () => {
+    addModule('authentik', '15m');
+    addMonitor('authentik', 60);
+    upsertModuleConfig(getDb(), 'authentik', HEALTH_CHECK_INTERVAL_CONFIG_KEY, 'daily');
+
+    migrateMonitorCadences(getDb());
+
+    expect(override('authentik')).toBe('daily');
+  });
+
+  test('a second run changes nothing', () => {
+    addModule('caddy', '15m');
+    addMonitor('caddy', 60);
+
+    migrateMonitorCadences(getDb());
+    const second = migrateMonitorCadences(getDb());
+
+    expect(second.written.size).toBe(0);
+    expect(override('caddy')).toBe('hourly');
+  });
+});
+
+describe("a module_hook row's stored cadence is not consulted", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-cadence-row-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    await runMigrations(process.env.CELILO_DB_PATH);
+  });
+
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  // A future reader that reintroduces the dependency on the row fails here
+  // rather than silently regressing to write-time resolution (design.md D8).
+  test('the resolved cadence follows the manifest, not the row', () => {
+    addModule('caddy', '15m');
+    addMonitor('caddy', 9999);
+
+    expect(loadModuleHealthCadences(getDb()).get('caddy')?.cadence).toEqual({ minutes: 15 });
+  });
+
+  test('the resolved cadence follows the override, not the row', () => {
+    addModule('caddy', '15m');
+    addMonitor('caddy', 9999);
+    upsertModuleConfig(getDb(), 'caddy', HEALTH_CHECK_INTERVAL_CONFIG_KEY, '1h');
+
+    expect(loadModuleHealthCadences(getDb()).get('caddy')?.cadence).toEqual({ minutes: 60 });
+  });
+});

package/src/services/alerting/cadence-migration.ts

@@ -0,0 +1,90 @@
+/**
+ * Carrying an existing fleet's health-check cadences into `module_configs`.
+ *
+ * Not bookkeeping. Before this change a `module_hook` monitor's cadence lived
+ * on its row, seeded from the manifest at first deploy and editable only by raw
+ * SQL; after it, the row is not read and the cadence comes from the operator's
+ * override or the manifest's suggestion. So on the FIRST apt upgrade that
+ * carries this code, every module whose row diverges from its manifest — which
+ * is every module anyone ever re-cadenced by hand — would silently revert to
+ * the author's suggestion, and every module an operator deliberately disabled
+ * would start being watched again.
+ *
+ * Two steps, both idempotent, both writing only where no override exists:
+ *
+ *   1. a row whose cadence differs from what its manifest suggests gets that
+ *      cadence written as an override;
+ *   2. a disabled row gets `manual`.
+ *
+ * Runs from `celilo system migrate`, which the `.deb` postinst already invokes
+ * on every upgrade. Rolling back is safe in both directions: the rows written
+ * here are inert to older code, which reads the monitor row, and rolling
+ * forward again finds them already present.
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../../db/client';
+import { modules, monitors } from '../../db/schema';
+import type { ModuleManifest } from '../../manifest/schema';
+import { formatCadence, parseCadence } from '../cadence';
+import { getModuleConfigValue, upsertModuleConfig } from '../module-config';
+import { HEALTH_CHECK_INTERVAL_CONFIG_KEY } from './health-cadence';
+
+export interface CadenceMigrationReport {
+  /** `moduleId → written value`, for the operator-visible summary. */
+  written: Map<string, string>;
+  /** Modules left alone: an override already existed, or nothing diverged. */
+  unchanged: string[];
+}
+
+export function migrateMonitorCadences(db: DbClient): CadenceMigrationReport {
+  const report: CadenceMigrationReport = { written: new Map(), unchanged: [] };
+
+  for (const monitor of db.select().from(monitors).where(eq(monitors.kind, 'module_hook')).all()) {
+    const moduleId = monitor.target;
+
+    // An operator who has already set one has said the last word; never
+    // overwrite it, which is also what makes a second run a no-op.
+    if (getModuleConfigValue(moduleId, HEALTH_CHECK_INTERVAL_CONFIG_KEY, db)) {
+      report.unchanged.push(moduleId);
+      continue;
+    }
+
+    const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+    if (!module) {
+      // A monitor whose module is gone has nothing to carry over.
+      report.unchanged.push(moduleId);
+      continue;
+    }
+
+    // Disabled wins over cadence: an operator who stopped watching a module
+    // meant that, whatever interval the row happens to carry.
+    if (!monitor.enabled) {
+      upsertModuleConfig(db, moduleId, HEALTH_CHECK_INTERVAL_CONFIG_KEY, 'manual');
+      report.written.set(moduleId, 'manual');
+      continue;
+    }
+
+    const manifest = module.manifestData as ModuleManifest;
+    const suggested = manifest.hooks?.health_check?.interval;
+    const suggestedMinutes = suggested ? parseCadence(suggested) : null;
+    const suggestedIsSame =
+      suggestedMinutes !== null &&
+      suggestedMinutes !== 'manual' &&
+      suggestedMinutes.minutes === monitor.intervalMinutes;
+
+    if (suggestedIsSame) {
+      // The row never diverged, so read-time resolution already produces it —
+      // and writing an override here would freeze this module against every
+      // future manifest correction, which is the failure this change removes.
+      report.unchanged.push(moduleId);
+      continue;
+    }
+
+    const carried = formatCadence({ minutes: monitor.intervalMinutes });
+    upsertModuleConfig(db, moduleId, HEALTH_CHECK_INTERVAL_CONFIG_KEY, carried);
+    report.written.set(moduleId, carried);
+  }
+
+  return report;
+}

package/src/services/alerting/coverage-source.ts

@@ -6,21 +6,18 @@
  * lives here. See Rule 2.3.
  */
 
-import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
-import { modules, monitors } from '../../db/schema';
+import { modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
+import { loadModuleHealthCadences } from './health-cadence';
 import type { ModuleCoverageInput } from './health-coverage';
 
 export function loadModuleCoverage(db: DbClient): ModuleCoverageInput[] {
-  const monitored = new Set(
-    db
-      .select({ target: monitors.target })
-      .from(monitors)
-      .where(eq(monitors.enabled, true))
-      .all()
-      .map((row) => row.target),
-  );
+  // Coverage now asks the same question the sweep asks — "what is this module's
+  // effective cadence" — rather than "does an enabled monitor row exist". The
+  // row's `enabled` column is `builtin_check`-only, so reading it here would
+  // have reported a module as watched that the sweep had stopped scheduling.
+  const cadences = loadModuleHealthCadences(db);
 
   return db
     .select({ id: modules.id, state: modules.state, manifestData: modules.manifestData })
@@ -32,7 +29,7 @@ export function loadModuleCoverage(db: DbClient): ModuleCoverageInput[] {
         id: module.id,
         state: module.state,
         hasHealthCheckHook: Boolean(manifest.hooks?.health_check),
-        hasEnabledMonitor: monitored.has(module.id),
+        cadence: cadences.get(module.id)?.cadence ?? null,
       };
     });
 }

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

@@ -101,21 +101,30 @@ describe('deploy hooks', () => {
       expect(monitor.intervalMinutes).toBe(15);
     });
 
-    test('a module without an interval gets nothing', () => {
+    // The row carries severity, escalation policy and lastRunAt; WHETHER it
+    // runs comes from the module's effective cadence. So a module with the hook
+    // and no suggested interval still gets a row — otherwise an operator who
+    // sets `health_check_interval` on it would have nothing to schedule against.
+    test('a module with the hook but no interval still gets a row to carry its state', () => {
       addModule('caddy', { hooks: { health_check: { script: 'x' } } });
-      expect(ensureMonitorOnDeploy(db, 'caddy')).toBe(false);
+      expect(ensureMonitorOnDeploy(db, 'caddy')).toBe(true);
+      expect(db.select().from(monitors).all()).toHaveLength(1);
+    });
+
+    test('a module with no health_check hook at all gets nothing', () => {
+      addModule('signal', { hooks: {} });
+      expect(ensureMonitorOnDeploy(db, 'signal')).toBe(false);
       expect(db.select().from(monitors).all()).toEqual([]);
     });
 
-    // The manifest interval is a SUGGESTION. An operator's setting has to
-    // survive module upgrades.
-    test('an existing monitor is never overwritten', () => {
+    // Not because the row protects an operator's setting any more — that lives
+    // in module_configs now — but because a redeploy must not duplicate rows.
+    test('a second deploy does not create a second row', () => {
       addModule('caddy', { hooks: { health_check: { script: 'x', interval: '15m' } } });
       ensureMonitorOnDeploy(db, 'caddy');
-      db.update(monitors).set({ intervalMinutes: 60 }).run();
 
       expect(ensureMonitorOnDeploy(db, 'caddy')).toBe(false);
-      expect(db.select().from(monitors).all()[0].intervalMinutes).toBe(60);
+      expect(db.select().from(monitors).all()).toHaveLength(1);
     });
 
     test('an unknown module does not throw', () => {

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

@@ -92,10 +92,14 @@ export function modulesInDeployWindow(db: DbClient): Set<string> {
 }
 
 /**
- * Create a monitor for a freshly deployed module that asks for one.
+ * Create the monitor row for a freshly deployed module that declares a
+ * `health_check` hook.
  *
- * Never overwrites: the manifest's interval is the author's suggestion, and an
- * operator's setting must survive module upgrades.
+ * A row for any such module, not only one whose manifest suggests an interval:
+ * the row carries severity, escalation policy and `lastRunAt`, while whether it
+ * runs comes from the module's effective cadence. Without a row, an operator
+ * setting `health_check_interval` on a module whose author named none would
+ * have nothing to schedule against.
  */
 export function ensureMonitorOnDeploy(db: DbClient, moduleId: string): boolean {
   try {
@@ -103,8 +107,10 @@ export function ensureMonitorOnDeploy(db: DbClient, moduleId: string): boolean {
     if (!module) return false;
 
     const manifest = module.manifestData as ModuleManifest;
-    const interval = manifest.hooks?.health_check?.interval;
-    return ensureMonitorForModule(db, moduleId, interval) !== null;
+    const healthCheck = manifest.hooks?.health_check;
+    if (!healthCheck) return false;
+
+    return ensureMonitorForModule(db, moduleId, healthCheck.interval) !== null;
   } catch {
     return false;
   }

package/src/services/alerting/health-cadence.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../../manifest/schema';
+import { effectiveHealthCheckCadence, isScheduled } from './health-cadence';
+
+function manifestWith(interval?: string): ModuleManifest {
+  return {
+    hooks: { health_check: { script: './health.ts', ...(interval ? { interval } : {}) } },
+  } as unknown as ModuleManifest;
+}
+
+describe('effectiveHealthCheckCadence', () => {
+  test("the manifest's suggestion applies when nobody has overridden", () => {
+    expect(effectiveHealthCheckCadence(manifestWith('15m'), undefined)).toEqual({ minutes: 15 });
+  });
+
+  test('the operator override wins', () => {
+    expect(effectiveHealthCheckCadence(manifestWith('15m'), '1h')).toEqual({ minutes: 60 });
+  });
+
+  // The failure this whole change exists for: the cadence used to be seeded onto
+  // the monitor row at first deploy and never reconsulted, so an author who
+  // corrected a bad interval never reached an existing install.
+  test('a corrected suggestion reaches an un-overridden module', () => {
+    const before = effectiveHealthCheckCadence(manifestWith('1h'), undefined);
+    const afterUpgrade = effectiveHealthCheckCadence(manifestWith('15m'), undefined);
+
+    expect(before).toEqual({ minutes: 60 });
+    expect(afterUpgrade).toEqual({ minutes: 15 });
+  });
+
+  test('a corrected suggestion does NOT disturb an overridden module', () => {
+    expect(effectiveHealthCheckCadence(manifestWith('15m'), '1h')).toEqual({ minutes: 60 });
+  });
+
+  test('`manual` stops it being scheduled, and is not the same as unset', () => {
+    expect(effectiveHealthCheckCadence(manifestWith('15m'), 'manual')).toBe('manual');
+    expect(isScheduled('manual')).toBe(false);
+    expect(isScheduled(null)).toBe(false);
+    expect(isScheduled({ minutes: 15 })).toBe(true);
+  });
+
+  test('unsetting the override resumes the manifest cadence', () => {
+    // `undefined` is what the accessor sees once the row is deleted.
+    expect(effectiveHealthCheckCadence(manifestWith('15m'), undefined)).toEqual({ minutes: 15 });
+  });
+
+  test('nobody naming a cadence is null — a gap, not an opt-out', () => {
+    expect(effectiveHealthCheckCadence(manifestWith(), undefined)).toBeNull();
+  });
+
+  test('an operator can set a cadence a module never suggested', () => {
+    expect(effectiveHealthCheckCadence(manifestWith(), 'daily')).toEqual({ minutes: 1440 });
+  });
+
+  test('an unparseable override falls back to the manifest rather than going quiet', () => {
+    expect(effectiveHealthCheckCadence(manifestWith('15m'), 'fifteen')).toEqual({ minutes: 15 });
+  });
+});

package/src/services/alerting/health-cadence.ts

@@ -0,0 +1,128 @@
+/**
+ * How often celilo health-checks a module.
+ *
+ * The same shape as the backup cadence, and for the same reason. The manifest's
+ * `hooks.health_check.interval` is the author's SUGGESTION; the operator's
+ * `health_check_interval` override decides; both resolve HERE, at read time.
+ *
+ * What this replaces is worth stating, because it failed silently in both
+ * directions. The cadence used to be seeded onto the `monitors` row at first
+ * deploy and never reconsulted (`monitors.ts` returned early if a row existed),
+ * so an author who corrected a bad interval never reached an existing install,
+ * with nothing an operator could read to discover it. And since nothing ever
+ * wrote `monitors.intervalMinutes` after that insert, an operator's only way to
+ * re-cadence a module was raw SQL against `celilo.db`.
+ *
+ * `manual` means the operator has stopped watching the module. That is a
+ * decision, not a gap: it raises no health-coverage finding, because a finding
+ * asking for the action they just declined is one no action can clear.
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../../db/client';
+import { moduleConfigs, modules } from '../../db/schema';
+import type { ModuleManifest } from '../../manifest/schema';
+import { type Cadence, parseCadence } from '../cadence';
+import { getModuleConfigValue, parseStoredConfigValue } from '../module-config';
+import { findMonitor, resolveMonitorAlerts } from './monitors';
+
+/** The `module_configs` key an operator's health-check cadence is stored under. */
+export const HEALTH_CHECK_INTERVAL_CONFIG_KEY = 'health_check_interval';
+
+/**
+ * `null` means NOBODY has said how often — the module is unscheduled and that
+ * is a coverage gap. It is distinct from `'manual'`, which is an operator
+ * saying not to watch it. There is no default: an interval celilo invented
+ * would run someone's health hook on a cadence no one chose.
+ *
+ * An unparseable override falls back to the manifest, the same direction the
+ * backup cadence fails in — values are validated at SET time, so a bad one here
+ * means hand-edited state, and continuing to watch beats going quiet.
+ */
+export function effectiveHealthCheckCadence(
+  manifest: ModuleManifest,
+  override: string | undefined,
+): Cadence | null {
+  if (override !== undefined) {
+    const chosen = parseCadence(override);
+    if (chosen !== null) return chosen;
+  }
+  const suggested = manifest.hooks?.health_check?.interval;
+  if (suggested !== undefined) {
+    const parsed = parseCadence(suggested);
+    if (parsed !== null) return parsed;
+  }
+  return null;
+}
+
+/** Whether a resolved cadence schedules anything at all. */
+export function isScheduled(cadence: Cadence | null): cadence is { minutes: number } {
+  return cadence !== null && cadence !== 'manual';
+}
+
+export interface ModuleHealthCadence {
+  moduleId: string;
+  manifest: ModuleManifest;
+  state: string;
+  cadence: Cadence | null;
+}
+
+/**
+ * Every module's effective health-check cadence, in one pass.
+ *
+ * Read here rather than resolved per call site (Rule 2.3): the alerting sweep,
+ * the coverage check and `monitor list` all need the same answer, and three
+ * queries that could disagree is the shape this change exists to remove.
+ */
+export function loadModuleHealthCadences(db: DbClient): Map<string, ModuleHealthCadence> {
+  const overrides = new Map<string, string>();
+  for (const row of db
+    .select()
+    .from(moduleConfigs)
+    .where(eq(moduleConfigs.key, HEALTH_CHECK_INTERVAL_CONFIG_KEY))
+    .all()) {
+    overrides.set(row.moduleId, String(parseStoredConfigValue(row)));
+  }
+
+  const cadences = new Map<string, ModuleHealthCadence>();
+  for (const module of db.select().from(modules).all()) {
+    const manifest = module.manifestData as ModuleManifest;
+    cadences.set(module.id, {
+      moduleId: module.id,
+      manifest,
+      state: module.state,
+      cadence: effectiveHealthCheckCadence(manifest, overrides.get(module.id)),
+    });
+  }
+  return cadences;
+}
+
+/**
+ * Bring a module's watch state into line with its effective cadence.
+ *
+ * Only one direction needs doing: a module that has just become `manual` may
+ * still own live alerts from its last scheduled runs, and nothing will ever
+ * report on them again — they would sit firing forever with no operator action
+ * able to clear them. This resolves them, the way disabling a monitor always
+ * has.
+ *
+ * Idempotent, and safe to call when nothing changed. Called wherever a
+ * `health_check_interval` override is written: `module config set`/`unset`, and
+ * the migrate step.
+ */
+export function reconcileModuleWatchState(db: DbClient, moduleId: string, now: Date): number {
+  const monitor = findMonitor(db, 'module_hook', moduleId);
+  if (!monitor) return 0;
+
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) return 0;
+
+  const override = getModuleConfigValue(moduleId, HEALTH_CHECK_INTERVAL_CONFIG_KEY, db);
+  const cadence = effectiveHealthCheckCadence(
+    module.manifestData as ModuleManifest,
+    override === null ? undefined : String(override.value),
+  );
+  if (isScheduled(cadence)) return 0;
+
+  return resolveMonitorAlerts(db, monitor.id, now);
+}

package/src/services/alerting/health-coverage.ts

@@ -10,7 +10,13 @@
  *
  * Two ways that happens, and both are worth saying out loud:
  *   - the module ships no `health_check` hook, so it can never be verified;
- *   - it has one, but no enabled monitor schedules it.
+ *   - it has one, but nothing gives it a cadence, so nothing schedules it.
+ *
+ * An effective cadence of `manual` raises NOTHING. The check exists to catch
+ * blindness nobody chose; `manual` is a recorded decision, visible in `module
+ * status` and removable with one command. A finding raised by an operator's
+ * explicit opt-out asks for the action they just declined, so no action of
+ * theirs could ever clear it.
  *
  * Deliberately cheap: this reads the module roster against the monitor set and
  * contacts nothing. It is safe to run on every sweep.
@@ -19,6 +25,8 @@
  */
 
 import type { ModuleState } from '../../db/schema';
+import type { Cadence } from '../cadence';
+import { isScheduled } from './health-cadence';
 import { type FailingKey, builtinAlertKey } from './keys';
 
 export const HEALTH_COVERAGE_CHECK = 'health_coverage';
@@ -35,8 +43,11 @@ export interface ModuleCoverageInput {
   state: ModuleState;
   /** Whether the manifest declares a `health_check` hook at all. */
   hasHealthCheckHook: boolean;
-  /** Whether an ENABLED monitor schedules that hook. */
-  hasEnabledMonitor: boolean;
+  /**
+   * The module's effective health-check cadence: `null` when nobody has named
+   * one (a gap), `'manual'` when the operator opted out (a decision).
+   */
+  cadence: Cadence | null;
 }
 
 /**
@@ -65,15 +76,14 @@ export function healthCoverageFailingKeys(modules: ModuleCoverageInput[]): Faili
       continue;
     }
 
-    if (!module.hasEnabledMonitor) {
+    if (module.cadence === 'manual') continue;
+
+    if (!isScheduled(module.cadence)) {
       failing.push({
         key,
         severity: 'warning',
         message: `${module.id} has a health_check hook but nothing schedules it`,
-        details:
-          'The module can be verified on demand but is not being watched.\n' +
-          'Create a monitor for it, or set hooks.health_check.interval in the\n' +
-          'module manifest so one is created on deploy.',
+        details: `The module can be verified on demand but is not being watched.\nGive it a cadence:  celilo module config set ${module.id} health_check_interval 15m\nor set hooks.health_check.interval in the module manifest.`,
       });
     }
   }