@celilo/cli 0.23.0 → 0.24.0

package/src/hooks/capability-loader.ts

@@ -154,6 +154,32 @@ export async function resolveFirewallNatIp(db: DbClient): Promise<string | undef
   return undefined;
 }
 
+/**
+ * The addresses of every machine a `firewall` capability provider manages.
+ *
+ * This is the authoritative answer to "which machines are firewalls", and it has
+ * to be: a machine's stored `role` is decided by `machine add`, from the zones
+ * declared AT THAT MOMENT. The normal order is `machine add` and THEN deploy
+ * iptables, whose `on_install` writes the zone subnets — so the firewall is
+ * recorded as a plain host and stays that way. A firewall provider naming an IP
+ * is a statement, not an inference from a snapshot.
+ */
+export async function listFirewallIps(db: DbClient): Promise<string[]> {
+  const providers = db
+    .select()
+    .from(capabilities)
+    .where(eq(capabilities.capabilityName, 'firewall'))
+    .all();
+  const ips: string[] = [];
+  for (const provider of providers) {
+    const config = await loadModuleConfig(provider.moduleId, db);
+    if (typeof config.firewall_ip === 'string' && config.firewall_ip) {
+      ips.push(config.firewall_ip);
+    }
+  }
+  return ips;
+}
+
 /**
  * Caddy's zone-routable IP — its own DMZ ingress address (`target_ip`, the same
  * value public_web exposes as `dmz_ip`). This is the in-zone split-horizon
@@ -606,6 +632,9 @@ function buildCapabilityInterface(
         undefined, // no upstream — the chain path handles that
         undefined, // logger is applied by wrapWithLogging at the loader site
         trustedSourceStore,
+        // LIVE, for the same reason as the chain path: a declaration written
+        // during this hook run must be visible to the converge that follows it.
+        zones ? { list: zones.declaredNetworks } : undefined,
       );
       return stampProvider(iface, providerModuleId);
     }
@@ -707,6 +736,18 @@ interface FirewallZones {
   trustedSubnets: string[];
   /** celilo's control-plane network, as a DESTINATION for trusted sources. */
   controlPlaneSubnet?: string;
+  /**
+   * Every zone with a declared subnet, WITH its name — the input to interface
+   * classification. Excludes `external`, which is a residual rather than a
+   * subnet (design D1, amended).
+   */
+  /**
+   * A LIVE read, not a snapshot. Everything else here is captured when the
+   * capability is built — before any hook runs — and for declarations that is
+   * wrong: `wireguard` declares its VPN subnet and brings `wg0` up inside one
+   * hook run, and the converge that follows has to see the declaration.
+   */
+  declaredNetworks: () => Array<{ zone: string; subnet: string }>;
   /**
    * Every declared zone subnet — read from
    * `network.<zone>.subnet` across all of `NETWORK_ZONES`, not just the three
@@ -806,6 +847,35 @@ export function loadTrustedSubnets(db: DbClient, firewallIp?: string): TrustedSu
  * of them. Zones with no configured subnet are omitted — their traffic stays
  * denied (fail-closed).
  */
+/**
+ * Every network celilo can attribute an interface to: one entry per
+ * `network.<name>.subnet` in system config.
+ *
+ * Read from the config rather than from `NETWORK_ZONES`, because celilo declares
+ * networks that are not placement zones. `wireguard`'s `on_install` writes
+ * `network.control-plane-vpn.subnet` before it brings `wg0` up, exactly as the
+ * design requires (D3), and the firewall is supposed to classify `wg0` "by the
+ * same subnet containment it uses for every other leg". Reading only
+ * `NETWORK_ZONES` left that declaration invisible: the converge could not
+ * attribute `wg0` and refused — and on a firewall with a baseline it would have
+ * ISOLATED it, shutting down the admin VPN.
+ *
+ * `external` is deliberately absent even when something has set
+ * `network.external.subnet`: it is the RESIDUAL, decided by `isPubliclyRoutable`
+ * and never by containment (design D1, amended). Matching an interface to
+ * `external` by subnet would reintroduce the overload this change removes.
+ */
+export function readDeclaredNetworks(db: DbClient): Array<{ zone: string; subnet: string }> {
+  return db
+    .select()
+    .from(systemConfig)
+    .all()
+    .flatMap((row) => {
+      const zone = /^network\.(.+)\.subnet$/.exec(row.key)?.[1];
+      return zone && zone !== 'external' && row.value ? [{ zone, subnet: row.value }] : [];
+    });
+}
+
 function loadFirewallZones(db: DbClient): FirewallZones {
   const zoneTiers: Array<{ name: string; subnet: string }> = [];
   for (const zone of ZONE_TIER_ORDER) {
@@ -822,17 +892,65 @@ function loadFirewallZones(db: DbClient): FirewallZones {
   // snapshot put the subnet straight back, so the set could grow but never
   // shrink. That is exactly what happened: `on_uninstall` withdrew the VPN's
   // trusted source, logged success, and the reach rules were re-rendered anyway.
+  // Every zone that HAS a declared subnet, keeping the zone NAME. Interface
+  // classification needs the name — `external` and `internal` are the only two
+  // legs a default route may leave through (design D11), which is not a question
+  // a bare list of subnets can answer.
+  //
+  // `external` is deliberately absent from this list even when something has set
+  // `network.external.subnet`: `external` is the RESIDUAL, decided by
+  // `isPubliclyRoutable`, never by containment (design D1, amended). Matching an
+  // interface to `external` by subnet would reintroduce the overload this change
+  // removes.
+  //
+  // EVERY declared network, not just the six `NETWORK_ZONES`. celilo declares
+  // networks that are not placement zones — `network.control-plane-vpn.subnet`,
+  // written by `wireguard`'s `on_install` — and the design is explicit that the
+  // firewall "classifies `wg0` by the same subnet containment it uses for every
+  // other leg". Reading only `NETWORK_ZONES` left that declaration invisible:
+  // the module declared the subnet before bringing the interface up, exactly as
+  // designed, and the converge still could not attribute `wg0` and refused. On a
+  // firewall that already had a baseline it would have gone further and ISOLATED
+  // the interface — celilo shutting down the admin VPN, which for a remote
+  // operator is the way back in.
+  //
+  // So the source is the config itself. A hardcoded list here could only ever
+  // describe the networks celilo knew about when this line was written.
+
   return {
     zoneTiers,
     trustedSubnets: loadTrustedSubnets(db).map((e) => e.subnet),
     controlPlaneSubnet: loadControlPlaneSubnet(db) ?? readZoneSubnet(db, 'internal'),
-    // Every zone celilo knows about, not the tier list — see the field doc.
-    frontedSubnets: NETWORK_ZONES.map((zone) => readZoneSubnet(db, zone)).filter(
-      (subnet): subnet is string => !!subnet,
-    ),
+    declaredNetworks: () => readDeclaredNetworks(db),
+    // Placement ZONES only — deliberately NOT `declaredNetworks`, which is wider.
+    // Fronting a subnet renders translation for it; the control-plane VPN
+    // reaches the fleet as a trusted source instead, and giving it a second
+    // mechanism would change the rendered ruleset for every existing fleet.
+    frontedSubnets: NETWORK_ZONES.filter((zone) => zone !== 'external').flatMap((zone) => {
+      const subnet = readZoneSubnet(db, zone);
+      return subnet ? [subnet] : [];
+    }),
   };
 }
 
+/**
+ * The interface baseline as stored in module config: a comma-separated list of
+ * interface names, or absent.
+ *
+ * Absent and empty are the SAME thing here and both mean "no baseline" — a
+ * firewall with zero interfaces does not exist, so an empty string can only be
+ * a cleared or never-written value. Treating it as a baseline of nothing would
+ * mean every interface is "new", which is the opposite of what it says.
+ */
+function parseInterfaceBaseline(raw: unknown): string[] | undefined {
+  if (typeof raw !== 'string') return undefined;
+  const names = raw
+    .split(',')
+    .map((n) => n.trim())
+    .filter((n) => n.length > 0);
+  return names.length > 0 ? names : undefined;
+}
+
 async function buildFirewallChain(
   allProviders: Array<{
     id: number;
@@ -982,11 +1100,19 @@ async function buildFirewallChain(
         trustedSubnets: zones.trustedSubnets,
         controlPlaneSubnet: zones.controlPlaneSubnet,
         frontedSubnets: zones.frontedSubnets,
+        // The recorded baseline (D12), from this firewall's own module config.
+        // Absent means the box has never converged cleanly, so an interface
+        // celilo cannot attribute refuses rather than being disabled.
+        interfaceBaseline: parseInterfaceBaseline(provConfig.interface_baseline),
       },
       store,
       currentUpstream,
       logger,
       trustedSourceStore,
+      // LIVE, not a snapshot: a declaration written during this hook run —
+      // `wireguard` declaring its VPN subnet before creating `wg0` — must be
+      // visible to the converge that follows it in the same run.
+      { list: zones.declaredNetworks },
     );
 
     debugLog(`firewall chain: wired ${provider.moduleId} → ${hasExternal.moduleId}`);

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