@celilo/cli 0.13.2 → 0.14.0

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

@@ -1,5 +1,8 @@
-import { getDb } from '../../db/client';
-import { modules } from '../../db/schema';
+import { eq } from 'drizzle-orm';
+import { type DbClient, getDb } from '../../db/client';
+import { modules, modules as modulesTable, monitors } from '../../db/schema';
+import { moduleHealthCell } from '../../services/alerting/format';
+import { loadAllLiveAlerts, summariseByModule } from '../../services/alerting/store';
 import { hasFlag } from '../parser';
 import type { CommandResult } from '../types';
 
@@ -36,10 +39,18 @@ export async function handleModuleList(
     };
   }
 
+  // Observed health, derived from live alerts rather than from module state.
+  // The two answer different questions: `state` says whether someone
+  // deliberately verified this module, `health` says whether it is working
+  // right now. "not observed" is a finding, not a blank — see design D15.
+  const health = loadObservedHealth(db);
+
   // Format module list
   const lines = ['Installed modules:', ''];
   for (const module of moduleRows) {
-    lines.push(`${module.id} (v${module.version}) - ${module.state}`);
+    const observed = health.get(module.id);
+    const healthNote = observed ? `  [${observed}]` : '';
+    lines.push(`${module.id} (v${module.version}) - ${module.state}${healthNote}`);
     if (module.description) {
       lines.push(`  ${module.description}`);
     }
@@ -55,3 +66,39 @@ export async function handleModuleList(
     data: moduleRows,
   };
 }
+
+/**
+ * Observed health per module: `ok`, `N firing`, `suppressed`, or
+ * `not observed`.
+ *
+ * Only computed for DEPLOYED modules — a module still being imported has
+ * nothing to observe, and reporting it as unwatched would be noise rather
+ * than a finding.
+ */
+function loadObservedHealth(db: DbClient): Map<string, string> {
+  const monitored = new Set(
+    db
+      .select({ target: monitors.target })
+      .from(monitors)
+      .where(eq(monitors.enabled, true))
+      .all()
+      .map((m) => m.target),
+  );
+  const byModule = summariseByModule(loadAllLiveAlerts(db));
+
+  const result = new Map<string, string>();
+  for (const module of db.select().from(modulesTable).all()) {
+    if (module.state !== 'INSTALLED' && module.state !== 'VERIFIED') continue;
+
+    const summary = byModule.get(module.id) ?? [];
+    result.set(
+      module.id,
+      moduleHealthCell({
+        monitored: monitored.has(module.id),
+        firingCount: summary.filter((s) => !s.suppressed).length,
+        suppressed: summary.length > 0 && summary.every((s) => s.suppressed),
+      }),
+    );
+  }
+  return result;
+}

package/src/cli/commands/monitor.ts

@@ -0,0 +1,178 @@
+/**
+ * `celilo monitor` — what celilo is watching, and running a check on demand.
+ *
+ * Thin adapter (Rule 10.5): parse, delegate, format. The scheduling decisions
+ * live in services/alerting/, and this command composes the real health runner
+ * and audit checks into the injectable deps `runOneMonitor` expects.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+import { getEventBusPath } from '../../config/paths';
+import { getDb } from '../../db/client';
+import type { MonitorKind } from '../../db/schema';
+import { parseIntervalMinutes } from '../../manifest/schema';
+import { runBuiltinCheckForMonitor } from '../../services/alerting/builtin-source';
+import { loadModuleCoverage } from '../../services/alerting/coverage-source';
+import { HEALTH_COVERAGE_CHECK } from '../../services/alerting/health-coverage';
+import {
+  createMonitor,
+  ensureSweepSubscriber,
+  findMonitorByTarget,
+  listMonitors,
+  setMonitorEnabled,
+} from '../../services/alerting/monitors';
+import { runOneMonitor } from '../../services/alerting/run-monitor';
+import { promoteReadyAlerts } from '../../services/alerting/store';
+import type { DriftCategory } from '../../services/audit/types';
+import { runModuleHealthCheck } from '../../services/health-runner';
+import type { CommandResult } from '../types';
+
+const NO_SCHEMAS = defineEvents({});
+
+/** Grace window before a newly-fired alert may notify. */
+const DEFAULT_GRACE_MS = 60_000;
+
+function buildDeps() {
+  const db = getDb();
+  return {
+    runModuleCheck: (moduleId: string) =>
+      runModuleHealthCheck(moduleId, db, { unattended: true, noInteractive: true }),
+    runBuiltinCheck: (category: DriftCategory) => runBuiltinCheckForMonitor(category),
+    loadModuleCoverage: () => loadModuleCoverage(db),
+    now: () => new Date(),
+    graceMs: DEFAULT_GRACE_MS,
+  };
+}
+
+function handleList(): CommandResult {
+  const rows = listMonitors(getDb());
+  if (rows.length === 0) {
+    console.log('\nNo monitors configured.\n');
+    console.log('A module declaring hooks.health_check.interval gets one on deploy,');
+    console.log('or add one directly:  celilo monitor add <module> --interval 15m\n');
+    return { success: true, message: 'No monitors configured' };
+  }
+
+  const width = Math.max(6, ...rows.map((r) => r.target.length));
+  console.log('');
+  console.log(`${'TARGET'.padEnd(width)}  ${'KIND'.padEnd(14)}  ${'EVERY'.padEnd(6)}  STATE`);
+  for (const monitor of rows) {
+    const state = monitor.enabled ? 'enabled' : 'disabled';
+    const suffix = monitor.lastRunAt ? '' : '  (never run)';
+    const every = `${monitor.intervalMinutes}m`;
+    console.log(
+      `${monitor.target.padEnd(width)}  ${monitor.kind.padEnd(14)}  ${every.padEnd(6)}  ${state}${suffix}`,
+    );
+  }
+  console.log('');
+  return { success: true, message: `${rows.length} monitor(s)` };
+}
+
+function handleAdd(args: string[], flags: Record<string, boolean | string>): CommandResult {
+  const target = args[0];
+  if (!target) {
+    return { success: false, error: 'Usage: celilo monitor add <target> [--interval 15m]' };
+  }
+
+  const db = getDb();
+  if (findMonitorByTarget(db, target)) {
+    return { success: false, error: `A monitor for "${target}" already exists.` };
+  }
+
+  const interval = typeof flags.interval === 'string' ? flags.interval : '15m';
+  const intervalMinutes = parseIntervalMinutes(interval);
+  if (intervalMinutes === null) {
+    return {
+      success: false,
+      error: `Invalid --interval "${interval}". Use a duration like "15m", "1h", or "1d".`,
+    };
+  }
+
+  // A target naming an audit category is a built-in check; anything else is a
+  // module's health_check hook.
+  const kind: MonitorKind =
+    target === HEALTH_COVERAGE_CHECK || target.includes('_') ? 'builtin_check' : 'module_hook';
+
+  createMonitor(db, { kind, target, intervalMinutes });
+
+  // Creating the first monitor is also what switches the sweep on. Registering
+  // here rather than at install means a celilo with no monitors carries no
+  // subscriber and does no periodic work.
+  const bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+  try {
+    ensureSweepSubscriber(bus);
+  } finally {
+    bus.close();
+  }
+
+  return {
+    success: true,
+    message: `Monitoring ${target} every ${interval} (sweep runs on timer.tick.5m)`,
+  };
+}
+
+async function handleRun(args: string[]): Promise<CommandResult> {
+  const target = args[0];
+  if (!target) return { success: false, error: 'Usage: celilo monitor run <target>' };
+
+  const db = getDb();
+  const monitor = findMonitorByTarget(db, target);
+  if (!monitor) {
+    return {
+      success: false,
+      error: `No monitor for "${target}".\n\nRun "celilo monitor list" to see configured monitors.`,
+    };
+  }
+
+  const summary = await runOneMonitor(db, monitor, buildDeps());
+  promoteReadyAlerts(db, new Date());
+
+  if (summary.outcome === 'error') {
+    return {
+      success: true,
+      message: `${target}: check could not run — ${summary.errorMessage ?? 'unknown error'}`,
+    };
+  }
+  return {
+    success: true,
+    message: `${target}: ${summary.failingKeyCount} failing, ${summary.resolvedIds.length} resolved`,
+  };
+}
+
+function handleToggle(args: string[], enabled: boolean): CommandResult {
+  const target = args[0];
+  const verb = enabled ? 'enable' : 'disable';
+  if (!target) return { success: false, error: `Usage: celilo monitor ${verb} <target>` };
+
+  const db = getDb();
+  const monitor = findMonitorByTarget(db, target);
+  if (!monitor) return { success: false, error: `No monitor for "${target}".` };
+
+  setMonitorEnabled(db, monitor.id, enabled, new Date());
+  return { success: true, message: `Monitor for ${target} ${enabled ? 'enabled' : 'disabled'}` };
+}
+
+export async function handleMonitor(
+  subcommand: string | undefined,
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  switch (subcommand) {
+    case undefined:
+    case 'list':
+      return handleList();
+    case 'add':
+      return handleAdd(args, flags);
+    case 'run':
+      return handleRun(args);
+    case 'enable':
+      return handleToggle(args, true);
+    case 'disable':
+      return handleToggle(args, false);
+    default:
+      return {
+        success: false,
+        error: `Unknown monitor subcommand: ${subcommand}\n\nUse: list, add, run, enable, disable`,
+      };
+  }
+}

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

@@ -0,0 +1,453 @@
+/**
+ * `celilo person` / `route` / `escalation-policy` — who celilo can reach.
+ *
+ * One file because the three are a single concept split across three tables,
+ * and splitting the CLI too would mean three copies of the same lookup-by-name
+ * and table-printing code.
+ *
+ * Everything is addressed by name. A UUID never reaches the operator
+ * (CLAUDE.md), and a route is identified by `<person>/<transport>` rather than
+ * by an id, because that is what someone actually knows about it.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+import { eq } from 'drizzle-orm';
+import { getEventBusPath } from '../../config/paths';
+import { getDb } from '../../db/client';
+import { type AlertSeverity, modules, monitors } from '../../db/schema';
+import { ensureInboundSubscriber, findMonitorByTarget } from '../../services/alerting/monitors';
+import {
+  addPolicyStep,
+  createPerson,
+  createPolicy,
+  createRoute,
+  deletePerson,
+  deletePolicy,
+  deleteRoute,
+  findPerson,
+  findPolicy,
+  findRoute,
+  listPeople,
+  listPolicies,
+  listPolicySteps,
+  listRoutes,
+} from '../../services/alerting/people';
+import { parseClockTime } from '../../services/alerting/quiet-hours';
+import type { CommandResult } from '../types';
+
+const NO_SCHEMAS = defineEvents({});
+
+function table(headers: string[], rows: string[][]): string {
+  if (rows.length === 0) return '';
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const line = (cells: string[]) =>
+    cells
+      .map((c, i) => (i === cells.length - 1 ? c : c.padEnd(widths[i])))
+      .join('  ')
+      .trimEnd();
+  return [line(headers), ...rows.map(line)].join('\n');
+}
+
+const flagString = (flags: Record<string, boolean | string>, name: string): string | undefined =>
+  typeof flags[name] === 'string' ? (flags[name] as string) : undefined;
+
+/**
+ * Whether a module declares the `notification` capability.
+ *
+ * Read from the manifest rather than the capabilities table: a module can be
+ * imported but not yet deployed, and configuring a route ahead of deploying
+ * the transport is a reasonable order to work in.
+ */
+function providesNotification(db: ReturnType<typeof getDb>, moduleId: string): boolean {
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) return false;
+  const manifest = module.manifestData as {
+    provides?: { capabilities?: { name?: string }[] };
+  };
+  return Boolean(manifest.provides?.capabilities?.some((c) => c.name === 'notification'));
+}
+
+// ── celilo person ───────────────────────────────────────────────────────────
+
+function personAdd(args: string[], flags: Record<string, boolean | string>): CommandResult {
+  const name = args[0];
+  if (!name) {
+    return {
+      success: false,
+      error: 'Usage: celilo person add <name> --timezone <IANA> [--quiet-hours 22:00-07:00]',
+    };
+  }
+
+  const db = getDb();
+  if (findPerson(db, name)) return { success: false, error: `Person "${name}" already exists.` };
+
+  const timezone = flagString(flags, 'timezone');
+  if (!timezone) {
+    return {
+      success: false,
+      error: 'A --timezone is required (e.g. America/Los_Angeles) — quiet hours are local to it.',
+    };
+  }
+
+  let quietStart: string | null = null;
+  let quietEnd: string | null = null;
+  const quiet = flagString(flags, 'quiet-hours');
+  if (quiet) {
+    const [start, end] = quiet.split('-');
+    if (!start || !end || parseClockTime(start) === null || parseClockTime(end) === null) {
+      return {
+        success: false,
+        error: `Invalid --quiet-hours "${quiet}". Use HH:MM-HH:MM, e.g. 22:00-07:00.`,
+      };
+    }
+    quietStart = start;
+    quietEnd = end;
+  }
+
+  createPerson(db, { name, timezone, quietHoursStart: quietStart, quietHoursEnd: quietEnd });
+  const quietNote = quiet ? `, quiet ${quiet}` : ', always reachable';
+  return { success: true, message: `Added ${name} (${timezone}${quietNote})` };
+}
+
+function personList(): CommandResult {
+  const people = listPeople(getDb());
+  if (people.length === 0) {
+    console.log('\nNobody configured.\n');
+    console.log(
+      '  celilo person add peter --timezone America/Los_Angeles --quiet-hours 22:00-07:00\n',
+    );
+    return { success: true, message: 'No people configured' };
+  }
+
+  console.log('');
+  console.log(
+    table(
+      ['NAME', 'TIMEZONE', 'QUIET HOURS'],
+      people.map((p) => [
+        p.name,
+        p.timezone,
+        p.quietHoursStart && p.quietHoursEnd
+          ? `${p.quietHoursStart}-${p.quietHoursEnd}`
+          : 'always reachable',
+      ]),
+    ),
+  );
+  console.log('');
+  return { success: true, message: `${people.length} person(s)` };
+}
+
+function personRemove(args: string[]): CommandResult {
+  const name = args[0];
+  if (!name) return { success: false, error: 'Usage: celilo person remove <name>' };
+
+  const db = getDb();
+  const person = findPerson(db, name);
+  if (!person) return { success: false, error: `No person named "${name}".` };
+
+  // Routes cascade, and so do the escalation steps pointing at them — a step
+  // aimed at a deleted route would otherwise skip silently at page time.
+  deletePerson(db, person.id);
+  return { success: true, message: `Removed ${name} and their routes` };
+}
+
+export async function handlePerson(
+  subcommand: string | undefined,
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  switch (subcommand) {
+    case undefined:
+    case 'list':
+      return personList();
+    case 'add':
+      return personAdd(args, flags);
+    case 'remove':
+      return personRemove(args);
+    default:
+      return {
+        success: false,
+        error: `Unknown person subcommand: ${subcommand}\n\nUse: list, add, remove`,
+      };
+  }
+}
+
+// ── celilo route ────────────────────────────────────────────────────────────
+
+function routeAdd(args: string[], flags: Record<string, boolean | string>): CommandResult {
+  const [personName, transport] = args;
+  const address = flagString(flags, 'address');
+  if (!personName || !transport || !address) {
+    return {
+      success: false,
+      error:
+        'Usage: celilo route add <person> <transport-module> --address <addr> [--severity-floor warning|critical]',
+    };
+  }
+
+  const db = getDb();
+  const person = findPerson(db, personName);
+  if (!person) return { success: false, error: `No person named "${personName}".` };
+
+  // Check the transport BEFORE inserting. The routes table has a foreign key
+  // to modules, so a typo would otherwise surface as a raw
+  // SQLITE_CONSTRAINT_FOREIGNKEY stack trace — which tells an operator
+  // nothing about what they got wrong.
+  const module = db.select().from(modules).where(eq(modules.id, transport)).get();
+  if (!module) {
+    const available = db.select({ id: modules.id }).from(modules).all();
+    const providers = available.filter((m) => providesNotification(db, m.id)).map((m) => m.id);
+    const hint = providers.length
+      ? `Available notification transports: ${providers.join(', ')}`
+      : 'No module providing the `notification` capability is installed yet.';
+    return { success: false, error: `No module "${transport}" is installed.\n\n${hint}` };
+  }
+
+  // A route to a module that cannot send is a route that silently never pages.
+  if (!providesNotification(db, transport)) {
+    return {
+      success: false,
+      error: `Module "${transport}" does not provide the \`notification\` capability, so it cannot page anyone.`,
+    };
+  }
+
+  if (findRoute(db, person.id, transport)) {
+    return { success: false, error: `${personName} already has a ${transport} route.` };
+  }
+
+  const floor = flagString(flags, 'severity-floor') ?? 'warning';
+  if (floor !== 'warning' && floor !== 'critical') {
+    return { success: false, error: `--severity-floor must be "warning" or "critical".` };
+  }
+
+  // A transport that can receive is one whose module is deployed AND provides
+  // a receive path. Until the inbound poller lands we record the operator's
+  // intent; a route that cannot ack simply never stops escalation.
+  const canAck = flags['can-ack'] === true;
+
+  createRoute(db, {
+    personId: person.id,
+    transportModuleId: transport,
+    address,
+    severityFloor: floor as AlertSeverity,
+    canAck,
+  });
+  // A route that can receive is what makes inbound polling worth doing, so
+  // that is when the subscriber is registered.
+  if (canAck) {
+    const bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+    try {
+      ensureInboundSubscriber(bus);
+    } finally {
+      bus.close();
+    }
+  }
+
+  return {
+    success: true,
+    message: `Reaching ${personName} via ${transport} at ${address} (floor: ${floor})`,
+  };
+}
+
+function routeList(): CommandResult {
+  const db = getDb();
+  const routes = listRoutes(db);
+  if (routes.length === 0) {
+    console.log('\nNo routes configured — nothing can be paged.\n');
+    console.log('  celilo route add peter signal --address +15551234567 --can-ack\n');
+    return { success: true, message: 'No routes configured' };
+  }
+
+  const people = new Map(listPeople(db).map((p) => [p.id, p.name]));
+  console.log('');
+  console.log(
+    table(
+      ['PERSON', 'TRANSPORT', 'ADDRESS', 'FLOOR', 'ACK', 'STATE'],
+      routes.map((r) => [
+        people.get(r.personId) ?? '(unknown)',
+        r.transportModuleId,
+        r.address,
+        r.severityFloor,
+        r.canAck ? 'yes' : 'no',
+        r.enabled ? 'enabled' : 'disabled',
+      ]),
+    ),
+  );
+  console.log('');
+  return { success: true, message: `${routes.length} route(s)` };
+}
+
+function routeRemove(args: string[]): CommandResult {
+  const [personName, transport] = args;
+  if (!personName || !transport) {
+    return { success: false, error: 'Usage: celilo route remove <person> <transport-module>' };
+  }
+
+  const db = getDb();
+  const person = findPerson(db, personName);
+  if (!person) return { success: false, error: `No person named "${personName}".` };
+  const route = findRoute(db, person.id, transport);
+  if (!route) return { success: false, error: `${personName} has no ${transport} route.` };
+
+  deleteRoute(db, route.id);
+  return { success: true, message: `Removed ${personName}'s ${transport} route` };
+}
+
+export async function handleRoute(
+  subcommand: string | undefined,
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  switch (subcommand) {
+    case undefined:
+    case 'list':
+      return routeList();
+    case 'add':
+      return routeAdd(args, flags);
+    case 'remove':
+      return routeRemove(args);
+    default:
+      return {
+        success: false,
+        error: `Unknown route subcommand: ${subcommand}\n\nUse: list, add, remove`,
+      };
+  }
+}
+
+// ── celilo escalation-policy ────────────────────────────────────────────────
+
+function policyAdd(args: string[]): CommandResult {
+  const name = args[0];
+  if (!name) return { success: false, error: 'Usage: celilo escalation-policy add <name>' };
+
+  const db = getDb();
+  if (findPolicy(db, name)) return { success: false, error: `Policy "${name}" already exists.` };
+
+  createPolicy(db, name);
+  return {
+    success: true,
+    message: `Created policy "${name}" — add steps with: celilo escalation-policy step ${name} <person> <transport> --after 0m`,
+  };
+}
+
+function policyStep(args: string[], flags: Record<string, boolean | string>): CommandResult {
+  const [policyName, personName, transport] = args;
+  if (!policyName || !personName || !transport) {
+    return {
+      success: false,
+      error:
+        'Usage: celilo escalation-policy step <policy> <person> <transport-module> --after <minutes>',
+    };
+  }
+
+  const db = getDb();
+  const policy = findPolicy(db, policyName);
+  if (!policy) return { success: false, error: `No policy named "${policyName}".` };
+  const person = findPerson(db, personName);
+  if (!person) return { success: false, error: `No person named "${personName}".` };
+  const route = findRoute(db, person.id, transport);
+  if (!route) {
+    return {
+      success: false,
+      error: `${personName} has no ${transport} route. Add one first:\n  celilo route add ${personName} ${transport} --address <addr>`,
+    };
+  }
+
+  const after = flagString(flags, 'after') ?? '0';
+  const delayMinutes = Number.parseInt(after.replace(/m$/, ''), 10);
+  if (!Number.isFinite(delayMinutes) || delayMinutes < 0) {
+    return { success: false, error: `Invalid --after "${after}". Use minutes, e.g. 0, 10, 30.` };
+  }
+
+  const step = addPolicyStep(db, policy.id, route.id, delayMinutes);
+  return {
+    success: true,
+    message: `Step ${step.stepIndex}: ${personName} via ${transport} after ${delayMinutes}m`,
+  };
+}
+
+function policyList(): CommandResult {
+  const db = getDb();
+  const policies = listPolicies(db);
+  if (policies.length === 0) {
+    console.log('\nNo escalation policies.\n');
+    console.log('  celilo escalation-policy add default\n');
+    return { success: true, message: 'No policies configured' };
+  }
+
+  const people = new Map(listPeople(db).map((p) => [p.id, p.name]));
+  const routes = new Map(listRoutes(db).map((r) => [r.id, r]));
+
+  console.log('');
+  for (const policy of policies) {
+    const steps = listPolicySteps(db, policy.id);
+    console.log(`${policy.name}${policy.bypassQuietHours ? '  (bypasses quiet hours)' : ''}`);
+    if (steps.length === 0) {
+      console.log('  (no steps — nothing will be paged)');
+    }
+    for (const step of steps) {
+      const route = routes.get(step.routeId);
+      const who = route ? (people.get(route.personId) ?? '(unknown)') : '(deleted route)';
+      const via = route ? route.transportModuleId : '?';
+      console.log(`  ${step.stepIndex}. ${who} via ${via} after ${step.delayMinutes}m`);
+    }
+    console.log('');
+  }
+  return { success: true, message: `${policies.length} polic(ies)` };
+}
+
+function policyRemove(args: string[]): CommandResult {
+  const name = args[0];
+  if (!name) return { success: false, error: 'Usage: celilo escalation-policy remove <name>' };
+
+  const db = getDb();
+  const policy = findPolicy(db, name);
+  if (!policy) return { success: false, error: `No policy named "${name}".` };
+
+  deletePolicy(db, policy.id);
+  return { success: true, message: `Removed policy "${name}"` };
+}
+
+function policyAssign(args: string[]): CommandResult {
+  const [policyName, target] = args;
+  if (!policyName || !target) {
+    return { success: false, error: 'Usage: celilo escalation-policy assign <policy> <monitor>' };
+  }
+
+  const db = getDb();
+  const policy = findPolicy(db, policyName);
+  if (!policy) return { success: false, error: `No policy named "${policyName}".` };
+  const monitor = findMonitorByTarget(db, target);
+  if (!monitor) return { success: false, error: `No monitor for "${target}".` };
+
+  db.update(monitors)
+    .set({ escalationPolicyId: policy.id })
+    .where(eq(monitors.id, monitor.id))
+    .run();
+
+  return { success: true, message: `${target} now escalates via "${policyName}"` };
+}
+
+export async function handleEscalationPolicy(
+  subcommand: string | undefined,
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  switch (subcommand) {
+    case undefined:
+    case 'list':
+      return policyList();
+    case 'add':
+      return policyAdd(args);
+    case 'step':
+      return policyStep(args, flags);
+    case 'assign':
+      return policyAssign(args);
+    case 'remove':
+      return policyRemove(args);
+    default:
+      return {
+        success: false,
+        error: `Unknown escalation-policy subcommand: ${subcommand}\n\nUse: list, add, step, assign, remove`,
+      };
+  }
+}