threadforge 0.1.1 → 0.2.2

package/dist/core/Supervisor.js

@@ -0,0 +1,1418 @@
+import cluster from "node:cluster";
+import { timingSafeEqual } from "node:crypto";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import { createServer } from "node:http";
+import { createServer as createNetServer } from "node:net";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ServiceRegistry } from "../registry/ServiceRegistry.js";
+import { ScaleAdvisor } from "../scaling/ScaleAdvisor.js";
+import { AlertSink } from "./AlertSink.js";
+import { RegistryMode, ServiceMode, ServiceType, } from "./config-enums.js";
+import { DirectMessageBus } from "./DirectMessageBus.js";
+import { IPC_PROTOCOL_VERSION, isExpectedIpcError } from "./ipc-errors.js";
+import { ThreadAllocator } from "./ThreadAllocator.js";
+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;
+/**
+ * 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 {
+    config;
+    services;
+    groups;
+    channels;
+    options;
+    allocator;
+    messageBus;
+    registry;
+    scaleAdvisor;
+    alertSink;
+    plugins;
+    _pluginEnv;
+    _failedPlugins;
+    workerMap;
+    groupWorkers;
+    allocation;
+    _metricsServer;
+    _shuttingDown;
+    _restartHistory;
+    _scalingDown;
+    _pendingRestarts;
+    _killTimers;
+    _restartWarningTimes;
+    _endpointTempFile;
+    _sitesTempFile;
+    _metricsRequestSeq;
+    _pendingMetricsSnapshots;
+    _groupReadyWorkers;
+    _groupReadyLogged;
+    _nextWorkerIndex;
+    _heartbeatInterval;
+    _lastHeartbeat;
+    _workersReady;
+    _workerRestartCount;
+    _workerErrorGuards;
+    _cachedEndpointJson;
+    _pidFilePath;
+    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 ?? 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,
+        });
+        // Alert sink — delivers critical event alerts via webhook or custom sink
+        const alertsConfig = config.alerts;
+        this.alertSink = new AlertSink(alertsConfig ?? {});
+        // Log scaling recommendations
+        this.scaleAdvisor.on("recommendation", (rec) => {
+            const icon = {
+                scale_up: "\u2191",
+                migrate: "\u2192",
+                split_out: "\u229E",
+                scale_down: "\u2193",
+            };
+            console.log(`\n  ${icon[rec.action] ?? "\u2022"} SCALE: ${rec.service} \u2014 ${rec.action}`);
+            console.log(`    ${rec.reason}`);
+            if (rec.details.command)
+                console.log(`    Run: ${rec.details.command}`);
+        });
+        // Plugins
+        this.plugins = (config.plugins ?? []);
+        this._pluginEnv = {};
+        this._failedPlugins = new Set();
+        this.workerMap = new Map();
+        this.groupWorkers = new Map();
+        this.allocation = new Map();
+        this._metricsServer = null;
+        this._shuttingDown = false;
+        this._restartHistory = new Map();
+        this._scalingDown = new Set();
+        this._pendingRestarts = new Map();
+        this._killTimers = new Map();
+        this._restartWarningTimes = new Map();
+        this._endpointTempFile = null;
+        this._sitesTempFile = null;
+        this._metricsRequestSeq = 0;
+        this._pendingMetricsSnapshots = new Map();
+        this._groupReadyWorkers = new Map();
+        this._groupReadyLogged = new Set();
+        this._nextWorkerIndex = {};
+        this._heartbeatInterval = null;
+        this._lastHeartbeat = new Map();
+        this._workersReady = new Map();
+        this._workerRestartCount = 0;
+        this._workerErrorGuards = new WeakSet();
+        this._cachedEndpointJson = undefined;
+        this._pidFilePath = null;
+    }
+    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);
+        }
+        // M-1 Security: Warn if FORGE_INTERNAL_SECRET is not set in production
+        if (process.env.NODE_ENV === "production" && !process.env.FORGE_INTERNAL_SECRET) {
+            console.error("\u26a0 WARNING: FORGE_INTERNAL_SECRET is not set. Internal endpoints (/__forge/*) will reject requests in production without a valid HMAC signature.");
+        }
+        // Register signal handlers early so signals during startup are caught
+        process.once("SIGTERM", () => this.shutdown());
+        process.once("SIGINT", () => this.shutdown());
+        // SUP-H1: Handle SIGQUIT for graceful shutdown instead of default core dump
+        process.once("SIGQUIT", () => 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
+        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(`  \u26a0  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);
+        });
+        // REG-H3: Start registry BEFORE building endpoint map so multicast discovery
+        // can contribute to the initial snapshot workers receive at fork time.
+        await this.registry.start();
+        this.scaleAdvisor.start();
+        // Register all local services in the registry before building endpoint map
+        for (const [name, svc] of Object.entries(this.services)) {
+            if (svc.type === ServiceType.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,
+                },
+            });
+        }
+        // P21: Pre-serialize endpoint map once for all worker forks
+        // REG-H3: Now built AFTER registry start + local registration so the map includes discovered services
+        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);
+            }
+        }
+        // SUP-H3: Start heartbeat monitor on a safety timer in case some groups never become ready.
+        // This prevents a stuck group from blocking health monitoring for all other groups.
+        const heartbeatSafetyTimer = setTimeout(() => {
+            if (!this._heartbeatInterval && !this._shuttingDown) {
+                console.warn("  ⚠  Starting heartbeat monitor via safety timer (not all groups ready after 60s)");
+                this._startHeartbeatMonitor();
+            }
+        }, 60_000);
+        if (typeof heartbeatSafetyTimer.unref === "function")
+            heartbeatSafetyTimer.unref();
+        await this._startMetricsServer();
+        // REG-H1: Push topology updates to workers when registry discovers new/removed services
+        const pushEndpointUpdate = () => {
+            const endpointMap = this._buildEndpointMap();
+            const json = JSON.stringify(endpointMap);
+            // Skip if nothing changed
+            if (json === this._cachedEndpointJson)
+                return;
+            this._cachedEndpointJson = json;
+            const message = { type: "forge:endpoint-update", endpoints: endpointMap };
+            const clusterWorkers = cluster.workers ?? {};
+            for (const id of Object.keys(clusterWorkers)) {
+                const worker = clusterWorkers[Number(id)];
+                if (worker) {
+                    this._sendWorkerMessage(worker, message, "endpoint update");
+                }
+            }
+        };
+        this.registry.on("discovered", pushEndpointUpdate);
+        this.registry.on("removed", pushEndpointUpdate);
+        this.registry.on("deregistered", pushEndpointUpdate);
+        // REG-H2: Push health status changes to workers so EndpointResolver can filter
+        const pushHealthUpdate = (reg) => {
+            if (!reg.ports?.http)
+                return;
+            const message = {
+                type: "forge:health-update",
+                host: reg.host,
+                port: reg.ports.http,
+                status: reg.health.status,
+            };
+            const clusterWorkers = cluster.workers ?? {};
+            for (const id of Object.keys(clusterWorkers)) {
+                const worker = clusterWorkers[Number(id)];
+                if (worker) {
+                    this._sendWorkerMessage(worker, message, "health update");
+                }
+            }
+        };
+        this.registry.on("unhealthy", pushHealthUpdate);
+        // 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 {
+            /* ignore: PID file write failure is non-fatal */
+        }
+        console.log(`\n  \u26a1 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: ServiceMode.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 === ServiceType.EDGE);
+        // Build comma-separated entry points for all services in the group
+        const entries = group.services.map((s) => `${s.name}=${s.entry}`).join(",");
+        const configuredHost = (() => {
+            if (typeof this.options.host === "string" && this.options.host.trim()) {
+                return this.options.host.trim();
+            }
+            if (typeof this.config.host === "string" && this.config.host.trim()) {
+                return this.config.host.trim();
+            }
+            return null;
+        })();
+        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: ServiceMode.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 configWithSites = this.config;
+                const sites = configWithSites._sites ?? this.config.sites;
+                const json = sites && Object.keys(sites).length > 0 ? JSON.stringify(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 ?? RegistryMode.EMBEDDED,
+            // 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))),
+            FORGE_INGRESS: this.config.ingress ? JSON.stringify(this.config.ingress) : "",
+            FORGE_SERVICE_RPC: JSON.stringify(Object.fromEntries(group.services
+                .filter((s) => s.rpc || s.rpcTargets)
+                .map((s) => [s.name, { rpc: s.rpc, rpcTargets: s.rpcTargets }]))),
+        };
+        if (configuredHost) {
+            env.FORGE_HOST = configuredHost;
+        }
+        if (this.config._isHostMode) {
+            const configAny = this.config;
+            env.FORGE_HOST_META = configAny._hostMetaJSON ?? JSON.stringify(configAny._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}" \u2014 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 (isExpectedIpcError(err))
+                return;
+            if (this._shuttingDown)
+                return;
+            console.error(`  \u26a0  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 (!isExpectedIpcError(err)) {
+                console.error(`  \u26a0  Failed to send ${label}: ${err?.message ?? err}`);
+            }
+            return false;
+        }
+    }
+    _handleWorkerMessage(worker, msg) {
+        if (msg?.type === "forge:group-ready") {
+            // IPC version handshake: fail fast on protocol mismatch
+            const workerVersion = msg.ipcVersion;
+            if (workerVersion !== undefined && workerVersion !== IPC_PROTOCOL_VERSION) {
+                const info = this.workerMap.get(worker.id);
+                const groupName = info?.groupName ?? "unknown";
+                console.error(`  FATAL: Worker ${groupName}[${info?.workerId ?? "?"}] IPC protocol version mismatch: ` +
+                    `worker=${workerVersion}, supervisor=${IPC_PROTOCOL_VERSION}. ` +
+                    `This usually means mismatched ThreadForge versions. ` +
+                    `Restart all processes with the same version.`);
+                try {
+                    worker.process.kill("SIGKILL");
+                }
+                catch {
+                    /* ignore: worker may already be dead */
+                }
+                return;
+            }
+            // 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 === ServiceType.EDGE);
+                const portLabel = edgeService?.port ? ` on port ${edgeService.port}` : "";
+                const svcLabel = group?.services?.map((s) => s.name).join(", ") ?? groupName;
+                console.log(`  \u2713 ${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(`  \u2716  Worker ${groupName}[${workerId}] fatal error: ${msg.error} - ${msg.message}`);
+            if (msg.port) {
+                console.error(`  \u2716  Failed to bind to port ${msg.port}. Check permissions or port availability.`);
+            }
+            return;
+        }
+        // H-5: Track heartbeat responses from workers
+        // Workers respond to forge:health-check with forge:health-response,
+        // so we accept both message types for heartbeat tracking.
+        if (msg?.type === "forge:heartbeat-response" || msg?.type === "forge:health-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 clusterWorkers = cluster.workers ?? {};
+        const activeWorkers = Object.values(clusterWorkers).filter((worker) => worker != null && !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);
+        // SUP-H2: Guard against -1 index — use worker.id as unique key fallback
+        const slotKey = workerSlotIndex !== -1 ? `slot${workerSlotIndex}` : `wid${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,
+            });
+        }
+        // SUP-M1: Invalidate cached endpoint map so restarted workers get fresh topology
+        this._cachedEndpointJson = undefined;
+        if (this._endpointTempFile) {
+            try {
+                fs.unlinkSync(this._endpointTempFile);
+            }
+            catch { /* ignore */ }
+            this._endpointTempFile = null;
+        }
+        // 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}:${slotKey}`;
+            this._restartHistory.delete(cooldownKey);
+            console.log(`  \u2193 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(`  \u2716  Worker ${groupName}[${workerId}] (${services.join("+")}) failed with fatal error \u2014 not restarting`);
+            console.error(`  \u2716  Check worker logs above for details (likely port permission issue)`);
+            // Clean up restart history to prevent future attempts
+            const cooldownKey = `${groupName}:${slotKey}`;
+            this._restartHistory.delete(cooldownKey);
+            this._pendingRestarts.delete(cooldownKey);
+            return;
+        }
+        const reason = signal ? `signal ${signal}` : `code ${code}`;
+        // Alert: worker crash
+        this.alertSink.emit("worker.crash", `Worker ${groupName}[${workerId}] (${services.join("+")}) exited: ${reason}`, "warning", { groupName, workerId, services, reason, code, signal });
+        // 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(`  \u26a0  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}:${slotKey}`;
+        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(`  \u26a0  ${groupName}[${workerId}] exceeded max restarts (${MAX_RESTARTS_PER_WINDOW} in ${RESTART_WINDOW_MS / 60000}min), not restarting`);
+            // Alert: restart limit exhausted — critical because the worker will not be restarted
+            this.alertSink.emit("worker.restart_limit", `Worker ${groupName}[${workerId}] (${services.join("+")}) exceeded max restarts (${MAX_RESTARTS_PER_WINDOW}/${RESTART_WINDOW_MS / 60000}min) — not restarting`, "critical", { groupName, workerId, services, restartCount: history.count, windowMs: RESTART_WINDOW_MS });
+            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(`  \u21bb  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(`  \u21bb  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(`  \u21bb  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 !== ServiceType.EDGE)
+                continue;
+            if (!Number.isInteger(svc.port) || !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(`  \u2191 Scaling ${groupName} ${currentCount} \u2192 ${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(`  \u2193 Scaling ${groupName} ${currentCount} \u2192 ${newCount} (-${toRemove})`);
+            for (let i = 0; i < toRemove; i++) {
+                const wid = currentIds[currentIds.length - 1 - i];
+                this._scalingDown.add(wid);
+                const clusterWorkers = cluster.workers ?? {};
+                const worker = clusterWorkers[wid];
+                if (worker) {
+                    // SUP-H5: Use worker.disconnect() for proper IPC channel teardown
+                    // instead of direct SIGTERM which bypasses cluster lifecycle
+                    try {
+                        worker.disconnect();
+                    }
+                    catch {
+                        /* ignore: worker may already be disconnected */
+                    }
+                    // RT-H3: Force SIGKILL after 10s if worker hasn't exited
+                    const killTimer = setTimeout(() => {
+                        this._killTimers.delete(wid);
+                        try {
+                            if (!worker.isDead()) {
+                                console.error(`  \u26a0  Worker ${wid} did not exit after SIGTERM, sending SIGKILL`);
+                                worker.process.kill("SIGKILL");
+                            }
+                        }
+                        catch {
+                            /* ignore: worker may have already exited between isDead() check and kill */
+                        }
+                    }, 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(`  \u2716  Worker ${info.groupName}[${info.workerId}] unresponsive for ${Math.round(elapsed / 1000)}s \u2014 sending SIGKILL`);
+                    // Alert: heartbeat timeout — critical because the worker is being force-killed
+                    this.alertSink.emit("worker.heartbeat_timeout", `Worker ${info.groupName}[${info.workerId}] (${info.services.join("+")}) unresponsive for ${Math.round(elapsed / 1000)}s — sending SIGKILL`, "critical", { groupName: info.groupName, workerId: info.workerId, services: info.services, elapsedMs: elapsed });
+                    try {
+                        const clusterWorkers = cluster.workers ?? {};
+                        const w = clusterWorkers[wid];
+                        if (w && !w.isDead()) {
+                            w.process.kill("SIGKILL");
+                        }
+                    }
+                    catch {
+                        /* ignore: worker may have already exited between isDead() check and kill */
+                    }
+                }
+                else if (elapsed > 60_000) {
+                    // 60s without response — log a warning
+                    console.warn(`  \u26a0  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(`  \u26a0  Shutdown deadline exceeded during: ${label} \u2014 skipping`);
+                return Promise.resolve();
+            }
+            return Promise.race([
+                promise,
+                new Promise((resolve) => {
+                    const t = setTimeout(() => {
+                        console.warn(`  \u26a0  Shutdown phase "${label}" exceeded deadline \u2014 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.
+        //
+        // H5: Intentionally NO SIGTERM here. Graceful shutdown uses only IPC
+        // (forge:shutdown) + worker.disconnect(). SIGTERM would race with the IPC
+        // handler — the worker might receive SIGTERM before it finishes draining
+        // HTTP connections triggered by the forge:shutdown message. SIGTERM is
+        // reserved for scale-down operations where immediate process termination
+        // is acceptable. SIGKILL is used only as a last resort in Step 5 if
+        // workers refuse to exit after disconnect.
+        const clusterWorkers = cluster.workers ?? {};
+        for (const id of Object.keys(clusterWorkers)) {
+            const worker = clusterWorkers[Number(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 cw = cluster.workers ?? {};
+                const alive = Object.keys(cw).filter((id) => {
+                    const w = cw[Number(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)
+        // SUP-M2: Listen for exits to remove PIDs, preventing SIGKILL of recycled PIDs
+        const workerPids = new Set();
+        const cw2 = cluster.workers ?? {};
+        for (const id of Object.keys(cw2)) {
+            const w = cw2[Number(id)];
+            if (w?.process?.pid) {
+                const pid = w.process.pid;
+                workerPids.add(pid);
+                w.once("exit", () => { workerPids.delete(pid); });
+            }
+        }
+        // Step 3: Disconnect remaining workers
+        const cw3 = cluster.workers ?? {};
+        for (const id of Object.keys(cw3)) {
+            const worker = cw3[Number(id)];
+            if (worker && !worker.isDead()) {
+                try {
+                    worker.disconnect();
+                }
+                catch {
+                    /* ignore: cleanup — worker may already be dead or disconnected */
+                }
+            }
+        }
+        // Step 4: Wait for disconnect to complete
+        await withDeadline(new Promise((resolve) => {
+            const check = setInterval(() => {
+                const cw4 = cluster.workers ?? {};
+                const alive = Object.keys(cw4).filter((id) => {
+                    const w = cw4[Number(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
+        const cw5 = cluster.workers ?? {};
+        for (const id of Object.keys(cw5)) {
+            const worker = cw5[Number(id)];
+            if (worker && !worker.isDead()) {
+                console.error(`  \u26a0  Forcefully killing worker ${id}...`);
+                worker.process.kill("SIGKILL");
+            }
+        }
+        // SUP-M2: Kill workers that disconnected from cluster but may still be alive.
+        // PIDs are removed from workerPids via exit listeners, so recycled PIDs are safe.
+        for (const pid of workerPids) {
+            try {
+                process.kill(pid, 0);
+                process.kill(pid, "SIGKILL");
+            }
+            catch {
+                /* ignore: cleanup — process already exited */
+            }
+        }
+        // C3: Clean up temp endpoint file if created
+        if (this._endpointTempFile) {
+            try {
+                fs.unlinkSync(this._endpointTempFile);
+            }
+            catch {
+                /* ignore: cleanup — temp file may already be removed */
+            }
+            this._endpointTempFile = null;
+        }
+        if (this._sitesTempFile) {
+            try {
+                fs.unlinkSync(this._sitesTempFile);
+            }
+            catch {
+                /* ignore: cleanup — temp file may already be removed */
+            }
+            this._sitesTempFile = null;
+        }
+        // H4: Clean up PID file
+        if (this._pidFilePath) {
+            try {
+                fs.unlinkSync(this._pidFilePath);
+            }
+            catch {
+                /* ignore: cleanup — PID file may already be removed */
+            }
+            this._pidFilePath = null;
+        }
+        console.log("  All workers stopped. Goodbye.\n");
+        this.messageBus.cleanup();
+        this.scaleAdvisor.stop();
+        // Flush pending alerts before stopping
+        await this.alertSink.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(`  \u26a0  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(`  \ud83d\udcca 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(`  \u26a0  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(`  \u26a0  Metrics server binding to ${bindAddr} without FORGE_METRICS_TOKEN \u2014 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(`  \ud83d\udcca Metrics: http://${bindAddr}:${port}/status (Prometheus: /metrics)`);
+                resolve();
+            });
+        });
+    }
+    _status() {
+        const groups = [];
+        const liveWorkersByService = {};
+        for (const [groupName, workerIds] of this.groupWorkers) {
+            const group = this.groups[groupName];
+            const clusterWorkers = cluster.workers ?? {};
+            const pids = workerIds
+                .map((wid) => clusterWorkers[wid]?.process?.pid)
+                .filter((pid) => pid != null);
+            const liveWorkers = workerIds.length;
+            for (const svc of group.services) {
+                liveWorkersByService[svc.name] = liveWorkers;
+            }
+            groups.push({
+                group: groupName,
+                services: group.services.map((s) => ({
+                    name: s.name,
+                    type: s.type,
+                    port: s.port,
+                })),
+                workers: liveWorkers,
+                pids,
+            });
+        }
+        const topology = this.registry.topology();
+        for (const [serviceName, liveWorkers] of Object.entries(liveWorkersByService)) {
+            const existing = Array.isArray(topology[serviceName]) ? topology[serviceName] : [];
+            let hasLocalEntry = false;
+            const updated = existing.map((entry) => {
+                const isLocalEntry = entry?.nodeId === this.registry.nodeId || entry?.transport === "local" || entry?.transport === "colocated";
+                if (!isLocalEntry)
+                    return entry;
+                hasLocalEntry = true;
+                return {
+                    ...entry,
+                    workers: liveWorkers,
+                    status: liveWorkers > 0 ? (entry.status ?? "healthy") : "unhealthy",
+                };
+            });
+            if (!hasLocalEntry) {
+                updated.unshift({
+                    nodeId: this.registry.nodeId,
+                    host: this.registry.host,
+                    transport: "local",
+                    status: liveWorkers > 0 ? "healthy" : "unhealthy",
+                    cpu: 0,
+                    workers: liveWorkers,
+                });
+            }
+            topology[serviceName] = updated;
+        }
+        const clusterWorkers = cluster.workers ?? {};
+        const status = {
+            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(clusterWorkers).length,
+            totalServices: Object.keys(this.services).length,
+            remoteServices: Object.values(this.services).filter((s) => s.type === ServiceType.REMOTE).length,
+            portsUsed: Object.values(this.services)
+                .filter((s) => s.port)
+                .map((s) => s.port),
+            messageBus: this.messageBus.stats(),
+            topology,
+            scalingRecommendations: this.scaleAdvisor.recommendations,
+        };
+        const configAny = this.config;
+        if (configAny?._hostMeta && typeof configAny._hostMeta === "object") {
+            const projects = {};
+            for (const [projectId, meta] of Object.entries(configAny._hostMeta)) {
+                const projectGroups = groups.filter((pg) => pg.services.some((svc) => Array.isArray(meta.services) && meta.services.includes(svc.name)));
+                projects[projectId] = {
+                    domain: meta.domain ?? null,
+                    services: Array.isArray(meta.services) ? meta.services.length : 0,
+                    workers: projectGroups.reduce((sum, pg) => sum + pg.workers, 0),
+                    schema: meta.schema ?? null,
+                    keyPrefix: meta.keyPrefix ?? null,
+                };
+            }
+            status.hostMode = true;
+            status.domain = configAny._hostDomain ?? null;
+            status.projects = projects;
+        }
+        if (configAny?._isPlatformMode) {
+            status.platformMode = true;
+        }
+        return status;
+    }
+    /**
+     * 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 === ServiceType.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 === ServiceType.INTERNAL || svc.type === ServiceType.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 messageBusAny = this.messageBus;
+                const socketPath = messageBusAny.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(`  \u26a0  Failed to parse address "${address}" for service "${serviceName ?? "unknown"}": ${err.message}`);
+        }
+        console.warn(`  \u26a0  Invalid address "${address}" for service "${serviceName ?? "unknown"}" \u2014 skipping`);
+        return null;
+    }
+    _printAllocation() {
+        console.log("");
+        console.log("  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
+        console.log("  \u2502 Process Group    \u2502 Services                  \u2502 Workers \u2502 Port   \u2502");
+        console.log("  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+        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 === ServiceType.EDGE ? "\u26a1" : s.type === ServiceType.BACKGROUND ? "\u23f0" : "\u25cb";
+                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) : "  \u2014   ";
+            console.log(`  \u2502 ${name} \u2502 ${svcs} \u2502 ${threads} \u2502 ${port} \u2502`);
+        }
+        console.log("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518");
+        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} \u2194 ${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 {
+            /* ignore: fallback to default version if package.json is unreadable */
+        }
+        return `
+  \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+  \u2551     \u26a1 ThreadForge v${version.padEnd(12)}\u2551
+  \u2551   Multi-threaded Service Runtime  \u2551
+  \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255d`;
+    }
+}
+//# sourceMappingURL=Supervisor.js.map