@checkstack/healthcheck-backend 1.21.3 → 1.23.0

package/drizzle/meta/_journal.json

@@ -148,6 +148,13 @@
       "when": 1783607735562,
       "tag": "0020_certain_mordo",
       "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1784736274302,
+      "tag": "0021_amazing_wolf_cub",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-backend",
-  "version": "1.21.3",
+  "version": "1.23.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,32 +14,34 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/ai-backend": "0.11.3",
-    "@checkstack/ai-common": "0.6.7",
-    "@checkstack/automation-backend": "0.11.7",
-    "@checkstack/backend-api": "0.34.0",
-    "@checkstack/cache-api": "0.3.20",
-    "@checkstack/cache-utils": "0.3.1",
-    "@checkstack/catalog-backend": "1.10.0",
-    "@checkstack/catalog-common": "2.8.0",
-    "@checkstack/command-backend": "0.2.26",
-    "@checkstack/common": "0.23.0",
-    "@checkstack/gitops-backend": "0.5.26",
-    "@checkstack/gitops-common": "0.7.4",
-    "@checkstack/healthcheck-common": "1.18.0",
-    "@checkstack/incident-backend": "1.13.5",
-    "@checkstack/incident-common": "1.10.4",
-    "@checkstack/maintenance-common": "1.10.4",
-    "@checkstack/notification-common": "1.7.2",
-    "@checkstack/queue-api": "0.4.0",
-    "@checkstack/satellite-backend": "0.9.3",
-    "@checkstack/script-packages-backend": "0.4.5",
-    "@checkstack/sdk": "0.133.1",
-    "@checkstack/secrets-backend": "0.3.8",
-    "@checkstack/secrets-common": "0.3.3",
-    "@checkstack/signal-common": "0.3.1",
-    "@checkstack/status-page-backend": "0.6.5",
-    "@checkstack/status-page-common": "0.6.4",
+    "@checkstack/ai-backend": "0.11.5",
+    "@checkstack/ai-common": "0.6.8",
+    "@checkstack/automation-backend": "0.11.9",
+    "@checkstack/backend-api": "0.35.0",
+    "@checkstack/cache-api": "0.3.21",
+    "@checkstack/cache-utils": "0.3.2",
+    "@checkstack/catalog-backend": "1.10.2",
+    "@checkstack/catalog-common": "2.8.2",
+    "@checkstack/command-backend": "0.3.0",
+    "@checkstack/common": "0.24.0",
+    "@checkstack/gitops-backend": "0.5.28",
+    "@checkstack/gitops-common": "0.7.5",
+    "@checkstack/healthcheck-common": "1.19.1",
+    "@checkstack/healthcheck-execution": "0.35.1",
+    "@checkstack/incident-backend": "1.14.0",
+    "@checkstack/incident-common": "1.11.0",
+    "@checkstack/maintenance-common": "1.11.0",
+    "@checkstack/notification-common": "1.9.0",
+    "@checkstack/queue-api": "0.4.1",
+    "@checkstack/satellite-backend": "0.10.0",
+    "@checkstack/satellite-common": "0.12.0",
+    "@checkstack/script-packages-backend": "0.4.7",
+    "@checkstack/sdk": "0.136.1",
+    "@checkstack/secrets-backend": "0.3.10",
+    "@checkstack/secrets-common": "0.3.4",
+    "@checkstack/signal-common": "0.3.2",
+    "@checkstack/status-page-backend": "0.7.0",
+    "@checkstack/status-page-common": "0.7.0",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/contract": "^1.14.4",
     "@orpc/server": "^1.14.4",
@@ -51,8 +53,8 @@
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.6",
-    "@checkstack/scripts": "0.7.6",
-    "@checkstack/test-utils-backend": "0.1.60",
+    "@checkstack/scripts": "0.7.7",
+    "@checkstack/test-utils-backend": "0.1.62",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "@types/pg": "^8.20.0",

package/src/ai/system-signals-contributor.test.ts

@@ -23,6 +23,7 @@ const unhealthyStatuses: HealthcheckSignalStatuses = {
         runsConsidered: 5,
         sliceCount: 1,
         failingSliceCount: 1,
+        slices: [],
       },
     ],
   },

package/src/cache.test.ts

@@ -63,6 +63,9 @@ function response(
       runsConsidered: 1,
       sliceCount: c.sliceCount ?? 1,
       failingSliceCount: c.failingSliceCount ?? 0,
+      // These tests exercise the cache's fingerprint/invalidation behaviour,
+      // which reads the counts rather than the per-slice breakdown.
+      slices: [],
     })),
   };
 }

package/src/effective-environments.test.ts

@@ -1,5 +1,8 @@
-import { describe, it, expect } from "bun:test";
-import { resolveEffectiveEnvironments } from "./effective-environments";
+import { describe, it, test, expect } from "bun:test";
+import {
+  resolveEffectiveEnvironments,
+  resolveSatelliteEnvironments,
+} from "./effective-environments";
 import type { Environment } from "@checkstack/catalog-common";
 
 const env = (
@@ -91,3 +94,61 @@ describe("resolveEffectiveEnvironments", () => {
     expect(result).toEqual([]);
   });
 });
+
+describe("resolveSatelliteEnvironments", () => {
+  const effective = [
+    { id: "env-prod", name: "Production", fields: {} },
+    { id: "env-stage", name: "Staging", fields: {} },
+  ];
+
+  test("an unscoped satellite runs every environment the assignment resolved to", () => {
+    // The backfill-free default: a NULL column means no scoping, so existing
+    // assignments keep behaving exactly as they did.
+    expect(
+      resolveSatelliteEnvironments({
+        effective,
+        satelliteEnvironmentIds: undefined,
+      }),
+    ).toEqual(effective);
+    expect(
+      resolveSatelliteEnvironments({ effective, satelliteEnvironmentIds: null }),
+    ).toEqual(effective);
+  });
+
+  test("a scoped satellite runs only its own environments", () => {
+    // The point of the feature: the prod satellite probes prod, and never
+    // reaches for a staging endpoint it may have no route to.
+    expect(
+      resolveSatelliteEnvironments({
+        effective,
+        satelliteEnvironmentIds: ["env-prod"],
+      }).map((e) => e.id),
+    ).toEqual(["env-prod"]);
+  });
+
+  test("a satellite can NARROW but never widen the assignment's scope", () => {
+    // An id the assignment does not cover silently drops - a satellite must not
+    // be able to probe an environment the assignment itself excluded.
+    expect(
+      resolveSatelliteEnvironments({
+        effective,
+        satelliteEnvironmentIds: ["env-prod", "env-secret"],
+      }).map((e) => e.id),
+    ).toEqual(["env-prod"]);
+  });
+
+  test("an empty selector opts the satellite out into a single env-less run", () => {
+    expect(
+      resolveSatelliteEnvironments({ effective, satelliteEnvironmentIds: [] }),
+    ).toEqual([]);
+  });
+
+  test("preserves the assignment's order, so fan-out stays deterministic", () => {
+    expect(
+      resolveSatelliteEnvironments({
+        effective,
+        satelliteEnvironmentIds: ["env-stage", "env-prod"],
+      }).map((e) => e.id),
+    ).toEqual(["env-prod", "env-stage"]);
+  });
+});

package/src/effective-environments.ts

@@ -62,3 +62,37 @@ export function resolveEffectiveEnvironments({
     .filter((env) => wanted.has(env.id))
     .map((env) => toEffective(env));
 }
+
+/**
+ * Narrow an assignment's effective environments to those a SPECIFIC satellite
+ * should run.
+ *
+ * A satellite's selector can only ever narrow, never widen: the assignment
+ * decides which environments exist for this check, and the satellite decides
+ * which of those it is responsible for. That ordering is what lets a prod
+ * satellite run only prod without being able to reach environments the
+ * assignment itself excluded.
+ *
+ * - `undefined` / `null` => every environment the assignment resolved to. This
+ *   is the default for an unscoped satellite, so existing assignments keep
+ *   behaving exactly as they did.
+ * - `[]`                 => opt out: one env-less run on this satellite.
+ * - non-empty            => exactly those ids, intersected with `effective`;
+ *   an id the assignment does not cover silently drops.
+ *
+ * Order follows `effective`, so fan-out order stays deterministic.
+ */
+export function resolveSatelliteEnvironments({
+  effective,
+  satelliteEnvironmentIds,
+}: {
+  effective: EffectiveEnvironment[];
+  satelliteEnvironmentIds: string[] | null | undefined;
+}): EffectiveEnvironment[] {
+  if (satelliteEnvironmentIds === null || satelliteEnvironmentIds === undefined) {
+    return effective;
+  }
+  if (satelliteEnvironmentIds.length === 0) return [];
+  const wanted = new Set(satelliteEnvironmentIds);
+  return effective.filter((env) => wanted.has(env.id));
+}

package/src/health-entity.ts

@@ -22,7 +22,7 @@
  *  - the `writeHealthEntity` helper called at every evaluation-write site.
  */
 import { z } from "zod";
-import { HealthCheckStatusSchema } from "@checkstack/healthcheck-common";
+import { SystemHealthStatusSchema } from "@checkstack/healthcheck-common";
 import type { AdvisoryLockService } from "@checkstack/backend-api";
 import type {
   EntityChangeDeriver,
@@ -43,7 +43,13 @@ export const HEALTH_ENTITY_KIND = "health";
  * same durable data `getSystemHealthStatus` reads — never materialized.
  */
 export const HealthEntityStateSchema = z.object({
-  status: HealthCheckStatusSchema,
+  /**
+   * `unknown` when the system's checks have produced no runs to evaluate.
+   * Automations matching on `unhealthy` therefore do NOT fire for a system that
+   * is merely unmeasured - which is the point: an unmeasured system is not a
+   * detected outage, and inventing `healthy` for it would hide the gap instead.
+   */
+  status: SystemHealthStatusSchema,
   healthyChecks: z.number().int().nonnegative(),
   totalChecks: z.number().int().nonnegative(),
 });

package/src/health-state.ts

@@ -1,5 +1,5 @@
 import { and, desc, eq, gte, isNull } from "drizzle-orm";
-import type { HealthCheckStatus } from "@checkstack/healthcheck-common";
+import type { SystemHealthStatus } from "@checkstack/healthcheck-common";
 import type { Logger, SafeDatabase } from "@checkstack/backend-api";
 import type { InferClient } from "@checkstack/common";
 import { MaintenanceApi } from "@checkstack/maintenance-common";
@@ -20,8 +20,11 @@ type MaintenanceClient = InferClient<typeof MaintenanceApi>;
  * re-deriving the math each time.
  */
 export interface HealthState {
-  /** Aggregate status across all enabled checks. */
-  status: HealthCheckStatus;
+  /**
+   * Aggregate status across all enabled checks. `unknown` when nothing has been
+   * measured yet - the system has no checks, or none of them has ever run.
+   */
+  status: SystemHealthStatus;
   /**
    * When the system most recently entered `status`. Null when no
    * transition has been recorded yet (fail-safe: never throws).
@@ -58,7 +61,8 @@ export interface HealthState {
 
 /** Raw inputs to the pure builder, decoupled from the DB layer. */
 export interface HealthStateInputs {
-  status: HealthCheckStatus;
+  /** May be `unknown` - nothing measured yet. */
+  status: SystemHealthStatus;
   inStatusSince: Date | null;
   latencyMs?: number;
   avgLatencyMs?: number;
@@ -330,7 +334,7 @@ export async function computeHealthState({
    */
   environmentId?: string | null;
   /** Returns the aggregate status for the system (per-check when scoped). */
-  resolveStatus: () => Promise<HealthCheckStatus>;
+  resolveStatus: () => Promise<SystemHealthStatus>;
   maintenanceClient?: MaintenanceClient;
   logger?: Logger;
   /** Trailing window (minutes) for the transition count. */
@@ -341,7 +345,12 @@ export async function computeHealthState({
 
   const [inStatusSince, latest, windowed, inMaintenance, transitionsInWindow] =
     await Promise.all([
-      findInStatusSince({ db, systemId, status, environmentId }),
+      // An UNMEASURED system has no transition rows to find - and `unknown` is
+      // not a member of the transition table's status enum, so querying for it
+      // would be a database error, not merely an empty result.
+      status === "unknown"
+        ? Promise.resolve(null)
+        : findInStatusSince({ db, systemId, status, environmentId }),
       findLatestRun({ db, systemId, configurationId, environmentId }),
       computeWindowedMetrics({ db, systemId, configurationId, environmentId, now }),
       resolveInMaintenance({ maintenanceClient, systemId, logger }),

package/src/index.ts

@@ -1,8 +1,10 @@
 import {
   setupHealthCheckWorker,
   recomputeSystemRollupHealth,
+  persistRunAndReact,
 } from "./queue-executor";
 import { reconcileHealthCheckJobs } from "./schedule-reconciler";
+import { SatelliteApi } from "@checkstack/satellite-common";
 import { setupRetentionJob } from "./retention-job";
 import * as schema from "./schema";
 import {
@@ -522,6 +524,15 @@ export default createBackendPlugin({
           cache,
           secretResolver,
           internalSecrets,
+          // Lets a satellite-ONLY check notice that none of its satellites are
+          // online and record a degraded run, instead of silently recording
+          // nothing and leaving its last status on screen forever. Resolved by
+          // RPC so this plugin keeps no direct dependency on satellite-backend.
+          getOnlineSatelliteIds: async () => {
+            const satelliteClient = rpcClient.forPlugin(SatelliteApi);
+            const result = await satelliteClient.getOnlineSatelliteIds();
+            return result.satelliteIds;
+          },
         });
 
         // Setup retention job for tiered storage (daily aggregation)
@@ -592,6 +603,28 @@ export default createBackendPlugin({
               logger,
             });
           },
+          // Bind the service deps ONCE so an ingested satellite result drives
+          // the exact same post-run path (`persistRunAndReact`) as a local run:
+          // reactive entity write, cache reconcile, signals, automation hooks,
+          // transition, and notification. The router only supplies the per-run
+          // fields, so the two callers cannot drift.
+          reactToSatelliteRun: (run) =>
+            persistRunAndReact({
+              db: database,
+              service,
+              cache,
+              signalService,
+              notificationClient,
+              catalogClient,
+              maintenanceClient,
+              incidentClient,
+              getHealthEntity: () => healthEntity,
+              getEmitHook: () => storedEmitHook,
+              collectorRegistry,
+              advisoryLock,
+              logger,
+              ...run,
+            }),
         });
         rpc.registerRouter(healthCheckRouter, healthCheckContract);
 

package/src/queue-executor.test.ts

@@ -336,6 +336,276 @@ describe("Queue-Based Health Check Executor", () => {
     });
   });
 
+  describe("executeHealthCheckJob - satellite-only checks with no online satellite", () => {
+    /**
+     * Builds a worker whose one configuration is satellite-ONLY (includeLocal
+     * false, satellites assigned) and captures the queue handler.
+     */
+    const setupSatelliteOnlyWorker = async (opts: {
+      getOnlineSatelliteIds?: () => Promise<string[]>;
+      /** Override the assignment shape to model a configuration change. */
+      configRow?: Partial<{
+        includeLocal: boolean;
+        satelliteIds: string[];
+        paused: boolean;
+      }>;
+      /** Records every subscriber notification the run would deliver. */
+      onNotify?: (input: unknown) => void;
+    }) => {
+      const mockDb = createMockDb();
+      const mockLogger = createMockLogger();
+      const mockQueueManager = createMockQueueManager();
+      const mockSignalService = createMockSignalService();
+      const mockCatalogClient = createMockCatalogClient();
+
+      // The shared mock has no `selectDistinct`; the rollup read uses it.
+      (mockDb as any).selectDistinct = mock(() => ({
+        from: mock(() => ({
+          where: mock(() => Promise.resolve([])),
+        })),
+      }));
+
+      (mockDb.select as any) = mock(() => ({
+        from: mock(() => ({
+          innerJoin: mock(() => ({
+            where: mock(() =>
+              Promise.resolve([
+                {
+                  configId: "config-1",
+                  configName: "Satellite check",
+                  strategyId: "test-strategy",
+                  config: {},
+                  collectors: [],
+                  interval: 30,
+                  enabled: true,
+                  // The shape this branch exists for: executed by satellites,
+                  // never by the core. Overridable so a test can model an
+                  // assignment change.
+                  paused: false,
+                  includeLocal: false,
+                  satelliteIds: ["sat-1", "sat-2"],
+                  environmentIds: null,
+                  ...opts.configRow,
+                },
+              ]),
+            ),
+          })),
+          where: mock(() => Promise.resolve([])),
+        })),
+      }));
+
+      const queue =
+        mockQueueManager.getQueue<HealthCheckJobPayload>("health-checks");
+      let capturedHandler:
+        | ((job: { data: HealthCheckJobPayload }) => Promise<void>)
+        | undefined;
+      (queue.consume as any) = mock(
+        async (
+          handler: (job: { data: HealthCheckJobPayload }) => Promise<void>,
+        ) => {
+          capturedHandler = handler;
+        },
+      );
+
+      await setupHealthCheckWorker({
+        db: mockDb as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["db"],
+        advisoryLock: mockAdvisoryLock,
+        registry: createMockRegistry(),
+        collectorRegistry:
+          createMockCollectorRegistry() as unknown as Parameters<
+            typeof setupHealthCheckWorker
+          >[0]["collectorRegistry"],
+        logger: mockLogger,
+        queueManager: mockQueueManager,
+        signalService: mockSignalService,
+        catalogClient: mockCatalogClient as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["catalogClient"],
+        notificationClient: {
+          notifyForSubscription: (input: unknown) => {
+            opts.onNotify?.(input);
+            return Promise.resolve({ notifiedCount: 0 });
+          },
+        } as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["notificationClient"],
+        maintenanceClient: createMockMaintenanceClient() as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["maintenanceClient"],
+        incidentClient: createMockIncidentClient() as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["incidentClient"],
+        getEmitHook: () => undefined,
+        cache: passthroughCache,
+        slowCheckRuntime: null,
+        ...(opts.getOnlineSatelliteIds
+          ? { getOnlineSatelliteIds: opts.getOnlineSatelliteIds }
+          : {}),
+      });
+
+      return { capturedHandler, mockLogger, mockSignalService };
+    };
+
+    const run = async (
+      handler:
+        | ((job: { data: HealthCheckJobPayload }) => Promise<void>)
+        | undefined,
+    ) => {
+      await handler?.({
+        data: {
+          configId: "config-1",
+          systemId: "system-1",
+          environmentId: null,
+        },
+      });
+    };
+
+    it("stays silent while at least one assigned satellite is online", async () => {
+      const { capturedHandler, mockLogger } = await setupSatelliteOnlyWorker({
+        getOnlineSatelliteIds: async () => ["sat-2"],
+      });
+
+      await run(capturedHandler);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        expect.stringContaining("satellite-only, skipping local execution"),
+      );
+      expect(mockLogger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining("no online satellite"),
+      );
+    });
+
+    it("warns and records a run when NO assigned satellite is online", async () => {
+      // The regression this guards: the core used to return silently here, so a
+      // check whose satellites were all down kept displaying its last known
+      // status forever - a dead probe reading exactly like a passing one.
+      const { capturedHandler, mockLogger } = await setupSatelliteOnlyWorker({
+        getOnlineSatelliteIds: async () => [],
+      });
+
+      // `persistRunAndReact` needs the full insert/aggregate/entity chain, which
+      // this file's mock database does not provide - so the call throws HERE and
+      // not in production, where it is the same function every successful run
+      // goes through. That is a mock limit, not the behaviour under test: what
+      // this pins is that the executor took the RECORD path instead of the
+      // silent one. What gets recorded is pinned separately and purely by
+      // `buildUnobservableRun` in `satellite-liveness.test.ts`.
+      await run(capturedHandler).catch(() => {});
+
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("no online satellite"),
+      );
+      // It must NOT take the silent path.
+      expect(mockLogger.debug).not.toHaveBeenCalledWith(
+        expect.stringContaining("satellite-only, skipping local execution"),
+      );
+    });
+
+    it("stays silent when satellite liveness cannot be resolved", async () => {
+      // A transient failure to reach the satellite service must never mark every
+      // satellite-only check in the fleet degraded at once.
+      const { capturedHandler, mockLogger } = await setupSatelliteOnlyWorker({
+        getOnlineSatelliteIds: async () => {
+          throw new Error("satellite service unreachable");
+        },
+      });
+
+      await run(capturedHandler);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        expect.stringContaining("satellite-only, skipping local execution"),
+      );
+      expect(mockLogger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining("no online satellite"),
+      );
+    });
+
+    it("stays silent when no liveness resolver is wired at all", async () => {
+      // Pre-existing behaviour for a deployment without the resolver: the core
+      // says nothing and lets the satellites report.
+      const { capturedHandler, mockLogger } = await setupSatelliteOnlyWorker({});
+
+      await run(capturedHandler);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        expect.stringContaining("satellite-only, skipping local execution"),
+      );
+    });
+
+    /**
+     * An operator CHANGING an assignment must never look like a failure. These
+     * are the cases that have historically been got wrong: the platform reacts
+     * to a deliberate configuration change as though the check had broken.
+     */
+    it("records nothing when the satellites are removed from the assignment", async () => {
+      const { capturedHandler, mockLogger } = await setupSatelliteOnlyWorker({
+        // No satellite is online at all - but the assignment no longer names
+        // any, so this check is simply not satellite-only any more.
+        getOnlineSatelliteIds: async () => [],
+        configRow: { satelliteIds: [] },
+      });
+
+      await run(capturedHandler).catch(() => {});
+
+      expect(mockLogger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining("no online satellite"),
+      );
+    });
+
+    it("records nothing when local execution is turned back on", async () => {
+      const { capturedHandler, mockLogger } = await setupSatelliteOnlyWorker({
+        getOnlineSatelliteIds: async () => [],
+        configRow: { includeLocal: true },
+      });
+
+      await run(capturedHandler).catch(() => {});
+
+      expect(mockLogger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining("no online satellite"),
+      );
+    });
+
+    it("a PAUSED satellite-only check records nothing, even with every satellite offline", async () => {
+      // Paused is checked BEFORE the satellite branch, so a paused check is
+      // quiet on purpose and must not manufacture a degraded run.
+      const { capturedHandler, mockLogger } = await setupSatelliteOnlyWorker({
+        getOnlineSatelliteIds: async () => [],
+        configRow: { paused: true },
+      });
+
+      await run(capturedHandler).catch(() => {});
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        expect.stringContaining("is paused, skipping execution"),
+      );
+      expect(mockLogger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining("no online satellite"),
+      );
+    });
+
+    it("does NOT notify subscribers for the unobservable run", async () => {
+      // One offline satellite degrades EVERY check assigned to it in the same
+      // tick, and healthy -> degraded is an escalation, so notifying per check
+      // turns a single root cause into one alert per check. The satellite's own
+      // connectivity subscription reports the cause once. The RUN is still
+      // recorded - only the per-check alert is withheld.
+      const notified: unknown[] = [];
+      const { capturedHandler, mockLogger } = await setupSatelliteOnlyWorker({
+        getOnlineSatelliteIds: async () => [],
+        onNotify: (input) => notified.push(input),
+      });
+
+      await run(capturedHandler).catch(() => {});
+
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("no online satellite"),
+      );
+      expect(notified).toHaveLength(0);
+    });
+  });
+
   describe("executeHealthCheckJob - collector run-context", () => {
     it("passes curated run-context to the collector (name falls back to id when configName is null)", async () => {
       const mockDb = createMockDb();