@celilo/cli 0.14.1 → 0.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

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

@@ -152,5 +152,35 @@ export async function handleAlertsSweep(): Promise<CommandResult> {
     `${report.unsuppressed} unsuppressed`,
     `${report.notified} notified`,
   ];
-  return { success: true, message: `alert sweep: ${parts.join(', ')}` };
+  // Only shown when non-zero: a quiet sweep should stay quiet. But a delivery
+  // that failed, was deferred, or was declined must never render as `0 notified`
+  // and nothing else — that is indistinguishable from "nothing needed sending",
+  // which is exactly how a transport that has stopped paging looks like a quiet
+  // night (#450).
+  if (report.deferred > 0) parts.push(`${report.deferred} deferred`);
+  if (report.deferredDelivered > 0) parts.push(`${report.deferredDelivered} deferred-delivered`);
+  if (report.failed > 0) parts.push(`${report.failed} FAILED`);
+  if (report.noPolicy > 0) parts.push(`${report.noPolicy} no-policy`);
+
+  const lines = [`alert sweep: ${parts.join(', ')}`];
+
+  // The reason escalation declined is the single most useful fact when someone
+  // asks "why was I not paged", so name it rather than aggregating it away.
+  const skipped = Object.entries(report.skipped).sort(([, a], [, b]) => b - a);
+  if (skipped.length > 0) {
+    lines.push(`  not delivered: ${skipped.map(([r, n]) => `${r}×${n}`).join(', ')}`);
+  }
+  // The error itself, not just a count: the transport is loaded lazily inside
+  // the send, so a capability that will not load produces no other record
+  // anywhere — nothing ever reaches the transport's own logs.
+  for (const failure of report.failures) {
+    lines.push(`  FAILED ${failure}`);
+  }
+  if (report.noPolicy > 0) {
+    lines.push(
+      `  ${report.noPolicy} live alert(s) have no escalation policy — assign one with:\n    celilo escalation-policy assign <policy> <monitor>`,
+    );
+  }
+
+  return { success: true, message: lines.join('\n') };
 }

package/src/services/alerting/sweep-runner.test.ts

@@ -226,4 +226,94 @@ describe('runSweep', () => {
     expect(db.select().from(monitors).get()?.lastRunAt).toEqual(NOW);
     expect(monitor.lastRunAt).toBeNull();
   });
+
+  // A delivery that never happened must be distinguishable from one that was
+  // never needed. Both used to render as `notified: 0` and nothing else, which
+  // is how a firing-but-undelivered alert became undebuggable (#450).
+  describe('undelivered alerts are accounted for, not silently dropped', () => {
+    test('an alert with no escalation policy is counted, not skipped in silence', async () => {
+      // `notifyDepsFor` returning null IS "nobody is configured to be told" —
+      // the default in every other test here, which is why this went unnoticed.
+      const report = await runSweep(db, currentMonitors(), deps());
+
+      expect(liveAlerts()).toHaveLength(1);
+      expect(report.notified).toBe(0);
+      expect(report.noPolicy).toBe(1);
+    });
+
+    test('escalation declining to notify records WHICH reason', async () => {
+      // A fresh alert is inside its grace window, so escalation declines with
+      // `within_grace` — a real skip reason reached through the real code path
+      // rather than a stubbed outcome.
+      const notifyDeps = {
+        steps: [{ stepIndex: 0, routeId: 'route-1', delayMinutes: 0 }],
+        routes: new Map([['route-1', { id: 'route-1', severityFloor: 'warning', enabled: true }]]),
+        routeDetails: new Map([
+          [
+            'route-1',
+            { id: 'route-1', personId: 'p1', address: '+15550000000', canAck: false } as never,
+          ],
+        ]),
+        quietHoursByPerson: new Map(),
+        bypassQuietHours: false,
+        transportFor: () => {
+          throw new Error('transport must not be reached for a skipped delivery');
+        },
+        mintToken: () => 'tok',
+        now: NOW,
+      } as never;
+
+      const report = await runSweep(
+        db,
+        currentMonitors(),
+        deps({ notifyDepsFor: () => notifyDeps }),
+      );
+
+      expect(report.notified).toBe(0);
+      expect(report.noPolicy).toBe(0);
+      expect(report.skipped.within_grace).toBe(1);
+    });
+
+    test('a transport that cannot be loaded records the error, not just a count', async () => {
+      // The transport is resolved lazily INSIDE the send, so a capability that
+      // will not load never reaches the transport's own logs. If the sweep does
+      // not carry the message, it exists nowhere.
+      const notifyDeps = (now: Date) =>
+        ({
+          steps: [{ stepIndex: 0, routeId: 'route-1', delayMinutes: 0 }],
+          routes: new Map([
+            ['route-1', { id: 'route-1', severityFloor: 'warning', enabled: true }],
+          ]),
+          routeDetails: new Map([
+            [
+              'route-1',
+              { id: 'route-1', personId: 'p1', address: '+15550000000', canAck: false } as never,
+            ],
+          ]),
+          quietHoursByPerson: new Map(),
+          bypassQuietHours: false,
+          transportFor: () => {
+            throw new Error('does not provide the notification capability');
+          },
+          mintToken: () => 'tok',
+          now,
+        }) as never;
+
+      // First sweep creates the alert; the second is past the grace window, so
+      // escalation actually reaches the transport.
+      await runSweep(db, currentMonitors(), deps());
+      const at = later(20);
+      const report = await runSweep(
+        db,
+        currentMonitors(),
+        deps({ notifyDepsFor: () => notifyDeps(at) }, failing, at),
+      );
+
+      expect(report.notified).toBe(0);
+      expect(report.failed).toBe(1);
+      expect(report.failures).toHaveLength(1);
+      expect(report.failures[0]).toContain(PORT_CHECK);
+      expect(report.failures[0]).toContain('does not provide the notification capability');
+    });
+  });
 });

package/src/services/alerting/sweep-runner.ts

@@ -61,6 +61,34 @@ export interface SweepReport {
   /** Messages held over quiet hours and delivered now that the window ended. */
   deferredDelivered: number;
   failed: number;
+  /**
+   * Live alerts nobody is configured to be told about — no escalation policy on
+   * the monitor, so `notifyDepsFor` returns null.
+   *
+   * Counted rather than skipped in silence: "nothing needed sending" and "an
+   * alert is firing and no policy points at anyone" are opposite situations that
+   * previously rendered identically as `0 notified`.
+   */
+  noPolicy: number;
+  /**
+   * Deliveries escalation declined, keyed by its reason (`within_grace`,
+   * `no_eligible_route`, …).
+   *
+   * `notifyAlert` returns the reason precisely so the caller can record it — its
+   * own contract says a silent skip is indistinguishable from a bug. Dropping it
+   * here is what made a firing-but-undelivered alert undebuggable (#450).
+   */
+  skipped: Record<string, number>;
+  /**
+   * Why each failed delivery failed, as `<alert key>: <error>`.
+   *
+   * A count alone does not answer the only question that matters after a page
+   * did not arrive. The transport is loaded lazily *inside* `notifyAlert`'s try
+   * block, so "the capability would not load" and "Signal rejected the message"
+   * both surface here and nowhere else — there is no daemon-side log for the
+   * former, because nothing ever reached the daemon.
+   */
+  failures: string[];
 }
 
 /**
@@ -85,6 +113,9 @@ export async function runSweep(
     deferred: 0,
     deferredDelivered: 0,
     failed: 0,
+    noPolicy: 0,
+    skipped: {},
+    failures: [],
   };
 
   // 1. Run due monitors.
@@ -162,24 +193,36 @@ export async function runSweep(
     try {
       const outcome = await deliverDeferred(alert, route, notifyDeps);
       if (outcome.result === 'sent') report.deferredDelivered++;
-      else if (outcome.result === 'failed') report.failed++;
-    } catch {
+      else if (outcome.result === 'failed') {
+        report.failed++;
+        report.failures.push(`${alert.key} (deferred): ${outcome.error}`);
+      }
+    } catch (error) {
       report.failed++;
+      report.failures.push(
+        `${alert.key} (deferred): ${error instanceof Error ? error.message : String(error)}`,
+      );
     }
   }
 
   // 5. Notify. Re-read: the steps above changed state under us.
   for (const alert of loadAllLiveAlerts(db)) {
     const notifyDeps = deps.notifyDepsFor(alert);
-    if (!notifyDeps) continue;
+    if (!notifyDeps) {
+      report.noPolicy++;
+      continue;
+    }
 
     let outcome: NotifyOutcome;
     try {
       outcome = await notifyAlert(alert, notifyDeps);
-    } catch {
+    } catch (error) {
       // notifyAlert already converts transport errors into a `failed` outcome;
       // reaching here means something above the transport broke.
       report.failed++;
+      report.failures.push(
+        `${alert.key}: ${error instanceof Error ? error.message : String(error)}`,
+      );
       continue;
     }
 
@@ -197,6 +240,9 @@ export async function runSweep(
       report.deferred++;
     } else if (outcome.result === 'failed') {
       report.failed++;
+      report.failures.push(`${alert.key}: ${outcome.error}`);
+    } else if (outcome.result === 'skipped') {
+      report.skipped[outcome.reason] = (report.skipped[outcome.reason] ?? 0) + 1;
     }
   }