@celilo/cli 2.1.0 → 2.2.1

package/src/registry/client.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import { createHash } from 'node:crypto';
 import type { IndexEntry } from './client';
 import { DEFAULT_REGISTRY, RegistryClient } from './client';
 
@@ -312,3 +313,151 @@ describe('RegistryClient owner methods', () => {
     );
   });
 });
+
+// ── get() retry ───────────────────────────────────────────────────────────────
+//
+// Every registry read goes through one private `get()`. It used to make exactly
+// one attempt, so a single transient — the shape the 15s→30s timeout bump was
+// already chasing — failed a module install outright. Measured 2026-09-04:
+// `module import iptables` failed twice with "Download failed: The operation
+// timed out" while the identical call had succeeded minutes earlier.
+
+describe('RegistryClient.get retry', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  test('a transient network failure is retried and the download succeeds', async () => {
+    const payload = new Uint8Array([1, 2, 3, 4]);
+    fetchSpy
+      .mockRejectedValueOnce(new DOMException('The operation timed out.', 'TimeoutError'))
+      .mockResolvedValueOnce(new Response(payload, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4');
+
+    expect(new Uint8Array(data)).toEqual(payload);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test('a 5xx is retried', async () => {
+    fetchSpy
+      .mockResolvedValueOnce(new Response(null, { status: 503 }))
+      .mockResolvedValueOnce(new Response(new Uint8Array([9]), { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await client.download('iptables', '3.1.4');
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test('a 404 is NOT retried — it is an answer, not a transient', async () => {
+    fetchSpy.mockResolvedValue(new Response(null, { status: 404 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.download('nope', '1.0.0')).rejects.toThrow('HTTP 404');
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('gives up after a bounded number of attempts', async () => {
+    fetchSpy.mockRejectedValue(new DOMException('The operation timed out.', 'TimeoutError'));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const error = await client.download('iptables', '3.1.4').then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(error).toBeInstanceOf(Error);
+    // The exhaustion report is the event, not the last attempt (celilo#1264):
+    // the bare lastError read as an unretried first attempt, because that is
+    // exactly what the same string meant before the retry existed.
+    expect((error as Error).message).toMatch(/failed after 3 attempts over \d+(\.\d+)?s/);
+    expect((error as Error).message).toContain('The operation timed out.');
+    expect((error as { cause?: unknown }).cause).toBeInstanceOf(DOMException);
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+  });
+});
+
+// ── download integrity ────────────────────────────────────────────────────────
+//
+// `cksum` is computed at publish time, shipped in every index entry, and was
+// never checked on the consuming side. A short download was therefore accepted
+// and blew up later in gunzip as "zlib: unexpected end of file", which blames
+// the package rather than the transfer. Measured 2026-09-04 in the e2e rig.
+// Retrying cannot help a fault it cannot detect, so verification is what makes
+// the retry meaningful.
+
+describe('RegistryClient.download integrity', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+  const body = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+  // sha256 of the 8 bytes above, in the `sha256:<hex>` shape publish() writes.
+  const goodCksum = `sha256:${createHash('sha256').update(body).digest('hex')}`;
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  test('a truncated payload is rejected and retried, then succeeds', async () => {
+    fetchSpy
+      .mockResolvedValueOnce(new Response(body.slice(0, 3), { status: 200 })) // short
+      .mockResolvedValueOnce(new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4', goodCksum);
+
+    expect(new Uint8Array(data)).toEqual(body);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test('a payload that never verifies fails with an error naming the integrity check', async () => {
+    // A fresh Response per call: one shared instance would be consumed by the
+    // first attempt and the retry would report "Body already used", hiding the
+    // integrity failure this test exists to assert.
+    fetchSpy.mockImplementation(() => new Response(body.slice(0, 3), { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.download('iptables', '3.1.4', goodCksum)).rejects.toThrow(
+      /integrity check/i,
+    );
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+  });
+
+  test('a correct payload verifies on the first attempt', async () => {
+    fetchSpy.mockResolvedValue(new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await client.download('iptables', '3.1.4', goodCksum);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('no expected cksum still downloads — callers may not have one', async () => {
+    fetchSpy.mockResolvedValue(new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4');
+    expect(new Uint8Array(data)).toEqual(body);
+  });
+
+  test('a non-digest cksum sentinel skips verification instead of failing', async () => {
+    // The registry's bootstrap path publishes `cksum: 'bootstrap'`
+    // (packages/registry-server/src/bootstrap.ts:114) because those modules are
+    // packaged on demand and have no stable digest. Treating a sentinel as a
+    // digest rejects a perfectly good 2.7MB package on every import.
+    fetchSpy.mockImplementation(() => new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4', 'bootstrap');
+
+    expect(new Uint8Array(data)).toEqual(body);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/registry/client.ts

@@ -11,6 +11,98 @@ import { readFile } from 'node:fs/promises';
 
 export const DEFAULT_REGISTRY = 'https://celilo.computer/registry';
 
+/** Attempts per idempotent registry read, including the first. */
+const GET_ATTEMPTS = 3;
+/** Per-attempt ceiling for metadata reads. Packages use DOWNLOAD_TIMEOUT_MS. */
+const GET_TIMEOUT_MS = 30_000;
+/** Linear backoff: 1s, then 2s. Short, because a deploy is waiting on this. */
+const GET_RETRY_DELAY_MS = 1_000;
+/**
+ * Per-attempt ceiling for a package download.
+ *
+ * This was briefly 180s, on the reasoning that a package is megabytes and
+ * metadata is not. That was wrong, and measurably so: the whole retry budget has
+ * to fit inside the CALLER's window, and celilo's own e2e harness gives a command
+ * 120s by default (`packages/e2e/src/container-manager.ts`). Three attempts at
+ * 180s allows ~543s, so a slow download stopped failing as a download and started
+ * being killed by the caller — a worse error, further from the cause.
+ *
+ * 30s x 3 attempts plus backoff is ~93s, which fits. The durability comes from
+ * retrying, not from a wider window: a 2.6MB transfer that normally takes about a
+ * second does not need 180s, it needs another go.
+ */
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+/**
+ * Read a body to completion, reporting progress so a failure can say how far it
+ * got. `Response.arrayBuffer()` gives no partial count when it throws.
+ */
+async function readCounting(
+  resp: Response,
+  onProgress: (bytes: number) => void,
+): Promise<ArrayBuffer> {
+  if (!resp.body) return resp.arrayBuffer();
+
+  const reader = resp.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        chunks.push(value);
+        total += value.byteLength;
+        onProgress(total);
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out.buffer;
+}
+
+/**
+ * A status worth trying again. 5xx is the server failing, 408 and 429 are it
+ * asking us to wait. Every other 4xx is a settled answer.
+ */
+function isRetryableStatus(status: number): boolean {
+  return status >= 500 || status === 408 || status === 429;
+}
+
+/**
+ * A settled answer from the registry. Retrying cannot change it, so `withRetry`
+ * rethrows it immediately rather than spending the backoff on a known 404.
+ */
+class RegistryAnswer extends Error {}
+
+/** `publish` writes `sha256:<hex>`; tolerate a bare hex digest from older entries. */
+function normalizeCksum(value: string): string {
+  return value.replace(/^sha256:/, '').toLowerCase();
+}
+
+/**
+ * Is this index entry's `cksum` an actual digest we can check against?
+ *
+ * Not every entry carries one. The registry's bootstrap path publishes the
+ * literal string `bootstrap` (packages/registry-server/src/bootstrap.ts), because
+ * those modules are packaged on demand and have no stable digest to publish.
+ * A sentinel means "no integrity data", which is a reason to skip the check and
+ * not a reason to reject the package — treating it as a digest rejects every
+ * bootstrap-served import.
+ */
+function isVerifiableCksum(value: string): boolean {
+  return /^[0-9a-f]{64}$/.test(normalizeCksum(value));
+}
+
 export interface SparseConfig {
   dl: string;
   api: string;
@@ -109,9 +201,56 @@ export class RegistryClient {
     return `${this.baseUrl}/api/v1/modules/${encodeURIComponent(name)}/${encodeURIComponent(version)}/download`;
   }
 
-  async download(name: string, version: string): Promise<ArrayBuffer> {
-    const resp = await this.get(this.downloadUrl(name, version));
-    return resp.arrayBuffer();
+  /**
+   * Fetch a module .netapp, verifying it against the index entry's `cksum`.
+   *
+   * `cksum` has always been computed at publish time and shipped in every index
+   * entry, and nothing on this side ever checked it. A short transfer was
+   * therefore accepted as a complete package and failed later in gunzip as
+   * "zlib: unexpected end of file", which points at the package rather than at
+   * the download that produced it.
+   *
+   * Verification is also what makes the retry mean anything: a fault nobody can
+   * detect is a fault nobody can retry. Pass `expectedCksum` whenever the caller
+   * holds the entry — both callers do.
+   */
+  async download(name: string, version: string, expectedCksum?: string): Promise<ArrayBuffer> {
+    const url = this.downloadUrl(name, version);
+
+    return this.withRetry(async () => {
+      const startedAt = Date.now();
+      const resp = await this.fetchOnce(url, DOWNLOAD_TIMEOUT_MS);
+
+      // Read in chunks so a failure can say how far it got. A bare
+      // `arrayBuffer()` that times out reports nothing, which is why three runs
+      // of this failure told us only that it was slow and never how slow. Bytes
+      // and elapsed together separate a steady trickle from a stall, and those
+      // two want different fixes (a bigger window versus an idle timeout).
+      let data: ArrayBuffer;
+      let received = 0;
+      try {
+        data = await readCounting(resp, (n) => {
+          received = n;
+        });
+      } catch (err) {
+        const seconds = (Date.now() - startedAt) / 1000;
+        const rate = seconds > 0 ? received / 1024 / seconds : 0;
+        throw new Error(
+          `Download of ${name}@${version} failed after ${received} bytes in ${seconds.toFixed(1)}s (${rate.toFixed(0)} KiB/s): ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+
+      if (expectedCksum && isVerifiableCksum(expectedCksum)) {
+        const actual = createHash('sha256').update(new Uint8Array(data)).digest('hex');
+        if (actual !== normalizeCksum(expectedCksum)) {
+          throw new Error(
+            `Package ${name}@${version} failed its integrity check: got ${data.byteLength} bytes with sha256 ${actual}, expected ${normalizeCksum(expectedCksum)}. A short or corrupted download, not a bad package.`,
+          );
+        }
+      }
+
+      return data;
+    });
   }
 
   /**
@@ -232,14 +371,67 @@ export class RegistryClient {
   }
 
   private async get(url: string): Promise<Response> {
-    // 30s (was 15s): a module .netapp can be tens of MB and the download must
-    // finish within one window. 15s was too aggressive on slow links — the
-    // download of a ~19MB module over a multi-hop path (e2e sim NAT, real WAN)
-    // intermittently timed out mid-transfer.
-    const resp = await fetch(url, { signal: AbortSignal.timeout(30_000) });
-    if (!resp.ok) {
-      throw new Error(`Registry error at ${url}: HTTP ${resp.status}`);
+    // 30s per attempt: a module .netapp can be tens of MB, and the download of a
+    // ~19MB module over a multi-hop path (e2e sim NAT, real WAN) intermittently
+    // times out mid-transfer.
+    //
+    // The window used to be the whole story — one attempt, and the response to
+    // observed flakiness was widening it from 15s to 30s. A wider single window
+    // is not a durable fetch, it is a bigger gap to fall through. Measured
+    // 2026-09-04: `module import iptables` failed twice with "Download failed:
+    // The operation timed out" on a loaded host, while the identical call had
+    // succeeded minutes earlier. This client is the fleet's module delivery
+    // path, so a single transient failing an import is an operator-facing
+    // outage, not just an e2e flake.
+    //
+    // Every caller of get() is an idempotent read (config, search, metadata,
+    // download), so retrying is safe. `publish` does not route through here.
+    // A 4xx is an answer and is never retried: a 404 must stay fast and say
+    // "not found" rather than stall for the whole backoff.
+    return this.withRetry(() => this.fetchOnce(url));
+  }
+
+  /** One attempt. Throws `RegistryAnswer` for a status retrying cannot change. */
+  private async fetchOnce(url: string, timeoutMs = GET_TIMEOUT_MS): Promise<Response> {
+    const resp = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (resp.ok) return resp;
+
+    const message = `Registry error at ${url}: HTTP ${resp.status}`;
+    if (!isRetryableStatus(resp.status)) throw new RegistryAnswer(message);
+    throw new Error(message);
+  }
+
+  /**
+   * Retry a whole operation, not a piece of one.
+   *
+   * The unit matters. Retrying only the request leaves the body download
+   * outside the retry, and a body is where a large transfer actually fails.
+   */
+  private async withRetry<T>(run: () => Promise<T>): Promise<T> {
+    const startedAt = Date.now();
+    let lastError: unknown;
+
+    for (let attempt = 1; attempt <= GET_ATTEMPTS; attempt++) {
+      try {
+        return await run();
+      } catch (err) {
+        if (err instanceof RegistryAnswer) throw err;
+        lastError = err;
+        if (attempt < GET_ATTEMPTS) {
+          await new Promise((resolve) => setTimeout(resolve, GET_RETRY_DELAY_MS * attempt));
+        }
+      }
     }
-    return resp;
+
+    // Exhausting the budget is itself the event worth reporting. The bare last
+    // error said only what the final attempt said, which is the same string the
+    // caller got before the retry existed, so the operator cannot tell whether
+    // the retry ran (celilo#1264). The original error rides along as `cause`.
+    const seconds = (Date.now() - startedAt) / 1000;
+    const detail = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new Error(
+      `Registry fetch failed after ${GET_ATTEMPTS} attempts over ${seconds.toFixed(1)}s: ${detail}`,
+      { cause: lastError },
+    );
   }
 }

package/src/services/alerting/ack.test.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { type Route, alerts, modules, monitors } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { acknowledgeAlert, findLiveAlertByKey, resolveAlertManually, silenceAlert } from './ack';
 import { moduleCheckAlertKey } from './keys';
 import { createPerson, createRoute } from './people';
@@ -79,7 +80,7 @@ describe('ack / silence / resolve', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/cadence-migration.test.ts

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { closeDb, getDb } from '../../db/client';
 import { runMigrations } from '../../db/migrate';
 import { modules, monitors } from '../../db/schema';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { getModuleConfigValue, upsertModuleConfig } from '../module-config';
 import { migrateMonitorCadences } from './cadence-migration';
 import { HEALTH_CHECK_INTERVAL_CONFIG_KEY, loadModuleHealthCadences } from './health-cadence';
@@ -66,7 +67,7 @@ describe('migrateMonitorCadences', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     rmSync(dir, { recursive: true, force: true });
   });
 
@@ -132,7 +133,7 @@ describe("a module_hook row's stored cadence is not consulted", () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     rmSync(dir, { recursive: true, force: true });
   });
 

package/src/services/alerting/coverage-source.test.ts

@@ -20,6 +20,7 @@ import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { modules } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { CONTROL_PLANE_MODULE_ID } from '../deployed-systems';
 import { loadModuleCoverage } from './coverage-source';
 import { healthCoverageFailingKeys } from './health-coverage';
@@ -37,7 +38,7 @@ describe('health coverage and the control plane', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/deferral.test.ts

@@ -6,6 +6,7 @@ import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type Alert, type Route, alerts, modules, monitors } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { moduleCheckAlertKey } from './keys';
 import { deliverDeferred } from './notifier';
 import { createPerson, createRoute } from './people';
@@ -80,7 +81,7 @@ describe('quiet-hours deferral', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/delivery-loop.test.ts

@@ -21,6 +21,7 @@ import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { type Alert, type Route, modules } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import type { EscalationStep, RouteForEscalation } from './escalation';
 import { interpretInbound } from './inbound';
 import {
@@ -249,7 +250,7 @@ describe('delivery loop against the signal-cli simulator', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/deploy-hooks.test.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { modules, monitors } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import {
   closeDeployWindows,
   ensureMonitorOnDeploy,
@@ -34,7 +35,7 @@ describe('deploy hooks', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/format.test.ts

@@ -6,9 +6,11 @@ import {
   humaniseRemaining,
   moduleHealthCell,
   renderAlertTable,
+  renderMonitorRunMessage,
   sortAlertRows,
   toAlertRow,
 } from './format';
+import type { MonitorRunOutcomeSummary } from './run-monitor';
 
 const NOW = new Date('2026-07-28T12:00:00Z');
 const ago = (minutes: number) => new Date(NOW.getTime() - minutes * 60_000);
@@ -190,3 +192,58 @@ describe('moduleHealthCell', () => {
     );
   });
 });
+
+describe('renderMonitorRunMessage — names the failing check (#1266)', () => {
+  function summary(over: Partial<MonitorRunOutcomeSummary>): MonitorRunOutcomeSummary {
+    return {
+      monitorId: 'mon-1',
+      outcome: 'success',
+      createdIds: [],
+      resolvedIds: [],
+      ...over,
+    } as MonitorRunOutcomeSummary;
+  }
+
+  const caddyRunning = {
+    key: 'module:caddy/check:caddy_running',
+    severity: 'critical' as const,
+    message: 'caddy systemd service is not active',
+  };
+
+  test('a failing check is named, with its reason', () => {
+    const message = renderMonitorRunMessage('caddy', summary({ failingKeys: [caddyRunning] }));
+    expect(message).toContain('module:caddy/check:caddy_running');
+    expect(message).toContain('caddy systemd service is not active');
+    expect(message).toContain('1 failing');
+  });
+
+  test('every failing key is named, not just the first', () => {
+    const diskSpace = {
+      key: 'module:caddy/check:disk-space',
+      severity: 'warning' as const,
+      message: '/var 94% used',
+    };
+    const message = renderMonitorRunMessage(
+      'caddy',
+      summary({ failingKeys: [caddyRunning, diskSpace] }),
+    );
+    expect(message).toContain('module:caddy/check:caddy_running');
+    expect(message).toContain('module:caddy/check:disk-space');
+    expect(message).toContain('2 failing');
+  });
+
+  test('a healthy run keeps the zero the suite greps for', () => {
+    const message = renderMonitorRunMessage('caddy', summary({ failingKeys: [] }));
+    expect(message).toContain('0 failing');
+    expect(message).toContain('0 resolved');
+  });
+
+  test('a run that could not execute says why instead of inventing a count', () => {
+    const message = renderMonitorRunMessage(
+      'caddy',
+      summary({ outcome: 'error', errorMessage: 'hook exited 1' }),
+    );
+    expect(message).toContain('check could not run');
+    expect(message).toContain('hook exited 1');
+  });
+});

package/src/services/alerting/format.ts

@@ -10,6 +10,7 @@
  */
 
 import type { Alert, AlertState } from '../../db/schema';
+import type { MonitorRunOutcomeSummary } from './run-monitor';
 
 export interface AlertRow {
   key: string;
@@ -148,3 +149,26 @@ export function moduleHealthCell(input: {
   if (input.firingCount > 0) return `${input.firingCount} firing`;
   return 'ok';
 }
+
+/**
+ * The message `celilo monitor run <target>` reports.
+ *
+ * The count line stays greppable (`0 failing` is what a healthy fleet prints),
+ * and each failing key is named underneath it with its reason — an operator
+ * paged by this line learns WHAT failed, not just that something did (#1266).
+ *
+ * Pure — takes the run summary, returns the string — so the wording can be
+ * asserted without a database or a fleet.
+ */
+export function renderMonitorRunMessage(target: string, summary: MonitorRunOutcomeSummary): string {
+  if (summary.outcome === 'error') {
+    return `${target}: check could not run — ${summary.errorMessage ?? 'unknown error'}`;
+  }
+  const lines = [
+    `${target}: ${summary.failingKeys.length} failing, ${summary.resolvedIds.length} resolved`,
+  ];
+  for (const failing of summary.failingKeys) {
+    lines.push(`  [${failing.severity}] ${failing.key}: ${failing.message}`);
+  }
+  return lines.join('\n');
+}

package/src/services/alerting/inbound-poller.test.ts

@@ -7,6 +7,7 @@ import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type Route, alerts, modules, monitors, notificationDeliveries } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import {
   type InboundPollDeps,
   type TransportReadRecord,
@@ -105,7 +106,7 @@ describe('pollInbound', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/inbound.test.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { type NotificationDelivery, modules, people, routes } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { interpretInbound, parseInbound } from './inbound';
 import { mintDelivery } from './tokens';
 
@@ -107,7 +108,7 @@ describe('interpretInbound', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/notification-responder.test.ts

@@ -6,6 +6,7 @@ import { defineEvents, openBus } from '@celilo/event-bus';
 import type { DbClient } from '../../db/client';
 import { type Route, modules } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import {
   type NotificationResponderHandle,
   startNotificationResponder,
@@ -88,7 +89,7 @@ describe('notification responder', () => {
     handle?.stop();
     handle = undefined;
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {