@celilo/cli 0.23.0 → 0.24.1

package/src/hooks/types.ts

@@ -120,7 +120,8 @@ export type HookName =
   | 'on_backup_analyze'
   | 'on_restore'
   | 'on_system_event'
-  | 'refresh_registrations';
+  | 'refresh_registrations'
+  | 'reassert_dhcp_dns';
 
 /**
  * Hook manifest section - maps hook names to definitions

package/src/manifest/contracts/v1.ts

@@ -194,6 +194,22 @@ export const V1_HOOKS: ContractHooks = {
     },
     outputs: {},
   },
+  /**
+   * Periodic re-assertion of the resolver a dns_internal provider hands
+   * out over DHCP (celilo#739). Some routers regenerate that value from
+   * their own upstream list on a timer and silently undo what on_install
+   * set — the write succeeds and reads back correct, so only a client
+   * renewing later ever sees the wrong resolver. No framework-injected
+   * inputs: the hook derives the address it wants from its own config and
+   * systems, and reads the device before writing. Typically driven by a
+   * `timer.tick.1m` subscription, because the tick interval is the
+   * worst-case window in which a renewing client can be handed the wrong
+   * resolver for a full lease.
+   */
+  reassert_dhcp_dns: {
+    inputs: {},
+    outputs: {},
+  },
   /**
    * Build-bus upstream publish hook. The executor passes the
    * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,

package/src/manifest/schema.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod';
 import { NETWORK_ZONES } from '../db/schema';
+import {
+  BACKUP_CADENCE_FLOOR_MINUTES,
+  MONITOR_INTERVAL_FLOOR_MINUTES,
+  cadenceSchema,
+} from '../services/cadence';
 import { SUPPORTED_CONTRACT_VERSIONS } from './contracts';
 
 /**
@@ -273,73 +278,26 @@ export const LifecycleHookSchema = z.object({
   timeout: z.number().positive().optional(),
 });
 
-/**
- * Floor for a module's suggested `health_check` interval.
- *
- * The monitor sweep rides the event bus's fixed `timer.tick.5m`
- * (packages/event-bus/src/timer.ts), so an interval below five minutes
- * cannot be honoured — it would silently round up. Rejecting it at manifest
- * validation is better than accepting a promise celilo can't keep.
- */
-export const MONITOR_INTERVAL_FLOOR_MINUTES = 5;
-
-const DURATION_PATTERN = /^(\d+)(m|h|d)$/;
-
-/**
- * Parse a duration string (`15m`, `1h`, `1d`) to whole minutes.
- * Returns null when the string is not a well-formed duration.
- */
-export function parseIntervalMinutes(value: string): number | null {
-  const match = DURATION_PATTERN.exec(value);
-  if (!match) return null;
-  const amount = Number.parseInt(match[1], 10);
-  if (!Number.isFinite(amount) || amount <= 0) return null;
-  const unit = match[2];
-  if (unit === 'm') return amount;
-  if (unit === 'h') return amount * 60;
-  return amount * 60 * 24;
-}
-
 /**
  * `health_check` accepts everything a lifecycle hook does, plus an optional
  * `interval` — the module author's SUGGESTED monitoring cadence.
  *
- * It is only a suggestion: the operator's `monitors` row is the effective
- * schedule and survives module upgrades (openspec/changes/add-alerting
- * design D3). A module that omits it is simply not monitored until an
- * operator creates a monitor by hand.
+ * It is only a suggestion: the operator's `health_check_interval` override
+ * decides, and resolution happens at read time so a corrected suggestion
+ * reaches every install that has not overridden
+ * ([[services/alerting/health-cadence.ts]]). A module that omits it is not
+ * monitored until someone names a cadence.
+ *
+ * The same spellings as every other cadence in celilo — a named period, a
+ * duration, or `manual` — with the floor derived from the alerting sweep's
+ * tick.
  */
 export const HealthCheckHookSchema = LifecycleHookSchema.extend({
-  // `.regex` duplicates the well-formedness half of the `superRefine` below on
-  // purpose: only `.regex` survives the export to JSON Schema, and that export is
-  // what validates `modules/*/manifest.yml` in the editor. The 5-minute floor
-  // cannot be expressed in JSON Schema at all, so it stays a refinement — which
-  // is why both exist rather than one. Keeping them in sync is the point of
-  // sharing DURATION_PATTERN.
-  interval: z
-    .string()
-    .regex(DURATION_PATTERN)
-    .optional()
-    .describe(
-      'Suggested monitoring cadence, e.g. "15m", "1h", "1d". Must be 5m or longer — the monitor sweep runs on a 5-minute grid.',
-    )
-    .superRefine((value, ctx) => {
-      if (value === undefined) return;
-      const minutes = parseIntervalMinutes(value);
-      if (minutes === null) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `Invalid health_check interval "${value}". Use a duration like "15m", "1h", or "1d".`,
-        });
-        return;
-      }
-      if (minutes < MONITOR_INTERVAL_FLOOR_MINUTES) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `health_check interval "${value}" is below the ${MONITOR_INTERVAL_FLOOR_MINUTES}m floor — the monitor sweep runs on a ${MONITOR_INTERVAL_FLOOR_MINUTES}-minute grid and cannot run it more often. Use "${MONITOR_INTERVAL_FLOOR_MINUTES}m" or longer.`,
-        });
-      }
-    }),
+  interval: cadenceSchema({
+    floorMinutes: MONITOR_INTERVAL_FLOOR_MINUTES,
+    description:
+      'Suggested monitoring cadence: a duration like "15m", "1h" or "1d", a named period (hourly, daily, weekly, monthly), or "manual". The monitor sweep runs on a 5-minute grid, so nothing finer than 5m can be served.',
+  }).optional(),
 });
 
 /**
@@ -639,6 +597,16 @@ export const ModuleManifestSchema = z
          * designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B3).
          */
         refresh_registrations: LifecycleHookSchema.optional(),
+        /**
+         * Periodic re-assertion of the resolver a dns_internal provider
+         * hands out over DHCP. Some routers regenerate that value from
+         * their own upstream list on a timer, silently undoing what
+         * on_install set. The hook reads the device before writing, so a
+         * quiet minute costs one query. Subscribe it to `timer.tick.1m` —
+         * the tick interval IS the worst-case window in which a renewing
+         * client can be handed the wrong resolver. See celilo#739.
+         */
+        reassert_dhcp_dns: LifecycleHookSchema.optional(),
         /**
          * Build-bus upstream publish hooks. Array (a module can react
          * to multiple upstream packages with different actions). See
@@ -694,10 +662,17 @@ export const ModuleManifestSchema = z
 
     backup: z
       .object({
-        // Absent means `daily`. Opting out of backups entirely is a real
-        // decision and takes an explicit `manual` — see
-        // [[services/backup-schedule.ts]].
-        schedule: z.enum(['hourly', 'daily', 'weekly', 'monthly', 'manual']).default('daily'),
+        // The author's SUGGESTED cadence. The operator's `backup_schedule`
+        // override wins and is resolved at read time — see
+        // [[services/backup-schedule.ts]]. Absent from both means `daily`;
+        // opting out of backups entirely is a real decision and takes an
+        // explicit `manual`.
+        //
+        schedule: cadenceSchema({
+          floorMinutes: BACKUP_CADENCE_FLOOR_MINUTES,
+          description:
+            'Suggested backup cadence: a named period (hourly, daily, weekly, monthly), a duration like "6h", or "manual" to opt out. The backup sweep runs hourly, so nothing finer than 1h can be served.',
+        }).default('daily'),
         retention: z
           .object({
             count: z.number().int().positive().default(7),

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 });
+  });
+});