threadforge 0.1.0

package/src/services/worker-bootstrap.js

@@ -0,0 +1,676 @@
+/**
+ * Worker Bootstrap v3
+ *
+ * Loads services, builds proxy clients, and injects them.
+ *
+ * After bootstrap, a service can call:
+ *   await this.users.getUser('123')
+ *
+ * Which transparently routes through:
+ *   - Direct function call (colocated services, same process)
+ *   - UDS (different process, same machine)
+ *   - Supervisor IPC fallback (startup race)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { EndpointResolver } from "../core/EndpointResolver.js";
+import { ForgeContext, NOT_HANDLED } from "../core/ForgeContext.js";
+import { RequestContext } from "../core/RequestContext.js";
+import { buildServiceProxies, createServiceProxy } from "../decorators/ServiceProxy.js";
+import { resolveStaticMountsForService } from "../frontend/SiteResolver.js";
+
+// A6: Consolidate all env var reads into a single structured config object
+function parseWorkerConfig() {
+  return {
+    groupName: process.env.FORGE_GROUP_NAME,
+    serviceEntries: process.env.FORGE_SERVICE_ENTRIES,
+    serviceNames: process.env.FORGE_SERVICE_NAMES,
+    port: process.env.FORGE_PORT,
+    workerId: process.env.FORGE_WORKER_ID,
+    threadCount: process.env.FORGE_THREAD_COUNT,
+    mode: process.env.FORGE_MODE,
+    serviceTypes: process.env.FORGE_SERVICE_TYPES,
+    channels: process.env.FORGE_CHANNELS,
+    hostMeta: process.env.FORGE_HOST_META,
+    registryMode: process.env.FORGE_REGISTRY_MODE ?? "embedded",
+    registryHost: process.env.FORGE_HOST,
+    servicePorts: process.env.FORGE_SERVICE_PORTS,
+    plugins: process.env.FORGE_PLUGINS,
+    servicePlugins: process.env.FORGE_SERVICE_PLUGINS,
+    configPath: process.env.FORGE_CONFIG_PATH,
+    serviceEndpoints: process.env.FORGE_SERVICE_ENDPOINTS,
+    sites: process.env.FORGE_SITES,
+    sitesFile: process.env.FORGE_SITES_FILE,
+  };
+}
+
+const workerConfig = parseWorkerConfig();
+const hostMeta = workerConfig.hostMeta ? JSON.parse(workerConfig.hostMeta) : null;
+let sites = null;
+let sitesPayload = workerConfig.sites;
+if (!sitesPayload && workerConfig.sitesFile) {
+  try {
+    sitesPayload = fs.readFileSync(workerConfig.sitesFile, "utf8");
+  } catch (err) {
+    console.warn(`[ThreadForge] Could not read FORGE_SITES_FILE, static mounts disabled: ${err.message}`);
+  }
+}
+if (sitesPayload) {
+  try {
+    sites = JSON.parse(sitesPayload);
+  } catch (err) {
+    console.warn(`[ThreadForge] Invalid FORGE_SITES payload, static mounts disabled: ${err.message}`);
+  }
+}
+
+async function _deliverRemoteEvent(url, body, headers, serviceName, maxRetries = 3) {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      const resp = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(5000),
+      });
+      if (resp.ok) return;
+      // Non-retryable status codes
+      if (resp.status >= 400 && resp.status < 500) return;
+    } catch (err) {
+      if (attempt === maxRetries - 1) {
+        console.error(`[ThreadForge] Remote event delivery to ${serviceName} failed after ${maxRetries} attempts: ${err.message}`);
+        return;
+      }
+    }
+    // Exponential backoff: 100ms, 200ms, 400ms
+    await new Promise(resolve => setTimeout(resolve, 100 * 2 ** attempt));
+  }
+}
+
+/**
+ * Look up which project owns a given service name.
+ * Returns { projectId, schema, keyPrefix } or null.
+ */
+function resolveProjectForService(serviceName) {
+  if (!hostMeta) return null;
+  for (const [projectId, meta] of Object.entries(hostMeta)) {
+    if (meta.services.includes(serviceName)) {
+      return { projectId, schema: meta.schema, keyPrefix: meta.keyPrefix };
+    }
+  }
+  return null;
+}
+
+// Hoisted reference so emergency shutdown handlers can access it
+/** @type {Map<string, {service: object, ctx: import('../core/ForgeContext.js').ForgeContext}>|null} */
+let _localServices = null;
+let emergencyShutdownPromise = null;
+// M-CORE-4: Module-level flag so emergencyShutdown can check if normal shutdown is running
+let shutdownInProgress = false;
+
+// Track unhandled rejections — exit only if 5+ within 60 seconds
+let _rejectionCount = 0;
+let _rejectionWindowStart = Date.now();
+const REJECTION_THRESHOLD = 5;
+const REJECTION_WINDOW_MS = 60_000;
+
+async function emergencyShutdown(reason, err) {
+  if (emergencyShutdownPromise) {
+    await emergencyShutdownPromise.catch(() => {});
+    process.exit(1);
+    return;
+  }
+  // M-CORE-4: Skip service._stop() if normal shutdown is already running
+  // to prevent double-cleanup of services
+  const skipServiceStop = shutdownInProgress;
+  emergencyShutdownPromise = (async () => {
+    console.error(`[ThreadForge] ${reason}:`, err);
+    try {
+      if (_localServices && !skipServiceStop) {
+        for (const [, { service }] of _localServices) {
+          try {
+            await Promise.race([
+              service._stop?.(),
+              new Promise((_, reject) => setTimeout(() => reject(new Error('Stop timed out')), 5000)),
+            ]);
+          } catch {}
+        }
+      }
+    } catch {}
+    process.exit(1);
+  })();
+  await emergencyShutdownPromise;
+}
+
+function handleUnhandledRejection(err) {
+  const now = Date.now();
+
+  // Reset window if it has elapsed
+  if (now - _rejectionWindowStart > REJECTION_WINDOW_MS) {
+    _rejectionCount = 0;
+    _rejectionWindowStart = now;
+  }
+  _rejectionCount++;
+
+  console.error(`[ThreadForge] SEVERE: Unhandled rejection (${_rejectionCount}/${REJECTION_THRESHOLD} in window):`, err);
+  if (err?.stack) console.error(err.stack);
+
+  if (_rejectionCount >= REJECTION_THRESHOLD) {
+    console.error(`[ThreadForge] ${REJECTION_THRESHOLD}+ unhandled rejections within ${REJECTION_WINDOW_MS / 1000}s — exiting`);
+    emergencyShutdown("Repeated unhandled rejections", err);
+  }
+}
+
+async function bootstrap() {
+  // RT-H2: Register emergency handlers early so exceptions during any phase get cleanup
+  process.on("uncaughtException", (err) => emergencyShutdown("Uncaught exception", err));
+  process.on("unhandledRejection", (err) => handleUnhandledRejection(err));
+
+  // RT-C2: Re-entrancy guard for graceful shutdown (uses module-level `shutdownInProgress`)
+
+  // H-RT-4: Register signal handlers early so SIGTERM/SIGINT during any phase triggers cleanup
+  process.once("SIGTERM", () => shutdown("SIGTERM"));
+  process.once("SIGINT", () => shutdown("SIGINT"));
+
+  const entries = workerConfig.serviceEntries.split(",")
+    .filter(e => e.trim())
+    .map((e) => {
+      const eqIdx = e.indexOf("=");
+      if (eqIdx === -1) {
+        throw new Error(`Invalid FORGE_SERVICE_ENTRIES format: "${e}". Expected "name=path".`);
+      }
+      const name = e.slice(0, eqIdx).trim();
+      const entryPath = e.slice(eqIdx + 1).trim();
+      if (!name || !entryPath) {
+        throw new Error(`Invalid FORGE_SERVICE_ENTRIES entry: "${e}". Name and path are both required.`);
+      }
+      return { name, entry: entryPath };
+    });
+
+  if (entries.length === 0) {
+    throw new Error("FORGE_SERVICE_ENTRIES is empty or contains no valid entries");
+  }
+
+  const typeMap = {};
+  if (workerConfig.serviceTypes) {
+    for (const pair of workerConfig.serviceTypes.split(",")) {
+      const [name, type] = pair.split("=");
+      typeMap[name] = type;
+    }
+  }
+
+  // Parse declared channels to know which services we might talk to
+  let declaredChannels = [];
+  try {
+    declaredChannels = JSON.parse(workerConfig.channels || "[]");
+  } catch {}
+
+  const port = parseInt(workerConfig.port, 10);
+  const workerId = parseInt(workerConfig.workerId, 10);
+  const threadCount = parseInt(workerConfig.threadCount, 10);
+
+  // Phase 1: Load all service modules (P13: parallel imports)
+  /** @type {Map<string, {ServiceClass: Function, instance: object}>} */
+  const loaded = new Map();
+  /** @type {Map<string, Function>} service name → class (for proxy building) */
+  const serviceClasses = new Map();
+
+  const resolvedEntries = entries.map(({ name, entry }) => ({
+    name,
+    entry,
+    url: pathToFileURL(path.resolve(process.cwd(), entry)).href,
+  }));
+
+  const importResults = await Promise.all(
+    resolvedEntries.map(async ({ name, entry, url }) => {
+      try {
+        const mod = await import(url);
+        return { name, entry, mod, error: null };
+      } catch (err) {
+        return { name, entry, mod: null, error: err };
+      }
+    }),
+  );
+
+  for (const { name, entry, mod, error } of importResults) {
+    if (error) {
+      console.error(`[ThreadForge] Failed to load service "${name}" from ${entry}: ${error.message}`);
+      if (error.stack) console.error(error.stack);
+      throw new Error(`Service "${name}" failed to load from "${entry}": ${error.message}`);
+    }
+    const ServiceClass = mod.default ?? mod;
+
+    if (typeof ServiceClass !== "function") {
+      throw new Error(`Service "${entry}" must export a class. Got: ${typeof ServiceClass}`);
+    }
+
+    const instance = new ServiceClass();
+    loaded.set(name, { ServiceClass, instance });
+    serviceClasses.set(name, ServiceClass);
+  }
+
+  // Also register remote service classes if we know about them
+  // (from channels config). For remote services we don't have the
+  // class, so proxies will use dynamic dispatch.
+  const allConnectedServices = new Set();
+  for (const ch of declaredChannels) {
+    allConnectedServices.add(ch.from);
+    allConnectedServices.add(ch.to);
+  }
+
+  // Phase 2: Create contexts and local service registry
+  /** @type {Map<string, {service: object, ctx: ForgeContext}>} */
+  const localServices = new Map();
+  _localServices = localServices;
+
+  function localSend(fromName, target, payload) {
+    const local = localServices.get(target);
+    if (!local) return false;
+    Promise.resolve(local.service.onMessage(fromName, payload)).catch((err) => {
+      local.ctx?.logger?.error?.("onMessage error", { from: fromName, error: err.message });
+      local.ctx?.metrics?.increment?.("forge_local_send_errors_total", { target });
+    });
+    return true;
+  }
+
+  async function localRequest(fromName, target, payload) {
+    const local = localServices.get(target);
+    if (local) {
+      return local.service.onRequest(fromName, payload);
+    }
+    return NOT_HANDLED;
+  }
+
+  // Create EndpointResolver from env — shared by all contexts in this worker
+  const endpointResolver = EndpointResolver.fromEnv();
+
+  for (const [name, { instance }] of loaded) {
+    const serviceType = typeMap[name] ?? "internal";
+    const isEdge = serviceType === "edge";
+
+    const ctx = new ForgeContext({
+      serviceName: name,
+      port: isEdge ? port : 0,
+      workerId,
+      threadCount,
+      mode: workerConfig.mode,
+      serviceType,
+      sendIPC: (msg) => {
+        if (process.send) process.send(msg);
+      },
+      localSend: (target, payload) => localSend(name, target, payload),
+      localRequest: (target, payload) => localRequest(name, target, payload),
+      staticMounts: resolveStaticMountsForService(name, sites),
+    });
+
+    ctx._endpointResolver = endpointResolver;
+
+    const projectInfo = resolveProjectForService(name);
+    if (projectInfo) {
+      ctx._projectId = projectInfo.projectId;
+      ctx._projectSchema = projectInfo.schema;
+      ctx._projectKeyPrefix = projectInfo.keyPrefix;
+    }
+
+    ctx._emitEvent = (eventName, data) => {
+      const eventPayload = { __forge_event: eventName, __forge_data: data };
+
+      for (const ch of declaredChannels) {
+        let target;
+        if (ch.from === name) target = ch.to;
+        else if (ch.to === name) target = ch.from;
+        else continue;
+
+        if (localSend(name, target, eventPayload)) continue;
+
+        const endpoint = endpointResolver.resolve(target);
+        if (endpoint?.remote) {
+          // Propagate RequestContext so events can be traced back to originating requests
+          const rctx = RequestContext.current();
+          const headers = { "Content-Type": "application/json" };
+          if (rctx) Object.assign(headers, rctx.toHeaders());
+          _deliverRemoteEvent(
+            `http://${endpoint.host}:${endpoint.port}/__forge/event`,
+            { from: name, event: eventName, data },
+            headers,
+            target,
+          );
+        } else {
+          ctx.send(target, eventPayload);
+        }
+      }
+    };
+
+    await instance._init(ctx);
+    ctx._serviceInstance = instance; // for /__forge/invoke endpoint
+    localServices.set(name, { service: instance, ctx });
+  }
+
+  // Phase 2b: Dynamic registry discovery
+  if (workerConfig.registryMode !== "embedded") {
+    try {
+      const { ServiceRegistry } = await import("../registry/ServiceRegistry.js");
+      const workerRegistry = new ServiceRegistry({
+        mode: workerConfig.registryMode,
+        host: workerConfig.registryHost || undefined,
+      });
+
+      workerRegistry.on("discovered", (reg) => {
+        if (reg.ports?.http) {
+          endpointResolver.set(reg.name, {
+            host: reg.host,
+            port: reg.ports.http,
+            remote: true,
+          });
+        }
+      });
+
+      workerRegistry.on("removed", (reg) => {
+        if (reg.ports?.http) {
+          endpointResolver.remove(reg.name, reg.host, reg.ports.http);
+        }
+      });
+
+      await workerRegistry.start();
+    } catch (err) {
+      // Don't crash on registry errors — static endpoints still work
+      console.error(`[ThreadForge] Worker registry init failed: ${err.message}`);
+    }
+  }
+
+  // Phase 3: Build and inject proxy clients
+  // A2: Delegate all proxy creation to ServiceProxy — no inline retry/circuit-breaker reimplementation
+  const servicePorts = JSON.parse(workerConfig.servicePorts || "{}");
+
+  for (const [name, { service }] of localServices) {
+    const ctx = localServices.get(name).ctx;
+    const proxies = buildServiceProxies(ctx, serviceClasses, localServices);
+
+    for (const svcName of allConnectedServices) {
+      if (svcName === name) continue;
+      if (proxies[svcName]) continue;
+
+      // Service not in serviceClasses (remote/external) — use dynamic proxy via ServiceProxy
+      proxies[svcName] = createServiceProxy(ctx, svcName, null, null, {});
+    }
+
+    service._setProxies(proxies);
+  }
+
+  // Phase 4: Connect plugins and inject into services
+  let pluginManager = null;
+  try {
+    const pluginNames = JSON.parse(workerConfig.plugins || "[]");
+    const servicePluginMap = JSON.parse(workerConfig.servicePlugins || "{}");
+
+    if (pluginNames.length > 0) {
+      const { PluginManager } = await import("../plugins/PluginManager.js");
+      pluginManager = new PluginManager();
+
+      if (workerConfig.configPath) {
+        const configMod = await import(workerConfig.configPath);
+        const config = configMod.default ?? configMod;
+        if (config.plugins) {
+          let plugins = config.plugins;
+
+          if (hostMeta) {
+            const { scopedPostgres } = await import("../plugins/ScopedPostgres.js");
+            const { scopedRedis } = await import("../plugins/ScopedRedis.js");
+            plugins = plugins.map((p) => {
+              if (p.name === "postgres") return scopedPostgres(p._options ?? {});
+              if (p.name === "redis") return scopedRedis(p._options ?? {});
+              return p;
+            });
+          }
+
+          pluginManager.register(plugins);
+        }
+      }
+
+      // P14: Connect plugins for all services in parallel
+      const pluginEntries = [...localServices.entries()];
+      const pluginResults = await Promise.all(
+        pluginEntries.map(async ([svcName, { service, ctx }]) => {
+          const svcPlugins = servicePluginMap[svcName];
+          const clients = await pluginManager.connectForService(svcPlugins, ctx);
+          return { svcName, service, ctx, clients, svcPlugins };
+        }),
+      );
+
+      for (const { service, ctx, clients, svcPlugins } of pluginResults) {
+        // Inject clients as properties on the service
+        for (const [injectName, client] of clients) {
+          if (injectName.startsWith("_")) continue; // skip internal plugins (cors, etc.)
+          service[injectName] = client;
+        }
+
+        // Apply plugin middleware
+        const middleware = pluginManager.getMiddleware(svcPlugins);
+        for (const mw of middleware) {
+          ctx.router.use(mw);
+        }
+
+        // Attach websocket lifecycle hooks for this service
+        ctx._wsPluginHooks = pluginManager.getWebSocketHooks(svcPlugins);
+      }
+    }
+  } catch (err) {
+    // Don't crash on plugin errors — log and continue
+    console.error(`[ThreadForge] Plugin init failed for ${workerConfig.groupName}: ${err.message}`);
+    if (err.stack) console.error(err.stack);
+    for (const [, { ctx }] of localServices) {
+      try {
+        ctx?.logger?.error(`Plugin init failed: ${err.message}`);
+      } catch {}
+    }
+  }
+
+  // O4: Correct shutdown order — stop accepting connections first, then drain, then stop services, then disconnect plugins
+  // RT-C1: shutdown is a function declaration (hoisted) to avoid TDZ when called from IPC handler
+  // RT-C2: re-entrancy guard prevents double shutdown from SIGTERM + IPC race
+  async function shutdown(signal) {
+    if (shutdownInProgress) return;
+    shutdownInProgress = true;
+
+    for (const [name, { ctx }] of localServices) {
+      ctx.logger.info(`Received ${signal}, shutting down ${name}...`);
+    }
+
+    // Step 1: Stop accepting new connections (server.close())
+    const serverClosePromises = [];
+    for (const [, { ctx }] of localServices) {
+      if (ctx._server) {
+        serverClosePromises.push(
+          new Promise((resolve) => {
+            ctx._server.close(() => resolve());
+          })
+        );
+      }
+    }
+
+    // Step 2: Wait for in-flight requests to drain (up to 5s)
+    if (serverClosePromises.length > 0) {
+      await Promise.race([
+        Promise.all(serverClosePromises),
+        new Promise((resolve) => setTimeout(resolve, 5000)),
+      ]);
+    }
+
+    // Step 3: Stop services (onStop hooks, with 5s timeout per service)
+    for (const [name, { service, ctx }] of localServices) {
+      try {
+        await Promise.race([
+          service._stop(),
+          new Promise((_, reject) => setTimeout(() => reject(new Error(`Service "${name}" stop timed out after 5s`)), 5000)),
+        ]);
+      } catch (err) {
+        ctx.logger.error("Shutdown error", { error: err.message });
+      }
+    }
+
+    // Step 4: Disconnect all plugins
+    if (pluginManager) {
+      try {
+        const errors = await pluginManager.disconnectAll(localServices.values().next().value?.ctx?.logger);
+        if (errors.length > 0) {
+          console.warn(`[ThreadForge] ${errors.length} plugins failed to disconnect cleanly`);
+        }
+      } catch (err) {
+        console.warn(`[ThreadForge] Plugin disconnect error: ${err.message}`);
+      }
+    }
+
+    process.exit(0);
+  }
+
+  // Wire IPC before starting so no messages are lost during startup
+  process.on("message", (msg, _handle) => {
+    if (typeof msg !== "object" || msg === null || !msg.type) return;
+
+    if (msg.type === "forge:shutdown") {
+      // Stop accepting new requests, let in-flight complete
+      shutdown("forge:shutdown");
+      return;
+    }
+
+    // IPC-C3: Socket messages handled only by WorkerChannelManager — skip here to avoid duplicates
+    if (msg.type === "forge:init-socket" || msg.type === "forge:socket-registry") return;
+
+    if (msg.type === "forge:health-check") {
+      for (const [, { ctx }] of localServices) {
+        ctx._handleIPCMessage(msg);
+      }
+      return;
+    }
+
+    if (msg.type === "forge:metrics-snapshot") {
+      if (!process.send) return;
+      try {
+        const chunks = [];
+        for (const [, { ctx }] of localServices) {
+          if (ctx?.metrics?.expose) {
+            chunks.push(ctx.metrics.expose());
+          }
+        }
+        process.send({
+          type: "forge:metrics-snapshot-response",
+          requestId: msg.requestId,
+          metrics: chunks.join("\n"),
+        });
+      } catch (err) {
+        process.send({
+          type: "forge:metrics-snapshot-response",
+          requestId: msg.requestId,
+          error: err.message,
+        });
+      }
+      return;
+    }
+
+    if (msg.type === "forge:message" || msg.type === "forge:request" || msg.type === "forge:response") {
+      for (const [, { ctx }] of localServices) {
+        ctx._handleIPCMessage(msg);
+      }
+    }
+  });
+
+  // Request socket setup (supervisor may have sent init-socket before we were listening)
+  if (process.send) {
+    process.send({ type: "forge:worker-ready", group: workerConfig.groupName });
+  }
+
+  // Phase 5: Start all services — track started services for cleanup on failure (RT-H1)
+  const startedServices = [];
+  try {
+    for (const [name, { service, ctx }] of localServices) {
+      await service._start();
+      startedServices.push({ name, service, ctx });
+
+      const proxyNames = Object.keys(
+        Object.fromEntries(Object.entries(service).filter(([_k, v]) => v?.$name || v?.$isLocal !== undefined)),
+      );
+
+      // Reduce startup noise: emit framework startup metadata once per group.
+      if (workerId === 0) {
+        ctx.logger.info("Service started", {
+          group: workerConfig.groupName,
+          service: name,
+          type: typeMap[name] ?? "internal",
+          port: ctx.port || null,
+          worker: workerId,
+          pid: process.pid,
+          colocated: entries.length > 1 ? entries.map((e) => e.name) : undefined,
+          proxies: proxyNames.length > 0 ? proxyNames : undefined,
+        });
+      }
+    }
+  } catch (startErr) {
+    // Check if this is a fatal bind error (EPERM, EACCES, EADDRNOTAVAIL, EADDRINUSE)
+    if (startErr.fatalBindError) {
+      // Log clear error message and exit without triggering restart loop
+      console.error(`\n[ThreadForge] FATAL: ${startErr.userMessage || startErr.message}`);
+      console.error(`[ThreadForge] Service group "${workerConfig.groupName}" cannot start. Worker will not restart.\n`);
+      // Notify supervisor this is a fatal error (already sent via IPC from ForgeContext)
+      // Exit with code 100 to signal fatal configuration error (supervisor checks this)
+      process.exit(100);
+    }
+
+    // RT-H1: Stop already-started services in reverse order before re-throwing
+    for (let i = startedServices.length - 1; i >= 0; i--) {
+      const { name, service, ctx } = startedServices[i];
+      try {
+        ctx.logger.warn(`Rolling back service start for ${name} due to Phase 5 failure`);
+        await service._stop();
+      } catch (stopErr) {
+        ctx.logger.error(`Rollback stop failed for ${name}`, { error: stopErr.message });
+      }
+      try {
+        if (ctx._server) {
+          await new Promise((resolve) => ctx._server.close(resolve));
+        }
+      } catch {}
+    }
+    throw startErr;
+  }
+
+  // Phase 6: Auto-register health check (always, not just with plugins)
+  for (const [, { ctx }] of localServices) {
+    const existingHealthRoute = [...ctx.router.routes.values()].some((bucket) =>
+      bucket.some((r) => r.pattern === "/health"),
+    );
+    if (!existingHealthRoute) {
+      ctx.router.get("/health", async (_req, res) => {
+        const health = {
+          status: "ok",
+          service: ctx.serviceName,
+          pid: process.pid,
+        };
+        if (pluginManager) {
+          health.plugins = await pluginManager.healthCheck();
+        }
+        res.json(health);
+      });
+    }
+  }
+
+  // Notify supervisor that this worker finished startup for readiness aggregation.
+  if (process.send) {
+    process.send({
+      type: "forge:group-ready",
+      group: workerConfig.groupName,
+      workerId,
+      pid: process.pid,
+      services: entries.map((e) => e.name),
+      port: Number.isFinite(port) && port > 0 ? port : null,
+    });
+  }
+
+  // Signal handlers moved to early in bootstrap() — see below uncaughtException handler
+}
+
+bootstrap().catch((err) => {
+  const services = workerConfig.serviceNames || "unknown";
+  console.error(`[ThreadForge] Worker bootstrap failed for group "${workerConfig.groupName}" (services: ${services}):`, err);
+  process.exit(1);
+});