@celilo/cli 0.22.0 → 0.24.0

package/src/cli/stdout-is-undecorated.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Recurrence gate for celilo#699 — ordinary stdout carries no decoration, and
+ * diagnostics do not share the stream with results.
+ *
+ * The CLI used to render every successful message through `@clack/prompts`,
+ * which prefixed each line with `│  ` and coloured it. Two costs followed, and
+ * this file pins both shut:
+ *
+ *  1. `line.startsWith('<module-id> ')` over `celilo module list` matched
+ *     nothing, because the line actually began `│  caddy (v2.2.0) - …`. In
+ *     celilo#695 that read as a MISSING MODULE rather than as a parse failure,
+ *     and cost a full e2e run to find. `e2e/tests/module-pause.test.ts` asserts
+ *     the same property against the real fleet topology; this is its fast
+ *     equivalent, so a regression is caught in seconds rather than in Docker.
+ *
+ *  2. clack wrote errors to stdout, so no caller could tell a result from a
+ *     complaint about producing one — `src/test-utils/cli.ts` carried a comment
+ *     saying exactly that, twice, and merged both streams to cope.
+ *
+ * Spawns the real CLI rather than using `CLIContext`: that harness runs the CLI
+ * in `CLI_SERVER_MODE`, which returns `result.message` over a protocol and
+ * never reaches the stdout writer under test here.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { type IntegrationTestContext, setupIntegrationTest } from '@/test-utils/integration';
+
+let ctx: IntegrationTestContext;
+
+function celilo(command: string): { stdout: string; stderr: string; status: number | null } {
+  const result = spawnSync('bun', ['run', 'src/cli/index.ts', ...command.split(' ')], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      CELILO_DB_PATH: ctx.dbPath,
+      CELILO_DATA_DIR: ctx.dataDir,
+      CELILO_SUPPRESS_DEPRECATION: '1',
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 60_000,
+  });
+  return { stdout: result.stdout, stderr: result.stderr, status: result.status };
+}
+
+/** The `│` clack used to open every rendered line with. */
+const BOX_DRAWING = /[│┌└├─]/;
+const ANSI = /\x1b\[[0-9;]*m/;
+
+describe('celilo#699 — stdout is undecorated', () => {
+  beforeAll(async () => {
+    ctx = await setupIntegrationTest();
+    // A module has to exist for `module list` to print a roster line at all —
+    // an empty roster would pass every assertion below without testing them.
+    const imported = celilo('module import ../../modules/celilo-mgmt');
+    expect(imported.status, `module import failed:\n${imported.stderr}`).toBe(0);
+  });
+
+  afterAll(async () => {
+    await ctx.cleanup();
+  });
+
+  test('module list lines start with the module id, with no preprocessing', () => {
+    const { stdout, status, stderr } = celilo('module list');
+    expect(status, `module list failed:\n${stderr}`).toBe(0);
+
+    // The exact shape celilo#695 tried and failed to match. No ANSI stripping,
+    // no prefix trimming — if this needs either, the bug is back.
+    const line = stdout.split('\n').find((l) => l.startsWith('celilo-mgmt '));
+
+    expect(
+      line,
+      `No line began with "celilo-mgmt ". stdout was:\n${JSON.stringify(stdout)}`,
+    ).toBeDefined();
+  });
+
+  test('module list stdout carries no box-drawing or ANSI', () => {
+    const { stdout } = celilo('module list');
+    expect(BOX_DRAWING.test(stdout), `box-drawing in stdout:\n${JSON.stringify(stdout)}`).toBe(
+      false,
+    );
+    expect(ANSI.test(stdout), `ANSI in stdout:\n${JSON.stringify(stdout)}`).toBe(false);
+  });
+
+  test('a failing command writes its diagnostic to stderr, not stdout', () => {
+    const { stdout, stderr, status } = celilo('module where no-such-module-exists');
+
+    expect(status).not.toBe(0);
+    expect(stderr).toContain('Error');
+    // The whole point: stdout stays empty so a caller parsing it is not handed
+    // an error message where a result belongs.
+    expect(stdout.trim(), `error text leaked to stdout: ${JSON.stringify(stdout)}`).toBe('');
+  });
+});

package/src/cli/tui/audit-state.ts

@@ -88,9 +88,11 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
   'disk_space',
   'transport_reads',
   'trusted_sources',
+  'interface_classification',
 ];
 
 export const CATEGORY_LABELS: Record<DriftCategory, string> = {
+  interface_classification: 'Firewall interfaces',
   cli_version: 'CLI version',
   schema: 'Schema migrations',
   capability_abi: 'Capability ABI',

package/src/cli/types.ts

@@ -20,8 +20,13 @@ export interface CommandSuccess {
   message: string;
   data?: unknown;
   /**
-   * When true, the CLI writes `message` directly to stdout (no clack formatting).
-   * Use for commands designed to be consumed by scripts (e.g. `module secret get`).
+   * Marks a command whose `message` is a machine-readable payload (JSON, a
+   * unit file, a secret) rather than prose for a human.
+   *
+   * Every successful message now reaches stdout verbatim, so this no longer
+   * selects a different destination. It is kept as the contract: these are the
+   * commands a script parses, and nothing may ever decorate them (celilo#698,
+   * where ten JSON payloads were rendered unparseable by the formatter).
    */
   rawOutput?: boolean;
 }

package/src/db/schema.ts

@@ -11,7 +11,17 @@ import {
 
 /**
  * Module lifecycle states
- * IMPORTED, VALIDATED, CONFIGURED, GENERATING, ERROR, DEPLOYING, INSTALLED, VERIFIED, UNINSTALLING
+ * IMPORTED, VALIDATED, CONFIGURED, GENERATING, ERROR, DEPLOYING, INSTALLED, VERIFIED, UNINSTALLING, PAUSED
+ *
+ * `PAUSED` is a real member of this union rather than a side flag, and that is
+ * the point (openspec/changes/module-pause-lifecycle/design.md D1): adding it
+ * makes the type-checker enumerate every site that must now consider
+ * paused-ness. A `pausedAt`-only flag would leave every `state === 'VERIFIED'`
+ * comparison silently compiling while quietly reading a paused module as live.
+ *
+ * There is deliberately no `prePauseState`: pause is legal only from a settled
+ * state and unpause redeploys, so the deploy path decides the resulting state
+ * and there is nothing to restore.
  */
 export type ModuleState =
   | 'IMPORTED'
@@ -22,23 +32,65 @@ export type ModuleState =
   | 'INSTALLED'
   | 'VERIFIED'
   | 'ERROR'
-  | 'UNINSTALLING';
+  | 'UNINSTALLING'
+  | 'PAUSED';
+
+/**
+ * States a module may be paused FROM (design D1). `ERROR` is deliberately
+ * included: quiescing a broken module to stop alert noise while working on it
+ * is legitimate, and refusing would push the operator toward silencing those
+ * alerts by some less visible route.
+ */
+export const PAUSABLE_STATES = [
+  'INSTALLED',
+  'VERIFIED',
+  'ERROR',
+] as const satisfies readonly ModuleState[];
+
+/**
+ * States that mean "a lifecycle transition is under way". Pausing one of these
+ * would strand the transition, so pause is refused with a distinct message from
+ * the never-deployed case.
+ */
+export const IN_FLIGHT_STATES = [
+  'GENERATING',
+  'DEPLOYING',
+  'UNINSTALLING',
+] as const satisfies readonly ModuleState[];
 
 /**
  * Modules table - stores module metadata and manifest data
  */
-export const modules = sqliteTable('modules', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
-  version: text('version').notNull(),
-  description: text('description'),
-  state: text('state').$type<ModuleState>().notNull().default('IMPORTED'),
-  manifestData: text('manifest_data', { mode: 'json' }).$type<Record<string, unknown>>().notNull(),
-  sourcePath: text('source_path').notNull(),
-  importedAt: integer('imported_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
-  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
-  errorMessage: text('error_message'),
-});
+export const modules = sqliteTable(
+  'modules',
+  {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    version: text('version').notNull(),
+    description: text('description'),
+    state: text('state').$type<ModuleState>().notNull().default('IMPORTED'),
+    manifestData: text('manifest_data', { mode: 'json' })
+      .$type<Record<string, unknown>>()
+      .notNull(),
+    sourcePath: text('source_path').notNull(),
+    importedAt: integer('imported_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    errorMessage: text('error_message'),
+    /**
+     * When the module was paused. Null unless `state = 'PAUSED'`. The state alone
+     * cannot answer "how long", and the DURATION is what makes a forgotten pause
+     * detectable (design D7) — every paused-module report carries the age.
+     */
+    pausedAt: integer('paused_at', { mode: 'timestamp' }),
+    /** Operator-supplied explanation, so the row explains itself. */
+    pauseReason: text('pause_reason'),
+  },
+  (table) => ({
+    // Every management-API response asks "is anything paused?" (design D7), so
+    // that lookup must stay a single indexed hit rather than a table scan.
+    stateIdx: index('modules_state_idx').on(table.state),
+  }),
+);
 
 /**
  * Module configuration - user-provided key-value pairs.
@@ -807,7 +859,13 @@ export const backups = sqliteTable('backups', {
  * pid is no longer alive is treated as abandoned (the process crashed before
  * the completion update landed) and ignored by in-flight checks.
  */
-export type ModuleOperationKind = 'deploy' | 'uninstall' | 'backup' | 'restore';
+export type ModuleOperationKind =
+  | 'deploy'
+  | 'uninstall'
+  | 'backup'
+  | 'restore'
+  | 'pause'
+  | 'unpause';
 export type ModuleOperationStatus = 'in_progress' | 'completed' | 'failed';
 
 export const moduleOperations = sqliteTable('module_operations', {

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/run-named-hook.ts

@@ -49,6 +49,13 @@ export interface RunNamedHookResult extends HookResult {
    * gracefully when a module has no `on_uninstall` defined.
    */
   notDefined?: boolean;
+  /**
+   * True when the hook was not run because the module is PAUSED. Reported as
+   * success rather than failure: the module is deliberately quiesced, and a
+   * failure here would be retried by the bus and then alerted on — paging the
+   * operator about the pause they took themselves.
+   */
+  skippedPaused?: boolean;
 }
 
 /**
@@ -82,6 +89,27 @@ export async function runNamedHook(
     };
   }
 
+  // Quiescence for a paused module (openspec/changes/module-pause-lifecycle,
+  // tasks 2.1/2.2). This is the chokepoint every non-lifecycle invocation
+  // funnels through — bus dispatch, timer fan-out, aspect fan-out,
+  // public-web republish, the dns-provider backfill, and `module run-hook` —
+  // so guarding here covers the paths individually rather than each caller
+  // remembering to.
+  //
+  // The exemptions are decided from the hook NAME, not a caller-supplied flag
+  // (Rule 10.3): `on_install` is how unpause redeploys the module back to life,
+  // and `on_uninstall` is how a paused module is removed — which is the entire
+  // point of pausing it. Both must run while `state` is still PAUSED.
+  const LIFECYCLE_HOOKS: readonly HookName[] = ['on_install', 'on_uninstall'];
+  if (module.state === 'PAUSED' && !LIFECYCLE_HOOKS.includes(hookName)) {
+    return {
+      success: true,
+      outputs: {},
+      duration: Date.now() - startedAt,
+      skippedPaused: true,
+    };
+  }
+
   const manifest = module.manifestData as ModuleManifest;
   const hookDef = manifest.hooks?.[hookName as keyof typeof manifest.hooks];
   if (!hookDef) {

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),