@celilo/cli 0.13.3 → 0.14.0

package/drizzle/0017_alerting.sql

@@ -0,0 +1,127 @@
+CREATE TABLE `people` (
+	`id` text PRIMARY KEY NOT NULL,
+	`name` text NOT NULL,
+	`timezone` text NOT NULL,
+	`quiet_hours_start` text,
+	`quiet_hours_end` text,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `people_name_unique` ON `people` (`name`);--> statement-breakpoint
+CREATE TABLE `routes` (
+	`id` text PRIMARY KEY NOT NULL,
+	`person_id` text NOT NULL,
+	`transport_module_id` text NOT NULL,
+	`address` text NOT NULL,
+	`severity_floor` text DEFAULT 'warning' NOT NULL,
+	`can_ack` integer DEFAULT false NOT NULL,
+	`enabled` integer DEFAULT true NOT NULL,
+	`verified_at` integer,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`person_id`) REFERENCES `people`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`transport_module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `routes_person_id_transport_module_id_address_unique` ON `routes` (`person_id`,`transport_module_id`,`address`);--> statement-breakpoint
+CREATE TABLE `escalation_policies` (
+	`id` text PRIMARY KEY NOT NULL,
+	`name` text NOT NULL,
+	`bypass_quiet_hours` integer DEFAULT false NOT NULL,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `escalation_policies_name_unique` ON `escalation_policies` (`name`);--> statement-breakpoint
+CREATE TABLE `escalation_steps` (
+	`policy_id` text NOT NULL,
+	`step_index` integer NOT NULL,
+	`route_id` text NOT NULL,
+	`delay_minutes` integer NOT NULL,
+	PRIMARY KEY(`policy_id`, `step_index`),
+	FOREIGN KEY (`policy_id`) REFERENCES `escalation_policies`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`route_id`) REFERENCES `routes`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE TABLE `monitors` (
+	`id` text PRIMARY KEY NOT NULL,
+	`kind` text NOT NULL,
+	`target` text NOT NULL,
+	`interval_minutes` integer NOT NULL,
+	`severity` text DEFAULT 'critical' NOT NULL,
+	`suppressible` integer DEFAULT true NOT NULL,
+	`enabled` integer DEFAULT true NOT NULL,
+	`escalation_policy_id` text,
+	`last_run_at` integer,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`escalation_policy_id`) REFERENCES `escalation_policies`(`id`) ON UPDATE no action ON DELETE set null
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `monitors_kind_target_unique` ON `monitors` (`kind`,`target`);--> statement-breakpoint
+CREATE TABLE `monitor_runs` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`monitor_id` text NOT NULL,
+	`ran_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`outcome` text NOT NULL,
+	`error_message` text,
+	FOREIGN KEY (`monitor_id`) REFERENCES `monitors`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE TABLE `suppression_windows` (
+	`id` text PRIMARY KEY NOT NULL,
+	`source` text NOT NULL,
+	`scope_module_id` text NOT NULL,
+	`started_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`ends_at` integer,
+	FOREIGN KEY (`scope_module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE TABLE `alerts` (
+	`id` text PRIMARY KEY NOT NULL,
+	`key` text NOT NULL,
+	`active_key` text,
+	`monitor_id` text NOT NULL,
+	`state` text DEFAULT 'pending' NOT NULL,
+	`severity` text NOT NULL,
+	`first_fired_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`last_seen_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`grace_until` integer NOT NULL,
+	`suppressed_by_alert_id` text,
+	`suppressed_by_window_id` text,
+	`unsuppressed_at` integer,
+	`awaiting_confirmation` integer DEFAULT false NOT NULL,
+	`acked_by` text,
+	`acked_at` integer,
+	`silenced_until` integer,
+	`escalation_step` integer DEFAULT 0 NOT NULL,
+	`next_escalation_at` integer,
+	`deferred_until` integer,
+	`deferred_route_id` text,
+	`escalation_policy_id` text,
+	`message` text NOT NULL,
+	`details` text,
+	`resolved_at` integer,
+	FOREIGN KEY (`monitor_id`) REFERENCES `monitors`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`suppressed_by_window_id`) REFERENCES `suppression_windows`(`id`) ON UPDATE no action ON DELETE set null,
+	FOREIGN KEY (`acked_by`) REFERENCES `people`(`id`) ON UPDATE no action ON DELETE set null,
+	FOREIGN KEY (`deferred_route_id`) REFERENCES `routes`(`id`) ON UPDATE no action ON DELETE set null,
+	FOREIGN KEY (`escalation_policy_id`) REFERENCES `escalation_policies`(`id`) ON UPDATE no action ON DELETE set null
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `alerts_live_key_idx` ON `alerts` (`active_key`);--> statement-breakpoint
+CREATE INDEX `alerts_key_idx` ON `alerts` (`key`);--> statement-breakpoint
+CREATE TABLE `notification_deliveries` (
+	`id` text PRIMARY KEY NOT NULL,
+	`token` text NOT NULL,
+	`kind` text NOT NULL,
+	`target_id` text NOT NULL,
+	`route_id` text NOT NULL,
+	`sent_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`expires_at` integer NOT NULL,
+	`consumed_at` integer,
+	FOREIGN KEY (`route_id`) REFERENCES `routes`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `notification_deliveries_token_unique` ON `notification_deliveries` (`token`);

package/drizzle/meta/_journal.json

@@ -113,6 +113,20 @@
       "when": 1783100000000,
       "tag": "0015_port_forwards",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "6",
+      "when": 1783200000000,
+      "tag": "0016_trusted_sources",
+      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "6",
+      "when": 1783300000000,
+      "tag": "0017_alerting",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.13.3",
+  "version": "0.14.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "schemas/",
     "tsconfig.json",
     "AGENTS.md",
+    "docs/",
     "CELILO_SUBSYSTEMS.md",
     "CELILO_CORE_MODULES.md",
     "MODULE_PRIMITIVES.md"
@@ -56,7 +57,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
-    "@celilo/capabilities": "^0.7.1",
+    "@celilo/capabilities": "^0.9.0",
     "@celilo/cli-display": "^0.1.9",
     "@celilo/core": "^0.1.0",
     "@celilo/event-bus": "^0.1.8",

package/schemas/system_config.json

@@ -74,6 +74,11 @@
       "maximum": 4094,
       "description": "VLAN tag for internal zone (not defaulted; internal is untagged)"
     },
+    "network.vpn.subnet": {
+      "type": "string",
+      "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
+      "description": "WireGuard VPN client subnet CIDR (remote-access tunnel; consumed by technitium's split-horizon → in-zone caddy view, #275, and by the firewall's trusted sources once the wireguard module registers it)"
+    },
     "network.secure-mgmt.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
@@ -90,6 +95,10 @@
       "maximum": 4094,
       "description": "VLAN tag for the control-plane zone (not defaulted)"
     },
+    "firewall.trusted_subnets": {
+      "type": "string",
+      "description": "Operator-declared trusted source subnets (comma-separated CIDRs) permitted to reach every managed zone. ADDITIVE to the control-plane subnet celilo derives and to the sources modules register — it cannot drop control-plane trust, which would block the SSH every hook and converge runs over."
+    },
     "dns.primary": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",

package/src/cli/commands/alerts-act.ts

@@ -0,0 +1,107 @@
+/**
+ * `celilo alerts ack|silence|resolve` — the operator's side of the ack loop.
+ *
+ * Alerts are addressed by KEY, not id. The key is what `celilo alerts list`
+ * prints and what arrives in a page, so it is the only identifier an operator
+ * ever has in hand.
+ */
+
+import { getDb } from '../../db/client';
+import { parseIntervalMinutes } from '../../manifest/schema';
+import {
+  acknowledgeAlert,
+  findLiveAlertByKey,
+  resolveAlertManually,
+  silenceAlert,
+} from '../../services/alerting/ack';
+import { findPerson, listPeople } from '../../services/alerting/people';
+import type { CommandResult } from '../types';
+
+function resolveKey(key: string | undefined) {
+  if (!key) return { error: 'An alert key is required. Run "celilo alerts list" to see them.' };
+  const db = getDb();
+  const alert = findLiveAlertByKey(db, key);
+  if (!alert) {
+    return {
+      error: `No live alert with key "${key}".\n\nRun "celilo alerts list" to see current alerts.`,
+    };
+  }
+  return { db, alert };
+}
+
+export async function handleAlertsAck(
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  const found = resolveKey(args[0]);
+  if (found.error !== undefined) return { success: false, error: found.error };
+  const { db, alert } = found;
+
+  // Who is acknowledging matters: it stops escalation AND tells everyone else
+  // who was paged that somebody has it.
+  const who = typeof flags.as === 'string' ? flags.as : undefined;
+  const people = listPeople(db);
+  if (!who) {
+    if (people.length !== 1) {
+      return {
+        success: false,
+        error: `Who is acknowledging? Pass --as <person>.\n\nKnown people: ${people.map((p) => p.name).join(', ') || '(none configured)'}`,
+      };
+    }
+  }
+  const person = who ? findPerson(db, who) : people[0];
+  if (!person) return { success: false, error: `No person named "${who}".` };
+
+  const result = acknowledgeAlert(db, alert.id, person.id, new Date());
+  if (!result) return { success: false, error: 'Alert vanished while acknowledging.' };
+
+  const broadcast = result.broadcastTo.length
+    ? ` — ${result.broadcastTo.length} other route(s) will be told`
+    : '';
+  return { success: true, message: `${alert.key} acknowledged by ${person.name}${broadcast}` };
+}
+
+export async function handleAlertsSilence(
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  const found = resolveKey(args[0]);
+  if (found.error !== undefined) return { success: false, error: found.error };
+  const { db, alert } = found;
+
+  const forFlag = typeof flags.for === 'string' ? flags.for : '2h';
+  const minutes = parseIntervalMinutes(forFlag);
+  if (minutes === null) {
+    return {
+      success: false,
+      error: `Invalid --for "${forFlag}". Use a duration like 2h, 30m, 1d.`,
+    };
+  }
+
+  const until = new Date(Date.now() + minutes * 60_000);
+  silenceAlert(db, alert.id, until);
+  return {
+    success: true,
+    message: `${alert.key} silenced for ${forFlag} (until ${until.toISOString()})`,
+  };
+}
+
+export async function handleAlertsResolve(args: string[]): Promise<CommandResult> {
+  const found = resolveKey(args[0]);
+  if (found.error !== undefined) return { success: false, error: found.error };
+  const { db, alert } = found;
+
+  resolveAlertManually(db, alert.id, new Date());
+  return {
+    success: true,
+    // Resolve does not override the monitor, and saying so is the whole point
+    // of the message — an operator who thinks it does will trust a cleared
+    // alert that is about to come back.
+    //
+    // What it IS for: you have just fixed something and the check runs every
+    // fifteen minutes. This stops the stale `firing` row escalating at you
+    // while you wait for the next run to agree.
+    message: `${alert.key} resolved.
+  The monitor is still the authority: if the check still fails, this fires again on the next sweep.`,
+  };
+}

package/src/cli/commands/alerts-list.ts

@@ -0,0 +1,62 @@
+/**
+ * `celilo alerts list` — what is currently wrong, and what is already accounted for.
+ *
+ * Thin adapter (Rule 10.5): read, delegate, format, return. The ordering,
+ * wording, and the "explained by something upstream" column all live in
+ * services/alerting/format.ts where they are unit-tested.
+ */
+
+import { getDb } from '../../db/client';
+import { renderAlertTable, toAlertRow } from '../../services/alerting/format';
+import { loadAllLiveAlerts } from '../../services/alerting/store';
+import type { CommandResult } from '../types';
+
+export async function handleAlertsList(
+  _args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  const db = getDb();
+  const now = new Date();
+  const live = loadAllLiveAlerts(db);
+
+  if (flags.json) {
+    return {
+      success: true,
+      message: JSON.stringify(
+        live.map((alert) => ({
+          key: alert.key,
+          state: alert.state,
+          severity: alert.severity,
+          firstFiredAt: alert.firstFiredAt,
+          lastSeenAt: alert.lastSeenAt,
+          suppressed: alert.state === 'suppressed',
+          suppressedByAlertId: alert.suppressedByAlertId,
+          suppressedByWindowId: alert.suppressedByWindowId,
+          awaitingConfirmation: alert.awaitingConfirmation,
+          ackedBy: alert.ackedBy,
+          silencedUntil: alert.silencedUntil,
+          message: alert.message,
+        })),
+        null,
+        2,
+      ),
+      rawOutput: true,
+    };
+  }
+
+  const table = renderAlertTable(live.map((alert) => toAlertRow(alert, now)));
+  console.log('');
+  console.log(table);
+  console.log('');
+
+  const firing = live.filter((a) => a.state === 'firing').length;
+  const suppressed = live.filter((a) => a.state === 'suppressed').length;
+
+  return {
+    success: true,
+    message:
+      live.length === 0
+        ? 'No alerts'
+        : `${firing} firing, ${suppressed} suppressed, ${live.length} live`,
+  };
+}

package/src/cli/commands/alerts-poll.ts

@@ -0,0 +1,129 @@
+/**
+ * `celilo alerts poll` — read replies off every bidirectional transport once.
+ *
+ * Runs far more often than the five-minute sweep: "I texted ack and nothing
+ * happened" is the experience this exists to prevent. Registered on
+ * `timer.tick.5m` like the sweep, but also safe to run by hand or from a
+ * tighter loop.
+ *
+ * The receive cursor is persisted in system config rather than memory, so a
+ * restart resumes where it left off instead of re-reading or skipping.
+ */
+
+import { eq } from 'drizzle-orm';
+import { getEventBusPath } from '../../config/paths';
+import { getDb } from '../../db/client';
+import { systemConfig } from '../../db/schema';
+import { makeReceiver, pollInbound } from '../../services/alerting/inbound-poller';
+import { startNotificationResponder } from '../../services/alerting/notification-responder';
+import { listRoutes } from '../../services/alerting/people';
+import { loadNotificationTransport } from '../../services/alerting/transport-loader';
+import type { CommandResult } from '../types';
+
+/** How long a reply token stays usable. A deploy may wait overnight. */
+const INTERVIEW_TTL_MS = 24 * 60 * 60_000;
+
+const CURSOR_PREFIX = 'alerting.inbound_cursor.';
+
+function readCursor(db: ReturnType<typeof getDb>, transportModuleId: string): string | null {
+  const key = `${CURSOR_PREFIX}${transportModuleId}`;
+  const row = db.select().from(systemConfig).where(eq(systemConfig.key, key)).get();
+  return row?.value ?? null;
+}
+
+function writeCursor(
+  db: ReturnType<typeof getDb>,
+  transportModuleId: string,
+  cursor: string | null,
+): void {
+  const key = `${CURSOR_PREFIX}${transportModuleId}`;
+  if (cursor === null) return;
+  const existing = db.select().from(systemConfig).where(eq(systemConfig.key, key)).get();
+  if (existing) {
+    db.update(systemConfig).set({ value: cursor }).where(eq(systemConfig.key, key)).run();
+  } else {
+    db.insert(systemConfig)
+      .values({
+        key,
+        value: cursor,
+        description: `Inbound receive cursor for ${transportModuleId}`,
+      })
+      .run();
+  }
+}
+
+export async function handleAlertsPoll(
+  flags: Record<string, string | boolean> = {},
+): Promise<CommandResult> {
+  const db = getDb();
+  const askErrors: string[] = [];
+
+  // `--ask-after 0` asks immediately. Useful for an operator who wants a
+  // question escalated now, and for tests that would otherwise wait out the
+  // grace.
+  const raw = flags['ask-after'];
+  const askAfterSeconds = typeof raw === 'string' ? Number.parseInt(raw, 10) : null;
+  if (raw !== undefined && (askAfterSeconds === null || Number.isNaN(askAfterSeconds))) {
+    return { success: false, error: '--ask-after expects a number of seconds' };
+  }
+
+  // The responder both DELIVERS unanswered questions and publishes the
+  // answers. Both halves belong here: a question delivered by a process that
+  // then exits is still answerable, because what was asked lives in the
+  // deliveries table rather than in that process's memory.
+  const responder = startNotificationResponder({
+    db,
+    busDbPath: getEventBusPath(),
+    routes: listRoutes(db).filter((route) => route.enabled && route.canAck),
+    transportFor: (route) => loadNotificationTransport(db, route.transportModuleId),
+    // A CLI invocation is never the terminal responder for someone else's
+    // deploy — that responder attaches to its own deploy's stdin.
+    hasTty: () => false,
+    now: () => new Date(),
+    ttlMs: INTERVIEW_TTL_MS,
+    askAfterMs: askAfterSeconds === null ? undefined : askAfterSeconds * 1000,
+    onSendFailed: (eventType, error) => askErrors.push(`${eventType}: ${error}`),
+  });
+
+  let ask = { asked: 0, failed: 0 };
+  try {
+    ask = await responder.poll();
+  } catch {
+    // A bus that cannot be opened must not stop alert replies being read —
+    // those are the 3am path.
+  }
+
+  const report = await pollInbound(db, {
+    receiveFrom: makeReceiver(db),
+    readCursor: (t) => readCursor(db, t),
+    writeCursor: (t, c) => writeCursor(db, t, c),
+    now: () => new Date(),
+    transportFor: (route) => loadNotificationTransport(db, route.transportModuleId),
+    answerInterview: (eventId, value) => responder.answer(eventId, value),
+  });
+
+  responder.stop();
+
+  // Rejections are worth surfacing rather than counting silently: a run of
+  // them means someone is replying and not being heard, which looks identical
+  // to the alerting system being broken.
+  const parts = [
+    `${report.transportsPolled} transport(s)`,
+    `${report.messagesRead} message(s)`,
+    `${report.acked} acked`,
+  ];
+  if (report.rejected > 0) parts.push(`${report.rejected} rejected`);
+  if (report.ignored > 0) parts.push(`${report.ignored} from unknown senders`);
+  if (report.broadcast > 0) parts.push(`${report.broadcast} told someone has it`);
+  if (report.answered > 0) parts.push(`${report.answered} deploy question(s) answered`);
+  if (ask.asked > 0) parts.push(`${ask.asked} question(s) asked`);
+  // Never silent: a deploy blocked on a question nobody received is
+  // indistinguishable from a deploy that is merely slow.
+  if (ask.failed > 0) parts.push(`${ask.failed} question(s) COULD NOT BE DELIVERED`);
+
+  const message = `inbound poll: ${parts.join(', ')}`;
+  return {
+    success: true,
+    message: askErrors.length > 0 ? `${message}\n  ${askErrors.join('\n  ')}` : message,
+  };
+}

package/src/cli/commands/alerts-sweep.ts

@@ -0,0 +1,156 @@
+/**
+ * `celilo alerts sweep` — one pass of the alerting loop.
+ *
+ * Invoked by the event-bus dispatcher on `timer.tick.5m`, not by a human. It
+ * is a normal command so the dispatcher's existing subprocess isolation,
+ * retry, and timeout apply unchanged — the sweep gets those for free rather
+ * than reimplementing them.
+ *
+ * Thin adapter (Rule 10.5): compose the real dependencies, call runSweep,
+ * report counts.
+ */
+
+import { eq } from 'drizzle-orm';
+import { getDb } from '../../db/client';
+import { type Alert, escalationPolicies, modules } from '../../db/schema';
+import { runBuiltinCheckForMonitor } from '../../services/alerting/builtin-source';
+import { loadModuleCoverage } from '../../services/alerting/coverage-source';
+import { modulesInDeployWindow } from '../../services/alerting/deploy-hooks';
+import { listMonitors } from '../../services/alerting/monitors';
+import type { NotifyDeps } from '../../services/alerting/notifier';
+import { listPeople, listPolicySteps, listRoutes } from '../../services/alerting/people';
+import type { SuppressionTopology } from '../../services/alerting/suppression';
+import { runSweep } from '../../services/alerting/sweep-runner';
+import { mintDelivery } from '../../services/alerting/tokens';
+import { loadNotificationTransport } from '../../services/alerting/transport-loader';
+import { getModuleSystems } from '../../services/deployed-systems';
+import { runModuleHealthCheck } from '../../services/health-runner';
+import type { CommandResult } from '../types';
+
+/** Grace window before a newly-fired alert may notify. */
+const DEFAULT_GRACE_MS = 60_000;
+
+/**
+ * How long a reply token stays valid. A day is long enough that someone who
+ * sees a page overnight can still act on it in the morning, and short enough
+ * that a token found later is useless.
+ */
+const TOKEN_TTL_MS = 24 * 60 * 60_000;
+
+/**
+ * Deployment topology for suppression, read once per sweep.
+ *
+ * Derived from what celilo already records — asking an operator to restate it
+ * would guarantee it drifts, and a stale suppression graph hides real
+ * failures rather than merely being untidy.
+ */
+function loadTopology(db: ReturnType<typeof getDb>): SuppressionTopology {
+  const moduleRows = db.select({ id: modules.id }).from(modules).all();
+  const moduleSystems = moduleRows.flatMap((module) =>
+    getModuleSystems(module.id, db).map((system) => ({
+      moduleId: module.id,
+      hostname: system.hostname,
+      zone: system.zone,
+      infraType: system.infrastructure.type,
+    })),
+  );
+  // Zone-capability providers are wired in a follow-up; an empty list means
+  // only the machine edge is active, which is the MVP scope.
+  return { moduleSystems, zoneProviders: [] };
+}
+
+/**
+ * Assemble everything needed to page for one alert, or null when nobody can be.
+ *
+ * Returning null rather than an empty policy is deliberate: "no escalation
+ * policy assigned" and "policy exists but nobody is eligible" are different
+ * situations, and only the second is worth an escalation decision.
+ */
+function buildNotifyDeps(db: ReturnType<typeof getDb>, alert: Alert): NotifyDeps | null {
+  if (!alert.escalationPolicyId) return null;
+
+  const policy = db
+    .select()
+    .from(escalationPolicies)
+    .where(eq(escalationPolicies.id, alert.escalationPolicyId))
+    .get();
+  if (!policy) return null;
+
+  const steps = listPolicySteps(db, policy.id).map((step) => ({
+    stepIndex: step.stepIndex,
+    routeId: step.routeId,
+    delayMinutes: step.delayMinutes,
+  }));
+  if (steps.length === 0) return null;
+
+  const routeRows = listRoutes(db);
+  const people = listPeople(db);
+
+  return {
+    steps,
+    routes: new Map(
+      routeRows.map((r) => [
+        r.id,
+        { id: r.id, severityFloor: r.severityFloor, enabled: r.enabled },
+      ]),
+    ),
+    routeDetails: new Map(routeRows.map((r) => [r.id, r])),
+    quietHoursByPerson: new Map(
+      people
+        .filter((p) => p.quietHoursStart && p.quietHoursEnd)
+        .map((p) => [
+          p.id,
+          {
+            personId: p.id,
+            start: p.quietHoursStart,
+            end: p.quietHoursEnd,
+            timezone: p.timezone,
+          },
+        ]),
+    ),
+    bypassQuietHours: policy.bypassQuietHours,
+    transportFor: (route) => loadNotificationTransport(db, route.transportModuleId),
+    mintToken: (alertId, routeId) =>
+      mintDelivery(db, {
+        kind: 'alert',
+        targetId: alertId,
+        routeId,
+        now: new Date(),
+        ttlMs: TOKEN_TTL_MS,
+      }).token,
+    now: new Date(),
+  };
+}
+
+export async function handleAlertsSweep(): Promise<CommandResult> {
+  const db = getDb();
+  const monitorRows = listMonitors(db);
+
+  const suppressibleByMonitor = new Map(monitorRows.map((m) => [m.id, m.suppressible]));
+
+  const report = await runSweep(db, monitorRows, {
+    monitorDeps: {
+      runModuleCheck: (moduleId: string) =>
+        runModuleHealthCheck(moduleId, db, { unattended: true, noInteractive: true }),
+      runBuiltinCheck: (category) => runBuiltinCheckForMonitor(category),
+      loadModuleCoverage: () => loadModuleCoverage(db),
+      now: () => new Date(),
+      graceMs: DEFAULT_GRACE_MS,
+    },
+    loadTopology: () => loadTopology(db),
+    loadDeployWindowModules: () => modulesInDeployWindow(db),
+    isSuppressible: (alert) => suppressibleByMonitor.get(alert.monitorId) ?? true,
+    notifyDepsFor: (alert) => buildNotifyDeps(db, alert),
+    now: () => new Date(),
+  });
+
+  const parts = [
+    `${report.monitorsRun} run`,
+    `${report.monitorsErrored} errored`,
+    `${report.promoted} promoted`,
+    `${report.suppressed} suppressed`,
+    `${report.unsuppressed} unsuppressed`,
+    `${report.notified} notified`,
+  ];
+  return { success: true, message: `alert sweep: ${parts.join(', ')}` };
+}