@celilo/cli 0.23.0 → 0.24.0

package/src/cli/commands/firewall-interface-list.ts

@@ -0,0 +1,123 @@
+/**
+ * `celilo firewall interface list [<hostname>]`
+ *
+ * The interface classification, on demand, with no side effects.
+ *
+ * A converge already refuses or isolates on what it finds — but only when it
+ * runs, and only in the middle of a deploy's output. An operator about to
+ * onboard a firewall, or wondering why one refused, needs to be able to ASK.
+ * The condition that produced `fw-keeper.sh` was not that celilo lacked the
+ * information; it was that celilo never said it.
+ *
+ * Read-only by construction: it reads the stored interface table and the
+ * declarations, and classifies in memory. It never touches the box, so it is
+ * safe to run against a firewall that is currently refusing.
+ */
+
+import { classifyInterfaces, isPubliclyRoutable } from '@celilo/capabilities';
+import { getDb } from '../../db/client';
+import { listFirewallIps, readDeclaredNetworks } from '../../hooks/capability-loader';
+import { listMachines } from '../../services/machine-pool';
+import { celiloIntro } from '../prompts';
+import type { CommandResult } from '../types';
+
+/**
+ * Every network a subnet is declared for — THE same reader the converge uses.
+ *
+ * This command's whole value is telling an operator what the next converge will
+ * do, so reading declarations a second way is not a duplication smell, it is a
+ * correctness bug: this file walked `NETWORK_ZONES` and so could not see
+ * `network.control-plane-vpn.subnet`. It would have reported `wg0` as ALIEN —
+ * "this will be isolated" — about an interface the converge attributes and
+ * leaves alone. The operator's most likely response to that reading is to go
+ * and remove their own admin VPN.
+ */
+async function declaredZones(): Promise<Array<{ zone: string; subnet: string }>> {
+  return readDeclaredNetworks(getDb());
+}
+
+/** One line per interface, explaining the role rather than just naming it. */
+function describe(role: string, zone: string | undefined, ip: string): string {
+  if (role === 'zone') return `zone:${zone}`;
+  if (role === 'external') return 'external — the WAN edge';
+  return isPubliclyRoutable(ip)
+    ? 'ALIEN — publicly routable but no declared zone claims it'
+    : 'ALIEN — no declared subnet contains it';
+}
+
+export async function handleFirewallInterfaceList(
+  args: string[],
+  _flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  celiloIntro('Firewall interfaces');
+
+  const wanted = args[0];
+  const machines = await listMachines();
+  // A firewall is a machine a firewall provider MANAGES. `role === 'router'` is
+  // kept as a second way in, but it cannot be the only one: the role is decided
+  // by `machine add` from the zones declared at that moment, and the normal
+  // order is to add the machine and THEN deploy iptables, whose `on_install`
+  // writes the zone subnets. So a working firewall is recorded as a plain host,
+  // and this command — whose entire purpose is to report on firewalls — answered
+  // "No firewalls in the machine pool" on a fleet that had one.
+  //
+  // Named explicitly, the hostname wins, so an operator can inspect any box.
+  const firewallIps = new Set(await listFirewallIps(getDb()));
+  const targets = wanted
+    ? machines.filter((m) => m.hostname === wanted)
+    : machines.filter((m) => firewallIps.has(m.ipAddress) || m.role === 'router');
+
+  if (targets.length === 0) {
+    return {
+      success: false,
+      error: wanted
+        ? `No machine named "${wanted}". Run \`celilo machine list\` to see the pool.`
+        : 'No firewalls in the machine pool. celilo looks for a machine managed by a firewall provider, or one it classified as a router.',
+    };
+  }
+
+  const zones = await declaredZones();
+  if (zones.length === 0) {
+    console.log(
+      'No zone subnets are declared, so every interface will read as unaccounted for.\n' +
+        'Declare them with: celilo system config set network.<zone>.subnet <cidr>\n',
+    );
+  }
+
+  let alienTotal = 0;
+  for (const machine of targets) {
+    console.log(`\n${machine.hostname} (${machine.ipAddress})`);
+
+    const interfaces = (machine.interfaces ?? []).map((i) => ({
+      name: i.name,
+      ip: i.ipAddress,
+    }));
+    if (interfaces.length === 0) {
+      console.log('  no interfaces recorded — re-run `celilo machine add` to detect them');
+      continue;
+    }
+
+    for (const c of classifyInterfaces(interfaces, zones)) {
+      if (c.role === 'alien') alienTotal += 1;
+      console.log(`  ${c.name.padEnd(8)} ${c.ip.padEnd(16)} ${describe(c.role, c.zone, c.ip)}`);
+    }
+  }
+
+  console.log('');
+  if (alienTotal > 0) {
+    // Say what will HAPPEN, not merely what was found — the answer differs by
+    // whether celilo has a baseline for the box, and that is the thing an
+    // operator most needs to know before the next converge.
+    const consequence = [
+      'On a firewall celilo has not yet converged cleanly, the next converge will REFUSE and change nothing.',
+      'On one with a recorded baseline, an interface that appeared since will be isolated.',
+      'Resolve either by declaring a zone: celilo system config set network.<zone>.subnet <cidr>',
+    ].join('\n');
+    console.log(`${alienTotal} interface(s) celilo cannot attribute.\n${consequence}`);
+  }
+
+  return {
+    success: true,
+    message: alienTotal === 0 ? 'every interface accounted for' : `${alienTotal} unaccounted`,
+  };
+}

package/src/cli/commands/machine-add.ts

@@ -6,6 +6,7 @@
 import { existsSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isPubliclyRoutable } from '@celilo/capabilities';
 import { getDb } from '../../db/client';
 import type { NetworkZone } from '../../db/schema';
 import { askText, withInterviewSession } from '../../services/bus-interview';
@@ -16,6 +17,7 @@ import {
   detectNetworkInterfacesLocal,
   testSshConnection,
 } from '../../services/machine-detector';
+import { describeInterfaceZone } from '../../services/machine-detector';
 import { addMachine, getMachineByIp } from '../../services/machine-pool';
 import { loadExistingConfiguration } from '../../services/system-init';
 import { detectZoneFromIp } from '../../services/zone-detector';
@@ -242,8 +244,34 @@ export async function handleMachineAdd(
         console.log(`  Disk: ${detectedInfo.hardware.disk_gb} GB\n`);
 
         // Zone: explicit override, else infer from IP.
+        //
+        // `detectZoneFromIp` answers containment only, and now says `'unknown'`
+        // rather than claiming `external` when nothing matches. Resolving that
+        // is a SECOND question — is this address one the internet can route to?
+        // — and the two were conflated before, which is how a private address in
+        // no declared subnet got labelled as facing the internet.
         console.log('Detecting network zone...');
-        zone = zoneOverride ?? (await detectZoneFromIp(ipAddress));
+        if (zoneOverride) {
+          zone = zoneOverride;
+        } else {
+          const detected = await detectZoneFromIp(ipAddress);
+          if (detected !== 'unknown') {
+            zone = detected;
+          } else if (isPubliclyRoutable(ipAddress)) {
+            // No declared subnet contains it and the internet can route to it:
+            // that is what `external` means — a cloud/VPS box.
+            zone = 'external';
+          } else {
+            // A private address in no declared subnet is UN-ZONEABLE, not
+            // external. Guessing here is the original defect; ask instead.
+            const fix =
+              'Fix: pass --zone <zone>, or declare the subnet with `celilo system config set network.<zone>.subnet <cidr>` and retry.';
+            return {
+              success: false,
+              error: `Cannot infer a zone for ${ipAddress}: it is not publicly routable and no declared network.<zone>.subnet contains it.\n${fix}`,
+            };
+          }
+        }
         console.log(`✓ Zone: ${zone}\n`);
 
         // Detect network interfaces and classify machine
@@ -254,7 +282,7 @@ export async function handleMachineAdd(
 
         console.log(`✓ Role: ${role}`);
         for (const iface of interfaces) {
-          console.log(`  ${iface.name}: ${iface.ipAddress} (${iface.zone})`);
+          console.log(`  ${iface.name}: ${iface.ipAddress} (${describeInterfaceZone(iface)})`);
         }
         console.log('');
       }

package/src/cli/commands/module-config.test.ts

@@ -14,7 +14,9 @@ import { modules } from '../../db/schema';
 import { resolveDeployPosture } from '../../services/deploy-posture';
 import {
   FRAMEWORK_CONFIG_KEYS,
+  handleModuleConfigGet,
   handleModuleConfigSet,
+  handleModuleConfigUnset,
   validateFrameworkConfigValue,
 } from './module-config';
 import { pickUpgradePolicy } from './module-upgrade';
@@ -112,6 +114,30 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
     expect(result.success).toBe(false);
   });
 
+  test('a per-module policy key is settable on a module whose manifest never mentions it', async () => {
+    expect((await handleModuleConfigSet(['testmod', 'backup_schedule', '6h'])).success).toBe(true);
+    const read = await handleModuleConfigGet(['testmod', 'backup_schedule']);
+    expect(read.success).toBe(true);
+    if (read.success) expect(read.message).toContain('6h');
+  });
+
+  test('unset removes the override so the module follows its manifest again', async () => {
+    await handleModuleConfigSet(['testmod', 'backup_schedule', 'weekly']);
+
+    const unset = await handleModuleConfigUnset(['testmod', 'backup_schedule']);
+    expect(unset.success).toBe(true);
+
+    expect((await handleModuleConfigGet(['testmod', 'backup_schedule'])).success).toBe(false);
+  });
+
+  test('unsetting a key that was never set reports it and still succeeds', async () => {
+    // `unset` states a desired end state. Failing on an already-clean one makes
+    // it unusable from any script that cannot check first.
+    const result = await handleModuleConfigUnset(['testmod', 'backup_schedule']);
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.message).toContain('No override set');
+  });
+
   test('the valid-keys hint advertises the celilo-managed keys', async () => {
     const result = await handleModuleConfigSet(['testmod', 'nope', 'x']);
     expect(result.success).toBe(false);
@@ -127,8 +153,19 @@ describe('validateFrameworkConfigValue (pure)', () => {
     expect(validateFrameworkConfigValue('app_port', 'anything')).toBeNull();
   });
 
-  test('accepts every documented value', () => {
-    for (const [key, values] of Object.entries(FRAMEWORK_CONFIG_KEYS)) {
+  test('every framework key accepts at least its documented values', () => {
+    const documented: Record<string, string[]> = {
+      auto_upgrade: ['true', 'false'],
+      upgrade_policy: ['by-semver', 'always-safe', 'always-fast'],
+      backup_schedule: ['hourly', 'daily', 'weekly', 'monthly', 'manual', '6h'],
+      health_check_interval: ['15m', '1h', 'daily', 'manual'],
+      backup_retention_count: ['1', '3', '30'],
+      backup_retention_max_age_days: ['1', '30', '365'],
+    };
+    // Every key must be covered, so adding one without deciding what it accepts
+    // fails here rather than shipping unvalidated.
+    expect(Object.keys(documented).sort()).toEqual(Object.keys(FRAMEWORK_CONFIG_KEYS).sort());
+    for (const [key, values] of Object.entries(documented)) {
       for (const v of values) expect(validateFrameworkConfigValue(key, v)).toBeNull();
     }
   });
@@ -136,6 +173,31 @@ describe('validateFrameworkConfigValue (pure)', () => {
   test('rejects an unlisted value', () => {
     expect(validateFrameworkConfigValue('upgrade_policy', 'always_safe')).toContain('Allowed');
   });
+
+  test('rejects a cadence the sweep that would serve it cannot run', () => {
+    // The backup sweep rides an hourly tick; accepting `5m` would leave the
+    // operator believing they configured something that can never happen.
+    expect(validateFrameworkConfigValue('backup_schedule', '5m')).toContain('hourly');
+    // The alerting sweep ticks every five minutes, so the same value is fine there.
+    expect(validateFrameworkConfigValue('health_check_interval', '5m')).toBeNull();
+    expect(validateFrameworkConfigValue('health_check_interval', '1m')).toContain('Allowed');
+  });
+
+  test('a retention of zero or below is refused rather than read as "keep nothing"', () => {
+    // A `0` read as a bound would delete every backup the module has.
+    for (const bad of ['0', '-1', '2.5', 'lots']) {
+      expect(validateFrameworkConfigValue('backup_retention_count', bad)).toContain('1 or greater');
+      expect(validateFrameworkConfigValue('backup_retention_max_age_days', bad)).toContain(
+        '1 or greater',
+      );
+    }
+  });
+
+  test('a misspelled cadence is refused, and says it was not coerced', () => {
+    const error = validateFrameworkConfigValue('backup_schedule', 'dailyy');
+    expect(error).toContain('named period');
+    expect(error).toContain('Rejected rather than coerced');
+  });
 });
 
 // The point of the whole control: with always-safe set, a PATCH upgrade — which

package/src/cli/commands/module-config.ts

@@ -3,9 +3,25 @@
  */
 
 import { eq } from 'drizzle-orm';
+import { z } from 'zod';
 import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import {
+  HEALTH_CHECK_INTERVAL_CONFIG_KEY,
+  reconcileModuleWatchState,
+} from '../../services/alerting/health-cadence';
+import {
+  BACKUP_RETENTION_COUNT_CONFIG_KEY,
+  BACKUP_RETENTION_MAX_AGE_DAYS_CONFIG_KEY,
+} from '../../services/backup-retention';
+import { BACKUP_SCHEDULE_CONFIG_KEY } from '../../services/backup-schedule';
+import {
+  BACKUP_CADENCE_FLOOR_MINUTES,
+  MONITOR_INTERVAL_FLOOR_MINUTES,
+  cadenceSchema,
+} from '../../services/cadence';
+import {
+  deleteModuleConfig,
   formatConfigValue,
   getAllModuleConfigValues,
   getModuleConfigValue,
@@ -18,6 +34,12 @@ import type { CommandResult } from '../types';
  * Operator keys that EVERY module accepts, whether or not its manifest declares
  * them, with their permitted values.
  *
+ * This is also where a module's per-module POLICY lives: how often to back it
+ * up, how often to health-check it. A manifest states those as the author's
+ * suggestion about a fleet they have never seen; the row an operator writes
+ * here wins, and every reader resolves the two at read time so a corrected
+ * manifest still reaches installs that have not overridden it.
+ *
  * These describe how celilo TREATS a module (its CD policy), not how the module
  * configures itself, so gating them on `variables.owns` had it backwards: it
  * required each module author to opt into being manageable. The failure was
@@ -34,9 +56,69 @@ import type { CommandResult } from '../types';
  * floor while nothing changed. A safety control that fails open on a typo is
  * worse than no control.
  */
-export const FRAMEWORK_CONFIG_KEYS: Record<string, readonly string[]> = {
-  auto_upgrade: ['true', 'false'],
-  upgrade_policy: ['by-semver', 'always-safe', 'always-fast'],
+export interface FrameworkConfigKey {
+  /** Accepts the value the operator typed, or explains what it should be. */
+  schema: z.ZodTypeAny;
+  /**
+   * Why this key is refused rather than coerced. Carried per key rather than
+   * derived from the schema's error: the substance is what a WRONG value would
+   * silently do, and no validator knows that.
+   */
+  why: string;
+}
+
+const REFUSED_NOT_COERCED_UPGRADE =
+  'Rejected rather than coerced: an unrecognized value silently falls back to the PERMISSIVE default (upgrade_policy → by-semver, which skips the pre-deploy backup on a patch), so a typo would look like it took effect.';
+
+const REFUSED_NOT_COERCED_CADENCE =
+  'Rejected rather than coerced: an unrecognized cadence falls back to the manifest\'s suggestion, so a typo would leave the module on the cadence you meant to change — visibly "set", and doing nothing.';
+
+const REFUSED_NOT_COERCED_RETENTION =
+  'Rejected rather than coerced: an unrecognized retention value falls back to the manifest, so a typo would leave the module keeping a different number of backups than you asked for — and the direction that goes wrong deletes data.';
+
+/** An enum whose rejection message reads as an operator instruction, not a type error. */
+function oneOf(values: readonly [string, ...string[]]): z.ZodTypeAny {
+  return z.enum(values, { errorMap: () => ({ message: `Allowed: ${values.join(', ')}` }) });
+}
+
+/**
+ * A whole number of things, at least one. Zero is refused rather than read as
+ * "keep nothing": a retention of 0 would delete every backup the module has.
+ */
+function positiveInteger(what: string): z.ZodTypeAny {
+  return z.string().superRefine((value, ctx) => {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Allowed: a whole number of ${what}, 1 or greater. Unset the key to keep everything.`,
+      });
+    }
+  });
+}
+
+export const FRAMEWORK_CONFIG_KEYS: Record<string, FrameworkConfigKey> = {
+  auto_upgrade: { schema: oneOf(['true', 'false']), why: REFUSED_NOT_COERCED_UPGRADE },
+  upgrade_policy: {
+    schema: oneOf(['by-semver', 'always-safe', 'always-fast']),
+    why: REFUSED_NOT_COERCED_UPGRADE,
+  },
+  [BACKUP_SCHEDULE_CONFIG_KEY]: {
+    schema: cadenceSchema({ floorMinutes: BACKUP_CADENCE_FLOOR_MINUTES }),
+    why: REFUSED_NOT_COERCED_CADENCE,
+  },
+  [HEALTH_CHECK_INTERVAL_CONFIG_KEY]: {
+    schema: cadenceSchema({ floorMinutes: MONITOR_INTERVAL_FLOOR_MINUTES }),
+    why: REFUSED_NOT_COERCED_CADENCE,
+  },
+  [BACKUP_RETENTION_COUNT_CONFIG_KEY]: {
+    schema: positiveInteger('copies to keep'),
+    why: REFUSED_NOT_COERCED_RETENTION,
+  },
+  [BACKUP_RETENTION_MAX_AGE_DAYS_CONFIG_KEY]: {
+    schema: positiveInteger('days to keep a backup'),
+    why: REFUSED_NOT_COERCED_RETENTION,
+  },
 };
 
 /**
@@ -44,10 +126,12 @@ export const FRAMEWORK_CONFIG_KEYS: Record<string, readonly string[]> = {
  * or null when the key is not a framework key or the value is permitted.
  */
 export function validateFrameworkConfigValue(key: string, value: string): string | null {
-  const allowed = FRAMEWORK_CONFIG_KEYS[key];
-  if (!allowed) return null;
-  if (allowed.includes(value)) return null;
-  return `Invalid value '${value}' for '${key}'.\n\nAllowed: ${allowed.join(', ')}\n\nRejected rather than coerced: an unrecognized value silently falls back to the PERMISSIVE default (upgrade_policy → by-semver, which skips the pre-deploy backup on a patch), so a typo would look like it took effect.`;
+  const framework = FRAMEWORK_CONFIG_KEYS[key];
+  if (!framework) return null;
+  const result = framework.schema.safeParse(value);
+  if (result.success) return null;
+  const explanation = result.error.issues.map((issue) => issue.message).join('\n');
+  return `Invalid value '${value}' for '${key}'.\n\n${explanation}\n\n${framework.why}`;
 }
 
 /**
@@ -131,10 +215,14 @@ export async function handleModuleConfigSet(args: string[]): Promise<CommandResu
   // Set config value using service (handles primitive and complex types)
   try {
     await setModuleConfigValue(moduleId, key, value);
+    const resolved = settlingWatchState(db, moduleId, key);
 
     return {
       success: true,
-      message: `Set config for ${moduleId}: ${key}`,
+      message:
+        resolved > 0
+          ? `Set config for ${moduleId}: ${key} (resolved ${resolved} alert(s) — nothing will report on this module again until it is watched)`
+          : `Set config for ${moduleId}: ${key}`,
     };
   } catch (error) {
     return {
@@ -144,6 +232,69 @@ export async function handleModuleConfigSet(args: string[]): Promise<CommandResu
   }
 }
 
+/**
+ * Handle module config unset command
+ *
+ * Usage: celilo module config unset <module-id> <key>
+ *
+ * Removing an override is what returns a module to following its manifest.
+ * Without it, an operator who once set a cadence could never go back to the
+ * author's suggestion, and every later correction would stop reaching them —
+ * the exact failure read-time resolution exists to prevent, aimed at the
+ * operators who engaged with the feature.
+ *
+ * @param args - Command arguments
+ * @returns Command result
+ */
+export async function handleModuleConfigUnset(args: string[]): Promise<CommandResult> {
+  const error = validateRequiredArgs(args, 2);
+  if (error) {
+    return {
+      success: false,
+      error: `${error}\n\nUsage: celilo module config unset <module-id> <key>`,
+    };
+  }
+
+  const moduleId = getArg(args, 0);
+  const key = getArg(args, 1);
+
+  if (!moduleId || !key) {
+    return { success: false, error: 'Module ID and key are required' };
+  }
+
+  const db = getDb();
+
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) {
+    return { success: false, error: `Module not found: ${moduleId}` };
+  }
+
+  // Unsetting a key that was never set SUCCEEDS. `unset` states a desired end
+  // state, and failing on an already-clean one makes it unusable from any
+  // script that cannot check first.
+  if (!getModuleConfigValue(moduleId, key, db)) {
+    return { success: true, message: `No override set for ${moduleId}: ${key}` };
+  }
+
+  deleteModuleConfig(db, moduleId, key);
+  settlingWatchState(db, moduleId, key);
+  return {
+    success: true,
+    message: `Unset config for ${moduleId}: ${key} (now follows the module's manifest)`,
+  };
+}
+
+/**
+ * A module that has just stopped being watched may still own live alerts from
+ * its last scheduled runs, and nothing will ever report on them again. Resolve
+ * them here rather than leaving them firing with no action able to clear them.
+ * No-op for every other key.
+ */
+function settlingWatchState(db: ReturnType<typeof getDb>, moduleId: string, key: string): number {
+  if (key !== HEALTH_CHECK_INTERVAL_CONFIG_KEY) return 0;
+  return reconcileModuleWatchState(db, moduleId, new Date());
+}
+
 /**
  * Handle module config get command
  *

package/src/cli/commands/module-status.ts

@@ -5,11 +5,123 @@
 import { eq } from 'drizzle-orm';
 import { getDb } from '../../db/client';
 import { capabilities, moduleConfigs, modules, secrets } from '../../db/schema';
+import type { ModuleManifest } from '../../manifest/schema';
+import {
+  HEALTH_CHECK_INTERVAL_CONFIG_KEY,
+  effectiveHealthCheckCadence,
+} from '../../services/alerting/health-cadence';
+import {
+  BACKUP_RETENTION_COUNT_CONFIG_KEY,
+  BACKUP_RETENTION_MAX_AGE_DAYS_CONFIG_KEY,
+  effectiveBackupRetention,
+  prunesNothing,
+} from '../../services/backup-retention';
+import {
+  BACKUP_SCHEDULE_CONFIG_KEY,
+  effectiveBackupSchedule,
+} from '../../services/backup-schedule';
+import { formatCadence } from '../../services/cadence';
 import { getModuleSystems } from '../../services/deployed-systems';
+import { configOverride, parseStoredConfigValue } from '../../services/module-config';
 import { formatPlacementLine, reconcilePlacement } from '../../services/placement-reconcile';
 import { getArg, validateRequiredArgs } from '../parser';
 import type { CommandResult } from '../types';
 
+/**
+ * PURE (Rule 10.1): the per-module policy block — what celilo will do to this
+ * module, and on whose authority.
+ *
+ * Both halves are shown deliberately. The stored override alone does not tell
+ * an operator what they changed it FROM, and the effective value alone does not
+ * tell them whether they set it or the module's author did.
+ */
+export function formatCadencePolicy(input: {
+  manifest: ModuleManifest;
+  configs: Record<string, unknown>;
+}): string {
+  const { manifest, configs } = input;
+  const lines = ['Policy:'];
+
+  if (manifest.hooks?.on_backup) {
+    const override = configOverride(configs, BACKUP_SCHEDULE_CONFIG_KEY);
+    const effective = formatCadence(effectiveBackupSchedule(manifest, override));
+    const suggested = manifest.backup?.schedule;
+    if (override !== undefined) {
+      lines.push(
+        `  backup cadence: ${effective} (operator override; manifest suggests ${suggested ?? 'nothing'})`,
+      );
+    } else if (suggested !== undefined) {
+      lines.push(`  backup cadence: ${effective} (from the manifest)`);
+    } else {
+      lines.push(`  backup cadence: ${effective} (celilo default; nothing declared or set)`);
+    }
+    lines.push(`  backup retention: ${describeRetention(manifest, configs)}`);
+  } else {
+    lines.push('  backup cadence: not backed up (module declares no on_backup hook)');
+  }
+
+  if (manifest.hooks?.health_check) {
+    const override = configOverride(configs, HEALTH_CHECK_INTERVAL_CONFIG_KEY);
+    const effective = effectiveHealthCheckCadence(manifest, override);
+    const suggested = manifest.hooks.health_check.interval;
+    const value = effective === null ? 'not watched (no cadence set)' : formatCadence(effective);
+    if (override !== undefined) {
+      lines.push(
+        `  health check: ${value} (operator override; manifest suggests ${suggested ?? 'nothing'})`,
+      );
+    } else if (suggested !== undefined) {
+      lines.push(`  health check: ${value} (from the manifest)`);
+    } else {
+      lines.push(`  health check: ${value}`);
+    }
+  } else {
+    lines.push('  health check: not watched (module declares no health_check hook)');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Retention in one line, per dimension, saying "unbounded" rather than a number
+ * wherever nothing bounds it. An operator reading a bound they never set would
+ * reasonably assume backups are being deleted — and the reverse assumption,
+ * that something is pruning when nothing is, is how a disk fills.
+ */
+function describeRetention(manifest: ModuleManifest, configs: Record<string, unknown>): string {
+  const policy = effectiveBackupRetention(manifest, configs);
+  if (prunesNothing(policy)) return 'none — every backup is kept';
+
+  const declared = manifest.backup?.retention;
+  const dimension = (
+    effective: number,
+    override: string | undefined,
+    suggested: number | undefined,
+    unit: string,
+  ): string => {
+    if (effective === Number.POSITIVE_INFINITY) return `unbounded ${unit}`;
+    const source =
+      override !== undefined
+        ? `operator override; manifest suggests ${suggested ?? 'nothing'}`
+        : 'from the manifest';
+    return `${effective} ${unit} (${source})`;
+  };
+
+  return [
+    dimension(
+      policy.count,
+      configOverride(configs, BACKUP_RETENTION_COUNT_CONFIG_KEY),
+      declared?.count,
+      'copies',
+    ),
+    dimension(
+      policy.maxAgeDays,
+      configOverride(configs, BACKUP_RETENTION_MAX_AGE_DAYS_CONFIG_KEY),
+      declared?.max_age_days,
+      'days',
+    ),
+  ].join(', ');
+}
+
 /**
  * Handle module status command
  *
@@ -114,6 +226,18 @@ export async function handleModuleStatus(args: string[]): Promise<CommandResult>
     sections.push('Configuration: (none)');
   }
 
+  // Section 2b: Per-module policy — what celilo will DO to this module, and
+  // whether that came from the operator or from the module's author. A raw
+  // config key does not tell an operator what the manifest said, and an
+  // effective value alone does not tell them whether they are the one who set
+  // it. Both, always.
+  sections.push(
+    formatCadencePolicy({
+      manifest: module.manifestData as ModuleManifest,
+      configs: Object.fromEntries(configs.map((c) => [c.key, parseStoredConfigValue(c)])),
+    }),
+  );
+
   // Section 3: Secrets
   if (moduleSecrets.length > 0) {
     const secretLines = ['Secrets:'];