@checkstack/healthcheck-backend 1.10.2 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # @checkstack/healthcheck-backend
 
+## 1.11.0
+
+### Minor Changes
+
+- defb97b: fix(healthcheck): emit a realtime signal on config/assignment changes
+
+  The health-check executor broadcasts run/status signals, but config and
+  assignment CRUD (create/update/delete/pause/resume, associate/disassociate,
+  create-and-assign) emitted nothing - so a check created or edited out-of-band
+  (the AI assistant, GitOps, another pod/user) did not appear in an open Health
+  Checks list until the first run fired a status signal, up to an interval later.
+
+  Add a `HEALTHCHECK_CONFIG_CHANGED` (`healthcheck.config.changed`) signal,
+  broadcast from every config/assignment mutation, so the frontend signal
+  auto-invalidator refreshes the `[[healthcheck]]` cache on every connected client
+  immediately.
+
+- defb97b: feat(healthcheck): atomically create and assign a health check in one step
+
+  Add a `createAndAssign` RPC that creates a health-check configuration and
+  assigns it to a system in a single transaction, so the common "one system, one
+  check" case can never leave a dormant, unassigned check that runs nothing. When
+  the assignment is enabled it is scheduled immediately, exactly like
+  `associateSystem`.
+
+  The AI `healthcheck.propose` tool now prefers the HTTP strategy for a URL
+  (instead of authoring a script health check) and, when given `assignToSystemId`,
+  creates, assigns, and starts the check in the same approval.
+
+  Also fixes a latent bug where the `associateSystem` handler silently dropped the
+  per-assignment `notificationPolicy` before it reached the database.
+
+### Patch Changes
+
+- Updated dependencies [defb97b]
+- Updated dependencies [defb97b]
+- Updated dependencies [defb97b]
+- Updated dependencies [defb97b]
+- Updated dependencies [defb97b]
+- Updated dependencies [defb97b]
+- Updated dependencies [defb97b]
+  - @checkstack/ai-backend@0.10.0
+  - @checkstack/catalog-backend@1.6.0
+  - @checkstack/catalog-common@2.5.0
+  - @checkstack/common@0.18.0
+  - @checkstack/healthcheck-common@1.9.0
+  - @checkstack/automation-backend@0.10.2
+  - @checkstack/incident-backend@1.8.6
+  - @checkstack/incident-common@1.6.4
+  - @checkstack/maintenance-common@1.7.4
+  - @checkstack/sdk@0.116.1
+  - @checkstack/ai-common@0.6.2
+  - @checkstack/backend-api@0.26.1
+  - @checkstack/cache-api@0.3.15
+  - @checkstack/command-backend@0.2.14
+  - @checkstack/gitops-backend@0.5.14
+  - @checkstack/gitops-common@0.6.7
+  - @checkstack/notification-common@1.4.2
+  - @checkstack/queue-api@0.3.15
+  - @checkstack/satellite-backend@0.7.3
+  - @checkstack/script-packages-backend@0.3.18
+  - @checkstack/secrets-backend@0.2.14
+  - @checkstack/secrets-common@0.2.7
+  - @checkstack/signal-common@0.2.13
+  - @checkstack/status-page-backend@0.4.1
+  - @checkstack/status-page-common@0.4.1
+  - @checkstack/cache-utils@0.2.20
+
 ## 1.10.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-backend",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,32 +14,32 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.26.0",
-    "@checkstack/ai-backend": "0.9.1",
-    "@checkstack/ai-common": "0.6.1",
-    "@checkstack/script-packages-backend": "0.3.17",
-    "@checkstack/cache-api": "0.3.14",
-    "@checkstack/cache-utils": "0.2.19",
-    "@checkstack/catalog-backend": "1.5.5",
-    "@checkstack/catalog-common": "2.4.3",
-    "@checkstack/command-backend": "0.2.13",
-    "@checkstack/common": "0.17.0",
-    "@checkstack/gitops-backend": "0.5.13",
-    "@checkstack/gitops-common": "0.6.6",
-    "@checkstack/healthcheck-common": "1.8.1",
-    "@checkstack/secrets-common": "0.2.6",
-    "@checkstack/secrets-backend": "0.2.13",
-    "@checkstack/incident-backend": "1.8.5",
-    "@checkstack/incident-common": "1.6.3",
-    "@checkstack/automation-backend": "0.10.1",
-    "@checkstack/maintenance-common": "1.7.3",
-    "@checkstack/notification-common": "1.4.1",
-    "@checkstack/queue-api": "0.3.14",
-    "@checkstack/satellite-backend": "0.7.2",
-    "@checkstack/sdk": "0.115.1",
-    "@checkstack/signal-common": "0.2.12",
-    "@checkstack/status-page-backend": "0.4.0",
-    "@checkstack/status-page-common": "0.4.0",
+    "@checkstack/backend-api": "0.26.1",
+    "@checkstack/ai-backend": "0.10.0",
+    "@checkstack/ai-common": "0.6.2",
+    "@checkstack/script-packages-backend": "0.3.18",
+    "@checkstack/cache-api": "0.3.15",
+    "@checkstack/cache-utils": "0.2.20",
+    "@checkstack/catalog-backend": "1.6.0",
+    "@checkstack/catalog-common": "2.5.0",
+    "@checkstack/command-backend": "0.2.14",
+    "@checkstack/common": "0.18.0",
+    "@checkstack/gitops-backend": "0.5.14",
+    "@checkstack/gitops-common": "0.6.7",
+    "@checkstack/healthcheck-common": "1.9.0",
+    "@checkstack/secrets-common": "0.2.7",
+    "@checkstack/secrets-backend": "0.2.14",
+    "@checkstack/incident-backend": "1.8.6",
+    "@checkstack/incident-common": "1.6.4",
+    "@checkstack/automation-backend": "0.10.2",
+    "@checkstack/maintenance-common": "1.7.4",
+    "@checkstack/notification-common": "1.4.2",
+    "@checkstack/queue-api": "0.3.15",
+    "@checkstack/satellite-backend": "0.7.3",
+    "@checkstack/sdk": "0.116.1",
+    "@checkstack/signal-common": "0.2.13",
+    "@checkstack/status-page-backend": "0.4.1",
+    "@checkstack/status-page-common": "0.4.1",
     "@hono/zod-validator": "^0.7.6",
     "drizzle-orm": "^0.45.0",
     "hono": "^4.12.25",
@@ -51,8 +51,8 @@
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.6",
-    "@checkstack/scripts": "0.6.4",
-    "@checkstack/test-utils-backend": "0.1.47",
+    "@checkstack/scripts": "0.6.5",
+    "@checkstack/test-utils-backend": "0.1.48",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "@types/tdigest": "^0.1.5",

package/src/ai/healthcheck-propose.test.ts

@@ -43,11 +43,13 @@ function fakeRpcClient({
   getStrategies,
   getCollectors,
   createConfiguration,
+  createAndAssign,
   validateConfiguration,
 }: {
   getStrategies: ReturnType<typeof mock>;
   getCollectors: ReturnType<typeof mock>;
   createConfiguration: ReturnType<typeof mock>;
+  createAndAssign?: ReturnType<typeof mock>;
   validateConfiguration?: ReturnType<typeof mock>;
 }): RpcClient {
   return {
@@ -55,6 +57,7 @@ function fakeRpcClient({
       getStrategies,
       getCollectors,
       createConfiguration,
+      createAndAssign: createAndAssign ?? mock(() => Promise.resolve({})),
       validateConfiguration: validateConfiguration ?? okValidate(),
     }),
   } as unknown as RpcClient;
@@ -265,4 +268,90 @@ describe("healthcheck.propose composite tool", () => {
     expect(createConfiguration).toHaveBeenCalledTimes(1);
     expect(result.configuration.id).toBe("hc1");
   });
+
+  test("description steers the model to HTTP, not script", () => {
+    const tool = createHealthcheckProposeTool();
+    // The model picked a script for a plain URL; the description must now make
+    // HTTP the default and call out the assign-in-one-step flow.
+    expect(tool.description).toContain("PREFER THE HTTP STRATEGY");
+    expect(tool.description).toContain("healthcheck-http.request");
+    expect(tool.description).toContain("assignToSystemId");
+  });
+
+  test("dryRun without a target system warns the check will not run yet", async () => {
+    const rpcClient = fakeRpcClient({
+      getStrategies: mock(() => Promise.resolve([httpStrategy])),
+      getCollectors: mock(() => Promise.resolve([])),
+      createConfiguration: mock(),
+    });
+    const tool = createHealthcheckProposeTool();
+
+    const preview = await tool.dryRun!({ input: validInput, principal, rpcClient });
+    expect(preview.summary).toContain("NOT assigned");
+  });
+
+  test("dryRun with a target system says it will assign + start the check", async () => {
+    const rpcClient = fakeRpcClient({
+      getStrategies: mock(() => Promise.resolve([httpStrategy])),
+      getCollectors: mock(() => Promise.resolve([])),
+      createConfiguration: mock(),
+    });
+    const tool = createHealthcheckProposeTool();
+
+    const preview = await tool.dryRun!({
+      input: { ...validInput, assignToSystemId: "sys1" },
+      principal,
+      rpcClient,
+    });
+    expect(preview.summary).toMatch(/assign/i);
+    expect(preview.summary).not.toContain("NOT assigned");
+  });
+
+  test("execute (apply) with assignToSystemId atomically creates AND assigns", async () => {
+    const created = {
+      id: "hc2",
+      name: "Probe foo status",
+      strategyId: "healthcheck-http.http",
+      config: { url: "https://foo.bar/status" },
+      intervalSeconds: 60,
+      paused: false,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    let captured: {
+      systemId?: string;
+      configuration?: { name?: string; strategyId?: string };
+    } = {};
+    const createAndAssign = mock(
+      (arg: {
+        systemId: string;
+        configuration: { name: string; strategyId: string };
+      }) => {
+        captured = arg;
+        return Promise.resolve(created);
+      },
+    );
+    const createConfiguration = mock(() => Promise.resolve(created));
+    const rpcClient = fakeRpcClient({
+      getStrategies: mock(() => Promise.resolve([httpStrategy])),
+      getCollectors: mock(() => Promise.resolve([])),
+      createConfiguration,
+      createAndAssign,
+    });
+    const tool = createHealthcheckProposeTool();
+
+    const result = await tool.execute({
+      input: { ...validInput, assignToSystemId: "sys1" },
+      principal,
+      rpcClient,
+    });
+
+    // The atomic create+assign path is used; the create-only path is NOT.
+    expect(createAndAssign).toHaveBeenCalledTimes(1);
+    expect(createConfiguration).not.toHaveBeenCalled();
+    expect(captured.systemId).toBe("sys1");
+    expect(captured.configuration?.name).toBe("Probe foo status");
+    expect(captured.configuration?.strategyId).toBe("healthcheck-http.http");
+    expect(result.configuration.id).toBe("hc2");
+  });
 });

package/src/ai/healthcheck-propose.ts

@@ -27,7 +27,22 @@ import { validateCollectorAssertions } from "./assertion-validation";
  * create skeleton (name, strategyId, config, intervalSeconds, collectors).
  */
 export const HealthcheckProposeInputSchema =
-  CreateHealthCheckConfigurationSchema;
+  CreateHealthCheckConfigurationSchema.extend({
+    /**
+     * Optional: the id of a system to atomically assign + start the check on in
+     * the SAME step (resolve a system name to its id with `catalog.listSystems`
+     * first). When set, the check is created, assigned, and starts running
+     * immediately. When omitted, the check is created but stays dormant until
+     * the operator assigns it to a system.
+     */
+    assignToSystemId: z.string().optional(),
+    /**
+     * Optional per-assignment environment selector, only meaningful with
+     * `assignToSystemId`. Omit (or null) to run once per environment the system
+     * belongs to (the default fan-out) - this is almost always what you want.
+     */
+    environmentIds: z.array(z.string()).nullable().optional(),
+  });
 
 export type HealthcheckProposeInput = z.infer<
   typeof HealthcheckProposeInputSchema
@@ -67,12 +82,13 @@ function formatIssues(
 }
 
 /**
- * Appended to every health-check propose summary + the tool description: a newly
- * created health check does NOT execute until it is assigned to a system, which
- * the model must tell the operator (it cannot assign automatically yet).
+ * Appended to a health-check propose summary (and echoed in the tool
+ * description) when the draft is NOT being assigned: a health check only runs
+ * once it is assigned to a system. The model should prefer to assign in the
+ * same step by passing `assignToSystemId`.
  */
-const SYSTEM_ASSIGNMENT_HINT =
-  "A new health check does not run until it is assigned to a system - after it is applied, tell the operator they must assign it to a system (Health Checks -> the check -> assign to a system) for it to start running.";
+const UNASSIGNED_GUIDANCE =
+  "This check is NOT assigned to a system yet, so it will not run. Prefer to assign it in the same step: resolve the target system's id with catalog.listSystems and pass it as assignToSystemId so the check is created, assigned, and started immediately. Otherwise, tell the operator to assign it to a system (Health Checks -> the check -> assign to a system) for it to start running.";
 
 /**
  * Validate a drafted health-check configuration via the health-check plugin's
@@ -248,7 +264,10 @@ export function createHealthcheckProposeTool(): RegisteredAiTool<
       scriptCollectors.length > 0
         ? ` (includes ${scriptCollectors.length} script collector${scriptCollectors.length === 1 ? "" : "s"})`
         : "";
-    const summary = `Create health check "${input.name}" using strategy "${strategy.displayName}" with ${collectorCount} collector(s), running every ${input.intervalSeconds}s${scriptNote}. ${SYSTEM_ASSIGNMENT_HINT}`;
+    const assignmentNote = input.assignToSystemId
+      ? " Then assign it to the selected system and start it immediately - it runs once per environment the system belongs to."
+      : ` ${UNASSIGNED_GUIDANCE}`;
+    const summary = `Create health check "${input.name}" using strategy "${strategy.displayName}" with ${collectorCount} collector(s), running every ${input.intervalSeconds}s${scriptNote}.${assignmentNote}`;
 
     return {
       summary,
@@ -261,7 +280,7 @@ export function createHealthcheckProposeTool(): RegisteredAiTool<
   return {
     name: "healthcheck.propose",
     description:
-      "Validate a drafted health check (strategy, collectors, interval, and any inline script source) and return it for a human to review and apply. Never creates a health check directly - a person must approve the proposal. Use this to turn a natural-language health-check request (including a script health check) into a concrete, validated draft after testing the script with testScript. If you do not know what an endpoint returns, call probeUrl first to inspect its status code and body, then assert on the real response. Use getCapabilitySchema to get exact collector config fields AND the assertable result fields + valid operators before drafting assertions (assertion field must be a result-schema field like statusCode, operator must be a full word like equals/greaterThan, never an abbreviation). Note: a newly created health check does not run until the operator assigns it to a system.",
+      'Validate a drafted health check (strategy, collectors, interval, and any inline script source) and return it for a human to review and apply. Never creates a health check directly - a person must approve the proposal. PREFER THE HTTP STRATEGY for anything reachable over HTTP(S): for a plain URL, use strategyId "http" with the "healthcheck-http.request" collector (config { url }) and assert on statusCode - do NOT author a SCRIPT health check unless the user explicitly asks for a script or no built-in strategy fits the target. To make the check actually run, pass assignToSystemId so it is created AND assigned in one step (resolve the system\'s id with catalog.listSystems first; create the system with catalog.createSystem if it does not exist). Most systems have exactly one check. If you do not know what an endpoint returns, call probeUrl first to inspect its status code and body, then assert on the real response. For a script health check, test it with testScript first. Use getCapabilitySchema to get exact collector config fields AND the assertable result fields + valid operators before drafting assertions (assertion field must be a result-schema field like statusCode, operator must be a full word like equals/greaterThan, never an abbreviation).',
     effect: "mutate",
     input: HealthcheckProposeInputSchema,
     requiredAccessRules: [
@@ -273,17 +292,32 @@ export function createHealthcheckProposeTool(): RegisteredAiTool<
     dryRun,
     async execute({ input, rpcClient }) {
       // Only reached via `apply` (the propose/apply token gate). The create
-      // handler runs its own zod + registry validation; this re-validates the
+      // handler runs its own zod + registry validation; re-validating the
       // server-stored payload against the input schema is already done by the
       // propose/apply service before we get here.
       const healthcheckClient = rpcClient.forPlugin(HealthCheckApi);
-      const configuration = await healthcheckClient.createConfiguration({
+      const configurationInput = {
         name: input.name,
         strategyId: input.strategyId,
         config: input.config,
         intervalSeconds: input.intervalSeconds,
         collectors: input.collectors,
-      });
+      };
+
+      // When a target system is named, atomically create AND assign so the
+      // check starts running immediately - no dormant, unassigned check. The
+      // user-scoped client enforces `catalog.system` manage on that system.
+      if (input.assignToSystemId) {
+        const configuration = await healthcheckClient.createAndAssign({
+          configuration: configurationInput,
+          systemId: input.assignToSystemId,
+          environmentIds: input.environmentIds,
+        });
+        return { configuration };
+      }
+
+      const configuration =
+        await healthcheckClient.createConfiguration(configurationInput);
       return { configuration };
     },
   };

package/src/index.ts

@@ -479,6 +479,7 @@ export default createBackendPlugin({
           catalogClient,
           maintenanceClient,
           logger,
+          signalService,
         });
         rpc.registerRouter(healthCheckRouter, healthCheckContract);
 

package/src/router-create-and-assign.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect, mock } from "bun:test";
+import { createHealthCheckRouter } from "./router";
+import { createMockRpcContext } from "@checkstack/backend-api";
+import { call } from "@orpc/server";
+import type { HealthCheckCache } from "./cache";
+
+/**
+ * Router-level tests for the atomic create+assign path and the
+ * `notificationPolicy` forwarding regression. They use a capturing DB so the
+ * exact insert values reaching the database can be asserted (the bug being
+ * guarded was the `associateSystem` handler silently dropping
+ * `input.body.notificationPolicy`).
+ */
+
+const passthroughCache: HealthCheckCache = {
+  wrapSystemHealthStatus: (_systemId, loader) => loader(),
+  invalidateSystem: async () => {},
+  invalidateAllSystems: async () => 0,
+  scope: {} as HealthCheckCache["scope"],
+};
+
+const mockUser = {
+  type: "user" as const,
+  id: "test-user",
+  accessRules: ["*"],
+  roles: ["admin"],
+};
+
+interface CapturedInsert {
+  values: Record<string, unknown>;
+}
+
+/**
+ * A DB that records every `.values(...)` payload. Supports the chains the
+ * service uses: `insert().values().returning()`,
+ * `insert().values().onConflictDoUpdate()`, a bare awaited
+ * `insert().values()`, and `transaction(fn)` (createAndAssign).
+ */
+function createCapturingDb(captured: CapturedInsert[]) {
+  const insert = () => ({
+    values: (values: Record<string, unknown>) => {
+      captured.push({ values });
+      return Object.assign(Promise.resolve(undefined), {
+        onConflictDoUpdate: () => Promise.resolve(undefined),
+        onConflictDoNothing: () => Promise.resolve(undefined),
+        returning: () =>
+          Promise.resolve([
+            {
+              id: "cfg-new",
+              paused: false,
+              createdAt: new Date(),
+              updatedAt: new Date(),
+              collectors: null,
+              ...values,
+            },
+          ]),
+      });
+    },
+  });
+  const emptyWhere = Object.assign(Promise.resolve([]), {
+    where: () => Promise.resolve([]),
+  });
+  return {
+    insert,
+    select: () => ({ from: () => emptyWhere }),
+    transaction: async (fn: (tx: unknown) => Promise<unknown>) =>
+      fn({ insert }),
+  };
+}
+
+interface SignalBroadcast {
+  signalId: string;
+  payload: Record<string, unknown>;
+}
+
+function buildRouter(
+  captured: CapturedInsert[],
+  broadcasts?: SignalBroadcast[],
+) {
+  const signalService = broadcasts
+    ? ({
+        broadcast: (
+          signal: { id: string },
+          payload: Record<string, unknown>,
+        ) => {
+          broadcasts.push({ signalId: signal.id, payload });
+          return Promise.resolve();
+        },
+      } as never)
+    : undefined;
+  return createHealthCheckRouter({
+    database: createCapturingDb(captured) as never,
+    registry: { getStrategy: mock(() => undefined) } as never,
+    collectorRegistry: { getCollector: mock(() => undefined) } as never,
+    gitOpsClient: {
+      getProvenance: mock(() => Promise.resolve(null)),
+    } as never,
+    signalService,
+    getEmitHook: () => undefined,
+    cache: passthroughCache,
+    configService: {
+      get: mock(async () => undefined),
+      set: mock(async () => {}),
+    } as never,
+    catalogClient: { getSystem: mock(async () => null) } as never,
+    maintenanceClient: {
+      hasActiveMaintenance: mock(async () => ({ active: false })),
+    } as never,
+    logger: {
+      debug: mock(() => {}),
+      info: mock(() => {}),
+      warn: mock(() => {}),
+      error: mock(() => {}),
+    } as never,
+  });
+}
+
+const policy = { suppressDeEscalations: true };
+const CONFIG_ID = "12345678-1234-4234-8234-123456789012";
+
+describe("associateSystem notificationPolicy forwarding (regression)", () => {
+  it("passes the per-assignment notificationPolicy through to the DB write", async () => {
+    const captured: CapturedInsert[] = [];
+    const router = buildRouter(captured);
+    const context = createMockRpcContext({ user: mockUser });
+
+    await call(
+      router.associateSystem,
+      {
+        systemId: "sys-1",
+        body: {
+          configurationId: CONFIG_ID,
+          enabled: false, // skip scheduling; we only assert the persisted row
+          includeLocal: true,
+          notificationPolicy: policy,
+        },
+      },
+      { context },
+    );
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0].values.notificationPolicy).toEqual(policy);
+    expect(captured[0].values.systemId).toBe("sys-1");
+  });
+});
+
+describe("createAndAssign router handler", () => {
+  it("atomically writes the config AND the assignment, forwarding policy + env fan-out", async () => {
+    const captured: CapturedInsert[] = [];
+    const router = buildRouter(captured);
+    const context = createMockRpcContext({ user: mockUser });
+
+    const result = await call(
+      router.createAndAssign,
+      {
+        systemId: "sys-1",
+        configuration: {
+          name: "Payments API root",
+          strategyId: "healthcheck-http.http",
+          config: { url: "https://api.example.com/healthz" },
+          intervalSeconds: 60,
+        },
+        enabled: false,
+        includeLocal: true,
+        environmentIds: null,
+        notificationPolicy: policy,
+      },
+      { context },
+    );
+
+    // Two writes: the config row, then the assignment row.
+    expect(captured).toHaveLength(2);
+    const configInsert = captured.find(
+      (c) => c.values.name === "Payments API root",
+    );
+    const assignmentInsert = captured.find(
+      (c) => c.values.configurationId !== undefined,
+    );
+    expect(configInsert).toBeDefined();
+    expect(assignmentInsert).toBeDefined();
+    expect(assignmentInsert?.values.systemId).toBe("sys-1");
+    expect(assignmentInsert?.values.notificationPolicy).toEqual(policy);
+    // null environmentIds = fan out to all of the system's environments.
+    expect(assignmentInsert?.values.environmentIds).toBeNull();
+    // Returns the created configuration.
+    expect(result.name).toBe("Payments API root");
+    expect(result.id).toBe("cfg-new");
+  });
+
+  it("broadcasts healthcheck.config.changed so open clients refresh", async () => {
+    const captured: CapturedInsert[] = [];
+    const broadcasts: SignalBroadcast[] = [];
+    const router = buildRouter(captured, broadcasts);
+    const context = createMockRpcContext({ user: mockUser });
+
+    await call(
+      router.createAndAssign,
+      {
+        systemId: "sys-1",
+        configuration: {
+          name: "Payments API root",
+          strategyId: "healthcheck-http.http",
+          config: { url: "https://api.example.com/healthz" },
+          intervalSeconds: 60,
+        },
+        enabled: false,
+        includeLocal: true,
+        environmentIds: null,
+      },
+      { context },
+    );
+
+    const change = broadcasts.find(
+      (b) => b.signalId === "healthcheck.config.changed",
+    );
+    expect(change).toBeDefined();
+    expect(change?.payload.entity).toBe("assignment");
+    expect(change?.payload.systemId).toBe("sys-1");
+  });
+});

package/src/router.ts

@@ -9,8 +9,12 @@ import {
   type CollectorRegistry,
   type ConfigService,
 } from "@checkstack/backend-api";
-import { healthCheckContract } from "@checkstack/healthcheck-common";
+import {
+  healthCheckContract,
+  HEALTHCHECK_CONFIG_CHANGED,
+} from "@checkstack/healthcheck-common";
 import type { StrategyCategory } from "@checkstack/healthcheck-common";
+import { type SignalService } from "@checkstack/signal-common";
 import {
   resolveResolutionRootFromStore,
   resolveScriptPackagesDir,
@@ -21,7 +25,7 @@ import { runCollectorScriptTest } from "./collector-script-test";
 import { healthCheckHooks } from "./hooks";
 import * as schema from "./schema";
 import { toJsonSchemaWithChartMeta } from "./schema-utils";
-import type { InferClient } from "@checkstack/common";
+import { extractErrorMessage, type InferClient } from "@checkstack/common";
 import { GitOpsApi } from "@checkstack/gitops-common";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { MaintenanceApi } from "@checkstack/maintenance-common";
@@ -45,6 +49,14 @@ export const createHealthCheckRouter = (opts: {
   catalogClient: InferClient<typeof CatalogApi>;
   maintenanceClient: InferClient<typeof MaintenanceApi>;
   logger: Logger;
+  /**
+   * Broadcasts `healthcheck.config.changed` so every client's `[[healthcheck]]`
+   * cache refreshes after a config/assignment mutation - the only way an
+   * out-of-band write (AI assistant, GitOps, another pod/user) reaches an
+   * already-open Health Checks list before the first run fires a status signal.
+   * Optional so existing tests can omit it.
+   */
+  signalService?: SignalService;
 }) => {
   const {
     database,
@@ -56,6 +68,7 @@ export const createHealthCheckRouter = (opts: {
     catalogClient,
     maintenanceClient,
     logger,
+    signalService,
   } = opts;
   // Create service instance once - shared across all handlers
   const service = new HealthCheckService(
@@ -84,6 +97,77 @@ export const createHealthCheckRouter = (opts: {
     }
   };
 
+  /**
+   * Fire the `healthcheck.config.changed` signal so every client's
+   * `[[healthcheck]]` cache refreshes after a config/assignment write (the
+   * executor's run/status signals only fire once a check actually runs).
+   * Best-effort: a signal failure must never fail the mutation.
+   */
+  const broadcastConfigChanged = async (payload: {
+    entity: "configuration" | "assignment";
+    action: "created" | "updated" | "deleted";
+    configurationId?: string;
+    systemId?: string;
+  }) => {
+    try {
+      await signalService?.broadcast(HEALTHCHECK_CONFIG_CHANGED, payload);
+    } catch (error) {
+      logger.warn(
+        `Failed to broadcast healthcheck.config.changed signal: ${extractErrorMessage(error, "unknown")}`,
+      );
+    }
+  };
+
+  /**
+   * Post-assignment side effects shared by `associateSystem` and
+   * `createAndAssign`: invalidate the system cache, schedule the first run when
+   * the assignment is enabled, and emit the `assignmentChanged` hook. Kept in
+   * one place so both entry points stay in lock-step and an enabled assignment
+   * always starts running immediately.
+   */
+  const scheduleAndNotifyAssignment = async (args: {
+    systemId: string;
+    configurationId: string;
+    enabled: boolean;
+    queueManager: RpcContext["queueManager"];
+  }) => {
+    await cache.invalidateSystem(args.systemId);
+
+    // If enabling the health check, schedule it immediately so it starts
+    // probing right away.
+    if (args.enabled) {
+      const config = await service.getConfiguration(args.configurationId);
+      if (config) {
+        const { scheduleHealthCheck } = await import("./queue-executor");
+        await scheduleHealthCheck({
+          queueManager: args.queueManager,
+          payload: {
+            configId: config.id,
+            systemId: args.systemId,
+          },
+          intervalSeconds: config.intervalSeconds,
+        });
+      }
+    }
+
+    // Notify subscribers (e.g., satellite-backend) that assignments changed.
+    const emitHook = getEmitHook();
+    if (emitHook) {
+      await emitHook(healthCheckHooks.assignmentChanged, {
+        systemId: args.systemId,
+        configurationId: args.configurationId,
+      });
+    }
+
+    // Refresh every client's Health Checks / assignment views.
+    await broadcastConfigChanged({
+      entity: "assignment",
+      action: "updated",
+      configurationId: args.configurationId,
+      systemId: args.systemId,
+    });
+  };
+
   return os.router({
     getStrategies: os.getStrategies.handler(async ({ context }) => {
       return context.healthCheckRegistry.getStrategiesWithMeta().map((r) => ({
@@ -164,6 +248,11 @@ export const createHealthCheckRouter = (opts: {
       // safe move is to drop every per-system status cache so the next read
       // recomputes from fresh DB state.
       await cache.invalidateAllSystems();
+      await broadcastConfigChanged({
+        entity: "configuration",
+        action: "created",
+        configurationId: created.id,
+      });
       return created;
     }),
 
@@ -195,6 +284,11 @@ export const createHealthCheckRouter = (opts: {
       }
       // Configuration update affects every system that has it associated.
       await cache.invalidateAllSystems();
+      await broadcastConfigChanged({
+        entity: "configuration",
+        action: "updated",
+        configurationId: config.id,
+      });
       return config;
     }),
 
@@ -202,18 +296,33 @@ export const createHealthCheckRouter = (opts: {
       await enforceNotGitOpsLocked("Healthcheck", input.id);
       await service.deleteConfiguration(input.id);
       await cache.invalidateAllSystems();
+      await broadcastConfigChanged({
+        entity: "configuration",
+        action: "deleted",
+        configurationId: input.id,
+      });
     }),
 
     pauseConfiguration: os.pauseConfiguration.handler(async ({ input }) => {
       await enforceNotGitOpsLocked("Healthcheck", input.id);
       await service.pauseConfiguration(input.id);
       await cache.invalidateAllSystems();
+      await broadcastConfigChanged({
+        entity: "configuration",
+        action: "updated",
+        configurationId: input.id,
+      });
     }),
 
     resumeConfiguration: os.resumeConfiguration.handler(async ({ input }) => {
       await enforceNotGitOpsLocked("Healthcheck", input.id);
       await service.resumeConfiguration(input.id);
       await cache.invalidateAllSystems();
+      await broadcastConfigChanged({
+        entity: "configuration",
+        action: "updated",
+        configurationId: input.id,
+      });
     }),
 
     getSystemConfigurations: os.getSystemConfigurations.handler(
@@ -238,35 +347,37 @@ export const createHealthCheckRouter = (opts: {
         satelliteIds: input.body.satelliteIds,
         environmentIds: input.body.environmentIds,
         includeLocal: input.body.includeLocal,
+        notificationPolicy: input.body.notificationPolicy,
       });
-      await cache.invalidateSystem(input.systemId);
-
-      // If enabling the health check, schedule it immediately
-      if (input.body.enabled) {
-        const config = await service.getConfiguration(
-          input.body.configurationId,
-        );
-        if (config) {
-          const { scheduleHealthCheck } = await import("./queue-executor");
-          await scheduleHealthCheck({
-            queueManager: context.queueManager,
-            payload: {
-              configId: config.id,
-              systemId: input.systemId,
-            },
-            intervalSeconds: config.intervalSeconds,
-          });
-        }
-      }
+      await scheduleAndNotifyAssignment({
+        systemId: input.systemId,
+        configurationId: input.body.configurationId,
+        enabled: input.body.enabled,
+        queueManager: context.queueManager,
+      });
+    }),
 
-      // Notify subscribers (e.g., satellite-backend) that assignments changed
-      const emitHook = getEmitHook();
-      if (emitHook) {
-        await emitHook(healthCheckHooks.assignmentChanged, {
-          systemId: input.systemId,
-          configurationId: input.body.configurationId,
-        });
-      }
+    createAndAssign: os.createAndAssign.handler(async ({ input, context }) => {
+      await enforceNotGitOpsLocked("System", input.systemId);
+      // Atomic create + assign in one transaction so the common 1-1 case can
+      // never leave a dormant, unassigned check.
+      const configuration = await service.createAndAssign({
+        configuration: input.configuration,
+        systemId: input.systemId,
+        enabled: input.enabled,
+        stateThresholds: input.stateThresholds,
+        satelliteIds: input.satelliteIds,
+        environmentIds: input.environmentIds,
+        includeLocal: input.includeLocal,
+        notificationPolicy: input.notificationPolicy,
+      });
+      await scheduleAndNotifyAssignment({
+        systemId: input.systemId,
+        configurationId: configuration.id,
+        enabled: input.enabled,
+        queueManager: context.queueManager,
+      });
+      return configuration;
     }),
 
     disassociateSystem: os.disassociateSystem.handler(async ({ input }) => {
@@ -282,6 +393,13 @@ export const createHealthCheckRouter = (opts: {
           configurationId: input.configId,
         });
       }
+
+      await broadcastConfigChanged({
+        entity: "assignment",
+        action: "deleted",
+        configurationId: input.configId,
+        systemId: input.systemId,
+      });
     }),
 
     getPlatformNotificationDefaults:

package/src/service.ts

@@ -291,6 +291,74 @@ export class HealthCheckService {
       });
   }
 
+  /**
+   * Atomically create a health-check configuration AND assign it to a system in
+   * a single transaction. Backs the `createAndAssign` RPC: the common 1-1
+   * onboarding case ("this system gets one check") can never leave a dormant,
+   * unassigned check because the config row and its `systemHealthChecks`
+   * assignment row commit together or not at all. Scheduling of the first run
+   * is the caller's (router's) responsibility, mirroring `associateSystem`.
+   */
+  async createAndAssign(props: {
+    configuration: CreateHealthCheckConfiguration;
+    systemId: string;
+    enabled?: boolean;
+    stateThresholds?: StateThresholds;
+    satelliteIds?: string[];
+    /**
+     * Per-assignment environment selector. `null` (or `undefined`) = all
+     * current environments; `[]` = opt out (env-less); non-empty = those ids.
+     */
+    environmentIds?: string[] | null;
+    includeLocal?: boolean;
+    notificationPolicy?: NotificationPolicy;
+  }): Promise<HealthCheckConfiguration> {
+    const {
+      configuration,
+      systemId,
+      enabled = true,
+      stateThresholds: stateThresholds_,
+      satelliteIds,
+      environmentIds,
+      includeLocal = true,
+      notificationPolicy,
+    } = props;
+
+    // Preserve the null/[]/list distinction faithfully (see associateSystem).
+    const environmentIdsValue: string[] | null = environmentIds ?? null;
+    const versionedThresholds: VersionedStateThresholds | undefined =
+      stateThresholds_ ? stateThresholds.create(stateThresholds_) : undefined;
+
+    const created = await this.db.transaction(async (tx) => {
+      const [config] = await tx
+        .insert(healthCheckConfigurations)
+        .values({
+          name: configuration.name,
+          strategyId: configuration.strategyId,
+          config: configuration.config,
+          collectors: configuration.collectors ?? undefined,
+          intervalSeconds: configuration.intervalSeconds,
+          isTemplate: false,
+        })
+        .returning();
+
+      await tx.insert(systemHealthChecks).values({
+        systemId,
+        configurationId: config.id,
+        enabled,
+        stateThresholds: versionedThresholds,
+        satelliteIds: satelliteIds ?? undefined,
+        environmentIds: environmentIdsValue,
+        includeLocal,
+        notificationPolicy: notificationPolicy ?? undefined,
+      });
+
+      return config;
+    });
+
+    return this.mapConfig(created);
+  }
+
   /**
    * Flip the `enabled` flag on an existing `systemHealthChecks` row
    * without touching any of the other configuration (thresholds,