threadforge 0.1.0

package/src/core/Supervisor.js

@@ -0,0 +1,1306 @@
+import cluster from "node:cluster";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import { createServer } from "node:http";
+import { createServer as createNetServer } from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ServiceRegistry } from "../registry/ServiceRegistry.js";
+import { ScaleAdvisor } from "../scaling/ScaleAdvisor.js";
+import { DirectMessageBus } from "./DirectMessageBus.js";
+import { ThreadAllocator } from "./ThreadAllocator.js";
+
+import { timingSafeEqual } from "node:crypto";
+import { tmpdir } from "node:os";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKER_BOOTSTRAP = path.join(__dirname, "..", "services", "worker-bootstrap.js");
+
+// L1: Restart policy constants
+const RESTART_BASE_BACKOFF_MS = 2000;
+const RESTART_MAX_BACKOFF_MS = 60000;
+const MAX_RESTARTS_PER_WINDOW = 5;
+const RESTART_WINDOW_MS = 300000;
+// L5: Rate-limit restart warnings — one per 5s per group
+const RESTART_WARNING_INTERVAL_MS = 5000;
+// C5: Overall shutdown deadline
+const SHUTDOWN_DEADLINE_MS = 25000;
+// C2: Forbidden env keys
+const FORBIDDEN_ENV_KEYS = new Set(['PATH', 'LD_PRELOAD', 'LD_LIBRARY_PATH', 'NODE_OPTIONS', 'NODE_EXTRA_CA_CERTS']);
+const VALID_ENV_KEY = /^[A-Z_][A-Z0-9_]*$/i;
+// C3: Max env var size before file fallback
+const MAX_ENDPOINT_ENV_SIZE = 65536;
+
+function isExpectedWorkerIpcError(err) {
+  if (!err) return false;
+  if (
+    err.code === "EPIPE" ||
+    err.code === "ECONNRESET" ||
+    err.code === "ERR_IPC_CHANNEL_CLOSED" ||
+    err.code === "ERR_IPC_DISCONNECTED"
+  ) {
+    return true;
+  }
+  const msg = String(err.message ?? "").toLowerCase();
+  return (
+    msg.includes("channel closed") ||
+    msg.includes("ipc channel is already disconnected") ||
+    msg.includes("broken pipe")
+  );
+}
+
+/**
+ * Supervisor v2
+ *
+ * Key differences from v1:
+ *
+ *  - Understands service types (edge/internal/background)
+ *  - Only edge services get HTTP servers
+ *  - Colocated services share a process (same event loop)
+ *  - Channels are dependency-based, not full mesh
+ *  - Thread allocation is per process group, not per service
+ */
+export class Supervisor extends EventEmitter {
+  constructor(config, options = {}) {
+    super();
+
+    this.config = config;
+    this.services = config.services;
+    this.groups = config.groups;
+    this.channels = config.channels; // declared dependency channels
+    this.options = options;
+
+    this.allocator = new ThreadAllocator({
+      cpus: options.cpus,
+      reserved: options.reserved,
+    });
+
+    this.messageBus = new DirectMessageBus();
+
+    // Service registry — starts embedded, upgrades to multicast/external
+    this.registry = new ServiceRegistry({
+      mode: options.registryMode ?? "embedded",
+      host: options.host,
+      httpBasePort: options.httpBasePort ?? 4000,
+    });
+
+    // Scale advisor — monitors health and recommends actions
+    this.scaleAdvisor = new ScaleAdvisor(this.registry, {
+      evaluationIntervalMs: options.evaluationIntervalMs ?? 30000,
+    });
+
+    // Log scaling recommendations
+    this.scaleAdvisor.on("recommendation", (rec) => {
+      const icon = { scale_up: "↑", migrate: "→", split_out: "⊞", scale_down: "↓" };
+      console.log(`\n  ${icon[rec.action] ?? "•"} SCALE: ${rec.service} — ${rec.action}`);
+      console.log(`    ${rec.reason}`);
+      if (rec.details.command) console.log(`    Run: ${rec.details.command}`);
+    });
+
+    // Plugins
+    this.plugins = config.plugins ?? [];
+    this._pluginEnv = {};
+
+    /** @type {Map<number, {groupName: string, services: string[], workerId: number}>} */
+    this.workerMap = new Map();
+
+    /** @type {Map<string, number[]>} group name → cluster worker IDs */
+    this.groupWorkers = new Map();
+
+    /** @type {Map<string, number>} */
+    this.allocation = new Map();
+
+    this._metricsServer = null;
+    this._shuttingDown = false;
+    this._restartHistory = new Map();
+    /** @type {Set<number>} worker IDs being intentionally removed during scale-down */
+    this._scalingDown = new Set();
+    /** @type {Map<string, NodeJS.Timeout>} pending delayed restarts keyed by cooldownKey */
+    this._pendingRestarts = new Map();
+    /** @type {Map<number, NodeJS.Timeout>} SIGKILL timers for scale-down workers (RT-H3) */
+    this._killTimers = new Map();
+    /** @type {Map<string, number>} L5: last restart warning time per group */
+    this._restartWarningTimes = new Map();
+    /** @type {string|null} C3: temp file path for large endpoint maps */
+    this._endpointTempFile = null;
+    /** @type {string|null} temp file path for large site maps */
+    this._sitesTempFile = null;
+    /** @type {number} */
+    this._metricsRequestSeq = 0;
+    /** @type {Map<string, {expected: Set<number>, chunks: string[], timer: NodeJS.Timeout, finish: Function}>} */
+    this._pendingMetricsSnapshots = new Map();
+    /** @type {Map<string, Set<number>>} */
+    this._groupReadyWorkers = new Map();
+    /** @type {Set<string>} */
+    this._groupReadyLogged = new Set();
+    /** @type {Object<string, number>} M-3: monotonic worker index per group for scale-up */
+    this._nextWorkerIndex = {};
+    /** @type {NodeJS.Timeout|null} H-5: heartbeat monitor interval */
+    this._heartbeatInterval = null;
+    /** @type {Map<number, number>} H-5: last heartbeat response time per worker ID */
+    this._lastHeartbeat = new Map();
+    /** @type {Map<number, boolean>} O1: per-worker readiness tracking */
+    this._workersReady = new Map();
+    /** @type {number} O15: total worker restart count */
+    this._workerRestartCount = 0;
+    /** @type {WeakSet<object>} workers that already have an error guard attached */
+    this._workerErrorGuards = new WeakSet();
+  }
+
+  async start() {
+    if (!cluster.isPrimary) {
+      throw new Error("Supervisor.start() must be called from the primary process");
+    }
+
+    // S6: Reject placeholder JWT_SECRET in production
+    if (process.env.NODE_ENV === 'production' && process.env.JWT_SECRET === 'CHANGE_ME_BEFORE_DEPLOY') {
+      console.error('FATAL: JWT_SECRET is set to the placeholder value "CHANGE_ME_BEFORE_DEPLOY". Set a real secret before deploying.');
+      process.exit(1);
+    }
+
+    // Register signal handlers early so signals during startup are caught
+    process.once("SIGTERM", () => this.shutdown());
+    process.once("SIGINT", () => this.shutdown());
+
+    // Preflight check: fail fast with a single clear error before forking workers.
+    await this._assertStartupPortsAvailable();
+
+    // Validate and collect plugin env vars before forking workers
+    /** @type {Set<string>} plugins that failed validation — workers will skip these */
+    this._failedPlugins = new Set();
+
+    if (this.plugins.length > 0) {
+      for (const plugin of this.plugins) {
+        const pName = plugin.name ?? "unknown";
+        try {
+          if (plugin.validate) {
+            await plugin.validate();
+          }
+          if (plugin.env) {
+            Object.assign(this._pluginEnv, plugin.env());
+          }
+        } catch (err) {
+          console.warn(`  ⚠  Plugin "${pName}" unavailable: ${err.message}`);
+          this._failedPlugins.add(pName);
+        }
+      }
+
+      const available = this.plugins.filter((p) => !this._failedPlugins.has(p.name ?? "unknown"));
+      if (available.length > 0) {
+        console.log(`  Plugins: ${available.map((p) => p.name).join(", ")}`);
+      }
+      if (this._failedPlugins.size > 0) {
+        console.warn(`  Failed plugins: ${[...this._failedPlugins].join(", ")}`);
+      }
+    }
+
+    console.log(this._banner());
+
+    // Allocate threads per process group (not per service)
+    this._allocateGroups();
+
+    // Display allocation
+    this._printAllocation();
+
+    cluster.setupPrimary({
+      exec: WORKER_BOOTSTRAP,
+      silent: false,
+    });
+
+    // Register exit handler BEFORE forking so early crashes are caught
+    cluster.on("exit", (worker, code, signal) => {
+      this._handleWorkerExit(worker, code, signal);
+    });
+
+    // P21: Pre-serialize endpoint map once for all worker forks
+    this._cachedEndpointJson = JSON.stringify(this._buildEndpointMap());
+
+    // Fork workers for each process group
+    for (const [groupName, group] of Object.entries(this.groups)) {
+      const threadCount = this.allocation.get(groupName) ?? 1;
+      this.groupWorkers.set(groupName, []);
+      this._groupReadyWorkers.set(groupName, new Set());
+
+      for (let i = 0; i < threadCount; i++) {
+        this._forkGroupWorker(groupName, group, i);
+      }
+    }
+
+    await this._startMetricsServer();
+
+    // Start registry and scale advisor
+    await this.registry.start();
+    this.scaleAdvisor.start();
+
+    // Register all local services in the registry
+    for (const [name, svc] of Object.entries(this.services)) {
+      if (svc.type === "remote") continue;
+      const groupName = svc.group ?? `_isolated:${name}`;
+      this.registry.register({
+        name,
+        ports: { http: svc.port },
+        udsPath: null,
+        workers: this.allocation.get(groupName) ?? 1,
+        contract: {
+          methods: [], // populated by worker after loading class
+          events: [],
+        },
+        metadata: {
+          group: groupName,
+        },
+      });
+    }
+
+    // Print channel topology
+    this._printTopology();
+
+    // H4: Write PID file so `forge stop` can find us without the metrics endpoint
+    this._pidFilePath = path.join(process.cwd(), ".forge.pid");
+    try {
+      fs.writeFileSync(this._pidFilePath, String(process.pid));
+    } catch {}
+
+    console.log(`\n  ⚡ ThreadForge runtime started\n`);
+  }
+
+  /**
+   * Allocate threads per process group.
+   *
+   * Each group gets threads based on the highest weight of its member
+   * services. Colocated services share their group's allocation.
+   */
+  _allocateGroups() {
+    // Build a services-like map for the allocator, keyed by group name
+    const groupConfigs = {};
+    for (const [groupName, group] of Object.entries(this.groups)) {
+      groupConfigs[groupName] = {
+        name: groupName,
+        port: group.port ?? 0,
+        threads: group.threads === 0 ? "auto" : group.threads,
+        weight: group.weight || 1,
+        mode: "cluster",
+      };
+    }
+
+    this.allocation = this.allocator.allocate(groupConfigs);
+  }
+
+  /**
+   * Fork a worker for a process group.
+   *
+   * The worker will load ALL services in the group within a single
+   * process. Colocated services communicate via direct function calls.
+   */
+  _forkGroupWorker(groupName, group, workerIndex) {
+    const serviceNames = group.services.map((s) => s.name);
+    const edgeService = group.services.find((s) => s.type === "edge");
+
+    // Build comma-separated entry points for all services in the group
+    const entries = group.services.map((s) => `${s.name}=${s.entry}`).join(",");
+
+    const env = {
+      ...process.env,
+      ...this._pluginEnv,
+      FORGE_GROUP_NAME: groupName,
+      FORGE_SERVICE_ENTRIES: entries,
+      FORGE_SERVICE_NAMES: serviceNames.join(","),
+      FORGE_PORT: edgeService ? String(edgeService.port) : "0", // 0 = no HTTP
+      FORGE_WORKER_ID: String(workerIndex),
+      FORGE_THREAD_COUNT: String(this.allocation.get(groupName) ?? 1),
+      FORGE_MODE: "cluster",
+      FORGE_SERVICE_TYPES: group.services.map((s) => `${s.name}=${s.type}`).join(","),
+      // Port map for HTTP-based service-to-service calls (backward compat)
+      FORGE_SERVICE_PORTS: JSON.stringify(
+        Object.fromEntries(
+          Object.entries(this.services)
+            .filter(([, s]) => s.port)
+            .map(([name, s]) => [name, s.port]),
+        ),
+      ),
+      // Full endpoint topology — includes remote hosts for multi-machine
+      // S10: Endpoint map may contain internal IPs — treat as trusted internal config, not user input.
+      // P21: Use cached JSON serialization; C3: File fallback when JSON exceeds 64KB
+      ...(() => {
+        const json = this._cachedEndpointJson ?? JSON.stringify(this._buildEndpointMap());
+        if (json.length > MAX_ENDPOINT_ENV_SIZE) {
+          if (!this._endpointTempFile) {
+            const tempFile = path.join(tmpdir(), `forge-endpoints-${process.pid}.json`);
+            // M-SEC-5: Restrict temp file permissions — contains internal topology
+            fs.writeFileSync(tempFile, json, { encoding: 'utf8', mode: 0o600 });
+            this._endpointTempFile = tempFile;
+          }
+          return { FORGE_SERVICE_ENDPOINTS_FILE: this._endpointTempFile };
+        }
+        return { FORGE_SERVICE_ENDPOINTS: json };
+      })(),
+      ...(() => {
+        const json = this.config._sites ? JSON.stringify(this.config._sites) : "";
+        if (!json) return { FORGE_SITES: "" };
+        if (json.length > MAX_ENDPOINT_ENV_SIZE) {
+          if (!this._sitesTempFile) {
+            const tempFile = path.join(tmpdir(), `forge-sites-${process.pid}.json`);
+            fs.writeFileSync(tempFile, json, { encoding: "utf8", mode: 0o600 });
+            this._sitesTempFile = tempFile;
+          }
+          return { FORGE_SITES_FILE: this._sitesTempFile };
+        }
+        return { FORGE_SITES: json };
+      })(),
+      // Registry mode and host for dynamic discovery
+      FORGE_REGISTRY_MODE: this.options.registryMode ?? "embedded",
+      FORGE_HOST: this.options.host ?? "",
+      // Plugin config — which plugins each service uses
+      FORGE_PLUGINS: JSON.stringify(this.plugins.map((p) => p.name)),
+      FORGE_CONFIG_PATH: this.config._configUrl ?? "",
+      FORGE_SERVICE_PLUGINS: JSON.stringify(Object.fromEntries(group.services.map((s) => [s.name, s.plugins ?? null]))),
+      FORGE_CHANNELS: JSON.stringify(
+        this.channels.filter((ch) => serviceNames.includes(ch.from) || serviceNames.includes(ch.to)),
+      ),
+    };
+
+    if (this.config._isHostMode) {
+      env.FORGE_HOST_META = this.config._hostMetaJSON ?? JSON.stringify(this.config._hostMeta);
+    }
+
+    if (this.config._isPlatformMode) {
+      env.FORGE_PLATFORM_MODE = "1";
+    }
+
+    // C2: Set per-service env overrides with validation
+    for (const svc of group.services) {
+      for (const [key, value] of Object.entries(svc.env)) {
+        if (!VALID_ENV_KEY.test(key)) {
+          throw new Error(`Service "${svc.name}": invalid env key "${key}" — must match /^[A-Z_][A-Z0-9_]*$/i`);
+        }
+        if (FORBIDDEN_ENV_KEYS.has(key.toUpperCase())) {
+          throw new Error(`Service "${svc.name}": env key "${key}" is forbidden (security risk)`);
+        }
+        env[`FORGE_ENV_${svc.name.toUpperCase()}_${key}`] = value;
+      }
+    }
+
+    const worker = cluster.fork(env);
+    this._attachWorkerErrorGuard(worker, groupName, serviceNames, workerIndex);
+
+    this.workerMap.set(worker.id, {
+      groupName,
+      services: serviceNames,
+      workerId: workerIndex,
+    });
+
+    // H-5: Initialize heartbeat timestamp so the monitor doesn't kill
+    // workers forked after startup (restarts, scale-up)
+    this._lastHeartbeat.set(worker.id, Date.now());
+
+    const workers = this.groupWorkers.get(groupName) ?? [];
+    workers.push(worker.id);
+    this.groupWorkers.set(groupName, workers);
+
+    // Register with message bus — using service names, not group name
+    // so IPC addressing is still by service name
+    for (const svcName of serviceNames) {
+      this.messageBus.registerWorker(svcName, worker, "cluster");
+    }
+
+    worker.on("message", (msg) => this._handleWorkerMessage(worker, msg));
+
+    return worker;
+  }
+
+  _attachWorkerErrorGuard(worker, groupName, serviceNames, workerIndex) {
+    if (!worker || this._workerErrorGuards.has(worker)) return;
+    this._workerErrorGuards.add(worker);
+    worker.on("error", (err) => {
+      if (isExpectedWorkerIpcError(err)) return;
+      if (this._shuttingDown) return;
+      console.error(
+        `  ⚠  Worker ${groupName}[${workerIndex}] (${serviceNames.join("+")}) IPC error: ${err?.message ?? err}`,
+      );
+    });
+  }
+
+  _sendWorkerMessage(worker, message, label = "worker message") {
+    if (!worker) return false;
+    if (typeof worker.isDead === "function" && worker.isDead()) return false;
+    if (typeof worker.isConnected === "function" && !worker.isConnected()) return false;
+    if (worker.process?.connected === false) return false;
+
+    try {
+      worker.send(message);
+      return true;
+    } catch (err) {
+      if (!isExpectedWorkerIpcError(err)) {
+        console.error(`  ⚠  Failed to send ${label}: ${err?.message ?? err}`);
+      }
+      return false;
+    }
+  }
+
+  _handleWorkerMessage(worker, msg) {
+    if (msg?.type === "forge:group-ready") {
+      // O1: Mark worker as ready for the /health/ready readiness probe
+      this._workersReady.set(worker.id, true);
+
+      const info = this.workerMap.get(worker.id);
+      if (!info) return;
+
+      const groupName = info.groupName;
+      const readySet = this._groupReadyWorkers.get(groupName) ?? new Set();
+      readySet.add(worker.id);
+      this._groupReadyWorkers.set(groupName, readySet);
+
+      const expected = this.allocation.get(groupName) ?? 1;
+      if (readySet.size >= expected && !this._groupReadyLogged.has(groupName)) {
+        this._groupReadyLogged.add(groupName);
+        const group = this.groups[groupName];
+        const edgeService = group?.services?.find((s) => s.type === "edge");
+        const portLabel = edgeService?.port ? ` on port ${edgeService.port}` : "";
+        const svcLabel = group?.services?.map((s) => s.name).join(", ") ?? groupName;
+        console.log(`  ✓ ${svcLabel}: ${expected} workers ready${portLabel}`);
+
+        // H-5: Start heartbeat monitor once all groups are ready
+        if (!this._heartbeatInterval) {
+          const allReady = [...this._groupReadyWorkers.entries()].every(
+            ([gn, set]) => set.size >= (this.allocation.get(gn) ?? 1)
+          );
+          if (allReady) {
+            this._startHeartbeatMonitor();
+          }
+        }
+      }
+      return;
+    }
+
+    if (msg?.type === "forge:fatal-error") {
+      const info = this.workerMap.get(worker.id);
+      const groupName = info?.groupName ?? "unknown";
+      const workerId = info?.workerId ?? "?";
+      console.error(`  ✖  Worker ${groupName}[${workerId}] fatal error: ${msg.error} - ${msg.message}`);
+      if (msg.port) {
+        console.error(`  ✖  Failed to bind to port ${msg.port}. Check permissions or port availability.`);
+      }
+      return;
+    }
+
+    // H-5: Track heartbeat responses from workers
+    if (msg?.type === "forge:heartbeat-response") {
+      this._lastHeartbeat.set(worker.id, Date.now());
+      return;
+    }
+
+    if (msg?.type === "forge:metrics-snapshot-response" && msg.requestId) {
+      const pending = this._pendingMetricsSnapshots.get(msg.requestId);
+      if (!pending) return;
+
+      if (typeof msg.metrics === "string" && msg.metrics.trim().length > 0) {
+        pending.chunks.push(msg.metrics);
+      }
+      if (msg.error) {
+        pending.chunks.push(`# Worker ${worker.id} metrics error: ${msg.error}`);
+      }
+
+      pending.expected.delete(worker.id);
+      if (pending.expected.size === 0) {
+        pending.finish();
+      }
+    }
+  }
+
+  _mergePrometheusExpositions(expositions) {
+    const lines = [];
+    const seenMeta = new Set();
+
+    for (const chunk of expositions) {
+      if (typeof chunk !== "string") continue;
+
+      for (const rawLine of chunk.split(/\r?\n/)) {
+        const line = rawLine.trimEnd();
+        if (!line) continue;
+
+        if (line.startsWith("# HELP ") || line.startsWith("# TYPE ")) {
+          if (seenMeta.has(line)) continue;
+          seenMeta.add(line);
+        }
+
+        lines.push(line);
+      }
+    }
+
+    if (lines.length === 0) {
+      return "# No worker metrics available\n";
+    }
+
+    return `${lines.join("\n")}\n`;
+  }
+
+  _collectMetricsSnapshot(timeoutMs = 1000) {
+    const activeWorkers = Object.values(cluster.workers).filter((worker) => worker && !worker.isDead());
+    if (activeWorkers.length === 0) {
+      return Promise.resolve("# No worker metrics available\n");
+    }
+
+    const requestId = `metrics-${process.pid}-${Date.now()}-${++this._metricsRequestSeq}`;
+
+    return new Promise((resolve) => {
+      const expected = new Set(activeWorkers.map((worker) => worker.id));
+      const chunks = [];
+      let finished = false;
+
+      const finish = () => {
+        if (finished) return;
+        finished = true;
+        const pending = this._pendingMetricsSnapshots.get(requestId);
+        if (pending?.timer) clearTimeout(pending.timer);
+        this._pendingMetricsSnapshots.delete(requestId);
+        resolve(this._mergePrometheusExpositions(chunks));
+      };
+
+      const timer = setTimeout(finish, timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+
+      this._pendingMetricsSnapshots.set(requestId, { expected, chunks, timer, finish });
+
+      for (const worker of activeWorkers) {
+        const sent = this._sendWorkerMessage(worker, { type: "forge:metrics-snapshot", requestId }, "metrics snapshot request");
+        if (!sent) expected.delete(worker.id);
+      }
+
+      if (expected.size === 0) {
+        finish();
+      }
+    });
+  }
+
+  _handleWorkerExit(worker, code, signal) {
+    const info = this.workerMap.get(worker.id);
+    if (!info) return;
+
+    const { groupName, services, workerId } = info;
+
+    // CR-1: Find the worker's slot index in the group before removing it
+    const workers = this.groupWorkers.get(groupName) ?? [];
+    const workerSlotIndex = workers.indexOf(worker.id);
+
+    // CR-2: Always perform cleanup even during shutdown — only skip restart/fork logic
+    this.workerMap.delete(worker.id);
+    this._groupReadyWorkers.get(groupName)?.delete(worker.id);
+    this._lastHeartbeat.delete(worker.id);
+    this._workersReady.delete(worker.id);
+
+    // RT-H3: Clear any pending SIGKILL timer for this worker
+    const killTimer = this._killTimers.get(worker.id);
+    if (killTimer) {
+      clearTimeout(killTimer);
+      this._killTimers.delete(worker.id);
+    }
+
+    if (workerSlotIndex !== -1) workers.splice(workerSlotIndex, 1);
+
+    // Unregister from message bus
+    for (let i = 0; i < services.length; i++) {
+      const svcName = services[i];
+      this.messageBus.unregisterWorker(svcName, worker.id, {
+        suppressBroadcast: i < services.length - 1,
+      });
+    }
+
+    // CR-2: During shutdown, only do cleanup (above) — skip restart/fork logic
+    if (this._shuttingDown) return;
+
+    // If this worker was intentionally removed during scale-down, don't restart
+    if (this._scalingDown.has(worker.id)) {
+      this._scalingDown.delete(worker.id);
+      // MED-4: Clean up restart history for removed worker
+      const cooldownKey = `${groupName}:slot${workerSlotIndex}`;
+      this._restartHistory.delete(cooldownKey);
+      console.log(`  ↓ Worker ${groupName}[${workerId}] (${services.join("+")}) removed (scale-down)`);
+      return;
+    }
+
+    // Exit code 100 indicates fatal configuration error (e.g., EPERM on port bind)
+    // Don't restart — log clear message and stop
+    if (code === 100) {
+      console.error(`  ✖  Worker ${groupName}[${workerId}] (${services.join("+")}) failed with fatal error — not restarting`);
+      console.error(`  ✖  Check worker logs above for details (likely port permission issue)`);
+      // Clean up restart history to prevent future attempts
+      const cooldownKey = `${groupName}:slot${workerSlotIndex}`;
+      this._restartHistory.delete(cooldownKey);
+      this._pendingRestarts.delete(cooldownKey);
+      return;
+    }
+
+    const reason = signal ? `signal ${signal}` : `code ${code}`;
+
+    // L5: Rate-limit restart warnings per group
+    const now = Date.now();
+    const lastWarning = this._restartWarningTimes.get(groupName) ?? 0;
+    if (now - lastWarning >= RESTART_WARNING_INTERVAL_MS) {
+      console.error(`  ⚠  Worker ${groupName}[${workerId}] (${services.join("+")}) exited: ${reason}`);
+      this._restartWarningTimes.set(groupName, now);
+    }
+
+    // CR-1: Key by worker slot index (not cluster worker.id) so restart history persists across restarts
+    const cooldownKey = `${groupName}:slot${workerSlotIndex}`;
+    const history = this._restartHistory.get(cooldownKey) ?? { count: 0, firstRestart: now, lastRestart: 0 };
+
+    // Reset counter if outside the restart window
+    if (now - history.firstRestart > RESTART_WINDOW_MS) {
+      history.count = 0;
+      history.firstRestart = now;
+    }
+
+    if (history.count >= MAX_RESTARTS_PER_WINDOW) {
+      console.error(`  ⚠  ${groupName}[${workerId}] exceeded max restarts (${MAX_RESTARTS_PER_WINDOW} in ${RESTART_WINDOW_MS / 60000}min), not restarting`);
+      this._restartHistory.delete(cooldownKey);
+      return;
+    }
+
+    // Exponential backoff with constants
+    const backoffMs = Math.min(RESTART_BASE_BACKOFF_MS * 2 ** history.count, RESTART_MAX_BACKOFF_MS);
+    const timeSinceLast = now - history.lastRestart;
+
+    if (timeSinceLast < backoffMs) {
+      const remaining = backoffMs - timeSinceLast;
+      console.log(`  ↻  Delaying restart for ${groupName}[${workerId}] (${remaining}ms remaining in backoff)`);
+
+      // Cancel any existing pending restart for this slot
+      const existingTimer = this._pendingRestarts.get(cooldownKey);
+      if (existingTimer) clearTimeout(existingTimer);
+
+      const timer = setTimeout(() => {
+        this._pendingRestarts.delete(cooldownKey);
+        if (this._shuttingDown) return;
+        if (!this.groups[groupName]) return;
+
+        history.count++;
+        history.lastRestart = Date.now();
+        this._restartHistory.set(cooldownKey, history);
+
+        console.log(
+          `  ↻  Restarting ${groupName}[${workerId}] (attempt ${history.count}/${MAX_RESTARTS_PER_WINDOW}, backoff ${backoffMs}ms)...`,
+        );
+        // O15: Track worker restart metric
+        this._workerRestartCount++;
+        this._forkGroupWorker(groupName, this.groups[groupName], workerId);
+      }, remaining);
+
+      timer.unref();
+      this._pendingRestarts.set(cooldownKey, timer);
+      return;
+    }
+
+    if (!this.groups[groupName]) return;
+
+    history.count++;
+    history.lastRestart = now;
+    this._restartHistory.set(cooldownKey, history);
+
+    console.log(`  ↻  Restarting ${groupName}[${workerId}] (attempt ${history.count}/${MAX_RESTARTS_PER_WINDOW}, backoff ${backoffMs}ms)...`);
+    // O15: Track worker restart metric
+    this._workerRestartCount++;
+    if (this._shuttingDown) return;
+    this._forkGroupWorker(groupName, this.groups[groupName], workerId);
+  }
+
+  _startupPortsToCheck() {
+    const targets = [];
+    const seen = new Set();
+
+    for (const [name, svc] of Object.entries(this.services)) {
+      if (svc?.type !== "edge") continue;
+      if (!Number.isInteger(svc.port) || svc.port <= 0) continue;
+      if (seen.has(svc.port)) continue;
+      seen.add(svc.port);
+      targets.push({ port: svc.port, purpose: `service "${name}"` });
+    }
+
+    return targets;
+  }
+
+  _isPortAvailable(port, host = "127.0.0.1") {
+    if (!Number.isInteger(port) || port <= 0) return Promise.resolve(true);
+
+    return new Promise((resolve) => {
+      const probe = createNetServer();
+      let settled = false;
+
+      const finish = (available) => {
+        if (settled) return;
+        settled = true;
+        if (available) {
+          probe.close(() => resolve(true));
+        } else {
+          resolve(false);
+        }
+      };
+
+      probe.once("error", (err) => {
+        if (err.code === "EADDRINUSE" || err.code === "EACCES" || err.code === "EPERM") {
+          finish(false);
+          return;
+        }
+        finish(false);
+      });
+
+      probe.once("listening", () => finish(true));
+      probe.listen(port, host);
+    });
+  }
+
+  async _assertStartupPortsAvailable() {
+    const targets = this._startupPortsToCheck();
+    for (const { port, purpose } of targets) {
+      const available = await this._isPortAvailable(port);
+      if (!available) {
+        throw new Error(
+          `Startup preflight failed: port ${port} (${purpose}) is unavailable ` +
+          `(already in use or permission denied).`,
+        );
+      }
+    }
+  }
+
+  async scale(groupName, newCount) {
+    const group = this.groups[groupName];
+    if (!group) throw new Error(`Unknown group: ${groupName}`);
+
+    // M-2: Bounds checking for newCount
+    if (newCount < 1 || newCount > 64) {
+      throw new Error(`Invalid worker count ${newCount} for group "${groupName}": must be between 1 and 64`);
+    }
+
+    const currentIds = this.groupWorkers.get(groupName) ?? [];
+    const currentCount = currentIds.length;
+
+    if (newCount === currentCount) return;
+
+    if (newCount > currentCount) {
+      const toAdd = newCount - currentCount;
+      console.log(`  ↑ Scaling ${groupName} ${currentCount} → ${newCount} (+${toAdd})`);
+      // H-3: Reset groupReadyLogged so ready message is logged again for new workers
+      this._groupReadyLogged.delete(groupName);
+      // Use a monotonic counter to avoid index collisions after scale-down + scale-up
+      if (this._nextWorkerIndex[groupName] === undefined) {
+        this._nextWorkerIndex[groupName] = currentCount;
+      }
+      for (let i = 0; i < toAdd; i++) {
+        const workerIndex = this._nextWorkerIndex[groupName]++;
+        // Clear any stale restart history so new workers don't inherit crash counts
+        this._restartHistory.delete(`${groupName}:${workerIndex}`);
+        this._forkGroupWorker(groupName, group, workerIndex);
+      }
+    } else {
+      const toRemove = currentCount - newCount;
+      console.log(`  ↓ Scaling ${groupName} ${currentCount} → ${newCount} (-${toRemove})`);
+      for (let i = 0; i < toRemove; i++) {
+        const wid = currentIds[currentIds.length - 1 - i];
+        this._scalingDown.add(wid);
+        const worker = cluster.workers[wid];
+        if (worker) {
+          worker.process.kill("SIGTERM");
+          // RT-H3: Force SIGKILL after 10s if worker hasn't exited
+          const killTimer = setTimeout(() => {
+            this._killTimers.delete(wid);
+            try {
+              if (!worker.isDead()) {
+                console.error(`  ⚠  Worker ${wid} did not exit after SIGTERM, sending SIGKILL`);
+                worker.process.kill("SIGKILL");
+              }
+            } catch {}
+          }, 10_000);
+          killTimer.unref();
+          this._killTimers.set(wid, killTimer);
+          // H3: Clean up kill timer if worker exits before SIGKILL fires
+          worker.once('exit', () => {
+            const t = this._killTimers.get(wid);
+            if (t) {
+              clearTimeout(t);
+              this._killTimers.delete(wid);
+            }
+          });
+        }
+      }
+    }
+
+    this.allocation.set(groupName, newCount);
+  }
+
+  /**
+   * H-5: Start heartbeat monitor — checks worker health every 30s.
+   * Warns after 60s of silence, kills after 90s.
+   */
+  _startHeartbeatMonitor() {
+    // Initialize heartbeat timestamps for all current workers
+    const now = Date.now();
+    for (const wid of this.workerMap.keys()) {
+      this._lastHeartbeat.set(wid, now);
+    }
+
+    this._heartbeatInterval = setInterval(() => {
+      if (this._shuttingDown) return;
+
+      // Request health checks from message bus if available
+      if (typeof this.messageBus.requestHealthChecks === 'function') {
+        this.messageBus.requestHealthChecks();
+      }
+
+      const checkTime = Date.now();
+      for (const [wid, info] of this.workerMap) {
+        const lastSeen = this._lastHeartbeat.get(wid) ?? 0;
+        const elapsed = checkTime - lastSeen;
+
+        if (elapsed > 90_000) {
+          // 90s without response — kill the worker
+          console.error(`  ✖  Worker ${info.groupName}[${info.workerId}] unresponsive for ${Math.round(elapsed / 1000)}s — sending SIGKILL`);
+          try {
+            const w = cluster.workers?.[wid];
+            if (w && !w.isDead()) {
+              w.process.kill('SIGKILL');
+            }
+          } catch {}
+        } else if (elapsed > 60_000) {
+          // 60s without response — log a warning
+          console.warn(`  ⚠  Worker ${info.groupName}[${info.workerId}] no heartbeat for ${Math.round(elapsed / 1000)}s`);
+        }
+      }
+    }, 30_000);
+
+    this._heartbeatInterval.unref();
+  }
+
+  _stopHeartbeatMonitor() {
+    if (this._heartbeatInterval) {
+      clearInterval(this._heartbeatInterval);
+      this._heartbeatInterval = null;
+    }
+  }
+
+  async shutdown() {
+    if (this._shuttingDown) return;
+    this._shuttingDown = true;
+
+    // H-5: Stop heartbeat monitor
+    this._stopHeartbeatMonitor();
+
+    // Resolve in-flight /metrics scrapes so callers don't hang during shutdown
+    for (const pending of this._pendingMetricsSnapshots.values()) {
+      clearTimeout(pending.timer);
+      pending.finish();
+    }
+    this._pendingMetricsSnapshots.clear();
+
+    // Cancel any pending delayed restarts
+    for (const timer of this._pendingRestarts.values()) {
+      clearTimeout(timer);
+    }
+    this._pendingRestarts.clear();
+
+    // Cancel any pending SIGKILL timers from scale-down
+    for (const [, timer] of this._killTimers) { clearTimeout(timer); }
+    this._killTimers.clear();
+
+    console.log("\n  Shutting down ThreadForge...\n");
+
+    // C5: Overall shutdown deadline — each phase races against remaining time
+    const deadlineStart = Date.now();
+    const withDeadline = (promise, label) => {
+      const remaining = SHUTDOWN_DEADLINE_MS - (Date.now() - deadlineStart);
+      if (remaining <= 0) {
+        console.warn(`  ⚠  Shutdown deadline exceeded during: ${label} — skipping`);
+        return Promise.resolve();
+      }
+      return Promise.race([
+        promise,
+        new Promise((resolve) => {
+          const t = setTimeout(() => {
+            console.warn(`  ⚠  Shutdown phase "${label}" exceeded deadline — skipping`);
+            resolve();
+          }, remaining);
+          t.unref();
+        }),
+      ]);
+    };
+
+    // Close metrics server first so health checks fail during shutdown
+    if (this._metricsServer) {
+      await withDeadline(
+        new Promise(resolve => this._metricsServer.close(resolve)),
+        'metrics server close'
+      );
+      this._metricsServer = null;
+    }
+
+    // Step 1: Send graceful shutdown message to each worker
+    for (const id of Object.keys(cluster.workers)) {
+      const worker = cluster.workers[id];
+      if (worker) {
+        this._sendWorkerMessage(worker, { type: "forge:shutdown" }, "shutdown signal");
+      }
+    }
+
+    // Step 2: Wait for workers to drain HTTP connections and exit
+    // H-CORE-3: Unref timers so they don't keep the process alive after workers exit
+    await withDeadline(new Promise((resolve) => {
+      const check = setInterval(() => {
+        const alive = Object.keys(cluster.workers).filter((id) => {
+          const w = cluster.workers[id];
+          return w && !w.isDead();
+        });
+        if (alive.length === 0) {
+          clearInterval(check);
+          resolve();
+        }
+      }, 200);
+      check.unref();
+      const fallback = setTimeout(() => {
+        clearInterval(check);
+        resolve();
+      }, 10000);
+      fallback.unref();
+    }), 'graceful drain');
+
+    // Collect all worker PIDs before disconnect (workers may leave cluster.workers after disconnect)
+    const workerPids = new Set();
+    for (const id of Object.keys(cluster.workers)) {
+      const w = cluster.workers[id];
+      if (w?.process?.pid) workerPids.add(w.process.pid);
+    }
+
+    // Step 3: Disconnect remaining workers
+    for (const id of Object.keys(cluster.workers)) {
+      const worker = cluster.workers[id];
+      if (worker && !worker.isDead()) {
+        try {
+          worker.disconnect();
+        } catch {
+          // Worker may already be dead
+        }
+      }
+    }
+
+    // Step 4: Wait for disconnect to complete
+    await withDeadline(new Promise((resolve) => {
+      const check = setInterval(() => {
+        const alive = Object.keys(cluster.workers).filter((id) => {
+          const w = cluster.workers[id];
+          return w && !w.isDead();
+        });
+        if (alive.length === 0) {
+          clearInterval(check);
+          resolve();
+        }
+      }, 200);
+      check.unref();
+      const fallback = setTimeout(() => {
+        clearInterval(check);
+        resolve();
+      }, 5000);
+      fallback.unref();
+    }), 'disconnect');
+
+    // Step 5: Force kill any remaining workers
+    for (const id of Object.keys(cluster.workers)) {
+      const worker = cluster.workers[id];
+      if (worker && !worker.isDead()) {
+        console.error(`  ⚠  Forcefully killing worker ${id}...`);
+        worker.process.kill("SIGKILL");
+      }
+    }
+
+    // Also kill workers that disconnected from cluster but may still be alive
+    for (const pid of workerPids) {
+      try { process.kill(pid, 0); process.kill(pid, "SIGKILL"); } catch {}
+    }
+
+    // C3: Clean up temp endpoint file if created
+    if (this._endpointTempFile) {
+      try { fs.unlinkSync(this._endpointTempFile); } catch {}
+      this._endpointTempFile = null;
+    }
+    if (this._sitesTempFile) {
+      try { fs.unlinkSync(this._sitesTempFile); } catch {}
+      this._sitesTempFile = null;
+    }
+
+    // H4: Clean up PID file
+    if (this._pidFilePath) {
+      try { fs.unlinkSync(this._pidFilePath); } catch {}
+      this._pidFilePath = null;
+    }
+
+    console.log("  All workers stopped. Goodbye.\n");
+    this.messageBus.cleanup();
+    this.scaleAdvisor.stop();
+    // O14: Add deadline to registry.stop() to prevent hanging
+    try {
+      await Promise.race([
+        this.registry.stop(),
+        new Promise(resolve => setTimeout(resolve, 5000)),
+      ]);
+    } catch (err) {
+      console.error(`  ⚠  Registry stop failed: ${err.message}`);
+    }
+    // Let the caller decide whether to exit — don't force process.exit here
+    // so tests and CLI wrappers can run post-shutdown cleanup
+  }
+
+  async _startMetricsServer() {
+    // Allow metricsPort: null or false to disable metrics entirely
+    if (this.config.metricsPort === null || this.config.metricsPort === false) {
+      console.log(`  📊 Metrics: disabled`);
+      return;
+    }
+
+    // Safety fallback to 9090 (config layer should already provide this default)
+    const port = this.config.metricsPort ?? 9090;
+
+    return new Promise((resolve) => {
+      this._metricsServer = createServer((req, res) => {
+        const reqPath = new URL(req.url ?? "/", "http://localhost").pathname;
+
+        // Let registry handle its endpoints first
+        if (this.registry.httpHandler(req, res)) return;
+
+        // S7: Auth gate for sensitive supervisor endpoints (matches worker-level FORGE_METRICS_TOKEN)
+        // SEC-C2: Include registry endpoints — they expose full service topology
+        const sensitiveEndpoints = ['/status', '/metrics', '/scaling', '/_forge/topology', '/_forge/resolve'];
+        if (sensitiveEndpoints.includes(reqPath)) {
+          const metricsToken = process.env.FORGE_METRICS_TOKEN;
+          if (metricsToken) {
+            const auth = req.headers['authorization'] ?? '';
+            const expected = `Bearer ${metricsToken}`;
+            if (auth.length !== expected.length ||
+                !timingSafeEqual(Buffer.from(auth), Buffer.from(expected))) {
+              res.writeHead(401, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Unauthorized" }));
+              return;
+            }
+          }
+        }
+
+        if (reqPath === "/status") {
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(this._status(), null, 2));
+        } else if (reqPath === "/metrics") {
+          this._collectMetricsSnapshot()
+            .then((payload) => {
+              // O15: Prepend supervisor-level restart counter
+              const supervisorMetrics =
+                `# HELP forge_worker_restarts_total Total number of worker restarts\n` +
+                `# TYPE forge_worker_restarts_total counter\n` +
+                `forge_worker_restarts_total ${this._workerRestartCount}\n`;
+              res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
+              res.end(supervisorMetrics + payload);
+            })
+            .catch((err) => {
+              res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+              res.end(`# metrics collection failed: ${err.message}\n`);
+            });
+          return;
+        } else if (reqPath === "/health" || reqPath === "/health/ready") {
+          // O1: Readiness probe — 200 only when ALL workers have reported ready
+          const totalWorkers = this.workerMap.size;
+          const readyWorkers = [...this._workersReady.values()].filter(Boolean).length;
+          if (totalWorkers > 0 && readyWorkers >= totalWorkers) {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "ready", ready: readyWorkers, total: totalWorkers }));
+          } else {
+            res.writeHead(503, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "starting", ready: readyWorkers, total: totalWorkers }));
+          }
+        } else if (reqPath === "/health/live") {
+          // O1: Liveness probe — always 200 if process is running
+          res.writeHead(200, { "Content-Type": "text/plain" });
+          res.end("ok");
+        } else if (reqPath === "/scaling") {
+          res.writeHead(200, { "Content-Type": "text/plain" });
+          res.end(this.scaleAdvisor.report());
+        } else {
+          res.writeHead(404);
+          res.end("Not found");
+        }
+      });
+
+      this._metricsServer.on("error", (err) => {
+        // Enhanced error message with actionable guidance
+        console.warn(`  ⚠  Metrics server failed to bind port ${port}: ${err.message}`);
+        console.warn(`     To fix: Set metricsPort to a different port in your config, or set metricsPort: null to disable metrics.`);
+        console.warn(`     Example: defineServices(services, { metricsPort: 9091 }) or { metricsPort: null }`);
+        this._metricsServer = null;
+        resolve(); // non-fatal — supervisor continues without metrics
+      });
+
+      // Set timeouts to prevent slowloris attacks
+      this._metricsServer.timeout = 5000;
+      this._metricsServer.requestTimeout = 5000;
+      this._metricsServer.headersTimeout = 3000;
+
+      // RT-H4: Bind to localhost only — metrics endpoint has no auth
+      // C2: Allow override via FORGE_METRICS_BIND for containers (e.g. 0.0.0.0)
+      const bindAddr = process.env.FORGE_METRICS_BIND || "127.0.0.1";
+      // SEC-C2: Warn when metrics are exposed without auth
+      if (bindAddr !== "127.0.0.1" && bindAddr !== "::1" && !process.env.FORGE_METRICS_TOKEN) {
+        console.warn(`  ⚠  Metrics server binding to ${bindAddr} without FORGE_METRICS_TOKEN — topology and metrics are publicly accessible`);
+        console.warn(`     Set FORGE_METRICS_TOKEN=<secret> to require Bearer auth on sensitive endpoints`);
+      }
+      this._metricsServer.listen(port, bindAddr, () => {
+        console.log(`  📊 Metrics: http://${bindAddr}:${port}/status (Prometheus: /metrics)`);
+        resolve();
+      });
+    });
+  }
+
+  _status() {
+    const groups = [];
+    for (const [groupName, workerIds] of this.groupWorkers) {
+      const group = this.groups[groupName];
+      const pids = workerIds.map((wid) => cluster.workers[wid]?.process?.pid).filter(Boolean);
+
+      groups.push({
+        group: groupName,
+        services: group.services.map((s) => ({
+          name: s.name,
+          type: s.type,
+          port: s.port,
+        })),
+        workers: workerIds.length,
+        pids,
+      });
+    }
+
+    return {
+      supervisorPid: process.pid,
+      uptime: process.uptime(),
+      totalCpus: this.allocator.totalCpus,
+      nodeId: this.registry.nodeId,
+      host: this.registry.host,
+      registryMode: this.registry.mode,
+      processGroups: groups,
+      channels: this.channels,
+      totalProcesses: Object.keys(cluster.workers).length,
+      totalServices: Object.keys(this.services).length,
+      remoteServices: Object.values(this.services).filter((s) => s.type === "remote").length,
+      portsUsed: Object.values(this.services)
+        .filter((s) => s.port)
+        .map((s) => s.port),
+      messageBus: this.messageBus.stats(),
+      topology: this.registry.topology(),
+      scalingRecommendations: this.scaleAdvisor.recommendations,
+    };
+  }
+
+  /**
+   * Build endpoint map for workers.
+   *
+   * Maps each service to { host, port, remote } or an array of endpoints
+   * for multi-instance services. Remote services get their address parsed
+   * into host/port. Local services get host: '127.0.0.1'.
+   */
+  _buildEndpointMap() {
+    const endpoints = {};
+
+    for (const [name, svc] of Object.entries(this.services)) {
+      if (svc.type === "remote") {
+        // Parse address: "http://host:port" or "host:port"
+        const parsed = this._parseAddress(svc.address, name);
+        if (parsed) {
+          endpoints[name] = { host: parsed.host, port: parsed.port, remote: true };
+        }
+      } else if (svc.port) {
+        endpoints[name] = { host: "127.0.0.1", port: svc.port, remote: false };
+      } else if (svc.type === "internal" || svc.type === "background") {
+        // Include internal/background services so workers can use DirectMessageBus
+        // for cross-group calls instead of falling back to supervisor IPC
+        const groupName = svc.group ?? `_isolated:${name}`;
+        const socketPath = this.messageBus.getSocketPath?.(name);
+        endpoints[name] = { host: "127.0.0.1", remote: false, uds: socketPath ?? null, group: groupName };
+      }
+    }
+
+    return endpoints;
+  }
+
+  /**
+   * Parse a service address string into host/port.
+   * Supports: "http://host:port", "host:port", and other URL schemes
+   */
+  _parseAddress(address, serviceName) {
+    if (!address) return null;
+
+    try {
+      // Try as URL first (handles http://, https://, etc.)
+      if (address.includes("://")) {
+        const url = new URL(address);
+        return {
+          host: url.hostname,
+          port: parseInt(url.port, 10) || (url.protocol === "https:" ? 443 : 80),
+        };
+      }
+
+      // Plain host:port
+      const [host, portStr] = address.split(":");
+      const port = parseInt(portStr, 10);
+      if (host && port) return { host, port };
+    } catch (err) {
+      console.warn(`  ⚠  Failed to parse address "${address}" for service "${serviceName ?? "unknown"}": ${err.message}`);
+    }
+
+    console.warn(`  ⚠  Invalid address "${address}" for service "${serviceName ?? "unknown"}" — skipping`);
+    return null;
+  }
+
+  _printAllocation() {
+    console.log("");
+    console.log("  ┌──────────────────┬───────────────────────────┬─────────┬────────┐");
+    console.log("  │ Process Group    │ Services                  │ Workers │ Port   │");
+    console.log("  ├──────────────────┼───────────────────────────┼─────────┼────────┤");
+
+    for (const [groupName, group] of Object.entries(this.groups)) {
+      const name = groupName.replace("_isolated:", "").padEnd(16);
+      const svcList = group.services
+        .map((s) => {
+          const badge = s.type === "edge" ? "⚡" : s.type === "background" ? "⏰" : "○";
+          return `${badge} ${s.name}`;
+        })
+        .join(", ");
+      const svcs = svcList.substring(0, 25).padEnd(25);
+      const threads = String(this.allocation.get(groupName) ?? 1).padEnd(7);
+      const port = group.port ? String(group.port).padEnd(6) : "  —   ";
+      console.log(`  │ ${name} │ ${svcs} │ ${threads} │ ${port} │`);
+    }
+
+    console.log("  └──────────────────┴───────────────────────────┴─────────┴────────┘");
+
+    let totalProcesses = 0;
+    for (const [, count] of this.allocation) totalProcesses += count;
+    const edgePorts = Object.values(this.services).filter((s) => s.port).length;
+
+    console.log(
+      `  Processes: ${totalProcesses} | Services: ${Object.keys(this.services).length} | Ports: ${edgePorts} | CPUs: ${this.allocator.totalCpus}`,
+    );
+  }
+
+  _printTopology() {
+    if (this.channels.length === 0) return;
+
+    console.log("");
+    console.log("  Channels:");
+    for (const ch of this.channels) {
+      console.log(`    ${ch.from} ↔ ${ch.to}`);
+    }
+    console.log(`  Total: ${this.channels.length} channels (dependency-based)`);
+  }
+
+  _banner() {
+    let version = "0.0.0";
+    try {
+      const pkg = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+      version = pkg.version;
+    } catch {}
+    return `
+  ╔════════════════════════════════════╗
+  ║     ⚡ ThreadForge v${version.padEnd(12)}║
+  ║   Multi-threaded Service Runtime  ║
+  ╚════════════════════════════════════╝`;
+  }
+}