@checkstack/satellite-backend 0.4.0 → 0.5.0

package/src/heartbeat-monitor.ts

@@ -1,110 +1,141 @@
-import type { Hook, Logger } from "@checkstack/backend-api";
+import type { Logger } from "@checkstack/backend-api";
 import type { SignalService } from "@checkstack/signal-common";
 import type { SatelliteService } from "./service";
-import {
-  SATELLITE_STATUS_CHANGED,
-  OFFLINE_THRESHOLD_MS,
-} from "@checkstack/satellite-common";
+import type { SatelliteConnectionEvent } from "./entity";
+import { computeStatus } from "./status";
+import { SATELLITE_STATUS_CHANGED } from "@checkstack/satellite-common";
 
 /**
- * Optional plug-point for firing the automation
- * `satellite.heartbeat_lost` trigger when the monitor observes a
- * satellite transitioning `online` → `offline`. Bound from
- * `afterPluginsReady`; when not provided, no hook fires.
+ * Plug-point for driving the heartbeat-lost (`online` → `offline`) edge into
+ * the reactive `satellite-connection` entity (reactive automation engine
+ * §10.6). Bound from `afterPluginsReady`; when not provided, no entity state is
+ * mirrored.
+ *
+ * The monitor flips ONLY `lastConnectionEvent` to `"heartbeat_lost"` (leaving
+ * the already-aged `lastHeartbeatAt` untouched, since it is what made the
+ * computed status `offline` in the first place). The change-deriver re-fires
+ * `satellite.heartbeat_lost`. The opposite edge (offline→online) is mirrored as
+ * `connected` by the WS handler on reconnect, so the monitor leaves it alone.
  */
-export interface SatelliteHeartbeatHookSink {
-  emitHook: <T>(hook: Hook<T>, payload: T) => Promise<void>;
-  heartbeatLostHook: Hook<{
-    satelliteId: string;
-    name: string;
-    region: string;
-    timestamp: string;
-  }>;
+export interface SatelliteHeartbeatEntitySink {
+  mirror: (satelliteId: string) => Promise<void>;
 }
 
 /**
- * Monitors satellite heartbeats and broadcasts status change signals.
- * Tracks previous state in-memory to detect transitions (online → offline, offline → online).
+ * Monitors satellite heartbeats and detects the online→offline transition from
+ * DURABLE state alone — no pod-local baseline.
+ *
+ * ## Horizontal-scale correctness
+ *
+ * The heartbeat-check job runs under ONE consumer group claimed by a VARYING
+ * pod. A process-local "previous status" map is therefore wrong: a pod with an
+ * empty map never sees the online→offline edge, so `connectionStatus` could get
+ * stuck `online` forever after a pod crash. This monitor instead reads every
+ * satellite's durable `(lastHeartbeatAt, lastConnectionEvent)`, computes status
+ * via {@link computeStatus} (the same wall-clock liveness rule the entity read
+ * uses), and detects the heartbeat-lost edge purely from durable state:
+ *
+ *   computed status is `offline` AND `lastConnectionEvent === "connected"`
+ *     ⇒ this satellite just lost its heartbeat (it was last marked connected,
+ *       but its heartbeat has now aged past the offline threshold).
+ *
+ * The mutate that flips `lastConnectionEvent` to `"heartbeat_lost"` is
+ * IDEMPOTENT across pods and redelivery: once it is `"heartbeat_lost"`, the
+ * predicate above is false, so re-runs (on any pod) are no-ops, and the entity
+ * handle's diff-on-unchanged suppresses any duplicate transition/event. Any pod
+ * can therefore drive the edge correctly, regardless of which pod (if any) ever
+ * observed the satellite online in memory.
  */
 export class HeartbeatMonitor {
   /**
-   * In-memory tracking of each satellite's last known status.
-   * Used to detect transitions and avoid redundant signal broadcasts.
+   * Pod-local broadcast-dedup ONLY (never the source of truth). The durable
+   * `lastConnectionEvent` flip is what makes detection idempotent; this set
+   * merely avoids re-broadcasting the same status-change signal from this pod on
+   * back-to-back checks. A fresh pod with an empty set still detects + mirrors
+   * the edge from durable state — it just also broadcasts once, which is benign.
    */
-  private previousStatuses = new Map<string, "online" | "offline">();
+  private broadcastedOffline = new Set<string>();
 
   constructor(
     private service: SatelliteService,
     private signalService: SignalService,
     private logger: Logger,
-    private hookSink?: SatelliteHeartbeatHookSink,
+    private entitySink?: SatelliteHeartbeatEntitySink,
   ) {}
 
   /**
-   * Check all satellites and broadcast status change signals for any transitions.
-   * Called periodically by a recurring queue job.
+   * Check all satellites and drive the heartbeat-lost edge for any that have
+   * aged out while still marked connected. Called periodically by a recurring
+   * queue job; safe to run on any pod and to redeliver.
    */
   async checkHeartbeats(): Promise<void> {
-    const allSatellites = await this.service.listSatellites();
+    const rows = await this.service.listConnectionLiveness();
+    const liveIds = new Set(rows.map((r) => r.id));
 
-    for (const satellite of allSatellites) {
-      const previousStatus = this.previousStatuses.get(satellite.id);
-      const currentStatus = satellite.status;
+    for (const row of rows) {
+      const status = computeStatus(row.lastHeartbeatAt);
+      const lostHeartbeat = this.hasLostHeartbeat({
+        status,
+        lastConnectionEvent: row.lastConnectionEvent,
+      });
 
-      // Detect transition
-      if (previousStatus !== undefined && previousStatus !== currentStatus) {
-        this.logger.info(
-          `Satellite ${satellite.name} (${satellite.region}) status: ${previousStatus} → ${currentStatus}`,
-        );
+      if (!lostHeartbeat) {
+        // Still online (or already past the lost edge / never connected):
+        // nothing to detect. Clear the broadcast-dedup marker once a satellite
+        // is no longer in the lost state so a future lost edge re-broadcasts.
+        if (status === "online") this.broadcastedOffline.delete(row.id);
+        continue;
+      }
+
+      // Durable heartbeat-lost edge: computed offline while still marked
+      // `connected`. Detected from durable state, so this fires correctly from
+      // ANY pod with no prior in-memory knowledge of the satellite.
+      this.logger.info(
+        `Satellite ${row.name} (${row.region}) lost heartbeat (online → offline)`,
+      );
 
+      // Broadcast the status-change signal once per offline edge from this pod.
+      if (!this.broadcastedOffline.has(row.id)) {
+        this.broadcastedOffline.add(row.id);
         await this.signalService.broadcast(SATELLITE_STATUS_CHANGED, {
-          satelliteId: satellite.id,
-          status: currentStatus,
-          name: satellite.name,
-          region: satellite.region,
+          satelliteId: row.id,
+          status: "offline",
+          name: row.name,
+          region: row.region,
         });
+      }
 
-        // Fire the automation `heartbeat_lost` hook only on the
-        // online → offline edge. The opposite transition is observable
-        // via the `satellite.connected` hook fired by the WS handler.
-        if (
-          previousStatus === "online" &&
-          currentStatus === "offline" &&
-          this.hookSink
-        ) {
-          try {
-            await this.hookSink.emitHook(this.hookSink.heartbeatLostHook, {
-              satelliteId: satellite.id,
-              name: satellite.name,
-              region: satellite.region,
-              timestamp: new Date().toISOString(),
-            });
-          } catch (error) {
-            this.logger.error(
-              `Failed to emit satellite.heartbeat_lost hook for ${satellite.name}:`,
-              error,
-            );
-          }
+      // Drive the entity edge. The mutate is idempotent: it flips
+      // `lastConnectionEvent` to `"heartbeat_lost"`, after which this branch is
+      // never re-entered for the same satellite (re-runs are no-ops).
+      if (this.entitySink) {
+        try {
+          await this.entitySink.mirror(row.id);
+        } catch (error) {
+          this.logger.error(
+            `Failed to mirror satellite-connection (heartbeat_lost) for ${row.name}:`,
+            error,
+          );
         }
       }
-
-      this.previousStatuses.set(satellite.id, currentStatus);
     }
 
-    // Clean up tracked satellites that no longer exist
-    const currentIds = new Set(allSatellites.map((s) => s.id));
-    for (const trackedId of this.previousStatuses.keys()) {
-      if (!currentIds.has(trackedId)) {
-        this.previousStatuses.delete(trackedId);
-      }
+    // Drop broadcast-dedup markers for satellites that no longer exist.
+    for (const id of this.broadcastedOffline) {
+      if (!liveIds.has(id)) this.broadcastedOffline.delete(id);
     }
   }
 
   /**
-   * Get the offline threshold in milliseconds.
-   * Exposed for testing.
+   * Pure predicate: a satellite has just lost its heartbeat when its computed
+   * status is `offline` but its last recorded lifecycle edge still says it was
+   * `connected`. Once the edge is mirrored (`lastConnectionEvent` becomes
+   * `"heartbeat_lost"`), this returns false — the idempotency guarantee.
    */
-  static get OFFLINE_THRESHOLD_MS(): number {
-    return OFFLINE_THRESHOLD_MS;
+  private hasLostHeartbeat(props: {
+    status: "online" | "offline";
+    lastConnectionEvent: SatelliteConnectionEvent | null;
+  }): boolean {
+    return props.status === "offline" && props.lastConnectionEvent === "connected";
   }
 }

package/src/hooks.ts

@@ -2,8 +2,15 @@ import { createHook } from "@checkstack/backend-api";
 
 /**
  * Satellite hooks for cross-plugin communication.
- * Other plugins (e.g., healthcheck-backend) can subscribe to clean up
- * when a satellite is removed.
+ *
+ * The connection-lifecycle hooks (`satellite.connected` / `.disconnected` /
+ * `.heartbeat_lost`) were removed in Phase 4 (reactive automation engine
+ * §10.6): satellite connection state is now the reactive
+ * `satellite-connection` entity (see `./entity.ts`), and the equivalent
+ * trigger events are derived from its changes.
+ *
+ * `satellite.removed` stays — it is a deletion/cleanup signal (consumed by
+ * healthcheck-backend to scrub the satellite's id), not entity state.
  */
 export const satelliteHooks = {
   /**
@@ -14,41 +21,4 @@ export const satelliteHooks = {
   satelliteRemoved: createHook<{
     satelliteId: string;
   }>("satellite.removed"),
-
-  /**
-   * Emitted when a satellite WebSocket completes authentication and
-   * registers itself in the in-memory connection map.
-   */
-  connected: createHook<{
-    satelliteId: string;
-    name: string;
-    region: string;
-    timestamp: string;
-  }>("satellite.connected"),
-
-  /**
-   * Emitted when a previously-connected satellite's WebSocket closes
-   * (graceful or otherwise). Distinct from `heartbeatLost`: this fires
-   * the moment the socket drops, regardless of whether the satellite
-   * comes back within the heartbeat window.
-   */
-  disconnected: createHook<{
-    satelliteId: string;
-    name: string;
-    region: string;
-    timestamp: string;
-  }>("satellite.disconnected"),
-
-  /**
-   * Emitted by the heartbeat monitor when a satellite's status
-   * transitions from `online` to `offline` — i.e. no heartbeat for
-   * longer than `OFFLINE_THRESHOLD_MS`. Used by automations that
-   * page on stale satellites.
-   */
-  heartbeatLost: createHook<{
-    satelliteId: string;
-    name: string;
-    region: string;
-    timestamp: string;
-  }>("satellite.heartbeat_lost"),
 } as const;

package/src/index.ts

@@ -9,6 +9,10 @@ import {
 } from "@checkstack/satellite-common";
 import { HealthCheckApi } from "@checkstack/healthcheck-common";
 import { healthCheckHooks } from "@checkstack/healthcheck-backend";
+import { ScriptPackagesApi } from "@checkstack/script-packages-common";
+import { scriptPackagesChangedHook } from "@checkstack/script-packages-backend";
+import { secretResolverRef } from "@checkstack/secrets-backend";
+import { resolveSatelliteRunSecrets } from "./run-secret-resolver";
 import { SatelliteService } from "./service";
 import { createSatelliteRouter } from "./router";
 import { HeartbeatMonitor } from "./heartbeat-monitor";
@@ -16,9 +20,21 @@ import { SatelliteWsHandler } from "./satellite-ws-handler";
 import { ConfigRelay } from "./config-relay";
 import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
 import { registerSatelliteGitOpsKinds } from "./satellite-gitops-kinds";
-import { automationTriggerExtensionPoint } from "@checkstack/automation-backend";
+import {
+  automationTriggerExtensionPoint,
+  entityExtensionPoint,
+  withEntityWrite,
+  type EntityHandle,
+} from "@checkstack/automation-backend";
+import {
+  SATELLITE_CONNECTION_ENTITY_KIND,
+  createSatelliteConnectionRead,
+  deriveSatelliteConnectionEvents,
+  satelliteChangeToPayload,
+  satelliteConnectionStateSchema,
+  type SatelliteConnectionState,
+} from "./entity";
 import { satelliteTriggers } from "./automations";
-import { satelliteHooks } from "./hooks";
 
 // Queue and job constants
 const HEARTBEAT_QUEUE = "satellite-heartbeat";
@@ -30,7 +46,29 @@ export default createBackendPlugin({
   register(env) {
     env.registerAccessRules(satelliteAccessRules);
 
-    // ─── Automation Platform: triggers ───────────────────────────────
+    // ─── Automation Platform: reactive connection entity ─────────────
+    // Satellite connection state is the `satellite-connection` entity
+    // (reactive automation engine §10.6, §9.1), PLUGIN-BACKED (Model B) and
+    // COMPUTE-ON-READ: its `status` is DERIVED on read from the DURABLE, shared
+    // `satellites.lastHeartbeatAt` column (the single liveness source of truth,
+    // same as the admin list), and `lastConnectionEvent` is the only extra
+    // durable column (the deriver's event discriminator). There is NO stored
+    // status copy and NO framework `entity_state` mirror, so EVERY pod computes
+    // the same state AND a stale row self-heals to offline once the heartbeat
+    // ages out (this fixes the horizontal-scaling bug twice: the old in-memory
+    // map made pod A's satellite invisible to pod B, and the prior fix's stored
+    // status got stuck `online` after a pod crash because the heartbeat-lost
+    // EDGE was detected pod-locally). The three lifecycle sites (connect /
+    // disconnect / heartbeat-lost) write the liveness inputs through
+    // `handle.mutate`, and the framework records full transition HISTORY in
+    // `entity_transitions`.
+    //
+    // The `satellite.connected` / `.disconnected` / `.heartbeat_lost` trigger
+    // events are DERIVED from its changes (no hook-backed triggers). The
+    // ENTITY-DRIVEN triggers below stay registered so they remain in the
+    // editor's trigger catalog + payload-introspectable, and a `toPayload`
+    // mapper makes the runtime `trigger.payload` match their `payloadSchema`
+    // (mirroring incident / catalog / dependency / healthcheck).
     const automationTriggers = env.getExtensionPoint(
       automationTriggerExtensionPoint,
     );
@@ -38,6 +76,20 @@ export default createBackendPlugin({
       automationTriggers.registerTrigger(trigger, pluginMetadata);
     }
 
+    const entity = env.getExtensionPoint(entityExtensionPoint);
+    entity.registerChangeDeriver({
+      kind: SATELLITE_CONNECTION_ENTITY_KIND,
+      derive: deriveSatelliteConnectionEvents,
+      toPayload: satelliteChangeToPayload,
+    });
+    entity.declareNonReactiveState({
+      table: "satellites",
+      reason: "bookkeeping",
+      note: "lastHeartbeatAt is the raw liveness timestamp; the satellite-connection entity's reactive status is computed from it on read.",
+    });
+    // Created once in init; reused by the WS handler + heartbeat monitor.
+    let satelliteEntityHandle: EntityHandle<SatelliteConnectionState>;
+
     // ─── GitOps Entity Kind Registration ─────────────────────────────
     let gitopsService: SatelliteService | undefined;
     const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
@@ -58,6 +110,7 @@ export default createBackendPlugin({
         signalService: coreServices.signalService,
         queueManager: coreServices.queueManager,
         wsRegistry: coreServices.wsRegistry,
+        secretResolver: secretResolverRef,
       },
       init: async ({ logger, database, rpc, signalService }) => {
         logger.debug("🛰️ Initializing Satellite Backend...");
@@ -67,6 +120,20 @@ export default createBackendPlugin({
         );
         gitopsService = service;
 
+        // Declare the reactive `satellite-connection` entity once. PLUGIN-
+        // BACKED, COMPUTE-ON-READ: `read` computes status from the durable
+        // `satellites.lastHeartbeatAt` (+ reads `lastConnectionEvent`) via the
+        // service (the source of truth — no stored status copy, no
+        // `entity_state` mirror, globally consistent from any pod). The handle
+        // is the only typed path that drives connection-state changes (reactive
+        // automation engine §4.2); it is reused by the WS handler + heartbeat
+        // monitor wired in afterPluginsReady.
+        satelliteEntityHandle = entity.defineEntity({
+          kind: SATELLITE_CONNECTION_ENTITY_KIND,
+          state: satelliteConnectionStateSchema,
+          read: createSatelliteConnectionRead(service),
+        });
+
         const router = createSatelliteRouter({
           service,
           signalService,
@@ -83,8 +150,8 @@ export default createBackendPlugin({
         signalService,
         wsRegistry,
         rpcClient,
+        secretResolver,
         onHook,
-        emitHook,
       }) => {
         const service = new SatelliteService(
           database as SafeDatabase<typeof schema>,
@@ -125,9 +192,69 @@ export default createBackendPlugin({
           },
           logger,
           {
-            emitHook,
-            connectedHook: satelliteHooks.connected,
-            disconnectedHook: satelliteHooks.disconnected,
+            // Drive connect/disconnect through `handle.mutate` (Model B):
+            // `apply` UPDATEs the satellite row's durable liveness columns
+            // (`lastHeartbeatAt` + `lastConnectionEvent`) — the globally-
+            // readable source of truth — and returns the view (status COMPUTED
+            // from `lastHeartbeatAt`). The framework snapshots `prev` via
+            // `read`, records the transition (durable history), and emits the
+            // change; the deriver re-fires the equivalent trigger events.
+            mirror: async ({ satelliteId, lastEvent, lastHeartbeatAt }) => {
+              await withEntityWrite({
+                handle: satelliteEntityHandle,
+                id: satelliteId,
+                apply: () =>
+                  service.applyConnectionState({
+                    satelliteId,
+                    lastEvent,
+                    lastHeartbeatAt,
+                  }),
+              });
+            },
+          },
+          {
+            // Script-package distribution: carry the desired lockfile hash in
+            // assignment payloads + persist per-satellite reconcile state.
+            // Satellites pull blobs from CORE (getManifest/downloadBlob),
+            // never the registry.
+            getDesiredLockfileHash: async () => {
+              const spClient = rpcClient.forPlugin(ScriptPackagesApi);
+              const state = await spClient.getInstallState();
+              return state.lockfileHash;
+            },
+            reportSyncState: async (input) => {
+              const spClient = rpcClient.forPlugin(ScriptPackagesApi);
+              await spClient.reportSatelliteSyncState(input);
+            },
+            getManifest: async ({ lockfileHash }) => {
+              const spClient = rpcClient.forPlugin(ScriptPackagesApi);
+              const res = await spClient.getManifest({ lockfileHash });
+              return res.entries;
+            },
+            getBlobBase64: async ({ integrity }) => {
+              const spClient = rpcClient.forPlugin(ScriptPackagesApi);
+              try {
+                const res = await spClient.downloadBlob({ integrity });
+                return res.data;
+              } catch {
+                return null;
+              }
+            },
+          },
+          {
+            // JIT secret delivery: resolve a collector's declared secretEnv
+            // (read from the satellite's own assignment) via the central
+            // resolver. Values are returned over the WS channel per-run and
+            // never persisted.
+            resolveRunSecrets: async ({ satelliteId, configId, collectorId }) =>
+              resolveSatelliteRunSecrets({
+                satelliteId,
+                configId,
+                collectorId,
+                getAssignmentsForSatellite: (id) =>
+                  configRelay.getAssignmentsForSatellite(id),
+                resolver: secretResolver,
+              }),
           },
         );
 
@@ -142,8 +269,28 @@ export default createBackendPlugin({
           signalService,
           logger,
           {
-            emitHook,
-            heartbeatLostHook: satelliteHooks.heartbeatLost,
+            // Drive the online → offline (heartbeat-lost) edge through
+            // `handle.mutate`. `apply` flips ONLY `lastConnectionEvent` to
+            // `"heartbeat_lost"` (the aged `lastHeartbeatAt` is left untouched —
+            // it is what made the computed status `offline`). The framework
+            // records the transition (durable history) and the deriver re-fires
+            // `satellite.heartbeat_lost`. The mutate is idempotent: once
+            // `lastConnectionEvent === "heartbeat_lost"`, the monitor's
+            // predicate is false and re-runs (on any pod) are no-ops. This is
+            // the durable, any-pod offline-on-timeout backstop: a pod that dies
+            // without flipping its satellites to offline leaves a stale state
+            // only until ANY pod's monitor observes the heartbeat timeout.
+            mirror: async (satelliteId) => {
+              await withEntityWrite({
+                handle: satelliteEntityHandle,
+                id: satelliteId,
+                apply: () =>
+                  service.applyConnectionState({
+                    satelliteId,
+                    lastEvent: "heartbeat_lost",
+                  }),
+              });
+            },
           },
         );
 
@@ -184,6 +331,18 @@ export default createBackendPlugin({
           },
         );
 
+        // Fan the script-packages.changed broadcast out to THIS instance's
+        // connected satellites. Every core instance subscribes in broadcast
+        // mode, so each pushes to its own satellites; offline satellites
+        // converge via the assignment-carried lockfile hash on reconnect.
+        onHook(
+          scriptPackagesChangedHook,
+          async ({ lockfileHash }) => {
+            wsHandler.pushRefreshScriptPackagesToAll(lockfileHash);
+          },
+          { mode: "broadcast" },
+        );
+
         logger.debug("✅ Satellite Backend afterPluginsReady complete.");
       },
     });

package/src/run-secret-resolver.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from "bun:test";
+import type { SatelliteAssignment } from "@checkstack/satellite-common";
+import type { SecretResolverService } from "@checkstack/secrets-backend";
+import { resolveSatelliteRunSecrets } from "./run-secret-resolver";
+
+// A resolver that resolves from a fixed name->value map (mirrors the real
+// resolveForRun: substitute ${{ secrets.NAME }} per declared env entry).
+function fakeResolver(values: Record<string, string>): SecretResolverService {
+  const TEMPLATE_RE = /\$\{\{\s*secrets\.([a-zA-Z0-9_-]+)\s*\}\}/g;
+  return {
+    resolveSecret: async ({ name }) => {
+      if (!(name in values)) throw new Error(`Secret not found: ${name}`);
+      return values[name];
+    },
+    resolveBySchema: async ({ value }) => ({ resolved: value, warnings: [] }),
+    resolveForRun: async ({ secretEnv }) => {
+      const env: Record<string, string> = {};
+      for (const [envName, template] of Object.entries(secretEnv)) {
+        TEMPLATE_RE.lastIndex = 0;
+        env[envName] = template.replaceAll(TEMPLATE_RE, (_m, name: string) => {
+          if (!(name in values)) throw new Error(`Secret not found: ${name}`);
+          return values[name];
+        });
+      }
+      return {
+        env,
+        masking: {
+          size: 0,
+          maskText: (t) => t,
+          maskDeep: (v) => v,
+        },
+      };
+    },
+  };
+}
+
+function assignment(
+  configId: string,
+  collectors: SatelliteAssignment["collectors"],
+): SatelliteAssignment {
+  return {
+    configId,
+    systemId: "sys-1",
+    strategyId: "script",
+    config: {},
+    collectors,
+    intervalSeconds: 60,
+  };
+}
+
+describe("resolveSatelliteRunSecrets", () => {
+  it("resolves ONLY the collector's declared secretEnv from the assignment", async () => {
+    const assignments = [
+      assignment("config-1", [
+        {
+          id: "col-1",
+          collectorId: "inline-script",
+          config: { secretEnv: { API_TOKEN: "${{ secrets.jira_token }}" } },
+        },
+      ]),
+    ];
+    const env = await resolveSatelliteRunSecrets({
+      satelliteId: "sat-1",
+      configId: "config-1",
+      collectorId: "col-1",
+      getAssignmentsForSatellite: async () => assignments,
+      resolver: fakeResolver({ jira_token: "real-value", other: "nope" }),
+    });
+    expect(env).toEqual({ API_TOKEN: "real-value" });
+  });
+
+  it("throws when the assignment is not assigned to this satellite", async () => {
+    await expect(
+      resolveSatelliteRunSecrets({
+        satelliteId: "sat-1",
+        configId: "missing",
+        collectorId: "col-1",
+        getAssignmentsForSatellite: async () => [],
+        resolver: fakeResolver({}),
+      }),
+    ).rejects.toThrow(/No assignment/);
+  });
+
+  it("throws when the collector declares no secretEnv (least-privilege)", async () => {
+    const assignments = [
+      assignment("config-1", [
+        { id: "col-1", collectorId: "inline-script", config: {} },
+      ]),
+    ];
+    await expect(
+      resolveSatelliteRunSecrets({
+        satelliteId: "sat-1",
+        configId: "config-1",
+        collectorId: "col-1",
+        getAssignmentsForSatellite: async () => assignments,
+        resolver: fakeResolver({}),
+      }),
+    ).rejects.toThrow(/no secretEnv/);
+  });
+
+  it("propagates a clear error when a required secret cannot resolve", async () => {
+    const assignments = [
+      assignment("config-1", [
+        {
+          id: "col-1",
+          collectorId: "inline-script",
+          config: { secretEnv: { TOKEN: "${{ secrets.absent }}" } },
+        },
+      ]),
+    ];
+    await expect(
+      resolveSatelliteRunSecrets({
+        satelliteId: "sat-1",
+        configId: "config-1",
+        collectorId: "col-1",
+        getAssignmentsForSatellite: async () => assignments,
+        resolver: fakeResolver({}),
+      }),
+    ).rejects.toThrow(/Secret not found: absent/);
+  });
+});